Provided by: openafs-client_1.4.1-2_i386 bug

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 setauth, bos setrestart,
           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), and when the BOS
           Server restarts processes that have new binary files (by default
           once per day). To administer the BosConfig file, use the following
           commands: bos create, bos delete, bos getrestart, bos setrestart,
           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

       the BosConfig(5) manpage, the CellServDB(5) manpage, the KeyFile(5)
       manpage, the ThisCell(5) manpage, the UserList(5) manpage, the
       bos_addhost(8) manpage, the bos_addkey(8) manpage, the bos_adduser(8)
       manpage, the bos_apropos(8) manpage, the bos_create(8) manpage, the
       bos_delete(8) manpage, the bos_exec(8) manpage, the bos_getdate(8)
       manpage, the bos_getlog(8) manpage, the bos_getrestart(8) manpage, the
       bos_help(8) manpage, the bos_install(8) manpage, the bos_listhosts(8)
       manpage, the bos_listkeys(8) manpage, the bos_listusers(8) manpage, the
       bos_prune(8) manpage, the bos_removehost(8) manpage, the
       bos_removekey(8) manpage, the bos_removeuser(8) manpage, the
       bos_restart(8) manpage, the bos_salvage(8) manpage, the bos_setauth(8)
       manpage, the bos_setcellname(8) manpage, the bos_setrestart(8) manpage,
       the bos_shutdown(8) manpage, the bos_start(8) manpage, the
       bos_startup(8) manpage, the bos_status(8) manpage, the bos_stop(8)
       manpage, the bos_uninstall(8) manpage

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.