mirror of
https://git.openafs.org/openafs.git
synced 2025-01-18 15:00:12 +00:00
54e4133873
Change-Id: I1021d99c2479f9157e5c5b1fef10e5d975b35f86 Reviewed-on: http://gerrit.openafs.org/8130 Tested-by: BuildBot <buildbot@rampaginggeek.com> Reviewed-by: Derrick Brashear <shadow@your-file-system.com>
2477 lines
102 KiB
C++
2477 lines
102 KiB
C++
/*!
|
|
\addtogroup bos-spec BOS Server Interface
|
|
@{
|
|
|
|
\page title 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
|
|
|
|
\par
|
|
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:
|
|
\li 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.
|
|
\li 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.
|
|
\li Collection of information regarding the current status, command line
|
|
parameters, execution history, and log files generated by the set of server
|
|
programs.
|
|
\li 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.
|
|
\li 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.
|
|
\par
|
|
Execution of commands on the server machine. An administrator may execute
|
|
arbitrary unix commands on a machine running the BOS Server.
|
|
\par
|
|
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
|
|
|
|
\par
|
|
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
|
|
|
|
\par
|
|
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.
|
|
\par
|
|
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
|
|
|
|
\par
|
|
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:
|
|
\li 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.
|
|
\li 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.
|
|
\li 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.
|
|
\li 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.
|
|
\li 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.
|
|
\par
|
|
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
|
|
|
|
\par
|
|
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
|
|
|
|
\par
|
|
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:
|
|
\li 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.
|
|
\li 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.
|
|
\par
|
|
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
|
|
|
|
\par
|
|
The descriptions of the members of the AFS server suite fall into three broad
|
|
classes of programs:
|
|
\li 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.
|
|
\li 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.
|
|
\li 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.
|
|
\par
|
|
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
|
|
|
|
\par
|
|
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.
|
|
\par
|
|
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.
|
|
\par
|
|
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:
|
|
\li create()
|
|
\li timeout()
|
|
\li getstat()
|
|
\li setstat()
|
|
\li delete()
|
|
\li procexit()
|
|
\li getstring()
|
|
\li getparm()
|
|
\li restartp()
|
|
\li hascore()
|
|
|
|
\section sec2-2 Section 2.2: BOS Server Directories
|
|
|
|
\par
|
|
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.
|
|
\li /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.
|
|
\li /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.
|
|
\li /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.
|
|
\li /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.
|
|
\li /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
|
|
|
|
\par
|
|
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
|
|
|
|
\par
|
|
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:
|
|
\n joe
|
|
\n schmoe
|
|
|
|
\subsection sec2-3-2 Section 2.3.2: /usr/afs/etc/CellServDB
|
|
|
|
\par
|
|
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:
|
|
\code
|
|
>grand.central.org #DARPA clearinghouse cell
|
|
192.54.226.100 #grand.central.org
|
|
192.54.226.101 #penn.central.org
|
|
\endcode
|
|
|
|
\subsection sec2-3-3 Section 2.3.3: /usr/afs/etc/ThisCell
|
|
|
|
\par
|
|
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:
|
|
\code
|
|
grand.central.org
|
|
\endcode
|
|
|
|
\subsection sec2-3-4 Section 2.3.4: /usr/afs/local/BosConfig
|
|
|
|
\par
|
|
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.
|
|
\par
|
|
The following is the text of the BosConfig file on grand.central.org. A
|
|
discussion of the contents follows immediately afterwards.
|
|
\code
|
|
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
|
|
\endcode
|
|
|
|
\par
|
|
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:
|
|
\code
|
|
restarttime <mask> <day> <hour> <minute>
|
|
<second> checkbintime <mask> <day> <hour>
|
|
<minute> <second>
|
|
\endcode
|
|
|
|
\par
|
|
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.
|
|
\par
|
|
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:
|
|
\code
|
|
bnode <type_name> <instance_name> <goal_val>
|
|
\endcode
|
|
|
|
\par
|
|
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).
|
|
\par
|
|
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.
|
|
\code
|
|
parm <command_line_text>
|
|
\endcode
|
|
|
|
\par
|
|
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
|
|
|
|
\par
|
|
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.
|
|
\par
|
|
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
|
|
|
|
\par
|
|
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:
|
|
\code
|
|
#define AFSCONF_MAXKEYS 8
|
|
struct afsconf_key {
|
|
long kvno;
|
|
char key[8];
|
|
};
|
|
struct afsconf_keys {
|
|
long nkeys;
|
|
struct afsconf_key key[AFSCONF_MAXKEYS];
|
|
};
|
|
\endcode
|
|
\par
|
|
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.
|
|
\par
|
|
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
|
|
|
|
\par
|
|
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:
|
|
\par
|
|
\b Complete \b system \b 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.
|
|
\par
|
|
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.
|
|
\par
|
|
\b New-binary \b 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.
|
|
\par
|
|
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.
|
|
\par
|
|
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
|
|
|
|
\par
|
|
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
|
|
|
|
\par
|
|
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.
|
|
\par
|
|
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.
|
|
\par
|
|
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
|
|
|
|
\par
|
|
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.
|
|
\par
|
|
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.
|
|
\par
|
|
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).
|
|
\par
|
|
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.
|
|
\par
|
|
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.
|
|
\par
|
|
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).
|
|
\par
|
|
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.
|
|
\par
|
|
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
|
|
|
|
\par
|
|
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
|
|
|
|
\par
|
|
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
|
|
|
|
\par
|
|
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.
|
|
\par
|
|
Each subsection is devoted to describing constants falling into each of the
|
|
following categories:
|
|
\li Status bits
|
|
\li Bnode activity bits
|
|
\li Bnode states
|
|
\li Pruning server binaries
|
|
\li Flag bits for struct bnode proc
|
|
\par
|
|
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
|
|
|
|
\par
|
|
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.
|
|
|
|
\par Name
|
|
BOZO HASCORE
|
|
\par Value
|
|
1
|
|
\par Description
|
|
Does this bnode have a stored core file?
|
|
|
|
\par Name
|
|
BOZO ERRORSTOP
|
|
\par Value
|
|
2
|
|
\par Description
|
|
Was this bnode execution shut down because of an excessive number of errors
|
|
(more than 10 in a 10 second period)?
|
|
|
|
\par Name
|
|
BOZO BADDIRACCESS
|
|
\par Value
|
|
3
|
|
\par 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
|
|
|
|
\par
|
|
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.
|
|
|
|
\par Name
|
|
BNODE NEEDTIMEOUT
|
|
\par Value
|
|
0x01
|
|
\par Description
|
|
This bnode is utilizing the timeout mechanism for invoking actions on its
|
|
behalf.
|
|
|
|
\par Name
|
|
BNODE ACTIVE
|
|
\par Value
|
|
0x02
|
|
\par Description
|
|
The given bnode is in active service.
|
|
|
|
\par Name
|
|
BNODE WAIT
|
|
\par Value
|
|
0x04
|
|
\par Description
|
|
Someone is waiting for a status change in this bnode.
|
|
|
|
\par Name
|
|
BNODE DELETE
|
|
\par Value
|
|
0x08
|
|
\par Description
|
|
This bnode should be deleted at the earliest convenience.
|
|
|
|
\par Name
|
|
BNODE ERRORSTOP
|
|
\par Value
|
|
0x10
|
|
\par 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
|
|
|
|
\par
|
|
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.
|
|
|
|
\par Name
|
|
BSTAT SHUTDOWN
|
|
\par Value
|
|
0
|
|
\par Description
|
|
The bnode's execution has been (should be) terminated.
|
|
|
|
\par Name
|
|
BSTAT NORMAL
|
|
\par Value
|
|
1
|
|
\par Description
|
|
The bnode is (should be) executing normally.
|
|
|
|
\par Name
|
|
BSTAT SHUTTINGDOWN
|
|
\par Value
|
|
2
|
|
\par Description
|
|
The bnode is currently being shutdown; execution has not yet ceased.
|
|
|
|
\par Name
|
|
BSTAT STARTINGUP
|
|
\par Value
|
|
3
|
|
\par Description
|
|
The bnode execution is currently being commenced; execution has not yet begun.
|
|
|
|
\subsection sec3-2-4 Section 3.2.4: Pruning Server Binaries
|
|
|
|
\par
|
|
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.
|
|
|
|
\par Name
|
|
BOZO PRUNEOLD
|
|
\par Value
|
|
1
|
|
\par Description
|
|
Prune all server binaries with the *.OLD extension.
|
|
|
|
\par Name
|
|
BOZO PRUNEBAK
|
|
\par Value
|
|
2
|
|
\par Description
|
|
Prune all server binaries with the *.BAK extension.
|
|
|
|
\par Name
|
|
BOZO PRUNECORE
|
|
\par Value
|
|
3
|
|
\par Description
|
|
Prune core files.
|
|
|
|
\subsection sec3-2-5 Section 3.2.5: Flag Bits for struct bnode proc
|
|
|
|
\par
|
|
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.
|
|
|
|
\par Name
|
|
BPROC STARTED
|
|
\par Value
|
|
1
|
|
\par Description
|
|
Has the associated unix process ever been started up?
|
|
|
|
\par Name
|
|
BPROC EXITED
|
|
\par Value
|
|
2
|
|
\par Description
|
|
Has the associated unix process ever exited?
|
|
|
|
\section sec3-3 Section 3.3: Structures
|
|
|
|
\par
|
|
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
|
|
|
|
\par
|
|
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.
|
|
\par
|
|
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.
|
|
|
|
\par Name
|
|
KTIME HOUR
|
|
\par Value
|
|
0x01
|
|
\par Description
|
|
Hour should match.
|
|
|
|
\par Name
|
|
KTIME MIN
|
|
\par Value
|
|
0x02
|
|
\par Description
|
|
Minute should match.
|
|
|
|
\par Name
|
|
KTIME SEC
|
|
\par Value
|
|
0x04
|
|
\par Description
|
|
Second should match.
|
|
|
|
\par Name
|
|
KTIME DAY
|
|
\par Value
|
|
0x08
|
|
\par Description
|
|
Day should match.
|
|
|
|
\par Name
|
|
KTIME TIME
|
|
\par Value
|
|
0x07
|
|
\par Description
|
|
All times should match.
|
|
|
|
\par Name
|
|
KTIME NEVER
|
|
\par Value
|
|
0x10
|
|
\par Description
|
|
Special case: never matches.
|
|
|
|
\par Name
|
|
KTIME NOW
|
|
\par Value
|
|
0x20
|
|
\par Description
|
|
Special case: right now.
|
|
|
|
\n \b Fields
|
|
\li int mask - A field of bit values used to specify which of the following
|
|
field are to be used in computing matches.
|
|
\li short hour - The hour, ranging in value from 0 to 23.
|
|
\li short min - The minute, ranging in value from 0 to 59.
|
|
\li short sec - The second, ranging in value from 0 to 59.
|
|
\li short day - Zero specifies Sunday, other days follow in order.
|
|
|
|
\subsection sec3-3-2 Section 3.3.2: struct bozo key
|
|
|
|
\par
|
|
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.
|
|
\n \b Fields
|
|
\li char data[8] - The array of 8 characters representing an encryption key.
|
|
|
|
\subsection sec3-3-3 Section 3.3.3: struct bozo keyInfo
|
|
|
|
\par
|
|
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.
|
|
\n \b Fields
|
|
\li long mod sec - The time in seconds when the associated key was last
|
|
modified.
|
|
\li 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.
|
|
\li 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.
|
|
\li long spare2 - This longword field is currently unused, and is reserved for
|
|
future use.
|
|
|
|
\subsection sec3-3-4 Section 3.3.4: struct bozo status
|
|
|
|
\par
|
|
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.
|
|
\n \b Fields
|
|
\li 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.
|
|
\li 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.
|
|
\li long procStartTime - The last time the given process instance was started.
|
|
\li long procStarts - The number of process starts executed on the behalf of
|
|
the given bnode.
|
|
\li long lastAnyExit - The last time the process instance exited for any
|
|
reason.
|
|
\li long lastErrorExit - The last time a process exited unexpectedly.
|
|
\li long errorCode - The last exit's return code.
|
|
\li long errorSignal - The last signal terminating the process.
|
|
\li long flags - BOZO HASCORE, BOZO ERRORSTOP, and BOZO BADDIRACCESS. These
|
|
constants are fully defined in Section 3.2.1.
|
|
\li long spare[] - Eight longword spares, currently unassigned and reserved for
|
|
future use.
|
|
|
|
\subsection sec3-3-5 Section 3.3.5: struct bnode ops
|
|
|
|
\par
|
|
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.
|
|
\n \b Fields
|
|
\li 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.
|
|
\li 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.
|
|
\li 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.
|
|
\li 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.
|
|
\li 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.
|
|
\li 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.
|
|
\li 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.
|
|
\li 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.
|
|
\li 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.
|
|
\li 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.
|
|
|
|
\subsection sec3-3-6 Section 3.3.6: struct bnode type
|
|
|
|
\par
|
|
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.
|
|
\n \b Fields
|
|
\li struct bnode type *next - Pointer to the next bnode type definition
|
|
structure in the list.
|
|
\li char *name - The null-terminated string name by which this bnode type is
|
|
identified.
|
|
\li bnode ops *ops - The function array that defines the behavior of this given
|
|
bnode type.
|
|
|
|
\subsection sec3-3-7 Section 3.3.7: struct bnode token
|
|
|
|
\par
|
|
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.
|
|
\n \b Fields
|
|
\li struct bnode token *next - The next token structure queued to the list.
|
|
\li char *key - A pointer to the token, or parsed character string, associated
|
|
with this entry.
|
|
|
|
\subsection sec3-3-8 Section 3.3.8: struct bnode
|
|
|
|
\par
|
|
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.
|
|
\n \b Fields
|
|
\li char *name - The null-terminated character string providing the instance
|
|
name associated with this bnode.
|
|
\li 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.
|
|
\li long period - This field specifies the time period between timeout calls.
|
|
It is only used by processes that need to have periodic activity performed.
|
|
\li long rsTime - The time that the BOS Server started counting restarts for
|
|
this process instance.
|
|
\li long rsCount - The count of the number of restarts since the time recorded
|
|
in the rsTime field.
|
|
\li struct bnode type *type - The type object defining this bnode's behavior.
|
|
\li 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.
|
|
\par
|
|
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.
|
|
\li long procStartTime - The last time this process instance was started
|
|
(executed).
|
|
\li long procStarts - The number of starts (executions) for this process
|
|
instance.
|
|
\li long lastAnyExit - The last time this process instance exited for any
|
|
reason.
|
|
\li long lastErrorExit - The last time this process instance exited
|
|
unexpectedly.
|
|
\li long errorCode - The last exit return code for this process instance.
|
|
\li long errorSignal - The last signal that terminated this process instance.
|
|
\li char *lastErrorName - The name of the last core file generated.
|
|
\li short refCount - A reference count maintained for this bnode.
|
|
\li 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.
|
|
\li 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.
|
|
\par
|
|
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.
|
|
\li 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.
|
|
|
|
\subsection sec3-3-9 Section 3.3.9: struct bnode proc
|
|
|
|
\par
|
|
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.
|
|
\n \b Fields
|
|
\li struct bnode proc *next - A pointer to the BOS Server's next process
|
|
record.
|
|
\li struct bnode *bnode - A pointer to the bnode creating and defining this
|
|
unix process.
|
|
\li char *comLine - The text of the command line used to start this process.
|
|
\li char *coreName - An optional core file component name for this process.
|
|
\li long pid - The unix pid, if successfully created.
|
|
\li long lastExit - This field keeps the last termination code for this
|
|
process.
|
|
\li long lastSignal - The last signal used to kill this process.
|
|
\li 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 sec3-4 Section 3.4: Error Codes
|
|
|
|
\par
|
|
This section covers the set of error codes exported by the BOS Server,
|
|
displaying the printable phrases with which they are associated.
|
|
|
|
\par Name
|
|
BZNOTACTIVE
|
|
\par Value
|
|
(39424L)
|
|
\par Description
|
|
process not active.
|
|
|
|
\par Name
|
|
BZNOENT
|
|
\par Value
|
|
(39425L)
|
|
\par Description
|
|
no such entity.
|
|
|
|
\par Name
|
|
BZBUSY
|
|
\par Value
|
|
(38426L)
|
|
\par Description
|
|
can't do operation now.
|
|
|
|
\par Name
|
|
BZEXISTS
|
|
\par Value
|
|
(29427L)
|
|
\par Description
|
|
entity already exists.
|
|
|
|
\par Name
|
|
BZNOCREATE
|
|
\par Value
|
|
(39428)
|
|
\par Description
|
|
failed to create entity.
|
|
|
|
\par Name
|
|
BZDOM
|
|
\par Value
|
|
(39429L)
|
|
\par Description
|
|
index out of range.
|
|
|
|
\par Name
|
|
BZACCESS
|
|
\par Value
|
|
(39430L)
|
|
\par Description
|
|
you are not authorized for this operation.
|
|
|
|
\par Name
|
|
BZSYNTAX
|
|
\par Value
|
|
(39431L)
|
|
\par Description
|
|
syntax error in create parameter.
|
|
|
|
\par Name
|
|
BZIO
|
|
\par Value
|
|
(39432L)
|
|
\par Description
|
|
I/O error.
|
|
|
|
\par Name
|
|
BZNET
|
|
\par Value
|
|
(39433L)
|
|
\par Description
|
|
network problem.
|
|
|
|
\par Name
|
|
BZBADTYPE
|
|
\par Value
|
|
(39434L)
|
|
\par Description
|
|
unrecognized bnode type.
|
|
|
|
\section sec3-5 Section 3.5: Macros
|
|
|
|
\par
|
|
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.
|
|
|
|
\subsection sec3-5-1 Section 3.5.1: BOP TIMEOUT()
|
|
|
|
\code
|
|
#define BOP_TIMEOUT(bnode) \
|
|
((*(bnode)->ops->timeout)((bnode)))
|
|
\endcode
|
|
\par
|
|
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.
|
|
|
|
\subsection sec3-5-2 Section 3.5.2: BOP GETSTAT()
|
|
|
|
\code
|
|
#define BOP_GETSTAT(bnode, a) \
|
|
((*(bnode)->ops->getstat)((bnode),(a)))
|
|
\endcode
|
|
\par
|
|
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.
|
|
|
|
\subsection sec3-5-3 Section 3.5.3: BOP SETSTAT()
|
|
|
|
\code
|
|
#define BOP_SETSTAT(bnode, a) \
|
|
((*(bnode)->ops->setstat)((bnode),(a)))
|
|
\endcode
|
|
\par
|
|
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.
|
|
|
|
\subsection sec3-5-4 Section 3.5.4: BOP DELETE()
|
|
|
|
\code
|
|
#define BOP_DELETE(bnode) \
|
|
((*(bnode)->ops->delete)((bnode)))
|
|
\endcode
|
|
\par
|
|
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.
|
|
|
|
\subsection sec3-5-5 Section 3.5.5: BOP PROCEXIT()
|
|
|
|
\code
|
|
#define BOP_PROCEXIT(bnode, a) \
|
|
((*(bnode)->ops->procexit)((bnode),(a)))
|
|
\endcode
|
|
\par
|
|
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.
|
|
|
|
\subsection sec3-5-6 Section 3.5.6: BOP GETSTRING()
|
|
|
|
\code
|
|
#define BOP_GETSTRING(bnode, a, b) \
|
|
((*(bnode)->ops->getstring)((bnode),(a), (b)))
|
|
\endcode
|
|
\par
|
|
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.
|
|
|
|
\subsection sec3-5-7 Section 3.5.7: BOP GETPARM()
|
|
|
|
\code
|
|
#define BOP_GETPARM(bnode, n, b, l) \
|
|
((*(bnode)->ops->getparm)((bnode),(n),(b),(l)))
|
|
\endcode
|
|
\par
|
|
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.
|
|
|
|
\subsection sec3-5-8 Section 3.5.8: BOP RESTARTP()
|
|
|
|
\code
|
|
#define BOP_RESTARTP(bnode) \
|
|
((*(bnode)->ops->restartp)((bnode)))
|
|
\endcode
|
|
\par
|
|
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.
|
|
|
|
\subsection sec3-5-9 Section 3.5.9: BOP HASCORE()
|
|
|
|
\code
|
|
#define BOP_HASCORE(bnode) ((*(bnode)->ops->hascore)((bnode)))
|
|
\endcode
|
|
\par
|
|
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 sec3-6 Section 3.6: Functions
|
|
|
|
\par
|
|
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:
|
|
\li Creating and removing process entries
|
|
\li Examining process information
|
|
\li Starting, stopping, and restarting processes
|
|
\li Security configuration
|
|
\li Cell configuration
|
|
\li Installing/uninstalling server binaries
|
|
\li Executing commands at the server
|
|
\par
|
|
The following is a summary of the interface functions and their purpose,
|
|
divided according to the above classifications:
|
|
|
|
\par Creating & Removing Process Entries
|
|
|
|
\par Function Name
|
|
BOZO CreateBnode()
|
|
\par Description
|
|
Create a process instance.
|
|
|
|
\par Function Name
|
|
BOZO DeleteBnode()
|
|
\par Description
|
|
Delete a process instance.
|
|
|
|
\par Examining Process Information
|
|
|
|
\par Function Name
|
|
BOZO GetStatus()
|
|
\par Description
|
|
Get status information for the given process instance.
|
|
|
|
\par Function Name
|
|
BOZO EnumerateInstance()
|
|
\par Description
|
|
Get instance name from the i'th bnode.
|
|
|
|
\par Function Name
|
|
BOZO GetInstanceInfo()
|
|
\par Description
|
|
Get information on the given process instance.
|
|
|
|
\par Function Name
|
|
BOZO GetInstanceParm()
|
|
\par Description
|
|
Get text of command line associated with the given process instance.
|
|
|
|
\par Function Name
|
|
BOZO GetRestartTime()
|
|
\par Description
|
|
Get one of the BOS Server restart times.
|
|
|
|
\par Function Name
|
|
BOZO SetRestartTime()
|
|
\par Description
|
|
Set one of the BOS Server restart times.
|
|
|
|
\par Function Name
|
|
BOZOGetDates()
|
|
\par Description
|
|
Get the modification times for versions of a server binary file.
|
|
|
|
\par Function Name
|
|
StartBOZO GetLog()
|
|
\par Description
|
|
Pass the IN params when fetching a BOS Server log file.
|
|
|
|
\par Function Name
|
|
EndBOZO GetLog()
|
|
\par Description
|
|
Get the OUT params when fetching a BOS Server log file.
|
|
|
|
\par Function Name
|
|
GetInstanceStrings()
|
|
\par Description
|
|
Get strings related to a given process instance.
|
|
|
|
\par Starting, Stopping & Restarting Processes
|
|
|
|
\par Function Name
|
|
BOZO SetStatus()
|
|
\par Description
|
|
Set process instance status and goal.
|
|
|
|
\par Function Name
|
|
BOZO SetTStatus()
|
|
\par Description
|
|
Start all existing process instances.
|
|
|
|
\par Function Name
|
|
BOZO StartupAll()
|
|
\par Description
|
|
Start all existing process instances.
|
|
|
|
\par Function Name
|
|
BOZO ShutdownAll()
|
|
\par Description
|
|
Shut down all process instances.
|
|
|
|
\par Function Name
|
|
BOZO RestartAll()
|
|
\par Description
|
|
Shut down, the restarted all process instances.
|
|
|
|
\par Function Name
|
|
BOZO ReBozo()
|
|
\par Description
|
|
Shut down, then restart all process instances and the BOS Server itself.
|
|
|
|
\par Function Name
|
|
BOZO Restart()
|
|
\par Description
|
|
Restart a given isntance.
|
|
|
|
\par Function Name
|
|
BOZO WaitAll()
|
|
\par Description
|
|
Wait until all process instances have reached their goals.
|
|
|
|
\par Security Configuration
|
|
|
|
\par Function Name
|
|
BOZO AddSUser()
|
|
\par Description
|
|
Add a user to the UserList.
|
|
|
|
\par Function Name
|
|
BOZO DeleteSUser()
|
|
\par Description
|
|
Delete a user from the UserList.
|
|
|
|
\par Function Name
|
|
BOZO ListSUsers()
|
|
\par Description
|
|
Get the name of the user in a given position in the UserList file.
|
|
|
|
\par Function Name
|
|
BOZO ListKeys()
|
|
\par Description
|
|
List info about the key at a given index in the key file.
|
|
|
|
\par Function Name
|
|
BOZO AddKey()
|
|
\par Description
|
|
Add a key to the key file.
|
|
|
|
\par Function Name
|
|
BOZO DeleteKey()
|
|
\par Description
|
|
Delete the entry for an AFS key.
|
|
|
|
\par Function Name
|
|
BOZO SetNoAuthFlag()
|
|
\par Description
|
|
Enable or disable authenticated call requirements.
|
|
|
|
\par Cell Configuration
|
|
|
|
\par Function Name
|
|
BOZO GetCellName()
|
|
\par Description
|
|
Get the name of the cell to which the BOS Server belongs.
|
|
|
|
\par Function Name
|
|
BOZO SetCellName()
|
|
\par Description
|
|
Set the name of the cell to which the BOS Server belongs.
|
|
|
|
\par Function Name
|
|
BOZO GetCellHost()
|
|
\par Description
|
|
Get the name of a database host given its index.
|
|
|
|
\par Function Name
|
|
BOZO AddCellHost()
|
|
\par Description
|
|
Add an entry to the list of database server hosts.
|
|
|
|
\par Function Name
|
|
BOZO DeleteCellHost()
|
|
\par Description
|
|
Delete an entry from the list of database server hosts.
|
|
|
|
\par Installing/Uninstalling Server Binaries
|
|
|
|
\par Function Name
|
|
StartBOZO Install()
|
|
\par Description
|
|
Pass the IN params when installing a server binary.
|
|
|
|
\par Function Name
|
|
EndBOZO Install()
|
|
\par Description
|
|
Get the OUT params when installing a server binary.
|
|
|
|
\par Function Name
|
|
BOZO UnInstall()
|
|
\par Description
|
|
Roll back from a server binary installation.
|
|
|
|
\par Function Name
|
|
BOZO Prune()
|
|
\par Description
|
|
Throw away old versions of server binaries and core files.
|
|
|
|
\par Executing Commands at the Server
|
|
|
|
\par Function Name
|
|
BOZO Exec()
|
|
\par Description
|
|
Execute a shell command at the server.
|
|
|
|
\par
|
|
All of the string parameters in these functions are expected to point to
|
|
character buffers that are at least BOZO BSSIZE long.
|
|
|
|
\subsection sec3-6-1 Section 3.6.1: Creating and Removing Processes
|
|
|
|
\par
|
|
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.
|
|
|
|
\subsubsection sec3-6-1-1 Section 3.6.1.1: BOZO CreateBnode - Create a
|
|
process instance
|
|
|
|
\code
|
|
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)
|
|
\endcode
|
|
\par Description
|
|
This interface function allows the caller to create a bnode (process instance)
|
|
on the server machine executing the routine.
|
|
\par
|
|
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).
|
|
\par
|
|
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:
|
|
\li kaserver for the Authentication Server.
|
|
\li runntp for the Network Time Protocol Daemon (ntpd).
|
|
\li ptserver for the Protection Server.
|
|
\li 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.
|
|
\li 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.
|
|
\li upclientetc for the client portion of the UpdateServer, which
|
|
references the /usr/afs/etc directory on the system control machine.
|
|
\li upserver for the server portion of the UpdateServer.
|
|
\li vlserver for the Volume Location Server.
|
|
\par
|
|
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.
|
|
\par
|
|
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.
|
|
\par
|
|
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.
|
|
\par Error Codes
|
|
BZACCESS The caller is not authorized to perform this operation.
|
|
\n BZEXISTS The given instance already exists.
|
|
\n BZBADTYPE Illegal value provided in the type parameter.
|
|
\n BZNOCREATE Failed to create desired entry.
|
|
|
|
\subsubsection sec3-6-1-2 Section 3.6.1.2: BOZO DeleteBnode - Delete a
|
|
process instance
|
|
|
|
\code
|
|
int BOZO DeleteBnode(IN struct rx connection *z conn, IN char *instance)
|
|
\endcode
|
|
\par 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.
|
|
\par
|
|
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.
|
|
\par
|
|
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.
|
|
\par Error Codes
|
|
BZACCESS The caller is not authorized to perform this operation.
|
|
\n BZNOENT The given instance name not registered with the BOS Server.
|
|
\n 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).
|
|
|
|
\subsection sec3-6-2 Section 3.6.2: Examining Process Information
|
|
|
|
\par
|
|
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
|
|
|
|
\subsubsection sec3-6-2-1 Section 3.6.2.1: BOZO GetStatus - Get status
|
|
information for the given process instance
|
|
|
|
\code
|
|
int BOZO GetStatus(IN struct rx connection *z conn,
|
|
IN char *instance,
|
|
OUT long *intStat,
|
|
OUT char **statdescr)
|
|
\endcode
|
|
\par 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.
|
|
\par
|
|
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.
|
|
\par
|
|
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:
|
|
\li "file server running"
|
|
\li "file server up; volser down"
|
|
\li "salvaging file system"
|
|
\li "starting file server"
|
|
\li "file server shutting down"
|
|
\li "salvager shutting down"
|
|
\li "file server shut down"
|
|
\par
|
|
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.
|
|
\par Error Codes
|
|
BZNOENT The given process instance is not registered with the BOS Server.
|
|
|
|
\subsubsection sec3-6-2-2 Section 3.6.2.2: BOZO EnumerateInstance - Get
|
|
instance name from i'th bnode
|
|
|
|
\code
|
|
int BOZO EnumerateInstance(IN struct rx connection *z conn,
|
|
IN long instance,
|
|
OUT char **iname);
|
|
\endcode
|
|
\par 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.
|
|
\par Error Codes
|
|
BZDOM The instance number indicated in the instance parameter does not exist.
|
|
|
|
\subsubsection sec3-6-2-3 Section 3.6.2.3: BOZO GetInstanceInfo - Get
|
|
information on the given process instance
|
|
|
|
\code
|
|
int BOZO GetInstanceInfo(IN struct rx connection *z conn,
|
|
IN char *instance,
|
|
OUT char **type,
|
|
OUT struct bozo status *status)
|
|
\endcode
|
|
\par 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.
|
|
\par Error Codes
|
|
BZNOENT The given process instance is not registered with the BOS Server.
|
|
|
|
\subsubsection sec3-6-2-4 Section 3.6.2.4: BOZO GetInstanceParm - Get
|
|
text of command line associated with the given process instance
|
|
|
|
\code
|
|
int BOZO GetInstanceParm(IN struct rx connection *z conn,
|
|
IN char *instance,
|
|
IN long num,
|
|
OUT char **parm)
|
|
\endcode
|
|
\par 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.
|
|
\par Error Codes
|
|
BZNOENT The given process instance is not registered with the BOS Server.
|
|
\n BZDOM There is no command line text associated with index num for this
|
|
bnode.
|
|
|
|
\subsubsection sec3-6-2-5 Section 3.6.2.5: BOZO GetRestartTime - Get
|
|
one of the BOS Server restart times
|
|
|
|
\code
|
|
int BOZO GetRestartTime(IN struct rx connection *z conn,
|
|
IN long type,
|
|
OUT struct bozo netKTime *restartTime)
|
|
\endcode
|
|
\par 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.
|
|
\par Error Codes
|
|
BZDOM All illegal value was passed in via the type parameter.
|
|
|
|
\subsubsection sec3-6-2-6 Section 3.6.2.6: BOZO SetRestartTime - Set
|
|
one of the BOS Server restart times
|
|
|
|
\code
|
|
int BOZO SetRestartTime(IN struct rx connection *z conn,
|
|
IN long type,
|
|
IN struct bozo netKTime *restartTime)
|
|
\endcode
|
|
\par 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.
|
|
\par
|
|
The BOS Server will only allow individuals listed in its locally-maintained
|
|
UserList file to set its restart times.
|
|
\par Error Codes
|
|
BZACCESS The caller is not authorized to perform this operation.
|
|
\n BZDOM All illegal value was passed in via the type parameter.
|
|
|
|
\subsubsection sec3-6-2-7 Section 3.6.2.7: BOZO GetDates - Get the
|
|
modification times for versions of a server binary file
|
|
|
|
\code
|
|
int BOZO GetDates(IN struct rx connection *z conn,
|
|
IN char *path,
|
|
OUT long *newtime,
|
|
OUT long *baktime,
|
|
OUT long *oldtime)
|
|
\endcode
|
|
\par 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.
|
|
\par Error Codes
|
|
---None.
|
|
|
|
\subsubsection sec3-6-2-8 Section 3.6.2.8: StartBOZO GetLog - Pass the
|
|
IN params when fetching a BOS Server log file
|
|
|
|
\code
|
|
int BOZO StartGetLog(IN struct rx connection *z conn, IN char *name)
|
|
\endcode
|
|
\par 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].
|
|
\par
|
|
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.
|
|
\par 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.
|
|
|
|
\subsubsection sec3-6-2-9 Section 3.6.2.9: EndBOZO GetLog - Get the OUT
|
|
params when fetching a BOS Server log file
|
|
|
|
\code
|
|
int BOZO EndGetLog(IN struct rx connection *z conn)
|
|
\endcode
|
|
\par 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.
|
|
\par Error Codes
|
|
---Always returns successfully.
|
|
|
|
\subsubsection sec3-6-2-10 Section 3.6.2.10: BOZO GetInstanceStrings -
|
|
Get strings related to a given process instance
|
|
|
|
\code
|
|
int BOZO GetInstanceStrings(IN struct rx connection *z conn,
|
|
IN char *instance,
|
|
OUT char **errorName,
|
|
OUT char **spare1,
|
|
OUT char **spare2,
|
|
OUT char **spare3)
|
|
\endcode
|
|
\par 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.
|
|
\par Error Codes
|
|
BZNOENT The given process instance is not registered with the BOS Server.
|
|
|
|
\subsection sec3-6-3 Section 3.6.3: Starting, Stopping, and Restarting
|
|
Processes
|
|
|
|
\par
|
|
The eight interface functions described in this section allow BOS Server
|
|
clients to manipulate the execution of the process instances the BOS Server
|
|
controls.
|
|
|
|
\subsubsection sec3-6-3-1 Section 3.6.3.1: BOZO SetStatus - Set process
|
|
instance status and goal
|
|
|
|
\code
|
|
int BOZO SetStatus(IN struct rx connection *z conn,
|
|
IN char *instance,
|
|
IN long status)
|
|
\endcode
|
|
\par 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.
|
|
\par
|
|
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.
|
|
\par
|
|
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.
|
|
\par Error Codes
|
|
BZACCESS The caller is not authorized to perform this operation.
|
|
\n BZNOENT The given instance name not registered with the BOS Server.
|
|
|
|
\subsubsection sec3-6-3-2 Section 3.6.3.2: BOZO SetTStatus -
|
|
Temporarily set process instance status and goal
|
|
|
|
\code
|
|
int BOZO SetTStatus(IN struct rx connection *z conn,
|
|
IN char *instance,
|
|
IN long status)
|
|
\endcode
|
|
\par 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.
|
|
\par
|
|
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.
|
|
\par
|
|
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.
|
|
\par Error Codes
|
|
BZACCESS The caller is not authorized to perform this operation.
|
|
\n BZNOENT The given instance name not registered with the BOS Server.
|
|
|
|
\subsubsection sec3-6-3-3 Section 3.6.3.3: BOZO StartupAll - Start all
|
|
existing process instances
|
|
|
|
\code
|
|
int BOZO StartupAll(IN struct rx connection *z conn)
|
|
\endcode
|
|
\par 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.
|
|
\par
|
|
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.
|
|
\par
|
|
The BOS Server will only allow individuals listed in its locally-maintained
|
|
UserList file to start up bnode process instances.
|
|
\par Error Codes
|
|
BZACCESS The caller is not authorized to perform this operation.
|
|
|
|
\subsubsection sec3-6-3-4 Section 3.6.3.4: BOZO ShutdownAll - Shut down
|
|
all process instances
|
|
|
|
\code
|
|
int BOZO ShutdownAll(IN struct rx connection *z conn)
|
|
\endcode
|
|
\par 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.
|
|
\par
|
|
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.
|
|
\par
|
|
The BOS Server will only allow individuals listed in its locally-maintained
|
|
UserList file to perform this operation.
|
|
\par Error Codes
|
|
BZACCESS The caller is not authorized to perform this operation.
|
|
|
|
\subsubsection sec3-6-3-5 Section 3.6.3.5: BOZO RestartAll - Shut down,
|
|
then restart all process instances
|
|
|
|
\code
|
|
int BOZO RestartAll(IN struct rx connection *z conn)
|
|
\endcode
|
|
\par 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.
|
|
\par
|
|
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.
|
|
\par
|
|
The BOS Server will only allow individuals listed in its locally-maintained
|
|
UserList file to restart bnode process instances.
|
|
\par Error Codes
|
|
BZACCESS The caller is not authorized to perform this operation.
|
|
|
|
\subsubsection sec3-6-3-6 Section 3.6.3.6: BOZO ReBozo - Shut down,
|
|
then restart all process instances and the BOS Server itself
|
|
|
|
\code
|
|
int BOZO ReBozo(IN struct rx connection *z conn)
|
|
\endcode
|
|
\par 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().
|
|
\par
|
|
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.
|
|
\par
|
|
The BOS Server will only allow individuals listed in its locally-maintained
|
|
UserList file to restart bnode process instances.
|
|
\par Error Codes
|
|
BZACCESS The caller is not authorized to perform this operation.
|
|
|
|
\subsubsection sec3-6-3-7 Section 3.6.3.7: BOZO Restart - Restart a
|
|
given process instance
|
|
|
|
\code
|
|
int BOZO Restart(IN struct rx connection *z conn, IN char *instance)
|
|
\endcode
|
|
\par Description
|
|
This interface function is used to shut down and then restart the process
|
|
instance identified by the instance string passed as an argument.
|
|
\par
|
|
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.
|
|
\par
|
|
The BOS Server will only allow individuals listed in its locally-maintained
|
|
UserList file to restart bnode process instances.
|
|
\par Error Codes
|
|
BZACCESS The caller is not authorized to perform this operation.
|
|
\n BZNOENT The given instance name not registered with the BOS Server.
|
|
|
|
\subsubsection sec3-6-3-8 Section 3.6.3.8: BOZO WaitAll - Wait until
|
|
all process instances have reached their goals
|
|
|
|
\code
|
|
int BOZO WaitAll(IN struct rx connection *z conn)
|
|
\endcode
|
|
\par 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.
|
|
\par
|
|
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.
|
|
\par
|
|
The BOS Server will only allow individuals listed in its locally-maintained
|
|
UserList file to wait on bnodes through this interface function.
|
|
\par
|
|
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.
|
|
\par Error Codes
|
|
BZACCESS The caller is not authorized to perform this operation.
|
|
|
|
\subsection sec3-6-4 Section 3.6.4: Security Configuration
|
|
|
|
\par
|
|
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.
|
|
|
|
\subsubsection sec3-6-4-1 Section 3.6.4.1: BOZO AddSUser - Add a user
|
|
to the UserList
|
|
|
|
\code
|
|
int BOZO AddSUser(IN struct rx connection *z conn, IN char *name);
|
|
\endcode
|
|
\par 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.
|
|
\par Error Codes
|
|
BZACCESS The caller is not authorized to perform this operation.
|
|
\n EEXIST The individual specified by name is already on the UserList.
|
|
\n EIO If the UserList file could not be opened or closed.
|
|
|
|
\subsubsection sec3-6-4-2 Section 3.6.4.2: BOZO DeleteSUser - Delete a
|
|
user from the UserList
|
|
|
|
\code
|
|
int BOZO DeleteSUser(IN struct rx connection *z conn, IN char *name)
|
|
\endcode
|
|
\par 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.
|
|
\par Error Codes
|
|
BZACCESS The caller is not authorized to perform this operation.
|
|
\n -1 The UserList file could not be opened.
|
|
\n EIO The UserList.NXX file could not be opened, or an error occured in the
|
|
file close operations.
|
|
\n ENOENT The given name was not found in the original UserList file.
|
|
|
|
\subsubsection sec3-6-4-3 Section 3.6.4.3: BOZO ListSUsers - Get the
|
|
name of the user in the given position in the UserList file
|
|
|
|
\code
|
|
int BOZO ListSUsers(IN struct rx connection *z conn,
|
|
IN long an,
|
|
OUT char **name)
|
|
\endcode
|
|
\par 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.
|
|
\par Error Codes
|
|
The UserList file could not be opened, or an invalid value was specified for
|
|
an.
|
|
|
|
\subsubsection sec3-6-4-4 Section 3.6.4.4: BOZO ListKeys - List info
|
|
about the key at a given index in the key file
|
|
|
|
\code
|
|
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)
|
|
\endcode
|
|
\par 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.
|
|
\par
|
|
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.
|
|
\par Error Codes
|
|
BZACCESS The caller is not authorized to perform this operation.
|
|
\n BZDOM An invalid index was found in the an parameter.
|
|
\n 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.
|
|
|
|
\subsubsection sec3-6-4-5 Section 3.6.4.5: BOZO AddKey - Add a key to
|
|
the key file
|
|
|
|
\code
|
|
int BOZO AddKey(IN struct rx connection *z conn,
|
|
IN long an,
|
|
IN struct bozo key *key)
|
|
\endcode
|
|
\par 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.
|
|
\par
|
|
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.
|
|
\par Error Codes
|
|
BZACCESS The caller is not authorized to perform this operation.
|
|
\n 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.
|
|
|
|
\subsubsection sec3-6-4-6 Section 3.6.4.6: BOZO DeleteKey - Delete the
|
|
entry for an AFS key
|
|
|
|
\code
|
|
int BOZO DeleteKey(IN struct rx connection *z conn,
|
|
IN long an)
|
|
\endcode
|
|
\par 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.
|
|
\par
|
|
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.
|
|
\par Error Codes
|
|
BZACCESS The caller is not authorized to perform this operation.
|
|
\n AFSCONF NOTFOUND An entry for key version number an was not found. This
|
|
constant defintion is available from the cellconfig.h AFS include file.
|
|
|
|
\subsubsection sec3-6-4-7 Section 3.6.4.7: BOZO SetNoAuthFlag - Enable
|
|
or disable requirement for authenticated calls
|
|
|
|
\code
|
|
int BOZO SetNoAuthFlag(IN struct rx connection *z conn,
|
|
IN long flag)
|
|
\endcode
|
|
\par 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.
|
|
\par Error Codes
|
|
BZACCESS The caller is not authorized to perform this operation.
|
|
|
|
\subsection sec3-6-5 Section 3.6.5: Cell Configuration
|
|
|
|
\par
|
|
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.
|
|
|
|
\subsubsection sec3-6-5-1 Section 3.6.5.1: BOZO GetCellName - Get the
|
|
name of the cell to which the BOS Server belongs
|
|
|
|
\code
|
|
int BOZO GetCellName(IN struct rx connection *z conn, OUT char **name)
|
|
\endcode
|
|
\par 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.
|
|
\par 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.
|
|
|
|
\subsubsection sec3-6-5-2 Section 3.6.5.2: BOZO SetCellName - Set the
|
|
name of the cell to which the BOS Server belongs
|
|
|
|
\code
|
|
int BOZO SetCellName(IN struct rx connection *z conn, IN char *name)
|
|
\endcode
|
|
\par 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.
|
|
\par
|
|
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.
|
|
\par Error Codes
|
|
BZACCESS The caller is not authorized to perform this operation.
|
|
\n 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.
|
|
\n AFSCONF FAILURE New cell name could not be written to file.
|
|
|
|
\subsubsection sec3-6-5-3 Section 3.6.5.3: BOZO GetCellHost - Get the
|
|
name of a database host given its index
|
|
|
|
\code
|
|
int BOZO GetCellHost(IN struct rx connection *z conn,
|
|
IN long awhich,
|
|
OUT char **name)
|
|
\endcode
|
|
\par 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.
|
|
\par Error Codes
|
|
BZDOM The host index in awhich is out of range.
|
|
\n AFSCONF NOTFOUND Information about the current cell could not be obtained.
|
|
This constant defintion may be found in the cellconfig.h AFS include file.
|
|
|
|
\subsubsection sec3-6-5-4 Section 3.6.5.4: BOZO AddCellHost - Add an
|
|
entry to the list of database server hosts
|
|
|
|
\code
|
|
int BOZO AddCellHost(IN struct rx connection *z conn, IN char *name)
|
|
\endcode
|
|
\par 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.
|
|
\par
|
|
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.
|
|
\par Error Codes
|
|
BZACCESS The caller is not authorized to perform this operation.
|
|
\n AFSCONF NOTFOUND Information about the current cell could not be obtained.
|
|
This constant defintion may be found in the cellconfig.h AFS include file.
|
|
|
|
\subsubsection sec3-6-5-5 Section 3.6.5.5: BOZO DeleteCellHost - Delete
|
|
an entry from the list of database server hosts
|
|
|
|
\code
|
|
int BOZO DeleteCellHost(IN struct rx connection *z conn, IN char *name)
|
|
\endcode
|
|
\par 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.
|
|
\par
|
|
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.
|
|
\par Error Codes
|
|
BZACCESS The caller is not authorized to perform this operation.
|
|
\n AFSCONF NOTFOUND Information about the current cell could not be obtained.
|
|
This constant defintion may be found in the cellconfig.h AFS include file.
|
|
|
|
\subsection sec3-6-6 Section 3.6.6: Installing/Uninstalling Server
|
|
Binaries
|
|
|
|
\par
|
|
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
|
|
|
|
\code
|
|
int StartBOZO Install(IN struct rx connection *z conn,
|
|
IN char *path,
|
|
IN long size,
|
|
IN long flags,
|
|
IN long date)
|
|
\endcode
|
|
\par 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].
|
|
\par
|
|
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.
|
|
\par
|
|
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.
|
|
\par
|
|
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.
|
|
\par Error Codes
|
|
BZACCESS The caller is not authorized to perform this operation.
|
|
\n 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.
|
|
\n 101 More than size bytes were delivered to the BOS Server in the RPC
|
|
transfer of the executable image.
|
|
\n 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
|
|
|
|
\code
|
|
int EndBOZO Install(IN struct rx connection *z conn)
|
|
\endcode
|
|
\par 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.
|
|
\par Error Codes
|
|
---Always returns successfully.
|
|
|
|
\subsubsection sec3-6-6-3 Section 3.6.6.3: BOZO UnInstall - Roll back
|
|
from a server binary installation
|
|
|
|
\code
|
|
int BOZO UnInstall(IN struct rx connection *z conn, IN char *path)
|
|
\endcode
|
|
\par 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.
|
|
\par
|
|
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.
|
|
\par 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
|
|
|
|
\code
|
|
int BOZO Prune(IN struct rx connection *z conn, IN long flags)
|
|
\endcode
|
|
\par 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.
|
|
\par
|
|
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.
|
|
\par 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
|
|
|
|
\par
|
|
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
|
|
|
|
\code
|
|
int BOZO Exec(IN struct rx connection *z conn, IN char *cmd)
|
|
\endcode
|
|
\par 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.
|
|
\par
|
|
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.
|
|
\par Error Codes
|
|
BZACCESS The caller is not authorized to perform this operation.
|
|
|
|
\page biblio Bibliography
|
|
|
|
\li [1] CMU Information Technology Center. Synchronization and Caching
|
|
Issues in the Andrew File System, USENIX Proceedings, Dallas, TX, Winter 1988.
|
|
\li [2] Transarc Corporation. AFS 3.0 Command Reference Manual, F-30-0-D103,
|
|
Pittsburgh, PA, April 1990.
|
|
\li [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.
|
|
\li [4] Zayas, Edward R., Transarc Corporation. AFS-3 Programmer's Reference:
|
|
File Server/Cache Manager Interface, FS-00-D162, Pittsburgh, PA, April 1991.
|
|
\li [5] Transarc Corporation. AFS 3.0 System Administrator's Guide,
|
|
F-30-0-D102, Pittsburgh, PA, April 1990.
|
|
\li [6] Kazar, Michael L., Information Technology Center, Carnegie Mellon
|
|
University. Ubik -A Library For Managing Ubiquitous Data, ITCID, Pittsburgh,
|
|
PA, Month, 1988.
|
|
\li [7] Kazar, Michael L., Information Technology Center, Carnegie Mellon
|
|
University. Quorum Completion, ITCID, Pittsburgh, PA, Month, 1988.
|
|
\li [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.
|
|
|
|
@}
|
|
*/
|
|
|