Update bos create man page for new naming of demand-attach binaries
[openafs.git] / doc / man-pages / pod8 / bos_create.pod
1 =head1 NAME
2
3 bos_create - Defines a new process in the BosConfig file and starts it
4
5 =head1 SYNOPSIS
6
7 =for html
8 <div class="synopsis">
9
10 B<bos create> S<<< B<-server> <I<machine name>> >>>
11     S<<< B<-instance> <I<server process name>> >>> S<<< B<-type> <I<server type>> >>>
12     S<<< B<-cmd> <I<command lines>>+ >>> S<<< [B<-notifier> <I<notifier program>>] >>>
13     S<<< [B<-cell> <I<cell name>>] >>> [B<-noauth>] [B<-localauth>] [B<-help>]
14
15 B<bos c> S<<< B<-s> <I<machine name>> >>> S<<< B<-i> <I<server process name>> >>>
16     S<<< B<-t> <I<server type>> >>> S<<< B<-cm> <I<command lines>>+ >>>
17     S<<< [B<-not> <I<notifier program>>] >>> S<<< [B<-ce> <I<cell name>>] >>> [B<-noa>]
18     [B<-l>] [B<-h>]
19
20 =for html
21 </div>
22
23 =head1 DESCRIPTION
24
25 The B<bos create> command creates a server process entry in the
26 F</usr/afs/local/BosConfig> file on the server machine named by the
27 B<-server> argument, sets the process's status to C<Run> in the
28 F<BosConfig> file and in memory, and starts the process.
29
30 A server process's entry in the F<BosConfig> file defines its name, its
31 type, the command that initializes it, and optionally, the name of a
32 notifier program that runs when the process terminates.
33
34 =head1 CAUTIONS
35
36 A server process entry of type B<fs> as described below will not work with
37 a demand-attach File Server, and a server process entry of type B<dafs>
38 for a demand-attach File Server will not work with a traditional File
39 Server. When switching from one File Server implementation to another,
40 remove the existing server process entry and create a new one. See
41 L<EXAMPLES> below for an example of switching from a traditional File
42 Server to a demand-attach File Server.
43
44 =head1 OPTIONS
45
46 =over 4
47
48 =item B<-server> <I<machine name>>
49
50 Indicates the server machine on which to define and start the new
51 process. Identify the machine by IP address or its host name (either
52 fully-qualified or abbreviated unambiguously). For details, see L<bos(8)>.
53
54 =item B<-instance> <I<server process name>>
55
56 Names the process to define and start. Any name is acceptable, but for the
57 sake of simplicity it is best to use the last element of the process's
58 binary file pathname (or the instance type for B<fs> and B<dafs>), and to
59 use the same name on every server machine. The conventional names, as used
60 in all AFS documentation, are:
61
62 =over 4
63
64 =item buserver
65
66 The Backup Server process.
67
68 =item dafs
69
70 The process that combines the Demand Attach File Server, Volume Server, 
71 Salvageserver and Salvager processes (B<dafileserver>, B<davolserver>,
72 B<salvageserver>, and B<dasalvager>).
73
74 =item fs
75
76 The process that combines the File Server, Volume Server, and Salvager
77 processes (B<fileserver>, B<volserver>, and B<salvager>).
78
79 =item kaserver
80
81 The Authentication Server process.
82
83 =item ptserver
84
85 The Protection Server process.
86
87 =item runntp
88
89 The controller process for the Network Time Protocol Daemon (obsolete).
90
91 =item upclientbin
92
93 The client portion of the Update Server process that retrieves binary
94 files from the F</usr/afs/bin> directory of the binary distribution
95 machine for this machine's CPU/operating system type. (The name of the
96 binary is B<upclient>, but the C<bin> suffix distinguishes this process
97 from C<upclientetc>.)
98
99 =item upclientetc
100
101 The client portion of the Update Server process that retrieves
102 configuration files from the F</usr/afs/etc> directory of the system
103 control machine. (The name of the binary is B<upclient>, but the C<etc>
104 suffix distinguishes this process from C<upclientbin>.)
105
106 =item upserver
107
108 The server portion of the Update Server process.
109
110 =item vlserver
111
112 The Volume Location (VL) Server process.
113
114 =back
115
116 =item B<-type> <I<server type>>
117
118 Specifies the process's type. The acceptable values are:
119
120 =over 4
121
122 =item cron
123
124 Use this value for cron-type processes that the BOS Server starts only at
125 a defined daily or weekly time, rather than whenever it detects that the
126 process has terminated. AFS does not define any such processes by default,
127 but makes this value available for administrator use. Define the time for
128 command execution as part of the B<-cmd> argument to the B<bos create>
129 command.
130
131 =item dafs
132
133 Use this value only for the dafs process, which combines the File Server,
134 Volume Server, Salvage Server, and Salvager processes in order to operate
135 as a Demand Attach File Server.  If one of the component processes
136 terminates, the BOS Server shuts down and restarts the process in the
137 appropriate order.
138
139 =item fs
140
141 Use this value only for the fs process, which combines the File Server,
142 Volume Server and Salvager processes. If one of the component processes
143 terminates, the BOS Server shuts down and restarts the processes in the
144 appropriate order.
145
146 =item simple
147
148 Use this value for all processes listed as acceptable values to the
149 B<-instance> argument, except for the B<fs> and B<dafs> processes.  
150 There are no interdependencies between simple processes, so the 
151 BOS Server can stop and start them independently as necessary.
152
153 =back
154
155 =item B<-cmd> <I<command lines>>+
156
157 Specifies each command the BOS Server runs to start the process.  Specify
158 no more than six commands (which can include the command's options, in
159 which case the entire string is surrounded by double quotes); any
160 additional commands are ignored.
161
162 For a simple process, provide the complete pathname of the process's
163 binary file on the local disk (for example, F</usr/afs/bin/ptserver> for
164 the Protection Server). If including any of the initialization command's
165 options, surround the entire command in double quotes (C<"">). The
166 B<upclient> process has a required argument, and the commands for all
167 other processes take optional arguments.
168
169 For the B<fs> process, provide the complete pathname of the local disk
170 binary file for each of the component processes: B<fileserver>,
171 B<volserver>, and B<salvager>, in that order. The standard binary
172 directory is F</usr/afs/bin>.  If including any of an initialization
173 command's options, surround the entire command in double quotes (C<"">).
174
175 For the B<dafs> process, provide the complete pathname of the local disk
176 binary file for each of the component processes: B<dafileserver>,
177 B<davolserver>, B<salvageserver>, and B<dasalvager>, in that order. The
178 standard binary directory is F</usr/afs/bin>.  If including any of an
179 initialization command's options, surround the entire command in double
180 quotes (C<"">).
181
182 For a cron process, provide two parameters:
183
184 =over 4
185
186 =item *
187
188 The complete local disk pathname of either an executable file or a command
189 from one of the AFS suites (complete with all of the necessary
190 arguments). Surround this parameter with double quotes (C<"">) if it
191 contains spaces.
192
193 =item *
194
195 A specification of when the BOS Server executes the file or command
196 indicated by the first parameter. There are three acceptable values:
197
198 =over 4
199
200 =item *
201
202 The string C<now>, which directs the BOS Server to execute the file or
203 command immediately and only once. It is usually simpler to issue the
204 command directly or issue the B<bos exec> command.
205
206 =item *
207
208 A time of day. The BOS Server executes the file or command daily at the
209 indicated time. Separate the hours and minutes with a colon (I<hh:MM>),
210 and use either 24-hour format, or a value in the range from C<1:00>
211 through C<12:59> with the addition of C<am> or C<pm>. For example, both
212 C<14:30> and C<"2:30 pm"> indicate 2:30 in the afternoon. Surround this
213 parameter with double quotes (C<"">) if it contains a space.
214
215 =item *
216
217 A day of the week and time of day, separated by a space and surrounded
218 with double quotes (C<"">). The BOS Server executes the file or command
219 weekly at the indicated day and time. For the day, provide either the
220 whole name or the first three letters, all in lowercase letters (C<sunday>
221 or C<sun>, C<thursday> or C<thu>, and so on). For the time, use the same
222 format as when specifying the time alone.
223
224 =back
225
226 =back
227
228 =item B<-notifier> <I<notifier program>>
229
230 Specifies the complete pathname on the local disk of a program that the
231 BOS Server invokes when the process terminates. The AFS distribution does
232 not include any notifier programs, but this argument is available for
233 administrator use. See L<NOTES>.
234
235 =item B<-cell> <I<cell name>>
236
237 Names the cell in which to run the command. Do not combine this argument
238 with the B<-localauth> flag. For more details, see L<bos(8)>.
239
240 =item B<-noauth>
241
242 Assigns the unprivileged identity C<anonymous> to the issuer. Do not
243 combine this flag with the B<-localauth> flag. For more details, see
244 L<bos(8)>.
245
246 =item B<-localauth>
247
248 Constructs a server ticket using a key from the local
249 F</usr/afs/etc/KeyFile> file. The B<bos> command interpreter presents the
250 ticket to the BOS Server during mutual authentication. Do not combine this
251 flag with the B<-cell> or B<-noauth> options. For more details, see
252 L<bos(8)>.
253
254 =item B<-help>
255
256 Prints the online help for this command. All other valid options are
257 ignored.
258
259 =back
260
261 =head1 EXAMPLES
262
263 The following command defines and starts the simple process
264 C<ptserver> on the machine C<fs3.abc.com>:
265
266    % bos create -server fs3.abc.com -instance ptserver -type simple \
267                 -cmd /usr/afs/bin/ptserver
268
269 The following command defines and starts the simple process C<upclientbin>
270 on the machine C<fs4.abc.com>. It references C<fs1.abc.com> as the source
271 for updates to binary files, checking for changes to the F</usr/afs/bin>
272 directory every 120 seconds.
273
274    % bos create -server fs4.abc.com -instance upclientbin -type simple \
275                 -cmd "/usr/afs/bin/upclient fs1.abc.com -clear -t 120 \
276                 /usr/afs/bin"
277
278 The following command creates the B<fs> process C<fs> on the machine
279 C<fs4.abc.com> (a traditional File Server with associated processes). Type
280 the command on a single line.
281
282    % bos create -server fs4.abc.com -instance fs -type fs \
283                 -cmd /usr/afs/bin/fileserver /usr/afs/bin/volserver \
284                 /usr/afs/bin/salvager
285
286 The following command creates the B<dafs> process C<dafs> on the machine
287 C<fs4.abc.com> (a demand-attach File Server with associated processes).
288 Type the command on a single line.
289
290    % bos create -server fs4.abc.com -instance dafs -type dafs \
291                 -cmd /usr/afs/bin/dafileserver \
292                 /usr/afs/bin/davolserver \
293                 /usr/afs/bin/salvageserver /usr/afs/bin/dasalvager
294
295 The following command creates a cron process called C<userbackup> on the
296 machine C<fs5.abc.com>, so that the BOS Server issues the indicated B<vos
297 backupsys> command each day at 3:00 a.m. (the command creates a backup
298 version of every volume in the file system whose name begins with
299 C<user>). Note that the issuer provides the complete pathname to the
300 B<vos> command, includes the B<-localauth> flag on it, and types the
301 entire B<bos create> command on one line.
302
303    % bos create -server fs5.abc.com -instance userbackup -type cron  \
304        -cmd "/usr/afs/bin/vos backupsys -prefix user -localauth" 03:00
305
306 To switch from a traditional File Server to a demand-attach File Server,
307 run:
308
309    % bos status localhost -instance fs -long
310
311 to see the current B<fileserver> and B<volserver> flags for an existing
312 traditional File Server configuration. (Substitute the C<dafs> instance
313 for an existing demand-attach File Server.) Then, run:
314
315    % bos stop localhost fs -localauth
316    % bos delete localhost fs -localauth
317    % bos create localhost dafs dafs \
318        "/usr/afs/bin/dafileserver <fileserver-flags>" \
319        "/usr/afs/bin/davolserver <volserver-flags>" \
320        /usr/afs/bin/salvageserver /usr/afs/bin/dasalvager
321
322 replacing <fileserver-flags> and <volserver-flags> with the flags from the
323 previous configuration. This will stop the traditional File Server and
324 start a demand-attach File Server. The binaries at the paths provided must
325 already be updated to binaries built with demand-attach enabled.
326
327 =head1 PRIVILEGE REQUIRED
328
329 The issuer must be listed in the F</usr/afs/etc/UserList> file on the
330 machine named by the B<-server> argument, or must be logged onto a server
331 machine as the local superuser C<root> if the B<-localauth> flag is
332 included.
333
334 The B<bos create> command cannot be run against servers which are in
335 restricted mode.
336
337 =head1 NOTES
338
339 If the B<-notifier> argument is included when this command is used to
340 define and start a process, the BOS Server invokes the indicated
341 I<notifier program> when the process exits. The intended use of a notifier
342 program is to inform administrators when a process exits unexpectedly, but
343 it can be used to perform any appropriate actions.  The following
344 paragraphs describe the bnode and bnode_proc structures in which the
345 BOS Server records information about the exiting process.
346
347 The BOS Server constructs and sends on the standard output stream one
348 bnode and one bnode_proc structure for each exiting process associated
349 with the notifier program. It brackets each structure with appropriate
350 C<BEGIN> and C<END> statements (C<BEGIN bnode> and C<END bnode>, C<BEGIN
351 bnode_proc> and C<END bnode_proc>), which immediately follow the preceding
352 newline character with no intervening spaces or other characters. If the
353 notifier program does not need information from a structure, it can scan
354 ahead in the input stream for the C<END> statement.
355
356 In general, each field in a structure is a string of ASCII text terminated
357 by the newline character. The format of the information within a structure
358 possibly varies slightly depending on the type of process associated with
359 the notifier program.
360
361 The C code for the bnode and bnode_proc structures follows. Note that the
362 structures sent by the BOS Server do not necessarily include all of the
363 fields described here, because some are used only for internal record
364 keeping. The notifier process must robustly handle the absence of expected
365 fields, as well as the presence of unexpected fields, on the standard
366 input stream.
367
368 For proper performance, the notifier program must continue processing the
369 input stream until it detects the end-of-file (EOF). The BOS Server closes
370 the standard input file descriptor to the notifier process when it has
371 completed delivery of the data, and it is the responsibility of the
372 notifier process to terminate properly.
373
374 struct bnode contents:
375
376    struct bnode {
377       struct bnode *next;      /* next pointer in top-level's list */
378       char *name;              /* instance name */
379       long nextTimeout;        /* next time this guy should be awakened */
380       long period;             /* period between calls */
381       long rsTime;             /* time we started counting restarts */
382       long rsCount;            /* count of restarts since rsTime */
383       struct bnode_type *type; /* type object */
384       struct bnode_ops *ops;   /* functions implementing bnode class */
385       long procStartTime;      /* last time a process was started */
386       long procStarts;         /* number of process starts */
387       long lastAnyExit;        /* last time a process exited for any reason */
388       long lastErrorExit;      /* last time a process exited unexpectedly */
389       long errorCode;          /* last exit return code */
390       long errorSignal;        /* last proc terminating signal */
391       char *lastErrorName;     /* name of proc that failed last */
392       short refCount;          /* reference count */
393       short flags;             /* random flags */
394       char goal;               /* 1=running or 0=not running */
395       char fileGoal;           /* same, but to be stored in file */
396 };
397
398 Format of struct bnode explosion:
399
400    printf("name: %s\n",tp->name);
401    printf("rsTime: %ld\n", tp->rsTime);
402    printf("rsCount: %ld\n", tp->rsCount);
403    printf("procStartTime: %ld\n", tp->procStartTime);
404    printf("procStarts: %ld\n", tp->procStarts);
405    printf("lastAnyExit: %ld\n", tp->lastAnyExit);
406    printf("lastErrorExit: %ld\n", tp->lastErrorExit);
407    printf("errorCode: %ld\n", tp->errorCode);
408    printf("errorSignal: %ld\n", tp->errorSignal);
409    printf("lastErrorName: %s\n", tp->lastErrorName);
410    printf("goal: %d\n", tp->goal);
411
412 struct bnode_proc contents:
413
414    struct bnode_proc {
415       struct bnode_proc *next; /* next guy in top-level's list */
416       struct bnode *bnode;     /* bnode creating this process */
417       char *comLine;           /* command line used to start this process */
418       char *coreName;          /* optional core file component name */
419       long pid;                /* pid if created */
420       long lastExit;           /* last termination code */
421       long lastSignal;         /* last signal that killed this guy */
422       long flags;              /* flags giving process state */
423 };
424
425 Format of struct bnode_proc explosion:
426
427    printf("comLine: %s\n", tp->comLine);
428    printf("coreName: %s\n", tp->coreName);
429    printf("pid: %ld\n", tp->pid);
430    printf("lastExit: %ld\n", tp->lastExit);
431    printf("lastSignal: %ld\n", tp->lastSignal);
432
433 =head1 SEE ALSO
434
435 L<BosConfig(5)>,
436 L<KeyFile(5)>,
437 L<UserList(5)>,
438 L<bos(8)>,
439 L<buserver(8)>,
440 L<dafileserver(8)>,
441 L<dasalvager(8)>,
442 L<davolserver(8)>,
443 L<fileserver(8)>,
444 L<kaserver(8)>,
445 L<ptserver(8)>,
446 L<salvager(8)>,
447 L<salvageserver(8)>,
448 L<upclient(8)>,
449 L<upserver(8)>,
450 L<vlserver(8)>,
451 L<volserver(8)>,
452 L<vos_backupsys(1)>
453
454 =head1 COPYRIGHT
455
456 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
457
458 This documentation is covered by the IBM Public License Version 1.0.  It was
459 converted from HTML to POD by software written by Chas Williams and Russ
460 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.