doc/html/AdminReference/auarf098.htm

   1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 4//EN">
   2 <HTML><HEAD>
   3 <TITLE>Administration Reference</TITLE>
   4 <!-- Begin Header Records  ========================================== -->
   5 <!-- /tmp/idwt3672/auarf000.scr converted by idb2h R4.2 (359) ID      -->
   6 <!-- Workbench Version (AIX) on 3 Oct 2000 at 16:18:30                -->
   7 <META HTTP-EQUIV="updated" CONTENT="Tue, 03 Oct 2000 16:18:29">
   8 <META HTTP-EQUIV="review" CONTENT="Wed, 03 Oct 2001 16:18:29">
   9 <META HTTP-EQUIV="expires" CONTENT="Thu, 03 Oct 2002 16:18:29">
  10 </HEAD><BODY>
  11 <!-- (C) IBM Corporation 2000. All Rights Reserved    -->
  12 <BODY bgcolor="ffffff">
  13 <!-- End Header Records  ============================================ -->
  14 <A NAME="Top_Of_Page"></A>
  15 <H1>Administration Reference</H1>
  16 <HR><P ALIGN="center"> <A HREF="../index.htm"><IMG SRC="../books.gif" BORDER="0" ALT="[Return to Library]"></A> <A HREF="auarf002.htm#ToC"><IMG SRC="../toc.gif" BORDER="0" ALT="[Contents]"></A> <A HREF="auarf097.htm"><IMG SRC="../prev.gif" BORDER="0" ALT="[Previous Topic]"></A> <A HREF="#Bot_Of_Page"><IMG SRC="../bot.gif" BORDER="0" ALT="[Bottom of Topic]"></A> <A HREF="auarf099.htm"><IMG SRC="../next.gif" BORDER="0" ALT="[Next Topic]"></A> <A HREF="auarf284.htm#HDRINDEX"><IMG SRC="../index.gif" BORDER="0" ALT="[Index]"></A> <P>
  17 <P>
  18 <H2><A NAME="HDRBOS_CREATE" HREF="auarf002.htm#ToC_112">bos create</A></H2>
  19 <A NAME="IDX4477"></A>
  20 <A NAME="IDX4478"></A>
  21 <A NAME="IDX4479"></A>
  22 <A NAME="IDX4480"></A>
  23 <A NAME="IDX4481"></A>
  24 <A NAME="IDX4482"></A>
  25 <A NAME="IDX4483"></A>
  26 <A NAME="IDX4484"></A>
  27 <A NAME="IDX4485"></A>
  28 <A NAME="IDX4486"></A>
  29 <P><STRONG>Purpose</STRONG>
  30 <P>Defines a new process in the <B>/usr/afs/local/BosConfig</B> file and
  31 starts it running
  32 <P><STRONG>Synopsis</STRONG>
  33 <PRE><B>bos create -server</B> &lt;<VAR>machine&nbsp;name</VAR>>  <B>-instance</B> &lt;<VAR>server process name</VAR>>
  34            <B>-type</B> &lt;<VAR>server type</VAR>>  <B>-cmd</B> &lt;<VAR>command lines</VAR>><SUP>+</SUP>
  35            [<B>-notifier</B> &lt;<VAR>Notifier program</VAR>>]  [<B>-cell</B> &lt;<VAR>cell&nbsp;name</VAR>>]
  36            [<B>-noauth</B>]  [<B>-localauth</B>]  [<B>-help</B>]
  37
  38 <B>bos c -s</B> &lt;<VAR>machine&nbsp;name</VAR>>  <B>-i</B> &lt;<VAR>server process name</VAR>>  <B>-t</B> &lt;<VAR>server type</VAR>>
  39       <B>-cm</B> &lt;<VAR>command lines</VAR>><SUP>+</SUP>  [<B>-not</B> &lt;<VAR>Notifier program</VAR>>]  [<B>-ce</B> &lt;<VAR>cell&nbsp;name</VAR>>]
  40       [<B>-noa</B>]  [<B>-l</B>]  [<B>-h</B>]
  41 </PRE>
  42 <P><STRONG>Description</STRONG>
  43 <P>The <B>bos create</B> command creates a server process entry in the
  44 <B>/usr/afs/local/BosConfig</B> file on the server machine named by the
  45 <B>-server</B> argument, sets the process's status to <B>Run</B>
  46 in the <B>BosConfig</B> file and in memory, and starts the process.
  47 <P>A server process's entry in the <B>BosConfig</B> file defines its
  48 name, its type, the command that initializes it, and optionally, the name of a
  49 notifier program that runs when the process terminates.
  50 <P><STRONG>Options</STRONG>
  51 <DL>
  52 <P><DT><B><B>-server</B>
  53 </B><DD>Indicates the server machine on which to define and start the new
  54 process. Identify the machine by IP address or its host name (either
  55 fully-qualified or abbreviated unambiguously). For details, see the
  56 introductory reference page for the <B>bos</B> command suite.
  57 <P><DT><B><B>-instance</B>
  58 </B><DD>Names the process to define and start. Any name is acceptable, but
  59 for the sake of simplicity it is best to use the last element of the
  60 process's binary file pathname, and to use the same name on every server
  61 machine. The conventional names, as used in all AFS documentation,
  62 are:
  63 <DL>
  64 <P><DT><B><B>buserver</B>
  65 </B><DD>The Backup Server process
  66 <A NAME="IDX4487"></A>
  67 <A NAME="IDX4488"></A>
  68 <P><DT><B><B>fs</B>
  69 </B><DD>The process that combines the File Server, Volume Server, and Salvager
  70 processes (<B>fileserver</B>, <B>volserver</B>, and
  71 <B>salvager</B>)
  72 <A NAME="IDX4489"></A>
  73 <A NAME="IDX4490"></A>
  74 <P><DT><B><B>kaserver</B>
  75 </B><DD>The Authentication Server process
  76 <A NAME="IDX4491"></A>
  77 <A NAME="IDX4492"></A>
  78 <P><DT><B><B>ptserver</B>
  79 </B><DD>The Protection Server process
  80 <A NAME="IDX4493"></A>
  81 <A NAME="IDX4494"></A>
  82 <P><DT><B><B>runntp</B>
  83 </B><DD>The controller process for the Network Time Protocol Daemon
  84 <A NAME="IDX4495"></A>
  85 <A NAME="IDX4496"></A>
  86 <P><DT><B><B>upclientbin</B>
  87 </B><DD>The client portion of the Update Server process that retrieves binary
  88 files from the <B>/usr/afs/bin</B> directory of the binary distribution
  89 machine for this machine's CPU/operating system type. (The name of
  90 the binary is <B>upclient</B>, but the <B>bin</B> suffix distinguishes
  91 this process from <B>upclientetc</B>.)
  92 <A NAME="IDX4497"></A>
  93 <A NAME="IDX4498"></A>
  94 <P><DT><B><B>upclientetc</B>
  95 </B><DD>The client portion of the Update Server process that retrieves
  96 configuration files from the <B>/usr/afs/etc</B> directory of the system
  97 control machine. Do not run this process in cells that use the
  98 international edition of AFS. (The name of the binary is
  99 <B>upclient</B>, but the <B>etc</B> suffix distinguishes this process
 100 from <B>upclientbin</B>.)
 101 <P><DT><B><B>upserver</B>
 102 </B><DD>The server portion of the Update Server process
 103 <A NAME="IDX4499"></A>
 104 <A NAME="IDX4500"></A>
 105 <P><DT><B><B>vlserver</B>
 106 </B><DD>The Volume Location (VL) Server process
 107 <A NAME="IDX4501"></A>
 108 <A NAME="IDX4502"></A>
 109 </DL>
 110 <P><DT><B><B>-type</B>
 111 </B><DD>Specifies the process's type. The acceptable values are:
 112 <P>
 113 <DL>
 114 <P><DT><B><B>cron</B>
 115 </B><DD>Use this value for cron-type processes that the BOS Server starts only at
 116 a defined daily or weekly time, rather than whenever it detects that the
 117 process has terminated. AFS does not define any such processes by
 118 default, but makes this value available for administrator use. Define
 119 the time for command execution as part of the <B>-cmd</B> argument to the
 120 <B>bos create</B> command.
 121 <P><DT><B><B>fs</B>
 122 </B><DD>Use this value only for the <B>fs</B> process, which combines the File
 123 Server, Volume Server and Salvager processes. If one of the component
 124 processes terminates, the BOS Server shuts down and restarts the processes in
 125 the appropriate order.
 126 <P><DT><B><B>simple</B>
 127 </B><DD>Use this value for all processes listed as acceptable values to the
 128 <B>-instance</B> argument, except for the <B>fs</B> process.
 129 There are no interdependencies between simple processes, so the BOS Server can
 130 stop and start them independently as necessary.
 131 </DL>
 132 <P><DT><B><B>-cmd</B>
 133 </B><DD>Specifies each command the BOS Server runs to start the process.
 134 Specify no more than six commands (which can include the command's
 135 options, in which case the entire string is surrounded by double quotes);
 136 any additional commands are ignored.
 137 <P>For a simple process, provide the complete pathname of the process's
 138 binary file on the local disk (for example, <B>/usr/afs/bin/ptserver</B>
 139 for the Protection Server). If including any of the initialization
 140 command's options, surround the entire command in double quotes (<B>"
 141 "</B>). The <B>upclient</B> process has a required argument, and
 142 the commands for all other processes take optional arguments.
 143 <A NAME="IDX4503"></A>
 144 <P>For the <B>fs</B> process, provide the complete pathname of the local
 145 disk binary file for each of the component processes:
 146 <B>fileserver</B>, <B>volserver</B>, and <B>salvager</B>, in that
 147 order. The standard binary directory is <B>/usr/afs/bin</B>.
 148 If including any of an initialization command's options, surround the
 149 entire command in double quotes (<B>" "</B>).
 150 <A NAME="IDX4504"></A>
 151 <P>For a <B>cron</B> process, provide two parameters:
 152 <A NAME="IDX4505"></A>
 153 <UL>
 154 <P><LI>The complete local disk pathname of either an executable file or a command
 155 from one of the AFS suites (complete with all of the necessary
 156 arguments). Surround this parameter with double quotes (<B>" "</B>)
 157 if it contains spaces.
 158 <P><LI>A specification of when the BOS Server executes the file or command
 159 indicated by the first parameter. There are three acceptable
 160 values:
 161 <UL>
 162 <P><LI>The string <B>now</B>, which directs the BOS Server to execute the
 163 file or command immediately and only once. It is usually simpler to
 164 issue the command directly or issue the <B>bos exec</B> command.
 165 <P><LI>A time of day. The BOS Server executes the file or command daily at
 166 the indicated time. Separate the hours and minutes with a colon
 167 (<I>hh</I>:<I>MM</I>), and use either 24-hour format, or a value
 168 in the range from <B>1:00</B> through <B>12:59</B> with
 169 the addition of <B>am</B> or <B>pm</B>. For example, both
 170 <B>14:30</B> and <B>"2:30 pm"</B> indicate 2:30 in
 171 the afternoon. Surround this parameter with double quotes (<B>"
 172 "</B>) if it contains a space.
 173 <P><LI>A day of the week and time of day, separated by a space and surrounded
 174 with double quotes (<B>" "</B>). The BOS Server executes the file
 175 or command weekly at the indicated day and time. For the day, provide
 176 either the whole name or the first three letters, all in lowercase letters
 177 (<B>sunday</B> or <B>sun</B>, <B>thursday</B> or <B>thu</B>,
 178 and so on). For the time, use the same format as when specifying the
 179 time alone.
 180 </UL>
 181 </UL>
 182 <P><DT><B><B>-notifier</B>
 183 </B><DD>Specifies the complete pathname on the local disk of a program that the
 184 BOS Server invokes when the process terminates. The AFS distribution
 185 does not include any notifier programs, but this argument is available for
 186 administrator use. See the <B>Related Information</B>
 187 section.
 188 <P><DT><B><B>-cell</B>
 189 </B><DD>Names the cell in which to run the command. Do not combine this
 190 argument with the <B>-localauth</B> flag. For more details, see the
 191 introductory <B>bos</B> reference page.
 192 <P><DT><B><B>-noauth</B>
 193 </B><DD>Assigns the unprivileged identity <B>anonymous</B> to the
 194 issuer. Do not combine this flag with the <B>-localauth</B>
 195 flag. For more details, see the introductory <B>bos</B> reference
 196 page.
 197 <P><DT><B><B>-localauth</B>
 198 </B><DD>Constructs a server ticket using a key from the local
 199 <B>/usr/afs/etc/KeyFile</B> file. The <B>bos</B> command
 200 interpreter presents the ticket to the BOS Server during mutual
 201 authentication. Do not combine this flag with the <B>-cell</B> or
 202 <B>-noauth</B> options. For more details, see the introductory
 203 <B>bos</B> reference page.
 204 <P><DT><B>-help
 205 </B><DD>Prints the online help for this command. All other valid options
 206 are ignored.
 207 </DL>
 208 <P><STRONG>Examples</STRONG>
 209 <P>The following command defines and starts the simple process
 210 <B>kaserver</B> on the machine <B>fs3.abc.com</B>:
 211 <PRE>   % <B>bos create -server fs3.abc.com -instance kaserver -type simple</B>  \
 212                 <B>-cmd /usr/afs/bin/kaserver</B>
 213
 214 </PRE>
 215 <P>The following command defines and starts the simple process
 216 <B>upclientbin</B> on the machine
 217 <B>fs4.abc.com</B>. It references
 218 <B>fs1.abc.com</B> as the source for updates to binary
 219 files, checking for changes to the <B>/usr/afs/bin</B> directory every 120
 220 seconds.
 221 <PRE>   % <B>bos create -server fs4.abc.com -instance upclientbin -type simple</B>  \
 222                 <B>-cmd "/usr/afs/bin/upclient fs1.abc.com -clear -t 120</B>  \
 223                 <B>/usr/afs/bin"</B>
 224
 225 </PRE>
 226 <P>The following command creates the fs process <B>fs</B> on the machine
 227 <B>fs4.abc.com</B>. Type the command on a single
 228 line.
 229 <PRE>   % <B>bos create -server fs4.abc.com -instance fs -type fs</B>  \
 230                 <B>-cmd /usr/afs/bin/fileserver /usr/afs/bin/volserver</B>  \
 231                 <B>/usr/afs/bin/salvager</B>
 232
 233 </PRE>
 234 <P>The following command creates a <B>cron</B> process called
 235 <B>userbackup</B> on the machine <B>fs5.abc.com</B>, so
 236 that the BOS Server issues the indicated <B>vos backupsys</B> command each
 237 day at 3:00 a.m. (the command creates a backup version of
 238 every volume in the file system whose name begins with
 239 <B>user</B>). Note that the issuer provides the complete pathname
 240 to the <B>vos</B> command, includes the <B>-localauth</B> flag on it,
 241 and types the entire <B>bos create</B> command on one line.
 242 <PRE>   % <B>bos create -server fs5.abc.com -instance userbackup -type cron</B>  \
 243                 <B>-cmd "/usr/afs/bin/vos backupsys -prefix user -localauth" 03:00</B>
 244
 245 </PRE>
 246 <P><STRONG>Privilege Required</STRONG>
 247 <P>The issuer must be listed in the <B>/usr/afs/etc/UserList</B> file on
 248 the machine named by the <B>-server</B> argument, or must be logged onto a
 249 server machine as the local superuser <B>root</B> if the
 250 <B>-localauth</B> flag is included.
 251 <P><STRONG>Related Information</STRONG>
 252 <P>If the <B>-notifier</B> argument is included when this command is used
 253 to define and start a process, the BOS Server invokes the indicated
 254 <I>notifier program</I> when the process exits. The intended use of
 255 a notifier program is to inform administrators when a process exits
 256 unexpectedly, but it can be used to perform any appropriate actions.
 257 The following paragraphs describe the <B>bnode</B> and
 258 <B>bnode_proc</B> structures in which the BOS Server records information
 259 about the exiting process. The list of AFS commands related to this one
 260 follows.
 261 <P>The BOS Server constructs and sends on the standard output stream one
 262 <B>bnode</B> and one <B>bnode_proc</B> structure for each exiting
 263 process associated with the notifier program. It brackets each
 264 structure with appropriate <TT>BEGIN</TT> and <TT>END</TT> statements
 265 (<TT>BEGIN bnode</TT> and <TT>END bnode</TT>, <TT>BEGIN bnode_proc</TT>
 266 and <TT>END bnode_proc</TT>), which immediately follow the preceding newline
 267 character with no intervening spaces or other characters. If the
 268 notifier program does not need information from a structure, it can scan ahead
 269 in the input stream for the <TT>END</TT> statement.
 270 <P>In general, each field in a structure is a string of ASCII text terminated
 271 by the newline character. The format of the information within a
 272 structure possibly varies slightly depending on the type of process associated
 273 with the notifier program.
 274 <P>The C code for the <B>bnode</B> and <B>bnode_proc</B> structures
 275 follows. Note that the structures sent by the BOS Server do not
 276 necessarily include all of the fields described here, because some are used
 277 only for internal record keeping. The notifier process must robustly
 278 handle the absence of expected fields, as well as the presence of unexpected
 279 fields, on the standard input stream.
 280 <P>For proper performance, the notifier program must continue processing the
 281 input stream until it detects the end-of-file (EOF). The BOS Server
 282 closes the standard input file descriptor to the notifier process when it has
 283 completed delivery of the data, and it is the responsibility of the notifier
 284 process to terminate properly.
 285 <P><B>struct bnode contents</B>
 286 <PRE>   struct bnode {
 287       struct bnode *next;      /* next pointer in top-level's list */
 288       char *name;              /* instance name */
 289       long nextTimeout;        /* next time this guy should be awakened */
 290       long period;             /* period between calls */
 291       long rsTime;             /* time we started counting restarts */
 292       long rsCount;            /* count of restarts since rsTime */
 293       struct bnode_type *type; /* type object */
 294       struct bnode_ops *ops;   /* functions implementing bnode class */
 295       long procStartTime;      /* last time a process was started */
 296       long procStarts;         /* number of process starts */
 297       long lastAnyExit;        /* last time a process exited for any reason */
 298       long lastErrorExit;      /* last time a process exited unexpectedly */
 299       long errorCode;          /* last exit return code */
 300       long errorSignal;        /* last proc terminating signal */
 301       char *lastErrorName;     /* name of proc that failed last */
 302       short refCount;          /* reference count */
 303       short flags;             /* random flags */
 304       char goal;               /* 1=running or 0=not running */
 305       char fileGoal;           /* same, but to be stored in file */
 306 };
 307
 308 </PRE>
 309 <P><B>format of struct bnode explosion</B>
 310 <PRE>   printf("name: %s\n",tp->name);
 311    printf("rsTime: %ld\n", tp->rsTime);
 312    printf("rsCount: %ld\n", tp->rsCount);
 313    printf("procStartTime: %ld\n", tp->procStartTime);
 314    printf("procStarts: %ld\n", tp->procStarts);
 315    printf("lastAnyExit: %ld\n", tp->lastAnyExit);
 316    printf("lastErrorExit: %ld\n", tp->lastErrorExit);
 317    printf("errorCode: %ld\n", tp->errorCode);
 318    printf("errorSignal: %ld\n", tp->errorSignal);
 319    printf("lastErrorName: %s\n", tp->lastErrorName);
 320    printf("goal: %d\n", tp->goal);
 321
 322 </PRE>
 323 <P><B>struct bnode_proc contents</B>
 324 <PRE>   struct bnode_proc {
 325       struct bnode_proc *next; /* next guy in top-level's list */
 326       struct bnode *bnode;     /* bnode creating this process */
 327       char *comLine;           /* command line used to start this process */
 328       char *coreName;          /* optional core file component name */
 329       long pid;                /* pid if created */
 330       long lastExit;           /* last termination code */
 331       long lastSignal;         /* last signal that killed this guy */
 332       long flags;              /* flags giving process state */
 333 };
 334
 335 </PRE>
 336 <P><B>format of struct bnode_proc explosion</B>
 337 <PRE>   printf("comLine: %s\n", tp->comLine);
 338    printf("coreName: %s\n", tp->coreName);
 339    printf("pid: %ld\n", tp->pid);
 340    printf("lastExit: %ld\n", tp->lastExit);
 341    printf("lastSignal: %ld\n", tp->lastSignal);
 342
 343 </PRE>
 344 <P><A HREF="auarf016.htm#HDRBOSCONFIG">BosConfig</A>
 345 <P><A HREF="auarf023.htm#HDRKEYFILE">KeyFile</A>
 346 <P><A HREF="auarf035.htm#HDRUSERLIST">UserList</A>
 347 <P><A HREF="auarf093.htm#HDRBOS_INTRO">bos</A>
 348 <P><A HREF="auarf125.htm#HDRBUSERVER">buserver</A>
 349 <P><A HREF="auarf129.htm#HDRFILESERVER">fileserver</A>
 350 <P><A HREF="auarf198.htm#HDRKASERVER">kaserver</A>
 351 <P><A HREF="auarf227.htm#HDRPTSERVER">ptserver</A>
 352 <P><A HREF="auarf230.htm#HDRRUNNTP">runntp</A>
 353 <P><A HREF="auarf232.htm#HDRSALVAGER">salvager</A>
 354 <P><A HREF="auarf240.htm#HDRUPCLIENT">upclient</A>
 355 <P><A HREF="auarf241.htm#HDRUPSERVER">upserver</A>
 356 <P><A HREF="auarf249.htm#HDRVLSERVER">vlserver</A>
 357 <P><A HREF="auarf251.htm#HDRVOLSERVER">volserver</A>
 358 <P><A HREF="auarf256.htm#HDRVOS_BACKUPSYS">vos backupsys</A>
 359 <P>
 360 <HR><P ALIGN="center"> <A HREF="../index.htm"><IMG SRC="../books.gif" BORDER="0" ALT="[Return to Library]"></A> <A HREF="auarf002.htm#ToC"><IMG SRC="../toc.gif" BORDER="0" ALT="[Contents]"></A> <A HREF="auarf097.htm"><IMG SRC="../prev.gif" BORDER="0" ALT="[Previous Topic]"></A> <A HREF="#Top_Of_Page"><IMG SRC="../top.gif" BORDER="0" ALT="[Top of Topic]"></A> <A HREF="auarf099.htm"><IMG SRC="../next.gif" BORDER="0" ALT="[Next Topic]"></A> <A HREF="auarf284.htm#HDRINDEX"><IMG SRC="../index.gif" BORDER="0" ALT="[Index]"></A> <P>
 361 <!-- Begin Footer Records  ========================================== -->
 362 <P><HR><B>
 363 <br>&#169; <A HREF="http://www.ibm.com/">IBM Corporation 2000.</A>  All Rights Reserved
 364 </B>
 365 <!-- End Footer Records  ============================================ -->
 366 <A NAME="Bot_Of_Page"></A>
 367 </BODY></HTML>