My Project
Loading...
Searching...
No Matches
BOS Server Interface

AFS-3 Programmer's Reference: BOS Server Interface

Author
Edward R. Zayas Transarc Corporation
Version
1.0
Date
28 August 1991 11:58 Copyright 1991 Transarc Corporation All Rights Reserved FS-00-D161
\page chap1 Chapter 1: Overview 

\section sec1-1 Section 1.1: Introduction 
One of the important duties of an AFS system administrator is to insure that processes on file server machines are properly installed and kept running. The BOS Server was written as a tool for assisting administrators in these tasks. An instance of the BOS Server runs on each AFS server machine, and has the following specific areas of responsibility:
  • Definition of the set of processes that are to be run on the machine on which a given BOS Server executes. This definition may be changed dynamically by system administrators. Programs may be marked as continuously or periodically runnable.
  • Automatic startup and restart of these specified processes upon server bootup and program failure. The BOS Server also responds to administrator requests for stopping and starting one or more of these processes. In addition, the BOS Server is capable of restarting itself on command.
  • Collection of information regarding the current status, command line parameters, execution history, and log files generated by the set of server programs.
  • Management of the security information resident on the machine on which the BOS Server executes. Such information includes the list of administratively privileged people associated with the machine and the set of AFS File Server encryption keys used in the course of file service.
  • Management of the cell configuration information for the server machine in question. This includes the name of the cell in which the server resides, along with the list and locations of the servers within the cell providing AFS database services (e.g., volume location, authentication, protection). Installation of server binaries on the given machine. The BOS Server allows several "generations" of server software to be kept on its machine. Installation of new software for one or more server agents is handled by the BOS Server, as is "rolling back" to a previous version should it prove more stable than the currently-installed image.
Execution of commands on the server machine. An administrator may execute arbitrary unix commands on a machine running the BOS Server.
Unlike many other AFS server processes, the BOS Server does not maintain a cell-wide, replicated database. It does, however, maintain several databases used exclusively on every machine on which it runs.
\section sec1-2 Section 1.2: Scope 
This paper describes the design and structure of the AFS-3 BOS Server. The scope of this work is to provide readers with a sufficiently detailed description of the BOS Server so that they may construct client applications that call the server's RPC interface routines.
\section sec1-3 Section 1.3: Document Layout 
The second chapter discusses various aspects of the BOS Server's architecture. First, one of the basic concepts is examined, namely the bnode. Providing the complete description of a program or set of programs to be run on the given server machine, a bnode is the generic definitional unit for the BOS Server's duties. After bnodes have been explained, the set of standard directories on which the BOS Server depends is considered. Also, the set of well-known files within these directories is explored. Their uses and internal formats are presented. After these sections, a discussion of BOS Server restart times follows. The BOS Server has special support for two commonly-used restart occasions, as described by this section. Finally, the organization and behavior of the bosserver program itself is presented.
The third and final chapter provides a detailed examination of the programmer-visible BOS Server constants and structures, along with a full specification of the API for the RPC-based BOS Server functionality.
\section sec1-4 Section 1.4: Related Documents 
This document is a member of a documentation suite providing programmer-level specifications for the operation of the various AFS servers and agents, and the interfaces they export, as well as the underlying RPC system they use to communicate. The full suite of related AFS specification documents is listed below:
  • AFS-3 Programmer's Reference: Architectural Overview: This paper provides an architectual overview of the AFS distributed file system, describing the full set of servers and agents in a coherent way, illustrating their relationships to each other and examining their interactions.
  • AFS-3 Programmer's Reference: File Server/Cache Manager Interface: This document describes the File Server and Cache Manager agents, which provide the backbone file managment services for AFS. The collection of File Servers for a cell supply centralized file storage for that site, and allow clients running the Cache Manager component to acces those files in a high-performance, secure fashion.
  • AFS-3 Programmer's Reference:Volume Server/Volume Location Server Interface: This document describes the services through which "containers" of related user data are located and managed.
  • AFS-3 Programmer's Reference: Protection Server Interface: This paper describes the server responsible for mapping printable user names to and from their internal AFS identifiers. The Protection Server also allows users to create, destroy, and manipulate "groups" of users, which are suitable for placement on ACLs.
  • AFS-3 Programmer's Reference: Specification for the Rx Remote Procedure Call Facility: This document specifies the design and operation of the remote procedure call and lightweight process packages used by AFS.
In addition to these papers, the AFS 3.1 product is delivered with its own user, administrator, installation, and command reference documents.
\page chap2 Chapter 2: BOS Server Architecture 
This chapter considers some of the architectual features of the AFS-3 BOS Server. First, the basic organizational and functional entity employed by the BOS Server, the bnode, is discussed. Next, the set of files with which the server interacts is examined. The notion of restart times is then explained in detail. Finally, the organization and components of the bosserver program itself, which implements the BOS Server, are presented.
\section sec2-1 Section 2.1: Bnodes 

\subsection sec2-1-1 Section 2.1.1: Overview 
The information required to manage each AFS-related program running on a File Server machine is encapsulated in a bnode object. These bnodes serve as the basic building blocks for BOS Server services. Bnodes have two forms of existence:
  • On-disk: The BosConfig file (see Section 2.3.4 below) defines the set of bnodes for which the BOS Server running on that machine will be responsible, along with specifying other information such as values for the two restart times. This file provides permanent storage (i.e., between bootups) for the desired list of programs for that server platform.
  • In-memory: The contents of the BosConfig file are parsed and internalized by the BOS Server when it starts execution. The basic data for a particular server program is placed into a struct bnode structure.
The initial contents of the BosConfig file are typically set up during system installation. The BOS Server can be directed, via its RPC interface, to alter existing bnode entries in the BosConfig file, add new ones, and delete old ones. Typically, this file is never edited directly.
\subsection sec2-1-2 Section 2.1.2: Bnode Classes 
The descriptions of the members of the AFS server suite fall into three broad classes of programs:
  • Simple programs: This server class is populated by programs that simply need to be kept running, and do not depend on other programs for correctness or effectiveness. Examples of AFS servers falling into this category are the Volume Location Server, Authentication Server, and Protection Server. Since its members exhibit such straightforward behavior, this class of programs is referred to as the simple class.
  • Interrelated programs: The File Server program depends on two other programs, and requires that they be executed at the appropriate times and in the appropriate sequence, for correct operation. The first of these programs is the Volume Server, which must be run concurrently with the File Server. The second is the salvager, which repairs the AFS volume metadata on the server partitions should the metadata become damaged. The salvager must not be run at the same time as the File Server. In honor of the File Server trio that inspired it, the class of programs consisting of groups of interrelated processes is named the fs class.
  • Periodic programs: Some AFS servers, such as the BackupServer, only need to run every so often, but on a regular and well-defined basis. The name for this class is taken from the unix tool that is typically used to define such regular executions, namely the cron class.
The recognition and definition of these three server classes is exploited by the BOS Server. Since all of the programs in a given class share certain common characteristics, they may all utilize the same basic data structures to record and manage their special requirements. Thus, it is not necessary to reimplement all the operations required to satisfy the capabilities promised by the BOS Server RPC interface for each and every program the BOS Server manages. Implementing one set of operations for each server class is sufficient to handle any and all server binaries to be run on the platform.
\subsection sec2-1-3 Section 2.1.3: Per-Class Bnode Operations 
As mentioned above, only one set of basic routines must be implemented for each AFS server class. Much like Sun's VFS/vnode interface [8], providing a common set of routines for interacting with a given file system, regardless of its underlying implementation and semantics, the BOS Server defines a common vector of operations for a class of programs to be run under the BOS Server's tutelage. In fact, it was this standardized file system interface that inspired the "bnode" name.
The BOS Server manipulates the process or processes that are described by each bnode by invoking the proper functions in the appropriate order from the operation vector for that server class. Thus, the BOS Server itself operates in a class-independent fashion. This allows each class to take care of the special circumstances associated with it, yet to have the BOS Server itself be totally unaware of what special actions (if any) are needed for the class. This abstraction also allows more server classes to be implemented without any significant change to the BOS Server code itself.
There are ten entries in this standardized class function array. The purpose and usage of each individual class function is described in detail in Section 3.3.5. Much like the VFS system, a collection of macros is also provided in order to simplify the invocation of these functions. These macros are described in Section 3.5. The ten function slots are named here for convenience:
  • create()
  • timeout()
  • getstat()
  • setstat()
  • delete()
  • procexit()
  • getstring()
  • getparm()
  • restartp()
  • hascore()
    \section sec2-2 Section 2.2: BOS Server Directories 
    
The BOS Server expects the existence of the following directories on the local disk of the platform on which it runs. These directories define where the system binaries, log files, ubik databases, and other files lie.
  • /usr/afs/bin: This directory houses the full set of AFS server binaries. Such executables as bosserver, fileserver, vlserver, volserver, kaserver, and ptserver reside here.
  • /usr/afs/db: This directory serves as the well-known location on the server's local disk for the ubik database replicas for this machine. Specifically, the Authentication Server, Protection Server, and the Volume Location Server maintain their local database images here.
  • /usr/afs/etc: This directory hosts the files containing the security, cell, and authorized system administrator list for the given machine. Specifically, the CellServDB, KeyFile, License, ThisCell, and UserList files are stored here.
  • /usr/afs/local: This directory houses the BosConfig file, which supplies the BOS Server with the permanent set of bnodes to support. Also contained in this directory are files used exclusively by the salvager.
  • /usr/afs/logs: All of the AFS server programs that maintain log files deposit them in this directory.
    \section sec2-3 Section 2.3: BOS Server Files 
    
Several files, some mentioned above, are maintained on the server's local disk and manipulated by the BOS Server. This section examines many of these files, and describes their formats.
\subsection sec2-3-1 Section 2.3.1: /usr/afs/etc/UserList 
This file contains the names of individuals who are allowed to issue "restricted" BOS Server commands (e.g., creating & deleting bnodes, setting cell information, etc.) on the given hardware platform. The format is straightforward, with one administrator name per line. If a cell grants joe and schmoe these rights on a machine, that particular UserList will have the following two lines:
joe
schmoe
\subsection sec2-3-2 Section 2.3.2: /usr/afs/etc/CellServDB 
This file identifies the name of the cell to which the given server machine belongs, along with the set of machines on which its ubik database servers are running. Unlike the CellServDB found in /usr/vice/etc on AFS client machines, this file contains only the entry for the home cell. It shares the formatting rules with the /usr/vice/etc version of CellServDB. The contents of the CellServDB file used by the BOS Server on host grand.central.org are:
>grand.central.org #DARPA clearinghouse cell
192.54.226.100 #grand.central.org
192.54.226.101 #penn.central.org
\subsection sec2-3-3 Section 2.3.3: /usr/afs/etc/ThisCell 
The BOS Server obtains its notion of cell membership from the ThisCell file in the specified directory. As with the version of ThisCell found in /usr/vice/etc on AFS client machines, this file simply contains the character string identifying the home cell name. For any server machine in the grand.central.org cell, this file contains the following:
grand.central.org
\subsection sec2-3-4 Section 2.3.4: /usr/afs/local/BosConfig 
The BosConfig file is the on-disk representation of the collection of bnodes this particular BOS Server manages. The BOS Server reads and writes to this file in the normal course of its affairs. The BOS Server itself, in fact, should be the only agent that modifies this file. Any changes to BosConfig should be carried out by issuing the proper RPCs to the BOS Server running on the desired machine.
The following is the text of the BosConfig file on grand.central.org. A discussion of the contents follows immediately afterwards.
restarttime 11 0 4 0 0 checkbintime 3 0 5 0 0
bnode simple kaserver 1 parm /usr/afs/bin/kaserver
end bnode simple ptserver 1 parm
/usr/afs/bin/ptserver end bnode simple vlserver 1
parm /usr/afs/bin/vlserver end bnode fs fs 1 parm
/usr/afs/bin/fileserver parm /usr/afs/bin/volserver
parm /usr/afs/bin/salvager end bnode simple runntp
1 parm /usr/afs/bin/runntp -localclock transarc.com
end bnode simple upserver 1 parm
/usr/afs/bin/upserver end bnode simple
budb_server 1 parm /usr/afs/bin/budb_server end
bnode cron backup 1 parm
/usr/afs/backup/clones/lib/backup.csh daily parm
05:00 end
The first two lines of this file set the system and new-binary restart times (see Section 2.4, below). They are optional, with the default system restart time being every Sunday at 4:00am and the new-binary restart time being 5:00am daily. Following the reserved words restarttime and checkbintime are five integers, providing the mask, day, hour, minute, and second values (in decimal) for the restart time, as diagrammed below:
restarttime <mask> <day> <hour> <minute>
<second> checkbintime <mask> <day> <hour>
<minute> <second>
The range of acceptable values for these fields is presented in Section 3.3.1. In this example, the restart line specifies a (decimal) mask value of 11, selecting the KTIME HOUR, KTIME MIN, and KTIME DAY bits. This indicates that the hour, minute, and day values are the ones to be used when matching times. Thus, this line requests that system restarts occur on day 0 (Sunday), hour 4 (4:00am), and minute 0 within that hour.
The sets of lines that follow define the individual bnodes for the particular machine. The first line of the bnode definition set must begin with the reserved word bnode, followed by the type name, the instance name, and the initial bnode goal:
bnode <type_name> <instance_name> <goal_val>
The <type name> and <instance name> fields are both character strings, and the <goal val> field is an integer. Acceptable values for the <type name> are simple, fs, and cron. Acceptable values for <goal val> are defined in Section 3.2.3, and are normally restricted to the integer values representing BSTAT NORMAL and BSTAT SHUTDOWN. Thus, in the bnode line defining the Authentication Server, it is declared to be of type simple, have instance name kaserver, and have 1 (BSTAT NORMAL) as a goal (e.g., it should be brought up and kept running).
Following the bnode line in the BosConfig file may be one or more parm lines. These entries represent the command line parameters that will be used to invoke the proper related program or programs. The entire text of the line after the parm reserved word up to the terminating newline is stored as the command line string.
parm <command_line_text>
After the parm lines, if any, the reserved word end must appear alone on a line, marking the end of an individual bnode definition.
\subsection sec2-3-5 Section 2.3.5: /usr/afs/local/NoAuth 
The appearance of this file is used to mark whether the BOS Server is to insist on properly authenticated connections for its restricted operations or whether it will allow any caller to exercise these commands. Not only is the BOS Server affected by the presence of this file, but so are all of the bnodes objects the BOS Server starts up. If /usr/afs/local/NoAuth is present, the BOS Server will start all of its bnodes with the -noauth flag.
Completely unauthenticated AFS operation will result if this file is present when the BOS Server starts execution. The file itself is typically empty. If any data is put into the NoAuth file, it will be ignored by the system.
\subsection sec2-3-6 Section 2.3.6: /usr/afs/etc/KeyFile 
This file stores the set of AFS encryption keys used for file service operations. The file follows the format defined by struct afsconf key and struct afsconf keys in include file afs/keys.h. For the reader's convenience, these structures are detailed below:
#define AFSCONF_MAXKEYS 8
struct afsconf_key {
long kvno;
char key[8];
};
struct afsconf_keys {
long nkeys;
struct afsconf_key key[AFSCONF_MAXKEYS];
};
The first longword of the file reveals the number of keys that may be found there, with a maximum of AFSCONF MAXKEYS (8). The keys themselves follow, each preceded by its key version number.
All information in this file is stored in network byte order. Each BOS Server converts the data to the appropriate host byte order befor storing and manipulating it.
\section sec2-4 Section 2.4: Restart Times 
It is possible to manually start or restart any server defined within the set of BOS Server bnodes from any AFS client machine, simply by making the appropriate call to the RPC interface while authenticated as a valid administrator (i.e., a principal listed in the UserList file on the given machine). However, two restart situations merit the implementation of special functionality within the BOS Server. There are two common occasions, occuring on a regular basis, where the entire system or individual server programs should be brought down and restarted:
Complete system restart: To guard against the reliability and performance problems caused by any core leaks in long-running programs, the entire AFS system should be occasionally shut down and restarted periodically. This action 'clears out' the memory system, and may result in smaller memory images for these servers, as internal data structures are reinitialized back to their starting sizes. It also allows AFS partitions to be regularly examined, and salvaged if necessary.
Another reason for performing a complete system restart is to commence execution of a new release of the BOS Server itself. The new-binary restarts described below do not restart the BOS Server if a new version of its software has been installed on the machine.
New-binary restarts: New server software may be installed at any time with the assistance of the BOS Server. However, it is often not the case that such software installations occur as a result of the discovery of an error in the program or programs requiring immediate restart. On these occasions, restarting the given processes in prime time so that the new binaries may begin execution is counterproductive, causing system downtime and interfering with user productivity. The system administrator may wish to set an off-peak time when the server binaries are automatically compared to the running program images, and restarts take place should the on-disk binary be more recent than the currently running program. These restarts would thus minimize the resulting service disruption.
Automatically performing these restart functions could be accomplished by creating cron-type bnodes that were defined to execute at the desired times. However, rather than force the system administrator to create and supervise such bnodes, the BOS Server supports the notion of an internal LWP thread with the same effect (see Section 2.5.2). As part of the BosConfig file defined above, the administrator may simply specify the values for the complete system restart and new-binary restart times, and a dedicated BOS Server thread will manage the restarts.
Unless otherwise instructed, the BOS Server selects default times for the two above restart times. A complete system restart is carried out every Sunday at 4:00am by default, and a new-binary restart is executed for each updated binary at 5:00am every day.
\section sec2-5 Section 2.5: The bosserver Process 

\subsection sec2-5-1 Section 2.5.1: Introduction 
The user-space bosserver process is in charge of managing the AFS server processes and software images, the local security and cell database files, and allowing administrators to execute arbitrary programs on the server machine on which it runs. It also implements the RPC interface defined in the bosint.xg Rxgen definition file.
\subsection sec2-5-2 Section 2.5.2: Threading 
As with all the other AFS server agents, the BOS Server is a multithreaded program. It is configured so that a minimum of two lightweight threads are guaranteed to be allocated to handle incoming RPC calls to the BOS Server, and a maximum of four threads are commissioned for this task.
In addition to these threads assigned to RPC duties, there is one other thread employed by the BOS Server, the BozoDaemon(). This thread is responsible for keeping track of the two major restart events, namely the system restart and the new binary restart (see Section 2.4). Every 60 seconds, this thread is awakened, at which time it checks to see if either deadline has occurred. If the complete system restart is then due, it invokes internal BOS Server routines to shut down the entire suite of AFS agents on that machine and then reexecute the BOS Server binary, which results in the restart of all of the server processes. If the new-binary time has arrived, the BOS Server shuts down the bnodes for which binaries newer than those running are available, and then invokes the new software.
In general, the following procedure is used when stopping and restarting processes. First, the restart() operation defined for each bnode's class is invoked via the BOP RESTART() macro. This allows each server to take any special steps required before cycling its service. After that function completes, the standard mechanisms are used to shut down each bnode's process, wait until it has truly stopped its execution, and then start it back up again.
\subsection sec2-5-3 Section 2.5.3: Initialization Algorithm 
This section describes the procedure followed by the BOS Server from the time when it is invoked to the time it has properly initialized the server machine upon which it is executing.
The first check performed by the BOS Server is whether or not it is running as root. It needs to manipulate local unix files and directories in which only root has been given access, so it immediately exits with an error message if this is not the case. The BOS Server's unix working directory is then set to be /usr/afs/logs in order to more easily service incoming RPC requests to fetch the contents of the various server log files at this location. Also, changing the working directory in this fashion results in any core images dumped by the BOS Server's wards will be left in /usr/afs/logs.
The command line is then inspected, and the BOS Server determines whether it will insist on authenticated RPC connections for secure administrative operations by setting up the /usr/afs/local/NoAuth file appropriately (see Section 2.3.5). It initializes the underlying bnode package and installs the three known bnode types (simple, fs, and cron).
After the bnode package is thus set up, the BOS Server ensures that the set of local directories on which it will depend are present; refer to Section 2.2 for more details on this matter. The license file in /usr/afs/etc/License is then read to determine the number of AFS server machines the site is allowed to operate, and whether the cell is allowed to run the NFS/AFS Translator software. This file is typically obtained in the initial system installation, taken from the installation tape. The BOS Server will exit unless this file exists and is properly formatted.
In order to record its actions, any existing /usr/afs/logs/BosLog file is moved to BosLog.old, and a new version is opened in append mode. The BOS Server immediately writes a log entry concerning the state of the above set of important directories.
At this point, the BOS Server reads the BosConfig file, which lists the set of bnodes for which it will be responsible. It starts up the processes associated with the given bnodes. Once accomplished, it invokes its internal system restart LWP thread (covered in Section 2.5.2 above).
Rx initialization begins at this point, setting up the RPC infrastructure to receive its packets on the AFSCONF NANNYPORT, UDP port 7007. The local cell database is then read and internalized, followed by acquisition of the AFS encryption keys.
After all of these steps have been carried out, the BOS Server has gleaned all of the necessary information from its environemnt and has also started up its wards. The final initialization action required is to start all of its listener LWP threads, which are devoted to executing incoming requests for the BOS Server RPC interface.
\subsection sec2-5-4 Section 2.5.4: Command Line Switches 
The BOS Server recognizes exactly one command line argument: -noauth. By default, the BOS Server attempts to use authenticated RPC connections (unless the /usr/afs/local/NoAuth file is present; see Section 2.3.5). The appearance of the -noauth command line flag signals that this server incarnation is to use unauthenticated connections for even those operations that are normally restricted to system administrators. This switch is essential during the initial AFS system installation, where the procedures followed to bootstrap AFS onto a new machine require the BOS Server to run before some system databases have been created.
\page chap3 Chapter 3: BOS Server Interface 

\section sec3-1 Section 3.1: Introduction 
This chapter documents the API for the BOS Server facility, as defined by the bosint.xg Rxgen interface file and the bnode.h include file. Descriptions of all the constants, structures, macros, and interface functions available to the application programmer appear in this chapter.
\section sec3-2 Section 3.2: Constants 
This section covers the basic constant definitions of interest to the BOS Server application programmer. These definitions appear in the bosint.h file, automatically generated from the bosint.xg Rxgen interface file. Another file is exported to the programmer, namely bnode.h.
Each subsection is devoted to describing constants falling into each of the following categories:
  • Status bits
  • Bnode activity bits
  • Bnode states
  • Pruning server binaries
  • Flag bits for struct bnode proc
One constant of general utility is BOZO BSSIZE, which defines the length in characters of BOS Server character string buffers, including the trailing null. It is defined to be 256 characters.
\subsection sec3-2-1 Section 3.2.1: Status Bits 
The following bit values are used in the flags field of struct bozo status, as defined in Section 3.3.4. They record whether or not the associated bnode process currently has a stored core file, whether the bnode execution was stopped because of an excessive number of errors, and whether the mode bits on server binary directories are incorrect.
Name
BOZO HASCORE
Value
1
Description
Does this bnode have a stored core file?
Name
BOZO ERRORSTOP
Value
2
Description
Was this bnode execution shut down because of an excessive number of errors (more than 10 in a 10 second period)?
Name
BOZO BADDIRACCESS
Value
3
Description
Are the mode bits on the /usr/afs directory and its descendants (etc, bin, logs, backup, db, local, etc/KeyFile, etc/UserList) correctly set?
\subsection sec3-2-2 Section 3.2.2: Bnode Activity Bits 
This section describes the legal values for the bit positions within the flags field of struct bnode, as defined in Section 3.3.8. They specify conditions related to the basic activity of the bnode and of the entities relying on it.
Name
BNODE NEEDTIMEOUT
Value
0x01
Description
This bnode is utilizing the timeout mechanism for invoking actions on its behalf.
Name
BNODE ACTIVE
Value
0x02
Description
The given bnode is in active service.
Name
BNODE WAIT
Value
0x04
Description
Someone is waiting for a status change in this bnode.
Name
BNODE DELETE
Value
0x08
Description
This bnode should be deleted at the earliest convenience.
Name
BNODE ERRORSTOP
Value
0x10
Description
This bnode decommissioned because of an excessive number of errors in its associated unix processes.
\subsection sec3-2-3 Section 3.2.3: Bnode States 
The constants defined in this section are used as values within the goal and fileGoal fields within a struct bnode. They specify either the current state of the associated bnode, or the anticipated state. In particular, the fileGoal field, which is the value stored on disk for the bnode, always represents the desired state of the bnode, whether or not it properly reflects the current state. For this reason, only BSTAT SHUTDOWN and BSTAT NORMAL may be used within the fileGoal field. The goal field may take on any of these values, and accurately reflects the current status of the bnode.
Name
BSTAT SHUTDOWN
Value
0
Description
The bnode's execution has been (should be) terminated.
Name
BSTAT NORMAL
Value
1
Description
The bnode is (should be) executing normally.
Name
BSTAT SHUTTINGDOWN
Value
2
Description
The bnode is currently being shutdown; execution has not yet ceased.
Name
BSTAT STARTINGUP
Value
3
Description
The bnode execution is currently being commenced; execution has not yet begun.
\subsection sec3-2-4 Section 3.2.4: Pruning Server Binaries 
The BOZO Prune() interface function, fully defined in Section 3.6.6.4, allows a properly-authenticated caller to remove ("prune") old copies of server binaries and core files managed by the BOS Server. This section identifies the legal values for the flags argument to the above function, specifying exactly what is to be pruned.
Name
BOZO PRUNEOLD
Value
1
Description
Prune all server binaries with the *.OLD extension.
Name
BOZO PRUNEBAK
Value
2
Description
Prune all server binaries with the *.BAK extension.
Name
BOZO PRUNECORE
Value
3
Description
Prune core files.
\subsection sec3-2-5 Section 3.2.5: Flag Bits for struct bnode proc 
This section specifies the acceptable bit values for the flags field in the struct bnode proc structure, as defined in Section 3.3.9. Basically, they are used to record whether or not the unix binary associated with the bnode has ever been run, and if so whether it has ever exited.
Name
BPROC STARTED
Value
1
Description
Has the associated unix process ever been started up?
Name
BPROC EXITED
Value
2
Description
Has the associated unix process ever exited?
\section sec3-3 Section 3.3: Structures 
This section describes the major exported BOS Server data structures of interest to application programmers.
\subsection sec3-3-1 Section 3.3.1: struct bozo netKTime 
This structure is used to communicate time values to and from the BOS Server. In particular, the BOZO GetRestartTime() and BOZO SetRestartTime() interface functions, described in Sections 3.6.2.5 and 3.6.2.6 respectively, use parameters declared to be of this type.
Four of the fields in this structure specify the hour, minute, second, and day of the event in question. The first field in the layout serves as a mask, identifying which of the above four fields are to be considered when matching the specified time to a given reference time (most often the current time). The bit values that may be used for the mask field are defined in the afs/ktime.h include file. For convenience, their values are reproduced here, including some special cases at the end of the table.
Name
KTIME HOUR
Value
0x01
Description
Hour should match.
Name
KTIME MIN
Value
0x02
Description
Minute should match.
Name
KTIME SEC
Value
0x04
Description
Second should match.
Name
KTIME DAY
Value
0x08
Description
Day should match.
Name
KTIME TIME
Value
0x07
Description
All times should match.
Name
KTIME NEVER
Value
0x10
Description
Special case: never matches.
Name
KTIME NOW
Value
0x20
Description
Special case: right now.


Fields

int StartBOZO Install(IN struct rx connection *z conn,
IN char *path,
IN long size,
IN long flags,
IN long date)
Description
The BOZO Install() function defined in the BOS Server Rxgen interface file is used to deliver the executable image of an AFS server process to the given server machine and then installing it in the appropriate directory there. It is defined to be a streamed function, namely one that can deliver an arbitrary amount of data. For full details on the definition and use of streamed functions, please refer to the Streamed Function Calls section in [4].
This function is created by Rxgen in response to the BOZO Install() interface definition in the bosint.xg file. The StartBOZO Install() routine handles passing the IN parameters of the streamed call to the BOS Server. Specifically, the apath argument specifies the name of the server binary to be installed (including the full pathname prefix, if necessary). Also, the length of the binary is communicated via the size argument, and the modification time the caller wants the given file to carry is placed in date. The flags argument is currently ignored by the BOS Server.
After the above parameters are delivered with StartBOZO Install(), the BOS Server creates a file with the name given in the path parameter followed by a .NEW postfix. The size bytes comprising the text of the executable in question are then read over the RPC channel and stuffed into this new file. When the transfer is complete, the file is closed. The existing versions of the server binary are then 'demoted'; the *.BAK version (if it exists) is renamed to .OLD. overwriting the existing *.OLD version if and only if an *.OLD version does not exist, or if a *.OLD exists and the .BAK file is at least seven days old. The main binary is then renamed to *.BAK. Finally, the *.NEW file is renamed to be the new standard binary image to run, and its modification time is set to date.
The BOS Server will only allow individuals listed in its locally-maintained UserList file to install server software onto the machine on which the BOS Server runs.
Error Codes
BZACCESS The caller is not authorized to perform this operation.
100 An error was encountered when writing the binary image to the local disk file. The truncated file was closed and deleted on the BOS Server.
101 More than size bytes were delivered to the BOS Server in the RPC transfer of the executable image.
102 Fewer than size bytes were delivered to the BOS Server in the RPC transfer of the executable image.
\subsubsection sec3-6-6-2 Section 3.6.6.2: EndBOZO Install - Get the
OUT params when installing a server binary
int EndBOZO Install(IN struct rx connection *z conn)
Description
This function is created by Rxgen in response to the BOZO Install() interface definition in the bosint.xg file. The EndBOZO Install() routine handles the recovery of the OUT parameters for this interface call, of which there are none. The utility of such functions is often the value they return. In this case, however, EndBOZO Install() always returns success. Thus, it is not even necessary to invoke this particular function, as it is basically a no-op.
Error Codes
—Always returns successfully.
\subsubsection sec3-6-6-3 Section 3.6.6.3: BOZO UnInstall - Roll back
from a server binary installation
int BOZO UnInstall(IN struct rx connection *z conn, IN char *path)
Description
This interface function allows a properly-authorized caller to "roll back" from the installation of a server binary. If the *.BAK version of the server named path exists, it will be renamed to be the main executable file. In this case, the *.OLD version, if it exists, will be renamed to *.BAK.If a *.BAK version of the binary in question is not found, the *.OLD version is renamed as the new standard binary file. If neither a *.BAK or a *.OLD version of the executable can be found, the function fails, returning the low-level unix error generated at the server.
The BOS Server will only allow individuals listed in its locally-maintained UserList file to roll back server software on the machine on which the BOS Server runs.
Error Codes
BZACCESS The caller is not authorized to perform this operation.
\subsubsection sec3-6-6-4 Section 3.6.6.4: BOZO Prune - Throw away old
versions of server binaries and core files
int BOZO Prune(IN struct rx connection *z conn, IN long flags)
Description
This interface routine allows a properly-authorized caller to prune the saved versions of server binaries resident on the machine on which the BOS Server runs. The /usr/afs/bin directory on the server machine is scanned in directory order. If the BOZO PRUNEOLD bit is set in the flags argument, every file with the *.OLD extension is deleted. If the BOZO PRUNEBAK bit is set in the flags argument, every file with the *.BAK extension is deleted. Next, the /usr/afs/logs directory is scanned in directory order. If the BOZO PRUNECORE bit is set in the flags argument, every file with a name beginning with the prefix core is deleted.
The BOS Server will only allow individuals listed in its locally-maintained UserList file to prune server software binary versions and core files on the machine on which the BOS Server runs.
Error Codes
BZACCESS The caller is not authorized to perform this operation.
\subsection sec3-6-7 Section 3.6.7: Executing Commands at the Server 
There is a single interface function defined by the BOS Server that allows execution of arbitrary programs or scripts on any server machine on which a BOS Server process is active.

3.6.7.1 BOZO Exec - Execute a shell command at the server

int BOZO Exec(IN struct rx connection *z conn, IN char *cmd)
Description
This interface routine allows a properly-authorized caller to execute any desired shell command on the server on which the given BOS Server runs. There is currently no provision made to pipe the output of the given command's execution back to the caller through the RPC channel.
The BOS Server will only allow individuals listed in its locally-maintained UserList file to execute arbitrary shell commands on the server machine on which the BOS Server runs via this call.
Error Codes
BZACCESS The caller is not authorized to perform this operation.
\page biblio Bibliography 
  • [1] CMU Information Technology Center. Synchronization and Caching Issues in the Andrew File System, USENIX Proceedings, Dallas, TX, Winter 1988.
  • [2] Transarc Corporation. AFS 3.0 Command Reference Manual, F-30-0-D103, Pittsburgh, PA, April 1990.
  • [3] Zayas, Edward R., Transarc Corporation. AFS-3 Programmer's Reference: Specification for the Rx Remote Procedure Call Facility, FS-00-D164, Pittsburgh, PA, April 1991.
  • [4] Zayas, Edward R., Transarc Corporation. AFS-3 Programmer's Reference: File Server/Cache Manager Interface, FS-00-D162, Pittsburgh, PA, April 1991.
  • [5] Transarc Corporation. AFS 3.0 System Administrator's Guide, F-30-0-D102, Pittsburgh, PA, April 1990.
  • [6] Kazar, Michael L., Information Technology Center, Carnegie Mellon University. Ubik -A Library For Managing Ubiquitous Data, ITCID, Pittsburgh, PA, Month, 1988.
  • [7] Kazar, Michael L., Information Technology Center, Carnegie Mellon University. Quorum Completion, ITCID, Pittsburgh, PA, Month, 1988.
  • [8] S. R. Kleinman. Vnodes: An Architecture for Multiple file System Types in Sun UNIX, Conference Proceedings, 1986 Summer Usenix Technical Conference, pp. 238-247, El Toro, CA, 1986.