doc/man-pages/pod/backup.pod

   1 =head1 NAME
   2
   3 backup - Introduction to the C<backup> command suite
   4
   5 =head1 DESCRIPTION
   6
   7 The commands in the C<backup> command suite are the administrative
   8 interface to the AFS Backup System. There are several categories of
   9 commands in the suite:
  10
  11 =over
  12
  13 =item *
  14
  15 Commands to copy data from AFS volumes to tape or a backup data
  16 file, and to restore it to the file system: C<backup diskrestore>,
  17 C<backup dump>, C<backup volrestore>, and C<backup volsetrestore>
  18
  19 =item *
  20
  21 Commands to administer the records in the Backup Database: C<backup
  22 adddump>, C<backup addhost>, C<backup addvolentry>, C<backup addvolset>,
  23 C<backup deldump>, C<backup deletedump>, C<backup delhost>, C<backup
  24 delvolentry>, C<backup delvolset>, C<backup dumpinfo>, C<backup listdumps>,
  25 C<backup listhosts>, C<backup listvolsets>, C<backup scantape>, C<backup
  26 setexp>, and C<backup volinfo>
  27
  28 =item *
  29
  30 Commands to write and read tape labels: C<backup labeltape> and
  31 C<backup readlabel>
  32
  33 =item *
  34
  35 Commands to list and change the status of backup operations and
  36 the machines performing them: C<(backup) jobs>, C<(backup) kill>, and
  37 C<backup status>
  38
  39 =item *
  40
  41 Commands to enter and leave interactive mode: C<backup (interactive)>
  42 and C<(backup) quit>
  43
  44 =item *
  45
  46 Commands to check for and repair corruption in the Backup
  47 Database: C<backup dbverify>, C<backup restoredb>, and C<backup savedb>
  48
  49 =item *
  50
  51 Commands to obtain help: C<backup apropos> and C<backup help>
  52
  53 =back
  54
  55 The C<backup> command interpreter interacts with two other processes:
  56
  57 =over
  58
  59 =item *
  60
  61 The Backup Server (B<buserver>) process. It maintains the Backup
  62 Database, which stores most of the administrative information used
  63 by the Backup System. In the standard configuration, the Backup
  64 Server runs on each database server machine in the cell, and uses
  65 AFS's distributed database technology, Ubik, to synchronize its
  66 copy of the database with the copies on the other database server
  67 machines.
  68
  69 =item *
  70
  71 The Backup Tape Coordinator (B<butc>) process. A separate instance of
  72 the process controls each tape device or backup data file used to
  73 dump or restore data. The Tape Coordinator runs on a Tape
  74 Coordinator machine, which is an AFS server or client machine that
  75 has one or more tape devices attached, or has sufficient disk
  76 space to accommodate one or more backup data files on its local
  77 disk.
  78
  79 Each Tape Coordinator must be registered in the Backup Database
  80 and in the B</usr/afs/backup/tapeconfig> configuration file on the
  81 Tape Coordinator machine's local disk, and information in the two
  82 places must be consistent for proper Backup System performance.
  83 The optional B</usr/afs/backup/CFG>I<_device_name> for each Tape
  84 Coordinator records information used to automate its operation.
  85
  86 =back
  87
  88 In addition to the standard command line interface, the C<backup> command
  89 suite provides an I<interactive> interface, which has several useful
  90 features described on the C<backup (interactive)> reference page. Three
  91 of the commands in the suite are available only in interactive mode:
  92 C<(backup) jobs>, C<(backup) kill>, and C<(backup) quit>.
  93
  94 =head1 OPTIONS
  95
  96 The following options are available on many commands in the C<backup>
  97 suite. The reference page for each command also lists them, but they
  98 are described here in greater detail.
  99
 100 =over 4
 101
 102 =item B<-cell> I<cell name>
 103
 104 Names the cell in which to run the command. It is acceptable to
 105 abbreviate the cell name to the shortest form that
 106 distinguishes it from the other entries in the
 107 B</usr/vice/etc/CellServDB> file on the local machine. If the
 108 B<-cell> argument is omitted, the command interpreter determines
 109 the name of the local cell by reading the following in order:
 110
 111 =over
 112
 113 =item 1.
 114
 115 The value of the AFSCELL environment variable
 116
 117 =item 2.
 118
 119 The local B</usr/vice/etc/ThisCell> file
 120
 121 =back
 122
 123 Do not combine the B<-cell> and B<-localauth> options. A command on
 124 which the B<-localauth> flag is included always runs in the local
 125 cell (as defined in the server machine's local
 126 B</usr/afs/etc/ThisCell> file), whereas a command on which the
 127 B<-cell> argument is included runs in the specified foreign cell.
 128
 129 The B<-cell> argument is not available on commands issued in
 130 interactive mode. The cell defined when the C<backup> command
 131 interpreter enters interactive mode applies to all commands
 132 issued during the interactive session.
 133
 134
 135 =item B<-help>
 136
 137 Prints a command's online help message on the standard output
 138 stream. Do not combine this flag with any of the command's
 139 other options; when it is provided, the command interpreter
 140 ignores all other options, and only prints the help message.
 141
 142
 143 =item B<-localauth>
 144
 145 Constructs a server ticket using the server encryption key with
 146 the highest key version number in the local
 147 B</usr/afs/etc/KeyFile> file. The C<backup> command interpreter
 148 presents the ticket, which never expires, to the Backup Server,
 149 Volume Server and Volume Location (VL) Server during mutual
 150 authentication.
 151
 152 Use this flag only when issuing a command on a server machine;
 153 client machines do not usually have a B</usr/afs/etc/KeyFile>
 154 file. The issuer of a command that includes this flag must be
 155 logged on to the server machine as the local superuser B<root>.
 156 The flag is useful for commands invoked by an unattended
 157 application program, such as a process controlled by the UNIX
 158 B<cron> utility or by a cron entry in the machine's
 159 B</usr/afs/local/BosConfig> file. It is also useful if an
 160 administrator is unable to authenticate to AFS but is logged in
 161 as the local superuser B<root>.
 162
 163 Do not combine the B<-cell> and B<-localauth> options. A command on
 164 which the B<-localauth> flag is included always runs in the local
 165 cell (as defined in the server machine's local
 166 B</usr/afs/etc/ThisCell> file), whereas a command on which the
 167 B<-cell> argument is included runs in the specified foreign cell.
 168
 169 The B<-localauth> argument is not available on commands issued in
 170 interactive mode. The local identity and AFS tokens with which
 171 the C<backup> command interpreter enters interactive mode apply to
 172 all commands issued during the interactive session.
 173
 174 =item B<-portoffset> I<TC port offset>
 175
 176 Specifies the port offset number of the Tape Coordinator that
 177 is to execute the C<backup> command. The port offset number
 178 uniquely identifies a pairing of a Tape Coordinator (B<butc>)
 179 process and tape device or C<backup> data file.
 180
 181 The C<backup> command interpreter and Tape Coordinator process
 182 communicate via a UDP socket, or port. Before issuing a C<backup>
 183 command that involves reading or writing a tape, the backup
 184 operator must start a B<butc> process that controls the
 185 appropriate tape device and listens for requests sent to its
 186 port number. If a Backup System machine has multiple tape
 187 devices attached, they can perform backup operations
 188 simultaneously because each device has its own associated B<butc>
 189 process and port offset number.
 190
 191 The Backup System associates a tape capacity and file mark size
 192 with each port offset (as defined in the B<tapeconfig> file). For
 193 a compressing tape device, the capacity and file mark values
 194 differ for compression and non-compression modes, so the two
 195 modes have distinct port offset numbers.
 196
 197 The Backup Database can store up to 58,511 port offsets, so the
 198 legal values for this argument are the integers B<0> through
 199 B<58510>. If the issuer omits the argument, it defaults to B<0>. (The
 200 limit of 58,511 port offsets results from the fact that UDP
 201 socket numbers are identified by a 16-bit integer, and the
 202 lowest socket number used by the Backup System is 7025. The
 203 largest number that a 16-bit integer can represent is 65,535.
 204 Subtracting 7,025 yields 58,510. The addition of port offset 0
 205 (zero) increases the maximum to 58,511.)
 206
 207 Although it is possible to define up to 58,511 port offset
 208 numbers for a cell, it is not possible to run 58,511 tape
 209 devices simultaneously, due to the following limits:
 210
 211
 212 =over
 213
 214 =item *
 215
 216 The maximum number of dump or restore operations that can run
 217 simultaneously is 64.
 218
 219 =item *
 220
 221 The maximum number of tape devices that can work together on
 222 a restore operation is 128 (that is the maximum number of
 223 values that can be provided for the B<-portoffset> argument to
 224 the C<backup diskrestore>, C<backup volrestore>, or C<backup
 225 volsetrestore> command).
 226
 227 =back
 228
 229 The Backup System does not reserve UDP sockets. If another
 230 application is already using the Tape Coordinator's socket when
 231 it tries to start, the B<butc> process fails and the following
 232 error message appears at the shell prompt:
 233
 234   bind: Address already in use
 235   rxi_GetUDPSocket: bind failed
 236
 237 =back
 238
 239 =head1 PRIVILEGE REQUIRED
 240
 241 To issue any C<backup> command that accesses the Backup Database only,
 242 the issuer must be listed in the B</usr/afs/etc/UserList> file on every
 243 machine where the Backup Server is running. To issue any C<backup> command
 244 that accesses volume data, the issuer must appear in the
 245 B<UserList> file on every Backup Server machine, every Volume Location
 246 (VL) Server machine, and every file server machine that houses
 247 affected volumes. By convention, a common B<UserList> file is distributed
 248 to all database server and file server machines in the cell. See the
 249 chapter on privileged users in the IBM AFS Administration Guide for
 250 more information on this type of privilege.
 251
 252 If the B<-localauth> flag is included, the user must instead be logged on
 253 as the local superuser root on the server machine where the C<backup> command is issued.
 254
 255 =head1 COPYRIGHT
 256
 257 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
 258
 259 Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
 260 Stanford Linear Accelerator Center, a department of Stanford University.
 261
 262 =head1 SEE ALSO
 263
 264 L<BosConfig(1)>,
 265 L<CFG_device_name(1)>,
 266 L<CellServDB_client_version(1)>,
 267 L<KeyFile(1)>,
 268 L<ThisCell_client_version(1)>,
 269 L<ThisCell_server_version(1)>,
 270 L<UserList(1)>,
 271 L<tapeconfig(1)>,
 272 L<backup_adddump(1)>,
 273 L<backup_addhost(1)>,
 274 L<backup_addvolentry(1)>,
 275 L<backup_addvolset(1)>,
 276 L<backup_dbverify(1)>,
 277 L<backup_deldump(1)>,
 278 L<backup_deletedump(1)>,
 279 L<backup_delhost(1)>,
 280 L<backup_delvolentry(1)>,
 281 L<backup_delvolset(1)>,
 282 L<backup_diskrestore(1)>,
 283 L<backup_dump(1)>,
 284 L<backup_dumpinfo(1)>,
 285 L<backup_help(1)>,
 286 L<backup_interactive(1)>,
 287 L<backup_jobs(1)>,
 288 L<backup_kill(1)>,
 289 L<backup_labeltape(1)>,
 290 L<backup_listdumps(1)>,
 291 L<backup_listhosts(1)>,
 292 L<backup_listvolsets(1)>,
 293 L<backup_quit(1)>,
 294 L<backup_readlabel(1)>,
 295 L<backup_restoredb(1)>,
 296 L<backup_savedb(1)>,
 297 L<backup_scantape(1)>,
 298 L<backup_setexp(1)>,
 299 L<backup_status(1)>,
 300 L<backup_volinfo(1)>,
 301 L<backup_volrestore(1)>,
 302 L<backup_volsetrestore(1)>,
 303 L<buserver(1)>,
 304 L<butc(1)>
 305
 306 =cut