backup - Introduction to the backup command suite
The commands in the backup
command suite are the administrative interface
to the AFS Backup System. There are several categories of commands in the
- 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
- 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
- Commands to obtain help: backup apropos and
- A command to display the OpenAFS command suite 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
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
, and backup quit
The following options are available on many commands in the backup
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
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.
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
- 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.
- Constructs a server ticket using the server encryption key
with the highest key version number in the local
/etc/openafs/server/KeyFile file. The backup command
interpreter presents the ticket, which never expires, to the Backup
Server, Volume Server and Volume Location (VL) Server during mutual
Use this flag only when issuing a command on a server machine; client
machines do not usually have a /etc/openafs/server/KeyFile 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.
- -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
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
process fails and the following error message appears at the shell
bind: Address already in use
rxi_GetUDPSocket: bind failed
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
that accesses volume data, the issuer must appear in the UserList
on every Backup Server machine, every Volume Location (VL) Server machine, and
every file server machine that houses affected volumes. By convention, a
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
If the -localauth
flag is included, the user must instead be logged on as
the local superuser "root" on the server machine where the
command is issued.
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.