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