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