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.

       •   A command to display the OpenAFS command suite version: bos 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/KeyFileExt file lists additional server encryption keys that
           the server processes can use to decrypt tickets presented by client processes and one
           another. These keys are strong encryption keys used by the rxkad-k5 extension; use
           asetkey(8) to manage the KeyFileExt.

       •   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 or
           /etc/openafs/server/KeyFileExt 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 or /etc/openafs/server/KeyFileExt 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.example.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), KeyFileExt(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.