mirror of
https://git.openafs.org/openafs.git
synced 2025-01-19 07:20:11 +00:00
77eb172833
Add an initialization retry in the bos, vos, and pts commands to fallback to the server configuration directory when initialization fails with the client configuration directory. This allows admins to run unauthenticated bos, vos, and pts commands on servers without a client configuration (including symlinks created by the bosserver) without any extra command line options. Perform the initialization retry only when the -localauth or -config options are not given. The bos, vos, and pts commands already use the server configuration path when the -localauth option is given, so there is no point in retrying the same path. The vos and pts -config option specifies the path to be used, so we do not fallback to a different directory when the user specifies the configuration path to be used. While here, change the scope of the confdir variable in vos.c from a global to a local variable, since it is only used within the MyBeforeProc() function. This change does not add a vsu_ClientInit() retry in the bos salvage command. That command always requires authorization, so when run without -localauth requires a token (and therefore a cache manager and client cell configuration). Update the bos, vos, and pts man pages to describe this new fallback method to lookup the configuration directory. (The AFSCONF environment variable and .AFSCONF files are currently undocumented in the man pages. They should be documented or removed from the code in a future change.) Change-Id: I55c3109494db744e7bc2defcb54eaee3b4e30018 Reviewed-on: https://gerrit.openafs.org/15351 Tested-by: BuildBot <buildbot@rampaginggeek.com> Reviewed-by: Andrew Deason <adeason@sinenomine.net> Reviewed-by: Cheyenne Wills <cwills@sinenomine.net> Reviewed-by: Benjamin Kaduk <kaduk@mit.edu>
305 lines
10 KiB
Plaintext
305 lines
10 KiB
Plaintext
=head1 NAME
|
|
|
|
bos - Introduction to the bos command suite
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
The commands in the B<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 B<bos> command suite:
|
|
|
|
=over 4
|
|
|
|
=item *
|
|
|
|
Commands to administer server process binary files: B<bos getdate>, B<bos
|
|
install>, B<bos prune>, and B<bos uninstall>.
|
|
|
|
=item *
|
|
|
|
Commands to maintain system configuration files: B<bos addhost>, B<bos
|
|
addkey>, B<bos adduser>, B<bos listhosts>, B<bos listkeys>, B<bos
|
|
listusers>, B<bos removehost>, B<bos removekey>, B<bos removeuser>, and
|
|
B<bos setcellname>.
|
|
|
|
=item *
|
|
|
|
Commands to start and stop processes: B<bos create>, B<bos delete>, B<bos
|
|
restart>, B<bos shutdown>, B<bos start>, B<bos startup>, and B<bos stop>.
|
|
|
|
=item *
|
|
|
|
Commands to set and verify server process and server machine status: B<bos
|
|
getlog>, B<bos getrestart>, B<bos getrestricted>, B<bos setauth>,
|
|
B<bos setrestart>, B<bos setrestricted> and B<bos status>.
|
|
|
|
=item *
|
|
|
|
A command to restore file system consistency: B<bos salvage>.
|
|
|
|
=item *
|
|
|
|
Commands to obtain help: B<bos apropos> and B<bos help>.
|
|
|
|
=item *
|
|
|
|
A command to display the OpenAFS command suite version: B<bos version>.
|
|
|
|
=back
|
|
|
|
The BOS Server and the B<bos> commands use and maintain the following
|
|
configuration and log files:
|
|
|
|
=over 4
|
|
|
|
=item *
|
|
|
|
The F</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
|
|
F<CellServDB> file, use the following commands: B<bos addhost>, B<bos
|
|
listhosts>, B<bos removehost>, and B<bos setcellname>.
|
|
|
|
=item *
|
|
|
|
The F</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 F<KeyFile> file, use the following
|
|
commands: B<bos addkey>, B<bos listkeys>, and B<bos removekey>.
|
|
|
|
=item *
|
|
|
|
The F</usr/afs/etc/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 L<asetkey(8)> to manage the
|
|
F<KeyFileExt>.
|
|
|
|
=item *
|
|
|
|
The F</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 B<bos setcellname> command. There is also a
|
|
F</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 F</usr/afs/etc/UserList> file lists the user name of each
|
|
administrator authorized to issue privileged B<bos> and B<vos>
|
|
commands. To administer the F<UserList> file, use the following commands:
|
|
B<bos adduser>, B<bos listusers>, and B<bos removeuser>.
|
|
|
|
=item *
|
|
|
|
The F</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), 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 F<BosConfig> file, use the following commands: B<bos
|
|
create>, B<bos delete>, B<bos getrestart>, B<bos getrestricted>, B<bos
|
|
setrestart>, B<bos setrestricted>, B<bos start>, and B<bos stop>.
|
|
|
|
=item *
|
|
|
|
The F</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
|
|
B<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 F</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 4
|
|
|
|
=item *
|
|
|
|
The value of the AFSCELL environment variable.
|
|
|
|
=item *
|
|
|
|
The local F</usr/vice/etc/ThisCell> file.
|
|
|
|
=item *
|
|
|
|
The local F</usr/afs/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 F</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 F</usr/afs/etc/KeyFile> or
|
|
F</usr/afs/etc/KeyFileExt> file. The
|
|
B<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 F</usr/afs/etc/KeyFile> or
|
|
F</usr/afs/etc/KeyFileExt> file. The issuer
|
|
of a command that includes this flag must be logged on to the server
|
|
machine as the local superuser C<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
|
|
F</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
|
|
C<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 F</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 C<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 B<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, C<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 B<bos addhost>, B<bos addkey>, B<bos adduser>,
|
|
B<bos removehost>, B<bos removekey>, and B<bos removeuser> commands), the
|
|
appropriate machine depends on whether the cell uses the United States or
|
|
international version of AFS:
|
|
|
|
=over 4
|
|
|
|
=item *
|
|
|
|
If the cell (as recommended) uses the Update Server to distribute the
|
|
contents of the F</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<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.
|
|
|
|
=item *
|
|
|
|
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.
|
|
|
|
=back
|
|
|
|
=back
|
|
|
|
=head1 PRIVILEGE REQUIRED
|
|
|
|
To issue any bos command that changes a configuration file or alters
|
|
process status, the issuer must be listed in the F</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 C<root>.
|
|
|
|
To issue a bos command that only displays information (other than the
|
|
B<bos listkeys> command), no privilege is required.
|
|
|
|
=head1 SEE ALSO
|
|
|
|
L<BosConfig(5)>,
|
|
L<CellServDB(5)>,
|
|
L<KeyFile(5)>,
|
|
L<KeyFileExt(5)>,
|
|
L<ThisCell(5)>,
|
|
L<UserList(5)>,
|
|
L<bos_addhost(8)>,
|
|
L<bos_addkey(8)>,
|
|
L<bos_adduser(8)>,
|
|
L<bos_apropos(8)>,
|
|
L<bos_create(8)>,
|
|
L<bos_delete(8)>,
|
|
L<bos_exec(8)>,
|
|
L<bos_getdate(8)>,
|
|
L<bos_getlog(8)>,
|
|
L<bos_getrestart(8)>,
|
|
L<bos_getrestricted(8)>,
|
|
L<bos_help(8)>,
|
|
L<bos_install(8)>,
|
|
L<bos_listhosts(8)>,
|
|
L<bos_listkeys(8)>,
|
|
L<bos_listusers(8)>,
|
|
L<bos_prune(8)>,
|
|
L<bos_removehost(8)>,
|
|
L<bos_removekey(8)>,
|
|
L<bos_removeuser(8)>,
|
|
L<bos_restart(8)>,
|
|
L<bos_salvage(8)>,
|
|
L<bos_setauth(8)>,
|
|
L<bos_setcellname(8)>,
|
|
L<bos_setrestart(8)>,
|
|
L<bos_setrestricted(8)>,
|
|
L<bos_shutdown(8)>,
|
|
L<bos_start(8)>,
|
|
L<bos_startup(8)>,
|
|
L<bos_status(8)>,
|
|
L<bos_stop(8)>,
|
|
L<bos_uninstall(8)>
|
|
|
|
=head1 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.
|