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