1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 4//EN">
3 <TITLE>Administration Reference</TITLE>
4 <!-- Begin Header Records ========================================== -->
5 <!-- /tmp/idwt3672/auarf000.scr converted by idb2h R4.2 (359) ID -->
6 <!-- Workbench Version (AIX) on 3 Oct 2000 at 16:18:30 -->
7 <META HTTP-EQUIV="updated" CONTENT="Tue, 03 Oct 2000 16:18:29">
8 <META HTTP-EQUIV="review" CONTENT="Wed, 03 Oct 2001 16:18:29">
9 <META HTTP-EQUIV="expires" CONTENT="Thu, 03 Oct 2002 16:18:29">
11 <!-- (C) IBM Corporation 2000. All Rights Reserved -->
12 <BODY bgcolor="ffffff">
13 <!-- End Header Records ============================================ -->
14 <A NAME="Top_Of_Page"></A>
15 <H1>Administration Reference</H1>
16 <HR><P ALIGN="center"> <A HREF="../index.htm"><IMG SRC="../books.gif" BORDER="0" ALT="[Return to Library]"></A> <A HREF="auarf002.htm#ToC"><IMG SRC="../toc.gif" BORDER="0" ALT="[Contents]"></A> <A HREF="auarf097.htm"><IMG SRC="../prev.gif" BORDER="0" ALT="[Previous Topic]"></A> <A HREF="#Bot_Of_Page"><IMG SRC="../bot.gif" BORDER="0" ALT="[Bottom of Topic]"></A> <A HREF="auarf099.htm"><IMG SRC="../next.gif" BORDER="0" ALT="[Next Topic]"></A> <A HREF="auarf284.htm#HDRINDEX"><IMG SRC="../index.gif" BORDER="0" ALT="[Index]"></A> <P>
18 <H2><A NAME="HDRBOS_CREATE" HREF="auarf002.htm#ToC_112">bos create</A></H2>
19 <A NAME="IDX4477"></A>
20 <A NAME="IDX4478"></A>
21 <A NAME="IDX4479"></A>
22 <A NAME="IDX4480"></A>
23 <A NAME="IDX4481"></A>
24 <A NAME="IDX4482"></A>
25 <A NAME="IDX4483"></A>
26 <A NAME="IDX4484"></A>
27 <A NAME="IDX4485"></A>
28 <A NAME="IDX4486"></A>
29 <P><STRONG>Purpose</STRONG>
30 <P>Defines a new process in the <B>/usr/afs/local/BosConfig</B> file and
32 <P><STRONG>Synopsis</STRONG>
33 <PRE><B>bos create -server</B> <<VAR>machine name</VAR>> <B>-instance</B> <<VAR>server process name</VAR>>
34 <B>-type</B> <<VAR>server type</VAR>> <B>-cmd</B> <<VAR>command lines</VAR>><SUP>+</SUP>
35 [<B>-notifier</B> <<VAR>Notifier program</VAR>>] [<B>-cell</B> <<VAR>cell name</VAR>>]
36 [<B>-noauth</B>] [<B>-localauth</B>] [<B>-help</B>]
38 <B>bos c -s</B> <<VAR>machine name</VAR>> <B>-i</B> <<VAR>server process name</VAR>> <B>-t</B> <<VAR>server type</VAR>>
39 <B>-cm</B> <<VAR>command lines</VAR>><SUP>+</SUP> [<B>-not</B> <<VAR>Notifier program</VAR>>] [<B>-ce</B> <<VAR>cell name</VAR>>]
40 [<B>-noa</B>] [<B>-l</B>] [<B>-h</B>]
42 <P><STRONG>Description</STRONG>
43 <P>The <B>bos create</B> command creates a server process entry in the
44 <B>/usr/afs/local/BosConfig</B> file on the server machine named by the
45 <B>-server</B> argument, sets the process's status to <B>Run</B>
46 in the <B>BosConfig</B> file and in memory, and starts the process.
47 <P>A server process's entry in the <B>BosConfig</B> file defines its
48 name, its type, the command that initializes it, and optionally, the name of a
49 notifier program that runs when the process terminates.
50 <P><STRONG>Options</STRONG>
52 <P><DT><B><B>-server</B>
53 </B><DD>Indicates the server machine on which to define and start the new
54 process. Identify the machine by IP address or its host name (either
55 fully-qualified or abbreviated unambiguously). For details, see the
56 introductory reference page for the <B>bos</B> command suite.
57 <P><DT><B><B>-instance</B>
58 </B><DD>Names the process to define and start. Any name is acceptable, but
59 for the sake of simplicity it is best to use the last element of the
60 process's binary file pathname, and to use the same name on every server
61 machine. The conventional names, as used in all AFS documentation,
64 <P><DT><B><B>buserver</B>
65 </B><DD>The Backup Server process
66 <A NAME="IDX4487"></A>
67 <A NAME="IDX4488"></A>
69 </B><DD>The process that combines the File Server, Volume Server, and Salvager
70 processes (<B>fileserver</B>, <B>volserver</B>, and
72 <A NAME="IDX4489"></A>
73 <A NAME="IDX4490"></A>
74 <P><DT><B><B>kaserver</B>
75 </B><DD>The Authentication Server process
76 <A NAME="IDX4491"></A>
77 <A NAME="IDX4492"></A>
78 <P><DT><B><B>ptserver</B>
79 </B><DD>The Protection Server process
80 <A NAME="IDX4493"></A>
81 <A NAME="IDX4494"></A>
82 <P><DT><B><B>runntp</B>
83 </B><DD>The controller process for the Network Time Protocol Daemon
84 <A NAME="IDX4495"></A>
85 <A NAME="IDX4496"></A>
86 <P><DT><B><B>upclientbin</B>
87 </B><DD>The client portion of the Update Server process that retrieves binary
88 files from the <B>/usr/afs/bin</B> directory of the binary distribution
89 machine for this machine's CPU/operating system type. (The name of
90 the binary is <B>upclient</B>, but the <B>bin</B> suffix distinguishes
91 this process from <B>upclientetc</B>.)
92 <A NAME="IDX4497"></A>
93 <A NAME="IDX4498"></A>
94 <P><DT><B><B>upclientetc</B>
95 </B><DD>The client portion of the Update Server process that retrieves
96 configuration files from the <B>/usr/afs/etc</B> directory of the system
97 control machine. Do not run this process in cells that use the
98 international edition of AFS. (The name of the binary is
99 <B>upclient</B>, but the <B>etc</B> suffix distinguishes this process
100 from <B>upclientbin</B>.)
101 <P><DT><B><B>upserver</B>
102 </B><DD>The server portion of the Update Server process
103 <A NAME="IDX4499"></A>
104 <A NAME="IDX4500"></A>
105 <P><DT><B><B>vlserver</B>
106 </B><DD>The Volume Location (VL) Server process
107 <A NAME="IDX4501"></A>
108 <A NAME="IDX4502"></A>
110 <P><DT><B><B>-type</B>
111 </B><DD>Specifies the process's type. The acceptable values are:
114 <P><DT><B><B>cron</B>
115 </B><DD>Use this value for cron-type processes that the BOS Server starts only at
116 a defined daily or weekly time, rather than whenever it detects that the
117 process has terminated. AFS does not define any such processes by
118 default, but makes this value available for administrator use. Define
119 the time for command execution as part of the <B>-cmd</B> argument to the
120 <B>bos create</B> command.
122 </B><DD>Use this value only for the <B>fs</B> process, which combines the File
123 Server, Volume Server and Salvager processes. If one of the component
124 processes terminates, the BOS Server shuts down and restarts the processes in
125 the appropriate order.
126 <P><DT><B><B>simple</B>
127 </B><DD>Use this value for all processes listed as acceptable values to the
128 <B>-instance</B> argument, except for the <B>fs</B> process.
129 There are no interdependencies between simple processes, so the BOS Server can
130 stop and start them independently as necessary.
132 <P><DT><B><B>-cmd</B>
133 </B><DD>Specifies each command the BOS Server runs to start the process.
134 Specify no more than six commands (which can include the command's
135 options, in which case the entire string is surrounded by double quotes);
136 any additional commands are ignored.
137 <P>For a simple process, provide the complete pathname of the process's
138 binary file on the local disk (for example, <B>/usr/afs/bin/ptserver</B>
139 for the Protection Server). If including any of the initialization
140 command's options, surround the entire command in double quotes (<B>"
141 "</B>). The <B>upclient</B> process has a required argument, and
142 the commands for all other processes take optional arguments.
143 <A NAME="IDX4503"></A>
144 <P>For the <B>fs</B> process, provide the complete pathname of the local
145 disk binary file for each of the component processes:
146 <B>fileserver</B>, <B>volserver</B>, and <B>salvager</B>, in that
147 order. The standard binary directory is <B>/usr/afs/bin</B>.
148 If including any of an initialization command's options, surround the
149 entire command in double quotes (<B>" "</B>).
150 <A NAME="IDX4504"></A>
151 <P>For a <B>cron</B> process, provide two parameters:
152 <A NAME="IDX4505"></A>
154 <P><LI>The complete local disk pathname of either an executable file or a command
155 from one of the AFS suites (complete with all of the necessary
156 arguments). Surround this parameter with double quotes (<B>" "</B>)
157 if it contains spaces.
158 <P><LI>A specification of when the BOS Server executes the file or command
159 indicated by the first parameter. There are three acceptable
162 <P><LI>The string <B>now</B>, which directs the BOS Server to execute the
163 file or command immediately and only once. It is usually simpler to
164 issue the command directly or issue the <B>bos exec</B> command.
165 <P><LI>A time of day. The BOS Server executes the file or command daily at
166 the indicated time. Separate the hours and minutes with a colon
167 (<I>hh</I>:<I>MM</I>), and use either 24-hour format, or a value
168 in the range from <B>1:00</B> through <B>12:59</B> with
169 the addition of <B>am</B> or <B>pm</B>. For example, both
170 <B>14:30</B> and <B>"2:30 pm"</B> indicate 2:30 in
171 the afternoon. Surround this parameter with double quotes (<B>"
172 "</B>) if it contains a space.
173 <P><LI>A day of the week and time of day, separated by a space and surrounded
174 with double quotes (<B>" "</B>). The BOS Server executes the file
175 or command weekly at the indicated day and time. For the day, provide
176 either the whole name or the first three letters, all in lowercase letters
177 (<B>sunday</B> or <B>sun</B>, <B>thursday</B> or <B>thu</B>,
178 and so on). For the time, use the same format as when specifying the
182 <P><DT><B><B>-notifier</B>
183 </B><DD>Specifies the complete pathname on the local disk of a program that the
184 BOS Server invokes when the process terminates. The AFS distribution
185 does not include any notifier programs, but this argument is available for
186 administrator use. See the <B>Related Information</B>
188 <P><DT><B><B>-cell</B>
189 </B><DD>Names the cell in which to run the command. Do not combine this
190 argument with the <B>-localauth</B> flag. For more details, see the
191 introductory <B>bos</B> reference page.
192 <P><DT><B><B>-noauth</B>
193 </B><DD>Assigns the unprivileged identity <B>anonymous</B> to the
194 issuer. Do not combine this flag with the <B>-localauth</B>
195 flag. For more details, see the introductory <B>bos</B> reference
197 <P><DT><B><B>-localauth</B>
198 </B><DD>Constructs a server ticket using a key from the local
199 <B>/usr/afs/etc/KeyFile</B> file. The <B>bos</B> command
200 interpreter presents the ticket to the BOS Server during mutual
201 authentication. Do not combine this flag with the <B>-cell</B> or
202 <B>-noauth</B> options. For more details, see the introductory
203 <B>bos</B> reference page.
205 </B><DD>Prints the online help for this command. All other valid options
208 <P><STRONG>Examples</STRONG>
209 <P>The following command defines and starts the simple process
210 <B>kaserver</B> on the machine <B>fs3.abc.com</B>:
211 <PRE> % <B>bos create -server fs3.abc.com -instance kaserver -type simple</B> \
212 <B>-cmd /usr/afs/bin/kaserver</B>
215 <P>The following command defines and starts the simple process
216 <B>upclientbin</B> on the machine
217 <B>fs4.abc.com</B>. It references
218 <B>fs1.abc.com</B> as the source for updates to binary
219 files, checking for changes to the <B>/usr/afs/bin</B> directory every 120
221 <PRE> % <B>bos create -server fs4.abc.com -instance upclientbin -type simple</B> \
222 <B>-cmd "/usr/afs/bin/upclient fs1.abc.com -clear -t 120</B> \
226 <P>The following command creates the fs process <B>fs</B> on the machine
227 <B>fs4.abc.com</B>. Type the command on a single
229 <PRE> % <B>bos create -server fs4.abc.com -instance fs -type fs</B> \
230 <B>-cmd /usr/afs/bin/fileserver /usr/afs/bin/volserver</B> \
231 <B>/usr/afs/bin/salvager</B>
234 <P>The following command creates a <B>cron</B> process called
235 <B>userbackup</B> on the machine <B>fs5.abc.com</B>, so
236 that the BOS Server issues the indicated <B>vos backupsys</B> command each
237 day at 3:00 a.m. (the command creates a backup version of
238 every volume in the file system whose name begins with
239 <B>user</B>). Note that the issuer provides the complete pathname
240 to the <B>vos</B> command, includes the <B>-localauth</B> flag on it,
241 and types the entire <B>bos create</B> command on one line.
242 <PRE> % <B>bos create -server fs5.abc.com -instance userbackup -type cron</B> \
243 <B>-cmd "/usr/afs/bin/vos backupsys -prefix user -localauth" 03:00</B>
246 <P><STRONG>Privilege Required</STRONG>
247 <P>The issuer must be listed in the <B>/usr/afs/etc/UserList</B> file on
248 the machine named by the <B>-server</B> argument, or must be logged onto a
249 server machine as the local superuser <B>root</B> if the
250 <B>-localauth</B> flag is included.
251 <P><STRONG>Related Information</STRONG>
252 <P>If the <B>-notifier</B> argument is included when this command is used
253 to define and start a process, the BOS Server invokes the indicated
254 <I>notifier program</I> when the process exits. The intended use of
255 a notifier program is to inform administrators when a process exits
256 unexpectedly, but it can be used to perform any appropriate actions.
257 The following paragraphs describe the <B>bnode</B> and
258 <B>bnode_proc</B> structures in which the BOS Server records information
259 about the exiting process. The list of AFS commands related to this one
261 <P>The BOS Server constructs and sends on the standard output stream one
262 <B>bnode</B> and one <B>bnode_proc</B> structure for each exiting
263 process associated with the notifier program. It brackets each
264 structure with appropriate <TT>BEGIN</TT> and <TT>END</TT> statements
265 (<TT>BEGIN bnode</TT> and <TT>END bnode</TT>, <TT>BEGIN bnode_proc</TT>
266 and <TT>END bnode_proc</TT>), which immediately follow the preceding newline
267 character with no intervening spaces or other characters. If the
268 notifier program does not need information from a structure, it can scan ahead
269 in the input stream for the <TT>END</TT> statement.
270 <P>In general, each field in a structure is a string of ASCII text terminated
271 by the newline character. The format of the information within a
272 structure possibly varies slightly depending on the type of process associated
273 with the notifier program.
274 <P>The C code for the <B>bnode</B> and <B>bnode_proc</B> structures
275 follows. Note that the structures sent by the BOS Server do not
276 necessarily include all of the fields described here, because some are used
277 only for internal record keeping. The notifier process must robustly
278 handle the absence of expected fields, as well as the presence of unexpected
279 fields, on the standard input stream.
280 <P>For proper performance, the notifier program must continue processing the
281 input stream until it detects the end-of-file (EOF). The BOS Server
282 closes the standard input file descriptor to the notifier process when it has
283 completed delivery of the data, and it is the responsibility of the notifier
284 process to terminate properly.
285 <P><B>struct bnode contents</B>
287 struct bnode *next; /* next pointer in top-level's list */
288 char *name; /* instance name */
289 long nextTimeout; /* next time this guy should be awakened */
290 long period; /* period between calls */
291 long rsTime; /* time we started counting restarts */
292 long rsCount; /* count of restarts since rsTime */
293 struct bnode_type *type; /* type object */
294 struct bnode_ops *ops; /* functions implementing bnode class */
295 long procStartTime; /* last time a process was started */
296 long procStarts; /* number of process starts */
297 long lastAnyExit; /* last time a process exited for any reason */
298 long lastErrorExit; /* last time a process exited unexpectedly */
299 long errorCode; /* last exit return code */
300 long errorSignal; /* last proc terminating signal */
301 char *lastErrorName; /* name of proc that failed last */
302 short refCount; /* reference count */
303 short flags; /* random flags */
304 char goal; /* 1=running or 0=not running */
305 char fileGoal; /* same, but to be stored in file */
309 <P><B>format of struct bnode explosion</B>
310 <PRE> printf("name: %s\n",tp->name);
311 printf("rsTime: %ld\n", tp->rsTime);
312 printf("rsCount: %ld\n", tp->rsCount);
313 printf("procStartTime: %ld\n", tp->procStartTime);
314 printf("procStarts: %ld\n", tp->procStarts);
315 printf("lastAnyExit: %ld\n", tp->lastAnyExit);
316 printf("lastErrorExit: %ld\n", tp->lastErrorExit);
317 printf("errorCode: %ld\n", tp->errorCode);
318 printf("errorSignal: %ld\n", tp->errorSignal);
319 printf("lastErrorName: %s\n", tp->lastErrorName);
320 printf("goal: %d\n", tp->goal);
323 <P><B>struct bnode_proc contents</B>
324 <PRE> struct bnode_proc {
325 struct bnode_proc *next; /* next guy in top-level's list */
326 struct bnode *bnode; /* bnode creating this process */
327 char *comLine; /* command line used to start this process */
328 char *coreName; /* optional core file component name */
329 long pid; /* pid if created */
330 long lastExit; /* last termination code */
331 long lastSignal; /* last signal that killed this guy */
332 long flags; /* flags giving process state */
336 <P><B>format of struct bnode_proc explosion</B>
337 <PRE> printf("comLine: %s\n", tp->comLine);
338 printf("coreName: %s\n", tp->coreName);
339 printf("pid: %ld\n", tp->pid);
340 printf("lastExit: %ld\n", tp->lastExit);
341 printf("lastSignal: %ld\n", tp->lastSignal);
344 <P><A HREF="auarf016.htm#HDRBOSCONFIG">BosConfig</A>
345 <P><A HREF="auarf023.htm#HDRKEYFILE">KeyFile</A>
346 <P><A HREF="auarf035.htm#HDRUSERLIST">UserList</A>
347 <P><A HREF="auarf093.htm#HDRBOS_INTRO">bos</A>
348 <P><A HREF="auarf125.htm#HDRBUSERVER">buserver</A>
349 <P><A HREF="auarf129.htm#HDRFILESERVER">fileserver</A>
350 <P><A HREF="auarf198.htm#HDRKASERVER">kaserver</A>
351 <P><A HREF="auarf227.htm#HDRPTSERVER">ptserver</A>
352 <P><A HREF="auarf230.htm#HDRRUNNTP">runntp</A>
353 <P><A HREF="auarf232.htm#HDRSALVAGER">salvager</A>
354 <P><A HREF="auarf240.htm#HDRUPCLIENT">upclient</A>
355 <P><A HREF="auarf241.htm#HDRUPSERVER">upserver</A>
356 <P><A HREF="auarf249.htm#HDRVLSERVER">vlserver</A>
357 <P><A HREF="auarf251.htm#HDRVOLSERVER">volserver</A>
358 <P><A HREF="auarf256.htm#HDRVOS_BACKUPSYS">vos backupsys</A>
360 <HR><P ALIGN="center"> <A HREF="../index.htm"><IMG SRC="../books.gif" BORDER="0" ALT="[Return to Library]"></A> <A HREF="auarf002.htm#ToC"><IMG SRC="../toc.gif" BORDER="0" ALT="[Contents]"></A> <A HREF="auarf097.htm"><IMG SRC="../prev.gif" BORDER="0" ALT="[Previous Topic]"></A> <A HREF="#Top_Of_Page"><IMG SRC="../top.gif" BORDER="0" ALT="[Top of Topic]"></A> <A HREF="auarf099.htm"><IMG SRC="../next.gif" BORDER="0" ALT="[Next Topic]"></A> <A HREF="auarf284.htm#HDRINDEX"><IMG SRC="../index.gif" BORDER="0" ALT="[Index]"></A> <P>
361 <!-- Begin Footer Records ========================================== -->
363 <br>© <A HREF="http://www.ibm.com/">IBM Corporation 2000.</A> All Rights Reserved
365 <!-- End Footer Records ============================================ -->
366 <A NAME="Bot_Of_Page"></A>