Provided by: openafs-client_1.4.1-2_i386
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 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
· Commands to list and change the status of backup operations and the
machines performing them: backup jobs, backup kill, and backup
· 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.
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
· 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 the backup_interactive(8) manpage. Three of the
commands in the suite are available only in interactive mode: backup
jobs, backup kill, and backup quit.
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
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.
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 authentication.
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
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 butc process fails and the following
error message appears at the shell prompt:
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 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 IBM AFS 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.
the BosConfig(5) manpage, the CellServDB(5) manpage, the KeyFile(5)
manpage, the ThisCell(5) manpage, the UserList(5) manpage, the butc(5)
manpage, the tapeconfig(5) manpage, the backup_adddump(8) manpage, the
backup_addhost(8) manpage, the backup_addvolentry(8) manpage, the
backup_addvolset(8) manpage, the backup_dbverify(8) manpage, the
backup_deldump(8) manpage, the backup_deletedump(8) manpage, the
backup_delhost(8) manpage, the backup_delvolentry(8) manpage, the
backup_delvolset(8) manpage, the backup_diskrestore(8) manpage, the
backup_dump(8) manpage, the backup_dumpinfo(8) manpage, the
backup_help(8) manpage, the backup_interactive(8) manpage, the
backup_jobs(8) manpage, the backup_kill(8) manpage, the
backup_labeltape(8) manpage, the backup_listdumps(8) manpage, the
backup_listhosts(8) manpage, the backup_listvolsets(8) manpage, the
backup_quit(8) manpage, the backup_readlabel(8) manpage, the
backup_restoredb(8) manpage, the backup_savedb(8) manpage, the
backup_scantape(8) manpage, the backup_setexp(8) manpage, the
backup_status(8) manpage, the backup_volinfo(8) manpage, the
backup_volrestore(8) manpage, the backup_volsetrestore(8) manpage, the
buserver(8) manpage, the butc(8) manpage
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.