Chapter 3: BOS Server Interface

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 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.

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?

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.

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.

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.

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 3.3: Structures

This section describes the major exported BOS Server data structures of interest to application programmers.

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

Section 3.3.2: struct bozo key

This structure defines the format of an AFS encryption key, as stored in the key file located at /usr/afs/etc/KeyFile at the host on which the BOS Server runs. It is used in the argument list of the BOZO ListKeys() and BOZO AddKeys() interface functions, as described in Sections 3.6.4.4 and 3.6.4.5 respectively.
Fields
  • char data[8] - The array of 8 characters representing an encryption key.

Section 3.3.3: struct bozo keyInfo

This structure defines the information kept regarding a given AFS encryption key, as represented by a variable of type struct bozo key, as described in Section 3.3.2 above. A parameter of this type is used by the BOZO ListKeys() function (described in Section 3.6.4.4). It contains fields holding the associated key's modification time, a checksum on the key, and an unused longword field. Note that the mod sec time field listed below is a standard unix time value.
Fields
  • long mod sec - The time in seconds when the associated key was last modified.
  • long mod usec - The number of microseconds elapsed since the second reported in the mod sec field. This field is never set by the BOS Server, and should always contain a zero.
  • unsigned long keyCheckSum - The 32-bit cryptographic checksum of the associated key. A block of zeros is encrypted, and the first four bytes of the result are placed into this field.
  • long spare2 - This longword field is currently unused, and is reserved for future use.

Section 3.3.4: struct bozo status

This structure defines the layout of the information returned by the status parameter for the interface function BOZO GetInstanceInfo(), as defined in Section 3.6.2.3. The enclosed fields include such information as the temporary and long-term goals for the process instance, an array of bit values recording status information, start and exit times, and associated error codes and signals.
Fields
  • long goal - The short-term goal for a process instance. Settings for this field are BSTAT SHUTDOWN, BSTAT NORMAL, BSTAT SHUTTINGDOWN, and BSTAT STARTINGUP. These values are fully defined in Section 3.2.3.
  • long fileGoal - The long-term goal for a process instance. Accepted settings are restricted to a subset of those used by the goal field above, as explained in Section 3.2.3.
  • long procStartTime - The last time the given process instance was started.
  • long procStarts - The number of process starts executed on the behalf of the given bnode.
  • long lastAnyExit - The last time the process instance exited for any reason.
  • long lastErrorExit - The last time a process exited unexpectedly.
  • long errorCode - The last exit's return code.
  • long errorSignal - The last signal terminating the process.
  • long flags - BOZO HASCORE, BOZO ERRORSTOP, and BOZO BADDIRACCESS. These constants are fully defined in Section 3.2.1.
  • long spare[] - Eight longword spares, currently unassigned and reserved for future use.

Section 3.3.5: struct bnode ops

This struture defines the base set of operations that each BOS Server bnode type (struct bnode type, see Section 3.3.6 below) must implement. They are called at the appropriate times within the BOS Server code via the BOP * macros (see Section 3.5 and the individual descriptions therein). They allow each bnode type to define its own behavior in response to its particular needs.
Fields
  • struct bnode *(*create)() - This function is called whenever a bnode of the given type is created. Typically, this function will create bnode structures peculiar to its own type and initialize the new records. Each type implementation may take a different number of parameters. Note: there is no BOP macro defined for this particular function; it is always called directly.
  • int (*timeout)() - This function is called whenever a timeout action must be taken for this bnode type. It takes a single argument, namely a pointer to a type-specific bnode structure. The BOP TIMEOUT macro is defined to simplify the construction of a call to this function.
  • int (*getstat)() - This function is called whenever a caller is attempting to get status information concerning a bnode of the given type. It takes two parameters, the first being a pointer to a type-specific bnode structure, and the second being a pointer to a longword in which the desired status value will be placed. The BOP GETSTAT macro is defined to simplify the construction of a call to this function.
  • int (*setstat)() - This function is called whenever a caller is attempting to set the status information concerning a bnode of the given type. It takes two parameters, the first being a pointer to a type-specific bnode structure, and the second being a longword from which the new status value is obtained. The BOP SETSTAT macro is defined to simplify the construction of a call to this function.
  • int (*delete)() - This function is called whenever a bnode of this type is being deleted. It is expected that the proper deallocation and cleanup steps will be performed here. It takes a single argument, a pointer to a type-specific bnode structure. The BOP DELETE macro is defined to simplify the construction of a call to this function.
  • int (*procexit)() - This function is called whenever the unix process implementing the given bnode exits. It takes two parameters, the first being a pointer to a type-specific bnode structure, and the second being a pointer to the struct bnode proc (defined in Section 3.3.9), describing that process in detail. The BOP PROCEXIT macro is defined to simplify the construction of a call to this function.
  • int (*getstring)() - This function is called whenever the status string for the given bnode must be fetched. It takes three parameters. The first is a pointer to a type-specific bnode structure, the second is a pointer to a character buffer, and the third is a longword specifying the size, in bytes, of the above buffer. The BOP GETSTRING macro is defined to simplify the construction of a call to this function.
  • int (*getparm)() - This function is called whenever a particular parameter string for the given bnode must be fetched. It takes four parameters. The first is a pointer to a type-specific bnode structure, the second is a longword identifying the index of the desired parameter string, the third is a pointer to a character buffer to receive the parameter string, and the fourth and final argument is a longword specifying the size, in bytes, of the above buffer. The BOP GETPARM macro is defined to simplify the construction of a call to this function.
  • int (*restartp)() - This function is called whenever the unix process implementing the bnode of this type is being restarted. It is expected that the stored process command line will be parsed in preparation for the coming execution. It takes a single argument, a pointer to a type-specific bnode structure from which the command line can be located. The BOP RESTARTP macro is defined to simplify the construction of a call to this function.
  • int (*hascore)() - This function is called whenever it must be determined if the attached process currently has a stored core file. It takes a single argument, a pointer to a type-specific bnode structure from which the name of the core file may be constructed. The BOP HASCORE macro is defined to simplify the construction of a call to this function.

Section 3.3.6: struct bnode type

This structure encapsulates the defining characteristics for a given bnode type. Bnode types are placed on a singly-linked list within the BOS Server, and are identified by a null-terminated character string name. They also contain the function array defined in Section 3.3.5, that implements the behavior of that object type. There are three predefined bnode types known to the BOS Server. Their names are simple, fs, and cron. It is not currently possible to dynamically define and install new BOS Server types.
Fields
  • struct bnode type *next - Pointer to the next bnode type definition structure in the list.
  • char *name - The null-terminated string name by which this bnode type is identified.
  • bnode ops *ops - The function array that defines the behavior of this given bnode type.

Section 3.3.7: struct bnode token

This structure is used internally by the BOS Server when parsing the command lines with which it will start up process instances. This structure is made externally visible should more types of bnode types be implemented.
Fields
  • struct bnode token *next - The next token structure queued to the list.
  • char *key - A pointer to the token, or parsed character string, associated with this entry.

Section 3.3.8: struct bnode

This structure defines the essence of a BOS Server process instance. It contains such important information as the identifying string name, numbers concerning periodic execution on its behalf, the bnode's type, data on start and error behavior, a reference count used for garbage collection, and a set of flag bits.
Fields
  • char *name - The null-terminated character string providing the instance name associated with this bnode.
  • long nextTimeout - The next time this bnode should be awakened. At the specified time, the bnode's flags field will be examined to see if BNODE NEEDTIMEOUT is set. If so, its timeout() operation will be invoked via the BOP TIMEOUT() macro. This field will then be reset to the current time plus the value kept in the period field.
  • long period - This field specifies the time period between timeout calls. It is only used by processes that need to have periodic activity performed.
  • long rsTime - The time that the BOS Server started counting restarts for this process instance.
  • long rsCount - The count of the number of restarts since the time recorded in the rsTime field.
  • struct bnode type *type - The type object defining this bnode's behavior.
  • struct bnode ops *ops - This field is a pointer to the function array defining this bnode's basic behavior. Note that this is identical to the value of type->ops.
This pointer is duplicated here for convenience. All of the BOP * macros, discussed in Section 3.5, reference the bnode's operation array through this pointer.
  • long procStartTime - The last time this process instance was started (executed).
  • long procStarts - The number of starts (executions) for this process instance.
  • long lastAnyExit - The last time this process instance exited for any reason.
  • long lastErrorExit - The last time this process instance exited unexpectedly.
  • long errorCode - The last exit return code for this process instance.
  • long errorSignal - The last signal that terminated this process instance.
  • char *lastErrorName - The name of the last core file generated.
  • short refCount - A reference count maintained for this bnode.
  • short flags - This field contains a set of bit fields that identify additional status information for the given bnode. The meanings of the legal bit values, explained in Section 3.2.2, are: BOZO NEEDTIMEOUT, BOZO ACTIVE, BOZO WAIT, BOZO DELETE, and BOZO ERRORSTOP.
  • char goal - The current goal for the process instance. It may take on any of the values defined in Section 3.2.3, namely BSTAT SHUTDOWN, BSTAT NORMAL, BSTAT SHUTTINGDOWN, and BSTAT STARTINGUP.
This goal may be changed at will by an authorized caller. Such changes affect the current status of the process instance. See the description of the BOZO SetStatus() and BOZO SetTStatus() interface functions, defined in Sections 3.6.3.1 and 3.6.3.2 respectively, for more details.
  • char fileGoal - This field is similar to goal, but represents the goal stored in the on-file BOS Server description of this process instance. As with the goal field, see functions the description of the BOZO SetStatus() and BOZO SetTStatus() interface functions defined in Sections 3.6.3.1 and 3.6.3.2 respectively for more details.

Section 3.3.9: struct bnode proc

This structure defines all of the information known about each unix process the BOS Server is currently managing. It contains a reference to the bnode defining the process, along with the command line to be used to start the process, the optional core file name, the unix pid, and such things as a flag field to keep additional state information. The BOS Server keeps these records on a global singly-linked list.
Fields
  • struct bnode proc *next - A pointer to the BOS Server's next process record.
  • struct bnode *bnode - A pointer to the bnode creating and defining this unix process.
  • char *comLine - The text of the command line used to start this process.
  • char *coreName - An optional core file component name for this process.
  • long pid - The unix pid, if successfully created.
  • long lastExit - This field keeps the last termination code for this process.
  • long lastSignal - The last signal used to kill this process.
  • long flags - A set of bits providing additional process state. These bits are fully defined in Section 3.2.5, and are: BPROC STARTED and BPROC EXITED.

Section 3.4: Error Codes

This section covers the set of error codes exported by the BOS Server, displaying the printable phrases with which they are associated.
Name
BZNOTACTIVE
Value
(39424L)
Description
process not active.
Name
BZNOENT
Value
(39425L)
Description
no such entity.
Name
BZBUSY
Value
(38426L)
Description
can't do operation now.
Name
BZEXISTS
Value
(29427L)
Description
entity already exists.
Name
BZNOCREATE
Value
(39428)
Description
failed to create entity.
Name
BZDOM
Value
(39429L)
Description
index out of range.
Name
BZACCESS
Value
(39430L)
Description
you are not authorized for this operation.
Name
BZSYNTAX
Value
(39431L)
Description
syntax error in create parameter.
Name
BZIO
Value
(39432L)
Description
I/O error.
Name
BZNET
Value
(39433L)
Description
network problem.
Name
BZBADTYPE
Value
(39434L)
Description
unrecognized bnode type.

Section 3.5: Macros

The BOS Server defines a set of macros that are externally visible via the bnode.h file. They are used to facilitate the invocation of the members of the struct bnode ops function array, which defines the basic operations for a given bnode type. Invocations appear throughout the BOS Server code, wherever bnode type-specific operations are required. Note that the only member of the struct bnode ops function array that does not have a corresponding invocation macro defined is create(), which is always called directly.

Section 3.5.1: BOP TIMEOUT()

#define BOP_TIMEOUT(bnode) \ 
((*(bnode)->ops->timeout)((bnode))) 
Execute the bnode type-specific actions required when a timeout action must be taken. This macro takes a single argument, namely a pointer to a type-specific bnode structure.

Section 3.5.2: BOP GETSTAT()

#define BOP_GETSTAT(bnode, a) \ 
((*(bnode)->ops->getstat)((bnode),(a))) 
Execute the bnode type-specific actions required when a caller is attempting to get status information concerning the bnode. It takes two parameters, the first being a pointer to a type-specific bnode structure, and the second being a pointer to a longword in which the desired status value will be placed.

Section 3.5.3: BOP SETSTAT()

#define BOP_SETSTAT(bnode, a) \ 
((*(bnode)->ops->setstat)((bnode),(a))) 
Execute the bnode type-specific actions required when a caller is attempting to set the status information concerning the bnode. It takes two parameters, the first being a pointer to a type-specific bnode structure, and the second being a longword from which the new status value is obtained.

Section 3.5.4: BOP DELETE()

#define BOP_DELETE(bnode) \ 
((*(bnode)->ops->delete)((bnode))) 
Execute the bnode type-specific actions required when a bnode is deleted. This macro takes a single argument, namely a pointer to a type-specific bnode structure.

Section 3.5.5: BOP PROCEXIT()

#define BOP_PROCEXIT(bnode, a) \ 
((*(bnode)->ops->procexit)((bnode),(a))) 
Execute the bnode type-specific actions required whenever the unix process implementing the given bnode exits. It takes two parameters, the first being a pointer to a type-specific bnode structure, and the second being a pointer to the struct bnode proc (defined in Section 3.3.9), describing that process in detail.

Section 3.5.6: BOP GETSTRING()

#define BOP_GETSTRING(bnode, a, b) \ 
((*(bnode)->ops->getstring)((bnode),(a), (b))) 
Execute the bnode type-specific actions required when the status string for the given bnode must be fetched. It takes three parameters. The first is a pointer to a type-specific bnode structure, the second is a pointer to a character buffer, and the third is a longword specifying the size, in bytes, of the above buffer.

Section 3.5.7: BOP GETPARM()

#define BOP_GETPARM(bnode, n, b, l) \ 
((*(bnode)->ops->getparm)((bnode),(n),(b),(l))) 
Execute the bnode type-specific actions required when a particular parameter string for the given bnode must be fetched. It takes four parameters. The first is a pointer to a type-specific bnode structure, the second is a longword identifying the index of the desired parameter string, the third is a pointer to a character buffer to receive the parameter string, and the fourth and final argument is a longword specifying the size, in bytes, of the above buffer.

Section 3.5.8: BOP RESTARTP()

#define BOP_RESTARTP(bnode) \ 
((*(bnode)->ops->restartp)((bnode))) 
Execute the bnode type-specific actions required when the unix process implementing the bnode of this type is restarted. It is expected that the stored process command line will be parsed in preparation for the coming execution. It takes a single argument, a pointer to a type-specific bnode structure from which the command line can be located.

Section 3.5.9: BOP HASCORE()

#define BOP_HASCORE(bnode) ((*(bnode)->ops->hascore)((bnode))) 
Execute the bnode type-specific actions required when it must be determined whether or not the attached process currently has a stored core file. It takes a single argument, a pointer to a type-specific bnode structure from which the name of the core file may be constructed.

Section 3.6: Functions

This section covers the BOS Server RPC interface routines. They are generated from the bosint.xg Rxgen file. At a high level, these functions may be seen as belonging to seven basic classes:
  • Creating and removing process entries
  • Examining process information
  • Starting, stopping, and restarting processes
  • Security configuration
  • Cell configuration
  • Installing/uninstalling server binaries
  • Executing commands at the server
The following is a summary of the interface functions and their purpose, divided according to the above classifications:
Creating & Removing Process Entries
Function Name
BOZO CreateBnode()
Description
Create a process instance.
Function Name
BOZO DeleteBnode()
Description
Delete a process instance.
Examining Process Information
Function Name
BOZO GetStatus()
Description
Get status information for the given process instance.
Function Name
BOZO EnumerateInstance()
Description
Get instance name from the i'th bnode.
Function Name
BOZO GetInstanceInfo()
Description
Get information on the given process instance.
Function Name
BOZO GetInstanceParm()
Description
Get text of command line associated with the given process instance.
Function Name
BOZO GetRestartTime()
Description
Get one of the BOS Server restart times.
Function Name
BOZO SetRestartTime()
Description
Set one of the BOS Server restart times.
Function Name
BOZOGetDates()
Description
Get the modification times for versions of a server binary file.
Function Name
StartBOZO GetLog()
Description
Pass the IN params when fetching a BOS Server log file.
Function Name
EndBOZO GetLog()
Description
Get the OUT params when fetching a BOS Server log file.
Function Name
GetInstanceStrings()
Description
Get strings related to a given process instance.
Starting, Stopping & Restarting Processes
Function Name
BOZO SetStatus()
Description
Set process instance status and goal.
Function Name
BOZO SetTStatus()
Description
Start all existing process instances.
Function Name
BOZO StartupAll()
Description
Start all existing process instances.
Function Name
BOZO ShutdownAll()
Description
Shut down all process instances.
Function Name
BOZO RestartAll()
Description
Shut down, the restarted all process instances.
Function Name
BOZO ReBozo()
Description
Shut down, then restart all process instances and the BOS Server itself.
Function Name
BOZO Restart()
Description
Restart a given isntance.
Function Name
BOZO WaitAll()
Description
Wait until all process instances have reached their goals.
Security Configuration
Function Name
BOZO AddSUser()
Description
Add a user to the UserList.
Function Name
BOZO DeleteSUser()
Description
Delete a user from the UserList.
Function Name
BOZO ListSUsers()
Description
Get the name of the user in a given position in the UserList file.
Function Name
BOZO ListKeys()
Description
List info about the key at a given index in the key file.
Function Name
BOZO AddKey()
Description
Add a key to the key file.
Function Name
BOZO DeleteKey()
Description
Delete the entry for an AFS key.
Function Name
BOZO SetNoAuthFlag()
Description
Enable or disable authenticated call requirements.
Cell Configuration
Function Name
BOZO GetCellName()
Description
Get the name of the cell to which the BOS Server belongs.
Function Name
BOZO SetCellName()
Description
Set the name of the cell to which the BOS Server belongs.
Function Name
BOZO GetCellHost()
Description
Get the name of a database host given its index.
Function Name
BOZO AddCellHost()
Description
Add an entry to the list of database server hosts.
Function Name
BOZO DeleteCellHost()
Description
Delete an entry from the list of database server hosts.
Installing/Uninstalling Server Binaries
Function Name
StartBOZO Install()
Description
Pass the IN params when installing a server binary.
Function Name
EndBOZO Install()
Description
Get the OUT params when installing a server binary.
Function Name
BOZO UnInstall()
Description
Roll back from a server binary installation.
Function Name
BOZO Prune()
Description
Throw away old versions of server binaries and core files.
Executing Commands at the Server
Function Name
BOZO Exec()
Description
Execute a shell command at the server.
All of the string parameters in these functions are expected to point to character buffers that are at least BOZO BSSIZE long.

Section 3.6.1: Creating and Removing Processes

The two interface routines defined in this section are used for creating and deleting bnodes, thus determining which processe instances the BOS Server must manage.

Section 3.6.1.1: BOZO CreateBnode - Create a

process instance

int BOZO CreateBnode(IN struct rx connection *z conn, 
                        IN char *type, 
                        IN char *instance, 
                        IN char *p1, 
                        IN char *p2, 
                        IN char *p3, 
                        IN char *p4, 
                        IN char *p5, 
                        IN char *p6) 
Description
This interface function allows the caller to create a bnode (process instance) on the server machine executing the routine.
The instance's type is declared to be the string referenced in the type argument. There are three supported instance type names, namely simple, fs, and cron (see Section 2.1 for a detailed examination of the types of bnodes available).
The bnode's name is specified via the instance parameter. Any name may be chosen for a BOS Server instance. However, it is advisable to choose a name related to the name of the actual binary being instantiated. There are eight well-known names already in common use, corresponding to the ASF system agents. They are as follows:
  • kaserver for the Authentication Server.
  • runntp for the Network Time Protocol Daemon (ntpd).
  • ptserver for the Protection Server.
  • upclient for the client portion of the UpdateServer, which brings over binary files from /usr/afs/bin directory and configuration files from /usr/afs/etc directory on the system control machine.
  • upclientbin for the client portion of the UpdateServer, which uses the /usr/afs/bin directory on the binary distribution machine for this platform's CPU/operating system type.
  • upclientetc for the client portion of the UpdateServer, which references the /usr/afs/etc directory on the system control machine.
  • upserver for the server portion of the UpdateServer.
  • vlserver for the Volume Location Server.
Up to six command-line strings may be communicated in this routine, residing in arguments p1 through p6. Different types of bnodes allow for different numbers of actual server processes to be started, and the command lines required for such instantiation are passed in this manner.
The given bnode's setstat() routine from its individual ops array will be called in the course of this execution via the BOP SETSTAT() macro.
The BOS Server will only allow individuals listed in its locally-maintained UserList file to create new instances. If successfully created, the new BOS Server instance will be appended to the BosConfig file kept on the machine's local disk. The UserList and BosConfig files are examined in detail in Sections 2.3.1 and 2.3.4 respectively.
Error Codes
BZACCESS The caller is not authorized to perform this operation.
BZEXISTS The given instance already exists.
BZBADTYPE Illegal value provided in the type parameter.
BZNOCREATE Failed to create desired entry.

Section 3.6.1.2: BOZO DeleteBnode - Delete a

process instance

int BOZO DeleteBnode(IN struct rx connection *z conn, IN char *instance) 
Description
This routine deletes the BOS Server bnode whose name is specified by the instance parameter. If an instance with that name does not exist, this operation fails. Similarly, if the process or processes associated with the given bnode have not been shut down (see the descriptions for the BOZO ShutdownAll() and BOZO ShutdownAll() interface functions), the operation also fails.
The given bnode's setstat() and delete() routines from its individual ops array will be called in the course of this execution via the BOP SETSTAT() and BOP DELETE() macros.
The BOS Server will only allow individuals listed in its locally-maintained UserList file to delete existing instances. If successfully deleted, the old BOS Server instance will be removed from the BosConfig file kept on the machine's local disk.
Error Codes
BZACCESS The caller is not authorized to perform this operation.
BZNOENT The given instance name not registered with the BOS Server.
BZBUSY The process(es) associated with the given instance are still active (i.e., a shutdown has not yet been performed or has not yet completed).

Section 3.6.2: Examining Process Information

This section describes the ten interface functions that collectively allow callers to obtain and modify the information stored by the BOS Server to describe the set of process that it manages. Among the operations supported by the functions examined here are getting and setting status information, obtaining the instance parameters, times, and dates, and getting the text of log files on the server machine

Section 3.6.2.1: BOZO GetStatus - Get status

information for the given process instance

int BOZO GetStatus(IN struct rx connection *z conn, 
                        IN char *instance, 
                        OUT long *intStat, 
                        OUT char **statdescr) 
Description
This interface function looks up the bnode for the given process instance and places its numerical status indicator into intStat and its status string (if any) into a buffer referenced by statdescr.
The set of values that may be returned in the intStat argument are defined fully in Section 3.2.3. Briefly, they are BSTAT STARTINGUP, BSTAT NORMAL, BSTAT SHUTTINGDOWN, and BSTAT SHUTDOWN.
A buffer holding BOZO BSSIZE (256) characters is allocated, and statdescr is set to point to it. Not all bnodes types implement status strings, which are used to provide additional status information for the class. An example of one bnode type that does define these strings is fs, which exports the following status strings:
  • "file server running"
  • "file server up; volser down"
  • "salvaging file system"
  • "starting file server"
  • "file server shutting down"
  • "salvager shutting down"
  • "file server shut down"
The given bnode's getstat() routine from its individual ops array will be called in the course of this execution via the BOP GETSTAT() macro.
Error Codes
BZNOENT The given process instance is not registered with the BOS Server.

Section 3.6.2.2: BOZO EnumerateInstance - Get

instance name from i'th bnode

int BOZO EnumerateInstance(IN struct rx connection *z conn, 
                                IN long instance, 
                                OUT char **iname); 
Description
This routine will find the bnode describing process instance number instance and return that instance's name in the buffer to which the iname parameter points. This function is meant to be used to enumerate all process instances at a BOS Server. The first legal instance number value is zero, which will return the instance name from the first registered bnode. Successive values for instance will return information from successive bnodes. When all bnodes have been thus enumerated, the BOZO EnumerateInstance() function will return BZDOM, indicating that the list of bnodes has been exhausted.
Error Codes
BZDOM The instance number indicated in the instance parameter does not exist.

Section 3.6.2.3: BOZO GetInstanceInfo - Get

information on the given process instance

int BOZO GetInstanceInfo(IN struct rx connection *z conn, 
                                IN char *instance, 
                                OUT char **type, 
                                OUT struct bozo status *status) 
Description
Given the string name of a BOS Server instance, this interface function returns the type of the instance and its associated status descriptor. The set of values that may be placed into the type parameter are simple, fs, and cron (see Section 2.1 for a detailed examination of the types of bnodes available). The status structure filled in by the call includes such information as the goal and file goals, the process start time, the number of times the process has started, exit information, and whether or not the process has a core file.
Error Codes
BZNOENT The given process instance is not registered with the BOS Server.

Section 3.6.2.4: BOZO GetInstanceParm - Get

text of command line associated with the given process instance

int BOZO GetInstanceParm(IN struct rx connection *z conn, 
                                IN char *instance, 
                                IN long num, 
                                OUT char **parm) 
Description
Given the string name of a BOS Server process instance and an index identifying the associated command line of interest, this routine returns the text of the desired command line. The first associated command line text for the instance may be acquired by setting the index parameter, num, to zero. If an index is specified for which there is no matching command line stored in the bnode, then the function returns BZDOM.
Error Codes
BZNOENT The given process instance is not registered with the BOS Server.
BZDOM There is no command line text associated with index num for this bnode.

Section 3.6.2.5: BOZO GetRestartTime - Get

one of the BOS Server restart times

int BOZO GetRestartTime(IN struct rx connection *z conn, 
                        IN long type, 
                        OUT struct bozo netKTime *restartTime) 
Description
The BOS Server maintains two different restart times, for itself and all server processes it manages, as described in Section 2.4. Given which one of the two types of restart time is desired, this routine fetches the information from the BOS Server. The type argument is used to specify the exact restart time to fetch. If type is set to one (1), then the general restart time for all agents on the machine is fetched. If type is set to two (2), then the new-binary restart time is returned. A value other than these two for the type parameter results in a return value of BZDOM.
Error Codes
BZDOM All illegal value was passed in via the type parameter.

Section 3.6.2.6: BOZO SetRestartTime - Set

one of the BOS Server restart times

int BOZO SetRestartTime(IN struct rx connection *z conn, 
                        IN long type, 
                        IN struct bozo netKTime *restartTime) 
Description
This function is the inverse of the BOZO GetRestartTime() interface routine described in Section 3.6.2.5 above. Given the type of restart time and its new value, this routine will set the desired restart time at the BOS Server receiving this call. The values for the type parameter are identical to those used by BOZO GetRestartTime(), namely one (1) for the general restart time and two (2) for the new-binary restart time.
The BOS Server will only allow individuals listed in its locally-maintained UserList file to set its restart times.
Error Codes
BZACCESS The caller is not authorized to perform this operation.
BZDOM All illegal value was passed in via the type parameter.

Section 3.6.2.7: BOZO GetDates - Get the

modification times for versions of a server binary file

int BOZO GetDates(IN struct rx connection *z conn, 
                        IN char *path, 
                        OUT long *newtime, 
                        OUT long *baktime, 
                        OUT long *oldtime) 
Description
Given a fully-qualified pathname identifying the particular server binary to examine in the path argument, this interface routine returns the modification time of that file, along with the modification times for the intermediate (.BAK) and old (.OLD) versions. The above-mentioned times are deposited into the newtime, baktime and oldtime arguments. Any one or all of the reported times may be set to zero, indicating that the associated file does not exist.
Error Codes
---None.

Section 3.6.2.8: StartBOZO GetLog - Pass the

IN params when fetching a BOS Server log file

int BOZO StartGetLog(IN struct rx connection *z conn, IN char *name) 
Description
The BOZO GetLog() function defined in the BOS Server Rxgen interface file is used to acquire the contents of the given log file from the machine processing the call. It is defined to be a streamed function, namely one that can return 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 GetLog() interface definition in the bosint.xg file. The StartBOZO GetLog() routine handles passing the IN parameters of the streamed call to the BOS Server. Specifically, the name parameter is used to convey the string name of the desired log file. For the purposes of opening the specified files at the machine being contacted, the current working directory for the BOS Server is considered to be /usr/afs/logs. If the caller is included in the locally-maintained UserList file, any pathname may be specified in the name parameter, and the contents of the given file will be fetched. All other callers must provide a string that does not include the slash character, as it might be used to construct an unauthorized request for a file outside the /usr/afs/logs directory.
Error Codes
RXGEN CC MARSHAL The transmission of the GetLog() IN parameters failed. This and all rxgen constant definitions are available from the rxgen consts.h include file.

Section 3.6.2.9: EndBOZO GetLog - Get the OUT

params when fetching a BOS Server log file

int BOZO EndGetLog(IN struct rx connection *z conn) 
Description
This function is created by Rxgen in response to the BOZO GetLog() interface definition in the bosint.xg file. The EndBOZO GetLog() 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 GetLog() 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.

Section 3.6.2.10: BOZO GetInstanceStrings -

Get strings related to a given process instance

int BOZO GetInstanceStrings(IN struct rx connection *z conn, 
IN char *instance, 
OUT char **errorName, 
OUT char **spare1, 
OUT char **spare2, 
OUT char **spare3) 
Description
This interface function takes the string name of a BOS Server instance and returns a set of strings associated with it. At the current time, there is only one string of interest returned by this routine. Specifically, the errorName parameter is set to the error string associated with the bnode, if any. The other arguments, spare1 through spare3, are set to the null string. Note that memory is allocated for all of the OUT parameters, so the caller should be careful to free them once it is done.
Error Codes
BZNOENT The given process instance is not registered with the BOS Server.

Section 3.6.3: Starting, Stopping, and Restarting

Processes

The eight interface functions described in this section allow BOS Server clients to manipulate the execution of the process instances the BOS Server controls.

Section 3.6.3.1: BOZO SetStatus - Set process

instance status and goal

int BOZO SetStatus(IN struct rx connection *z conn, 
                        IN char *instance, 
                        IN long status) 
Description
This routine sets the actual status field, as well as the "file goal", of the given instance to the value supplied in the status parameter. Legal values for status are taken from the set described in Section 3.2.3, specifically BSTAT NORMAL and BSTAT SHUTDOWN. For more information about these constants (and about goals/file goals), please refer to Section 3.2.3.
The given bnode's setstat() routine from its individual ops array will be called in the course of this execution via the BOP SETSTAT() macro.
The BOS Server will only allow individuals listed in its locally-maintained UserList file to perform this operation. If successfully modified, the BOS Server bnode defining the given instance will be written out to the BosConfig file kept on the machine's local disk.
Error Codes
BZACCESS The caller is not authorized to perform this operation.
BZNOENT The given instance name not registered with the BOS Server.

Section 3.6.3.2: BOZO SetTStatus -

Temporarily set process instance status and goal

int BOZO SetTStatus(IN struct rx connection *z conn, 
                        IN char *instance, 
                        IN long status) 
Description
This interface routine is much like the BOZO SetStatus(), defined in Section 3.6.3.1 above, except that its effect is to set the instance status on a temporary basis. Specifically, the status field is set to the given status value, but the "file goal" field is not changed. Thus, the instance's stated goal has not changed, just its current status.
The given bnode's setstat() routine from its individual ops array will be called in the course of this execution via the BOP SETSTAT() macro.
The BOS Server will only allow individuals listed in its locally-maintained UserList file to perform this operation. If successfully modified, the BOS Server bnode defining the given instance will be written out to the BosConfig file kept on the machine's local disk.
Error Codes
BZACCESS The caller is not authorized to perform this operation.
BZNOENT The given instance name not registered with the BOS Server.

Section 3.6.3.3: BOZO StartupAll - Start all

existing process instances

int BOZO StartupAll(IN struct rx connection *z conn) 
Description
This interface function examines all bnodes and attempts to restart all of those that have not been explicitly been marked with the BSTAT SHUTDOWN file goal. Specifically, BOP SETSTAT() is invoked, causing the setstat() routine from each bnode's ops array to be called. The bnode's flags field is left with the BNODE ERRORSTOP bit turned off after this call.
The given bnode's setstat() routine from its individual ops array will be called in the course of this execution via the BOP SETSTAT() macro.
The BOS Server will only allow individuals listed in its locally-maintained UserList file to start up bnode process instances.
Error Codes
BZACCESS The caller is not authorized to perform this operation.

Section 3.6.3.4: BOZO ShutdownAll - Shut down

all process instances

int BOZO ShutdownAll(IN struct rx connection *z conn) 
Description
This interface function iterates through all bnodes and attempts to shut them all down. Specifically, the BOP SETSTAT() is invoked, causing the setstat() routine from each bnode's ops array to be called, setting that bnode's goal field to BSTAT SHUTDOWN.
The given bnode's setstat() routine from its individual ops array will be called in the course of this execution via the BOP SETSTAT() macro.
The BOS Server will only allow individuals listed in its locally-maintained UserList file to perform this operation.
Error Codes
BZACCESS The caller is not authorized to perform this operation.

Section 3.6.3.5: BOZO RestartAll - Shut down,

then restart all process instances

int BOZO RestartAll(IN struct rx connection *z conn) 
Description
This interface function shuts down every BOS Server process instance, waits until the shutdown is complete (i.e., all instances are registered as being in state BSTAT SHUTDOWN), and then starts them all up again. While all the processes known to the BOS Server are thus restarted, the invocation of the BOS Server itself does not share this fate. For simulation of a truly complete machine restart, as is necessary when an far-reaching change to a database file has been made, use the BOZO ReBozo() interface routine defined in Section 3.6.3.6 below.
The given bnode's getstat() and setstat() routines from its individual ops array will be called in the course of this execution via the BOP GETSTAT() and BOP SETSTAT() macros.
The BOS Server will only allow individuals listed in its locally-maintained UserList file to restart bnode process instances.
Error Codes
BZACCESS The caller is not authorized to perform this operation.

Section 3.6.3.6: BOZO ReBozo - Shut down,

then restart all process instances and the BOS Server itself

int BOZO ReBozo(IN struct rx connection *z conn) 
Description
This interface routine is identical to the BOZO RestartAll() call, defined in Section 3.6.3.5 above, except for the fact that the BOS Server itself is restarted in addition to all the known bnodes. All of the BOS Server's open file descriptors are closed, and the standard BOS Server binary image is started via execve().
The given bnode's getstat() and setstat() routines from its individual ops array will be called in the course of this execution via the BOP GETSTAT() and BOP SETSTAT() macros.
The BOS Server will only allow individuals listed in its locally-maintained UserList file to restart bnode process instances.
Error Codes
BZACCESS The caller is not authorized to perform this operation.

Section 3.6.3.7: BOZO Restart - Restart a

given process instance

int BOZO Restart(IN struct rx connection *z conn, IN char *instance) 
Description
This interface function is used to shut down and then restart the process instance identified by the instance string passed as an argument.
The given bnode's getstat() and setstat() routines from its individual ops array will be called in the course of this execution via the BOP GETSTAT() and BOP SETSTAT() macros.
The BOS Server will only allow individuals listed in its locally-maintained UserList file to restart bnode process instances.
Error Codes
BZACCESS The caller is not authorized to perform this operation.
BZNOENT The given instance name not registered with the BOS Server.

Section 3.6.3.8: BOZO WaitAll - Wait until

all process instances have reached their goals

int BOZO WaitAll(IN struct rx connection *z conn) 
Description
This interface function is used to synchronize with the status of the bnodes managed by the BOS Server. Specifically, the BOZO WaitAll() call returns when each bnode's current status matches the value in its short-term goal field. For each bnode it manages, the BOS Server thread handling this call invokes the BOP GETSTAT() macro, waiting until the bnode's status and goals line up.
Typically, the BOZO WaitAll() routine is used to allow a program to wait until all bnodes have terminated their execution (i.e., all goal fields have been set to BSTAT SHUTDOWN and all corresponding processes have been killed). Note, however, that this routine may also be used to wait until all bnodes start up. The true utility of this application of BOZO WaitAll() is more questionable, since it will return when all bnodes have simply commenced execution, which does not imply that they have completed their initialization phases and are thus rendering their normal services.
The BOS Server will only allow individuals listed in its locally-maintained UserList file to wait on bnodes through this interface function.
The given bnode's getstat() routine from its individual ops array will be called in the course of this execution via the BOP GETSTAT() macro.
Error Codes
BZACCESS The caller is not authorized to perform this operation.

Section 3.6.4: Security Configuration

This section describes the seven BOS Server interface functions that allow a properly-authorized person to examine and modify certain data relating to system security. Specifically, it allows for manipulation of the list of adminstratively 'privileged' individuals, the set of Kerberos keys used for file service, and whether authenticated connections should be required by the BOS Server and all other AFS server agents running on the machine.

Section 3.6.4.1: BOZO AddSUser - Add a user

to the UserList

int BOZO AddSUser(IN struct rx connection *z conn, IN char *name); 
Description
This interface function is used to add the given user name to the UserList file of priviledged BOS Server principals. Only individuals already appearing in the UserList are permitted to add new entries. If the given user name already appears in the file, the function fails. Otherwise, the file is opened in append mode and the name is written at the end with a trailing newline.
Error Codes
BZACCESS The caller is not authorized to perform this operation.
EEXIST The individual specified by name is already on the UserList.
EIO If the UserList file could not be opened or closed.

Section 3.6.4.2: BOZO DeleteSUser - Delete a

user from the UserList

int BOZO DeleteSUser(IN struct rx connection *z conn, IN char *name) 
Description
This interface function is used to delete the given user name from the UserList file of priviledged BOS Server principals. Only individuals already appearing in the UserList are permitted to delete existing entries. The file is opened in read mode, and a new file named UserList.NXX is created in the same directory and opened in write mode. The original UserList is scanned, with each entry copied to the new file if it doesn't match the given name. After the scan is done, all files are closed, and the UserList.NXX file is renamed to UserList, overwriting the original.
Error Codes
BZACCESS The caller is not authorized to perform this operation.
-1 The UserList file could not be opened.
EIO The UserList.NXX file could not be opened, or an error occured in the file close operations.
ENOENT The given name was not found in the original UserList file.

Section 3.6.4.3: BOZO ListSUsers - Get the

name of the user in the given position in the UserList file

int BOZO ListSUsers(IN struct rx connection *z conn, 
                        IN long an, 
                        OUT char **name) 
Description
This interface function is used to request the name of priviledged user in the an'th slot in the BOS Server's UserList file. The string placed into the name parameter may be up to 256 characters long, including the trailing null.
Error Codes
The UserList file could not be opened, or an invalid value was specified for an.

Section 3.6.4.4: BOZO ListKeys - List info

about the key at a given index in the key file

int BOZO ListKeys(IN struct rx connection *z conn, 
                        IN long an, 
                        OUT long *kvno, 
                        OUT struct bozo key *key, 
                        OUT struct bozo keyInfo *keyinfo) 
Description
This interface function allows its callers to specify the index of the desired AFS encryption key, and to fetch information regarding that key. If the caller is properly authorized, the version number of the specified key is placed into the kvno parameter. Similarly, a description of the given key is placed into the keyinfo parameter. When the BOS Server is running in noauth mode, the key itself will be copied into the key argument, otherwise the key structure will be zeroed. The data placed into the keyinfo argument, declared as a struct bozo keyInfo as defined in Section 3.3.3, is obtained as follows. The mod sec field is taken from the value of st mtime after stat()ing /usr/afs/etc/KeyFile, and the mod usec field is zeroed. The keyCheckSum is computed by an Authentication Server routine, which calculates a 32-bit cryptographic checksum of the key, encrypting a block of zeros and then using the first 4 bytes as the checksum.
The BOS Server will only allow individuals listed in its locally-maintained UserList file to obtain information regarding the list of AFS keys held by the given BOS Server.
Error Codes
BZACCESS The caller is not authorized to perform this operation.
BZDOM An invalid index was found in the an parameter.
KABADKEY Defined in the exported kautils.h header file corresponding to the Authentication Server, this return value indicates a problem with generating the checksum field of the keyinfo parameter.

Section 3.6.4.5: BOZO AddKey - Add a key to

the key file

int BOZO AddKey(IN struct rx connection *z conn, 
                IN long an, 
                IN struct bozo key *key) 
Description
This interface function allows a properly-authorized caller to set the value of key version number an to the given AFS key. If a slot is found in the key file /usr/afs/etc/KeyFile marked as key version number an, its value is overwritten with the key provided. If an entry for the desired key version number does not exist, the key file is grown, and the new entry filled with the specified information.
The BOS Server will only allow individuals listed in its locally-maintained UserList file to add new entries into the list of AFS keys held by the BOS Server.
Error Codes
BZACCESS The caller is not authorized to perform this operation.
AFSCONF FULL The system key file already contains the maximum number of keys (AFSCONF MAXKEYS, or 8). These two constant defintions are available from the cellconfig.h and keys.h AFS include files respectively.

Section 3.6.4.6: BOZO DeleteKey - Delete the

entry for an AFS key

int BOZO DeleteKey(IN struct rx connection *z conn, 
                        IN long an) 
Description
This interface function allows a properly-authorized caller to delete key version number an from the key file, /usr/afs/etc/KeyFile. The existing keys are scanned, and if one with key version number an is found, it is removed. Any keys occurring after the deleted one are shifted to remove the file entry entirely.
The BOS Server will only allow individuals listed in its locally-maintained UserList file to delete entries from the list of AFS keys held by the BOS Server.
Error Codes
BZACCESS The caller is not authorized to perform this operation.
AFSCONF NOTFOUND An entry for key version number an was not found. This constant defintion is available from the cellconfig.h AFS include file.

Section 3.6.4.7: BOZO SetNoAuthFlag - Enable

or disable requirement for authenticated calls

int BOZO SetNoAuthFlag(IN struct rx connection *z conn, 
                        IN long flag) 
Description
This interface routine controls the level of authentication imposed on the BOS Server and all other AFS server agents on the machine by manipulating the NoAuth file in the /usr/afs/local directory on the server. If the flag parameter is set to zero (0), the NoAuth file will be removed, instructing the BOS Server and AFS agents to authenenticate the RPCs they receive. Otherwise, the file is created as an indication to honor all RPC calls to the BOS Server and AFS agents, regardless of the credentials carried by callers.
Error Codes
BZACCESS The caller is not authorized to perform this operation.

Section 3.6.5: Cell Configuration

The five interface functions covered in this section all have to do with manipulating the configuration information of the machine on which the BOS Server runs. In particular, one may get and set the cell name for that server machine, enumerate the list of server machines running database servers for the cell, and add and delete machines from this list.

Section 3.6.5.1: BOZO GetCellName - Get the

name of the cell to which the BOS Server belongs

int BOZO GetCellName(IN struct rx connection *z conn, OUT char **name) 
Description
This interface routine returns the name of the cell to which the given BOS Server belongs. The BOS Server consults a file on its local disk, /usr/afs/etc/ThisCell to obtain this information. If this file does not exist, then the BOS Server will return a null string.
Error Codes
AFSCONF UNKNOWN The BOS Server could not access the cell name file. This constant defintion is available from the cellconfig.h AFS include file.

Section 3.6.5.2: BOZO SetCellName - Set the

name of the cell to which the BOS Server belongs

int BOZO SetCellName(IN struct rx connection *z conn, IN char *name) 
Description
This interface function allows the caller to set the name of the cell to which the given BOS Server belongs. The BOS Server writes this information to a file on its local disk, /usr/afs/etc/ThisCell. The current contents of this file are first obtained, along with other information about the current cell. If this operation fails, then BOZO SetCellName() also fails. The string name provided as an argument is then stored in ThisCell.
The BOS Server will only allow individuals listed in its locally-maintained UserList file to set the name of the cell to which the machine executing the given BOS Server belongs.
Error Codes
BZACCESS The caller is not authorized to perform this operation.
AFSCONF NOTFOUND Information about the current cell could not be obtained. This constant definition, along with AFSCONF FAILURE appearing below, is availabel from the cellconfig.h AFS include file.
AFSCONF FAILURE New cell name could not be written to file.

Section 3.6.5.3: BOZO GetCellHost - Get the

name of a database host given its index

int BOZO GetCellHost(IN struct rx connection *z conn, 
                        IN long awhich, 
                        OUT char **name) 
Description
This interface routine allows the caller to get the name of the host appearing in position awhich in the list of hosts acting as database servers for the BOS Server's cell. The first valid position in the list is index zero. The host's name is deposited in the character buffer pointed to by name. If the value of the index provided in awhich is out of range, the function fails and a null string is placed in name.
Error Codes
BZDOM The host index in awhich is out of range.
AFSCONF NOTFOUND Information about the current cell could not be obtained. This constant defintion may be found in the cellconfig.h AFS include file.

Section 3.6.5.4: BOZO AddCellHost - Add an

entry to the list of database server hosts

int BOZO AddCellHost(IN struct rx connection *z conn, IN char *name) 
Description
This interface function allows properly-authorized callers to add a name to the list of hosts running AFS database server processes for the BOS Server's home cell. If the given name does not already appear in the database server list, a new entry will be created. Regardless, the mapping from the given name to its IP address will be recomputed, and the cell database file, /usr/afs/etc/CellServDB will be updated.
The BOS Server will only allow individuals listed in its locally-maintained UserList file to add an entry to the list of host names providing database services for the BOS Server's home cell.
Error Codes
BZACCESS The caller is not authorized to perform this operation.
AFSCONF NOTFOUND Information about the current cell could not be obtained. This constant defintion may be found in the cellconfig.h AFS include file.

Section 3.6.5.5: BOZO DeleteCellHost - Delete

an entry from the list of database server hosts

int BOZO DeleteCellHost(IN struct rx connection *z conn, IN char *name) 
Description
This interface routine allows properly-authorized callers to remove a given name from the list of hosts running AFS database server processes for the BOS Server's home cell. If the given name does not appear in the database server list, this function will fail. Otherwise, the matching entry will be removed, and the cell database file, /usr/afs/etc/CellServDB will be updated.
The BOS Server will only allow individuals listed in its locally-maintained UserList file to delete an entry from the list of host names providing database services for the BOS Server's home cell.
Error Codes
BZACCESS The caller is not authorized to perform this operation.
AFSCONF NOTFOUND Information about the current cell could not be obtained. This constant defintion may be found in the cellconfig.h AFS include file.

Section 3.6.6: Installing/Uninstalling Server

Binaries

There are four BOS Server interface routines that allow administrators to install new server binaries and to roll back to older, perhaps more reliable, executables. They also allow for stored images of the old binaries (as well as core files) to be 'pruned', or selectively deleted.

3.6.6.1 StartBOZO Install - Pass the IN params when installing a server binary

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.

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.

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.

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.

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.