OPENAFS-SA-2018-001 backup: use authenticated connection to butc
[openafs.git] / doc / man-pages / pod8 / backup.pod
index ceadf8f..0900fe6 100644 (file)
@@ -4,7 +4,7 @@ backup - Introduction to the backup command suite
 
 =head1 DESCRIPTION
 
-The commands in the backup command suite are the administrative
+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:
 
@@ -13,220 +13,232 @@ commands in the suite:
 =item *
 
 Commands to copy data from AFS volumes to tape or a backup data file, and
-to restore it to the file system: B<backup diskrestore>,
-B<backup dump>, B<backup volrestore>, and B<backup
-volsetrestore>
-
+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:
-B<backup adddump>, B<backup addhost>, B<backup
-addvolentry>, B<backup addvolset>, B<backup deldump>,
-B<backup deletedump>, B<backup delhost>, B<backup
-delvolentry>, B<backup delvolset>, B<backup dumpinfo>,
-B<backup listdumps>, B<backup listhosts>, B<backup
-listvolsets>, B<backup scantape>, B<backup setexp>, and
-B<backup volinfo>
-
+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: backup labeltape
-and B<backup readlabel>
-
+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: B<(backup) jobs>, B<(backup)
-kill>, and B<backup status>
-
+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: backup
-(interactive) and B<(backup) quit>
-
+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:
-B<backup dbverify>, B<backup restoredb>, and B<backup
-savedb>
-
+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: B<backup apropos> and backup
-help
+Commands to obtain help:
+L<B<backup apropos>|backup_apropos(8)>
+and L<B<backup help>|backup_help(8)>.
+
+=item *
 
+A command to display the OpenAFS command suite version: B<backup version>.
 
 =back
 
-The backup command interpreter interacts with two other
-processes:
-L<(1)>
-L<(1)>
+The backup command interpreter interacts with two other processes:
 
 =over 4
 
 =item *
 
-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 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 (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.
-
+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
-B</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
-B</usr/afs/backup/CFG_>I<device_name> for each Tape Coordinator
-records information used to automate its operation.
+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 backup
-command suite provides an I<interactive> interface, which has several
-useful features described on the B<backup (interactive)> reference
-page. Three of the commands in the suite are available only in
-interactive mode: B<(backup) jobs>, B<(backup) kill>,
-and B<(backup) quit>.
+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.
-L<(1)>
-L<(1)>
-L<(1)>
+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 -cell <I<cell name>
->
+=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 B</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: 
+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:
 
-=item *
+=over 4
 
-The value of the AFSCELL environment variable
+=item *
 
+The value of the AFSCELL environment variable.
 
 =item *
 
-The local /usr/vice/etc/ThisCell file
+The local F</usr/vice/etc/ThisCell> file.
 
+=back
 
-Do not combine the B<-cell> and -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
-B</usr/afs/etc/ThisCell> file), whereas a command on which the
-B<-cell> argument is included runs in the specified foreign
-cell. 
+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 -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.
-L<(1)>
+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 -help
+=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.
+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 L<(1)
--localauth
->
+=item B<-localauth>
 
 Constructs a server ticket using the server encryption key with the
-highest key version number in the local B</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. 
+highest key version number in the local F</usr/afs/etc/KeyFile>
+or F</usr/afs/etc/KeyFileExt> 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 B</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 B<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 B</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 B<root>. 
-
-Do not combine the B<-cell> and -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
-B</usr/afs/etc/ThisCell> file), whereas a command on which the
-B<-cell> argument is included runs in the specified foreign
-cell. 
-
-The -localauth argument is not available on commands issued in
+machines do not usually have a F</usr/afs/etc/KeyFile> or
+F</usr/afs/etc/KeyFileExt> 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 L<(1)
--portoffset <I<TC port offset>>
->
+=item B<-nobutcauth>
+
+Prior to the fix for OPENAFS-SA-2018-001, B<butc> did not allow incoming
+connections to be authenticated.  As part of that fix, B<backup> was modified
+to authenticate to the B<butc> services when possible, but a B<backup> utility
+with the security fix will not interoperate with a B<butc> that lacks the fix
+unless this option is passed, which forces the use of unauthenticated
+connections to the B<butc>.  Use of this option is strongly disrecommended,
+and it is provided only for backwards compatibility in environments where
+B<backup> and B<butc> communicate over a secure network environment that denies
+access to untrusted parties.
+
+=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.
+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 B<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.
+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 B<0> through
-B<58510>. If the issuer omits the argument, it defaults to
-B<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.)
+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:
+cell, it is not possible to run 58,511 tape devices simultaneously, due to
+the following limits:
 
 =over 4
 
@@ -235,22 +247,21 @@ following limits:
 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 B<backup diskrestore>,
-B<backup volrestore>, or B<backup volsetrestore>
-command).
-
+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:
+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
@@ -259,68 +270,65 @@ appears at the shell prompt:
 
 =head1 PRIVILEGE REQUIRED
 
-To issue any backup command that accesses the Backup Database
-only, the issuer must be listed in the B</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 B<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 B<UserList> file is
-distributed to all database server and file server machines in the
-cell. See the chapter on privileged users in the I<IBM AFS
-Administration Guide> for more information on this type of
+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 -localauth flag is included, the user must instead be
-logged on as the local superuser B<root> on the server machine where
-the B<backup> command is issued.
+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(1)>,
-L<CFG_I<device_name>(1)>,
-L<CellServDB (client version)(1)>
-
-L<KeyFile(1)>,
-L<ThisCell (client version)(1)>
-
-L<ThisCell (server version)(1)>
-
-L<UserList(1)>,
-L<tapeconfig(1)>,
-L<backup_adddump(1)>,
-L<backup_addhost(1)>,
-L<backup_addvolentry(1)>,
-L<backup_addvolset(1)>,
-L<backup_dbverify(1)>,
-L<backup_deldump(1)>,
-L<backup_deletedump(1)>,
-L<backup_delhost(1)>,
-L<backup_delvolentry(1)>,
-L<backup_delvolset(1)>,
-L<backup_diskrestore(1)>,
-L<backup_dump(1)>,
-L<backup_dumpinfo(1)>,
-L<backup_help(1)>,
-L<backup_interactive(1)>,
-L<backup_jobs(1)>,
-L<backup_kill(1)>,
-L<backup_labeltape(1)>,
-L<backup_listdumps(1)>,
-L<backup_listhosts(1)>,
-L<backup_listvolsets(1)>,
-L<backup_quit(1)>,
-L<backup_readlabel(1)>,
-L<backup_restoredb(1)>,
-L<backup_savedb(1)>,
-L<backup_scantape(1)>,
-L<backup_setexp(1)>,
-L<backup_status(1)>,
-L<backup_volinfo(1)>,
-L<backup_volrestore(1)>,
-L<backup_volsetrestore(1)>,
-L<buserver(1)>,
-L<butc(1)>
+L<BosConfig(5)>,
+L<CellServDB(5)>,
+L<KeyFile(5)>,
+L<KeyFileExt(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