doc/man-pages/pod8/bos.pod

   1 =head1 NAME
   2
   3 bos - Introduction to the bos command suite
   4
   5 =head1 DESCRIPTION
   6
   7 The commands in the B<bos> command suite are the administrative interface
   8 to the Basic OverSeer (BOS) Server, which runs on every file server
   9 machine to monitor the other server processes on it. If a process fails,
  10 the BOS Server can restart it automatically, taking into account
  11 interdependencies between it and other processes. The BOS Server frees
  12 system administrators from constantly monitoring the status of server
  13 machines and processes.
  14
  15 There are several categories of commands in the B<bos> command suite:
  16
  17 =over 4
  18
  19 =item *
  20
  21 Commands to administer server process binary files: B<bos getdate>, B<bos
  22 install>, B<bos prune>, and B<bos uninstall>.
  23
  24 =item *
  25
  26 Commands to maintain system configuration files: B<bos addhost>, B<bos
  27 addkey>, B<bos adduser>, B<bos listhosts>, B<bos listkeys>, B<bos
  28 listusers>, B<bos removehost>, B<bos removekey>, B<bos removeuser>, and
  29 B<bos setcellname>.
  30
  31 =item *
  32
  33 Commands to start and stop processes: B<bos create>, B<bos delete>, B<bos
  34 restart>, B<bos shutdown>, B<bos start>, B<bos startup>, and B<bos stop>.
  35
  36 =item *
  37
  38 Commands to set and verify server process and server machine status: B<bos
  39 getlog>, B<bos getrestart>, B<bos getrestricted>, B<bos setauth>,
  40 B<bos setrestart>, B<bos setrestricted> and B<bos status>.
  41
  42 =item *
  43
  44 A command to restore file system consistency: B<bos salvage>.
  45
  46 =item *
  47
  48 Commands to obtain help: B<bos apropos> and B<bos help>.
  49
  50 =item *
  51
  52 A command to display the OpenAFS command suite version: B<bos version>.
  53
  54 =back
  55
  56 The BOS Server and the B<bos> commands use and maintain the following
  57 configuration and log files:
  58
  59 =over 4
  60
  61 =item *
  62
  63 The F</usr/afs/etc/CellServDB> file lists the local cell's database server
  64 machines. These machines run the Authentication, Backup, Protection and
  65 Volume Location (VL) Server processes, which maintain databases of
  66 administrative information. The database server processes consult the file
  67 to learn about their peers, whereas the other server processes consult it
  68 to learn where to access database information as needed. To administer the
  69 F<CellServDB> file, use the following commands: B<bos addhost>, B<bos
  70 listhosts>, B<bos removehost>, and B<bos setcellname>.
  71
  72 =item *
  73
  74 The F</usr/afs/etc/KeyFile> file lists the server encryption keys that the
  75 server processes use to decrypt tickets presented by client processes and
  76 one another. To administer the F<KeyFile> file, use the following
  77 commands: B<bos addkey>, B<bos listkeys>, and B<bos removekey>.
  78
  79 =item *
  80
  81 The F</usr/afs/etc/KeyFileExt> file lists additional server encryption
  82 keys that the server processes can use to decrypt tickets presented by
  83 client processes and one another. These keys are strong encryption
  84 keys used by the rxkad-k5 extension; use L<asetkey(8)> to manage the
  85 F<KeyFileExt>.
  86
  87 =item *
  88
  89 The F</usr/afs/etc/ThisCell> file defines the cell to which the server
  90 machine belongs for the purposes of server-to-server communication.
  91 Administer it with the B<bos setcellname> command. There is also a
  92 F</usr/vice/etc/ThisCell> file that defines the machine's cell membership
  93 with respect to the AFS command suites and Cache Manager access to AFS
  94 data.
  95
  96 =item *
  97
  98 The F</usr/afs/etc/UserList> file lists the user name of each
  99 administrator authorized to issue privileged B<bos> and B<vos>
 100 commands. To administer the F<UserList> file, use the following commands:
 101 B<bos adduser>, B<bos listusers>, and B<bos removeuser>.
 102
 103 =item *
 104
 105 The F</usr/afs/local/BosConfig> file defines which AFS server processes
 106 run on the server machine, and whether the BOS Server restarts them
 107 automatically if they fail. It also defines when all processes restart
 108 automatically (by default once per week), when the BOS Server restarts
 109 processes that have new binary files (by default once per day), and
 110 whether the BOS Server will start in restricted mode. To
 111 administer the F<BosConfig> file, use the following commands: B<bos
 112 create>, B<bos delete>, B<bos getrestart>, B<bos getrestricted>, B<bos
 113 setrestart>, B<bos setrestricted>, B<bos start>, and B<bos stop>.
 114
 115 =item *
 116
 117 The F</usr/afs/log/BosLog> file records important operations the BOS
 118 Server performs and error conditions it encounters.
 119
 120 =back
 121
 122 For more details, see the reference page for each file.
 123
 124 =head1 OPTIONS
 125
 126 The following arguments and flags are available on many commands in the
 127 B<bos> suite. The reference page for each command also lists them, but
 128 they are described here in greater detail.
 129
 130 =over 4
 131
 132 =item B<-cell> <I<cell name>>
 133
 134 Names the cell in which to run the command. It is acceptable to abbreviate
 135 the cell name to the shortest form that distinguishes it from the other
 136 entries in the F</usr/vice/etc/CellServDB> file on the local machine. If
 137 the B<-cell> argument is omitted, the command interpreter determines the
 138 name of the local cell by reading the following in order:
 139
 140 =over 4
 141
 142 =item *
 143
 144 The value of the AFSCELL environment variable.
 145
 146 =item *
 147
 148 The local F</usr/vice/etc/ThisCell> file.
 149
 150 =back
 151
 152 Do not combine the B<-cell> and B<-localauth> options. A command on which
 153 the B<-localauth> flag is included always runs in the local cell (as
 154 defined in the server machine's local F</usr/afs/etc/ThisCell> file),
 155 whereas a command on which the B<-cell> argument is included runs in the
 156 specified foreign cell.
 157
 158 =item B<-help>
 159
 160 Prints a command's online help message on the standard output stream. Do
 161 not combine this flag with any of the command's other options; when it is
 162 provided, the command interpreter ignores all other options, and only
 163 prints the help message.
 164
 165 =item B<-localauth>
 166
 167 Constructs a server ticket using the server encryption key with the
 168 highest key version number in the local F</usr/afs/etc/KeyFile> or
 169 F</usr/afs/etc/KeyFileExt> file. The
 170 B<bos> command interpreter presents the ticket, which never expires, to
 171 the BOS Server during mutual authentication.
 172
 173 Use this flag only when issuing a command on a server machine; client
 174 machines do not usually have a F</usr/afs/etc/KeyFile> or
 175 F</usr/afs/etc/KeyFileExt> file.  The issuer
 176 of a command that includes this flag must be logged on to the server
 177 machine as the local superuser C<root>. The flag is useful for commands
 178 invoked by an unattended application program, such as a process controlled
 179 by the UNIX B<cron> utility or by a cron entry in the machine's
 180 F</usr/afs/local/BosConfig> file. It is also useful if an administrator is
 181 unable to authenticate to AFS but is logged in as the local superuser
 182 C<root>.
 183
 184 Do not combine the B<-cell> and B<-localauth> options. A command on which
 185 the B<-localauth> flag is included always runs in the local cell (as
 186 defined in the server machine's local F</usr/afs/etc/ThisCell> file),
 187 whereas a command on which the B<-cell> argument is included runs in the
 188 specified foreign cell. Also, do not combine the B<-localauth> and
 189 B<-noauth> flags.
 190
 191 =item B<-noauth>
 192
 193 Establishes an unauthenticated connection to the BOS Server, in which the
 194 BOS Server treats the issuer as the unprivileged user C<anonymous>. It is
 195 useful only when authorization checking is disabled on the server machine
 196 (during the installation of a file server machine or when the B<bos
 197 setauth> command has been used during other unusual circumstances). In
 198 normal circumstances, the BOS Server allows only privileged users to issue
 199 commands that change the status of a server or configuration file, and
 200 refuses to perform such an action even if the B<-noauth> flag is
 201 provided. Do not combine the B<-noauth> and B<-localauth> flags.
 202
 203 =item B<-server> <I<machine name>>
 204
 205 Indicates the AFS server machine on which to run the command.  Identify
 206 the machine by its IP address in dotted decimal format, its
 207 fully-qualified host name (for example, C<fs1.example.com>), or by an
 208 abbreviated form of its host name that distinguishes it from other
 209 machines. Successful use of an abbreviated form depends on the
 210 availability of a name service (such as the Domain Name Service or a local
 211 host table) at the time the command is issued.
 212
 213 For the commands that alter the administrative files shared by all server
 214 machines in the cell (the B<bos addhost>, B<bos addkey>, B<bos adduser>,
 215 B<bos removehost>, B<bos removekey>, and B<bos removeuser> commands), the
 216 appropriate machine depends on whether the cell uses the United States or
 217 international version of AFS:
 218
 219 =over 4
 220
 221 =item *
 222
 223 If the cell (as recommended) uses the Update Server to distribute the
 224 contents of the F</usr/afs/etc> directory, provide the name of the system
 225 control machine. After issuing the command, allow up to five minutes for
 226 the Update Server to distribute the changed file to the other AFS server
 227 machines in the cell. If the specified machine is not the system control
 228 machine but is running an B<upclient> process that refers to the system
 229 control machine, then the change will be overwritten when the process next
 230 brings over the relevant file from the system control machine.
 231
 232 =item *
 233
 234 Otherwise, repeatedly issue the command, naming each of the cell's server
 235 machines in turn. To avoid possible inconsistency problems, finish issuing
 236 the commands within a fairly short time.
 237
 238 =back
 239
 240 =back
 241
 242 =head1 PRIVILEGE REQUIRED
 243
 244 To issue any bos command that changes a configuration file or alters
 245 process status, the issuer must be listed in the F</usr/afs/etc/UserList>
 246 file on the server machine named by the B<-server>
 247 argument. Alternatively, if the B<-localauth> flag is included the issuer
 248 must be logged on as the local superuser C<root>.
 249
 250 To issue a bos command that only displays information (other than the
 251 B<bos listkeys> command), no privilege is required.
 252
 253 =head1 SEE ALSO
 254
 255 L<BosConfig(5)>,
 256 L<CellServDB(5)>,
 257 L<KeyFile(5)>,
 258 L<KeyFileExt(5)>,
 259 L<ThisCell(5)>,
 260 L<UserList(5)>,
 261 L<bos_addhost(8)>,
 262 L<bos_addkey(8)>,
 263 L<bos_adduser(8)>,
 264 L<bos_apropos(8)>,
 265 L<bos_create(8)>,
 266 L<bos_delete(8)>,
 267 L<bos_exec(8)>,
 268 L<bos_getdate(8)>,
 269 L<bos_getlog(8)>,
 270 L<bos_getrestart(8)>,
 271 L<bos_getrestricted(8)>,
 272 L<bos_help(8)>,
 273 L<bos_install(8)>,
 274 L<bos_listhosts(8)>,
 275 L<bos_listkeys(8)>,
 276 L<bos_listusers(8)>,
 277 L<bos_prune(8)>,
 278 L<bos_removehost(8)>,
 279 L<bos_removekey(8)>,
 280 L<bos_removeuser(8)>,
 281 L<bos_restart(8)>,
 282 L<bos_salvage(8)>,
 283 L<bos_setauth(8)>,
 284 L<bos_setcellname(8)>,
 285 L<bos_setrestart(8)>,
 286 L<bos_setrestricted(8)>,
 287 L<bos_shutdown(8)>,
 288 L<bos_start(8)>,
 289 L<bos_startup(8)>,
 290 L<bos_status(8)>,
 291 L<bos_stop(8)>,
 292 L<bos_uninstall(8)>
 293
 294 =head1 COPYRIGHT
 295
 296 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
 297
 298 This documentation is covered by the IBM Public License Version 1.0.  It was
 299 converted from HTML to POD by software written by Chas Williams and Russ
 300 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.