3 bos create - Defines a new process in the /usr/afs/local/BosConfig file and
8 B<bos create -server> <I<machine name>> -instance <I<server process name>>
9 B<-type> <I<server type>> B<-cmd> <I<command lines>>+
10 [B<-notifier> <I<Notifier program>>] [-cell <I<cell name>>]
11 [B<-noauth>] [B<-localauth>] [-help]
13 B<bos c -s> <I<machine name>> B<-i> <I<server process name>> -t <I<server type>>
14 B<-cm> <I<command lines>>+ [B<-not> <I<Notifier program>>] [B<-ce> <I<cell name>>]
15 [B<-noa>] [B<-l>] [-h]
19 The bos create command creates a server process entry in the
20 B</usr/afs/local/BosConfig> file on the server machine named by the
21 B<-server> argument, sets the process's status to B<Run>
22 in the B<BosConfig> file and in memory, and starts the process.
24 A server process's entry in the BosConfig file defines its
25 name, its type, the command that initializes it, and optionally, the name of a
26 notifier program that runs when the process terminates.
35 Indicates the server machine on which to define and start the new
36 process. Identify the machine by IP address or its host name (either
37 fully-qualified or abbreviated unambiguously). For details, see the
38 introductory reference page for the B<bos> command suite.
43 Names the process to define and start. Any name is acceptable, but
44 for the sake of simplicity it is best to use the last element of the
45 process's binary file pathname, and to use the same name on every server
46 machine. The conventional names, as used in all AFS documentation,
54 The Backup Server process
61 The process that combines the File Server, Volume Server, and Salvager
62 processes (B<fileserver>, B<volserver>, and
70 The Authentication Server process
77 The Protection Server process
84 The controller process for the Network Time Protocol Daemon
91 The client portion of the Update Server process that retrieves binary
92 files from the B</usr/afs/bin> directory of the binary distribution
93 machine for this machine's CPU/operating system type. (The name of
94 the binary is B<upclient>, but the B<bin> suffix distinguishes
95 this process from B<upclientetc>.)
102 The client portion of the Update Server process that retrieves
103 configuration files from the B</usr/afs/etc> directory of the system
104 control machine. Do not run this process in cells that use the
105 international edition of AFS. (The name of the binary is
106 B<upclient>, but the B<etc> suffix distinguishes this process
107 from B<upclientbin>.)
112 The server portion of the Update Server process
119 The Volume Location (VL) Server process
128 Specifies the process's type. The acceptable values are:
135 Use this value for cron-type processes that the BOS Server starts only at
136 a defined daily or weekly time, rather than whenever it detects that the
137 process has terminated. AFS does not define any such processes by
138 default, but makes this value available for administrator use. Define
139 the time for command execution as part of the B<-cmd> argument to the
140 B<bos create> command.
145 Use this value only for the fs process, which combines the File
146 Server, Volume Server and Salvager processes. If one of the component
147 processes terminates, the BOS Server shuts down and restarts the processes in
148 the appropriate order.
153 Use this value for all processes listed as acceptable values to the
154 B<-instance> argument, except for the B<fs> process.
155 There are no interdependencies between simple processes, so the BOS Server can
156 stop and start them independently as necessary.
163 Specifies each command the BOS Server runs to start the process.
164 Specify no more than six commands (which can include the command's
165 options, in which case the entire string is surrounded by double quotes);
166 any additional commands are ignored.
168 For a simple process, provide the complete pathname of the process's
169 binary file on the local disk (for example, B</usr/afs/bin/ptserver>
170 for the Protection Server). If including any of the initialization
171 command's options, surround the entire command in double quotes (B<"
172 ">). The B<upclient> process has a required argument, and
173 the commands for all other processes take optional arguments.
176 For the fs process, provide the complete pathname of the local
177 disk binary file for each of the component processes:
178 B<fileserver>, B<volserver>, and B<salvager>, in that
179 order. The standard binary directory is B</usr/afs/bin>.
180 If including any of an initialization command's options, surround the
181 entire command in double quotes (B<" ">).
184 For a cron process, provide two parameters:
191 The complete local disk pathname of either an executable file or a command
192 from one of the AFS suites (complete with all of the necessary
193 arguments). Surround this parameter with double quotes (B<" ">)
194 if it contains spaces.
199 A specification of when the BOS Server executes the file or command
200 indicated by the first parameter. There are three acceptable
208 The string now, which directs the BOS Server to execute the
209 file or command immediately and only once. It is usually simpler to
210 issue the command directly or issue the B<bos exec> command.
215 A time of day. The BOS Server executes the file or command daily at
216 the indicated time. Separate the hours and minutes with a colon
217 (I<hh>:I<MM>), and use either 24-hour format, or a value
218 in the range from B<1:00> through B<12:59> with
219 the addition of B<am> or B<pm>. For example, both
220 B<14:30> and B<"2:30 pm"> indicate 2:30 in
221 the afternoon. Surround this parameter with double quotes (B<"
222 ">) if it contains a space.
227 A day of the week and time of day, separated by a space and surrounded
228 with double quotes (B<" ">). The BOS Server executes the file
229 or command weekly at the indicated day and time. For the day, provide
230 either the whole name or the first three letters, all in lowercase letters
231 (B<sunday> or B<sun>, B<thursday> or B<thu>,
232 and so on). For the time, use the same format as when specifying the
243 Specifies the complete pathname on the local disk of a program that the
244 BOS Server invokes when the process terminates. The AFS distribution
245 does not include any notifier programs, but this argument is available for
246 administrator use. See the B<Related Information>
252 Names the cell in which to run the command. Do not combine this
253 argument with the B<-localauth> flag. For more details, see the
254 introductory B<bos> reference page.
259 Assigns the unprivileged identity anonymous to the
260 issuer. Do not combine this flag with the B<-localauth>
261 flag. For more details, see the introductory B<bos> reference
267 Constructs a server ticket using a key from the local
268 B</usr/afs/etc/KeyFile> file. The B<bos> command
269 interpreter presents the ticket to the BOS Server during mutual
270 authentication. Do not combine this flag with the B<-cell> or
271 B<-noauth> options. For more details, see the introductory
272 B<bos> reference page.
276 Prints the online help for this command. All other valid options
283 The following command defines and starts the simple process
284 B<kaserver> on the machine B<fs3.abc.com>:
286 % bos create -server fs3.abc.com -instance kaserver -type simple \
287 -cmd /usr/afs/bin/kaserver
289 The following command defines and starts the simple process
290 B<upclientbin> on the machine
291 B<fs4.abc.com>. It references
292 B<fs1.abc.com> as the source for updates to binary
293 files, checking for changes to the B</usr/afs/bin> directory every 120
296 % bos create -server fs4.abc.com -instance upclientbin -type simple \
297 -cmd "/usr/afs/bin/upclient fs1.abc.com -clear -t 120 \
300 The following command creates the fs process fs on the machine
301 B<fs4.abc.com>. Type the command on a single
304 % bos create -server fs4.abc.com -instance fs -type fs \
305 -cmd /usr/afs/bin/fileserver /usr/afs/bin/volserver \
306 /usr/afs/bin/salvager
308 The following command creates a cron process called
309 B<userbackup> on the machine B<fs5.abc.com>, so
310 that the BOS Server issues the indicated B<vos backupsys> command each
311 day at 3:00 a.m. (the command creates a backup version of
312 every volume in the file system whose name begins with
313 B<user>). Note that the issuer provides the complete pathname
314 to the B<vos> command, includes the B<-localauth> flag on it,
315 and types the entire B<bos create> command on one line.
317 % bos create -server fs5.abc.com -instance userbackup -type cron \
318 -cmd "/usr/afs/bin/vos backupsys -prefix user -localauth" 03:00
320 =head1 PRIVILEGE REQUIRED
322 The issuer must be listed in the /usr/afs/etc/UserList file on
323 the machine named by the B<-server> argument, or must be logged onto a
324 server machine as the local superuser B<root> if the
325 B<-localauth> flag is included.
329 If the -notifier argument is included when this command is used
330 to define and start a process, the BOS Server invokes the indicated
331 I<notifier program> when the process exits. The intended use of
332 a notifier program is to inform administrators when a process exits
333 unexpectedly, but it can be used to perform any appropriate actions.
334 The following paragraphs describe the B<bnode> and
335 B<bnode_proc> structures in which the BOS Server records information
336 about the exiting process. The list of AFS commands related to this one
339 The BOS Server constructs and sends on the standard output stream one
340 B<bnode> and one B<bnode_proc> structure for each exiting
341 process associated with the notifier program. It brackets each
342 structure with appropriate C<BEGIN> and C<END> statements
343 (C<BEGIN bnode> and C<END bnode>, C<BEGIN bnode_proc>
344 and C<END bnode_proc>), which immediately follow the preceding newline
345 character with no intervening spaces or other characters. If the
346 notifier program does not need information from a structure, it can scan ahead
347 in the input stream for the C<END> statement.
349 In general, each field in a structure is a string of ASCII text terminated
350 by the newline character. The format of the information within a
351 structure possibly varies slightly depending on the type of process associated
352 with the notifier program.
354 The C code for the B<bnode> and bnode_proc structures
355 follows. Note that the structures sent by the BOS Server do not
356 necessarily include all of the fields described here, because some are used
357 only for internal record keeping. The notifier process must robustly
358 handle the absence of expected fields, as well as the presence of unexpected
359 fields, on the standard input stream.
361 For proper performance, the notifier program must continue processing the
362 input stream until it detects the end-of-file (EOF). The BOS Server
363 closes the standard input file descriptor to the notifier process when it has
364 completed delivery of the data, and it is the responsibility of the notifier
365 process to terminate properly.
367 struct bnode contents
370 struct bnode *next; /* next pointer in top-level's list */
371 char *name; /* instance name */
372 long nextTimeout; /* next time this guy should be awakened */
373 long period; /* period between calls */
374 long rsTime; /* time we started counting restarts */
375 long rsCount; /* count of restarts since rsTime */
376 struct bnode_type *type; /* type object */
377 struct bnode_ops *ops; /* functions implementing bnode class */
378 long procStartTime; /* last time a process was started */
379 long procStarts; /* number of process starts */
380 long lastAnyExit; /* last time a process exited for any reason */
381 long lastErrorExit; /* last time a process exited unexpectedly */
382 long errorCode; /* last exit return code */
383 long errorSignal; /* last proc terminating signal */
384 char *lastErrorName; /* name of proc that failed last */
385 short refCount; /* reference count */
386 short flags; /* random flags */
387 char goal; /* 1=running or 0=not running */
388 char fileGoal; /* same, but to be stored in file */
391 format of struct bnode explosion
393 printf("name: %s\n",tp->name);
394 printf("rsTime: %ld\n", tp->rsTime);
395 printf("rsCount: %ld\n", tp->rsCount);
396 printf("procStartTime: %ld\n", tp->procStartTime);
397 printf("procStarts: %ld\n", tp->procStarts);
398 printf("lastAnyExit: %ld\n", tp->lastAnyExit);
399 printf("lastErrorExit: %ld\n", tp->lastErrorExit);
400 printf("errorCode: %ld\n", tp->errorCode);
401 printf("errorSignal: %ld\n", tp->errorSignal);
402 printf("lastErrorName: %s\n", tp->lastErrorName);
403 printf("goal: %d\n", tp->goal);
405 struct bnode_proc contents
408 struct bnode_proc *next; /* next guy in top-level's list */
409 struct bnode *bnode; /* bnode creating this process */
410 char *comLine; /* command line used to start this process */
411 char *coreName; /* optional core file component name */
412 long pid; /* pid if created */
413 long lastExit; /* last termination code */
414 long lastSignal; /* last signal that killed this guy */
415 long flags; /* flags giving process state */
418 format of struct bnode_proc explosion
420 printf("comLine: %s\n", tp->comLine);
421 printf("coreName: %s\n", tp->coreName);
422 printf("pid: %ld\n", tp->pid);
423 printf("lastExit: %ld\n", tp->lastExit);
424 printf("lastSignal: %ld\n", tp->lastSignal);
444 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
446 This documentation is covered by the IBM Public License Version 1.0. It was
447 converted from HTML to POD by software written by Chas Williams and Russ
448 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.