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