doc-doxygen-20090531
[openafs.git] / doc / protocol / bos-spec.h
1 /*!
2
3         \page title AFS-3 Programmer's Reference: BOS Server Interface 
4
5 \author Edward R. Zayas 
6 Transarc Corporation 
7 \version 1.0 
8 \date 28 August 1991 11:58 Copyright 1991 Transarc Corporation All Rights
9 Reserved FS-00-D161 
10
11         \page chap1 Chapter 1: Overview 
12
13         \section sec1-1 Section 1.1: Introduction 
14
15 \par
16 One of the important duties of an AFS system administrator is to insure that
17 processes on file server machines are properly installed and kept running. The
18 BOS Server was written as a tool for assisting administrators in these tasks.
19 An instance of the BOS Server runs on each AFS server machine, and has the
20 following specific areas of responsibility: 
21 \li Definition of the set of processes that are to be run on the machine on
22 which a given BOS Server executes. This definition may be changed dynamically
23 by system administrators. Programs may be marked as continuously or
24 periodically runnable. 
25 \li Automatic startup and restart of these specified processes upon server
26 bootup and program failure. The BOS Server also responds to administrator
27 requests for stopping and starting one or more of these processes. In addition,
28 the BOS Server is capable of restarting itself on command. 
29 \li Collection of information regarding the current status, command line
30 parameters, execution history, and log files generated by the set of server
31 programs. 
32 \li Management of the security information resident on the machine on which the
33 BOS Server executes. Such information includes the list of administratively
34 privileged people associated with the machine and the set of AFS File Server
35 encryption keys used in the course of file service. 
36 \li Management of the cell configuration information for the server machine in
37 question. This includes the name of the cell in which the server resides, along
38 with the list and locations of the servers within the cell providing AFS
39 database services (e.g., volume location, authentication, protection).
40 Installation of server binaries on the given machine. The BOS Server allows
41 several "generations" of server software to be kept on its machine.
42 Installation of new software for one or more server agents is handled by the
43 BOS Server, as is "rolling back" to a previous version should it prove more
44 stable than the currently-installed image. 
45 \par
46 Execution of commands on the server machine. An administrator may execute
47 arbitrary unix commands on a machine running the BOS Server. 
48 \par
49 Unlike many other AFS server processes, the BOS Server does not maintain a
50 cell-wide, replicated database. It does, however, maintain several databases
51 used exclusively on every machine on which it runs. 
52
53         \section sec1-2 Section 1.2: Scope 
54
55 \par
56 This paper describes the design and structure of the AFS-3 BOS Server. The
57 scope of this work is to provide readers with a sufficiently detailed
58 description of the BOS Server so that they may construct client applications
59 that call the server's RPC interface routines. 
60
61         \section sec1-3 Section 1.3: Document Layout 
62
63 \par
64 The second chapter discusses various aspects of the BOS Server's architecture.
65 First, one of the basic concepts is examined, namely the bnode. Providing the
66 complete description of a program or set of programs to be run on the given
67 server machine, a bnode is the generic definitional unit for the BOS Server's
68 duties. After bnodes have been explained, the set of standard directories on
69 which the BOS Server depends is considered. Also, the set of well-known files
70 within these directories is explored. Their uses and internal formats are
71 presented. After these sections, a discussion of BOS Server restart times
72 follows. The BOS Server has special support for two commonly-used restart
73 occasions, as described by this section. Finally, the organization and behavior
74 of the bosserver program itself is presented. 
75 \par
76 The third and final chapter provides a detailed examination of the
77 programmer-visible BOS Server constants and structures, along with a full
78 specification of the API for the RPC-based BOS Server functionality. 
79
80         \section sec1-4 Section 1.4: Related Documents 
81
82 \par
83 This document is a member of a documentation suite providing programmer-level
84 specifications for the operation of the various AFS servers and agents, and the
85 interfaces they export, as well as the underlying RPC system they use to
86 communicate. The full suite of related AFS specification documents is listed
87 below: 
88 \li AFS-3 Programmer's Reference: Architectural Overview: This paper provides
89 an architectual overview of the AFS distributed file system, describing the
90 full set of servers and agents in a coherent way, illustrating their
91 relationships to each other and examining their interactions. 
92 \li AFS-3 Programmer's Reference: File Server/Cache Manager Interface: This
93 document describes the File Server and Cache Manager agents, which provide the
94 backbone file managment services for AFS. The collection of File Servers for a
95 cell supply centralized file storage for that site, and allow clients running
96 the Cache Manager component to acces those files in a high-performance, secure
97 fashion. 
98 \li AFS-3 Programmer's Reference:Volume Server/Volume Location Server
99 Interface: This document describes the services through which "containers" of
100 related user data are located and managed. 
101 \li AFS-3 Programmer's Reference: Protection Server Interface: This paper
102 describes the server responsible for mapping printable user names to and from
103 their internal AFS identifiers. The Protection Server also allows users to
104 create, destroy, and manipulate "groups" of users, which are suitable for
105 placement on ACLs. 
106 \li AFS-3 Programmer's Reference: Specification for the Rx Remote Procedure
107 Call Facility: This document specifies the design and operation of the remote
108 procedure call and lightweight process packages used by AFS. 
109 \par
110 In addition to these papers, the AFS 3.1 product is delivered with its own
111 user, administrator, installation, and command reference documents. 
112
113         \page chap2 Chapter 2: BOS Server Architecture 
114
115 \par
116 This chapter considers some of the architectual features of the AFS-3 BOS
117 Server. First, the basic organizational and functional entity employed by the
118 BOS Server, the bnode, is discussed. Next, the set of files with which the
119 server interacts is examined. The notion of restart times is then explained in
120 detail. Finally, the organization and components of the bosserver program
121 itself, which implements the BOS Server, are presented. 
122
123         \section sec2-1 Section 2.1: Bnodes 
124
125         \subsection sec2-1-1 Section 2.1.1: Overview 
126
127 \par
128 The information required to manage each AFS-related program running on a File
129 Server machine is encapsulated in a bnode object. These bnodes serve as the
130 basic building blocks for BOS Server services. Bnodes have two forms of
131 existence: 
132 \li On-disk: The BosConfig file (see Section 2.3.4 below) defines the set of
133 bnodes for which the BOS Server running on that machine will be responsible,
134 along with specifying other information such as values for the two restart
135 times. This file provides permanent storage (i.e., between bootups) for the
136 desired list of programs for that server platform. 
137 \li In-memory: The contents of the BosConfig file are parsed and internalized
138 by the BOS Server when it starts execution. The basic data for a particular
139 server program is placed into a struct bnode structure. 
140 \par
141 The initial contents of the BosConfig file are typically set up during system
142 installation. The BOS Server can be directed, via its RPC interface, to alter
143 existing bnode entries in the BosConfig file, add new ones, and delete old
144 ones. Typically, this file is never edited directly. 
145
146         \subsection sec2-1-2 Section 2.1.2: Bnode Classes 
147
148 \par
149 The descriptions of the members of the AFS server suite fall into three broad
150 classes of programs: 
151 \li Simple programs: This server class is populated by programs that simply
152 need to be kept running, and do not depend on other programs for correctness or
153 effectiveness. Examples of AFS servers falling into this category are the
154 Volume Location Server, Authentication Server, and Protection Server. Since its
155 members exhibit such straightforward behavior, this class of programs is
156 referred to as the simple class. 
157 \li Interrelated programs: The File Server program depends on two other
158 programs, and requires that they be executed at the appropriate times and in
159 the appropriate sequence, for correct operation. The first of these programs is
160 the Volume Server, which must be run concurrently with the File Server. The
161 second is the salvager, which repairs the AFS volume metadata on the server
162 partitions should the metadata become damaged. The salvager must not be run at
163 the same time as the File Server. In honor of the File Server trio that
164 inspired it, the class of programs consisting of groups of interrelated
165 processes is named the fs class. 
166 \li Periodic programs: Some AFS servers, such as the BackupServer, only need to
167 run every so often, but on a regular and well-defined basis. The name for this
168 class is taken from the unix tool that is typically used to define such regular
169 executions, namely the cron class. 
170 \par
171 The recognition and definition of these three server classes is exploited by
172 the BOS Server. Since all of the programs in a given class share certain common
173 characteristics, they may all utilize the same basic data structures to record
174 and manage their special requirements. Thus, it is not necessary to reimplement
175 all the operations required to satisfy the capabilities promised by the BOS
176 Server RPC interface for each and every program the BOS Server manages.
177 Implementing one set of operations for each server class is sufficient to
178 handle any and all server binaries to be run on the platform. 
179
180         \subsection sec2-1-3 Section 2.1.3: Per-Class Bnode Operations 
181
182 \par
183 As mentioned above, only one set of basic routines must be implemented for each
184 AFS server class. Much like Sun's VFS/vnode interface [8], providing a common
185 set of routines for interacting with a given file system, regardless of its
186 underlying implementation and semantics, the BOS Server defines a common vector
187 of operations for a class of programs to be run under the BOS Server's
188 tutelage. In fact, it was this standardized file system interface that inspired
189 the "bnode" name. 
190 \par
191 The BOS Server manipulates the process or processes that are described by each
192 bnode by invoking the proper functions in the appropriate order from the
193 operation vector for that server class. Thus, the BOS Server itself operates in
194 a class-independent fashion. This allows each class to take care of the special
195 circumstances associated with it, yet to have the BOS Server itself be totally
196 unaware of what special actions (if any) are needed for the class. This
197 abstraction also allows more server classes to be implemented without any
198 significant change to the BOS Server code itself. 
199 \par
200 There are ten entries in this standardized class function array. The purpose
201 and usage of each individual class function is described in detail in Section
202 3.3.5. Much like the VFS system, a collection of macros is also provided in
203 order to simplify the invocation of these functions. These macros are described
204 in Section 3.5. The ten function slots are named here for convenience: 
205 \li create() 
206 \li timeout() 
207 \li getstat() 
208 \li setstat() 
209 \li delete() 
210 \li procexit() 
211 \li getstring() 
212 \li getparm() 
213 \li restartp() 
214 \li hascore() 
215
216         \section sec2-2 Section 2.2: BOS Server Directories 
217
218 \par
219 The BOS Server expects the existence of the following directories on the local
220 disk of the platform on which it runs. These directories define where the
221 system binaries, log files, ubik databases, and other files lie. 
222 \li /usr/afs/bin: This directory houses the full set of AFS server binaries.
223 Such executables as bosserver, fileserver, vlserver, volserver, kaserver, and
224 ptserver reside here. 
225 \li /usr/afs/db: This directory serves as the well-known location on the
226 server's local disk for the ubik database replicas for this machine.
227 Specifically, the Authentication Server, Protection Server, and the Volume
228 Location Server maintain their local database images here. 
229 \li /usr/afs/etc: This directory hosts the files containing the security, cell,
230 and authorized system administrator list for the given machine. Specifically,
231 the CellServDB, KeyFile, License, ThisCell, and UserList files are stored here. 
232 \li /usr/afs/local: This directory houses the BosConfig file, which supplies
233 the BOS Server with the permanent set of bnodes to support. Also contained in
234 this directory are files used exclusively by the salvager. 
235 \li /usr/afs/logs: All of the AFS server programs that maintain log files
236 deposit them in this directory. 
237
238         \section sec2-3 Section 2.3: BOS Server Files 
239
240 \par
241 Several files, some mentioned above, are maintained on the server's local disk
242 and manipulated by the BOS Server. This section examines many of these files,
243 and describes their formats. 
244
245         \subsection sec2-3-1 Section 2.3.1: /usr/afs/etc/UserList 
246
247 \par
248 This file contains the names of individuals who are allowed to issue
249 "restricted" BOS Server commands (e.g., creating & deleting bnodes, setting
250 cell information, etc.) on the given hardware platform. The format is
251 straightforward, with one administrator name per line. If a cell grants joe and
252 schmoe these rights on a machine, that particular UserList will have the
253 following two lines: 
254 \n joe 
255 \n schmoe 
256
257         \subsection sec2-3-2 Section 2.3.2: /usr/afs/etc/CellServDB 
258
259 \par
260 This file identifies the name of the cell to which the given server machine
261 belongs, along with the set of machines on which its ubik database servers are
262 running. Unlike the CellServDB found in /usr/vice/etc on AFS client machines,
263 this file contains only the entry for the home cell. It shares the formatting
264 rules with the /usr/vice/etc version of CellServDB. The contents of the
265 CellServDB file used by the BOS Server on host grand.central.org are: 
266 \code
267 >grand.central.org      #DARPA clearinghouse cell
268 192.54.226.100          #grand.central.org
269 192.54.226.101          #penn.central.org
270 \endcode
271
272         \subsection sec2-3-3 Section 2.3.3: /usr/afs/etc/ThisCell 
273
274 \par
275 The BOS Server obtains its notion of cell membership from the ThisCell file in
276 the specified directory. As with the version of ThisCell found in /usr/vice/etc
277 on AFS client machines, this file simply contains the character string
278 identifying the home cell name. For any server machine in the grand.central.org
279 cell, this file contains the following: 
280 \code 
281 grand.central.org 
282 \endcode
283
284         \subsection sec2-3-4 Section 2.3.4: /usr/afs/local/BosConfig 
285
286 \par
287 The BosConfig file is the on-disk representation of the collection of bnodes
288 this particular BOS Server manages. The BOS Server reads and writes to this
289 file in the normal course of its affairs. The BOS Server itself, in fact,
290 should be the only agent that modifies this file. Any changes to BosConfig
291 should be carried out by issuing the proper RPCs to the BOS Server running on
292 the desired machine. 
293 \par
294 The following is the text of the BosConfig file on grand.central.org. A
295 discussion of the contents follows immediately afterwards. 
296 \code
297 restarttime 11 0 4 0 0 checkbintime 3 0 5 0 0 
298 bnode simple kaserver 1 parm /usr/afs/bin/kaserver 
299 end bnode simple ptserver 1 parm 
300 /usr/afs/bin/ptserver end bnode simple vlserver 1 
301 parm /usr/afs/bin/vlserver end bnode fs fs 1 parm 
302 /usr/afs/bin/fileserver parm /usr/afs/bin/volserver 
303 parm /usr/afs/bin/salvager end bnode simple runntp 
304 1 parm /usr/afs/bin/runntp -localclock transarc.com 
305 end bnode simple upserver 1 parm 
306 /usr/afs/bin/upserver end bnode simple 
307 budb_server 1 parm /usr/afs/bin/budb_server end 
308 bnode cron backup 1 parm 
309 /usr/afs/backup/clones/lib/backup.csh daily parm 
310 05:00 end 
311 \endcode
312
313 \par
314 The first two lines of this file set the system and new-binary restart times
315 (see Section 2.4, below). They are optional, with the default system restart
316 time being every Sunday at 4:00am and the new-binary restart time being 5:00am
317 daily. Following the reserved words restarttime and checkbintime are five
318 integers, providing the mask, day, hour, minute, and second values (in decimal)
319 for the restart time, as diagrammed below: 
320 \code
321 restarttime <mask> <day> <hour> <minute> 
322 <second> checkbintime <mask> <day> <hour> 
323 <minute> <second> 
324 \endcode
325
326 \par
327 The range of acceptable values for these fields is presented in Section 3.3.1.
328 In this example, the restart line specifies a (decimal) mask value of 11,
329 selecting the KTIME HOUR, KTIME MIN, and KTIME DAY bits. This indicates that
330 the hour, minute, and day values are the ones to be used when matching times.
331 Thus, this line requests that system restarts occur on day 0 (Sunday), hour 4
332 (4:00am), and minute 0 within that hour. 
333 \par
334 The sets of lines that follow define the individual bnodes for the particular
335 machine. The first line of the bnode definition set must begin with the
336 reserved word bnode, followed by the type name, the instance name, and the
337 initial bnode goal: 
338 \code
339 bnode <type_name> <instance_name> <goal_val> 
340 \endcode
341
342 \par
343 The <type name> and <instance name> fields are both character strings, and the
344 <goal val> field is an integer. Acceptable values for the <type name> are
345 simple, fs, and cron. Acceptable values for <goal val> are defined in Section
346 3.2.3, and are normally restricted to the integer values representing BSTAT
347 NORMAL and BSTAT SHUTDOWN. Thus, in the bnode line defining the Authentication
348 Server, it is declared to be of type simple, have instance name kaserver, and
349 have 1 (BSTAT NORMAL) as a goal (e.g., it should be brought up and kept
350 running). 
351 \par
352 Following the bnode line in the BosConfig file may be one or more parm lines.
353 These entries represent the command line parameters that will be used to invoke
354 the proper related program or programs. The entire text of the line after the
355 parm reserved word up to the terminating newline is stored as the command line
356 string. 
357 \code
358 parm <command_line_text> 
359 \endcode
360
361 \par
362 After the parm lines, if any, the reserved word end must appear alone on a
363 line, marking the end of an individual bnode definition. 
364
365         \subsection sec2-3-5 Section 2.3.5: /usr/afs/local/NoAuth 
366
367 \par
368 The appearance of this file is used to mark whether the BOS Server is to insist
369 on properly authenticated connections for its restricted operations or whether
370 it will allow any caller to exercise these commands. Not only is the BOS Server
371 affected by the presence of this file, but so are all of the bnodes objects the
372 BOS Server starts up. If /usr/afs/local/NoAuth is present, the BOS Server will
373 start all of its bnodes with the -noauth flag. 
374 \par
375 Completely unauthenticated AFS operation will result if this file is present
376 when the BOS Server starts execution. The file itself is typically empty. If
377 any data is put into the NoAuth file, it will be ignored by the system. 
378
379         \subsection sec2-3-6 Section 2.3.6: /usr/afs/etc/KeyFile 
380
381 \par
382 This file stores the set of AFS encryption keys used for file service
383 operations. The file follows the format defined by struct afsconf key and
384 struct afsconf keys in include file afs/keys.h. For the reader's convenience,
385 these structures are detailed below: 
386 \code
387 #define AFSCONF_MAXKEYS 8 
388 struct afsconf_key { 
389         long kvno; 
390         char key[8]; 
391 }; 
392 struct afsconf_keys { 
393         long nkeys; 
394         struct afsconf_key key[AFSCONF_MAXKEYS]; 
395 }; 
396 \endcode
397 \par
398 The first longword of the file reveals the number of keys that may be found
399 there, with a maximum of AFSCONF MAXKEYS (8). The keys themselves follow, each
400 preceded by its key version number. 
401 \par
402 All information in this file is stored in network byte order. Each BOS Server
403 converts the data to the appropriate host byte order befor storing and
404 manipulating it. 
405
406         \section sec2-4 Section 2.4: Restart Times 
407
408 \par
409 It is possible to manually start or restart any server defined within the set
410 of BOS Server bnodes from any AFS client machine, simply by making the
411 appropriate call to the RPC interface while authenticated as a valid
412 administrator (i.e., a principal listed in the UserList file on the given
413 machine). However, two restart situations merit the implementation of special
414 functionality within the BOS Server. There are two common occasions, occuring
415 on a regular basis, where the entire system or individual server programs
416 should be brought down and restarted: 
417 \par 
418 \b Complete \b system \b restart: To guard against the reliability and
419 performance problems caused by any core leaks in long-running programs, the
420 entire AFS system should be occasionally shut down and restarted periodically.
421 This action 'clears out' the memory system, and may result in smaller memory
422 images for these servers, as internal data structures are reinitialized back to
423 their starting sizes. It also allows AFS partitions to be regularly examined,
424 and salvaged if necessary. 
425 \par 
426 Another reason for performing a complete system restart is to commence
427 execution of a new release of the BOS Server itself. The new-binary restarts
428 described below do not restart the BOS Server if a new version of its software
429 has been installed on the machine. 
430 \par 
431 \b New-binary \b restarts: New server software may be installed at any time
432 with the assistance of the BOS Server. However, it is often not the case that
433 such software installations occur as a result of the discovery of an error in
434 the program or programs requiring immediate restart. On these occasions,
435 restarting the given processes in prime time so that the new binaries may begin
436 execution is counterproductive, causing system downtime and interfering with
437 user productivity. The system administrator may wish to set an off-peak time
438 when the server binaries are automatically compared to the running program
439 images, and restarts take place should the on-disk binary be more recent than
440 the currently running program. These restarts would thus minimize the resulting
441 service disruption. 
442 \par 
443 Automatically performing these restart functions could be accomplished by
444 creating cron-type bnodes that were defined to execute at the desired times.
445 However, rather than force the system administrator to create and supervise
446 such bnodes, the BOS Server supports the notion of an internal LWP thread with
447 the same effect (see Section 2.5.2). As part of the BosConfig file defined
448 above, the administrator may simply specify the values for the complete system
449 restart and new-binary restart times, and a dedicated BOS Server thread will
450 manage the restarts. 
451 \par 
452 Unless otherwise instructed, the BOS Server selects default times for the two
453 above restart times. A complete system restart is carried out every Sunday at
454 4:00am by default, and a new-binary restart is executed for each updated binary
455 at 5:00am every day. 
456
457         \section sec2-5 Section 2.5: The bosserver Process 
458
459         \subsection sec2-5-1 Section 2.5.1: Introduction 
460
461 \par
462 The user-space bosserver process is in charge of managing the AFS server
463 processes and software images, the local security and cell database files, and
464 allowing administrators to execute arbitrary programs on the server machine on
465 which it runs. It also implements the RPC interface defined in the bosint.xg
466 Rxgen definition file. 
467
468         \subsection sec2-5-2 Section 2.5.2: Threading 
469
470 \par
471 As with all the other AFS server agents, the BOS Server is a multithreaded
472 program. It is configured so that a minimum of two lightweight threads are
473 guaranteed to be allocated to handle incoming RPC calls to the BOS Server, and
474 a maximum of four threads are commissioned for this task. 
475 \par
476 In addition to these threads assigned to RPC duties, there is one other thread
477 employed by the BOS Server, the BozoDaemon(). This thread is responsible for
478 keeping track of the two major restart events, namely the system restart and
479 the new binary restart (see Section 2.4). Every 60 seconds, this thread is
480 awakened, at which time it checks to see if either deadline has occurred. If
481 the complete system restart is then due, it invokes internal BOS Server
482 routines to shut down the entire suite of AFS agents on that machine and then
483 reexecute the BOS Server binary, which results in the restart of all of the
484 server processes. If the new-binary time has arrived, the BOS Server shuts down
485 the bnodes for which binaries newer than those running are available, and then
486 invokes the new software. 
487 \par
488 In general, the following procedure is used when stopping and restarting
489 processes. First, the restart() operation defined for each bnode's class is
490 invoked via the BOP RESTART() macro. This allows each server to take any
491 special steps required before cycling its service. After that function
492 completes, the standard mechanisms are used to shut down each bnode's process,
493 wait until it has truly stopped its execution, and then start it back up again. 
494
495         \subsection sec2-5-3 Section 2.5.3: Initialization Algorithm 
496
497 \par
498 This section describes the procedure followed by the BOS Server from the time
499 when it is invoked to the time it has properly initialized the server machine
500 upon which it is executing. 
501 \par
502 The first check performed by the BOS Server is whether or not it is running as
503 root. It needs to manipulate local unix files and directories in which only
504 root has been given access, so it immediately exits with an error message if
505 this is not the case. The BOS Server's unix working directory is then set to be
506 /usr/afs/logs in order to more easily service incoming RPC requests to fetch
507 the contents of the various server log files at this location. Also, changing
508 the working directory in this fashion results in any core images dumped by the
509 BOS Server's wards will be left in /usr/afs/logs. 
510 \par
511 The command line is then inspected, and the BOS Server determines whether it
512 will insist on authenticated RPC connections for secure administrative
513 operations by setting up the /usr/afs/local/NoAuth file appropriately (see
514 Section 2.3.5). It initializes the underlying bnode package and installs the
515 three known bnode types (simple, fs, and cron). 
516 \par
517 After the bnode package is thus set up, the BOS Server ensures that the set of
518 local directories on which it will depend are present; refer to Section 2.2 for
519 more details on this matter. The license file in /usr/afs/etc/License is then
520 read to determine the number of AFS server machines the site is allowed to
521 operate, and whether the cell is allowed to run the NFS/AFS Translator
522 software. This file is typically obtained in the initial system installation,
523 taken from the installation tape. The BOS Server will exit unless this file
524 exists and is properly formatted. 
525 \par
526 In order to record its actions, any existing /usr/afs/logs/BosLog file is moved
527 to BosLog.old, and a new version is opened in append mode. The BOS Server
528 immediately writes a log entry concerning the state of the above set of
529 important directories. 
530 \par
531 At this point, the BOS Server reads the BosConfig file, which lists the set of
532 bnodes for which it will be responsible. It starts up the processes associated
533 with the given bnodes. Once accomplished, it invokes its internal system
534 restart LWP thread (covered in Section 2.5.2 above). 
535 \par
536 Rx initialization begins at this point, setting up the RPC infrastructure to
537 receive its packets on the AFSCONF NANNYPORT, UDP port 7007. The local cell
538 database is then read and internalized, followed by acquisition of the AFS
539 encryption keys. 
540 \par
541 After all of these steps have been carried out, the BOS Server has gleaned all
542 of the necessary information from its environemnt and has also started up its
543 wards. The final initialization action required is to start all of its listener
544 LWP threads, which are devoted to executing incoming requests for the BOS
545 Server RPC interface. 
546
547         \subsection sec2-5-4 Section 2.5.4: Command Line Switches 
548
549 \par
550 The BOS Server recognizes exactly one command line argument: -noauth. By
551 default, the BOS Server attempts to use authenticated RPC connections (unless
552 the /usr/afs/local/NoAuth file is present; see Section 2.3.5). The appearance
553 of the -noauth command line flag signals that this server incarnation is to use
554 unauthenticated connections for even those operations that are normally
555 restricted to system administrators. This switch is essential during the
556 initial AFS system installation, where the procedures followed to bootstrap AFS
557 onto a new machine require the BOS Server to run before some system databases
558 have been created. 
559
560         \page chap3 Chapter 3: BOS Server Interface 
561
562         \section sec3-1 Section 3.1: Introduction 
563
564 \par
565 This chapter documents the API for the BOS Server facility, as defined by the
566 bosint.xg Rxgen interface file and the bnode.h include file. Descriptions of
567 all the constants, structures, macros, and interface functions available to the
568 application programmer appear in this chapter. 
569
570         \section sec3-2 Section 3.2: Constants 
571
572 \par
573 This section covers the basic constant definitions of interest to the BOS
574 Server application programmer. These definitions appear in the bosint.h file,
575 automatically generated from the bosint.xg Rxgen interface file. Another file
576 is exported to the programmer, namely bnode.h. 
577 \par
578 Each subsection is devoted to describing constants falling into each of the
579 following categories: 
580 \li Status bits 
581 \li Bnode activity bits 
582 \li Bnode states 
583 \li Pruning server binaries 
584 \li Flag bits for struct bnode proc 
585 \par
586 One constant of general utility is BOZO BSSIZE, which defines the length in
587 characters of BOS Server character string buffers, including the trailing null.
588 It is defined to be 256 characters. 
589
590         \subsection sec3-2-1 Section 3.2.1: Status Bits 
591
592 \par
593 The following bit values are used in the flags field of struct bozo status, as
594 defined in Section 3.3.4. They record whether or not the associated bnode
595 process currently has a stored core file, whether the bnode execution was
596 stopped because of an excessive number of errors, and whether the mode bits on
597 server binary directories are incorrect. 
598
599 \par Name
600 BOZO HASCORE
601 \par Value
602 1
603 \par Description
604 Does this bnode have a stored core file?
605
606 \par Name
607 BOZO ERRORSTOP
608 \par Value
609 2
610 \par Description
611 Was this bnode execution shut down because of an excessive number of errors
612 (more than 10 in a 10 second period)?
613
614 \par Name
615 BOZO BADDIRACCESS
616 \par Value
617 3
618 \par Description
619 Are the mode bits on the /usr/afs directory and its descendants (etc, bin,
620 logs, backup, db, local, etc/KeyFile, etc/UserList) correctly set?
621
622         \subsection sec3-2-2 Section 3.2.2: Bnode Activity Bits 
623
624 \par
625 This section describes the legal values for the bit positions within the flags
626 field of struct bnode, as defined in Section 3.3.8. They specify conditions
627 related to the basic activity of the bnode and of the entities relying on it. 
628
629 \par Name
630 BNODE NEEDTIMEOUT
631 \par Value
632 0x01
633 \par Description
634 This bnode is utilizing the timeout mechanism for invoking actions on its
635 behalf.
636
637 \par Name
638 BNODE ACTIVE
639 \par Value
640 0x02
641 \par Description
642 The given bnode is in active service.
643
644 \par Name
645 BNODE WAIT
646 \par Value
647 0x04
648 \par Description
649 Someone is waiting for a status change in this bnode.
650
651 \par Name
652 BNODE DELETE
653 \par Value
654 0x08
655 \par Description
656 This bnode should be deleted at the earliest convenience.
657
658 \par Name
659 BNODE ERRORSTOP
660 \par Value
661 0x10
662 \par Description
663 This bnode decommissioned because of an excessive number of errors in its
664 associated unix processes. 
665
666         \subsection sec3-2-3 Section 3.2.3: Bnode States 
667
668 \par
669 The constants defined in this section are used as values within the goal and
670 fileGoal fields within a struct bnode. They specify either the current state of
671 the associated bnode, or the anticipated state. In particular, the fileGoal
672 field, which is the value stored on disk for the bnode, always represents the
673 desired state of the bnode, whether or not it properly reflects the current
674 state. For this reason, only BSTAT SHUTDOWN and BSTAT NORMAL may be used within
675 the fileGoal field. The goal field may take on any of these values, and
676 accurately reflects the current status of the bnode. 
677
678 \par Name
679 BSTAT SHUTDOWN
680 \par Value
681 0
682 \par Description
683 The bnode's execution has been (should be) terminated.
684
685 \par Name
686 BSTAT NORMAL
687 \par Value
688 1
689 \par Description
690 The bnode is (should be) executing normally.
691
692 \par Name
693 BSTAT SHUTTINGDOWN
694 \par Value
695 2
696 \par Description
697 The bnode is currently being shutdown; execution has not yet ceased.
698
699 \par Name
700 BSTAT STARTINGUP
701 \par Value
702 3
703 \par Description
704 The bnode execution is currently being commenced; execution has not yet begun.
705
706         \subsection sec3-2-4 Section 3.2.4: Pruning Server Binaries 
707
708 \par
709 The BOZO Prune() interface function, fully defined in Section 3.6.6.4, allows a
710 properly-authenticated caller to remove ("prune") old copies of server binaries
711 and core files managed by the BOS Server. This section identifies the legal
712 values for the flags argument to the above function, specifying exactly what is
713 to be pruned. 
714
715 \par Name
716 BOZO PRUNEOLD
717 \par Value
718 1
719 \par Description
720 Prune all server binaries with the *.OLD extension.
721
722 \par Name
723 BOZO PRUNEBAK
724 \par Value
725 2
726 \par Description
727 Prune all server binaries with the *.BAK extension.
728
729 \par Name
730 BOZO PRUNECORE
731 \par Value
732 3
733 \par Description
734 Prune core files.
735
736         \subsection sec3-2-5 Section 3.2.5: Flag Bits for struct bnode proc 
737
738 \par
739 This section specifies the acceptable bit values for the flags field in the
740 struct bnode proc structure, as defined in Section 3.3.9. Basically, they are
741 used to record whether or not the unix binary associated with the bnode has
742 ever been run, and if so whether it has ever exited. 
743
744 \par Name
745 BPROC STARTED
746 \par Value
747 1
748 \par Description
749 Has the associated unix process ever been started up?
750
751 \par Name
752 BPROC EXITED
753 \par Value
754 2
755 \par Description
756 Has the associated unix process ever exited?
757
758         \section sec3-3 Section 3.3: Structures 
759
760 \par
761 This section describes the major exported BOS Server data structures of
762 interest to application programmers. 
763
764         \subsection sec3-3-1 Section 3.3.1: struct bozo netKTime 
765
766 \par
767 This structure is used to communicate time values to and from the BOS Server.
768 In particular, the BOZO GetRestartTime() and BOZO SetRestartTime() interface
769 functions, described in Sections 3.6.2.5 and 3.6.2.6 respectively, use
770 parameters declared to be of this type. 
771 \par
772 Four of the fields in this structure specify the hour, minute, second, and day
773 of the event in question. The first field in the layout serves as a mask,
774 identifying which of the above four fields are to be considered when matching
775 the specified time to a given reference time (most often the current time). The
776 bit values that may be used for the mask field are defined in the afs/ktime.h
777 include file. For convenience, their values are reproduced here, including some
778 special cases at the end of the table. 
779
780 \par Name
781 KTIME HOUR
782 \par Value
783 0x01
784 \par Description
785 Hour should match.
786
787 \par Name
788 KTIME MIN
789 \par Value
790 0x02
791 \par Description
792 Minute should match.
793
794 \par Name
795 KTIME SEC
796 \par Value
797 0x04
798 \par Description
799 Second should match.
800
801 \par Name
802 KTIME DAY
803 \par Value
804 0x08
805 \par Description
806 Day should match.
807
808 \par Name
809 KTIME TIME
810 \par Value
811 0x07
812 \par Description
813 All times should match.
814
815 \par Name
816 KTIME NEVER
817 \par Value
818 0x10
819 \par Description
820 Special case: never matches.
821
822 \par Name
823 KTIME NOW
824 \par Value
825 0x20
826 \par Description
827 Special case: right now.
828
829 \n \b Fields 
830 \li int mask - A field of bit values used to specify which of the following
831 field are to be used in computing matches. 
832 \li short hour - The hour, ranging in value from 0 to 23. 
833 \li short min - The minute, ranging in value from 0 to 59. 
834 \li short sec - The second, ranging in value from 0 to 59. 
835 \li short day - Zero specifies Sunday, other days follow in order. 
836
837         \subsection sec3-3-2 Section 3.3.2: struct bozo key 
838
839 \par
840 This structure defines the format of an AFS encryption key, as stored in the
841 key file located at /usr/afs/etc/KeyFile at the host on which the BOS Server
842 runs. It is used in the argument list of the BOZO ListKeys() and BOZO AddKeys()
843 interface functions, as described in Sections 3.6.4.4 and 3.6.4.5 respectively. 
844 \n \b Fields 
845 \li char data[8] - The array of 8 characters representing an encryption key. 
846
847         \subsection sec3-3-3 Section 3.3.3: struct bozo keyInfo 
848
849 \par
850 This structure defines the information kept regarding a given AFS encryption
851 key, as represented by a variable of type struct bozo key, as described in
852 Section 3.3.2 above. A parameter of this type is used by the BOZO ListKeys()
853 function (described in Section 3.6.4.4). It contains fields holding the
854 associated key's modification time, a checksum on the key, and an unused
855 longword field. Note that the mod sec time field listed below is a standard
856 unix time value. 
857 \n \b Fields 
858 \li long mod sec - The time in seconds when the associated key was last
859 modified. 
860 \li long mod usec - The number of microseconds elapsed since the second
861 reported in the mod sec field. This field is never set by the BOS Server, and
862 should always contain a zero. 
863 \li unsigned long keyCheckSum - The 32-bit cryptographic checksum of the
864 associated key. A block of zeros is encrypted, and the first four bytes of the
865 result are placed into this field. 
866 \li long spare2 - This longword field is currently unused, and is reserved for
867 future use. 
868
869         \subsection sec3-3-4 Section 3.3.4: struct bozo status 
870
871 \par
872 This structure defines the layout of the information returned by the status
873 parameter for the interface function BOZO GetInstanceInfo(), as defined in
874 Section 3.6.2.3. The enclosed fields include such information as the temporary
875 and long-term goals for the process instance, an array of bit values recording
876 status information, start and exit times, and associated error codes and
877 signals. 
878 \n \b Fields 
879 \li long goal - The short-term goal for a process instance. Settings for this
880 field are BSTAT SHUTDOWN, BSTAT NORMAL, BSTAT SHUTTINGDOWN, and BSTAT
881 STARTINGUP. These values are fully defined in Section 3.2.3. 
882 \li long fileGoal - The long-term goal for a process instance. Accepted
883 settings are restricted to a subset of those used by the goal field above, as
884 explained in Section 3.2.3. 
885 \li long procStartTime - The last time the given process instance was started. 
886 \li long procStarts - The number of process starts executed on the behalf of
887 the given bnode. 
888 \li long lastAnyExit - The last time the process instance exited for any
889 reason. 
890 \li long lastErrorExit - The last time a process exited unexpectedly. 
891 \li long errorCode - The last exit's return code. 
892 \li long errorSignal - The last signal terminating the process. 
893 \li long flags - BOZO HASCORE, BOZO ERRORSTOP, and BOZO BADDIRACCESS. These
894 constants are fully defined in Section 3.2.1. 
895 \li long spare[] - Eight longword spares, currently unassigned and reserved for
896 future use. 
897
898         \subsection sec3-3-5 Section 3.3.5: struct bnode ops 
899
900 \par
901 This struture defines the base set of operations that each BOS Server bnode
902 type (struct bnode type, see Section 3.3.6 below) must implement. They are
903 called at the appropriate times within the BOS Server code via the BOP * macros
904 (see Section 3.5 and the individual descriptions therein). They allow each
905 bnode type to define its own behavior in response to its particular needs. 
906 \n \b Fields 
907 \li struct bnode *(*create)() - This function is called whenever a bnode of the
908 given type is created. Typically, this function will create bnode structures
909 peculiar to its own type and initialize the new records. Each type
910 implementation may take a different number of parameters. Note: there is no BOP
911 * macro defined for this particular function; it is always called directly. 
912 \li int (*timeout)() - This function is called whenever a timeout action must
913 be taken for this bnode type. It takes a single argument, namely a pointer to a
914 type-specific bnode structure. The BOP TIMEOUT macro is defined to simplify the
915 construction of a call to this function. 
916 \li int (*getstat)() - This function is called whenever a caller is attempting
917 to get status information concerning a bnode of the given type. It takes two
918 parameters, the first being a pointer to a type-specific bnode structure, and
919 the second being a pointer to a longword in which the desired status value will
920 be placed. The BOP GETSTAT macro is defined to simplify the construction of a
921 call to this function. 
922 \li int (*setstat)() - This function is called whenever a caller is attempting
923 to set the status information concerning a bnode of the given type. It takes
924 two parameters, the first being a pointer to a type-specific bnode structure,
925 and the second being a longword from which the new status value is obtained.
926 The BOP SETSTAT macro is defined to simplify the construction of a call to this
927 function. 
928 \li int (*delete)() - This function is called whenever a bnode of this type is
929 being deleted. It is expected that the proper deallocation and cleanup steps
930 will be performed here. It takes a single argument, a pointer to a
931 type-specific bnode structure. The BOP DELETE macro is defined to simplify the
932 construction of a call to this function. 
933 \li int (*procexit)() - This function is called whenever the unix process
934 implementing the given bnode exits. It takes two parameters, the first being a
935 pointer to a type-specific bnode structure, and the second being a pointer to
936 the struct bnode proc (defined in Section 3.3.9), describing that process in
937 detail. The BOP PROCEXIT macro is defined to simplify the construction of a
938 call to this function. 
939 \li int (*getstring)() - This function is called whenever the status string for
940 the given bnode must be fetched. It takes three parameters. The first is a
941 pointer to a type-specific bnode structure, the second is a pointer to a
942 character buffer, and the third is a longword specifying the size, in bytes, of
943 the above buffer. The BOP GETSTRING macro is defined to simplify the
944 construction of a call to this function. 
945 \li int (*getparm)() - This function is called whenever a particular parameter
946 string for the given bnode must be fetched. It takes four parameters. The first
947 is a pointer to a type-specific bnode structure, the second is a longword
948 identifying the index of the desired parameter string, the third is a pointer
949 to a character buffer to receive the parameter string, and the fourth and final
950 argument is a longword specifying the size, in bytes, of the above buffer. The
951 BOP GETPARM macro is defined to simplify the construction of a call to this
952 function. 
953 \li int (*restartp)() - This function is called whenever the unix process
954 implementing the bnode of this type is being restarted. It is expected that the
955 stored process command line will be parsed in preparation for the coming
956 execution. It takes a single argument, a pointer to a type-specific bnode
957 structure from which the command line can be located. The BOP RESTARTP macro is
958 defined to simplify the construction of a call to this function. 
959 \li int (*hascore)() - This function is called whenever it must be determined
960 if the attached process currently has a stored core file. It takes a single
961 argument, a pointer to a type-specific bnode structure from which the name of
962 the core file may be constructed. The BOP HASCORE macro is defined to simplify
963 the construction of a call to this function. 
964
965         \subsection sec3-3-6 Section 3.3.6: struct bnode type 
966
967 \par
968 This structure encapsulates the defining characteristics for a given bnode
969 type. Bnode types are placed on a singly-linked list within the BOS Server, and
970 are identified by a null-terminated character string name. They also contain
971 the function array defined in Section 3.3.5, that implements the behavior of
972 that object type. There are three predefined bnode types known to the BOS
973 Server. Their names are simple, fs, and cron. It is not currently possible to
974 dynamically define and install new BOS Server types. 
975 \n \b Fields 
976 \li struct bnode type *next - Pointer to the next bnode type definition
977 structure in the list. 
978 \li char *name - The null-terminated string name by which this bnode type is
979 identified. 
980 \li bnode ops *ops - The function array that defines the behavior of this given
981 bnode type. 
982
983         \subsection sec3-3-7 Section 3.3.7: struct bnode token 
984
985 \par
986 This structure is used internally by the BOS Server when parsing the command
987 lines with which it will start up process instances. This structure is made
988 externally visible should more types of bnode types be implemented. 
989 \n \b Fields 
990 \li struct bnode token *next - The next token structure queued to the list. 
991 \li char *key - A pointer to the token, or parsed character string, associated
992 with this entry. 
993
994         \subsection sec3-3-8 Section 3.3.8: struct bnode 
995
996 \par
997 This structure defines the essence of a BOS Server process instance. It
998 contains such important information as the identifying string name, numbers
999 concerning periodic execution on its behalf, the bnode's type, data on start
1000 and error behavior, a reference count used for garbage collection, and a set of
1001 flag bits. 
1002 \n \b Fields 
1003 \li char *name - The null-terminated character string providing the instance
1004 name associated with this bnode. 
1005 \li long nextTimeout - The next time this bnode should be awakened. At the
1006 specified time, the bnode's flags field will be examined to see if BNODE
1007 NEEDTIMEOUT is set. If so, its timeout() operation will be invoked via the BOP
1008 TIMEOUT() macro. This field will then be reset to the current time plus the
1009 value kept in the period field. 
1010 \li long period - This field specifies the time period between timeout calls.
1011 It is only used by processes that need to have periodic activity performed. 
1012 \li long rsTime - The time that the BOS Server started counting restarts for
1013 this process instance. 
1014 \li long rsCount - The count of the number of restarts since the time recorded
1015 in the rsTime field. 
1016 \li struct bnode type *type - The type object defining this bnode's behavior. 
1017 \li struct bnode ops *ops - This field is a pointer to the function array
1018 defining this bnode's basic behavior. Note that this is identical to the value
1019 of type->ops. 
1020 \par
1021 This pointer is duplicated here for convenience. All of the BOP * macros,
1022 discussed in Section 3.5, reference the bnode's operation array through this
1023 pointer. 
1024 \li long procStartTime - The last time this process instance was started
1025 (executed). 
1026 \li long procStarts - The number of starts (executions) for this process
1027 instance. 
1028 \li long lastAnyExit - The last time this process instance exited for any
1029 reason. 
1030 \li long lastErrorExit - The last time this process instance exited
1031 unexpectedly. 
1032 \li long errorCode - The last exit return code for this process instance. 
1033 \li long errorSignal - The last signal that terminated this process instance. 
1034 \li char *lastErrorName - The name of the last core file generated. 
1035 \li short refCount - A reference count maintained for this bnode. 
1036 \li short flags - This field contains a set of bit fields that identify
1037 additional status information for the given bnode. The meanings of the legal
1038 bit values, explained in Section 3.2.2, are: BOZO NEEDTIMEOUT, BOZO ACTIVE,
1039 BOZO WAIT, BOZO DELETE, and BOZO ERRORSTOP. 
1040 \li char goal - The current goal for the process instance. It may take on any
1041 of the values defined in Section 3.2.3, namely BSTAT SHUTDOWN, BSTAT NORMAL,
1042 BSTAT SHUTTINGDOWN, and BSTAT STARTINGUP. 
1043 \par
1044 This goal may be changed at will by an authorized caller. Such changes affect
1045 the current status of the process instance. See the description of the BOZO
1046 SetStatus() and BOZO SetTStatus() interface functions, defined in Sections
1047 3.6.3.1 and 3.6.3.2 respectively, for more details. 
1048 \li char fileGoal - This field is similar to goal, but represents the goal
1049 stored in the on-file BOS Server description of this process instance. As with
1050 the goal field, see functions the description of the BOZO SetStatus() and BOZO
1051 SetTStatus() interface functions defined in Sections 3.6.3.1 and 3.6.3.2
1052 respectively for more details. 
1053
1054         \subsection sec3-3-9 Section 3.3.9: struct bnode proc 
1055
1056 \par
1057 This structure defines all of the information known about each unix process the
1058 BOS Server is currently managing. It contains a reference to the bnode defining
1059 the process, along with the command line to be used to start the process, the
1060 optional core file name, the unix pid, and such things as a flag field to keep
1061 additional state information. The BOS Server keeps these records on a global
1062 singly-linked list. 
1063 \n \b Fields 
1064 \li struct bnode proc *next - A pointer to the BOS Server's next process
1065 record. 
1066 \li struct bnode *bnode - A pointer to the bnode creating and defining this
1067 unix process. 
1068 \li char *comLine - The text of the command line used to start this process. 
1069 \li char *coreName - An optional core file component name for this process. 
1070 \li long pid - The unix pid, if successfully created. 
1071 \li long lastExit - This field keeps the last termination code for this
1072 process. 
1073 \li long lastSignal - The last signal used to kill this process. 
1074 \li long flags - A set of bits providing additional process state. These bits
1075 are fully defined in Section 3.2.5, and are: BPROC STARTED and BPROC EXITED. 
1076
1077         \section sec3-4 Section 3.4: Error Codes 
1078
1079 \par
1080 This section covers the set of error codes exported by the BOS Server,
1081 displaying the printable phrases with which they are associated. 
1082
1083 \par Name
1084 BZNOTACTIVE
1085 \par Value
1086 (39424L)
1087 \par Description
1088 process not active.
1089
1090 \par Name
1091 BZNOENT
1092 \par Value
1093 (39425L)
1094 \par Description
1095 no such entity.
1096
1097 \par Name
1098 BZBUSY
1099 \par Value
1100 (38426L)
1101 \par Description
1102 can't do operation now.
1103
1104 \par Name
1105 BZEXISTS
1106 \par Value
1107 (29427L)
1108 \par Description
1109 entity already exists.
1110
1111 \par Name
1112 BZNOCREATE
1113 \par Value
1114 (39428)
1115 \par Description
1116 failed to create entity.
1117
1118 \par Name
1119 BZDOM
1120 \par Value
1121 (39429L)
1122 \par Description
1123 index out of range.
1124
1125 \par Name
1126 BZACCESS
1127 \par Value
1128 (39430L)
1129 \par Description
1130 you are not authorized for this operation.
1131
1132 \par Name
1133 BZSYNTAX
1134 \par Value
1135 (39431L)
1136 \par Description
1137 syntax error in create parameter.
1138
1139 \par Name
1140 BZIO
1141 \par Value
1142 (39432L)
1143 \par Description
1144 I/O error.
1145
1146 \par Name
1147 BZNET
1148 \par Value
1149 (39433L)
1150 \par Description
1151 network problem.
1152
1153 \par Name
1154 BZBADTYPE
1155 \par Value
1156 (39434L)
1157 \par Description
1158 unrecognized bnode type.
1159
1160         \section sec3-5 Section 3.5: Macros 
1161
1162 \par
1163 The BOS Server defines a set of macros that are externally visible via the
1164 bnode.h file. They are used to facilitate the invocation of the members of the
1165 struct bnode ops function array, which defines the basic operations for a given
1166 bnode type. Invocations appear throughout the BOS Server code, wherever bnode
1167 type-specific operations are required. Note that the only member of the struct
1168 bnode ops function array that does not have a corresponding invocation macro
1169 defined is create(), which is always called directly. 
1170
1171         \subsection sec3-5-1 Section 3.5.1: BOP TIMEOUT() 
1172
1173 \code
1174 #define BOP_TIMEOUT(bnode) \ 
1175 ((*(bnode)->ops->timeout)((bnode))) 
1176 \endcode
1177 \par
1178 Execute the bnode type-specific actions required when a timeout action must be
1179 taken. This macro takes a single argument, namely a pointer to a type-specific
1180 bnode structure. 
1181
1182         \subsection sec3-5-2 Section 3.5.2: BOP GETSTAT() 
1183
1184 \code
1185 #define BOP_GETSTAT(bnode, a) \ 
1186 ((*(bnode)->ops->getstat)((bnode),(a))) 
1187 \endcode
1188 \par
1189 Execute the bnode type-specific actions required when a caller is attempting to
1190 get status information concerning the bnode. It takes two parameters, the first
1191 being a pointer to a type-specific bnode structure, and the second being a
1192 pointer to a longword in which the desired status value will be placed. 
1193
1194         \subsection sec3-5-3 Section 3.5.3: BOP SETSTAT() 
1195
1196 \code
1197 #define BOP_SETSTAT(bnode, a) \ 
1198 ((*(bnode)->ops->setstat)((bnode),(a))) 
1199 \endcode
1200 \par
1201 Execute the bnode type-specific actions required when a caller is attempting to
1202 set the status information concerning the bnode. It takes two parameters, the
1203 first being a pointer to a type-specific bnode structure, and the second being
1204 a longword from which the new status value is obtained. 
1205
1206         \subsection sec3-5-4 Section 3.5.4: BOP DELETE() 
1207
1208 \code
1209 #define BOP_DELETE(bnode) \ 
1210 ((*(bnode)->ops->delete)((bnode))) 
1211 \endcode
1212 \par
1213 Execute the bnode type-specific actions required when a bnode is deleted. This
1214 macro takes a single argument, namely a pointer to a type-specific bnode
1215 structure. 
1216
1217         \subsection sec3-5-5 Section 3.5.5: BOP PROCEXIT() 
1218
1219 \code
1220 #define BOP_PROCEXIT(bnode, a) \ 
1221 ((*(bnode)->ops->procexit)((bnode),(a))) 
1222 \endcode
1223 \par
1224 Execute the bnode type-specific actions required whenever the unix process
1225 implementing the given bnode exits. It takes two parameters, the first being a
1226 pointer to a type-specific bnode structure, and the second being a pointer to
1227 the struct bnode proc (defined in Section 3.3.9), describing that process in
1228 detail. 
1229
1230         \subsection sec3-5-6 Section 3.5.6: BOP GETSTRING() 
1231
1232 \code
1233 #define BOP_GETSTRING(bnode, a, b) \ 
1234 ((*(bnode)->ops->getstring)((bnode),(a), (b))) 
1235 \endcode
1236 \par
1237 Execute the bnode type-specific actions required when the status string for the
1238 given bnode must be fetched. It takes three parameters. The first is a pointer
1239 to a type-specific bnode structure, the second is a pointer to a character
1240 buffer, and the third is a longword specifying the size, in bytes, of the above
1241 buffer. 
1242
1243         \subsection sec3-5-7 Section 3.5.7: BOP GETPARM() 
1244
1245 \code
1246 #define BOP_GETPARM(bnode, n, b, l) \ 
1247 ((*(bnode)->ops->getparm)((bnode),(n),(b),(l))) 
1248 \endcode
1249 \par
1250 Execute the bnode type-specific actions required when a particular parameter
1251 string for the given bnode must be fetched. It takes four parameters. The first
1252 is a pointer to a type-specific bnode structure, the second is a longword
1253 identifying the index of the desired parameter string, the third is a pointer
1254 to a character buffer to receive the parameter string, and the fourth and final
1255 argument is a longword specifying the size, in bytes, of the above buffer. 
1256
1257         \subsection sec3-5-8 Section 3.5.8: BOP RESTARTP() 
1258
1259 \code
1260 #define BOP_RESTARTP(bnode) \ 
1261 ((*(bnode)->ops->restartp)((bnode))) 
1262 \endcode
1263 \par
1264 Execute the bnode type-specific actions required when the unix process
1265 implementing the bnode of this type is restarted. It is expected that the
1266 stored process command line will be parsed in preparation for the coming
1267 execution. It takes a single argument, a pointer to a type-specific bnode
1268 structure from which the command line can be located. 
1269
1270         \subsection sec3-5-9 Section 3.5.9: BOP HASCORE() 
1271
1272 \code
1273 #define BOP_HASCORE(bnode) ((*(bnode)->ops->hascore)((bnode))) 
1274 \endcode
1275 \par
1276 Execute the bnode type-specific actions required when it must be determined
1277 whether or not the attached process currently has a stored core file. It takes
1278 a single argument, a pointer to a type-specific bnode structure from which the
1279 name of the core file may be constructed. 
1280
1281         \section sec3-6 Section 3.6: Functions 
1282
1283 \par
1284 This section covers the BOS Server RPC interface routines. They are generated
1285 from the bosint.xg Rxgen file. At a high level, these functions may be seen as
1286 belonging to seven basic classes: 
1287 \li Creating and removing process entries 
1288 \li Examining process information 
1289 \li Starting, stopping, and restarting processes 
1290 \li Security configuration 
1291 \li Cell configuration 
1292 \li Installing/uninstalling server binaries 
1293 \li Executing commands at the server 
1294 \par
1295 The following is a summary of the interface functions and their purpose,
1296 divided according to the above classifications: 
1297
1298 \par Creating & Removing Process Entries
1299
1300 \par Function Name
1301 BOZO CreateBnode()
1302 \par Description
1303 Create a process instance.
1304
1305 \par Function Name
1306 BOZO DeleteBnode() 
1307 \par Description
1308 Delete a process instance.
1309
1310 \par Examining Process Information
1311
1312 \par Function Name
1313 BOZO GetStatus()
1314 \par Description
1315 Get status information for the given process instance.
1316
1317 \par Function Name
1318 BOZO EnumerateInstance()
1319 \par Description
1320 Get instance name from the i'th bnode.
1321
1322 \par Function Name
1323 BOZO GetInstanceInfo()
1324 \par Description
1325 Get information on the given process instance.
1326
1327 \par Function Name
1328 BOZO GetInstanceParm()
1329 \par Description
1330 Get text of command line associated with the given process instance.
1331
1332 \par Function Name
1333 BOZO GetRestartTime()
1334 \par Description
1335 Get one of the BOS Server restart times.
1336
1337 \par Function Name
1338 BOZO SetRestartTime()
1339 \par Description
1340 Set one of the BOS Server restart times.
1341
1342 \par Function Name
1343 BOZOGetDates()
1344 \par Description
1345 Get the modification times for versions of a server binary file.
1346
1347 \par Function Name
1348 StartBOZO GetLog()
1349 \par Description
1350 Pass the IN params when fetching a BOS Server log file.
1351
1352 \par Function Name
1353 EndBOZO GetLog()
1354 \par Description
1355 Get the OUT params when fetching a BOS Server log file.
1356
1357 \par Function Name
1358 GetInstanceStrings() 
1359 \par Description
1360 Get strings related to a given process instance.
1361
1362 \par Starting, Stopping & Restarting Processes
1363
1364 \par Function Name
1365 BOZO SetStatus()
1366 \par Description
1367 Set process instance status and goal.
1368
1369 \par Function Name
1370 BOZO SetTStatus()
1371 \par Description
1372 Start all existing process instances.
1373
1374 \par Function Name
1375 BOZO StartupAll()
1376 \par Description
1377 Start all existing process instances.
1378
1379 \par Function Name
1380 BOZO ShutdownAll()
1381 \par Description
1382 Shut down all process instances.
1383
1384 \par Function Name
1385 BOZO RestartAll()
1386 \par Description
1387 Shut down, the restarted all process instances.
1388
1389 \par Function Name
1390 BOZO ReBozo()
1391 \par Description
1392 Shut down, then restart all process instances and the BOS Server itself.
1393
1394 \par Function Name
1395 BOZO Restart()
1396 \par Description
1397 Restart a given isntance.
1398
1399 \par Function Name
1400 BOZO WaitAll()
1401 \par Description
1402 Wait until all process instances have reached their goals. 
1403
1404 \par Security Configuration
1405
1406 \par Function Name
1407 BOZO AddSUser()
1408 \par Description
1409 Add a user to the UserList.
1410
1411 \par Function Name
1412 BOZO DeleteSUser()
1413 \par Description
1414 Delete a user from the UserList.
1415
1416 \par Function Name
1417 BOZO ListSUsers()
1418 \par Description
1419 Get the name of the user in a given position in the UserList file.
1420
1421 \par Function Name
1422 BOZO ListKeys()
1423 \par Description
1424 List info about the key at a given index in the key file.
1425
1426 \par Function Name
1427 BOZO AddKey()
1428 \par Description
1429 Add a key to the key file.
1430
1431 \par Function Name
1432 BOZO DeleteKey()
1433 \par Description
1434 Delete the entry for an AFS key.
1435
1436 \par Function Name
1437 BOZO SetNoAuthFlag() 
1438 \par Description
1439 Enable or disable authenticated call requirements.
1440
1441 \par Cell Configuration
1442
1443 \par Function Name
1444 BOZO GetCellName()
1445 \par Description
1446 Get the name of the cell to which the BOS Server belongs.
1447
1448 \par Function Name
1449 BOZO SetCellName()
1450 \par Description
1451 Set the name of the cell to which the BOS Server belongs.
1452
1453 \par Function Name
1454 BOZO GetCellHost()
1455 \par Description
1456 Get the name of a database host given its index.
1457
1458 \par Function Name
1459 BOZO AddCellHost()
1460 \par Description
1461 Add an entry to the list of database server hosts.
1462
1463 \par Function Name
1464 BOZO DeleteCellHost()
1465 \par Description
1466 Delete an entry from the list of database server hosts. 
1467
1468 \par Installing/Uninstalling Server Binaries
1469
1470 \par Function Name
1471 StartBOZO Install()
1472 \par Description
1473 Pass the IN params when installing a server binary.
1474
1475 \par Function Name
1476 EndBOZO Install()
1477 \par Description
1478 Get the OUT params when installing a server binary.
1479
1480 \par Function Name
1481 BOZO UnInstall()
1482 \par Description
1483 Roll back from a server binary installation.
1484
1485 \par Function Name
1486 BOZO Prune()
1487 \par Description
1488 Throw away old versions of server binaries and core files.
1489
1490 \par Executing Commands at the Server
1491
1492 \par Function Name
1493 BOZO Exec()
1494 \par Description
1495 Execute a shell command at the server.
1496
1497 \par
1498 All of the string parameters in these functions are expected to point to
1499 character buffers that are at least BOZO BSSIZE long. 
1500
1501         \subsection sec3-6-1 Section 3.6.1: Creating and Removing Processes 
1502
1503 \par
1504 The two interface routines defined in this section are used for creating and
1505 deleting bnodes, thus determining which processe instances the BOS Server must
1506 manage. 
1507
1508         \subsubsection sec3-6-1-1 Section 3.6.1.1: BOZO CreateBnode - Create a
1509 process instance 
1510
1511 \code
1512 int BOZO CreateBnode(IN struct rx connection *z conn, 
1513                         IN char *type, 
1514                         IN char *instance, 
1515                         IN char *p1, 
1516                         IN char *p2, 
1517                         IN char *p3, 
1518                         IN char *p4, 
1519                         IN char *p5, 
1520                         IN char *p6) 
1521 \endcode
1522 \par Description 
1523 This interface function allows the caller to create a bnode (process instance)
1524 on the server machine executing the routine. 
1525 \par
1526 The instance's type is declared to be the string referenced in the type
1527 argument. There are three supported instance type names, namely simple, fs, and
1528 cron (see Section 2.1 for a detailed examination of the types of bnodes
1529 available). 
1530 \par
1531 The bnode's name is specified via the instance parameter. Any name may be
1532 chosen for a BOS Server instance. However, it is advisable to choose a name
1533 related to the name of the actual binary being instantiated. There are eight
1534 well-known names already in common use, corresponding to the ASF system agents.
1535 They are as follows: 
1536 \li     kaserver for the Authentication Server. 
1537 \li     runntp for the Network Time Protocol Daemon (ntpd). 
1538 \li     ptserver for the Protection Server. 
1539 \li     upclient for the client portion of the UpdateServer, which brings over
1540 binary files from /usr/afs/bin directory and configuration files from
1541 /usr/afs/etc directory on the system control machine. 
1542 \li     upclientbin for the client portion of the UpdateServer, which uses the
1543 /usr/afs/bin directory on the binary distribution machine for this platform's
1544 CPU/operating system type. 
1545 \li     upclientetc for the client portion of the UpdateServer, which
1546 references the /usr/afs/etc directory on the system control machine. 
1547 \li     upserver for the server portion of the UpdateServer. 
1548 \li     vlserver for the Volume Location Server. 
1549 \par
1550 Up to six command-line strings may be communicated in this routine, residing in
1551 arguments p1 through p6. Different types of bnodes allow for different numbers
1552 of actual server processes to be started, and the command lines required for
1553 such instantiation are passed in this manner. 
1554 \par
1555 The given bnode's setstat() routine from its individual ops array will be
1556 called in the course of this execution via the BOP SETSTAT() macro. 
1557 \par
1558 The BOS Server will only allow individuals listed in its locally-maintained
1559 UserList file to create new instances. If successfully created, the new BOS
1560 Server instance will be appended to the BosConfig file kept on the machine's
1561 local disk. The UserList and BosConfig files are examined in detail in Sections
1562 2.3.1 and 2.3.4 respectively. 
1563 \par Error Codes 
1564 BZACCESS The caller is not authorized to perform this operation. 
1565 \n BZEXISTS The given instance already exists. 
1566 \n BZBADTYPE Illegal value provided in the type parameter. 
1567 \n BZNOCREATE Failed to create desired entry. 
1568
1569         \subsubsection sec3-6-1-2 Section 3.6.1.2: BOZO DeleteBnode - Delete a
1570 process instance 
1571
1572 \code
1573 int BOZO DeleteBnode(IN struct rx connection *z conn, IN char *instance) 
1574 \endcode
1575 \par Description 
1576 This routine deletes the BOS Server bnode whose name is specified by the
1577 instance parameter. If an instance with that name does not exist, this
1578 operation fails. Similarly, if the process or processes associated with the
1579 given bnode have not been shut down (see the descriptions for the BOZO
1580 ShutdownAll() and BOZO ShutdownAll() interface functions), the operation also
1581 fails. 
1582 \par
1583 The given bnode's setstat() and delete() routines from its individual ops array
1584 will be called in the course of this execution via the BOP SETSTAT() and BOP
1585 DELETE() macros. 
1586 \par
1587 The BOS Server will only allow individuals listed in its locally-maintained
1588 UserList file to delete existing instances. If successfully deleted, the old
1589 BOS Server instance will be removed from the BosConfig file kept on the
1590 machine's local disk. 
1591 \par Error Codes 
1592 BZACCESS The caller is not authorized to perform this operation. 
1593 \n BZNOENT The given instance name not registered with the BOS Server. 
1594 \n BZBUSY The process(es) associated with the given instance are still active
1595 (i.e., a shutdown has not yet been performed or has not yet completed). 
1596
1597         \subsection sec3-6-2 Section 3.6.2: Examining Process Information 
1598
1599 \par
1600 This section describes the ten interface functions that collectively allow
1601 callers to obtain and modify the information stored by the BOS Server to
1602 describe the set of process that it manages. Among the operations supported by
1603 the functions examined here are getting and setting status information,
1604 obtaining the instance parameters, times, and dates, and getting the text of
1605 log files on the server machine 
1606
1607         \subsubsection sec3-6-2-1 Section 3.6.2.1: BOZO GetStatus - Get status
1608 information for the given process instance 
1609
1610 \code
1611 int BOZO GetStatus(IN struct rx connection *z conn, 
1612                         IN char *instance, 
1613                         OUT long *intStat, 
1614                         OUT char **statdescr) 
1615 \endcode
1616 \par Description 
1617 This interface function looks up the bnode for the given process instance and
1618 places its numerical status indicator into intStat and its status string (if
1619 any) into a buffer referenced by statdescr. 
1620 \par
1621 The set of values that may be returned in the intStat argument are defined
1622 fully in Section 3.2.3. Briefly, they are BSTAT STARTINGUP, BSTAT NORMAL, BSTAT
1623 SHUTTINGDOWN, and BSTAT SHUTDOWN. 
1624 \par
1625 A buffer holding BOZO BSSIZE (256) characters is allocated, and statdescr is
1626 set to point to it. Not all bnodes types implement status strings, which are
1627 used to provide additional status information for the class. An example of one
1628 bnode type that does define these strings is fs, which exports the following
1629 status strings: 
1630 \li  "file server running" 
1631 \li  "file server up; volser down" 
1632 \li  "salvaging file system" 
1633 \li  "starting file server" 
1634 \li  "file server shutting down" 
1635 \li  "salvager shutting down" 
1636 \li  "file server shut down" 
1637 \par
1638 The given bnode's getstat() routine from its individual ops array will be
1639 called in the course of this execution via the BOP GETSTAT() macro. 
1640 \par Error Codes 
1641 BZNOENT The given process instance is not registered with the BOS Server. 
1642
1643         \subsubsection sec3-6-2-2 Section 3.6.2.2: BOZO EnumerateInstance - Get
1644 instance name from i'th bnode 
1645
1646 \code
1647 int BOZO EnumerateInstance(IN struct rx connection *z conn, 
1648                                 IN long instance, 
1649                                 OUT char **iname); 
1650 \endcode
1651 \par Description 
1652 This routine will find the bnode describing process instance number instance
1653 and return that instance's name in the buffer to which the iname parameter
1654 points. This function is meant to be used to enumerate all process instances at
1655 a BOS Server. The first legal instance number value is zero, which will return
1656 the instance name from the first registered bnode. Successive values for
1657 instance will return information from successive bnodes. When all bnodes have
1658 been thus enumerated, the BOZO EnumerateInstance() function will return BZDOM,
1659 indicating that the list of bnodes has been exhausted. 
1660 \par Error Codes 
1661 BZDOM The instance number indicated in the instance parameter does not exist. 
1662
1663         \subsubsection sec3-6-2-3 Section 3.6.2.3: BOZO GetInstanceInfo - Get
1664 information on the given process instance 
1665
1666 \code
1667 int BOZO GetInstanceInfo(IN struct rx connection *z conn, 
1668                                 IN char *instance, 
1669                                 OUT char **type, 
1670                                 OUT struct bozo status *status) 
1671 \endcode
1672 \par Description 
1673 Given the string name of a BOS Server instance, this interface function returns
1674 the type of the instance and its associated status descriptor. The set of
1675 values that may be placed into the type parameter are simple, fs, and cron (see
1676 Section 2.1 for a detailed examination of the types of bnodes available). The
1677 status structure filled in by the call includes such information as the goal
1678 and file goals, the process start time, the number of times the process has
1679 started, exit information, and whether or not the process has a core file. 
1680 \par Error Codes 
1681 BZNOENT The given process instance is not registered with the BOS Server. 
1682
1683         \subsubsection sec3-6-2-4 Section 3.6.2.4: BOZO GetInstanceParm - Get
1684 text of command line associated with the given process instance 
1685
1686 \code
1687 int BOZO GetInstanceParm(IN struct rx connection *z conn, 
1688                                 IN char *instance, 
1689                                 IN long num, 
1690                                 OUT char **parm) 
1691 \endcode
1692 \par Description 
1693 Given the string name of a BOS Server process instance and an index identifying
1694 the associated command line of interest, this routine returns the text of the
1695 desired command line. The first associated command line text for the instance
1696 may be acquired by setting the index parameter, num, to zero. If an index is
1697 specified for which there is no matching command line stored in the bnode, then
1698 the function returns BZDOM. 
1699 \par Error Codes 
1700 BZNOENT The given process instance is not registered with the BOS Server. 
1701 \n BZDOM There is no command line text associated with index num for this
1702 bnode. 
1703
1704         \subsubsection sec3-6-2-5 Section 3.6.2.5: BOZO GetRestartTime - Get
1705 one of the BOS Server restart times 
1706
1707 \code
1708 int BOZO GetRestartTime(IN struct rx connection *z conn, 
1709                         IN long type, 
1710                         OUT struct bozo netKTime *restartTime) 
1711 \endcode
1712 \par Description 
1713 The BOS Server maintains two different restart times, for itself and all server
1714 processes it manages, as described in Section 2.4. Given which one of the two
1715 types of restart time is desired, this routine fetches the information from the
1716 BOS Server. The type argument is used to specify the exact restart time to
1717 fetch. If type is set to one (1), then the general restart time for all agents
1718 on the machine is fetched. If type is set to two (2), then the new-binary
1719 restart time is returned. A value other than these two for the type parameter
1720 results in a return value of BZDOM. 
1721 \par Error Codes 
1722 BZDOM All illegal value was passed in via the type parameter. 
1723
1724         \subsubsection sec3-6-2-6 Section 3.6.2.6: BOZO SetRestartTime - Set
1725 one of the BOS Server restart times 
1726
1727 \code
1728 int BOZO SetRestartTime(IN struct rx connection *z conn, 
1729                         IN long type, 
1730                         IN struct bozo netKTime *restartTime) 
1731 \endcode
1732 \par Description 
1733 This function is the inverse of the BOZO GetRestartTime() interface routine
1734 described in Section 3.6.2.5 above. Given the type of restart time and its new
1735 value, this routine will set the desired restart time at the BOS Server
1736 receiving this call. The values for the type parameter are identical to those
1737 used by BOZO GetRestartTime(), namely one (1) for the general restart time and
1738 two (2) for the new-binary restart time. 
1739 \par
1740 The BOS Server will only allow individuals listed in its locally-maintained
1741 UserList file to set its restart times. 
1742 \par Error Codes 
1743 BZACCESS The caller is not authorized to perform this operation. 
1744 \n BZDOM All illegal value was passed in via the type parameter. 
1745
1746         \subsubsection sec3-6-2-7 Section 3.6.2.7: BOZO GetDates - Get the
1747 modification times for versions of a server binary file 
1748
1749 \code
1750 int BOZO GetDates(IN struct rx connection *z conn, 
1751                         IN char *path, 
1752                         OUT long *newtime, 
1753                         OUT long *baktime, 
1754                         OUT long *oldtime) 
1755 \endcode
1756 \par Description 
1757 Given a fully-qualified pathname identifying the particular server binary to
1758 examine in the path argument, this interface routine returns the modification
1759 time of that file, along with the modification times for the intermediate
1760 (.BAK) and old (.OLD) versions. The above-mentioned times are deposited into
1761 the newtime, baktime and oldtime arguments. Any one or all of the reported
1762 times may be set to zero, indicating that the associated file does not exist. 
1763 \par Error Codes 
1764 ---None. 
1765
1766         \subsubsection sec3-6-2-8 Section 3.6.2.8: StartBOZO GetLog - Pass the
1767 IN params when fetching a BOS Server log file 
1768
1769 \code
1770 int BOZO StartGetLog(IN struct rx connection *z conn, IN char *name) 
1771 \endcode
1772 \par Description 
1773 The BOZO GetLog() function defined in the BOS Server Rxgen interface file is
1774 used to acquire the contents of the given log file from the machine processing
1775 the call. It is defined to be a streamed function, namely one that can return
1776 an arbitrary amount of data. For full details on the definition and use of
1777 streamed functions, please refer to the Streamed Function Calls section in [4]. 
1778 \par
1779 This function is created by Rxgen in response to the BOZO GetLog() interface
1780 definition in the bosint.xg file. The StartBOZO GetLog() routine handles
1781 passing the IN parameters of the streamed call to the BOS Server. Specifically,
1782 the name parameter is used to convey the string name of the desired log file.
1783 For the purposes of opening the specified files at the machine being contacted,
1784 the current working directory for the BOS Server is considered to be
1785 /usr/afs/logs. If the caller is included in the locally-maintained UserList
1786 file, any pathname may be specified in the name parameter, and the contents of
1787 the given file will be fetched. All other callers must provide a string that
1788 does not include the slash character, as it might be used to construct an
1789 unauthorized request for a file outside the /usr/afs/logs directory. 
1790 \par Error Codes 
1791 RXGEN CC MARSHAL The transmission of the GetLog() IN parameters failed. This
1792 and all rxgen constant definitions are available from the rxgen consts.h
1793 include file. 
1794
1795         \subsubsection sec3-6-2-9 Section 3.6.2.9: EndBOZO GetLog - Get the OUT
1796 params when fetching a BOS Server log file 
1797
1798 \code
1799 int BOZO EndGetLog(IN struct rx connection *z conn) 
1800 \endcode
1801 \par Description 
1802 This function is created by Rxgen in response to the BOZO GetLog() interface
1803 definition in the bosint.xg file. The EndBOZO GetLog() routine handles the
1804 recovery of the OUT parameters for this interface call (of which there are
1805 none). The utility of such functions is often the value they return. In this
1806 case, however, EndBOZO GetLog() always returns success. Thus, it is not even
1807 necessary to invoke this particular function, as it is basically a no-op. 
1808 \par Error Codes 
1809 ---Always returns successfully. 
1810
1811         \subsubsection sec3-6-2-10 Section 3.6.2.10: BOZO GetInstanceStrings -
1812 Get strings related to a given process instance 
1813
1814 \code
1815 int BOZO GetInstanceStrings(IN struct rx connection *z conn, 
1816 IN char *instance, 
1817 OUT char **errorName, 
1818 OUT char **spare1, 
1819 OUT char **spare2, 
1820 OUT char **spare3) 
1821 \endcode
1822 \par Description 
1823 This interface function takes the string name of a BOS Server instance and
1824 returns a set of strings associated with it. At the current time, there is only
1825 one string of interest returned by this routine. Specifically, the errorName
1826 parameter is set to the error string associated with the bnode, if any. The
1827 other arguments, spare1 through spare3, are set to the null string. Note that
1828 memory is allocated for all of the OUT parameters, so the caller should be
1829 careful to free them once it is done. 
1830 \par Error Codes 
1831 BZNOENT The given process instance is not registered with the BOS Server. 
1832
1833         \subsection sec3-6-3 Section 3.6.3: Starting, Stopping, and Restarting
1834 Processes 
1835
1836 \par
1837 The eight interface functions described in this section allow BOS Server
1838 clients to manipulate the execution of the process instances the BOS Server
1839 controls. 
1840
1841         \subsubsection sec3-6-3-1 Section 3.6.3.1: BOZO SetStatus - Set process
1842 instance status and goal 
1843
1844 \code
1845 int BOZO SetStatus(IN struct rx connection *z conn, 
1846                         IN char *instance, 
1847                         IN long status) 
1848 \endcode
1849 \par Description 
1850 This routine sets the actual status field, as well as the "file goal", of the
1851 given instance to the value supplied in the status parameter. Legal values for
1852 status are taken from the set described in Section 3.2.3, specifically BSTAT
1853 NORMAL and BSTAT SHUTDOWN. For more information about these constants (and
1854 about goals/file goals), please refer to Section 3.2.3. 
1855 \par
1856 The given bnode's setstat() routine from its individual ops array will be
1857 called in the course of this execution via the BOP SETSTAT() macro. 
1858 \par
1859 The BOS Server will only allow individuals listed in its locally-maintained
1860 UserList file to perform this operation. If successfully modified, the BOS
1861 Server bnode defining the given instance will be written out to the BosConfig
1862 file kept on the machine's local disk. 
1863 \par Error Codes 
1864 BZACCESS The caller is not authorized to perform this operation. 
1865 \n BZNOENT The given instance name not registered with the BOS Server. 
1866
1867         \subsubsection sec3-6-3-2 Section 3.6.3.2: BOZO SetTStatus -
1868 Temporarily set process instance status and goal 
1869
1870 \code
1871 int BOZO SetTStatus(IN struct rx connection *z conn, 
1872                         IN char *instance, 
1873                         IN long status) 
1874 \endcode
1875 \par Description 
1876 This interface routine is much like the BOZO SetStatus(), defined in Section
1877 3.6.3.1 above, except that its effect is to set the instance status on a
1878 temporary basis. Specifically, the status field is set to the given status
1879 value, but the "file goal" field is not changed. Thus, the instance's stated
1880 goal has not changed, just its current status. 
1881 \par
1882 The given bnode's setstat() routine from its individual ops array will be
1883 called in the course of this execution via the BOP SETSTAT() macro. 
1884 \par
1885 The BOS Server will only allow individuals listed in its locally-maintained
1886 UserList file to perform this operation. If successfully modified, the BOS
1887 Server bnode defining the given instance will be written out to the BosConfig
1888 file kept on the machine's local disk. 
1889 \par Error Codes 
1890 BZACCESS The caller is not authorized to perform this operation. 
1891 \n BZNOENT The given instance name not registered with the BOS Server. 
1892
1893         \subsubsection sec3-6-3-3 Section 3.6.3.3: BOZO StartupAll - Start all
1894 existing process instances 
1895
1896 \code
1897 int BOZO StartupAll(IN struct rx connection *z conn) 
1898 \endcode
1899 \par Description 
1900 This interface function examines all bnodes and attempts to restart all of
1901 those that have not been explicitly been marked with the BSTAT SHUTDOWN file
1902 goal. Specifically, BOP SETSTAT() is invoked, causing the setstat() routine
1903 from each bnode's ops array to be called. The bnode's flags field is left with
1904 the BNODE ERRORSTOP bit turned off after this call. 
1905 \par
1906 The given bnode's setstat() routine from its individual ops array will be
1907 called in the course of this execution via the BOP SETSTAT() macro. 
1908 \par
1909 The BOS Server will only allow individuals listed in its locally-maintained
1910 UserList file to start up bnode process instances. 
1911 \par Error Codes 
1912 BZACCESS The caller is not authorized to perform this operation. 
1913
1914         \subsubsection sec3-6-3-4 Section 3.6.3.4: BOZO ShutdownAll - Shut down
1915 all process instances 
1916
1917 \code
1918 int BOZO ShutdownAll(IN struct rx connection *z conn) 
1919 \endcode
1920 \par Description 
1921 This interface function iterates through all bnodes and attempts to shut them
1922 all down. Specifically, the BOP SETSTAT() is invoked, causing the setstat()
1923 routine from each bnode's ops array to be called, setting that bnode's goal
1924 field to BSTAT SHUTDOWN. 
1925 \par 
1926 The given bnode's setstat() routine from its individual ops array will be
1927 called in the course of this execution via the BOP SETSTAT() macro. 
1928 \par
1929 The BOS Server will only allow individuals listed in its locally-maintained
1930 UserList file to perform this operation. 
1931 \par Error Codes 
1932 BZACCESS The caller is not authorized to perform this operation. 
1933
1934         \subsubsection sec3-6-3-5 Section 3.6.3.5: BOZO RestartAll - Shut down,
1935 then restart all process instances 
1936
1937 \code
1938 int BOZO RestartAll(IN struct rx connection *z conn) 
1939 \endcode
1940 \par Description 
1941 This interface function shuts down every BOS Server process instance, waits
1942 until the shutdown is complete (i.e., all instances are registered as being in
1943 state BSTAT SHUTDOWN), and then starts them all up again. While all the
1944 processes known to the BOS Server are thus restarted, the invocation of the BOS
1945 Server itself does not share this fate. For simulation of a truly complete
1946 machine restart, as is necessary when an far-reaching change to a database file
1947 has been made, use the BOZO ReBozo() interface routine defined in Section
1948 3.6.3.6 below. 
1949 \par
1950 The given bnode's getstat() and setstat() routines from its individual ops
1951 array will be called in the course of this execution via the BOP GETSTAT() and
1952 BOP SETSTAT() macros. 
1953 \par
1954 The BOS Server will only allow individuals listed in its locally-maintained
1955 UserList file to restart bnode process instances. 
1956 \par Error Codes 
1957 BZACCESS The caller is not authorized to perform this operation. 
1958
1959         \subsubsection sec3-6-3-6 Section 3.6.3.6: BOZO ReBozo - Shut down,
1960 then restart all process instances and the BOS Server itself 
1961
1962 \code
1963 int BOZO ReBozo(IN struct rx connection *z conn) 
1964 \endcode
1965 \par Description 
1966 This interface routine is identical to the BOZO RestartAll() call, defined in
1967 Section 3.6.3.5 above, except for the fact that the BOS Server itself is
1968 restarted in addition to all the known bnodes. All of the BOS Server's open
1969 file descriptors are closed, and the standard BOS Server binary image is
1970 started via execve(). 
1971 \par
1972 The given bnode's getstat() and setstat() routines from its individual ops
1973 array will be called in the course of this execution via the BOP GETSTAT() and
1974 BOP SETSTAT() macros. 
1975 \par
1976 The BOS Server will only allow individuals listed in its locally-maintained
1977 UserList file to restart bnode process instances. 
1978 \par Error Codes 
1979 BZACCESS The caller is not authorized to perform this operation. 
1980
1981         \subsubsection sec3-6-3-7 Section 3.6.3.7: BOZO Restart - Restart a
1982 given process instance 
1983
1984 \code
1985 int BOZO Restart(IN struct rx connection *z conn, IN char *instance) 
1986 \endcode
1987 \par Description 
1988 This interface function is used to shut down and then restart the process
1989 instance identified by the instance string passed as an argument. 
1990 \par
1991 The given bnode's getstat() and setstat() routines from its individual ops
1992 array will be called in the course of this execution via the BOP GETSTAT() and
1993 BOP SETSTAT() macros. 
1994 \par
1995 The BOS Server will only allow individuals listed in its locally-maintained
1996 UserList file to restart bnode process instances. 
1997 \par Error Codes 
1998 BZACCESS The caller is not authorized to perform this operation. 
1999 \n BZNOENT The given instance name not registered with the BOS Server. 
2000
2001         \subsubsection sec3-6-3-8 Section 3.6.3.8: BOZO WaitAll - Wait until
2002 all process instances have reached their goals 
2003
2004 \code
2005 int BOZO WaitAll(IN struct rx connection *z conn) 
2006 \endcode
2007 \par Description 
2008 This interface function is used to synchronize with the status of the bnodes
2009 managed by the BOS Server. Specifically, the BOZO WaitAll() call returns when
2010 each bnode's current status matches the value in its short-term goal field. For
2011 each bnode it manages, the BOS Server thread handling this call invokes the BOP
2012 GETSTAT() macro, waiting until the bnode's status and goals line up. 
2013 \par
2014 Typically, the BOZO WaitAll() routine is used to allow a program to wait until
2015 all bnodes have terminated their execution (i.e., all goal fields have been set
2016 to BSTAT SHUTDOWN and all corresponding processes have been killed). Note,
2017 however, that this routine may also be used to wait until all bnodes start up.
2018 The true utility of this application of BOZO WaitAll() is more questionable,
2019 since it will return when all bnodes have simply commenced execution, which
2020 does not imply that they have completed their initialization phases and are
2021 thus rendering their normal services. 
2022 \par
2023 The BOS Server will only allow individuals listed in its locally-maintained
2024 UserList file to wait on bnodes through this interface function. 
2025 \par
2026 The given bnode's getstat() routine from its individual ops array will be
2027 called in the course of this execution via the BOP GETSTAT() macro. 
2028 \par Error Codes 
2029 BZACCESS The caller is not authorized to perform this operation. 
2030
2031         \subsection sec3-6-4 Section 3.6.4: Security Configuration 
2032
2033 \par
2034 This section describes the seven BOS Server interface functions that allow a
2035 properly-authorized person to examine and modify certain data relating to
2036 system security. Specifically, it allows for manipulation of the list of
2037 adminstratively 'privileged' individuals, the set of Kerberos keys used for
2038 file service, and whether authenticated connections should be required by the
2039 BOS Server and all other AFS server agents running on the machine. 
2040
2041         \subsubsection sec3-6-4-1 Section 3.6.4.1: BOZO AddSUser - Add a user
2042 to the UserList 
2043
2044 \code
2045 int BOZO AddSUser(IN struct rx connection *z conn, IN char *name); 
2046 \endcode
2047 \par Description 
2048 This interface function is used to add the given user name to the UserList file
2049 of priviledged BOS Server principals. Only individuals already appearing in the
2050 UserList are permitted to add new entries. If the given user name already
2051 appears in the file, the function fails. Otherwise, the file is opened in
2052 append mode and the name is written at the end with a trailing newline. 
2053 \par Error Codes 
2054 BZACCESS The caller is not authorized to perform this operation. 
2055 \n EEXIST The individual specified by name is already on the UserList. 
2056 \n EIO If the UserList file could not be opened or closed. 
2057
2058         \subsubsection sec3-6-4-2 Section 3.6.4.2: BOZO DeleteSUser - Delete a
2059 user from the UserList 
2060
2061 \code
2062 int BOZO DeleteSUser(IN struct rx connection *z conn, IN char *name) 
2063 \endcode
2064 \par Description 
2065 This interface function is used to delete the given user name from the UserList
2066 file of priviledged BOS Server principals. Only individuals already appearing
2067 in the UserList are permitted to delete existing entries. The file is opened in
2068 read mode, and a new file named UserList.NXX is created in the same directory
2069 and opened in write mode. The original UserList is scanned, with each entry
2070 copied to the new file if it doesn't match the given name. After the scan is
2071 done, all files are closed, and the UserList.NXX file is renamed to UserList,
2072 overwriting the original. 
2073 \par Error Codes 
2074 BZACCESS The caller is not authorized to perform this operation. 
2075 \n -1 The UserList file could not be opened. 
2076 \n EIO The UserList.NXX file could not be opened, or an error occured in the
2077 file close operations. 
2078 \n ENOENT The given name was not found in the original UserList file. 
2079
2080         \subsubsection sec3-6-4-3 Section 3.6.4.3: BOZO ListSUsers - Get the
2081 name of the user in the given position in the UserList file 
2082
2083 \code
2084 int BOZO ListSUsers(IN struct rx connection *z conn, 
2085                         IN long an, 
2086                         OUT char **name) 
2087 \endcode
2088 \par Description 
2089 This interface function is used to request the name of priviledged user in the
2090 an'th slot in the BOS Server's UserList file. The string placed into the name
2091 parameter may be up to 256 characters long, including the trailing null. 
2092 \par Error Codes 
2093 The UserList file could not be opened, or an invalid value was specified for
2094 an. 
2095
2096         \subsubsection sec3-6-4-4 Section 3.6.4.4: BOZO ListKeys - List info
2097 about the key at a given index in the key file 
2098
2099 \code
2100 int BOZO ListKeys(IN struct rx connection *z conn, 
2101                         IN long an, 
2102                         OUT long *kvno, 
2103                         OUT struct bozo key *key, 
2104                         OUT struct bozo keyInfo *keyinfo) 
2105 \endcode
2106 \par Description 
2107 This interface function allows its callers to specify the index of the desired
2108 AFS encryption key, and to fetch information regarding that key. If the caller
2109 is properly authorized, the version number of the specified key is placed into
2110 the kvno parameter. Similarly, a description of the given key is placed into
2111 the keyinfo parameter. When the BOS Server is running in noauth mode, the key
2112 itself will be copied into the key argument, otherwise the key structure will
2113 be zeroed. The data placed into the keyinfo argument, declared as a struct bozo
2114 keyInfo as defined in Section 3.3.3, is obtained as follows. The mod sec field
2115 is taken from the value of st mtime after stat()ing /usr/afs/etc/KeyFile, and
2116 the mod usec field is zeroed. The keyCheckSum is computed by an Authentication
2117 Server routine, which calculates a 32-bit cryptographic checksum of the key,
2118 encrypting a block of zeros and then using the first 4 bytes as the checksum. 
2119 \par
2120 The BOS Server will only allow individuals listed in its locally-maintained
2121 UserList file to obtain information regarding the list of AFS keys held by the
2122 given BOS Server. 
2123 \par Error Codes 
2124 BZACCESS The caller is not authorized to perform this operation. 
2125 \n BZDOM An invalid index was found in the an parameter. 
2126 \n KABADKEY Defined in the exported kautils.h header file corresponding to the
2127 Authentication Server, this return value indicates a problem with generating
2128 the checksum field of the keyinfo parameter. 
2129
2130         \subsubsection sec3-6-4-5 Section 3.6.4.5: BOZO AddKey - Add a key to
2131 the key file 
2132
2133 \code
2134 int BOZO AddKey(IN struct rx connection *z conn, 
2135                 IN long an, 
2136                 IN struct bozo key *key) 
2137 \endcode
2138 \par Description 
2139 This interface function allows a properly-authorized caller to set the value of
2140 key version number an to the given AFS key. If a slot is found in the key file
2141 /usr/afs/etc/KeyFile marked as key version number an, its value is overwritten
2142 with the key provided. If an entry for the desired key version number does not
2143 exist, the key file is grown, and the new entry filled with the specified
2144 information. 
2145 \par
2146 The BOS Server will only allow individuals listed in its locally-maintained
2147 UserList file to add new entries into the list of AFS keys held by the BOS
2148 Server. 
2149 \par Error Codes 
2150 BZACCESS The caller is not authorized to perform this operation. 
2151 \n AFSCONF FULL The system key file already contains the maximum number of keys
2152 (AFSCONF MAXKEYS, or 8). These two constant defintions are available from the
2153 cellconfig.h and keys.h AFS include files respectively. 
2154
2155         \subsubsection sec3-6-4-6 Section 3.6.4.6: BOZO DeleteKey - Delete the
2156 entry for an AFS key 
2157
2158 \code
2159 int BOZO DeleteKey(IN struct rx connection *z conn, 
2160                         IN long an) 
2161 \endcode
2162 \par Description 
2163 This interface function allows a properly-authorized caller to delete key
2164 version number an from the key file, /usr/afs/etc/KeyFile. The existing keys
2165 are scanned, and if one with key version number an is found, it is removed. Any
2166 keys occurring after the deleted one are shifted to remove the file entry
2167 entirely. 
2168 \par
2169 The BOS Server will only allow individuals listed in its locally-maintained
2170 UserList file to delete entries from the list of AFS keys held by the BOS
2171 Server. 
2172 \par Error Codes 
2173 BZACCESS The caller is not authorized to perform this operation. 
2174 \n AFSCONF NOTFOUND An entry for key version number an was not found. This
2175 constant defintion is available from the cellconfig.h AFS include file. 
2176
2177         \subsubsection sec3-6-4-7 Section 3.6.4.7: BOZO SetNoAuthFlag - Enable
2178 or disable requirement for authenticated calls 
2179
2180 \code
2181 int BOZO SetNoAuthFlag(IN struct rx connection *z conn, 
2182                         IN long flag) 
2183 \endcode
2184 \par Description 
2185 This interface routine controls the level of authentication imposed on the BOS
2186 Server and all other AFS server agents on the machine by manipulating the
2187 NoAuth file in the /usr/afs/local directory on the server. If the flag
2188 parameter is set to zero (0), the NoAuth file will be removed, instructing the
2189 BOS Server and AFS agents to authenenticate the RPCs they receive. Otherwise,
2190 the file is created as an indication to honor all RPC calls to the BOS Server
2191 and AFS agents, regardless of the credentials carried by callers. 
2192 \par Error Codes 
2193 BZACCESS The caller is not authorized to perform this operation. 
2194
2195         \subsection sec3-6-5 Section 3.6.5: Cell Configuration 
2196
2197 \par
2198 The five interface functions covered in this section all have to do with
2199 manipulating the configuration information of the machine on which the BOS
2200 Server runs. In particular, one may get and set the cell name for that server
2201 machine, enumerate the list of server machines running database servers for the
2202 cell, and add and delete machines from this list. 
2203
2204         \subsubsection sec3-6-5-1 Section 3.6.5.1: BOZO GetCellName - Get the
2205 name of the cell to which the BOS Server belongs 
2206
2207 \code
2208 int BOZO GetCellName(IN struct rx connection *z conn, OUT char **name) 
2209 \endcode
2210 \par Description 
2211 This interface routine returns the name of the cell to which the given BOS
2212 Server belongs. The BOS Server consults a file on its local disk,
2213 /usr/afs/etc/ThisCell to obtain this information. If this file does not exist,
2214 then the BOS Server will return a null string. 
2215 \par Error Codes 
2216 AFSCONF UNKNOWN The BOS Server could not access the cell name file. This
2217 constant defintion is available from the cellconfig.h AFS include file. 
2218
2219         \subsubsection sec3-6-5-2 Section 3.6.5.2: BOZO SetCellName - Set the
2220 name of the cell to which the BOS Server belongs 
2221
2222 \code
2223 int BOZO SetCellName(IN struct rx connection *z conn, IN char *name) 
2224 \endcode
2225 \par Description 
2226 This interface function allows the caller to set the name of the cell to which
2227 the given BOS Server belongs. The BOS Server writes this information to a file
2228 on its local disk, /usr/afs/etc/ThisCell. The current contents of this file are
2229 first obtained, along with other information about the current cell. If this
2230 operation fails, then BOZO SetCellName() also fails. The string name provided
2231 as an argument is then stored in ThisCell. 
2232 \par 
2233 The BOS Server will only allow individuals listed in its locally-maintained
2234 UserList file to set the name of the cell to which the machine executing the
2235 given BOS Server belongs. 
2236 \par Error Codes 
2237 BZACCESS The caller is not authorized to perform this operation. 
2238 \n AFSCONF NOTFOUND Information about the current cell could not be obtained.
2239 This constant definition, along with AFSCONF FAILURE appearing below, is
2240 availabel from the cellconfig.h AFS include file. 
2241 \n AFSCONF FAILURE New cell name could not be written to file. 
2242
2243         \subsubsection sec3-6-5-3 Section 3.6.5.3: BOZO GetCellHost - Get the
2244 name of a database host given its index 
2245
2246 \code
2247 int BOZO GetCellHost(IN struct rx connection *z conn, 
2248                         IN long awhich, 
2249                         OUT char **name) 
2250 \endcode
2251 \par Description 
2252 This interface routine allows the caller to get the name of the host appearing
2253 in position awhich in the list of hosts acting as database servers for the BOS
2254 Server's cell. The first valid position in the list is index zero. The host's
2255 name is deposited in the character buffer pointed to by name. If the value of
2256 the index provided in awhich is out of range, the function fails and a null
2257 string is placed in name. 
2258 \par Error Codes 
2259 BZDOM The host index in awhich is out of range. 
2260 \n AFSCONF NOTFOUND Information about the current cell could not be obtained.
2261 This constant defintion may be found in the cellconfig.h AFS include file. 
2262
2263         \subsubsection sec3-6-5-4 Section 3.6.5.4: BOZO AddCellHost - Add an
2264 entry to the list of database server hosts 
2265
2266 \code
2267 int BOZO AddCellHost(IN struct rx connection *z conn, IN char *name) 
2268 \endcode
2269 \par Description 
2270 This interface function allows properly-authorized callers to add a name to the
2271 list of hosts running AFS database server processes for the BOS Server's home
2272 cell. If the given name does not already appear in the database server list, a
2273 new entry will be created. Regardless, the mapping from the given name to its
2274 IP address will be recomputed, and the cell database file,
2275 /usr/afs/etc/CellServDB will be updated. 
2276 \par
2277 The BOS Server will only allow individuals listed in its locally-maintained
2278 UserList file to add an entry to the list of host names providing database
2279 services for the BOS Server's home cell. 
2280 \par Error Codes 
2281 BZACCESS The caller is not authorized to perform this operation. 
2282 \n AFSCONF NOTFOUND Information about the current cell could not be obtained.
2283 This constant defintion may be found in the cellconfig.h AFS include file. 
2284
2285         \subsubsection sec3-6-5-5 Section 3.6.5.5: BOZO DeleteCellHost - Delete
2286 an entry from the list of database server hosts 
2287
2288 \code
2289 int BOZO DeleteCellHost(IN struct rx connection *z conn, IN char *name) 
2290 \endcode
2291 \par Description 
2292 This interface routine allows properly-authorized callers to remove a given
2293 name from the list of hosts running AFS database server processes for the BOS
2294 Server's home cell. If the given name does not appear in the database server
2295 list, this function will fail. Otherwise, the matching entry will be removed,
2296 and the cell database file, /usr/afs/etc/CellServDB will be updated. 
2297 \par
2298 The BOS Server will only allow individuals listed in its locally-maintained
2299 UserList file to delete an entry from the list of host names providing database
2300 services for the BOS Server's home cell. 
2301 \par Error Codes 
2302 BZACCESS The caller is not authorized to perform this operation. 
2303 \n AFSCONF NOTFOUND Information about the current cell could not be obtained.
2304 This constant defintion may be found in the cellconfig.h AFS include file. 
2305
2306         \subsection sec3-6-6 Section 3.6.6: Installing/Uninstalling Server
2307 Binaries 
2308
2309 \par
2310 There are four BOS Server interface routines that allow administrators to
2311 install new server binaries and to roll back to older, perhaps more reliable,
2312 executables. They also allow for stored images of the old binaries (as well as
2313 core files) to be 'pruned', or selectively deleted. 
2314
2315 3.6.6.1 StartBOZO Install - Pass the IN params when installing a server binary 
2316
2317 \code
2318 int StartBOZO Install(IN struct rx connection *z conn, 
2319                         IN char *path, 
2320                         IN long size, 
2321                         IN long flags, 
2322                         IN long date) 
2323 \endcode
2324 \par Description 
2325 The BOZO Install() function defined in the BOS Server Rxgen interface file is
2326 used to deliver the executable image of an AFS server process to the given
2327 server machine and then installing it in the appropriate directory there. It is
2328 defined to be a streamed function, namely one that can deliver an arbitrary
2329 amount of data. For full details on the definition and use of streamed
2330 functions, please refer to the Streamed Function Calls section in [4]. 
2331 \par
2332 This function is created by Rxgen in response to the BOZO Install() interface
2333 definition in the bosint.xg file. The StartBOZO Install() routine handles
2334 passing the IN parameters of the streamed call to the BOS Server. Specifically,
2335 the apath argument specifies the name of the server binary to be installed
2336 (including the full pathname prefix, if necessary). Also, the length of the
2337 binary is communicated via the size argument, and the modification time the
2338 caller wants the given file to carry is placed in date. The flags argument is
2339 currently ignored by the BOS Server. 
2340 \par
2341 After the above parameters are delivered with StartBOZO Install(), the BOS
2342 Server creates a file with the name given in the path parameter followed by a
2343 .NEW postfix. The size bytes comprising the text of the executable in question
2344 are then read over the RPC channel and stuffed into this new file. When the
2345 transfer is complete, the file is closed. The existing versions of the server
2346 binary are then 'demoted'; the *.BAK version (if it exists) is renamed to
2347 *.OLD. overwriting the existing *.OLD version if and only if an *.OLD version
2348 does not exist, or if a *.OLD exists and the .BAK file is at least seven days
2349 old. The main binary is then renamed to *.BAK. Finally, the *.NEW file is
2350 renamed to be the new standard binary image to run, and its modification time
2351 is set to date. 
2352 \par
2353 The BOS Server will only allow individuals listed in its locally-maintained
2354 UserList file to install server software onto the machine on which the BOS
2355 Server runs. 
2356 \par Error Codes 
2357 BZACCESS The caller is not authorized to perform this operation. 
2358 \n 100 An error was encountered when writing the binary image to the local disk
2359 file. The truncated file was closed and deleted on the BOS Server. 
2360 \n 101 More than size bytes were delivered to the BOS Server in the RPC
2361 transfer of the executable image. 
2362 \n 102 Fewer than size bytes were delivered to the BOS Server in the RPC
2363 transfer of the executable image. 
2364
2365         \subsubsection sec3-6-6-2 Section 3.6.6.2: EndBOZO Install - Get the
2366 OUT params when installing a server binary 
2367
2368 \code
2369 int EndBOZO Install(IN struct rx connection *z conn) 
2370 \endcode
2371 \par Description 
2372 This function is created by Rxgen in response to the BOZO Install() interface
2373 definition in the bosint.xg file. The EndBOZO Install() routine handles the
2374 recovery of the OUT parameters for this interface call, of which there are
2375 none. The utility of such functions is often the value they return. In this
2376 case, however, EndBOZO Install() always returns success. Thus, it is not even
2377 necessary to invoke this particular function, as it is basically a no-op. 
2378 \par Error Codes 
2379 ---Always returns successfully. 
2380
2381         \subsubsection sec3-6-6-3 Section 3.6.6.3: BOZO UnInstall - Roll back
2382 from a server binary installation 
2383
2384 \code
2385 int BOZO UnInstall(IN struct rx connection *z conn, IN char *path) 
2386 \endcode
2387 \par Description 
2388 This interface function allows a properly-authorized caller to "roll back" from
2389 the installation of a server binary. If the *.BAK version of the server named
2390 path exists, it will be renamed to be the main executable file. In this case,
2391 the *.OLD version, if it exists, will be renamed to *.BAK.If a *.BAK version of
2392 the binary in question is not found, the *.OLD version is renamed as the new
2393 standard binary file. If neither a *.BAK or a *.OLD version of the executable
2394 can be found, the function fails, returning the low-level unix error generated
2395 at the server. 
2396 \par
2397 The BOS Server will only allow individuals listed in its locally-maintained
2398 UserList file to roll back server software on the machine on which the BOS
2399 Server runs. 
2400 \par Error Codes 
2401 BZACCESS The caller is not authorized to perform this operation. 
2402
2403         \subsubsection sec3-6-6-4 Section 3.6.6.4: BOZO Prune - Throw away old
2404 versions of server binaries and core files 
2405
2406 \code
2407 int BOZO Prune(IN struct rx connection *z conn, IN long flags) 
2408 \endcode
2409 \par Description 
2410 This interface routine allows a properly-authorized caller to prune the saved
2411 versions of server binaries resident on the machine on which the BOS Server
2412 runs. The /usr/afs/bin directory on the server machine is scanned in directory
2413 order. If the BOZO PRUNEOLD bit is set in the flags argument, every file with
2414 the *.OLD extension is deleted. If the BOZO PRUNEBAK bit is set in the flags
2415 argument, every file with the *.BAK extension is deleted. Next, the
2416 /usr/afs/logs directory is scanned in directory order. If the BOZO PRUNECORE
2417 bit is set in the flags argument, every file with a name beginning with the
2418 prefix core is deleted. 
2419 \par
2420 The BOS Server will only allow individuals listed in its locally-maintained
2421 UserList file to prune server software binary versions and core files on the
2422 machine on which the BOS Server runs. 
2423 \par Error Codes 
2424 BZACCESS The caller is not authorized to perform this operation. 
2425
2426         \subsection sec3-6-7 Section 3.6.7: Executing Commands at the Server 
2427
2428 \par
2429 There is a single interface function defined by the BOS Server that allows
2430 execution of arbitrary programs or scripts on any server machine on which a BOS
2431 Server process is active. 
2432
2433 3.6.7.1 BOZO Exec - Execute a shell command at the server 
2434
2435 \code
2436 int BOZO Exec(IN struct rx connection *z conn, IN char *cmd) 
2437 \endcode
2438 \par Description 
2439 This interface routine allows a properly-authorized caller to execute any
2440 desired shell command on the server on which the given BOS Server runs. There
2441 is currently no provision made to pipe the output of the given command's
2442 execution back to the caller through the RPC channel. 
2443 \par
2444 The BOS Server will only allow individuals listed in its locally-maintained
2445 UserList file to execute arbitrary shell commands on the server machine on
2446 which the BOS Server runs via this call. 
2447 \par Error Codes 
2448 BZACCESS The caller is not authorized to perform this operation. 
2449
2450         \page biblio Bibliography 
2451
2452 \li [1] CMU Information Technology Center.      Synchronization and Caching
2453 Issues in the Andrew File System, USENIX Proceedings, Dallas, TX, Winter 1988. 
2454 \li [2] Transarc Corporation. AFS 3.0 Command Reference Manual, F-30-0-D103,
2455 Pittsburgh, PA, April 1990. 
2456 \li [3] Zayas, Edward R., Transarc Corporation.         AFS-3 Programmer's
2457 Reference: Specification for the Rx Remote Procedure Call Facility, FS-00-D164,
2458 Pittsburgh, PA, April 1991. 
2459 \li [4] Zayas,  Edward R., Transarc Corporation. AFS-3 Programmer's Reference:
2460 File Server/Cache Manager Interface, FS-00-D162, Pittsburgh, PA, April 1991. 
2461 \li [5] Transarc Corporation. AFS 3.0 System Administrator's Guide,
2462 F-30-0-D102, Pittsburgh, PA, April 1990. 
2463 \li [6] Kazar, Michael L., Information Technology Center, Carnegie Mellon
2464 University. Ubik -A Library For Managing Ubiquitous Data, ITCID, Pittsburgh,
2465 PA, Month, 1988. 
2466 \li [7] Kazar, Michael L., Information Technology Center, Carnegie Mellon
2467 University. Quorum Completion, ITCID, Pittsburgh, PA, Month, 1988. 
2468 \li [8] S. R. Kleinman.         Vnodes: An Architecture for Multiple file
2469 System Types in Sun UNIX, Conference Proceedings, 1986 Summer Usenix Technical
2470 Conference, pp. 238-247, El Toro, CA, 1986. 
2471
2472 */
2473