mirror of
https://git.openafs.org/openafs.git
synced 2025-01-19 07:20:11 +00:00
5f70221b2c
Change references to the documentation sets that we still ship to reference the OpenAFS manuals instead of the IBM AFS manuals. Remove references to the IBM AFS/DFS Migration documentation, since that doesn't appear to be available anywhere any more, replacing them where relevant to more generic references to the DFS documentation. Add links to docs.openafs.org for mentions of the manuals in SEE ALSO, and standardize on one link format. Replace a few references to the IBM AFS Release Notes with the actual information in those notes, or drop the reference if it doesn't seem particularly useful. Change-Id: Ie9666842f1315891c6a9c37c0424200f4b78bff7 Reviewed-on: http://gerrit.openafs.org/2031 Reviewed-by: Derrick Brashear <shadow@dementia.org> Tested-by: Derrick Brashear <shadow@dementia.org>
321 lines
11 KiB
Plaintext
321 lines
11 KiB
Plaintext
=head1 NAME
|
|
|
|
backup - Introduction to the backup command suite
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
The commands in the B<backup> command suite are the administrative
|
|
interface to the AFS Backup System. There are several categories of
|
|
commands in the suite:
|
|
|
|
=over 4
|
|
|
|
=item *
|
|
|
|
Commands to copy data from AFS volumes to tape or a backup data file, and
|
|
to restore it to the file system:
|
|
L<B<backup diskrestore>|backup_diskrestore(8)>,
|
|
L<B<backup dump>|backup_dump(8)>,
|
|
L<B<backup volrestore>|backup_volrestore(8)>,
|
|
and L<B<backup volsetrestore>|backup_volsetrestore(8)>.
|
|
|
|
=item *
|
|
|
|
Commands to administer the records in the Backup Database:
|
|
L<B<backup adddump>|backup_adddump(8)>,
|
|
L<B<backup addhost>|backup_addhost(8)>,
|
|
L<B<backup addvolentry>|backup_addvolentry(8)>,
|
|
L<B<backup addvolset>|backup_addvolset(8)>,
|
|
L<B<backup deldump>|backup_deldump(8)>,
|
|
L<B<backup deletedump>|backup_deletedump(8)>,
|
|
L<B<backup delhost>|backup_delhost(8)>,
|
|
L<B<backup delvolentry>|backup_delvolentry(8)>,
|
|
L<B<backup delvolset>|backup_delvolset(8)>,
|
|
L<B<backup dumpinfo>|backup_dumpinfo(8)>,
|
|
L<B<backup listdumps>|backup_listdumps(8)>,
|
|
L<B<backup listhosts>|backup_listhosts(8)>,
|
|
L<B<backup listvolsets>|backup_listvolsets(8)>,
|
|
L<B<backup scantape>|backup_scantape(8)>,
|
|
L<B<backup setexp>|backup_setexp(8)>,
|
|
and L<B<backup volinfo>|backup_volinfo(8)>.
|
|
|
|
=item *
|
|
|
|
Commands to write and read tape labels:
|
|
L<B<backup labeltape>|backup_labeltape(8)>
|
|
and L<B<backup readlabel>|backup_readlabel(8)>.
|
|
|
|
=item *
|
|
|
|
Commands to list and change the status of backup operations and the
|
|
machines performing them:
|
|
L<B<backup jobs>|backup_jobs(8)>,
|
|
L<B<backup kill>|backup_kill(8)>,
|
|
and L<B<backup status>|backup_status(8)>.
|
|
|
|
=item *
|
|
|
|
Commands to enter and leave interactive mode:
|
|
L<B<backup interactive>|backup_interactive(8)>
|
|
and L<B<backup quit>|backup_quit(8)>.
|
|
|
|
=item *
|
|
|
|
Commands to check for and repair corruption in the Backup Database:
|
|
L<B<backup dbverify>|backup_dbverify(8)>,
|
|
L<B<backup restoredb>|backup_restoredb(8)>,
|
|
and L<B<backup savedb>|backup_savedb(8)>.
|
|
|
|
=item *
|
|
|
|
Commands to obtain help:
|
|
L<B<backup apropos>|backup_apropos(8)>
|
|
and L<B<backup help>|backup_help(8)>.
|
|
|
|
=back
|
|
|
|
The backup command interpreter interacts with two other processes:
|
|
|
|
=over 4
|
|
|
|
=item *
|
|
|
|
The Backup Server (B<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.
|
|
|
|
=item *
|
|
|
|
The Backup Tape Coordinator (B<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
|
|
F</usr/afs/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
|
|
F</usr/afs/backup/CFG_I<device_name>> for each Tape Coordinator records
|
|
information used to automate its operation.
|
|
|
|
=back
|
|
|
|
In addition to the standard command line interface, the B<backup> command
|
|
suite provides an I<interactive> interface, which has several useful
|
|
features described in L<backup_interactive(8)>. Three of the commands in
|
|
the suite are available only in interactive mode:
|
|
L<B<backup jobs>|backup_jobs(8)>,
|
|
L<B<backup kill>|backup_kill(8)>,
|
|
and L<B<backup quit>|backup_quit(8)>
|
|
|
|
=head1 OPTIONS
|
|
|
|
The following options are available on many commands in the B<backup>
|
|
suite. The reference page for each command also lists them, but they are
|
|
described here in greater detail.
|
|
|
|
=over 4
|
|
|
|
=item B<-cell> <I<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 F</usr/vice/etc/CellServDB> file on the local machine. If
|
|
the B<-cell> argument is omitted, the command interpreter determines the
|
|
name of the local cell by reading the following in order:
|
|
|
|
=over 4
|
|
|
|
=item *
|
|
|
|
The value of the AFSCELL environment variable.
|
|
|
|
=item *
|
|
|
|
The local F</usr/vice/etc/ThisCell> file.
|
|
|
|
=back
|
|
|
|
Do not combine the B<-cell> and B<-localauth> options. A command on which
|
|
the B<-localauth> flag is included always runs in the local cell (as
|
|
defined in the server machine's local F</usr/afs/etc/ThisCell> file),
|
|
whereas a command on which the B<-cell> argument is included runs in the
|
|
specified foreign cell.
|
|
|
|
The B<-cell> argument is not available on commands issued in interactive
|
|
mode. The cell defined when the B<backup> command interpreter enters
|
|
interactive mode applies to all commands issued during the interactive
|
|
session.
|
|
|
|
=item B<-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.
|
|
|
|
=item B<-localauth>
|
|
|
|
Constructs a server ticket using the server encryption key with the
|
|
highest key version number in the local F</usr/afs/etc/KeyFile> file. The
|
|
B<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 F</usr/afs/etc/KeyFile> file. The issuer
|
|
of a command that includes this flag must be logged on to the server
|
|
machine as the local superuser C<root>. The flag is useful for commands
|
|
invoked by an unattended application program, such as a process controlled
|
|
by the UNIX B<cron> utility or by a cron entry in the machine's
|
|
F</usr/afs/local/BosConfig> file. It is also useful if an administrator is
|
|
unable to authenticate to AFS but is logged in as the local superuser
|
|
C<root>.
|
|
|
|
Do not combine the B<-cell> and B<-localauth> options. A command on which
|
|
the B<-localauth> flag is included always runs in the local cell (as
|
|
defined in the server machine's local F</usr/afs/etc/ThisCell> file),
|
|
whereas a command on which the B<-cell> argument is included runs in the
|
|
specified foreign cell.
|
|
|
|
The B<-localauth> argument is not available on commands issued in
|
|
interactive mode. The local identity and AFS tokens with which the
|
|
B<backup> command interpreter enters interactive mode apply to all
|
|
commands issued during the interactive session.
|
|
|
|
=item B<-portoffset> <I<TC port offset>>
|
|
|
|
Specifies the port offset number of the Tape Coordinator that is to
|
|
execute the B<backup> command. The port offset number uniquely identifies
|
|
a pairing of a Tape Coordinator (B<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 B<backup> command that
|
|
involves reading or writing a tape, the backup operator must start a
|
|
B<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 B<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 F<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 C<0> through C<58510>. If the
|
|
issuer omits the argument, it defaults to C<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:
|
|
|
|
=over 4
|
|
|
|
=item *
|
|
|
|
The maximum number of dump or restore operations that can run
|
|
simultaneously is 64.
|
|
|
|
=item *
|
|
|
|
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 B<-portoffset> argument to the
|
|
L<B<backup diskrestore>|backup_diskrestore(8)>,
|
|
L<B<backup volrestore>|backup_volrestore(8)>,
|
|
or L<B<backup volsetrestore>|backup_volsetrestore(8)> command).
|
|
|
|
=back
|
|
|
|
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
|
|
B<butc> process fails and the following error message appears at the shell
|
|
prompt:
|
|
|
|
bind: Address already in use
|
|
rxi_GetUDPSocket: bind failed
|
|
|
|
=back
|
|
|
|
=head1 PRIVILEGE REQUIRED
|
|
|
|
To issue any backup command that accesses the Backup Database only, the
|
|
issuer must be listed in the F</usr/afs/etc/UserList> file on every
|
|
machine where the Backup Server is running. To issue any B<backup> command
|
|
that accesses volume data, the issuer must appear in the F<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 F<UserList> file is distributed to all database server and file
|
|
server machines in the cell. See the chapter on privileged users in the
|
|
I<OpenAFS Administration Guide> for more information on this type of
|
|
privilege.
|
|
|
|
If the B<-localauth> flag is included, the user must instead be logged on
|
|
as the local superuser C<root> on the server machine where the B<backup>
|
|
command is issued.
|
|
|
|
=head1 SEE ALSO
|
|
|
|
L<BosConfig(5)>,
|
|
L<CellServDB(5)>,
|
|
L<KeyFile(5)>,
|
|
L<ThisCell(5)>,
|
|
L<UserList(5)>,
|
|
L<butc(5)>,
|
|
L<tapeconfig(5)>,
|
|
L<backup_adddump(8)>,
|
|
L<backup_addhost(8)>,
|
|
L<backup_addvolentry(8)>,
|
|
L<backup_addvolset(8)>,
|
|
L<backup_apropos(8)>,
|
|
L<backup_dbverify(8)>,
|
|
L<backup_deldump(8)>,
|
|
L<backup_deletedump(8)>,
|
|
L<backup_delhost(8)>,
|
|
L<backup_delvolentry(8)>,
|
|
L<backup_delvolset(8)>,
|
|
L<backup_diskrestore(8)>,
|
|
L<backup_dump(8)>,
|
|
L<backup_dumpinfo(8)>,
|
|
L<backup_help(8)>,
|
|
L<backup_interactive(8)>,
|
|
L<backup_jobs(8)>,
|
|
L<backup_kill(8)>,
|
|
L<backup_labeltape(8)>,
|
|
L<backup_listdumps(8)>,
|
|
L<backup_listhosts(8)>,
|
|
L<backup_listvolsets(8)>,
|
|
L<backup_quit(8)>,
|
|
L<backup_readlabel(8)>,
|
|
L<backup_restoredb(8)>,
|
|
L<backup_savedb(8)>,
|
|
L<backup_scantape(8)>,
|
|
L<backup_setexp(8)>,
|
|
L<backup_status(8)>,
|
|
L<backup_volinfo(8)>,
|
|
L<backup_volrestore(8)>,
|
|
L<backup_volsetrestore(8)>,
|
|
L<buserver(8)>,
|
|
L<butc(8)>
|
|
|
|
=head1 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.
|