OPENAFS-SA-2018-001 backup: use authenticated connection to butc
[openafs.git] / doc / man-pages / pod8 / backup.pod
index c199d90..0900fe6 100644 (file)
@@ -13,42 +13,68 @@ 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>.
+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: B<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: B<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 B<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
 
@@ -86,8 +112,10 @@ information used to automate its operation.
 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: B<backup jobs>, B<backup
-kill>, and B<backup quit>.
+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
 
@@ -138,13 +166,15 @@ 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
+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 F</usr/afs/etc/KeyFile> file.  The issuer
+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
@@ -164,6 +194,18 @@ 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<-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
@@ -209,8 +251,10 @@ 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 B<-portoffset> argument to the B<backup diskrestore>,
-B<backup volrestore>, or B<backup volsetrestore> command).
+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
 
@@ -234,7 +278,7 @@ 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<IBM AFS Administration Guide> for more information on this type of
+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
@@ -246,6 +290,7 @@ command is issued.
 L<BosConfig(5)>,
 L<CellServDB(5)>,
 L<KeyFile(5)>,
+L<KeyFileExt(5)>,
 L<ThisCell(5)>,
 L<UserList(5)>,
 L<butc(5)>,
@@ -254,6 +299,7 @@ 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)>,