Provided by: openafs-client_1.6.15-1ubuntu1.1_amd64 
NAME
bos - Introduction to the bos command suite
DESCRIPTION
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 command suite:
• Commands to administer server process binary files: bos getdate, bos install, bos prune, and bos
uninstall.
• 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 setcellname.
• 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 salvage.
• Commands to obtain help: bos apropos and bos help.
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 removeuser.
• 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 encounters.
For more details, see the reference page for each file.
OPTIONS
The following arguments and flags are available on many commands in the bos 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 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.
-help
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.
-localauth
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.
-noauth
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.
PRIVILEGE REQUIRED
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 argument.
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 listkeys command), no privilege
is required.
SEE ALSO
BosConfig(5), CellServDB(5), KeyFile(5), ThisCell(5), UserList(5), bos_addhost(8), bos_addkey(8),
bos_adduser(8), bos_apropos(8), bos_create(8), bos_delete(8), bos_exec(8), bos_getdate(8), bos_getlog(8),
bos_getrestart(8), bos_getrestricted(8), bos_help(8), bos_install(8), bos_listhosts(8), bos_listkeys(8),
bos_listusers(8), bos_prune(8), bos_removehost(8), bos_removekey(8), bos_removeuser(8), bos_restart(8),
bos_salvage(8), bos_setauth(8), bos_setcellname(8), bos_setrestart(8), bos_setrestricted(8),
bos_shutdown(8), bos_start(8), bos_startup(8), bos_status(8), bos_stop(8), bos_uninstall(8)
COPYRIGHT
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.
OpenAFS 2021-04-01 BOS(8)