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 command suite:
Commands to administer server process binary files: bos getdate, bos getfile, 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.
A command to debug authentication identities: bos whoami.
Commands to obtain help: bos apropos and bos help.
Command to display the program version: bos version.
The BOS Server and the bos commands use and maintain the following configuration and log files:
The /etc/yfs/server/UserListExt and /etc/yfs/server/ReaderListfiles list the Kerberos v4 principal name (rxkad) or GSS-API Kerberos v5 name (yfs-rxgk) of each administrator authorized to issue privileged bos and vos commands. To administer the /etc/yfs/server/UserListExt and /etc/yfs/server/ReaderList files, use the following commands: bos adduser, bos listusers, and bos removeuser.
The /etc/yfs/server/BosConfig file stores the B-node definitions that are managed by the BOS Server, and whether or not it restarts them automatically if B-node processes fail. The file also defines when all B-nodes restart automatically (by default never), when the BOS Server restarts B-nodes that have new binary files (by default never), and whether the BOS Server will start in restricted mode.
Although the /etc/yfs/server/BosConfig file is human readable it should be treated as an opaque binary file. To administer the B-node configuration, use the following commands: bos create, bos delete, bos getrestart, bos getrestricted, bos setrestart, bos setrestricted, bos start, and bos stop.
The /var/log/yfs/BosLog file records important operations the BOS Server performs and error conditions it encounters.
For more details, see the reference page for each file.
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.
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/yfs/yfs-client.conf file's [cellservdb] section 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.
Do not combine the -cell and -localauth options. A command on which the -localauth flag is included always runs in the local cell whereas a command on which the -cell argument is included runs in the specified foreign cell.
Prints the online help for this command. All other valid options are ignored.
Constructs an authentication token using the server encryption key with the highest key version number in the local /etc/yfs/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/yfs/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/yfs/server/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 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.
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 should be the system control machine (the machine running the Update Server).
The cell should use the Update Server to distribute the contents of the /etc/yfs/server directory. Provide the name of the system control machine to bos. 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.
(If the cell does not use the Update Server, 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. This method is not recommended. Use the Update Server instead.)
To issue any bos command that changes a configuration file or alters process status,
the issuer must be listed in the /etc/yfs/server/UserListExt 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.
The following commands are unsupported by AuriStorFS servers: bos addhost, bos listhosts, bos removehost, bos setcellname, bos addkey, bos listkeys, and bos removekey. These commands can be used to remotely manage IBM AFS and OpenAFS servers.
BosConfig(5), KeyFileExt(5), UserListExt(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_getfile(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), bos_version(8), bos_whoami(8), yfs-client.conf(5)
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.
"AFS" is a registered mark of International Business Machines Corporation, used under license. (USPTO Registration 1598389)
"OpenAFS" is a registered mark of International Business Machines Corporation. (USPTO Registration 4577045)
The "AuriStor" name, log 'S' brand mark, and icon are registered marks of AuriStor, Inc. (USPTO Registrations 4849419, 4849421, and 4928460) (EUIPO Registration 015539653).
"Your File System" is a registered mark of AuriStor, Inc. (USPTO Registrations 4801402 and 4849418).
"YFS" and "AuriStor File System" are trademarks of AuriStor, Inc.