.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "BOS 8" .TH BOS 8 "2021-01-14" "OpenAFS" "AFS Command Reference" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" bos \- Introduction to the bos command suite .SH "DESCRIPTION" .IX Header "DESCRIPTION" The commands in the \fBbos\fR command suite are the administrative interface to the Basic OverSeer (\s-1BOS\s0) Server, which runs on every file server machine to monitor the other server processes on it. If a process fails, the \s-1BOS\s0 Server can restart it automatically, taking into account interdependencies between it and other processes. The \s-1BOS\s0 Server frees system administrators from constantly monitoring the status of server machines and processes. .PP There are several categories of commands in the \fBbos\fR command suite: .IP "\(bu" 4 Commands to administer server process binary files: \fBbos getdate\fR, \fBbos install\fR, \fBbos prune\fR, and \fBbos uninstall\fR. .IP "\(bu" 4 Commands to maintain system configuration files: \fBbos addhost\fR, \fBbos addkey\fR, \fBbos adduser\fR, \fBbos listhosts\fR, \fBbos listkeys\fR, \fBbos listusers\fR, \fBbos removehost\fR, \fBbos removekey\fR, \fBbos removeuser\fR, and \&\fBbos setcellname\fR. .IP "\(bu" 4 Commands to start and stop processes: \fBbos create\fR, \fBbos delete\fR, \fBbos restart\fR, \fBbos shutdown\fR, \fBbos start\fR, \fBbos startup\fR, and \fBbos stop\fR. .IP "\(bu" 4 Commands to set and verify server process and server machine status: \fBbos getlog\fR, \fBbos getrestart\fR, \fBbos getrestricted\fR, \fBbos setauth\fR, \&\fBbos setrestart\fR, \fBbos setrestricted\fR and \fBbos status\fR. .IP "\(bu" 4 A command to restore file system consistency: \fBbos salvage\fR. .IP "\(bu" 4 Commands to obtain help: \fBbos apropos\fR and \fBbos help\fR. .IP "\(bu" 4 A command to display the OpenAFS command suite version: \fBbos version\fR. .PP The \s-1BOS\s0 Server and the \fBbos\fR commands use and maintain the following configuration and log files: .IP "\(bu" 4 The \fI/etc/openafs/server/CellServDB\fR file lists the local cell's database server machines. These machines run the Authentication, Backup, Protection and Volume Location (\s-1VL\s0) 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 \&\fICellServDB\fR file, use the following commands: \fBbos addhost\fR, \fBbos listhosts\fR, \fBbos removehost\fR, and \fBbos setcellname\fR. .IP "\(bu" 4 The \fI/etc/openafs/server/KeyFile\fR file lists the server encryption keys that the server processes use to decrypt tickets presented by client processes and one another. To administer the \fIKeyFile\fR file, use the following commands: \fBbos addkey\fR, \fBbos listkeys\fR, and \fBbos removekey\fR. .IP "\(bu" 4 The \fI/etc/openafs/server/KeyFileExt\fR 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 \fBasetkey\fR\|(8) to manage the \&\fIKeyFileExt\fR. .IP "\(bu" 4 The \fI/etc/openafs/server/ThisCell\fR file defines the cell to which the server machine belongs for the purposes of server-to-server communication. Administer it with the \fBbos setcellname\fR command. There is also a \&\fI/etc/openafs/ThisCell\fR file that defines the machine's cell membership with respect to the \s-1AFS\s0 command suites and Cache Manager access to \s-1AFS\s0 data. .IP "\(bu" 4 The \fI/etc/openafs/server/UserList\fR file lists the user name of each administrator authorized to issue privileged \fBbos\fR and \fBvos\fR commands. To administer the \fIUserList\fR file, use the following commands: \&\fBbos adduser\fR, \fBbos listusers\fR, and \fBbos removeuser\fR. .IP "\(bu" 4 The \fI/etc/openafs/BosConfig\fR file defines which \s-1AFS\s0 server processes run on the server machine, and whether the \s-1BOS\s0 Server restarts them automatically if they fail. It also defines when all processes restart automatically (by default once per week), when the \s-1BOS\s0 Server restarts processes that have new binary files (by default once per day), and whether the \s-1BOS\s0 Server will start in restricted mode. To administer the \fIBosConfig\fR file, use the following commands: \fBbos create\fR, \fBbos delete\fR, \fBbos getrestart\fR, \fBbos getrestricted\fR, \fBbos setrestart\fR, \fBbos setrestricted\fR, \fBbos start\fR, and \fBbos stop\fR. .IP "\(bu" 4 The \fI/usr/afs/log/BosLog\fR file records important operations the \s-1BOS\s0 Server performs and error conditions it encounters. .PP For more details, see the reference page for each file. .SH "OPTIONS" .IX Header "OPTIONS" The following arguments and flags are available on many commands in the \&\fBbos\fR suite. The reference page for each command also lists them, but they are described here in greater detail. .IP "\fB\-cell\fR <\fIcell name\fR>" 4 .IX Item "-cell " 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 \fI/etc/openafs/CellServDB\fR file on the local machine. If the \fB\-cell\fR argument is omitted, the command interpreter determines the name of the local cell by reading the following in order: .RS 4 .IP "\(bu" 4 The value of the \s-1AFSCELL\s0 environment variable. .IP "\(bu" 4 The local \fI/etc/openafs/ThisCell\fR file. .RE .RS 4 .Sp Do not combine the \fB\-cell\fR and \fB\-localauth\fR options. A command on which the \fB\-localauth\fR flag is included always runs in the local cell (as defined in the server machine's local \fI/etc/openafs/server/ThisCell\fR file), whereas a command on which the \fB\-cell\fR argument is included runs in the specified foreign cell. .RE .IP "\fB\-help\fR" 4 .IX Item "-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. .IP "\fB\-localauth\fR" 4 .IX Item "-localauth" Constructs a server ticket using the server encryption key with the highest key version number in the local \fI/etc/openafs/server/KeyFile\fR or \&\fI/etc/openafs/server/KeyFileExt\fR file. The \&\fBbos\fR command interpreter presents the ticket, which never expires, to the \s-1BOS\s0 Server during mutual authentication. .Sp Use this flag only when issuing a command on a server machine; client machines do not usually have a \fI/etc/openafs/server/KeyFile\fR or \&\fI/etc/openafs/server/KeyFileExt\fR file. The issuer of a command that includes this flag must be logged on to the server machine as the local superuser \f(CW\*(C`root\*(C'\fR. The flag is useful for commands invoked by an unattended application program, such as a process controlled by the \s-1UNIX\s0 \fBcron\fR utility or by a cron entry in the machine's \&\fI/etc/openafs/BosConfig\fR file. It is also useful if an administrator is unable to authenticate to \s-1AFS\s0 but is logged in as the local superuser \&\f(CW\*(C`root\*(C'\fR. .Sp Do not combine the \fB\-cell\fR and \fB\-localauth\fR options. A command on which the \fB\-localauth\fR flag is included always runs in the local cell (as defined in the server machine's local \fI/etc/openafs/server/ThisCell\fR file), whereas a command on which the \fB\-cell\fR argument is included runs in the specified foreign cell. Also, do not combine the \fB\-localauth\fR and \&\fB\-noauth\fR flags. .IP "\fB\-noauth\fR" 4 .IX Item "-noauth" Establishes an unauthenticated connection to the \s-1BOS\s0 Server, in which the \&\s-1BOS\s0 Server treats the issuer as the unprivileged user \f(CW\*(C`anonymous\*(C'\fR. It is useful only when authorization checking is disabled on the server machine (during the installation of a file server machine or when the \fBbos setauth\fR command has been used during other unusual circumstances). In normal circumstances, the \s-1BOS\s0 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 \fB\-noauth\fR flag is provided. Do not combine the \fB\-noauth\fR and \fB\-localauth\fR flags. .IP "\fB\-server\fR <\fImachine name\fR>" 4 .IX Item "-server " Indicates the \s-1AFS\s0 server machine on which to run the command. Identify the machine by its \s-1IP\s0 address in dotted decimal format, its fully-qualified host name (for example, \f(CW\*(C`fs1.example.com\*(C'\fR), 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. .Sp For the commands that alter the administrative files shared by all server machines in the cell (the \fBbos addhost\fR, \fBbos addkey\fR, \fBbos adduser\fR, \&\fBbos removehost\fR, \fBbos removekey\fR, and \fBbos removeuser\fR commands), the appropriate machine depends on whether the cell uses the United States or international version of \s-1AFS:\s0 .RS 4 .IP "\(bu" 4 If the cell (as recommended) uses the Update Server to distribute the contents of the \fI/etc/openafs/server\fR 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 \s-1AFS\s0 server machines in the cell. If the specified machine is not the system control machine but is running an \fBupclient\fR 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. .IP "\(bu" 4 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. .RE .RS 4 .RE .SH "PRIVILEGE REQUIRED" .IX Header "PRIVILEGE REQUIRED" To issue any bos command that changes a configuration file or alters process status, the issuer must be listed in the \fI/etc/openafs/server/UserList\fR file on the server machine named by the \fB\-server\fR argument. Alternatively, if the \fB\-localauth\fR flag is included the issuer must be logged on as the local superuser \f(CW\*(C`root\*(C'\fR. .PP To issue a bos command that only displays information (other than the \&\fBbos listkeys\fR command), no privilege is required. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBBosConfig\fR\|(5), \&\fBCellServDB\fR\|(5), \&\fBKeyFile\fR\|(5), \&\fBKeyFileExt\fR\|(5), \&\fBThisCell\fR\|(5), \&\fBUserList\fR\|(5), \&\fBbos_addhost\fR\|(8), \&\fBbos_addkey\fR\|(8), \&\fBbos_adduser\fR\|(8), \&\fBbos_apropos\fR\|(8), \&\fBbos_create\fR\|(8), \&\fBbos_delete\fR\|(8), \&\fBbos_exec\fR\|(8), \&\fBbos_getdate\fR\|(8), \&\fBbos_getlog\fR\|(8), \&\fBbos_getrestart\fR\|(8), \&\fBbos_getrestricted\fR\|(8), \&\fBbos_help\fR\|(8), \&\fBbos_install\fR\|(8), \&\fBbos_listhosts\fR\|(8), \&\fBbos_listkeys\fR\|(8), \&\fBbos_listusers\fR\|(8), \&\fBbos_prune\fR\|(8), \&\fBbos_removehost\fR\|(8), \&\fBbos_removekey\fR\|(8), \&\fBbos_removeuser\fR\|(8), \&\fBbos_restart\fR\|(8), \&\fBbos_salvage\fR\|(8), \&\fBbos_setauth\fR\|(8), \&\fBbos_setcellname\fR\|(8), \&\fBbos_setrestart\fR\|(8), \&\fBbos_setrestricted\fR\|(8), \&\fBbos_shutdown\fR\|(8), \&\fBbos_start\fR\|(8), \&\fBbos_startup\fR\|(8), \&\fBbos_status\fR\|(8), \&\fBbos_stop\fR\|(8), \&\fBbos_uninstall\fR\|(8) .SH "COPYRIGHT" .IX Header "COPYRIGHT" \&\s-1IBM\s0 Corporation 2000. All Rights Reserved. .PP This documentation is covered by the \s-1IBM\s0 Public License Version 1.0. It was converted from \s-1HTML\s0 to \s-1POD\s0 by software written by Chas Williams and Russ Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.