doc/man-pages/pod8/backup.pod

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