3 bos create - Defines a new process in the B</usr/afs/local/BosConfig> file and starts
8 bos create B<-server> I<machine name> B<-instance> I<server process name>
9 B<-type> I<server type> B<-cmd> I<command lines> [I<command lines> ...]
10 [B<-notifier> I<Notifier program>] [B<-cell> I<cell name>]
11 [B<-noauth>] [B<-localauth>] [B<-help>]
13 bos c B<-s> I<machine name> B<-i> I<server process name> B<-t> I<server type>
14 B<-cm> I<command lines> [I<command lines> ...] [B<-not> I<Notifier program>] [B<-ce> I<cell name>]
15 [B<-noa>] [B<-l>] [B<-h>]
19 The C<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> in the B<BosConfig>
22 file and in memory, and starts the process.
24 A server process's entry in the B<BosConfig> file defines its name, its
25 type, the command that initializes it, and optionally, the name of a
26 notifier program that runs when the process terminates.
32 =item B<-server> I<machine name>
34 Indicates the server machine on which to define and start the
35 new process. Identify the machine by IP address or its host
36 name (either fully-qualified or abbreviated unambiguously). For
37 details, see the introductory reference page for the C<bos>
40 =item B<-instance> I<server process name>
42 Names the process to define and start. Any name is acceptable,
43 but for the sake of simplicity it is best to use the last
44 element of the process's binary file pathname, and to use the
45 same name on every server machine. The conventional names, as
46 used in all AFS documentation, are:
52 The Backup Server process
56 The process that combines the File Server, Volume Server,
57 and Salvager processes (B<fileserver>, B<volserver>, and
62 The Authentication Server process
66 The Protection Server process
70 The controller process for the Network Time Protocol
75 The client portion of the Update Server process that
76 retrieves binary files from the B</usr/afs/bin> directory of
77 the binary distribution machine for this machine's
78 CPU/operating system type. (The name of the binary is
79 B<upclient>, but the B<bin> suffix distinguishes this process
84 The client portion of the Update Server process that
85 retrieves configuration files from the B</usr/afs/etc>
86 directory of the system control machine. Do not run this
87 process in cells that use the international edition of
88 AFS. (The name of the binary is B<upclient>, but the B<etc>
89 suffix distinguishes this process from B<upclientbin>.)
93 The server portion of the Update Server process
97 The Volume Location (VL) Server process
101 =item B<-type> I<server type>
103 Specifies the process's type. The acceptable values are:
109 Use this value for cron-type processes that the BOS
110 Server starts only at a defined daily or weekly time,
111 rather than whenever it detects that the process has
112 terminated. AFS does not define any such processes by
113 default, but makes this value available for administrator
114 use. Define the time for command execution as part of the
115 B<-cmd> argument to the C<bos create> command.
119 Use this value only for the B<fs> process, which combines
120 the File Server, Volume Server and Salvager processes. If
121 one of the component processes terminates, the BOS Server
122 shuts down and restarts the processes in the appropriate
127 Use this value for all processes listed as acceptable
128 values to the B<-instance> argument, except for the B<fs>
129 process. There are no interdependencies between simple
130 processes, so the BOS Server can stop and start them
131 independently as necessary.
135 =item B<-cmd> I<command lines> [I<command lines> ...]
137 Specifies each command the BOS Server runs to start the
138 process. Specify no more than six commands (which can include
139 the command's options, in which case the entire string is
140 surrounded by double quotes); any additional commands are
143 For a simple process, provide the complete pathname of the
144 process's binary file on the local disk (for example,
145 B</usr/afs/bin/ptserver> for the Protection Server). If including
146 any of the initialization command's options, surround the
147 entire command in double quotes (" "). The B<upclient> process has
148 a required argument, and the commands for all other processes
149 take optional arguments.
151 For the B<fs> process, provide the complete pathname of the local
152 disk binary file for each of the component processes:
153 B<fileserver>, B<volserver>, and B<salvager>, in that order. The
154 standard binary directory is B</usr/afs/bin>. If including any of
155 an initialization command's options, surround the entire
156 command in double quotes (B<" ">).
158 For a B<cron> process, provide two parameters:
164 The complete local disk pathname of either an executable file
165 or a command from one of the AFS suites (complete with all of
166 the necessary arguments). Surround this parameter with double
167 quotes (B<" ">) if it contains spaces.
171 A specification of when the BOS Server executes the file or
172 command indicated by the first parameter. There are three
179 The string C<now>, which directs the BOS Server to execute
180 the file or command immediately and only once. It is
181 usually simpler to issue the command directly or issue
182 the C<bos exec> command.
186 A time of day. The BOS Server executes the file or
187 command daily at the indicated time. Separate the hours
188 and minutes with a colon (I<hh>:I<MM>), and use either 24-hour
189 format, or a value in the range from B<1:00> through B<12:59>
190 with the addition of B<am> or B<pm>. For example, both B<14:30>
191 and B<"2:30 pm"> indicate 2:30 in the afternoon. Surround
192 this parameter with double quotes (B<" ">) if it contains a
197 A day of the week and time of day, separated by a space
198 and surrounded with double quotes (B<" ">). The BOS Server
199 executes the file or command weekly at the indicated day
200 and time. For the day, provide either the whole name or
201 the first three letters, all in lowercase letters
202 (B<sunday> or B<sun>, B<thursday> or B<thu>, and so on). For the
203 time, use the same format as when specifying the time
210 =item B<-notifier> I<Notifier program>
212 Specifies the complete pathname on the local disk of a program
213 that the BOS Server invokes when the process terminates. The
214 AFS distribution does not include any notifier programs, but
215 this argument is available for administrator use. See the
216 L</"Related Information"> section.
218 =item B<-cell> I<cell name>
220 Names the cell in which to run the command. Do not combine this
221 argument with the B<-localauth> flag. For more details, see the
222 introductory L<bos(1)> reference page.
226 Assigns the unprivileged identity B<anonymous> to the issuer. Do
227 not combine this flag with the B<-localauth> flag. For more
228 details, see the introductory L<bos(1)> reference page.
232 Constructs a server ticket using a key from the local
233 B</usr/afs/etc/KeyFile> file. The C<bos> command interpreter presents
234 the ticket to the BOS Server during mutual authentication. Do
235 not combine this flag with the B<-cell> or B<-noauth> options. For
236 more details, see the introductory L<bos(1)> reference page.
240 Prints the online help for this command. All other valid
247 The following command defines and starts the simple process kaserver
248 on the machine B<fs3.abc.com>:
250 bos create -server fs3.abc.com -instance kaserver -type simple \
251 -cmd /usr/afs/bin/kaserver
253 The following command defines and starts the simple process
254 B<upclientbin> on the machine B<fs4.abc.com>. It references B<fs1.abc.com> as
255 the source for updates to binary files, checking for changes to the
256 B</usr/afs/bin> directory every 120 seconds.
258 bos create -server fs4.abc.com -instance upclientbin -type simple \
259 -cmd "/usr/afs/bin/upclient fs1.abc.com -clear -t 120 \
262 The following command creates the fs process B<fs> on the machine
263 B<fs4.abc.com>. Type the command on a single line.
265 bos create -server fs4.abc.com -instance fs -type fs \
266 -cmd /usr/afs/bin/fileserver /usr/afs/bin/volserver \
267 /usr/afs/bin/salvager
269 The following command creates a B<cron> process called B<userbackup> on the
270 machine B<fs5.abc.com>, so that the BOS Server issues the indicated C<vos
271 backupsys> command each day at 3:00 a.m. (the command creates a backup
272 version of every volume in the file system whose name begins with
273 B<user>). Note that the issuer provides the complete pathname to the C<vos>
274 command, includes the B<-localauth> flag on it, and types the entire C<bos
275 create> command on one line.
277 bos create -server fs5.abc.com -instance userbackup -type cron \
278 -cmd "/usr/afs/bin/vos backupsys -prefix user -localauth" 03:00
280 =head1 PRIVILEGE REQUIRED
282 The issuer must be listed in the B</usr/afs/etc/UserList> file on the
283 machine named by the B<-server> argument, or must be logged onto a server
284 machine as the local superuser B<root> if the B<-localauth> flag is
287 =head1 Related Information
289 If the B<-notifier> argument is included when this command is used to
290 define and start a process, the BOS Server invokes the indicated
291 I<notifier program> when the process exits. The intended use of a
292 notifier program is to inform administrators when a process exits
293 unexpectedly, but it can be used to perform any appropriate actions.
294 The following paragraphs describe the B<bnode> and B<bnode_proc> structures
295 in which the BOS Server records information about the exiting process.
296 The list of AFS commands related to this one follows.
298 The BOS Server constructs and sends on the standard output stream one
299 B<bnode> and one B<bnode_proc> structure for each exiting process associated
300 with the notifier program. It brackets each structure with appropriate
301 C<BEGIN> and C<END> statements (C<BEGIN bnode> and C<END bnode>, C<BEGIN bnode_proc>
302 and C<END bnode_proc>), which immediately follow the preceding newline
303 character with no intervening spaces or other characters. If the
304 notifier program does not need information from a structure, it can
305 scan ahead in the input stream for the C<END> statement.
307 In general, each field in a structure is a string of ASCII text
308 terminated by the newline character. The format of the information
309 within a structure possibly varies slightly depending on the type of
310 process associated with the notifier program.
312 The C code for the B<bnode> and B<bnode_proc> structures follows. Note that
313 the structures sent by the BOS Server do not necessarily include all
314 of the fields described here, because some are used only for internal
315 record keeping. The notifier process must robustly handle the absence
316 of expected fields, as well as the presence of unexpected fields, on
317 the standard input stream.
319 For proper performance, the notifier program must continue processing
320 the input stream until it detects the end-of-file (EOF). The BOS
321 Server closes the standard input file descriptor to the notifier
322 process when it has completed delivery of the data, and it is the
323 responsibility of the notifier process to terminate properly.
325 =head2 struct bnode contents
328 struct bnode *next; /* next pointer in top-level's list */
329 char *name; /* instance name */
330 long nextTimeout; /* next time this guy should be awakened */
331 long period; /* period between calls */
332 long rsTime; /* time we started counting restarts */
333 long rsCount; /* count of restarts since rsTime */
334 struct bnode_type *type; /* type object */
335 struct bnode_ops *ops; /* functions implementing bnode class */
336 long procStartTime; /* last time a process was started */
337 long procStarts; /* number of process starts */
338 long lastAnyExit; /* last time a process exited for any reason */
339 long lastErrorExit; /* last time a process exited unexpectedly */
340 long errorCode; /* last exit return code */
341 long errorSignal; /* last proc terminating signal */
342 char *lastErrorName; /* name of proc that failed last */
343 short refCount; /* reference count */
344 short flags; /* random flags */
345 char goal; /* 1=running or 0=not running */
346 char fileGoal; /* same, but to be stored in file */
349 =head2 format of struct bnode explosion
351 printf("name: %s\n",tp->name);
352 printf("rsTime: %ld\n", tp->rsTime);
353 printf("rsCount: %ld\n", tp->rsCount);
354 printf("procStartTime: %ld\n", tp->procStartTime);
355 printf("procStarts: %ld\n", tp->procStarts);
356 printf("lastAnyExit: %ld\n", tp->lastAnyExit);
357 printf("lastErrorExit: %ld\n", tp->lastErrorExit);
358 printf("errorCode: %ld\n", tp->errorCode);
359 printf("errorSignal: %ld\n", tp->errorSignal);
360 printf("lastErrorName: %s\n", tp->lastErrorName);
361 printf("goal: %d\n", tp->goal);
363 =head2 struct bnode_proc contents
366 struct bnode_proc *next; /* next guy in top-level's list */
367 struct bnode *bnode; /* bnode creating this process */
368 char *comLine; /* command line used to start this process */
369 char *coreName; /* optional core file component name */
370 long pid; /* pid if created */
371 long lastExit; /* last termination code */
372 long lastSignal; /* last signal that killed this guy */
373 long flags; /* flags giving process state */
376 =head2 format of struct bnode_proc explosion
378 printf("comLine: %s\n", tp->comLine);
379 printf("coreName: %s\n", tp->coreName);
380 printf("pid: %ld\n", tp->pid);
381 printf("lastExit: %ld\n", tp->lastExit);
382 printf("lastSignal: %ld\n", tp->lastSignal);
386 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
388 Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
389 and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
390 Stanford Linear Accelerator Center, a department of Stanford University.