=head1 NAME

bos - Introduction to the C<bos> command suite

=head1 DESCRIPTION

The commands in the C<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 C<bos> command suite:

=over

=item *

Commands to administer server process binary files: C<bos getdate>,
C<bos install>, C<bos prune>, and C<bos uninstall>

=item *

Commands to maintain system configuration files: C<bos addhost>, C<bos
addkey>, C<bos adduser>, C<bos listhosts>, C<bos listkeys>, C<bos listusers>,
C<bos removehost>, C<bos removekey>, C<bos removeuser>, and C<bos setcellname>

=item *

Commands to start and stop processes: C<bos create>, C<bos delete>, C<bos
restart>, C<bos shutdown>, C<bos start>, C<bos startup>, and C<bos stop>

=item *

Commands to set and verify server process and server machine
status: C<bos getlog>, C<bos getrestart>, C<bos setauth>, C<bos setrestart>,
and C<bos status>

=item *

A command to restore file system consistency: C<bos salvage>

=item *

Commands to obtain help: C<bos apropos> and C<bos help>

=back

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

=over

=item *

The B</usr/afs/etc/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
B<CellServDB> file, use the following commands: C<bos addhost>, C<bos
listhosts>, C<bos removehost>, and C<bos setcellname>.

=item *

The B</usr/afs/etc/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: C<bos addkey>, C<bos listkeys>, and C<bos
removekey>.

=item *

The B</usr/afs/etc/ThisCell> file defines the cell to which the
server machine belongs for the purposes of server-to-server
communication. Administer it with the C<bos setcellname> command.
There is also a B</usr/vice/etc/ThisCell> file that defines the
machine's cell membership with respect to the AFS command suites
and Cache Manager access to AFS data.

=item *

The B</usr/afs/etc/UserList> file lists the user name of each
administrator authorized to issue privileged C<bos> and C<vos> commands.
To administer the UserList file, use the following commands: C<bos
adduser>, C<bos listusers>, and C<bos removeuser>.

=item *

The B</usr/afs/local/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: C<bos create>, C<bos delete>, C<bos getrestart>,
C<bos setrestart>, C<bos start>, and C<bos stop>.

=item *

The B</usr/afs/log/BosLog> file records important operations the BOS
Server performs and error conditions it encounters.

=back

For more details, see the reference page for each file.

=head1 OPTIONS

The following arguments and flags are available on many commands in
the C<bos> suite. The reference page for each command also lists them,
but they are described here in greater detail.

=over 4

=item B<-cell> I<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
B</usr/vice/etc/CellServDB> file on the local machine. If the
B<-cell> argument is omitted, the command interpreter determines
the name of the local cell by reading the following in order:

=over

=item 1.

The value of the AFSCELL environment variable

=item 2.

The local B</usr/vice/etc/ThisCell> file

=back

Do not combine the B<-cell> and B<-localauth> options. A command on
which the B<-localauth> flag is included always runs in the local
cell (as defined in the server machine's local
B</usr/afs/etc/ThisCell> file), whereas a command on which the
B<-cell> argument is included runs in the specified foreign cell.

=item B<-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.

=item B<-localauth>

Constructs a server ticket using the server encryption key with
the highest key version number in the local
B</usr/afs/etc/KeyFile> file. The C<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 B</usr/afs/etc/KeyFile>
file. The issuer of a command that includes this flag must be
logged on to the server machine as the local superuser B<root>.
The flag is useful for commands invoked by an unattended
application program, such as a process controlled by the UNIX
B<cron> utility or by a cron entry in the machine's
B</usr/afs/local/BosConfig> file. It is also useful if an
administrator is unable to authenticate to AFS but is logged in
as the local superuser B<root>.

Do not combine the B<-cell> and B<-localauth> options. A command on
which the B<-localauth> flag is included always runs in the local
cell (as defined in the server machine's local
B</usr/afs/etc/ThisCell> file), whereas a command on which the
B<-cell> argument is included runs in the specified foreign cell.
Also, do not combine the B<-localauth> and B<-noauth> flags.

=item B<-noauth>

Establishes an unauthenticated connection to the BOS Server, in
which the BOS Server treats the issuer as the unprivileged user
B<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 C<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 B<-noauth> flag is provided. Do not combine the B<-noauth> and
B<-localauth> flags.

=item B<-server> I<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,
B<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 C<bos addhost>, C<bos addkey>,
C<bos adduser>, C<bos removehost>, C<bos removekey>, and C<bos removeuser>
commands), the appropriate machine depends on whether the cell
uses the United States or international version of AFS:

=over

=item *

If the cell runs the United States edition of AFS and (as
recommended) uses the Update Server to distribute the
contents of the B</usr/afs/etc> 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 B<upclientetc> 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.

=item *

If the cell runs the international edition of AFS, do not use
the Update Server to distribute the contents of the
B</usr/afs/etc> directory. Instead, 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.

=back

=back

=head1 PRIVILEGE REQUIRED

To issue any C<bos> command that changes a configuration file or alters
process status, the issuer must be listed in the B</usr/afs/etc/UserList>
file on the server machine named by the B<-server> argument.
Alternatively, if the B<-localauth> flag is included the issuer must be
logged on as the local superuser B<root>.

To issue a C<bos> command that only displays information (other than the
C<bos listkeys> command), no privilege is required.

=head1 COPYRIGHT

IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.

Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
Stanford Linear Accelerator Center, a department of Stanford University.

=head1 SEE ALSO

L<BosConfig(1)>,
L<CellServDB_client_version(1)>,
L<CellServDB_server_version(1)>,
L<KeyFile(1)>,
L<ThisCell_client_version(1)>,
L<ThisCell_server_version(1)>,
L<UserList(1)>,
L<bos_addhost(1)>,
L<bos_addkey(1)>,
L<bos_adduser(1)>,
L<bos_apropos(1)>,
L<bos_create(1)>,
L<bos_delete(1)>,
L<bos_exec(1)>,
L<bos_getdate(1)>,
L<bos_getlog(1)>,
L<bos_getrestart(1)>,
L<bos_help(1)>,
L<bos_install(1)>,
L<bos_listhosts(1)>,
L<bos_listkeys(1)>,
L<bos_listusers(1)>,
L<bos_prune(1)>,
L<bos_removehost(1)>,
L<bos_removekey(1)>,
L<bos_removeuser(1)>,
L<bos_restart(1)>,
L<bos_salvage(1)>,
L<bos_setauth(1)>,
L<bos_setcellname(1)>,
L<bos_setrestart(1)>,
L<bos_shutdown(1)>,
L<bos_start(1)>,
L<bos_startup(1)>,
L<bos_status(1)>,
L<bos_stop(1)>,
L<bos_uninstall(1)>

=cut
