bos - Introduction to the bos command suite
The commands in the bos
command suite are the administrative interface to
the Basic OverSeer (BOS) Server, which runs on every file server machine to
monitor the other server processes on it. If a process fails, the BOS Server
can restart it automatically, taking into account interdependencies between it
and other processes. The BOS Server frees system administrators from
constantly monitoring the status of server machines and processes.
There are several categories of commands in the bos
- Commands to administer server process binary files: bos
getdate, bos install, bos prune, and bos
- Commands to maintain system configuration files: bos
addhost, bos addkey, bos adduser, bos
listhosts, bos listkeys, bos listusers, bos
removehost, bos removekey, bos removeuser, and bos
- Commands to start and stop processes: bos create,
bos delete, bos restart, bos shutdown, bos
start, bos startup, and bos stop.
- Commands to set and verify server process and server
machine status: bos getlog, bos getrestart, bos
getrestricted, bos setauth, bos setrestart, bos
setrestricted and bos status.
- A command to restore file system consistency: bos
- Commands to obtain help: bos apropos and bos
- A command to display the OpenAFS command suite version:
The BOS Server and the bos
commands use and maintain the following
configuration and log files:
- The /etc/openafs/server/CellServDB file lists the
local cell's database server machines. These machines run the
Authentication, Backup, Protection and Volume Location (VL) Server
processes, which maintain databases of administrative information. The
database server processes consult the file to learn about their peers,
whereas the other server processes consult it to learn where to access
database information as needed. To administer the CellServDB file,
use the following commands: bos addhost, bos
listhosts, bos removehost, and bos setcellname.
- The /etc/openafs/server/KeyFile file lists the
server encryption keys that the server processes use to decrypt tickets
presented by client processes and one another. To administer the
KeyFile file, use the following commands: bos addkey, bos
listkeys, and bos removekey.
- The /etc/openafs/server/ThisCell file defines the
cell to which the server machine belongs for the purposes of
server-to-server communication. Administer it with the bos
setcellname command. There is also a /etc/openafs/ThisCell file
that defines the machine's cell membership with respect to the AFS command
suites and Cache Manager access to AFS data.
- The /etc/openafs/server/UserList file lists the user
name of each administrator authorized to issue privileged bos and
vos commands. To administer the UserList file, use the
following commands: bos adduser, bos listusers, and bos
- The /etc/openafs/BosConfig file defines which AFS
server processes run on the server machine, and whether the BOS Server
restarts them automatically if they fail. It also defines when all
processes restart automatically (by default once per week), when the BOS
Server restarts processes that have new binary files (by default once per
day), and whether the BOS Server will start in restricted mode. To
administer the BosConfig file, use the following commands:
bos create, bos delete, bos getrestart, bos
getrestricted, bos setrestart, bos setrestricted,
bos start, and bos stop.
- The /usr/afs/log/BosLog file records important
operations the BOS Server performs and error conditions it
For more details, see the reference page for each file.
The following arguments and flags are available on many commands in the
suite. The reference page for each command also lists them, but
they are described here in greater detail.
- -cell <cell name>
- Names the cell in which to run the command. It is
acceptable to abbreviate the cell name to the shortest form that
distinguishes it from the other entries in the
/etc/openafs/CellServDB file on the local machine. If the
-cell argument is omitted, the command interpreter determines the
name of the local cell by reading the following in order:
- The value of the AFSCELL environment variable.
- The local /etc/openafs/ThisCell file.
Do not combine the -cell
options. A command on
which the -localauth
flag is included always runs in the local cell (as
defined in the server machine's local /etc/openafs/server/ThisCell
file), whereas a command on which the -cell
argument is included runs
in the specified foreign cell.
- Prints a command's online help message on the standard
output stream. Do not combine this flag with any of the command's other
options; when it is provided, the command interpreter ignores all other
options, and only prints the help message.
- Constructs a server ticket using the server encryption key
with the highest key version number in the local
/etc/openafs/server/KeyFile file. The bos command
interpreter presents the ticket, which never expires, to the BOS Server
during mutual authentication.
Use this flag only when issuing a command on a server machine; client
machines do not usually have a /etc/openafs/server/KeyFile file.
The issuer of a command that includes this flag must be logged on to the
server machine as the local superuser "root". The flag is useful
for commands invoked by an unattended application program, such as a
process controlled by the UNIX cron utility or by a cron entry in
the machine's /etc/openafs/BosConfig file. It is also useful if an
administrator is unable to authenticate to AFS but is logged in as the
local superuser "root".
Do not combine the -cell and -localauth options. A command on
which the -localauth flag is included always runs in the local cell
(as defined in the server machine's local
/etc/openafs/server/ThisCell file), whereas a command on which the
-cell argument is included runs in the specified foreign cell.
Also, do not combine the -localauth and -noauth flags.
- Establishes an unauthenticated connection to the BOS
Server, in which the BOS Server treats the issuer as the unprivileged user
"anonymous". It is useful only when authorization checking is
disabled on the server machine (during the installation of a file server
machine or when the bos setauth command has been used during
other unusual circumstances). In normal circumstances, the BOS Server
allows only privileged users to issue commands that change the status of a
server or configuration file, and refuses to perform such an action even
if the -noauth flag is provided. Do not combine the -noauth
and -localauth flags.
- -server <machine name>
- Indicates the AFS server machine on which to run the
command. Identify the machine by its IP address in dotted decimal format,
its fully-qualified host name (for example, "fs1.abc.com"), or
by an abbreviated form of its host name that distinguishes it from other
machines. Successful use of an abbreviated form depends on the
availability of a name service (such as the Domain Name Service or a local
host table) at the time the command is issued.
For the commands that alter the administrative files shared by all server
machines in the cell (the bos addhost, bos addkey, bos
adduser, bos removehost, bos removekey, and bos
removeuser commands), the appropriate machine depends on whether the
cell uses the United States or international version of AFS:
- If the cell (as recommended) uses the Update Server to
distribute the contents of the /etc/openafs/server directory,
provide the name of the system control machine. After issuing the command,
allow up to five minutes for the Update Server to distribute the changed
file to the other AFS server machines in the cell. If the specified
machine is not the system control machine but is running an
upclient process that refers to the system control machine, then
the change will be overwritten when the process next brings over the
relevant file from the system control machine.
- Otherwise, repeatedly issue the command, naming each of the
cell's server machines in turn. To avoid possible inconsistency problems,
finish issuing the commands within a fairly short time.
To issue any bos command that changes a configuration file or alters process
status, the issuer must be listed in the /etc/openafs/server/UserList
file on the server machine named by the -server
Alternatively, if the -localauth
flag is included the issuer must be
logged on as the local superuser "root".
To issue a bos command that only displays information (other than the bos
command), no privilege is required.
IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
This documentation is covered by the IBM Public License Version 1.0. It was
converted from HTML to POD by software written by Chas Williams and Russ
Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.