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