NAME

       backup - Introduction to the backup command suite

DESCRIPTION

       The commands in the backup command suite are the administrative interface to the AFS
       Backup System. There are several categories of commands in the suite:

       •   Commands to copy data from AFS volumes to tape or a backup data file, and to restore
           it to the file system: backup diskrestore, backup dump, backup volrestore, and backup
           volsetrestore.

       •   Commands to administer the records in the Backup Database: backup adddump, backup
           addhost, backup addvolentry, backup addvolset, backup deldump, backup deletedump,
           backup delhost, backup delvolentry, backup delvolset, backup dumpinfo, backup
           listdumps, backup listhosts, backup listvolsets, backup scantape, backup setexp, and
           backup volinfo.

       •   Commands to write and read tape labels: backup labeltape and backup readlabel.

       •   Commands to list and change the status of backup operations and the machines
           performing them: backup jobs, backup kill, and backup status.

       •   Commands to enter and leave interactive mode: backup interactive and backup quit.

       •   Commands to check for and repair corruption in the Backup Database: backup dbverify,
           backup restoredb, and backup savedb.

       •   Commands to obtain help: backup apropos and backup help.

       •   A command to display the OpenAFS command suite version: backup version.

       The backup command interpreter interacts with two other processes:

       •   The Backup Server (buserver) process. It maintains the Backup Database, which stores
           most of the administrative information used by the Backup System. In the standard
           configuration, the Backup Server runs on each database server machine in the cell, and
           uses AFS's distributed database technology, Ubik, to synchronize its copy of the
           database with the copies on the other database server machines.

       •   The Backup Tape Coordinator (butc) process. A separate instance of the process
           controls each tape device or backup data file used to dump or restore data. The Tape
           Coordinator runs on a Tape Coordinator machine, which is an AFS server or client
           machine that has one or more tape devices attached, or has sufficient disk space to
           accommodate one or more backup data files on its local disk.

           Each Tape Coordinator must be registered in the Backup Database and in the
           /var/lib/openafs/backup/tapeconfig configuration file on the Tape Coordinator
           machine's local disk, and information in the two places must be consistent for proper
           Backup System performance. The optional /var/lib/openafs/backup/CFG_device_name for
           each Tape Coordinator records information used to automate its operation.

       In addition to the standard command line interface, the backup command suite provides an
       interactive interface, which has several useful features described in
       backup_interactive(8).  Three of the commands in the suite are available only in
       interactive mode: backup jobs, backup kill, and backup quit

OPTIONS

       The following options are available on many commands in the backup suite. The reference
       page for each command also lists them, but they are described here in greater detail.

       -cell <cell name>
           Names the cell in which to run the command. It is acceptable to abbreviate the cell
           name to the shortest form that distinguishes it from the other entries in the
           /etc/openafs/CellServDB file on the local machine. If the -cell argument is omitted,
           the command interpreter determines the name of the local cell by reading the following
           in order:

           •   The value of the AFSCELL environment variable.

           •   The local /etc/openafs/ThisCell file.

           Do not combine the -cell and -localauth options. A command on which the -localauth
           flag is included always runs in the local cell (as defined in the server machine's
           local /etc/openafs/server/ThisCell file), whereas a command on which the -cell
           argument is included runs in the specified foreign cell.

           The -cell argument is not available on commands issued in interactive mode. The cell
           defined when the backup command interpreter enters interactive mode applies to all
           commands issued during the interactive session.

       -help
           Prints a command's online help message on the standard output stream. Do not combine
           this flag with any of the command's other options; when it is provided, the command
           interpreter ignores all other options, and only prints the help message.

       -localauth
           Constructs a server ticket using the server encryption key with the highest key
           version number in the local /etc/openafs/server/KeyFile or
           /etc/openafs/server/KeyFileExt file. The backup command interpreter presents the
           ticket, which never expires, to the Backup Server, Volume Server and Volume Location
           (VL) Server during mutual authentication.

           Use this flag only when issuing a command on a server machine; client machines do not
           usually have a /etc/openafs/server/KeyFile or /etc/openafs/server/KeyFileExt file.
           The issuer of a command that includes this flag must be logged on to the server
           machine as the local superuser "root". The flag is useful for commands invoked by an
           unattended application program, such as a process controlled by the UNIX cron utility
           or by a cron entry in the machine's /etc/openafs/BosConfig file. It is also useful if
           an administrator is unable to authenticate to AFS but is logged in as the local
           superuser "root".

           Do not combine the -cell and -localauth options. A command on which the -localauth
           flag is included always runs in the local cell (as defined in the server machine's
           local /etc/openafs/server/ThisCell file), whereas a command on which the -cell
           argument is included runs in the specified foreign cell.

           The -localauth argument is not available on commands issued in interactive mode. The
           local identity and AFS tokens with which the backup command interpreter enters
           interactive mode apply to all commands issued during the interactive session.

       -nobutcauth
           Prior to the fix for OPENAFS-SA-2018-001, butc did not allow incoming connections to
           be authenticated.  As part of that fix, backup was modified to authenticate to the
           butc services when possible, but a backup utility with the security fix will not
           interoperate with a butc that lacks the fix unless this option is passed, which forces
           the use of unauthenticated connections to the butc.  Use of this option is strongly
           disrecommended, and it is provided only for backwards compatibility in environments
           where backup and butc communicate over a secure network environment that denies access
           to untrusted parties.

       -portoffset <TC port offset>
           Specifies the port offset number of the Tape Coordinator that is to execute the backup
           command. The port offset number uniquely identifies a pairing of a Tape Coordinator
           (butc) process and tape device or backup data file.

           The backup command interpreter and Tape Coordinator process communicate via a UDP
           socket, or port. Before issuing a backup command that involves reading or writing a
           tape, the backup operator must start a butc process that controls the appropriate tape
           device and listens for requests sent to its port number. If a Backup System machine
           has multiple tape devices attached, they can perform backup operations simultaneously
           because each device has its own associated butc process and port offset number.

           The Backup System associates a tape capacity and file mark size with each port offset
           (as defined in the tapeconfig file). For a compressing tape device, the capacity and
           file mark values differ for compression and non-compression modes, so the two modes
           have distinct port offset numbers.

           The Backup Database can store up to 58,511 port offsets, so the legal values for this
           argument are the integers 0 through 58510. If the issuer omits the argument, it
           defaults to 0. (The limit of 58,511 port offsets results from the fact that UDP socket
           numbers are identified by a 16-bit integer, and the lowest socket number used by the
           Backup System is 7025. The largest number that a 16-bit integer can represent is
           65,535. Subtracting 7,025 yields 58,510. The addition of port offset 0 (zero)
           increases the maximum to 58,511.)

           Although it is possible to define up to 58,511 port offset numbers for a cell, it is
           not possible to run 58,511 tape devices simultaneously, due to the following limits:

           •   The maximum number of dump or restore operations that can run simultaneously is
               64.

           •   The maximum number of tape devices that can work together on a restore operation
               is 128 (that is the maximum number of values that can be provided for the
               -portoffset argument to the backup diskrestore, backup volrestore, or backup
               volsetrestore command).

           The Backup System does not reserve UDP sockets. If another application is already
           using the Tape Coordinator's socket when it tries to start, the butc process fails and
           the following error message appears at the shell prompt:

              bind: Address already in use
              rxi_GetUDPSocket: bind failed

PRIVILEGE REQUIRED

       To issue any backup command that accesses the Backup Database only, the issuer must be
       listed in the /etc/openafs/server/UserList file on every machine where the Backup Server
       is running. To issue any backup command that accesses volume data, the issuer must appear
       in the UserList file on every Backup Server machine, every Volume Location (VL) Server
       machine, and every file server machine that houses affected volumes. By convention, a
       common UserList file is distributed to all database server and file server machines in the
       cell. See the chapter on privileged users in the OpenAFS Administration Guide for more
       information on this type of privilege.

       If the -localauth flag is included, the user must instead be logged on as the local
       superuser "root" on the server machine where the backup command is issued.

SEE ALSO

       BosConfig(5), CellServDB(5), KeyFile(5), KeyFileExt(5), ThisCell(5), UserList(5), butc(5),
       tapeconfig(5), backup_adddump(8), backup_addhost(8), backup_addvolentry(8),
       backup_addvolset(8), backup_apropos(8), backup_dbverify(8), backup_deldump(8),
       backup_deletedump(8), backup_delhost(8), backup_delvolentry(8), backup_delvolset(8),
       backup_diskrestore(8), backup_dump(8), backup_dumpinfo(8), backup_help(8),
       backup_interactive(8), backup_jobs(8), backup_kill(8), backup_labeltape(8),
       backup_listdumps(8), backup_listhosts(8), backup_listvolsets(8), backup_quit(8),
       backup_readlabel(8), backup_restoredb(8), backup_savedb(8), backup_scantape(8),
       backup_setexp(8), backup_status(8), backup_volinfo(8), backup_volrestore(8),
       backup_volsetrestore(8), buserver(8), butc(8)

COPYRIGHT

       IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.

       This documentation is covered by the IBM Public License Version 1.0.  It was converted
       from HTML to POD by software written by Chas Williams and Russ Allbery, based on work by
       Alf Wachsmann and Elizabeth Cassell.