doc/man-pages/pod/bos.pod

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