Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
BOS(8)			     AFS Command Reference			BOS(8)

       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:

       o   Commands to administer server process binary	files: bos getdate,
	   bos install,	bos prune, and bos uninstall.

       o   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.

       o   Commands to start and stop processes: bos create, bos delete, bos
	   restart, bos	shutdown, bos start, bos startup, and bos stop.

       o   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.

       o   A command to	restore	file system consistency: bos salvage.

       o   Commands to obtain help: bos	apropos	and bos	help.

       o   A command to	display	the OpenAFS command suite version: bos

       The BOS Server and the bos commands use and maintain the	following
       configuration and log files:

       o   The /usr/local/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.

       o   The /usr/local/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.

       o   The /usr/local/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 /usr/local/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.

       o   The /usr/local/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.

       o   The /usr/local/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.

       o   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.

       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 /usr/local/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:

	   o   The value of the	AFSCELL	environment variable.

	   o   The local /usr/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
	   /usr/local/etc/openafs/server/ThisCell file), whereas a command on
	   which the -cell argument is included	runs in	the specified foreign

	   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
	   /usr/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
	   /usr/local/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 /usr/local/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
	   /usr/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, ""), 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:

	   o   If the cell (as recommended) uses the Update Server to
	       distribute the contents of the /usr/local/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.

	   o   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

       To issue	any bos	command	that changes a configuration file or alters
       process status, the issuer must be listed in the
       /usr/local/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.

       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)

       IBM Corporation 2000. <> 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				  2016-12-14				BOS(8)


Want to link to this manual page? Use this URL:

home | help