Commit | Line | Data |
---|---|---|
805e021f CE |
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 |