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