man8-editing-pass-20051213
authorRuss Allbery <rra@stanford.edu>
Tue, 13 Dec 2005 19:21:13 +0000 (19:21 +0000)
committerRuss Allbery <rra@stanford.edu>
Tue, 13 Dec 2005 19:21:13 +0000 (19:21 +0000)
This completes the initial editing pass of the section eight man pages.
Only small amounts of content editing has been done.  Some known problems
have been noted in README, but there will doubtless be others, as well as
some lingering formatting problems.  However, the quality should now be
good enough for general public review.

Some of the section eight man pages were really supposed to be section one,
the package apropros and package help commands are too useless to document,
and a few of the difficult-to-name section five man pages have now acquired
names.

128 files changed:
doc/man-pages/README
doc/man-pages/pod1/package_test.pod [moved from doc/man-pages/pod8/package_test.pod with 64% similarity]
doc/man-pages/pod1/xstat_cm_test.pod [moved from doc/man-pages/pod8/xstat_cm_test.pod with 50% similarity]
doc/man-pages/pod1/xstat_fs_test.pod [new file with mode: 0644]
doc/man-pages/pod5/package.pod [new file with mode: 0644]
doc/man-pages/pod5/tapeconfig.pod [moved from doc/man-pages/pod8/tapeconfig.pod with 89% similarity]
doc/man-pages/pod5/uss.pod [new file with mode: 0644]
doc/man-pages/pod5/uss_bulk.pod [new file with mode: 0644]
doc/man-pages/pod8/afsd.pod
doc/man-pages/pod8/backup.pod
doc/man-pages/pod8/backup_adddump.pod
doc/man-pages/pod8/backup_addhost.pod
doc/man-pages/pod8/backup_addvolentry.pod
doc/man-pages/pod8/backup_addvolset.pod
doc/man-pages/pod8/backup_apropos.pod
doc/man-pages/pod8/backup_dbverify.pod
doc/man-pages/pod8/backup_deldump.pod
doc/man-pages/pod8/backup_deletedump.pod
doc/man-pages/pod8/backup_delhost.pod
doc/man-pages/pod8/backup_delvolentry.pod
doc/man-pages/pod8/backup_delvolset.pod
doc/man-pages/pod8/backup_diskrestore.pod
doc/man-pages/pod8/backup_dump.pod
doc/man-pages/pod8/backup_dumpinfo.pod
doc/man-pages/pod8/backup_help.pod
doc/man-pages/pod8/backup_interactive.pod
doc/man-pages/pod8/backup_jobs.pod
doc/man-pages/pod8/backup_kill.pod
doc/man-pages/pod8/backup_labeltape.pod
doc/man-pages/pod8/backup_listdumps.pod
doc/man-pages/pod8/backup_listhosts.pod
doc/man-pages/pod8/backup_listvolsets.pod
doc/man-pages/pod8/backup_quit.pod
doc/man-pages/pod8/backup_readlabel.pod
doc/man-pages/pod8/backup_restoredb.pod
doc/man-pages/pod8/backup_savedb.pod
doc/man-pages/pod8/backup_scantape.pod
doc/man-pages/pod8/backup_setexp.pod
doc/man-pages/pod8/backup_status.pod
doc/man-pages/pod8/backup_volinfo.pod
doc/man-pages/pod8/backup_volrestore.pod
doc/man-pages/pod8/backup_volsetrestore.pod
doc/man-pages/pod8/bos.pod
doc/man-pages/pod8/bos_addhost.pod
doc/man-pages/pod8/bos_addkey.pod
doc/man-pages/pod8/bos_adduser.pod
doc/man-pages/pod8/bos_apropos.pod
doc/man-pages/pod8/bos_create.pod
doc/man-pages/pod8/bos_delete.pod
doc/man-pages/pod8/bos_exec.pod
doc/man-pages/pod8/bos_getdate.pod
doc/man-pages/pod8/bos_getlog.pod
doc/man-pages/pod8/bos_getrestart.pod
doc/man-pages/pod8/bos_help.pod
doc/man-pages/pod8/bos_install.pod
doc/man-pages/pod8/bos_listhosts.pod
doc/man-pages/pod8/bos_listkeys.pod
doc/man-pages/pod8/bos_listusers.pod
doc/man-pages/pod8/bos_prune.pod
doc/man-pages/pod8/bos_removehost.pod
doc/man-pages/pod8/bos_removekey.pod
doc/man-pages/pod8/bos_removeuser.pod
doc/man-pages/pod8/bos_restart.pod
doc/man-pages/pod8/bos_salvage.pod
doc/man-pages/pod8/bos_setauth.pod
doc/man-pages/pod8/bos_setcellname.pod
doc/man-pages/pod8/bos_setrestart.pod
doc/man-pages/pod8/bos_shutdown.pod
doc/man-pages/pod8/bos_start.pod
doc/man-pages/pod8/bos_startup.pod
doc/man-pages/pod8/bos_status.pod
doc/man-pages/pod8/bos_stop.pod
doc/man-pages/pod8/bos_uninstall.pod
doc/man-pages/pod8/bosserver.pod
doc/man-pages/pod8/buserver.pod
doc/man-pages/pod8/butc.pod
doc/man-pages/pod8/fileserver.pod
doc/man-pages/pod8/fms.pod
doc/man-pages/pod8/fstrace.pod
doc/man-pages/pod8/fstrace_apropos.pod
doc/man-pages/pod8/fstrace_clear.pod
doc/man-pages/pod8/fstrace_dump.pod
doc/man-pages/pod8/fstrace_help.pod
doc/man-pages/pod8/fstrace_lslog.pod
doc/man-pages/pod8/fstrace_lsset.pod
doc/man-pages/pod8/fstrace_setlog.pod
doc/man-pages/pod8/fstrace_setset.pod
doc/man-pages/pod8/kadb_check.pod
doc/man-pages/pod8/kas.pod
doc/man-pages/pod8/kas_apropos.pod
doc/man-pages/pod8/kas_create.pod
doc/man-pages/pod8/kas_delete.pod
doc/man-pages/pod8/kas_examine.pod
doc/man-pages/pod8/kas_forgetticket.pod
doc/man-pages/pod8/kas_help.pod
doc/man-pages/pod8/kas_interactive.pod
doc/man-pages/pod8/kas_list.pod
doc/man-pages/pod8/kas_listtickets.pod
doc/man-pages/pod8/kas_noauthentication.pod
doc/man-pages/pod8/kas_quit.pod
doc/man-pages/pod8/kas_setfields.pod
doc/man-pages/pod8/kas_setpassword.pod
doc/man-pages/pod8/kas_statistics.pod
doc/man-pages/pod8/kas_stringtokey.pod
doc/man-pages/pod8/kas_unlock.pod
doc/man-pages/pod8/kaserver.pod
doc/man-pages/pod8/kdb.pod
doc/man-pages/pod8/kpwvalid.pod
doc/man-pages/pod8/package.pod
doc/man-pages/pod8/package_apropos.pod [deleted file]
doc/man-pages/pod8/package_help.pod [deleted file]
doc/man-pages/pod8/prdb_check.pod
doc/man-pages/pod8/ptserver.pod
doc/man-pages/pod8/salvager.pod
doc/man-pages/pod8/upclient.pod
doc/man-pages/pod8/upserver.pod
doc/man-pages/pod8/uss.pod
doc/man-pages/pod8/uss_add.pod
doc/man-pages/pod8/uss_apropos.pod
doc/man-pages/pod8/uss_bulk.pod
doc/man-pages/pod8/uss_delete.pod
doc/man-pages/pod8/uss_help.pod
doc/man-pages/pod8/vldb_check.pod
doc/man-pages/pod8/vlserver.pod
doc/man-pages/pod8/volinfo.pod
doc/man-pages/pod8/volserver.pod
doc/man-pages/pod8/xfs_size_check.pod
doc/man-pages/pod8/xstat_fs_test.pod [deleted file]

index 15074a9..4bcfaef 100644 (file)
@@ -223,6 +223,32 @@ Known Problems
    * fs sysname documentation needs to include the possibility of setting
      multiple sysnames and the resulting behavior.
 
+   * The afsd man page is horribly out of date.  It doesn't explain
+     dynroot, many options are missing, and some of the options described
+     are no longer valid.  It also still assumes that -settime is the
+     default and says that the system must be rebooted after shutdown,
+     which isn't the case at least on Linux.
+
+   * All of the paths in the man pages are the Transarc paths.  I'm not
+     sure how best to deal with the possibility of installing OpenAFS in
+     multiple different paths, but it would be good to at least
+     acknowledge the issue.
+
+   * bos listkeys assumes that you're using the kaserver.
+
+   * I'm fairly sure that the fileserver man page no longer documents all
+     of the fileserver options.
+
+   * The package man page should probably mention the (pointless) package
+     apropos and package help commands, or they could be removed.  There
+     used to be separate man pages for them, but that seemed rather
+     pointless.
+
+   * There are lingering references to AFS Development or AFS Product
+     Support in descriptions of options that one should generally not
+     use.  Also, all of the manual references refer to the "IBM" manual.
+     We should decide how to handle this terminology-wise.
+
   If you notice other problems, please send them to the openafs-doc list
   even if you don't have time to fix them.  Someone else might, and we
   want to track all of the issues.
similarity index 64%
rename from doc/man-pages/pod8/package_test.pod
rename to doc/man-pages/pod1/package_test.pod
index 91e98f6..58ffbb1 100644 (file)
@@ -4,24 +4,22 @@ package_test - Tests the validity of a package configuration file
 
 =head1 SYNOPSIS
 
-package_test <I<config file>>
-
-This command does not use the syntax conventions of the AFS command
-suites. Provide the command name in full.
+B<package_test> <I<config file>>
 
 =head1 DESCRIPTION
 
-The package_test command tests the validity of a
-B<package> configuration file created when a prototype file is
-compiled. The command interpreter prints error messages on the standard
-output stream.
+The B<package_test> command tests the validity of a B<package>
+configuration file created when a prototype file is compiled. The command
+interpreter prints error messages on the standard output stream.
+
+This command does not use the syntax conventions of the AFS command
+suites. Provide the command name in full.
 
 =head1 OPTIONS
 
 =over 4
 
-=item I<config file
->
+=item <I<config file>>
 
 Specifies the package configuration file to validate.
 
@@ -29,8 +27,8 @@ Specifies the package configuration file to validate.
 
 =head1 EXAMPLES
 
-The following example tests the validity of the package
-configuration file I<staff.sun4x_56>.
+The following example tests the validity of the package configuration file
+C<staff.sun4x_56>.
 
    % package_test staff.sun4x_56
 
@@ -40,9 +38,8 @@ None
 
 =head1 SEE ALSO
 
-L<package Configuration File(1)>
-
-L<package(1)>
+L<package(5)>,
+L<package(8)>
 
 =head1 COPYRIGHT
 
similarity index 50%
rename from doc/man-pages/pod8/xstat_cm_test.pod
rename to doc/man-pages/pod1/xstat_cm_test.pod
index ce39816..dea9ac9 100644 (file)
@@ -4,22 +4,23 @@ xstat_cm_test - Displays data collections from the Cache Manager
 
 =head1 SYNOPSIS
 
-B<xstat_cm_test> [B<initcmd>] -cmname <I<Cache Manager name(s) to monitor>>+
-B<-collID> <I<Collection(s) to fetch>>+  [B<-onceonly>]  
-              [-frequency <I<poll frequency, in seconds>>]  
-              [B<-period> <I<data collection time, in minutes>>]  [B<-debug>]  [-help]
-
-B<xstat_cm_test> [B<i>] -cm <I<Cache Manager name(s) to monitor>>+
-B<-co> <I<Collection(s) to fetch>>+  [B<-o>]  
-              [-f <I<poll frequency, in seconds>>]  
-              [B<-p> <I<data collection time, in minutes>>]  [B<-d>]  [-h]
+B<xstat_cm_test> [I<initcmd>]
+    B<-cmname> <I<cache manager name(s) to monitor>>+
+    B<-collID> <I<collection(s) to fetch>>+ [B<-onceonly>]  
+    [B<-frequency> <I<poll frequency, in seconds>>]  
+    [B<-period> <I<data collection time, in minutes>>] [B<-debug>]
+    [B<-help>]
+
+B<xstat_cm_test> [I<i>] B<-cm> <I<cache manager name(s) to monitor>>+
+    B<-co> <I<collection(s) to fetch>>+ [B<-o>]
+    [B<-f> <I<poll frequency, in seconds>>]  
+    [B<-p> <I<data collection time, in minutes>>] [B<-d>] [B<-h>]
 
 =head1 DESCRIPTION
 
-The xstat_cm_test command tests the routines in the
-B<libxstat_cm.a> library and displays the data collections
-associated with the Cache Manager. The command executes in the
-foreground.
+The B<xstat_cm_test> command tests the routines in the F<libxstat_cm.a>
+library and displays the data collections associated with the Cache
+Manager. The command executes in the foreground.
 
 The command produces a large volume of output; to save it for later
 analysis, direct it to a file.
@@ -28,17 +29,16 @@ analysis, direct it to a file.
 
 =over 4
 
-=item initcmd
+=item I<initcmd>
 
-Accommodates the command's use of the AFS command parser, and is
-optional.
+Accommodates the command's use of the AFS command parser, and is optional.
 
-=item -cmname
+=item B<-cmname> <I<cache manager name to monitor>>+
 
 Specifies the fully qualified hostname of each client machine for which to
 monitor the Cache Manager.
 
-=item -collID
+=item B<-collID> <I<collection to fetch>>+
 
 Specifies each data collection to return, which defines the type and
 amount of data the command interpreter gathers about the Cache Manager.
@@ -57,44 +57,44 @@ started.
 =item 1
 
 Reports various internal performance statistics related to the Cache
-Manager (for example, statistics about how effectively the cache is being used
-and the quantity of intracell and intercell data access).
+Manager (for example, statistics about how effectively the cache is being
+used and the quantity of intracell and intercell data access).
 
 =item 2
 
-Reports all of the internal performance statistics provided by the
-B<1> setting, plus some additional, detailed performance figures (for
-example, statistics about the number of RPCs sent by the Cache Manager and how
-long they take to complete, and statistics regarding authentication, access,
+Reports all of the internal performance statistics provided by the C<1>
+setting, plus some additional, detailed performance figures (for example,
+statistics about the number of RPCs sent by the Cache Manager and how long
+they take to complete, and statistics regarding authentication, access,
 and PAG information associated with data access).
 
 =back
 
-=item -onceonly
+=item B<-onceonly>
 
-Gathers statistics just one time. Omit this flag to have the
-command continue to probe the Cache Manager for statistics at the frequency
-specified by the B<-frequency> argument; in this case press
-<B<Ctrl-c>> to stop the probes.
+Gathers statistics just one time. Omit this flag to have the command
+continue to probe the Cache Manager for statistics at the frequency
+specified by the B<-frequency> argument; in this case press Ctrl-C to stop
+the probes.
 
-=item -frequency
+=item B<-frequency> <I<poll frequency>>
 
 Sets the frequency in seconds at which the program initiates probes to the
 Cache Manager. The default is 30 seconds.
 
-=item -period
+=item B<-period> <I<data collection time>>
 
-Sets the number of minutes the program runs; at the end of this
-period of time, the program exits. The default is 10 minutes.
+Sets the number of minutes the program runs; at the end of this period of
+time, the program exits. The default is 10 minutes.
 
-=item -debug
+=item B<-debug>
 
 Displays a trace on the standard output stream as the command runs.
 
-=item -help
+=item B<-help>
 
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
 
 =back
 
diff --git a/doc/man-pages/pod1/xstat_fs_test.pod b/doc/man-pages/pod1/xstat_fs_test.pod
new file mode 100644 (file)
index 0000000..81c1555
--- /dev/null
@@ -0,0 +1,107 @@
+=head1 NAME
+
+xstat_fs_test - Displays data collections from the File Server process
+
+=head1 SYNOPSIS
+
+B<xstat_fs_test> [I<initcmd>] B<-fsname> <I<file server name(s) to monitor>>+
+    B<-collID> <I<collection(s) to fetch>>+ [B<-onceonly>]
+    [B<-frequency> <I<poll frequency, in seconds>>]
+    [B<-period> <I<data collection time, in minutes>>] [B<-debug>] [B<-help>]
+
+B<xstat_fs_test> [B<initcmd>] B<-fs> <I<File Server name(s) to monitor>>+
+    B<-c> <I<Collection(s) to fetch>>+ [B<-o>]
+    [B<-fr> <I<poll frequency, in seconds>>]
+    [B<-p> <I<data collection time, in minutes>>] [B<-d>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<xstat_fs_test> command tests the routines in the F<libxstat_fs.a>
+library and displays the data collections associated with the File Server
+(the C<fs> process). The command executes in the foreground.
+
+The command produces a large volume of output; to save it for later
+analysis, direct it to a file.
+
+=head1 OPTIONS
+
+=over 4
+
+=item I<initcmd>
+
+Accommodates the command's use of the AFS command parser, and is optional.
+
+=item B<-fsname> <I<file server name to monitor>>+
+
+Specifies the fully qualified hostname of each file server machine for
+which to monitor the File Server process.
+
+=item B<-collID> <I<collection to fetch>>+
+
+Specifies each data collection to return, which defines the type and
+amount of data the command interpreter gathers about the File Server.
+Data is returned in a predefined data structure.
+
+There are three acceptable values: 
+
+=over 4
+
+=item 0
+
+Provides profiling information about the numbers of times different
+internal File Server routines were called since the File Server
+started. This value is not currently implemented; it returns no data.
+
+=item 1
+
+Reports various internal performance statistics related to the File Server
+(for example, vnode cache entries and Rx protocol activity).
+
+=item 2
+
+Reports all of the internal performance statistics provided by the C<1>
+setting, plus some additional, detailed performance figures about the File
+Server (for example, minimum, maximum, and cumulative statistics regarding
+File Server RPCs, how long they take to complete, and how many succeed).
+
+=back
+
+=item B<-onceonly>
+
+Gathers statistics just one time. Omit this flag to have the command
+continue to probe the Cache Manager for statistics at the frequency
+specified by the B<-frequency> argument; in this case press Ctrl-C to stop
+the probes.
+
+=item B<-frequency> <I<poll frequency>>
+
+Sets the frequency in seconds at which the program initiates probes to the
+Cache Manager. The default is 30 seconds.
+
+=item B<-period> <I<data collection time>>
+
+Sets the number of minutes the program runs; at the end of this period of
+time, the program exits. The default is 10 minutes.
+
+=item B<-debug>
+
+Displays a trace on the standard output stream as the command runs.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 SEE ALSO
+
+L<xstat_cm_test(1)>
+
+=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.
diff --git a/doc/man-pages/pod5/package.pod b/doc/man-pages/pod5/package.pod
new file mode 100644 (file)
index 0000000..6833d4d
--- /dev/null
@@ -0,0 +1,878 @@
+=head1 NAME
+
+package Configuration File - Provides instructions for the package command
+
+=head1 DESCRIPTION
+
+The package configuration file defines the file system elements
+that the B<package> command creates or alters on the local disk of an
+AFS client machine it is configuring. Use the B<-config> or
+B<-fullconfig> argument to the B<package> command to identify
+the configuration file to use.
+
+Summary of Configuration File Instructions
+
+The configuration file can include one or more instances of each of the
+following instructions, each on its own line. A more detailed
+description of each instruction's syntax follows this list.
+
+=over 4
+
+=item B
+
+Defines a block special device, such as a disk, which deals with input in
+units of multi-byte command blocks
+
+=item C
+
+Defines a character special device, such as a terminal or tty, which deals
+with input in single character units
+
+=item D
+
+Creates a directory
+
+=item F
+
+Creates or alters a file to match the contents of a specified source file
+
+=item L
+
+Creates a symbolic link
+
+=item S
+
+Defines a socket, which is a communications device for UDP and TCP/IP
+connections
+
+=item %define
+
+Defines a variable or declares a string as defined
+
+=item %ifdef
+
+Specifies an action to perform if a certain string is declared or defined
+
+=item %ifndef
+
+Specifies an action to perform if a certain string is not declared or
+defined
+
+=item %include
+
+Includes a library file
+
+=item %undef
+
+Declares a string not to be defined, or a variable no longer to have a
+value
+
+=back
+
+The B and C Instructions for Defining Block and Character Special
+Devices
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+
+The B<B> instruction in a package configuration file
+defines a block special device, such as a disk, that deals with input in units
+of multi-byte command blocks. The B<C> instruction defines a
+character special device, such as a terminal or tty, that deals with input in
+single character units. They share a common syntax:
+
+   {B<B >| C}   I<device_name>  I<major_device>  I<minor_device>  I<owner>  I<group>  I<mode_bits>
+
+where
+
+=over 4
+
+=item B
+
+Indicates the definition of a block special device. It must be a
+capital letter.
+
+=item C
+
+Indicates the definition of character special device. It must be a
+capital letter.
+
+=item I<device_name
+>
+
+Names the special device to define. To learn the name format
+appropriate to the machine's system type, consult the hardware or
+operating system documentation.
+
+=item I<major_device
+>
+
+Specifies the device's major device number in decimal format.
+To learn the correct value for the machine's system type, consult the
+hardware or operating system documentation.
+
+=item I<minor_device
+>
+
+Specifies the device's minor device number in one of hexadecimal,
+octal, or decimal format. Precede a hexadecimal number with the string
+B<0x> (zero and the letter B<x>) or an octal number with a
+B<0> (zero). A number without either prefix is interpreted as a
+decimal. To learn the correct value for the machine's system type,
+consult the hardware or operating system documentation.
+
+=item I<owner
+>
+
+Specifies the username or UNIX user ID (UID) of the user to be designated
+the device's owner in the output from the UNIX B<ls -l>
+command.
+
+=item I<group
+>
+
+Specifies the group name or UNIX group ID (GID) of the group to be
+designated the device's group in the output from the UNIX B<ls
+-lg> command.
+
+=item I<mode_bits
+>
+
+Defines the device's UNIX mode bits. Acceptable values are the
+standard three- or four-digit numbers corresponding to combinations of
+permissions. Examples: B<755> corresponds to
+B<rwxr-xr-x>, and B<644> to B<rw-r--r-->.
+
+=back
+
+The D Instruction for Creating a Directory
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+
+The B<D> instruction in a package configuration file
+creates a directory on the local disk. If a symbolic link, file, or
+other element on the local disk has the same name, it is replaced with a
+directory. If the directory already exists, its owner, group, and mode
+bits are changed if necessary to conform with the instruction. The
+instruction has the following syntax:
+
+   D[I<update_code>]  I<directory>  I<owner>  I<group>  I<mode_bits>
+
+where
+
+=over 4
+
+=item D
+
+Indicates the creation of a directory. It must be a capital
+letter.
+
+=item I<update_code
+>
+
+Modulates the directory creation instruction. It is optional and
+follows the letter B<D> directly, without an intervening space.
+Choose one of the two acceptable values: 
+
+=over 4
+
+=item X
+
+Indicates that the directory is a lost+found directory (used by
+the B<fsck> program).
+
+=item R
+
+Removes any subdirectory (along its contents) or file that exists in the
+existing directory on the local disk but for which an instruction does not
+appear in the configuration file.
+
+=back
+
+=item I<directory
+>
+
+Specifies the full pathname of the directory to create.
+
+=item I<owner
+>
+
+Specifies the username or UNIX user ID (UID) of the user to be designated
+the directory's owner in the output from the UNIX B<ls -ld>
+command.
+
+=item I<group
+>
+
+Specifies the name or UNIX group ID (GID) of the group to be designated
+the directory's group in the output from the UNIX B<ls -lgd>
+command.
+
+=item I<mode_bits
+>
+
+Defines the directory's UNIX mode bits. Acceptable values are
+the standard three- or four-digit numbers corresponding to combinations of
+permissions. Examples: B<755> corresponds to
+B<drwxr-xr-x>, and B<644> to B<drw-r--r-->.
+
+=back
+
+The F Instruction for Creating or Updating a File
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+
+The B<F> instruction in a package configuration file
+creates or updates a file on the local disk by copying in the contents of the
+indicated source file, which can reside in AFS or on the local disk. If
+the B<package> command interpreter cannot access the source file, it
+exits without executing any instruction in the configuration file.
+
+If a file with the same name already exists on disk, the package
+command overwrites it with the contents of the source file, unless the
+B<I> update code is used to prevent that. To add a
+B<.old> extension to the current version of the file, include
+the B<O> update code. To have the machine reboot automatically
+after the B<package> program completes, include the B<Q>
+update code.
+
+If a symbolic link, directory, or other element on the local disk has the
+same name, it is replaced with the file (a directory's contents are first
+removed as necessary).
+
+The instruction has the following syntax:
+
+   F[I<update_code>]  I<file>  I<source_file>  [I<owner  group  mode_bits>]
+
+where
+
+=over 4
+
+=item F
+
+Indicates the creation or update of a file. It must be a capital
+letter.
+
+=item I<update_code
+>
+
+Modulates the file creation instruction. It is optional and follows
+the letter B<F> directly, without an intervening space. Choose
+one or more of the four acceptable values, and list them in any order: 
+
+=over 4
+
+=item A
+
+Indicates that the pathname in the I<source_file> field is the
+complete pathname of the source file, including the filename. If this
+argument is omitted, the B<package> command appends the pathname in
+the I< file> field to the pathname in the I<source_file> field to
+derive the source file's full name. This code allows the source
+and target filenames to differ.
+
+=item I
+
+Preserves the existing file called I<file>, rather than overwriting
+it.
+
+=item O
+
+Saves the existing version of the file by appending a
+B<.old> extension to it.
+
+=item Q
+
+Causes the package command to exit with status code
+B<4> if it overwrites the file. If the standard
+B<package>-related changes have been made to the machine's AFS
+initialization file, then status code B<4> causes the machine to
+reboot automatically. Use this code when the machine must reboot if
+updates to the file are to have any effect (for example, if the operating
+system file--B</vmunix> or equivalent--has changed).
+
+=back
+
+=item I<file
+>
+
+Specifies the complete pathname on the local disk of the file to create or
+update, including the filename as the final element.
+
+=item I<source_file
+>
+
+Specifies the pathname (local or AFS) of the file to copy to the local
+disk.
+
+If the A update code is included, specify the source file's
+complete pathname. Otherwise, the B<package> command derives
+the source file's full name by appending the I<file> pathname to
+this pathname. For example, if the B<A> update code is not
+included and the file B</afs/abc.com/rs_aix42/bin/grep> is the
+source file for the B</bin/grep> binary, the proper value in this
+field is B</afs/abc.com/rs_aix42>.
+
+=item I<owner
+>
+
+Specifies the username or UNIX user ID (UID) of the user to be designated
+the file's owner in the output from the UNIX B<ls -l>
+command. 
+
+To copy the source file's owner to the target file, leave this field
+empty. In this case, the I<group> and I<mode_bits> fields
+must also be empty.
+
+=item I<group
+>
+
+Specifies the name or UNIX group ID (GID) of the group to be designated
+the file's group in the output from the UNIX B<ls -lg>
+command. 
+
+To copy the source file's group to the target file, leave this field
+empty. In this case, the I< owner> and I<mode_bits> fields
+must also be empty.
+
+=item I<mode_bits
+>
+
+Defines the file's UNIX mode bits. Acceptable values are the
+standard three- or four-digit numbers corresponding to combinations of
+permissions. Examples: B<755> corresponds to
+B<rwxr-xr-x>, and B<644> to B<rw-r--r-->. 
+
+To copy the source file's mode bits to the target file, leave this
+field empty. In this case, the I<owner> and I<group> fields
+must also be empty.
+
+=back
+
+The L Instruction for Creating a Symbolic Link
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+
+The B<L> instruction in a package configuration file
+creates a symbolic link on the local disk to a directory or file that exists
+either in AFS or elsewhere on the local disk. As with the standard UNIX
+B<ln -s> command, the link is created even if the actual file or
+directory does not exist.
+
+If a file or directory on the local disk already has the same name, the
+B<package> command replaces it with a symbolic link.
+
+The instruction has the following syntax:
+
+   L[I<update_code>]  I<link>  I<actual_path>  [I<owner  group  mode_bits>]
+
+where
+
+=over 4
+
+=item L
+
+Indicates the creation of a symbolic link. It must be a capital
+letter.
+
+=item I<update_code
+>
+
+Modulates the link creation instruction. It is optional and follows
+the letter B<L> directly, without an intervening space. Choose
+one or both of the acceptable values, and list them in any order: 
+
+=over 4
+
+=item A
+
+Indicates that the pathname in the I<actual_path> field is the
+complete pathname of the actual directory or file (including the filename for
+a file). If this argument is omitted, the B<package> command
+appends the value in the I<link> field to the pathname in the
+I<actual_path> field to derive the actual directory or file's full
+name. This code allows the name of the symbolic link and actual
+directory or file to differ.
+
+=item I
+
+Preserves the existing symbolic link called I<link>, rather than
+overwriting it.
+
+=back
+
+=item I<link
+>
+
+Specifies the complete local disk pathname of the symbolic link to
+create.
+
+=item I<actual_path
+>
+
+Specifies the pathname (local or AFS) of the directory or file to which
+the link refers. If the B<A> update code is included, specify
+the directory or file's complete pathname. Otherwise, the
+B<package> command derives the actual directory or file's full
+name by appending the value in the I<link> field to this
+pathname. For example, if the B<A> update code is not included
+and B</etc/ftpd> is a symbolic link to the file
+B</afs/abc.com/sun4x_56/etc/ftpd>, the proper value in this
+field is B</afs/abc.com/sun4x_56>.
+
+The package command interpreter correctly handles pathnames that
+begin with the B<./> (period, slash) or
+B<../> (two periods, slash) notation, interpreting them
+relative to the current working directory from which the B<package>
+command is invoked.
+
+=item I<owner
+>
+
+Specifies the username or UNIX user ID (UID) of the user to be designated
+the symbolic link's owner in the output from the UNIX B<ls -l>
+command.
+
+To designate the issuer of the package command (usually, the
+local superuser B<root>) as the symbolic link's owner, leave this
+field empty. In this case, the I<group> and I<mode_bits>
+fields must also be empty.
+
+=item I<group
+>
+
+Specifies the name or UNIX group ID (GID) of the group to be designated
+the link's group in the output from the UNIX B<ls -lg>
+command.
+
+To have the symbolic link's group match the default group associated
+with the B<package> command's issuer, leave this field
+empty. The issuer is usually the local superuser B<root> and
+the default group is designated in the issuer's entry in the local
+B</etc/passwd> file or equivalent. If this field is left empty,
+the I<owner> and I<mode_bits> fields must also be empty.
+
+=item I<mode_bits
+>
+
+Defines the symbolic link's UNIX mode bits. Acceptable values
+are the standard three- or four-digit numbers corresponding to combinations of
+permissions. Examples: B<755> corresponds to
+B<rwxr-xr-x>, and B<644> to B<rw-r--r-->.
+
+Leaving this field empty sets the symbolic link's mode bits to
+B<777> (B<rwxrwxrwx>). In this case, the I<owner>
+and I<group> fields must also be empty.
+
+=back
+
+The S Instruction for Creating a Socket
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+
+The B<S> instruction in a package configuration file
+creates a socket (a communications device for UDP or TCP/IP connections) on
+the local disk. The instruction has the following syntax:
+
+   S  I<socket> [I<owner  group  mode_bits>]
+
+where
+
+=over 4
+
+=item S
+
+Indicates the creation of a socket. It must be a capital
+letter.
+
+=item I<socket
+>
+
+Names the socket. The proper format depends on the local
+machine's operating system.
+
+=item I<owner
+>
+
+Specifies the username or UNIX user ID (UID) of the user to be designated
+the socket's owner in the output from the UNIX B<ls -l>
+command.
+
+To designate the issuer of the package command (usually, the
+local superuser B<root>) as the socket's owner, leave this field
+empty. In this case, the I<group> and I<mode_bits> fields
+must also be empty.
+
+=item I<group
+>
+
+Specifies the name or UNIX group ID (GID) of the group to be designated
+the socket's group in the output from the UNIX B<ls -lg>
+command.
+
+To have the symbolic link's group match the default group associated
+with the B<package> command's issuer, leave this field
+empty. The issuer is usually the local superuser B<root> and
+the default group is designated in the issuer's entry in the local
+B</etc/passwd> file or equivalent. If this field is left empty,
+the I<owner> and I<mode_bits> fields must also be empty.
+
+=item I<mode_bits
+>
+
+Defines the socket's UNIX mode bits. Acceptable values are the
+standard three- or four-digit numbers corresponding to combinations of
+permissions. Examples: B<755> corresponds to
+B<rwxr-xr-x>, and B<644> to B<rw-r--r-->.
+
+Leaving this field empty sets the symbolic link's mode bits to
+B<777> (B<rwxrwxrwx>), modulated by the cell's
+umask. In this case, the I<owner> and I<group> fields must
+also be empty.
+
+=back
+
+The %define or %undef Instructions Declaring or Undeclaring a
+Definition
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+
+The B<%define> instruction in a package configuration
+file declares or defines a variable, depending on its number of
+arguments:
+
+=over 4
+
+=item *
+
+If followed by a single argument, it declares that argument to be
+defined. The argument is then available as a controller when mentioned
+in B<%ifdef> and B<%ifndef> statements, which evaluate to
+B<true> and B<false> respectively.
+
+
+=item *
+
+If followed by two arguments, it defines the second argument as the value
+of the first. When the first argument appears later in this prototype
+or other prototype or library files as a variable--surrounded by curly
+braces and preceded by a dollar sign, as in the example
+C<${variable}>--the B<package> command interpreter
+substitutes the second argument for it.
+
+
+=back
+
+The %undef statement negates the effect of a previous
+B<%define> statement, declaring its argument to be defined no longer,
+or to have a value no longer if it is a variable.
+
+The syntax for the two types of instruction are as follows:
+
+   %define  I<declaration>
+   %define  I<variable>  I<value>
+   %undef  I<declaration>
+   %undef  I<variable>
+
+where
+
+=over 4
+
+=item %define
+
+Indicates a definition statement.
+
+=item %undef
+
+Indicates a statement that negates a definition.
+
+=item I<declaration
+>
+
+Names the string being declared by a %define statement, or
+negated by an B<%undef> statement.
+
+=item I<variable
+>
+
+Specifies the name of the variable that a %define statement is
+defining, or an B<%undef> statement is negating.
+
+=item I<value
+>
+
+Specifies the value to substitute for the string in the I<variable>
+field when it appears in the appropriate format (surrounded by curly braces
+and preceded by a dollar sign, as in the example C<${variable}>), in
+this or other prototype and library files. It can include one or more
+words.
+
+=back
+
+The %ifdef and %ifndef Instructions for Specifying a Conditional
+Action to Perform
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+
+The B<%ifdef> instruction in a package configuration
+file specifies one or more actions to perform if the indicated string has been
+declared by a single-argument B<%define> statement, or is a variable
+for which a value has been defined by a two-argument B<%define>
+statement.
+
+Similarly, the %ifndef instruction specifies one or more actions
+to perform if the indicated string has not been declared or is a variable
+without a value, either because no B<%define> statement has defined it
+or an B<%undef> statement has undefined it.
+
+In both cases, the optional %else statement specifies one or
+more alternate actions to perform if the first statement evaluates to
+B<false>. (For an B<%ifdef> statement, the
+B<%else> statement is executed if the indicated string has never been
+declared or is a variable without a value, or if an B<%undef>
+statement has undefined either one; for an B<%ifndef> statement,
+it is executed if the string has been declared or is a variable with a
+value.)
+
+It is possible to nest any number of %ifdef and
+B<%ifndef> statements.
+
+The two types of statement share a common syntax:
+
+   %ifdef | ifndef   I<declaration> 
+                                  I<action>+
+   [%else [I<declaration>] 
+                  I<alternate_action>+]
+   %endif I<declaration>
+
+where
+
+=over 4
+
+=item ifdef
+
+Indicates that the statement evaluates as true if the string in
+the I<declaration> field is declared or is a variable with a defined
+value.
+
+=item ifndef
+
+Indicates that the statement evaluates as true if the string in
+the I<declaration> field is not declared or is a variable without a
+defined value.
+
+=item I<declaration
+>
+
+Specifies the string that must be declared or the variable name that must
+have a defined value for an B<%ifdef> statement to evaluate as
+B<true>, which results in the specified action being performed.
+For an B<%ifndef> statement, the string must not be declared or the
+variable must have no defined value for the statement to evaluate as
+B<true>. The first and third occurrences of
+I<declaration> (the latter following the string B<%endif>) are
+required. The second occurrence (following the string B<%else>)
+is optional, serving only to clarify to which B<%ifdef> or
+B<%ifndef> statement the B<%else> statement belongs.
+
+=item I<action
+>
+
+Specifies each action to perform if the %ifdef or
+B<%ifndef> statement evaluates as B<true>. Each action
+must appear on a separate line. Acceptable types of actions are other
+statements beginning with a percent sign and definition instructions.
+
+=item I<alternate_action
+>
+
+Specifies each action to perform if the %ifdef or
+B<%ifndef> statement evaluates to B<false>. Each action
+must appear on a separate line. Acceptable types of actions are other
+statements beginning with a percent sign and definition instructions.
+
+=back
+
+The %include Instruction for Including a Library File
+L<(1)>
+L<(1)>
+L<(1)>
+
+The B<%include> instruction in a package configuration
+file includes the contents of the indicated library file in a configuration
+file that results from the compilation of the prototype file in which the
+B<%include> instruction appears. It has the following
+syntax:
+
+   %include  I<pathname>
+
+where
+
+=over 4
+
+=item %include
+
+Indicates a library file include statement.
+
+=item I<pathname
+>
+
+Specifies the complete pathname of the library file to include. It
+can be in AFS or on the local disk, and can include one or more
+variables.
+
+=back
+
+=head1 CAUTIONS
+
+The configuration file must be completely correct. If there are any
+syntax errors or incorrect values, the B<package> command interpreter
+exits without executing any instruction.
+
+=head1 EXAMPLES
+
+The following example B<B> and C instructions define a
+disk B</dev/hd0a> with major and minor device numbers B<1> and
+B<0> and mode bits of B<-rw-r--r-->, and a tty
+B</dev/ttyp5> with major and minor device numbers B<6> and
+B<5> and mode bits of B<-rw-rw-rw>. In both cases, the
+owner is B<root> and the owning group B<wheel>.
+
+   B /dev/hd0a 1 0 root wheel 644
+   C /dev/ttyp5 6 5 root wheel 666
+
+The following example D instruction creates the local
+B</usr> directory with owner B<root> and group
+B<wheel> and mode bits of B<drwxr-xr-x>. The
+B<R> update code removes any files and subdirectories that reside in
+the B</usr> directory (if it already exists) but do not appear in the
+configuration file.
+
+   DR /usr root wheel 755
+
+The following example F instruction, appropriate for a machine
+running AIX 4.2 in the ABC Corporation cell, creates or updates the
+local disk file B</bin/grep>, using
+B</afs/abc.com/rs_aix42/bin/grep> as the source.
+
+   F /bin/grep /afs/abc.com/rs_aix42 root wheel 755
+
+The next example F instruction creates the
+B</usr/vice/etc/ThisCell> file and specifies an absolute pathname for
+the source file, as indicated by the B<A> update code. The
+B<Q> code makes the B<package> command return status code 4 as
+it exits, prompting a reboot of the machine if the standard
+B<package>-related changes have been made to the machine's AFS
+initialization file. No values are provided for the owner, group and
+mode bits, so the file inherits them from the source file.
+
+   FAQ /usr/vice/etc/ThisCell /afs/abc.com/common/etc/ThisCell
+
+The following example L instruction, appropriate for a machine
+running AIX 4.2 in the ABC Corporation cell, creates a symbolic link
+from B</etc/ftpd> on the local disk to the file
+B</afs/abc.com/rs_aix42/etc/ftpd>.
+
+   L /etc/ftpd /afs/abc.com/rs_aix42 root wheel 644
+
+The following example S instruction defines the socket
+B</dev/printer>.
+
+
+   S /dev/printer root wheel 777
+   
+
+The following example %define instruction defines the value for
+the variable C<${diskmode}>. This variable is used elsewhere in
+the template to fill the I<owner_name>, I<group_name>, and
+I<mode_bits> fields in a B<D>, B<F>, or B<L>
+instruction.
+
+   %define diskmode root wheel 644
+
+The following example %undef instruction declares the string
+B<afsd> not to be defined.
+
+   %undef afsd
+
+The following example %ifdef instruction specifies that if the
+string C<rs_aix42> is currently declared, then when the prototype file
+containing the instruction is compiled the three indicated library files are
+included. There is no alternate action defined. There must be
+B<%define> statements earlier in the prototype file to declare
+B<rs_aix42> and to assign a value to the C<${wsadmin}>
+variable.
+
+   %ifdef rs_aix42
+   %include ${wsadmin}/lib/rs_aix42.readonly
+   %include ${wsadmin}/lib/rs_aix42.generic
+   %include ${wsadmin}/lib/rs_aix42.generic.dev
+   %endif rs_aix42
+
+The following example %ifndef instruction, appropriate for the
+State University cell, defines C<stateu.edu> as the value of
+the C<${cell}> variable if it does not already have a value.
+
+   %ifndef cell
+   %define cell stateu.edu
+   %endif cell
+
+The following example %include instruction includes the library
+file B<base.generic> from the B<lib> subdirectory of
+the directory in which B<package>-related files reside. The
+C<${wsadmin}> variable resolves to an actual pathname (such as
+B</afs/abc.com/wsadmin>) during compilation.
+
+   %include ${wsadmin}/lib/base.generic
+
+=head1 SEE ALSO
+
+L<package(1)>
+
+=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.
similarity index 89%
rename from doc/man-pages/pod8/tapeconfig.pod
rename to doc/man-pages/pod5/tapeconfig.pod
index 49e657e..b7d0901 100644 (file)
@@ -8,7 +8,7 @@ on a Tape Coordinator machine
 The tapeconfig file defines basic configuration parameters for
 all of the tape devices or backup data files available for backup operations
 on a Tape Coordinator machine. The file is in ASCII format and must
-reside in the local B</usr/afs/backup> directory. The
+reside in the local F</usr/afs/backup> directory. The
 instruction for each tape device or backup data file appears on its own line
 and each has the following format:
 
@@ -19,7 +19,6 @@ where
 =over 4
 
 =item I<capacity
->
 
 Specifies the capacity of the tapes used with a tape device, or the amount
 of data to write into a backup data file. The Tape Coordinator refers
@@ -36,7 +35,6 @@ can write to the tape or file during a B<backup dump> or B<backup
 savedb> operation. If there is already a capacity value on the
 label, the Tape Coordinator uses it instead.
 
-
 =item *
 
 When the -size argument is omitted the first time the
@@ -44,7 +42,6 @@ B<backup labeltape> command is used on a given tape or file.
 The Tape Coordinator copies this value into the label's capacity
 field.
 
-
 =back
 
 The Tape Coordinator uses this capacity value or the one on the Backup
@@ -75,22 +72,18 @@ default is kilobytes.
 
 B<k>or K for kilobytes (KB)
 
-
 =item *
 
 B<m> or M for megabytes (MB)
 
-
 =item *
 
 B<g> or G for gigabytes (GB)
 
-
 =item *
 
 B<t> or T for terabytes (TB)
 
-
 =back
 
 If this field is omitted, the Tape Coordinator uses the maximum acceptable
@@ -98,7 +91,6 @@ value (2048 GB or 2 TB). Either leave both this field and the
 I<filemark_size> field empty, or provide a value in both of them.
 
 =item I<filemark_size
->
 
 Specifies the size of a tape device's filemarks (also called
 end-of-file or EOF marks), which is set by the device's
@@ -126,27 +118,25 @@ If this field is empty, the Tape Coordinator uses the value 0
 empty, or provide a value in both of them.
 
 =item I<device_name
->
 
 Specifies the complete pathname of the tape device or backup data
 file. The format of tape device names depends on the operating system,
 but on UNIX systems device names generally begin with the string
-B</dev/>. For a backup data file, this field defines the
+F</dev/>. For a backup data file, this field defines the
 complete pathname; for a discussion of suggested naming conventions see
 the description of the B<FILE> instruction in L<CFG_I<device_name>(1)>.
 
 =item I<port_offset
->
 
 Specifies the port offset number associated with this combination of Tape
 Coordinator and tape device or backup data file. 
 
-Acceptable values are the integers B<0> through 58510
+Acceptable values are the integers C<0> through 58510
 (the Backup System can track a maximum of 58,511 port offset numbers).
 Each value must be unique among the cell's Tape Coordinators, but any
 number of them can be associated with a single machine. Port offset
 numbers need not be assigned sequentially, and can appear in any order in the
-B<tapeconfig> file. Assign port offset B<0> to the Tape
+B<tapeconfig> file. Assign port offset C<0> to the Tape
 Coordinator for the tape device or backup data file used most often for backup
 operations; doing so will allow the operator to omit the
 B<-portoffset> argument from the largest possible number of
@@ -158,21 +148,21 @@ B<backup> commands.
 
 Creating the file requires UNIX B<w> (write) and
 B<x> (B<execute>) permissions on the
-B</usr/afs/backup> directory. Editing the file requires UNIX
+F</usr/afs/backup> directory. Editing the file requires UNIX
 B<w> (B<write>) permission on the file.
 
 =head1 EXAMPLES
 
 The following example tapeconfig file configures three tape
 devices and a backup data file. The first device has device name
-B</dev/rmt/0h>, and is assigned port offset B<0> because it
+F</dev/rmt/0h>, and is assigned port offset C<0> because it
 will be the most frequently used device for all backup operations in the
 cell. Its default tape capacity is 2 GB and filemark size is 1
-MB. The B</dev/rmt/3h> drive has half the capacity but a much
-smaller filemark size; its port offset is B<3>. The third
-device listed, B</dev/rmt/4h>, has the same capacity and filemark size
-as the first device and is assigned port offset B<2>. Port
-offset B<4> is assigned to the backup data file B</dev/FILE>,
+MB. The F</dev/rmt/3h> drive has half the capacity but a much
+smaller filemark size; its port offset is C<3>. The third
+device listed, F</dev/rmt/4h>, has the same capacity and filemark size
+as the first device and is assigned port offset C<2>. Port
+offset C<4> is assigned to the backup data file F</dev/FILE>,
 which is actually a symbolic link to the actual file located elsewhere on the
 local disk. The Tape Coordinator writes up to 1.5 GB into the
 file; as recommended, the filemark size is set to zero.
@@ -184,10 +174,10 @@ file; as recommended, the filemark size is set to zero.
 
 =head1 SEE ALSO
 
-L<backup_addhost(1)>,
-L<backup_dump(1)>,
-L<backup_labeltape(1)>,
-L<backup_savedb(1)>,
+L<backup_addhost(8)>,
+L<backup_dump(8)>,
+L<backup_labeltape(8)>,
+L<backup_savedb(8)>,
 L<butc(1)>,
 L<fms(1)>
 
diff --git a/doc/man-pages/pod5/uss.pod b/doc/man-pages/pod5/uss.pod
new file mode 100644 (file)
index 0000000..bec37e5
--- /dev/null
@@ -0,0 +1,952 @@
+=head1 NAME
+
+uss Template File - Provides instructions for the uss add command
+
+=head1 DESCRIPTION
+
+The uss template file defines the components of an AFS user
+account that the B<uss add> command (or B<add> instruction in
+a B<uss> bulk input file) creates. Use the B<-template>
+argument to the B<uss add> or B<uss bulk> command to identify
+the template file.
+
+Summary of Template File Instructions
+
+The template file can include the following instructions, each on its own
+line. A more detailed description of each instruction's syntax
+follows this list.
+
+=over 4
+
+=item A
+
+Imposes restrictions on user passwords and authentication attempts
+
+=item D
+
+Creates a directory
+
+=item E
+
+Creates a single-line file
+
+=item F
+
+Creates a file by copying a prototype
+
+=item G
+
+Defines a directory that is one of a set of parent directories into which
+the B<uss> command interpreter evenly distributes newly created home
+directories
+
+=item L
+
+Creates a hard link
+
+=item S
+
+Creates a symbolic link
+
+=item V
+
+Creates a volume, mounts it in the file space and sets the ACL on the
+mount point
+
+=item X
+
+Executes a command
+
+=back
+
+If the template file is empty (zero-length), the uss add command
+or B<add> instruction in a bulk input file only creates an entry in
+the Protection and Authentication Databases, naming them according to the name
+specified with the B<uss add> command's B<-user>
+argument, or in the bulk input file B<add> instruction's
+I<username> field.
+
+The A Instruction for Setting the Default Treatment of Volumes
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+
+The B<A> instruction in a uss template file enhances
+cell security by imposing the following restrictions on users' password
+choice and authentication attempts. For further information on these
+limits, see the I<IBM AFS Administration Guide> and the B<kas
+setfields> reference page.
+
+=over 4
+
+=item *
+
+Limiting the user's password lifetime. When the lifetime
+expires, the user can no longer authenticate using that password, and must
+change it.
+
+
+=item *
+
+Prohibiting the reuse of the user's 20 most recently used
+passwords.
+
+
+=item *
+
+Limiting the number of consecutive times that a user can provide an
+incorrect password during authentication, and for how long the Authentication
+Server refuses further authentication attempts after the limit is exceeded
+(referred to as an I<account lockout>). For regular user
+accounts in most cells, the recommended limit is nine and lockout time is 25
+minutes.
+
+
+=back
+
+The instruction has the following syntax:
+
+   A  I<username>  I<password_lifetime>  I<password_reuse>  I<failures>  I<locktime>
+
+where
+
+=over 4
+
+=item A
+
+Indicates a security-enhancing instruction. It must be a capital
+letter.
+
+=item I<username
+>
+
+Names the Authentication Database entry on which to impose security
+restrictions. Specify the value B<$USER> to read in the
+username from the B<uss add> command's B<-user> argument,
+or from the I<username> field of an B<add> instruction in a bulk
+input file.
+
+=item I<password_lifetime
+>
+
+Sets the number of days after the user's password is changed that it
+remains valid. When the password becomes invalid (expires), the user is
+unable to authenticate, but has 30 more days in which to issue the
+B<kpasswd> command to change the password (after that, only an
+administrator can change it).
+
+Specify an integer from the range B<1> through 254 to
+specify the number of days until expiration, the value B<0> to
+indicate that the password never expires, or the value B<$PWEXPIRES>
+to read in the number of days from the B<uss add> or B<uss
+bulk> command's B<-pwexpires> argument. If the
+B<A> instruction does not appear in the template file, the default is
+for the user's password never to expire.
+
+=item I<password_reuse
+>
+
+Determines whether or not the user can change his or her password (using
+the B<kpasswd> or B<kas setpassword> command) to one that is
+similar to any of the last twenty passwords. The acceptable values are
+B<reuse> to allow reuse and B<noreuse> to prohibit it.
+If the B<A> instruction does not appear in the template file, the
+default is to allow password reuse.
+
+=item I<failures
+>
+
+Sets the number of consecutive times the user can provide an incorrect
+password during authentication (using the B<klog> command or a login
+utility that grants AFS tokens). When the user exceeds the limit, the
+Authentication Server rejects further authentication attempts for the amount
+of time specified in the I<locktime> field.
+
+Specify an integer from the range B<1> through 254 to
+specify the number of failures permitted, or the value B<0> to
+indicate that there is no limit to the number of unsuccessful attempts.
+If the B<A> instruction does not appear in the template file, the
+default is to allow an unlimited number of failures.
+
+=item I<locktime
+>
+
+Specifies how long the Authentication Server refuses authentication
+attempts from a user who has exceeded the failure limit set in the
+I<failures> field.
+
+Specify a number of hours and minutes (I<hh:mm>) or minutes
+only (I<mm>), from the range B<01> (one minute) through
+B<36:00> (36 hours). The Authentication Server
+automatically reduces any larger value to B<36:00> and also
+rounds up any non-zero value to the next higher multiple of 8.5
+minutes. A value of B<0> (zero) sets an infinite lockout
+time; an administrator must always issue the B<kas unlock>
+command to unlock the account.
+
+=back
+
+The D Instruction for Creating a Directory
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+
+The B<D> instruction in a uss template file creates a
+directory. Its intended use is to create a subdirectory in the user
+home directory created by the B<V> instruction in the template
+file.
+
+Any number of D instructions can appear in the template
+file. If any variables in the instruction take their values from the
+B<V> instruction (notably, the $MTPT variable), the instruction must
+follow the B<V> instruction in the file.
+
+Although it is possible to use the D instruction to create a
+directory on the local disk of the machine where the B<uss> command is
+issued, it is not recommended. The preferred method for automated
+creation of directories on a local disk is the B<package>
+program. Two complications arise if the I<pathname> field refers
+to a local disk directory:
+
+=over 4
+
+=item *
+
+The uss command prints a warning message because it cannot
+associate an access control list (ACL) with a local disk directory. It
+creates the directory nonetheless, and some syntactically correct value must
+appear in the instruction's I<ACL> field.
+
+
+=item *
+
+To designate any user other than the issuer as the new directory's
+owner, the issuer must log onto the machine as the local superuser
+B<root>. For local disk directories, only the local superuser
+B<root> is allowed to issue the UNIX B<chown> command that the
+B<uss> command interpreter invokes to change the owner from the
+default value (the directory's creator, which in this case is the issuer
+of the B<uss> command). The issuer must then also use the
+B<-admin> argument to the B<uss add> or B<uss bulk>
+command to authenticate as a privileged AFS administrator, which is required
+for creating the Authentication Database and Protection Database entries that
+the B<uss> command interpreter always creates for a new
+account.
+
+
+=back
+
+The instruction has the following syntax:
+
+   D  I<pathname>  I<mode_bits>  I<owner>  I<ACL>
+
+where
+
+=over 4
+
+=item D
+
+Indicates a directory creation instruction. It must be a capital
+letter.
+
+=item I<pathname
+>
+
+Specifies the directory's full pathname. It can include
+variables.
+
+Specify the read/write path to the directory, to avoid the failure that
+results from attempting to create a new directory in a read-only
+volume. By convention, the read/write path is indicated by placing a
+period before the cell name at the pathname's second level (for example,
+B</afs/.abc.com>). For further discussion of the
+concept of read/write and read-only paths through the filespace, see the
+reference page for the B<fs mkmount> command.
+
+=item I<mode_bits
+>
+
+Sets the directory's UNIX mode bits. Acceptable values are the
+standard three- or four-digit numbers corresponding to combinations of
+permissions. Examples: B<755> corresponds to
+B<rwxr-xr-x>, and B<644> to B<rw-r--r-->. The
+first (owner) B<x> bit must be turned on to enable access to a
+directory.
+
+=item I<owner
+>
+
+Specifies the username or UNIX user ID (UID) of the user to be designated
+the directory's owner in the output from the UNIX B<ls -ld>
+command. If the directory resides in AFS, place the $UID variable in
+this field. If the directory resides on the local disk, this field must
+be the username or UID of the B<uss> command's issuer, unless the
+issuer is logged in as the local superuser B<root>.
+
+=item I<ACL
+>
+
+Sets the ACL on the new directory. It must appear even if the new
+directory resides on the local disk rather than in AFS, but is ignored in that
+case. Provide one or more paired values, each pair consisting of an AFS
+username or group name and the desired permissions, in that order.
+Separate the two parts of the pair, and each pair, with a space. The
+B<fs setacl> reference page describes the available
+permissions.
+
+For an AFS directory, grant all permissions to the directory's owner
+at least. Usually that is the new user, in which case the appropriate
+value is B<$USER all>.
+
+It is not possible to grant any permissions to the issuer of the
+B<uss> command. As the last step in account creation, the
+B<uss> command interpreter automatically deletes that person from any
+ACLs set during the creation process.
+
+=back
+
+The E Instruction for Creating a Single-line File
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+
+The B<E> instruction in a uss template file creates a
+file by echoing a specified character string into it. Its intended use
+is to create files in the user home directory created by the B<V>
+instruction in the template file, or in a subdirectory created by a
+B<D> instruction.
+
+Any number of E instructions can appear in the template
+file. If the file resides in a directory created by a B<D>
+instruction, the B<E> instruction must follow the B<D>
+instruction in the file.
+
+The B<E> and F instructions have complementary
+advantages. The character string echoed into the file by an
+B<E> instruction can be customized for each user, because it can
+include the standard variables for which the B<uss> command
+interpreter substitutes the values specified by arguments to the B<uss
+add> command or fields in a bulk input file B<add>
+instruction. In contrast, a file created using the B<F>
+instruction cannot include variables and so has the same content for all
+users. However, a file created by an B<E> instruction can be a
+single line only, because no carriage returns (newline characters) are allowed
+in the character string.
+
+Although it is possible to use the E instruction to create a
+file on the local disk of the machine where the B<uss> command is
+issued, it is not recommended. The preferred method for automated
+creation of files on a local disk is the B<package> program.
+The main complication is that designating any user other than the issuer as
+the new file's owner requires logging onto the machine as the local
+superuser B<root>. For local disk files, only the local
+superuser B<root> is allowed to issue the UNIX B<chown>
+command that the B<uss> command interpreter invokes to change the
+owner from the default value (the file's creator, which in this case is
+the issuer of the B<uss> command). The issuer must then also
+use the B<-admin> argument to the B<uss add> or B<uss
+bulk> command to authenticate as a privileged AFS administrator, which is
+required for creating the Authentication Database and Protection Database
+entries that the B<uss> command interpreter always creates for a new
+account.
+
+The instruction has the following syntax:
+
+   E  I<pathname>  I<mode_bits>  I<owner>  "I<contents>"
+
+where
+
+=over 4
+
+=item E
+
+Indicates a file creation instruction. It must be a capital
+letter.
+
+=item I<pathname
+>
+
+Specifies the file's full pathname. It can include
+variables.
+
+Specify the read/write path to the file, to avoid the failure that results
+from attempting to create a new file in a read-only volume. By
+convention, the read/write path is indicated by placing a period before the
+cell name at the pathname's second level (for example,
+B</afs/.abc.com>). For further discussion of the
+concept of read/write and read-only paths through the filespace, see the
+reference page for the B<fs mkmount> command.
+
+=item I<mode_bits
+>
+
+Sets the file's UNIX mode bits. Acceptable values are the
+standard three- or four-digit numbers corresponding to combinations of
+permissions. Examples: B<755> corresponds to
+B<rwxr-xr-x>, and B<644> to B<rw-r--r-->.
+
+=item I<owner
+>
+
+Specifies the username or UNIX user ID (UID) of the user to be designated
+the file's owner in the output from the UNIX B<ls -l>
+command. If the file resides in AFS, place the $UID variable in this
+field. If the file resides on the local disk, specify the username or
+UID of the B<uss> command's issuer; otherwise, the account
+creation operation halts immediately.
+
+=item I<contents
+>
+
+Specifies the one-line character string to write into the new file.
+Surround it with double quotes if it contains one or more spaces. It
+cannot contain the newline character, but can contain any of the standard
+variables, which the command interpreter resolves as it creates the
+file.
+
+=back
+
+L<(1)>The F Instruction for Creating a File
+from a Prototype
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+
+The B<F> instruction in a uss template file creates a
+file by copying the contents of an existing file (the I<prototype>)
+into it. Its intended use is to create files in the user home directory
+created by the B<V> instruction in the template file, or in a
+subdirectory created by a B<D> instruction.
+
+Any number of F instructions can appear in the template
+file. If the file resides in a directory created by a B<D>
+instruction, the B<F> instruction must follow the B<D>
+instruction in the file.
+
+The B<E> and F instructions have complementary
+advantages. A file created using the B<F> instruction has the
+same content for all users, whereas a file created by an B<E>
+instruction can be customized for each user if it includes variables.
+However, a file created by an B<E> instruction can be a single line
+only, whereas the prototype file copied by an B<F> instruction can be
+any length.
+
+Although it is possible to use the F instruction to create a
+file on the local disk of the machine where the B<uss> command is
+issued, it is not recommended. The preferred method for automated
+creation of files on a local disk is the B<package> program.
+The main complication is that designating any user other than the issuer as
+the new file's owner requires logging onto the machine as the local
+superuser B<root>. For local disk files, only the local
+superuser B<root> is allowed to issue the UNIX B<chown>
+command that the B<uss> command interpreter invokes to change the
+owner from the default value (the file's creator, which in this case is
+the issuer of the B<uss> command). The issuer must then also
+use the B<-admin> argument to the B<uss add> or B<uss
+bulk> command to authenticate as a privileged AFS administrator, which is
+required for creating the Authentication Database and Protection Database
+entries that the B<uss> command interpreter always creates for a new
+account.
+
+The instruction has the following syntax:
+
+   F  I<pathname>  I<mode_bits>  I<owner>  I<prototype_file>
+
+where
+
+=over 4
+
+=item F
+
+Indicates a file creation instruction. It must be a capital
+letter.
+
+=item I<pathname
+>
+
+Specifies the full pathname of the file to create, including the
+filename. It can include variables.
+
+Specify the read/write path to the file, to avoid the failure that results
+from attempting to create a new file in a read-only volume. By
+convention, the read/write path is indicated by placing a period before the
+cell name at the pathname's second level (for example,
+B</afs/.abc.com>). For further discussion of the
+concept of read/write and read-only paths through the filespace, see the
+reference page for the B<fs mkmount> command.
+
+=item I<mode_bits
+>
+
+Sets the file's UNIX mode bits. Acceptable values are the
+standard three- or four-digit numbers corresponding to combinations of
+permissions. Examples: B<755> corresponds to
+B<rwxr-xr-x>, and B<644> to B<rw-r--r-->.
+
+=item I<owner
+>
+
+Specifies the username or UNIX user ID (UID) of the user to be designated
+the file's owner in the output from the UNIX B<ls -l>
+command. If the file resides in AFS, place the $UID variable in this
+field. If the file resides on the local disk, specify the username or
+UID of the B<uss> command's issuer; otherwise, the account
+creation operation halts immediately.
+
+=item I<prototype_file
+>
+
+Names the AFS or local disk directory that houses the prototype file to
+copy. The prototype file's name must match the final element in
+the I<pathname> field.
+
+=back
+
+L<(1)>The G Instruction for Facilitating Even
+Distribution of Home Directories
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+
+The B<G> instruction in a uss template file creates a
+directory as one of the set of directories from which the B<uss>
+command interpreter selects when choosing a new user home directory's
+parent directory. More specifically, when the $AUTO variable appears in
+the I<mount_point> field of a B<V> instruction, the command
+interpreter substitutes for it the directory defined by a B<G>
+instruction that currently has the fewest entries.
+
+The instruction's intended use is to distribute user accounts evenly
+among several directories, rather than using directories that reflect
+divisions such as departmental affiliation. Distributing home
+directories in this fashion is useful mainly in very large cells where storing
+all user home directories under a single parent directory potentially slows
+directory lookup, or where a workplace-based division results in unevenly
+sized directories such that some users consistently experience slower
+directory lookup than others. See the chapter on B<uss> in the
+I<IBM AFS Administration Guide> for more information.
+
+Any number of G instructions can appear in the template
+file. If the B<V> instruction includes the $AUTO variable, it
+must appear after all of the B<G> instructions in the file.
+
+The instruction has the following syntax:
+
+   G  I<directory>
+
+where
+
+=over 4
+
+=item G
+
+Indicates an instruction that creates a directory to be considered as a
+value for the $AUTO variable. It must be a capital letter.
+
+=item I<directory
+>
+
+Specifies the directory's name as either a complete pathname or only
+the directory name. The choice determines the appropriate format for
+the I<mount_point> field of a B<V> instruction, as discussed in
+the following example.
+
+Specify the read/write path to the directory, to avoid the failure that
+results from attempting to create a new mount point in a read-only volume when
+the $AUTO variable is used in a B<V> instruction's
+I<mount_point> field. By convention, the read/write path is
+indicated by placing a period before the cell name at the pathname's
+second level (for example, B</afs/.abc.com>). For
+further discussion of the concept of read/write and read-only paths through
+the filespace, see the reference page for the B<fs mkmount>
+command.
+
+=back
+
+The L and S Instructions for Creating a Link
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+
+The B<L> instruction in a uss template file creates a
+hard link between two files, as achieved by the standard UNIX B<ln>
+command. The B<S> instruction creates a symbolic link between
+two files, as achieved by the standard UNIX B<ln -s> command. A
+full explanation of links is beyond the scope of this document, but the basic
+effect is to create a second name for an existing file, enabling access via
+either name. Creating a link does not create a second copy of the
+file.
+
+AFS allows hard links only if the linked files reside in the same
+directory, because it becomes difficult to determine which access control list
+(ACL) applies to the file if the two copies reside in directories with
+different ACLs. AFS allows symbolic links between two files that reside
+in different directories, or even different volumes. The File Server
+uses the ACL associated with the actual file rather than the link.
+
+Any number of B<L> and S instructions can appear in the
+template file. If the existing file or link is to reside in a directory
+created by a B<D> instruction, or if the existing file was created by
+an B<E> or B<F> instruction, the B<L> or B<S>
+instruction must follow the B<D>, B<E>, or B<F>
+instruction.
+
+The instructions share the following syntax:
+
+   L  I<existing_file>  I<link>
+   S  I<existing_file>  I<link>
+
+where
+
+=over 4
+
+=item L
+
+Indicates a hard link creation instruction. It must be a capital
+letter.
+
+=item S
+
+Indicates a symbolic link creation instruction. It must be a
+capital letter.
+
+=item I<existing_file
+>
+
+Specifies the complete pathname of the existing file.
+
+=item I<link
+>
+
+Specifies the complete pathname of the second name for the file.
+
+Specify the read/write path to the link, to avoid the failure that results
+from attempting to create a new link in a read-only volume. By
+convention, the read/write path is indicated by placing a period before the
+cell name at the pathname's second level (for example,
+B</afs/.abc.com>). For further discussion of the
+concept of read/write and read-only paths through the filespace, see the
+reference page for the B<fs mkmount> command.
+
+=back
+
+L<(1)>The V Instruction for Creating and
+Mounting a Volume
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+
+The B<V> instruction in a uss template file creates a
+volume on a specified file server machine and partition and creates an entry
+for it in the Volume Location Database (VLDB). It mounts the volume at
+a location in the AFS file space that becomes the user's home directory,
+then designates the directory's owner and sets its access control list
+(ACL).
+
+Only one V instruction can appear in the template file, and one
+must appear if the template file contains any instructions at all (is not
+empty). All other instructions are optional, except that the template
+must include B<G> instructions if the $AUTO variable appears in
+it. (The B<V> instruction is not necessarily the first line in
+the template. If the template includes the $AUTO variable, then the
+B<G> instructions which provide values for the variable must precede
+it in the file.)
+
+The instruction has the following syntax:
+
+   V  I<volume_name>  I<server>  I<partition>  I<quota>  I<mount_point> I<owner>  I<ACL>
+
+where
+
+=over 4
+
+=item V
+
+Indicates a volume creation instruction. It must be a capital
+letter.
+
+=item I<volume_name
+>
+
+Specifies the volume's name. To follow the convention for AFS
+user volume names, specify the value B<user.$USER>.
+Provide a value for the $USER variable via the B<uss add>
+command's B<-user> argument or the I<username> field in the
+bulk input file B<add> instruction.
+
+=item I<server
+>
+
+Names the file server machine on which to create the new user's
+volume. It is best to provide the fully-qualified hostname (for
+example, B<fs1.abc.com>), but an abbreviated form is
+acceptable provided that the cell's naming service is available to
+resolve it at the time the volume is created. To read in the value from
+the B<uss add> command's B<-server> argument, specify the
+value B<$SERVER>.
+
+=item I<partition
+>
+
+Specifies the partition on which to create the user's volume; it
+must be on the file server machine named in the I<server> field.
+Identify the partition by its complete name (for example, B</vicepa>)
+or use or use one of the following abbreviations. 
+
+   B</vicepa>     =     B<vicepa>      =      B<a>      =      0
+   B</vicepb>     =     B<vicepb>      =      B<b>      =      1
+
+After /vicepz (for which the index is 25) comes 
+
+   B</vicepaa>    =     B<vicepaa>     =      B<aa>     =      26
+   B</vicepab>    =     B<vicepab>     =      B<ab>     =      27
+
+and so on through 
+
+   B</vicepiv>    =     B<vicepiv>     =      B<iv>     =      255
+
+To read in the value from the uss add command's
+B<-partition> argument, specify the value B<$PART>.
+
+=item I<quota
+>
+
+Sets the maximum number of kilobyte blocks the volume can occupy on the
+file server machine's disk. Specify an integer constant if all
+volumes have the same quota (B<1024> equals a megabyte), or use one of
+the number variables ($1 through $9) to assign different values to different
+volumes.
+
+=item I<mount_point
+>
+
+Creates a mount point for the volume, which serves as the volume's
+root directory. Include the $USER variable as part of the pathname to
+follow the convention that user home directory names include the
+username.
+
+Specify the read/write path to the mount point, to avoid the failure that
+results from attempting to create a new mount point in a read-only
+volume. By convention, the read/write path is indicated by placing a
+period before the cell name at the pathname's second level (for example,
+B</afs/.abc.com>). If the $AUTO variable appears
+in this field, the directories named by each B<G> instruction possibly
+already indicate the read/write path. For further discussion of the
+concept of read/write and read-only paths through the filespace, see the
+reference page for the B<fs mkmount> command..
+
+=item I<owner
+>
+
+Specifies the username or UNIX user ID (UID) of the user to be designated
+the mount point's owner in the output from the UNIX B<ls -ld>
+command. To follow the convention for home directory ownership, place
+the value B<$UID> in this field.
+
+=item I<ACL
+>
+
+Sets the ACL on the new directory. Provide one or more paired
+values, each pair consisting of an AFS username or group name and the desired
+permissions, in that order. Separate the two parts of the pair, and
+each pair, with a space. The B<fs setacl> reference page
+describes the available permissions.
+
+Grant all permissions to the new user at least. The appropriate
+value is B<$USER all>.
+
+AFS automatically grants the system:administrators group
+all permissions as well. It is not possible to grant any permissions to
+the issuer of the B<uss> command. As the last step in account
+creation, the B<uss> command interpreter automatically deletes that
+user from any ACLs set during the creation process.
+
+=back
+
+L<(1)>The X Instruction for Running a
+Command
+L<(1)>
+L<(1)>
+L<(1)>
+
+The B<X> instruction in a uss template file runs the
+indicated command, which can be a standard UNIX or AFS command. It can
+include any variables from the template file, which the B<uss> command
+interpreter resolves before passing the command on to the appropriate other
+command interpreter. It must be a single line only, however (cannot
+contain carriage returns or newline characters).
+
+Any number of X instructions can appear in the template
+file. If an instruction manipulates an element created by another
+instruction, it must follow that instruction in the file.
+
+The instruction has the following syntax:
+
+   B<X ">I<command>"
+
+where
+
+=over 4
+
+=item X
+
+Indicates a command execution instruction. It must be a capital
+letter.
+
+=item I<command
+>
+
+Specifies the command to run. Surround it with double quotes as
+shown if it contains one or more spaces. It can contain any variables
+from the template file, but not newline characters.
+
+=back
+
+=head1 EXAMPLES
+
+The following example A instruction sets a password lifetime of
+254 days, prohibits password reuse, limits the number of consecutive failed
+authentication attempts to nine and sets the corresponding locktime to
+25:30 minutes (which is a multiple of 8.5 minutes). The
+username is read in from the B<-user> argument to the B<uss
+add> command or from the I<username> field in each B<add>
+instruction in a bulk input file.
+
+   A $USER 254 noreuse 9 25:30
+
+The following example D instruction creates a directory called
+I<public> in a new user's home directory, designates the user as
+the directory's owner, and grants him or her all ACL permissions.
+
+   D $MTPT/public 0755 $UID $USER all 
+
+The following example E instruction creates a file in the
+current working directory called
+I<username>.B<etcp>. The contents are an entry
+suitable for incorporating into the cell's global
+B</etc/password> file.
+
+   E  $USER.etcp  0644 root "$USER:X:$UID:10:$NAME:$MTPT:/bin/csh"
+
+The following example F instruction, appropriate for the ABC
+Corporation cell, copies a prototype B<.login> file into the
+user's home directory.
+
+   F $MTPT/.login 0644 $UID /afs/abc.com/common/uss/skel/.login 
+
+In the following example, the State University cell's administrators
+have decided to distribute user home directories evenly into three
+directories. They define three B<G> instructions:
+
+   G usr1
+   G usr2
+   G usr3
+
+and then put the following value in the I<mount_point> field of the
+B<V> instruction:
+
+   /afs/stateu.edu/$AUTO/$USER
+
+Alternatively, if they include the entire directory pathname in the
+B<G> instruction:
+
+   G /afs/stateu.edu/usr1
+   G /afs/stateu.edu/usr2
+   G /afs/stateu.edu/usr3
+
+then the I<mount_point> field of the V instruction
+specifies only the following:
+
+   $AUTO/$USER
+
+The following example L instruction creates a hard link between
+the files B<mail> and B<mbox> in the user's home
+directory.
+
+   L $MTPT/mbox $MTPT/mail
+
+The following example S instruction, appropriate for the ABC
+Corporation cell, links the file B<Mail/outgoing> in the user's
+home directory to the file
+B</afs/abc.com/common/mail/outgoing>.
+
+   S /afs/abc.com/common/mail/outgoing $MTPT/Mail/outgoing
+
+The following example V instruction creates a volume called
+B<user.>I<username> on the B</vicepa> partition
+of the specified file server machine, assigning it a quota of 3000 kilobyte
+blocks. The mount point is under B</afs/abc.com/usr> and
+matches the username (the value of the $USER variable). The user owns
+the home directory and has all access rights to it. The instruction
+appears on two lines only for legibility; it must appear on a single line
+in the template file.
+
+   V user.$USER $SERVER.abc.com /vicepa 3000   \
+           /afs/abc.com/usr/$USER $UID $USER all 
+
+The following example X instruction mounts the backup version of
+the user's volume at the B<OldFiles> subdirectory.
+
+   X "fs mkm /afs/abc.com/usr/$USER/OldFiles   user.$USER.backup"
+
+=head1 SEE ALSO
+
+L<uss Bulk Input File(1)>
+
+L<fs_mkmount(1)>,
+L<uss_add(1)>
+
+=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.
diff --git a/doc/man-pages/pod5/uss_bulk.pod b/doc/man-pages/pod5/uss_bulk.pod
new file mode 100644 (file)
index 0000000..213f502
--- /dev/null
@@ -0,0 +1,407 @@
+=head1 NAME
+
+uss Bulk Input File - Provides instructions for the uss bulk command
+
+=head1 DESCRIPTION
+
+The uss bulk input file lists instructions for the
+B<uss> command interpreter to execute when running the B<uss
+bulk> command. If the file includes B<add> instructions
+that reference a B<uss> template file, then the template file must
+also exist.
+
+Summary of Bulk Input File Instructions
+
+The bulk input file can include the following instructions, each on its own
+line. A more detailed description of each instruction's syntax
+follows this list.
+
+=over 4
+
+=item add
+
+Creates a user account. Equivalent to the uss add
+command.
+
+=item delete
+
+Deletes a user account. Equivalent to the uss delete
+command.
+
+=item delvolume
+
+Removes the volume and VLDB entry for each account referenced by a
+B<delete> instruction that follows this instruction in the bulk input
+file.
+
+=item exec
+
+Executes a command.
+
+=item savevolume
+
+Preserves the volume and VLDB entry for each account referenced by a
+B<delete> instruction that follows this instruction in the bulk input
+file.
+
+=back
+
+The add Instruction for Creating an Account
+L<(1)>
+L<(1)>
+
+The add instruction creates a user account. Each instance
+in the bulk input file is equivalent in effect to a B<uss add> command
+issued on the command line. The order of the instruction's fields
+matches the order of arguments to the B<uss add> command, although
+some arguments do not have a corresponding field. Like the B<uss
+add> command's arguments, many of the fields correspond to (provide
+a value for) a variable in the B<uss> template file, as indicated in
+the following description of each field.
+
+The instruction's syntax is as follows. It appears on multiple
+lines here only for the sake of legibility--each B<add>
+instruction must appear on a single line in the bulk input file.
+
+   add I<username>[:I<full_name>][:I<initial_password>][:I<password_expires>]
+       [:I<file_server>][:I<partition>][:I<mount_point>][:I<uid>][:I<var1>][:I<var2>]
+       [:I<var3>][:I<var4>][:I<var5>][:I<var6>][:I<var7>][:I<var8>][:I<var9>][:]
+
+To omit a value for a field (presumably because it is optional or the
+template specifies a constant value for it), type nothing between the two
+colons that surround it. After the last argument provided, end the line
+with either a colon and carriage return, or a carriage return alone.
+
+The meaning of, and acceptable values for, each field are as
+follows.
+
+=over 4
+
+=item I<username
+>
+
+Names the user's Authentication Database and Protection Database
+entries. It can include up to eight alphanumeric characters, but not
+the B<:> (colon), B<.> (period), or B<@>
+(at-sign) characters. Because it becomes the username (the name under
+which a user logs in), it is best not to include shell metacharacters and to
+obey the restrictions that many operating systems impose on usernames
+(usually, to contain no more than eight lowercase letters).
+
+Corresponding argument to the uss add command:
+B<-user>. Corresponding variable in the template file:
+$USER.
+
+=item I<full_name
+>
+
+Specifies the user's full name. Do not surround it with double
+quotes (""), even if it contains spaces. If not provided, it defaults
+to the username in the I<username> field. 
+
+Corresponding argument to the uss add command:
+B<-realname>. Corresponding variable in the template
+file: $NAME. Many operating systems include a field for the full
+name in a user's entry in the local password file (B</etc/passwd>
+or equivalent), and this variable can be used to pass a value to be used in
+that field.
+
+=item I<initial_password
+>
+
+Specifies the user's initial password. Although the AFS
+commands that handle passwords accept strings of virtually unlimited length,
+it is best to use a password of eight characters or less, which is the maximum
+length that many applications and utilities accept. If not provided,
+this argument defaults to the string B<changeme>.
+
+Corresponding argument to the uss add command:
+B<-pass>. Corresponding variable in the template file:
+none.
+
+=item I<password_expires
+>
+
+Sets the number of days after a user's password is changed that it
+remains valid. Provide an integer from the range B<1> through
+B<254> to specify the number of days until expiration, or the value
+B<0> to indicate that the password never expires (the default).
+
+When the password becomes invalid (expires), the user is unable to
+authenticate, but has 30 more days in which to issue the B<kpasswd>
+command to change the password (after that, only an administrator can change
+it).
+
+Corresponding argument to the uss add command:
+B<-pwexpires>. Corresponding variable in the template
+file: $PWEXPIRES.
+
+=item I<file_server
+>
+
+Names the file server machine on which to create the new user's
+volume. It is best to provide a fully-qualified hostname (for example,
+B<fs1.abc.com>), but an abbreviated form is acceptable
+provided that the cell's naming service is available to resolve it at the
+time the volume is created.
+
+Corresponding argument to the uss add command:
+B<-server>. Corresponding variable in the template file:
+$SERVER.
+
+=item I<partition
+>
+
+Specifies the partition on which to create the user's volume; it
+must reside on the file server machine named in the I<file_server>
+field. Identify the partition by its complete name (for example,
+B</vicepa>, or use one of the following abbreviations: 
+
+   B</vicepa>     =     B<vicepa>      =      B<a>      =      0
+   B</vicepb>     =     B<vicepb>      =      B<b>      =      1
+
+After /vicepz (for which the index is 25) comes 
+
+   B</vicepaa>    =     B<vicepaa>     =      B<aa>     =      26
+   B</vicepab>    =     B<vicepab>     =      B<ab>     =      27
+
+and so on through 
+
+   B</vicepiv>    =     B<vicepiv>     =      B<iv>     =      255
+
+Corresponding argument to the uss add command:
+B<-partition>. Corresponding variable in template:
+$PART.
+
+=item I<mount_point
+>
+
+Specifies the complete pathname for the user's home directory.
+
+Corresponding argument to the uss add command:
+B<-mount>.
+
+Corresponding variable in template: $MTPT, but in the template
+file's B<V> instruction only. Occurrences of the $MTPT
+variable in template instructions that follow the B<V> instruction
+take their value from the B<V> instruction's I<mount_point>
+field. Thus the value of this command line argument becomes the value
+for the $MTPT variable in instructions that follow the B<V>
+instruction only if the string $MTPT appears alone in the B<V>
+instruction's I<mount_point> field.
+
+=item I<uid
+>
+
+Specifies a positive integer other than 0 (zero) to assign as
+the user's AFS UID. If this argument is omitted, the Protection
+Server assigns an AFS UID that is one greater than the current value of the
+C<max> C<user> C<id> counter (use the B<pts
+listmax> command to display the counter). If including this
+argument, first use the B<pts examine> command to verify that no
+existing account already has the desired AFS UID; if one does, the
+account-creation process terminates with an error.
+
+Corresponding argument to the uss add command:
+B<-uid>. Corresponding variable in template: $UID.
+
+=item I<var1 through I<var9>
+>
+
+Specifies values for each of the number variables $1 through $9 that can
+appear in the template file. The number variables allow the
+administrator to provide values for variables other than the set defined by
+the B<uss> command suite.
+
+Corresponding argument to the uss add command:
+B<-var>. Corresponding variables in template: $1 through
+$9.
+
+If providing a value in any of the fields, then in every field that
+precedes it either provide an actual value or indicate an empty field by
+putting nothing between two colons. It is acceptable, but not
+necessary, to indicate empty fields by putting colons after the last field
+that contains an actual value.
+
+=back
+
+The delete Instruction for Deleting an Account
+L<(1)>
+L<(1)>
+
+The delete instruction deletes a user account from the
+system. Each instance in the bulk input file is equivalent in effect to
+a B<uss delete> command issued on the command line. The order
+of the instruction's fields matches the order of arguments to the
+B<uss delete> command:
+
+   delete I<username>:I<mount_point_path>[:{ savevolume | delvolume }][:]
+
+where
+
+=over 4
+
+=item I<username
+>
+
+Names the entry to delete from the Protection and Authentication
+Databases.
+
+=item I<mount_point_path
+>
+
+Specifies the complete pathname to the user's home directory, which
+is deleted from the filespace. By default, the volume mounted there is
+also deleted from the file server machine where it resides, as is its record
+from the Volume Location Database (VLDB). To prevent deletion, include
+the B<savevolume> string in the instruction's third field, or
+precede this B<delete> instruction with a B<savevolume>
+instruction. Partial pathnames are interpreted relative to the current
+working directory.
+
+=item savevolume
+
+Retains the volume on its file server machine, and the corresponding entry
+in the VLDB. Provide this value or B<delvolume> in the third
+field, or omit both values to treat the volume according to the prevailing
+default, which is set by a preceding B<savevolume> or
+B<delvolume> instruction in the bulk input file.
+
+=item delvolume
+
+Removes the volume from its file server machine, and the corresponding
+entry from the VLDB. Provide this value or B<savevolume> in the
+third field, or omit both values to treat the volume according to the
+prevailing default, which is set by a preceding B<savevolume> or
+B<delvolume> instruction in the bulk input file.
+
+=back
+
+After the last argument provided, end the line with either a colon and
+carriage return or a carriage return alone.
+
+The exec Instruction for Executing a Command
+
+The exec instruction executes the specified command, which can
+be a UNIX shell script or command, a program, or an AFS command. The
+B<uss> command interpreter must have the necessary privileges in AFS
+and the local file system; it assumes the AFS and local identities of the
+issuer of the B<uss bulk> command.
+
+The instruction's syntax is as follows:
+
+   exec I<command>
+
+The delvolume and savevolume Instructions for Setting the Default
+Treatment of Volumes
+L<(1)>
+L<(1)>
+L<(1)>
+L<(1)>
+
+The B<savevolume> and delvolume instructions determine
+the default treatment of volumes referenced by the B<delete>
+instructions that follow them in the bulk input file. Their syntax is
+as follows:
+
+   savevolume
+   delvolume
+
+The savevolume instruction prevents the removal of the volume
+and VLDB entry for all B<delete> instruction that follow it in the
+bulk input file, and the B<delvolume> instruction removes the volume
+and VLDB entry for all subsequent B<delete> instructions.
+Either setting persists until its opposite appears in the file, or until the
+end of the bulk file.
+
+If neither line appears in the bulk input file, the default is to remove
+the volume and the VLDB entry; B<delete> instructions that appear
+before the first B<savevolume> instruction are also subject to this
+default. If a B<delete> instruction's third field
+specifies either B<savevolume> or B<delvolume>, that setting
+overrides the default.
+
+=head1 EXAMPLES
+
+The following example add instruction creates an
+authentication-only account. The user's initial password is
+B<changeme> (the default).
+
+   add anderson
+
+The following example add instructions refer to the indicated
+B<V> instruction in a template file (which must appear on a single
+line in the template file). 
+
+   add smith:John Smith:::fs1:a:::::marketing 
+   add jones:Pat Jones:::fs3:c:::::finance
+   V user.$USER $SERVER.abc.com /vicep$PART 2000 \
+       /afs/abc.com/usr/$3/$USER $UID $USER all
+
+The first add instruction creates an account called
+B<smith> in the Protection and Authentication Databases, with an
+initial password B<changeme> and a value for $UID provided by the
+Protection Server. The volume B<user.smith> resides on
+partition B</vicepa> of file server machine
+B<fs1.abc.com> and is mounted at
+B</afs/abc.com/usr/marketing/smith>. He owns his home
+directory and has all access permissions on its root directory's access
+control list (ACL). The account for B<jones> is similar, except
+that the volume resides on partition B</vicepc> of file server machine
+B<fs3.abc.com> and is mounted at
+B</afs/abc.com/usr/finance/jones>.
+
+Notice that the fields corresponding to the volume mount point, UID, $1
+variable, and $2 variable are empty (between C<a> and
+C<marketing> on the first example line), because their corresponding
+variables do not appear in the template file. The initial password
+field is also empty.
+
+The following add instructions are equivalent in effect to the
+preceding example, but explicitly indicate empty fields for all of the number
+variables that don't have a value:
+
+   add smith:John Smith:::fs1:a:::::marketing::::::
+   add jones:Pat Jones:::fs3:c:::::finance::::::
+
+The following example shows a complete bulk file containing a set of
+B<delete> instructions combined with a B<savevolume>
+instruction. Because the B<delete> instruction for users
+B<smith>, B<pat>, and B<rogers> appear before the
+B<savevolume> instruction and the third field is blank in each, the
+corresponding home volumes are removed. The volume for user
+B<terry> is retained because the default established by the
+B<savevolume> instruction applies to it, but user
+B<johnson>'s volume is removed because the third field of her
+B<delete> instruction overrides the current default.
+
+   delete smith:/afs/abc.com/usr/smith
+   delete pat:/afs/abc.com/usr/pat
+   delete rogers:/afs/abc.com/usr/rogers
+   savevolume
+   delete terry:/afs/abc.com/usr/terry
+   delete johnson:/afs/abc.com/usr/johnson:delvolume
+
+The following example exec instruction appears between sets of
+B<add> and B<delete> instructions in a bulk input file.
+A message appears in the command shell where the B<uss bulk> command
+is issued, to indicate when the additions are finished and the deletions
+beginning.
+
+   exec echo "Additions completed; beginning deletions..."
+
+=head1 SEE ALSO
+
+L<uss Template File(1)>
+
+L<uss_add(1)>,
+L<uss_bulk(1)>,
+L<uss_delete(1)>
+
+=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.
index c852b6c..4491921 100644 (file)
@@ -1,36 +1,33 @@
 =head1 NAME
 
-afsd - Initializes the Cache Manager and starts related daemons.
+afsd - Initializes the Cache Manager and starts related daemons
 
 =head1 SYNOPSIS
 
-B<afsd> [-blocks <I<1024 byte blocks in cache>>]  
-[B<-files> <I<files in cache>>]
-     [-rootvol <I<name of AFS root volume>>]
-     [-stat <I<number of stat entries>>]
-     [B<-memcache>]  [-cachedir <I<cache directory>>]  
-     [-mountdir <I<mount location>>]
-     [-daemons <I<number of daemons to use>>]  
-     [B<-nosettime>]  [B<-verbose>]  [B<-rmtsys>]  [-debug]  
-     [-chunksize <I<log(2) of chunk size>>]
-     [-dcache <I<number of dcache entries>>]
-     [-volumes <I<number of volume entries>>]  
-     [-biods <I<number of bkg I/O daemons (aix vm)>>]
-     [-prealloc <I<number of 'small' preallocated blocks>>]
-     [-confdir <I<configuration directory>>]
-     [-logfile <I<Place to keep the CM log>>]  
-     [B<-waitclose>]  [B<-shutdown>]  [-enable_peer_stats]  
-     [B<-enable_process_stats>]  [-help]
-
-This command does not use the syntax conventions of the AFS command
-suites. Provide the command name and all option names in full.
+B<afsd> [B<-blocks> <I<1024 byte blocks in cache>>]  
+     [B<-files> <I<files in cache>>]
+     [B<-rootvol> <I<name of AFS root volume>>]
+     [B<-stat> <I<number of stat entries>>]
+     [B<-memcache>] [B<-cachedir> <I<cache directory>>]  
+     [B<-mountdir> <I<mount location>>]
+     [B<-daemons> <I<number of daemons to use>>]  
+     [B<-nosettime>] [B<-verbose>] [B<-rmtsys>] [B<-debug>]
+     [B<-chunksize> <I<log(2) of chunk size>>]
+     [B<-dcache> <I<number of dcache entries>>]
+     [B<-volumes> <I<number of volume entries>>]  
+     [B<-biods> <I<number of bkg I/O daemons (aix vm)>>]
+     [B<-prealloc> <I<number of 'small' preallocated blocks>>]
+     [B<-confdir> <I<configuration directory>>]
+     [B<-logfile> <I<Place to keep the CM log>>]  
+     [B<-waitclose>] [B<-shutdown>] [B<-enable_peer_stats>]
+     [B<-enable_process_stats>] [B<-help>]
 
 =head1 DESCRIPTION
 
-The afsd command initializes the Cache Manager on an AFS client
-machine by transferring AFS-related configuration information into kernel
-memory and starting several daemons. More specifically, the
-B<afsd> command performs the following actions:
+The B<afsd> command initializes the Cache Manager on an AFS client machine
+by transferring AFS-related configuration information into kernel memory
+and starting several daemons. More specifically, the B<afsd> command
+performs the following actions:
 
 =over 4
 
@@ -39,166 +36,144 @@ B<afsd> command performs the following actions:
 Sets a field in kernel memory that defines the machine's cell
 membership. Some Cache Manager-internal operations and system calls
 consult this field to learn which cell to execute in. (The AFS command
-interpreters refer to the B</usr/vice/etc/ThisCell> file
-instead.) This information is transferred into the kernel from the
-B</usr/vice/etc/ThisCell> file and cannot be changed until the
-B<afsd> program runs again.
-
+interpreters refer to the F</usr/vice/etc/ThisCell> file instead.) This
+information is transferred into the kernel from the
+F</usr/vice/etc/ThisCell> file and cannot be changed until the B<afsd>
+program runs again.
 
 =item *
 
 Places in kernel memory the names and Internet addresses of the database
 server machines in the local cell and (optionally) foreign cells. The
 appearance of a cell's database server machines in this list enables the
-Cache Manager to contact them and to access files in the cell. Omission
-of a cell from this list, or incorrect information about its database server
+Cache Manager to contact them and to access files in the cell. Omission of
+a cell from this list, or incorrect information about its database server
 machines, prevents the Cache Manager from accessing files in it.
 
-
 The list of database server machines is transferred into the kernel from
-the B</usr/vice/etc/CellServDB> file. After initialization, use
-the B<fs newcell> command to change the kernel-resident list without
-having to reboot.
+the F</usr/vice/etc/CellServDB> file. After initialization, use the B<fs
+newcell> command to change the kernel-resident list without having to
+reboot.
 
 =item *
 
-Mounts the root of the AFS filespace on a directory on the machine's
-local disk, according to either the first field in the
-B</usr/vice/etc/cacheinfo> file (the default) or the B<afsd>
-command's B<-mountdir> argument. The conventional value is
-B</afs>.
-
+Mounts the root of the AFS filespace on a directory on the machine's local
+disk, according to either the first field in the
+F</usr/vice/etc/cacheinfo> file (the default) or the B<afsd> command's
+B<-mountdir> argument. The conventional value is F</afs>.
 
 =item *
 
-Determines which volume to mount at the root of the AFS file tree.
-The default is the volume B<root.afs>; use the
-B<-rootvol> argument to override it. Although the base
-(read/write) form of the volume name is the appropriate value, the Cache
-Manager has a bias for accessing the read-only version of the volume (by
-convention, B<root.afs.readonly>) if it is
-available.
-
+Determines which volume to mount at the root of the AFS file tree.  The
+default is the volume C<root.afs>; use the B<-rootvol> argument to
+override it. Although the base (read/write) form of the volume name is the
+appropriate value, the Cache Manager has a bias for accessing the
+read-only version of the volume (by convention, C<root.afs.readonly>) if
+it is available.
 
 =item *
 
 Configures the cache on disk (the default) or in machine memory if the
-B<-memcache> argument is provided. In the latter case, the
-B<afsd> program allocates space in machine memory for caching, and the
-Cache Manager uses no disk space for caching even if the machine has a
-disk.
-
+B<-memcache> argument is provided. In the latter case, the B<afsd> program
+allocates space in machine memory for caching, and the Cache Manager uses
+no disk space for caching even if the machine has a disk.
 
 =item *
 
 Defines the name of the local disk directory devoted to caching, when the
-B<-memcache> argument is not used. If necessary, the
-B<afsd> program creates the directory (its parent directory must
-already exist). It does not remove the directory that formerly served
-this function, if one exists.
-
+B<-memcache> argument is not used. If necessary, the B<afsd> program
+creates the directory (its parent directory must already exist). It does
+not remove the directory that formerly served this function, if one
+exists.
 
-The second field in the /usr/vice/etc/cacheinfo file is the
-source for this name, and the standard value is the B</usr/vice/cache>
-directory. Use the B<-cachedir> argument to override the value
-in the B<cacheinfo> file.
+The second field in the F</usr/vice/etc/cacheinfo> file is the source for
+this name, and the standard value is the F</usr/vice/cache> directory. Use
+the B<-cachedir> argument to override the value in the B<cacheinfo> file.
 
 =item *
 
-Sets the size of the cache. The default source for the value is the
-third field in the B</usr/vice/etc/cacheinfo> file, which specifies a
-number of kilobytes.
+Sets the size of the cache. The default source for the value is the third
+field in the F</usr/vice/etc/cacheinfo> file, which specifies a number of
+kilobytes.
 
-
-For a memory cache, the following arguments to the afsd command
-override the value in the B<cacheinfo> file:
+For a memory cache, the following arguments to the afsd command override
+the value in the B<cacheinfo> file:
 
 =over 4
 
 =item *
 
-The -blocks argument, to specify a different number of kilobyte
-blocks.
-
+The B<-blocks> argument, to specify a different number of kilobyte blocks.
 
 =item *
 
-The B<-dcache> and -chunksize arguments together, to
-set both the number of dcache entries and the chunk size (see below for
-definition of these parameters). In this case, the B<afsd>
-program derives cache size by multiplying the two values. Using this
-combination is not recommended, as it requires the issuer to perform the
-calculation beforehand to determine the resulting cache size.
-
+The B<-dcache> and B<-chunksize> arguments together, to set both the
+number of dcache entries and the chunk size (see below for definition of
+these parameters). In this case, the B<afsd> program derives cache size by
+multiplying the two values. Using this combination is not recommended, as
+it requires the issuer to perform the calculation beforehand to determine
+the resulting cache size.
 
 =item *
 
-The -dcache argument by itself. In this case, the
-B<afsd> program derives cache size by multiplying the value specified
-by the B<-dcache> argument by the default memory cache chunk size of
-eight kilobytes. Using this argument is not recommended, as it requires
-the issuer to perform the calculation beforehand to determine the resulting
-cache size.
-
+The B<-dcache> argument by itself. In this case, the B<afsd> program
+derives cache size by multiplying the value specified by the B<-dcache>
+argument by the default memory cache chunk size of eight kilobytes. Using
+this argument is not recommended, as it requires the issuer to perform the
+calculation beforehand to determine the resulting cache size.
 
 =back
 
 For satisfactory memory cache performance, the specified value must leave
-enough memory free to accommodate all other processes and commands that can
-run on the machine. If the value exceeds the amount of memory
+enough memory free to accommodate all other processes and commands that
+can run on the machine. If the value exceeds the amount of memory
 available, the B<afsd> program exits without initializing the Cache
-Manager and produces the following message on the standard output
-stream:
+Manager and produces the following message on the standard output stream:
 
-   afsd: memCache allocation failure at I<number> KB
+   afsd: memCache allocation failure at <number> KB
 
-where I<number> is how many kilobytes were allocated just before the
+where <number> is how many kilobytes were allocated just before the
 failure.
 
-For a disk cache, use the -blocks argument to the
-B<afsd> command to override the value in the B<cacheinfo>
-file. The value specified in either way sets an absolute upper limit on
-cache size; values provided for other arguments (such as
-B<-dcache> and B<-chunksize>) never result in a larger
-cache. The B<afsd> program rejects any setting larger than 95%
-of the partition size, and exits after generating an error message on the
+For a disk cache, use the B<-blocks> argument to the B<afsd> command to
+override the value in the B<cacheinfo> file. The value specified in either
+way sets an absolute upper limit on cache size; values provided for other
+arguments (such as B<-dcache> and B<-chunksize>) never result in a larger
+cache. The B<afsd> program rejects any setting larger than 95% of the
+partition size, and exits after generating an error message on the
 standard output stream, because the cache implementation itself requires a
-small amount of disk space and overfilling the partition can cause the client
-machine to panic.
+small amount of disk space and overfilling the partition can cause the
+client machine to panic.
 
 To change the size of a disk cache after initialization without rebooting,
-use the B<fs setcachesize> command; the setting persists until
-the B<afsd> command runs again or the B<fs setcachesize>
-command is reissued. The B<fs setcachesize> command does not
-work for memory caches.
+use the B<fs setcachesize> command; the setting persists until the B<afsd>
+command runs again or the B<fs setcachesize> command is reissued. The B<fs
+setcachesize> command does not work for memory caches.
 
 =item *
 
-Sets the size of each cache I<chunk>, and by implication the amount
-of data that the Cache Manager requests at a time from the File Server (how
+Sets the size of each cache I<chunk>, and by implication the amount of
+data that the Cache Manager requests at a time from the File Server (how
 much data per fetch RPC, since AFS uses partial file transfer).
 
-
-For a disk cache, a chunk is a VI<n> file and this
-parameter sets the maximum size to which each one can expand; the default
-is 64 KB. For a memory cache, each chunk is a collection of contiguous
-memory blocks; the default is size is 8 KB.
+For a disk cache, a chunk is a F<< VIZ<><n> >> file and this parameter
+sets the maximum size to which each one can expand; the default is 64
+KB. For a memory cache, each chunk is a collection of contiguous memory
+blocks; the default is size is 8 KB.
 
 To override the default chunk size for either type of cache, use the
-B<-chunksize> argument to provide an integer to be used as an exponent
-of two; see the B<Options> section for details. For a
-memory cache, if total cache size divided by chunk size leaves a remainder,
-the B<afsd> program rounds down the number of dcache entries,
-resulting in a slightly smaller cache.
+B<-chunksize> argument to provide an integer to be used as an exponent of
+two; see L<OPTIONS> for details. For a memory cache, if total cache size
+divided by chunk size leaves a remainder, the B<afsd> program rounds down
+the number of dcache entries, resulting in a slightly smaller cache.
 
 =item *
 
-Sets the number of chunks in the cache. For a memory cache, the
-number of chunks is equal to the cache size divided by the chunk size.
-For a disk cache, the number of chunks (B<V>I<n> files) is set
-to the largest of the following unless the B<-files> argument is used
-to set the value explicitly:
-
+Sets the number of chunks in the cache. For a memory cache, the number of
+chunks is equal to the cache size divided by the chunk size.  For a disk
+cache, the number of chunks (F<< VIZ<><n> >> files) is set to the largest
+of the following unless the B<-files> argument is used to set the value
+explicitly:
 
 =over 4
 
@@ -206,18 +181,15 @@ to set the value explicitly:
 
 100
 
-
 =item *
 
 1.5 times the result of dividing cache size by chunk size
 (I<cachesize>/I<chunksize> * 1.5)
 
-
 =item *
 
 The result of dividing cachesize by 10 KB (I<cachesize>/10240)
 
-
 =back
 
 =item *
@@ -225,33 +197,29 @@ The result of dividing cachesize by 10 KB (I<cachesize>/10240)
 Sets the number of I<dcache entries> allocated in machine memory for
 storing information about the chunks in the cache.
 
+For a disk cache, the F</usr/vice/cache/CacheItems> file contains one
+entry for each F<< VIZ<><n> >> file. By default, one half the number of
+these entries (but not more that 2,000) are duplicated as dcache entries
+in machine memory for quicker access.
 
-For a disk cache, the /usr/vice/cache/CacheItems file contains
-one entry for each B<V>I<n> file. By default, one half
-the number of these entries (but not more that 2,000) are duplicated as dcache
-entries in machine memory for quicker access.
+For a memory cache, there is no F<CacheItems> file so all information
+about cache chunks must be in memory as dcache entries.  Thus, there is no
+default number of dcache entries for a memory cache; instead, the B<afsd>
+program derives it by dividing the cache size by the chunk size.
 
-For a memory cache, there is no CacheItems file so all
-information about cache chunks must be in memory as dcache entries.
-Thus, there is no default number of dcache entries for a memory cache;
-instead, the B<afsd> program derives it by dividing the cache size by
-the chunk size.
-
-To set the number of dcache entries, use the -dcache
-argument; the specified value can exceed the default limit of
-2,000. Using this argument is not recommended for either type of
-cache. Increasing the number of dcache entries for a disk cache
-sometimes improves performance (because more entries are retrieved from memory
-rather than from disk), but only marginally. Using this argument for a
-memory cache requires the issuer to calculate the cache size by multiplying
-this value by the chunk size.
+To set the number of dcache entries, use the B<-dcache> argument; the
+specified value can exceed the default limit of 2,000. Using this argument
+is not recommended for either type of cache. Increasing the number of
+dcache entries for a disk cache sometimes improves performance (because
+more entries are retrieved from memory rather than from disk), but only
+marginally. Using this argument for a memory cache requires the issuer to
+calculate the cache size by multiplying this value by the chunk size.
 
 =item *
 
-Sets the number of I<stat> entries available in machine memory for
-caching status information about cached AFS files. The default is
-300; use the B<-stat> argument to override the default.
-
+Sets the number of I<stat> entries available in machine memory for caching
+status information about cached AFS files. The default is 300; use the
+B<-stat> argument to override the default.
 
 =item *
 
@@ -259,86 +227,73 @@ Randomly selects a file server machine in the local cell as the source for
 the correct time. Every five minutes thereafter, the local clock is
 adjusted (if necessary) to match the file server machine's clock.
 
-
-Use the B<-nosettime> flag to prevent the afsd command
-from selecting a time standard. This is recommended only on file server
-machines that are also acting as clients. File server machines maintain
-the correct time using the Network Time Protocol Daemon instead.
+Use the B<-nosettime> flag to prevent the afsd command from selecting a
+time standard. This is recommended only on file server machines that are
+also acting as clients. File server machines maintain the correct time
+using the Network Time Protocol Daemon instead.
 
 =back
 
-In addition to setting cache configuration parameters, the afsd
-program starts the following daemons. (On most system types, these
-daemons appear as nameless entries in the output of the UNIX B<ps>
-command.)
+In addition to setting cache configuration parameters, the B<afsd> program
+starts the following daemons. (On most system types, these daemons appear
+as nameless entries in the output of the UNIX B<ps> command.)
 
 =over 4
 
 =item *
 
-One I<callback> daemon, which handles callbacks. It also
-responds to the File Server's periodic probes, which check that the
-client machine is still alive.
-
+One I<callback> daemon, which handles callbacks. It also responds to the
+File Server's periodic probes, which check that the client machine is
+still alive.
 
 =item *
 
-One I<maintenance> daemon, which performs the following
-tasks:
-
+One I<maintenance> daemon, which performs the following tasks:
 
 =over 4
 
 =item *
 
 Garbage collects obsolete data (for example, expired tokens) from kernel
-memory
-
+memory.
 
 =item *
 
-Synchronizes files
-
+Synchronizes files.
 
 =item *
 
-Refreshes information from read-only volumes once per hour
-
+Refreshes information from read-only volumes once per hour.
 
 =item *
 
 Does delayed writes for NFS clients if the machine is running the NFS/AFS
-Translator
-
+Translator.
 
 =back
 
 =item *
 
-One I<cache-truncation> daemon, which flushes the cache when free
-space is required, by writing cached data and status information to the File
+One I<cache-truncation> daemon, which flushes the cache when free space is
+required, by writing cached data and status information to the File
 Server.
 
-
 =item *
 
-One I<server connection> daemon, which sends a probe to the File
-Server every few minutes to check that it is still accessible. It also
+One I<server connection> daemon, which sends a probe to the File Server
+every few minutes to check that it is still accessible. It also
 synchronizes the machine's clock with the clock on a randomly-chosen file
-server machine, unless the B<-nosettime> flag is used. There is
-always one server connection daemon.
-
+server machine, unless the B<-nosettime> flag is used. There is always one
+server connection daemon.
 
 =item *
 
-One or more I<background> daemons that improve performance by
-pre-fetching files and performing background (delayed) writes of saved data
-into AFS. 
+One or more I<background> daemons that improve performance by pre-fetching
+files and performing background (delayed) writes of saved data into AFS.
 
-
-The default number of background daemons is two, enough to service at least
-five simultaneous users of the machine. To increase the number, use the
-B<-daemons> argument. A value greater than six is not generally
+The default number of background daemons is two, enough to service at
+least five simultaneous users of the machine. To increase the number, use
+the B<-daemons> argument. A value greater than six is not generally
 necessary.
 
 =item *
@@ -346,122 +301,116 @@ necessary.
 On some system types, one I<Rx listener> daemon, which listens for
 incoming RPCs.
 
-
 =item *
 
 On some system types, one I<Rx event> daemon, which reviews the Rx
-system's queue of tasks and performs them as appropriate. Most
-items in the queue are retransmissions of failed packets.
-
+system's queue of tasks and performs them as appropriate. Most items in
+the queue are retransmissions of failed packets.
 
 =item *
 
 On machines that run AIX with virtual memory (VM) integration, one or more
-I<VM> daemons (sometimes called I<I/O> daemons, which transfer
-data between disk and machine memory. The number of them depends on the
-setting of the B<-biods> and B<-daemons> arguments:
-
+I<VM> daemons (sometimes called I<I/O> daemons, which transfer data
+between disk and machine memory. The number of them depends on the setting
+of the B<-biods> and B<-daemons> arguments:
 
 =over 4
 
 =item *
 
-If the -biods argument is used, it sets the number of VM
-daemons.
-
+If the B<-biods> argument is used, it sets the number of VM daemons.
 
 =item *
 
-If only the -daemons argument is used, the number of VM daemons
-is twice the number of background daemons.
-
+If only the B<-daemons> argument is used, the number of VM daemons is
+twice the number of background daemons.
 
 =item *
 
 If neither argument is used, there are five VM daemons.
 
-
 =back
 
 =back
 
+This command does not use the syntax conventions of the AFS command
+suites. Provide the command name and all option names in full.
+
 =head1 CAUTIONS
 
-Do not use the -shutdown parameter. It does not shutdown
-the Cache Manager effectively. Instead, halt Cache Manager activity by
-using the standard UNIX B<umount> command to unmount the AFS root
-directory (by convention, B</afs>). The machine must then be
-rebooted to reinitialize the Cache Manager.
+Do not use the B<-shutdown> parameter. It does not shutdown the Cache
+Manager effectively. Instead, halt Cache Manager activity by using the
+standard UNIX B<umount> command to unmount the AFS root directory (by
+convention, F</afs>). The machine must then be rebooted to reinitialize
+the Cache Manager.
 
 =head1 OPTIONS
 
 =over 4
 
-=item -blocks
+=item B<-blocks> <I<blocks in cache>>
 
 Specifies the number of kilobyte blocks to be made available for caching
 in the machine's cache directory (for a disk cache) or memory (for a
 memory cache), overriding the default defined in the third field of the
-B</usr/vice/etc/cacheinfo> file. For a disk cache, the value
-cannot exceed 95% of the space available in the cache partition. If
-using a memory cache, do not combine this argument with the B<-dcache>
-argument, since doing so can possibly result in a chunk size that is not an
-exponent of 2.
+F</usr/vice/etc/cacheinfo> file. For a disk cache, the value cannot exceed
+95% of the space available in the cache partition. If using a memory
+cache, do not combine this argument with the B<-dcache> argument, since
+doing so can possibly result in a chunk size that is not an exponent of 2.
 
-=item -files
+=item B<-files> <I<files in cache>>
 
-Specifies the number of VI<n> files to create in the
-cache directory for a disk cache, overriding the default that is calculated as
-described in the B<Description> section. Each
-B<V>I<n> file accommodates a chunk of data, and can grow to a
-maximum size of 64 KB by default. Do not combine this argument with the
-B<-memcache> argument.
+Specifies the number of F<< VIZ<><n> >> files to create in the cache
+directory for a disk cache, overriding the default that is calculated as
+described in L<DESCRIPTION>. Each F<< VIZ<><n> >> file accommodates a
+chunk of data, and can grow to a maximum size of 64 KB by default. Do not
+combine this argument with the B<-memcache> argument.
 
-=item -rootvol
+=item B<-rootvol> <I<name of AFS root volume>>
 
 Names the read/write volume corresponding to the root directory for the
-AFS file tree (which is usually the B</afs> directory). This
-value overrides the default of the B<root.afs> volume.
+AFS file tree (which is usually the F</afs> directory). This value
+overrides the default of the C<root.afs> volume.
 
-=item -stat
+=item B<-stat> <I<number of stat entries>>
 
-Specifies the number of entries to allocate in the machine's memory
-for recording status information about the AFS files in the cache. This
-value overrides the default of 300.
+Specifies the number of entries to allocate in the machine's memory for
+recording status information about the AFS files in the cache. This value
+overrides the default of C<300>.
 
-=item -memcache
+=item B<-memcache>
 
-Initializes a memory cache rather than a disk cache. Do not combine
-this flag with the B<-files> argument.
+Initializes a memory cache rather than a disk cache. Do not combine this
+flag with the B<-files> argument.
 
-=item -cachedir
+=item B<-cachedir> <I<cache directory>>
 
 Names the local disk directory to be used as the cache. This value
 overrides the default defined in the second field of the
-B</usr/vice/etc/cacheinfo> file.
+F</usr/vice/etc/cacheinfo> file.
 
-=item -mountdir
+=item B<-mountdir> <I<mount location>>
 
 Names the local disk directory on which to mount the root of the AFS
-filespace. This value overrides the default defined in the first field
-of the B</usr/vice/etc/cacheinfo> file. If a value other than
-the B</afs> directory is used, the machine cannot access the filespace
-of cells that do use that value.
+filespace. This value overrides the default defined in the first field of
+the F</usr/vice/etc/cacheinfo> file. If a value other than the F</afs>
+directory is used, the machine cannot access the filespace of cells that
+do use that value.
 
-=item -daemons
+=item B<-daemons> <I<number of daemons to use>>
 
-Specifies the number of background daemons to run on the machine.
-These daemons improve efficiency by doing prefetching and background writing
-of saved data. This value overrides the default of 2, which is adequate
-for a machine serving up to five users. Values greater than
-B<6> are not generally more effective than B<6>. 
+Specifies the number of background daemons to run on the machine.  These
+daemons improve efficiency by doing prefetching and background writing of
+saved data. This value overrides the default of C<2>, which is adequate
+for a machine serving up to five users. Values greater than C<6> are not
+generally more effective than C<6>.
 
-Note: On AIX machines with integrated virtual memory (VM),
-the number of VM daemons is set to twice the value of this argument, if it is
-provided and the B<-biods> argument is not. If both arguments
-are omitted, there are five VM daemons.
+Note: On AIX machines with integrated virtual memory (VM), the number of
+VM daemons is set to twice the value of this argument, if it is provided
+and the B<-biods> argument is not. If both arguments are omitted, there
+are five VM daemons.
 
-=item -nosettime
+=item B<-nosettime>
 
 Prevents the Cache Manager from synchronizing its clock with the clock on
 a server machine selected at random, by checking the time on the server
@@ -469,104 +418,100 @@ machine every five minutes. Use this flag only on a machine that is
 already using another time synchronization protocol (for example, a server
 machine that is running the B<runntp> process).
 
-=item -verbose
+=item B<-verbose>
 
-Generates a detailed trace of the afsd program's actions
-on the standard output stream.
+Generates a detailed trace of the B<afsd> program's actions on the
+standard output stream.
 
-=item -rmtsys
+=item B<-rmtsys>
 
 Initializes an additional daemon to execute AFS-specific system calls on
 behalf of NFS client machines. Use this flag only if the machine is an
-NFS/AFS translator machine serving users of NFS client machines who execute
-AFS commands.
-L<(1)>
+NFS/AFS translator machine serving users of NFS client machines who
+execute AFS commands.
 
-=item -debug
+=item B<-debug>
 
-Generates a highly detailed trace of the afsd program's
-actions on the standard output stream. The information is useful mostly
-for debugging purposes.
+Generates a highly detailed trace of the B<afsd> program's actions on the
+standard output stream. The information is useful mostly for debugging
+purposes.
 
-=item -chunksize
+=item B<-chunksize> <I<chunk size>>
 
-Sets the size of each cache chunk. The integer provided, which must
-be from the range B<0> to B<30>, is used as an exponent on the
-number 2. It overrides the default of 16 for a disk cache
-(216 is 64 KB) and 13 for a memory cache (213 is 8
-KB). A value of B<0> or less, or greater than B<30>,
-sets chunk size to the appropriate default. Values less than
-B<10> (which sets chunk size to a 1 KB) are not recommended.
-Combining this argument with the B<-dcache> argument is not
-recommended because it requires that the issuer calculate the cache size that
-results.
+Sets the size of each cache chunk. The integer provided, which must be
+from the range C<0> to C<30>, is used as an exponent on the number 2. It
+overrides the default of 16 for a disk cache (2^16 is 64 KB) and 13 for a
+memory cache (2^13 is 8 KB). A value of C<0> or less, or greater than
+C<30>, sets chunk size to the appropriate default. Values less than C<10>
+(which sets chunk size to a 1 KB) are not recommended.  Combining this
+argument with the B<-dcache> argument is not recommended because it
+requires that the issuer calculate the cache size that results.
 
-=item -dcache
+=item B<-dcache> <I<number of dcache entries>>
 
 Sets the number of dcache entries in memory, which are used to store
 information about cache chunks. For a disk cache, this overrides the
-default, which is 50% of the number of B<V>I<n> files (cache
-chunks). For a memory cache, this argument effectively sets the number
-of cache chunks, but its use is not recommended, because it requires the
+default, which is 50% of the number of F<< VIZ<><n> >> files (cache
+chunks). For a memory cache, this argument effectively sets the number of
+cache chunks, but its use is not recommended, because it requires the
 issuer to calculate the resulting total cache size (derived by multiplying
 this value by the chunk size). Do not combine this argument with the
-B<-blocks> argument, since doing so can possibly result in a chunk
-size that is not an exponent of 2.
+B<-blocks> argument, since doing so can possibly result in a chunk size
+that is not an exponent of 2.
 
-=item -volumes
+=item B<-volumes> <I<number of volume entries>>
 
 Specifies the number of memory structures to allocate for storing volume
-location information. The default value is 50.
+location information. The default value is C<50>.
 
-=item -biods
+=item B<-biods> <I<number of I/O daemons>>
 
 Sets the number of VM daemons dedicated to performing I/O operations on a
-machine running a version of AIX with virtual memory (VM) integration.
-If both this argument and the B<-daemons> argument are omitted, the
-default is five. If this argument is omitted but the
-B<-daemons> argument is provided, the number of VM daemons is set to
-twice the value of the B<-daemons> argument. 
+machine running a version of AIX with virtual memory (VM) integration.  If
+both this argument and the B<-daemons> argument are omitted, the default
+is five. If this argument is omitted but the B<-daemons> argument is
+provided, the number of VM daemons is set to twice the value of the
+B<-daemons> argument.
 
-=item -prealloc
+=item B<-prealloc> <I<number of preallocated blocks>>
 
 Specifies the number of pieces of memory to preallocate for the Cache
-Manager's internal use. The default initial value is 400, but the
-Cache Manager dynamically allocates more memory as it needs it.
+Manager's internal use. The default initial value is C<400>, but the Cache
+Manager dynamically allocates more memory as it needs it.
 
-=item -confdir
+=item B<-confdir> <I<configuration directory>>
 
-Names a directory other than the /usr/vice/etc directory from
-which to fetch the B<cacheinfo>, B<ThisCell>, and
-B<CellServDB> configuration files.
+Names a directory other than the F</usr/vice/etc> directory from which to
+fetch the F<cacheinfo>, F<ThisCell>, and F<CellServDB> configuration
+files.
 
-=item -logfile
+=item B<-logfile> <I<log file location>>
 
-Is obsolete and has no real effect. It specifies an alternate file
-in which to record a type of trace that the Cache Manager no longer
-generates; the default value is B</usr/vice/etc/AFSLog>.
+Is obsolete and has no real effect. It specifies an alternate file in
+which to record a type of trace that the Cache Manager no longer
+generates; the default value is F</usr/vice/etc/AFSLog>.
 
-=item -waitclose
+=item B<-waitclose>
 
-Has no effect on the operation of the Cache Manager. The behavior
-it affected in previous versions of the Cache Manager, to perform synchronous
+Has no effect on the operation of the Cache Manager. The behavior it
+affected in previous versions of the Cache Manager, to perform synchronous
 writes to the File Server, is now the default behavior. To perform
-asynchronous writes in certain cases, use the B<fs storebehind>
-command.
+asynchronous writes in certain cases, use the B<fs storebehind> command.
 
-=item -shutdown
+=item B<-shutdown>
 
 Shuts down the Cache Manager, but not in the most effective possible
 way. Do not use this flag.
 
-=item -enable_peer_stats
+=item B<-enable_peer_stats>
 
 Activates the collection of Rx statistics and allocates memory for their
-storage. For each connection with a specific UDP port on another
-machine, a separate record is kept for each type of RPC (FetchFile, GetStatus,
-and so on) sent or received. To display or otherwise access the
-records, use the Rx Monitoring API.
+storage. For each connection with a specific UDP port on another machine,
+a separate record is kept for each type of RPC (FetchFile, GetStatus, and
+so on) sent or received. To display or otherwise access the records, use
+the Rx Monitoring API.
 
-=item -enable_process_stats
+=item B<-enable_process_stats>
 
 Activates the collection of Rx statistics and allocates memory for their
 storage. A separate record is kept for each type of RPC (FetchFile,
@@ -574,16 +519,16 @@ GetStatus, and so on) sent or received, aggregated over all connections to
 other machines. To display or otherwise access the records, use the Rx
 Monitoring API.
 
-=item -help
+=item B<-help>
 
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
 
 =back
 
 =head1 EXAMPLES
 
-The afsd command is normally included in the machine's AFS
+The B<afsd> command is normally included in the machine's AFS
 initialization file, rather than typed at the command shell prompt. For
 most disk caches, the appropriate form is
 
@@ -595,7 +540,7 @@ NFS/AFS Translator machine serving more than five users.
    /usr/vice/etc/afsd -daemons 4 -rmtsys
 
 The following command initializes a memory cache and sets chunk size to 16
-KB (214).
+KB (2^14).
 
    /usr/vice/etc/afsd -memcache -chunksize 14
 
@@ -605,18 +550,9 @@ The issuer must be logged in as the local superuser root.
 
 =head1 SEE ALSO
 
-L<CacheItems(1)>,
-L<CellServDB (client version)(1)>
-
-L<ThisCell (client version)(1)>
-
-L<VI<n>(1)>,
-L<cacheinfo(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
+L<CacheItems(5)>,
+L<CellServDB(5)>,
+L<cacheinfo(5)>
 
 =head1 COPYRIGHT
 
index ceadf8f..f5ad974 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,190 @@ 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: B<backup diskrestore>, B<backup dump>,
+B<backup volrestore>, and B<backup volsetrestore>.
 
 =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: 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>.
 
 =item *
 
-Commands to write and read tape labels: backup labeltape
-and B<backup readlabel>
-
+Commands to write and read tape labels: B<backup labeltape> and B<backup
+readlabel>.
 
 =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: B<backup jobs>, B<backup kill>, and B<backup
+status>.
 
 =item *
 
-Commands to enter and leave interactive mode: backup
-(interactive) and B<(backup) quit>
-
+Commands to enter and leave interactive mode: B<backup interactive> and
+B<backup quit>.
 
 =item *
 
 Commands to check for and repair corruption in the Backup Database:
-B<backup dbverify>, B<backup restoredb>, and B<backup
-savedb>
-
+B<backup dbverify>, B<backup restoredb>, and B<backup savedb>.
 
 =item *
 
-Commands to obtain help: B<backup apropos> and backup
-help
-
+Commands to obtain help: B<backup apropos> and B<backup help>.
 
 =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: B<backup jobs>, B<backup
+kill>, and B<backup quit>.
 
 =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> 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> 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<-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 +205,19 @@ 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 B<backup diskrestore>,
+B<backup volrestore>, or B<backup volsetrestore> 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 +226,62 @@ 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<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 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<ThisCell(5)>,
+L<UserList(5)>,
+L<tapeconfig(5)>,
+L<backup_adddump(8)>,
+L<backup_addhost(8)>,
+L<backup_addvolentry(8)>,
+L<backup_addvolset(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
 
index 07b14f2..9b26f41 100644 (file)
@@ -4,31 +4,32 @@ backup adddump - Defines a dump level in the dump hierarchy
 
 =head1 SYNOPSIS
 
-B<backup adddump -dump> <I<dump level name>>+ [-expires <I<expiration date>>+]
-[B<-localauth>]  [B<-cell> <I<cell name>>]  [B<-help>]
+B<backup adddump> B<-dump> <I<dump level name>>+
+    [B<-expires> <I<expiration date>>+]
+    [B<-localauth>] [B<-cell> <I<cell name>>] [B<-help>]
 
-B<backup addd -d>  <I<dump level name>>+ [B<-e> <I<expiration date>>+]  [-l]  
-[B<-c> <I<cell name>>]  [B<-h>]
+B<backup addd> B<-d> <I<dump level name>>+ [B<-e> <I<expiration date>>+]
+    [B<-l>] [B<-c> <I<cell name>>] [B<-h>]
 
 =head1 DESCRIPTION
 
-The backup adddump command creates one or more dump levels in
-the dump hierarchy stored in the Backup Database, and optionally assigns an
-expiration date to each one. All of the dump levels in the Backup
-Database collectively constitute the dump hierarchy.
-
-Use the -expires argument to associate an expiration date with
-each dump level. When the Backup System subsequently creates a dump at
-the dump level, it uses the specified value to derive the dump's
-expiration date, which it records on the label of the tape (or backup data
-file). The Backup System refuses to overwrite a tape until after the
-latest expiration date of any dump that the tape contains, unless the
-B<backup labeltape> command is used to relabel the tape. If a
-dump level does not have an expiration date, the Backup System treats dumps
-created at the level as expired as soon as it creates them.
-
-(Note that the Backup System does not automatically remove a dump's
-record from the Backup Database when the dump reaches its expiration date, but
+The B<backup adddump> command creates one or more dump levels in the dump
+hierarchy stored in the Backup Database, and optionally assigns an
+expiration date to each one. All of the dump levels in the Backup Database
+collectively constitute the dump hierarchy.
+
+Use the B<-expires> argument to associate an expiration date with each
+dump level. When the Backup System subsequently creates a dump at the dump
+level, it uses the specified value to derive the dump's expiration date,
+which it records on the label of the tape (or backup data file). The
+Backup System refuses to overwrite a tape until after the latest
+expiration date of any dump that the tape contains, unless the B<backup
+labeltape> command is used to relabel the tape. If a dump level does not
+have an expiration date, the Backup System treats dumps created at the
+level as expired as soon as it creates them.
+
+(Note that the Backup System does not automatically remove a dump's record
+from the Backup Database when the dump reaches its expiration date, but
 only if the tape that contains the dump is recycled or relabeled. To
 remove expired and other obsolete dump records, use the B<backup
 deletedump> command.)
@@ -40,19 +41,17 @@ Define either an absolute or relative expiration date:
 =item *
 
 An absolute expiration date defines the month/day/year (and, optionally,
-hour and minutes) at which a dump expires. If the expiration date
-predates the dump creation time, the Backup System immediately treats the dump
-as expired.
-
+hour and minutes) at which a dump expires. If the expiration date predates
+the dump creation time, the Backup System immediately treats the dump as
+expired.
 
 =item *
 
 A relative date defines the number of years, months, or days (or a
-combination of the three) after the dump's creation that it
-expires. When the Backup System creates a dump at the dump level, it
-calculates an actual expiration date by adding the relative date to the start
-time of the dump operation.
-
+combination of the three) after the dump's creation that it expires. When
+the Backup System creates a dump at the dump level, it calculates an
+actual expiration date by adding the relative date to the start time of
+the dump operation.
 
 =back
 
@@ -60,122 +59,115 @@ time of the dump operation.
 
 =over 4
 
-=item -dump
+=item B<-dump> <I<dump level name>>+
 
-Names each dump level to add to the dump hierarchy. Precede full
-dump level names with a slash (for example, B</full>). Indicate
-an incremental dump level by preceding it with an ordered list of the dump
-levels directly above it in the hierarchy (its parent dump levels); use
-the slash as a separator. The parent dump levels must already
-exist. For example, the dump levels B</full> and
-B</full/incremental1> must exist when the incremental dump level
-B</full/incremental1/incremental2> is created.
+Names each dump level to add to the dump hierarchy. Precede full dump
+level names with a slash (for example, C</full>). Indicate an incremental
+dump level by preceding it with an ordered list of the dump levels
+directly above it in the hierarchy (its parent dump levels); use the slash
+as a separator. The parent dump levels must already exist. For example,
+the dump levels C</full> and C</full/incremental1> must exist when the
+incremental dump level C</full/incremental1/incremental2> is created.
 
 Dump level names can have any number of levels, but cannot exceed 256
 characters in length, including the slashes. The maximum length for any
-single level (the text between slashes) is 28 characters, not including the
-preceding slash.
+single level (the text between slashes) is 28 characters, not including
+the preceding slash.
 
-All alphanumeric characters are allowed in dump level names. Do not
-use the period (B<.>), however, because it is the separator
-between the volume set name and dump level name in the dump name assigned
-automatically by the B<backup dump> command. It is best not to
-include other metacharacters either; if using them, enclose them in
-double quotes (B<" ">) when issuing the B<backup adddump>
-command outside interactive mode.
+All alphanumeric characters are allowed in dump level names. Do not use
+the period (C<.>), however, because it is the separator between the volume
+set name and dump level name in the dump name assigned automatically by
+the B<backup dump> command. It is best not to include other metacharacters
+either; if using them, enclose them in double quotes (C<" ">) when issuing
+the B<backup adddump> command outside interactive mode.
 
-=item -expires
+=item B<-expires> <I<expiration date>>+
 
 Defines the absolute or relative expiration date to associate with each
-dump level named by the B<-dump> argument. Absolute expiration
-dates have the following format:
+dump level named by the B<-dump> argument. Absolute expiration dates have
+the following format:
 
-   [B<at>] {B<NEVER> | I<mm>B</>I<dd>B</>I<yyyy> [I<hh>:I<MM>] }
+   [at] {NEVER | <mm>/<dd>/<yyyy> [<hh>:<MM>] }
 
-where the optional word at is followed either by the string
-B<NEVER>, which indicates that dumps created at the dump level never
-expire, or by a date value with a required portion (I<mm> for month,
-I<dd> for day, and I<yyyy> for year) and an optional portion
-(I<hh> for hours and I<MM> for minutes). 
+where the optional word at is followed either by the string C<NEVER>,
+which indicates that dumps created at the dump level never expire, or by a
+date value with a required portion (<mm> for month, <dd> for day, and
+<yyyy> for year) and an optional portion (<hh> for hours and <MM> for
+minutes).
 
-Omit the I<hh>:I<MM> portion to use the default of
-midnight (00:00 hours), or provide a value in 24-hour format (for
-example, B<20:30> is 8:30 p.m.).
-Valid values for the year range from B<1970> to B<2037>;
-higher values are not valid because the latest possible date in the standard
-UNIX representation is in February 2038. The command interpreter
-automatically reduces later dates to the maximum value.
+Omit the I<hh:MM> portion to use the default of midnight (00:00 hours), or
+provide a value in 24-hour format (for example, C<20:30> is 8:30 p.m.).
+Valid values for the year range from C<1970> to C<2037>; higher values are
+not valid because the latest possible date in the standard UNIX
+representation is in February 2038. The command interpreter automatically
+reduces later dates to the maximum value.
 
 Relative expiration dates have the following format: 
 
-   [B<in>] [I<years>B<y>] [I<months>B<m>] [I<days>d]
+   [in] [<years>y] [<months>m] [<days>d]
 
-where the optional word in is followed by at least one of a
-number of years (maximum B<9999>) followed by the letter B<y>,
-a number of months (maximum B<12>) followed by the letter
-B<m>, or a number of days (maximum B<31>) followed by the
-letter B<d>. If providing more than one of the three, list them
-in the indicated order. If the date that results from adding the
-relative expiration value to a dump's creation time is later than the
-latest possible date in the UNIX time representation, the Backup System
-automatically reduces it to that date. 
+where the optional word in is followed by at least one of a number of
+years (maximum C<9999>) followed by the letter C<y>, a number of months
+(maximum C<12>) followed by the letter C<m>, or a number of days (maximum
+C<31>) followed by the letter C<d>. If providing more than one of the
+three, list them in the indicated order. If the date that results from
+adding the relative expiration value to a dump's creation time is later
+than the latest possible date in the UNIX time representation, the Backup
+System automatically reduces it to that date.
 
-=item -localauth
+=item B<-localauth>
 
 Constructs a server ticket using a key from the local
-B</usr/afs/etc/KeyFile> file. The B<backup> command
-interpreter presents it to the Backup Server, Volume Server and VL Server
-during mutual authentication. Do not combine this flag with the
-B<-cell> argument. For more details, see the introductory
-B<backup> reference page.
+F</usr/afs/etc/KeyFile> file. The B<backup> command interpreter presents
+it to the Backup Server, Volume Server and VL Server during mutual
+authentication. Do not combine this flag with the B<-cell> argument. For
+more details, see L<backup(8)>.
 
-=item -cell
+=item B<-cell> <I<cell name>>
 
-Names the cell in which to run the command. Do not combine this
-argument with the B<-localauth> flag. For more details, see the
-introductory B<backup> reference page.
+Names the cell in which to run the command. Do not combine this argument
+with the B<-localauth> flag. For more details, see L<backup(8)>.
 
-=item -help
+=item B<-help>
 
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
 
 =back
 
 =head1 EXAMPLES
 
-The following command defines a full dump called /1999 with a
-relative expiration date of one year:
+The following command defines a full dump called C</1999> with a relative
+expiration date of one year:
 
    % backup adddump -dump /1999 -expires in 1y
 
 The following command defines an incremental dump called
-B</sunday1/monday>1 with a relative expiration date of 13 days:
+C</sunday1/monday>1 with a relative expiration date of 13 days:
 
    % backup adddump -dump /sunday1/monday1 -expires in 13d
 
 The following command defines two dump incremental dump levels,
-B</Monthly/Week1> and B</Monthly/Week2>. Their parent,
-the full dump level B</Monthly>, must already exist. The
-expiration date for both levels is 12:00 a.m. on 1 January
-2000.
+C</Monthly/Week1> and C</Monthly/Week2>. Their parent, the full dump level
+C</Monthly>, must already exist. The expiration date for both levels is
+12:00 a.m. on 1 January 2000.
 
    % backup adddump -dump /Monthly/Week1 /Monthly/Week2 -expires at 01/01/2000
 
 =head1 PRIVILEGE REQUIRED
 
-The issuer must be listed in the /usr/afs/etc/UserList file on
-every machine where the Backup Server is running, or must be logged onto a
-server machine as the local superuser B<root> if the
-B<-localauth> flag is included.
+The issuer must be listed in the F</usr/afs/etc/UserList> file on every
+machine where the Backup Server is running, or must be logged onto a
+server machine as the local superuser C<root> if the B<-localauth> flag is
+included.
 
 =head1 SEE ALSO
 
-L<backup(1)>,
-L<backup_deldump(1)>,
-L<backup_deletedump(1)>,
-L<backup_listdumps(1)>,
-L<backup_setexp(1)>
+L<backup(8)>,
+L<backup_deldump(8)>,
+L<backup_deletedump(8)>,
+L<backup_listdumps(8)>,
+L<backup_setexp(8)>
 
 =head1 COPYRIGHT
 
index 879b42c..1ecbabd 100644 (file)
@@ -4,83 +4,78 @@ backup addhost - Adds a Tape Coordinator entry to the Backup Database
 
 =head1 SYNOPSIS
 
-B<backup addhost -tapehost> <I<tape machine name>> [-portoffset <I<TC port offset>>]
-[B<-localauth>]  [B<-cell> <I<cell name>>]  [B<-help>]
+B<backup addhost> B<-tapehost> <I<tape machine name>>
+    [B<-portoffset> <I<TC port offset>>]
+    [B<-localauth>] [B<-cell> <I<cell name>>] [B<-help>]
 
-B<backup addh -t> <I<tape machine name>>  [-p <I<TC port offset>>]
-[B<-l>]  [B<-c> <I<cell name>>]  [B<-h>]
+B<backup addh> B<-t> <I<tape machine name>> [B<-p> <I<TC port offset>>]
+    [B<-l>] [B<-c> <I<cell name>>] [B<-h>]
 
 =head1 DESCRIPTION
 
-The backup addhost command creates a Tape Coordinator entry in
-the Backup Database. The entry records
+The B<backup addhost> command creates a Tape Coordinator entry in the
+Backup Database. The entry records
 
 =over 4
 
 =item *
 
 The host name of the Tape Coordinator machine where the Tape Coordinator
-(B<butc>) process runs, as specified with the B<-tapehost>
-argument.
-
+(B<butc>) process runs, as specified with the B<-tapehost> argument.
 
 =item *
 
 The Tape Coordinator's port offset number, as specified with the
-B<-portoffset> argument. An entry for the port offset must also
-appear in the B</usr/afs/backup/tapeconfig> file on the Tape
-Coordinator machine, where it is mapped to a UNIX device name (for a tape
-device) or pathname (for a backup data file).
-
+B<-portoffset> argument. An entry for the port offset must also appear in
+the F</usr/afs/backup/tapeconfig> file on the Tape Coordinator machine,
+where it is mapped to a UNIX device name (for a tape device) or pathname
+(for a backup data file).
 
 =back
 
-Each Tape Coordinator must have its own port offset number, and the command
-fails if a Backup Database entry already exists for the requested port offset
-number. To display existing Tape Coordinator entries, use the
+Each Tape Coordinator must have its own port offset number, and the
+command fails if a Backup Database entry already exists for the requested
+port offset number. To display existing Tape Coordinator entries, use the
 B<backup listhosts> command.
 
 =head1 OPTIONS
 
 =over 4
 
-=item -tapehost
+=item B<-tapehost> <I<tape machine name>>
 
 Specifies the fully-qualified hostname of the machine for which to create
-a Tape Coordinator entry in the Backup Database. The machine must have
-an entry in either the cell's naming service (such as the Domain Name
-Service) or the host file (B</etc/hosts> or equivalent) on the machine
+a Tape Coordinator entry in the Backup Database. The machine must have an
+entry in either the cell's naming service (such as the Domain Name
+Service) or the host file (F</etc/hosts> or equivalent) on the machine
 where the command is issued.
 
-=item -portoffset
+=item B<-portoffset> <I<TC port offset>>
 
-Specifies the Tape Coordinator's port offset number. Provide
-an integer from the range B<0> through B<58510>, or omit this
-argument to use the default value of B<0> (zero). The value
-must match the port offset number recorded for the same combination of Tape
-Coordinator and tape device or file in the
-B</usr/afs/backup/tapeconfig> file on the Tape Coordinator machine
-named by the B<-tapehost> argument.
+Specifies the Tape Coordinator's port offset number. Provide an integer
+from the range C<0> through C<58510>, or omit this argument to use the
+default value of C<0> (zero). The value must match the port offset number
+recorded for the same combination of Tape Coordinator and tape device or
+file in the F</usr/afs/backup/tapeconfig> file on the Tape Coordinator
+machine named by the B<-tapehost> argument.
 
-=item -localauth
+=item B<-localauth>
 
 Constructs a server ticket using a key from the local
-B</usr/afs/etc/KeyFile> file. The B<backup> command
-interpreter presents it to the Backup Server, Volume Server and VL Server
-during mutual authentication. Do not combine this flag with the
-B<-cell> argument. For more details, see the introductory
-B<backup> reference page.
+F</usr/afs/etc/KeyFile> file. The B<backup> command interpreter presents
+it to the Backup Server, Volume Server and VL Server during mutual
+authentication. Do not combine this flag with the B<-cell> argument. For
+more details, see L<backup(8)>.
 
-=item -cell
+=item B<-cell> <I<cell name>>
 
-Names the cell in which to run the command. Do not combine this
-argument with the B<-localauth> flag. For more details, see the
-introductory B<backup> reference page.
+Names the cell in which to run the command. Do not combine this argument
+with the B<-localauth> flag. For more details, see L<backup(8)>.
 
-=item -help
+=item B<-help>
 
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
 
 =back
 
@@ -88,28 +83,27 @@ are ignored.
 
 The following command creates an entry in the Backup Database that assigns
 port offset number 4 to a Tape Coordinator running on the machine
-B<backup1.abc.com>:
+C<backup1.abc.com>:
 
    % backup addhost -tapehost backup1.abc.com -portoffset 4
 
 The following command creates a Backup Database entry that assigns port
-offset number 0 to a Tape Coordinator on the machine
-B<backup3.abc.com>:
+offset number 0 to a Tape Coordinator on the machine C<backup3.abc.com>:
 
    % backup addhost backup3.abc.com
 
 =head1 PRIVILEGE REQUIRED
 
-The issuer must be listed in the /usr/afs/etc/UserList file on
-every machine where the Backup Server is running, or must be logged onto a
-server machine as the local superuser B<root> if the
-B<-localauth> flag is included.
+The issuer must be listed in the F</usr/afs/etc/UserList> file on every
+machine where the Backup Server is running, or must be logged onto a
+server machine as the local superuser C<root> if the B<-localauth> flag is
+included.
 
 =head1 SEE ALSO
 
-L<backup(1)>,
-L<backup_delhost(1)>,
-L<backup_listhosts(1)>
+L<backup(8)>,
+L<backup_delhost(8)>,
+L<backup_listhosts(8)>
 
 =head1 COPYRIGHT
 
index 1251704..037b635 100644 (file)
@@ -4,89 +4,80 @@ backup addvolentry - Defines a volume entry in a volume set
 
 =head1 SYNOPSIS
 
-B<backup addvolentry -name> <I<volume set name>>  -server <I<machine name>>
-B<-partition> <I<partition name>> 
-                   -volumes <I<volume name (regular expression)>>   
-                   [B<-localauth>]  [B<-cell> <I<cell name>>]  [-help]
+B<backup addvolentry> B<-name> <I<volume set name>>
+    B<-server> <I<machine name>> B<-partition> <I<partition name>> 
+    B<-volumes> <I<volume name (regular expression)>>   
+    [B<-localauth>] [B<-cell> <I<cell name>>] [B<-help>]
 
-B<backup addvole -n> <I<volume set name>>  B<-s> <I<machine name>> -p <I<partition name>>
-B<-v> <I<volume name (regular expression)>>
-               [B<-l>]  [B<-c> <I<cell name>>]  [-h]
+B<backup addvole> B<-n> <I<volume set name>> B<-s> <I<machine name>>
+    B<-p> <I<partition name>> B<-v> <I<volume name (regular expression)>>
+    [B<-l>] [B<-c> <I<cell name>>] [B<-h>]
 
 =head1 DESCRIPTION
 
-The backup addvolentry command adds a volume entry definition to
-the existing volume set named by the B<-name> argument. A
-volume entry definition can match one or more volumes, depending on the
-combination of the B<-server>, B<-partition>, and
-B<-volumes> arguments.
+The B<backup addvolentry> command adds a volume entry definition to the
+existing volume set named by the B<-name> argument. A volume entry
+definition can match one or more volumes, depending on the combination of
+the B<-server>, B<-partition>, and B<-volumes> arguments.
 
-For the B<-server> and -partition arguments, provide
-either
+For the B<-server> and B<-partition> arguments, provide either
 
 =over 4
 
 =item *
 
-The name of one machine or partition
-
+The name of one machine or partition.
 
 =item *
 
-The metacharacter expression .* (period and asterisk),
-which matches every machine name or partition name in the Volume Location
-Database (VLDB).
-
+The metacharacter expression .* (period and asterisk), which matches every
+machine name or partition name in the Volume Location Database (VLDB).
 
 =back
 
-For the -volumes argument, specify a combination of alphanumeric
+For the B<-volumes> argument, specify a combination of alphanumeric
 characters and one or more metacharacters to wildcard part or all of the
-volume name. The B<Options> section lists the acceptable
-metacharacters.
+volume name. L<OPTIONS> lists the acceptable metacharacters.
 
 =head1 CAUTIONS
 
-It is best to issue this command in interactive mode. If issuing it
-at the shell prompt, enclose any strings containing metacharacters in double
+It is best to issue this command in interactive mode. If issuing it at the
+shell prompt, enclose any strings containing metacharacters in double
 quotes, or escape the metacharacters with other delimiters, to prevent the
-shell from interpreting them. Adding volume entries to a temporary
-volume set is possible only within the interactive session in which the volume
+shell from interpreting them. Adding volume entries to a temporary volume
+set is possible only within the interactive session in which the volume
 set was created.
 
 =head1 OPTIONS
 
 =over 4
 
-=item -name
+=item B<-name> <I<volume set name>>
 
-Names the volume set to which to add this volume entry definition.
-The volume set must already exist (use the B<backup addvolset> command
-to create it).
+Names the volume set to which to add this volume entry definition.  The
+volume set must already exist (use the B<backup addvolset> command to
+create it).
 
-=item -server
+=item B<-server> <I<machine name>>
 
 Defines the set of one or more file server machines that house the volumes
-in the volume entry. Provide either one fully-qualified hostname (such
-as B<fs1.abc.com>) or the metacharacter expression
-B<.*> (period and asterisk), which matches all machine names in
-the VLDB.
+in the volume entry. Provide either one fully-qualified hostname (such as
+C<fs1.abc.com>) or the metacharacter expression C<.*> (period and
+asterisk), which matches all machine names in the VLDB.
 
-=item -partition
+=item B<-partition> <I<partition name>>
 
 Defines the set of one or more partitions that house the volumes in the
 volume entry. Provide either one complete partition name (such as
-B</vicepa>) or the metacharacter expression B<.*>
-(period and asterisk), which matches all partition names.
+C</vicepa>) or the metacharacter expression C<.*> (period and asterisk),
+which matches all partition names.
 
-=item -volumes
+=item B<-volumes> <I<volume name>>
 
 Defines the set of one or more volumes included in the volume
 entry. Specify the volumes by name, by using any combination of regular
 alphanumeric characters and one or more of the following metacharacter
 expressions:
-L<(1)>
-L<(1)>
 
 =over 4
 
@@ -96,108 +87,100 @@ The period matches any single character.
 
 =item *
 
-The asterisk matches zero or more instances of the preceding
-character. Combine it with any other alphanumeric character or
-metacharacter.
+The asterisk matches zero or more instances of the preceding character.
+Combine it with any other alphanumeric character or metacharacter.
 
 =item [ ]
 
 Square brackets around a list of characters match a single instance of any
-of the characters, but no other characters; for example, B<[abc]>
-matches a single B<a> or B<b> or B<c>, but not
-B<d> or B<A>. This expression can be combined with the
-asterisk.
+of the characters, but no other characters; for example, C<[abc]> matches
+a single C<a> or C<b> or C<c>, but not C<d> or C<A>. This expression can
+be combined with the asterisk.
 
 =item ^
 
 The caret, when used as the first character in a square-bracketed set,
-designates a match with any single character I<except> the characters
-that follow it; for example, B<[^a]> matches any single character
-except lowercase B<a>. This expression can be combined with the
-asterisk.
+designates a match with any single character I<except> the characters that
+follow it; for example, C<[^a]> matches any single character except
+lowercase C<a>. This expression can be combined with the asterisk.
 
 =item \
 
 A backslash preceding any of the metacharacters in this list makes it
-match its literal value only. For example, the expression
-B<\.> (backslash and period) matches a single period,
-B<\*> a single asterisk, and B<\\> a single backslash.
-Such expressions can be combined with the asterisk (for example,
-B<\.*> matches any number of periods).
+match its literal value only. For example, the expression C<\.> (backslash
+and period) matches a single period, C<\*> a single asterisk, and C<\\> a
+single backslash.  Such expressions can be combined with the asterisk (for
+example, C<\.*> matches any number of periods).
 
 =back
 
 Perhaps the most common metacharacter expression is the period followed by
-an asterisk (B<.*>). This expression matches any string
-of any length, because the period matches any character and the asterisk means
-any number of that character. As mentioned, it is the only acceptable
-metacharacter expression for the B<-server> and B<-partition>
-arguments. In a volume definition it can stand alone (in which case it
-matches every volume listed in the VLDB), or can combine with regular
-characters. The following example matches any volume name that begins
-with the string B<user> and ends with B<backup>: 
+an asterisk (C<.*>). This expression matches any string of any length,
+because the period matches any character and the asterisk means any number
+of that character. As mentioned, it is the only acceptable metacharacter
+expression for the B<-server> and B<-partition> arguments. In a volume
+definition it can stand alone (in which case it matches every volume
+listed in the VLDB), or can combine with regular characters. The following
+example matches any volume name that begins with the string C<user> and
+ends with C<backup>:
 
    user.*backup
 
-=item -localauth
+=item B<-localauth>
 
 Constructs a server ticket using a key from the local
-B</usr/afs/etc/KeyFile> file. The B<backup> command
-interpreter presents it to the Backup Server, Volume Server and VL Server
-during mutual authentication. Do not combine this flag with the
-B<-cell> argument. For more details, see the introductory
-B<backup> reference page.
+F</usr/afs/etc/KeyFile> file. The B<backup> command interpreter presents
+it to the Backup Server, Volume Server and VL Server during mutual
+authentication. Do not combine this flag with the B<-cell> argument. For
+more details, see L<backup(8)>.
 
-=item -cell
+=item B<-cell> <I<cell name>>
 
-Names the cell in which to run the command. Do not combine this
-argument with the B<-localauth> flag. For more details, see the
-introductory B<backup> reference page.
+Names the cell in which to run the command. Do not combine this argument
+with the B<-localauth> flag. For more details, see L<backup(8)>.
 
-=item -help
+=item B<-help>
 
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
 
 =back
 
 =head1 EXAMPLES
 
 The following command adds a volume entry to the volume set called
-B<sys>. The entry matches all volumes on any machine or
-partition whose names begin with the string B<sun4x_56> followed by a
-period:
+C<sys>. The entry matches all volumes on any machine or partition whose
+names begin with the string C<sun4x_56> followed by a period:
 
    backup> addvolentry sys .* .* sun4x_56\..*
 
-The following command adds a volume entry to the volume set called
-B<fs2>, to match all volumes on the B</vicepb> partition of
-file server machine B<fs2.abc.com>. Because it is
-issued at the shell prompt, double quotes surround the metacharacters in the
-B<-volumes> argument. (The command is shown here on two lines
-only for legibility reasons.)
+The following command adds a volume entry to the volume set called C<fs2>,
+to match all volumes on the F</vicepb> partition of file server machine
+C<fs2.abc.com>. Because it is issued at the shell prompt, double quotes
+surround the metacharacters in the B<-volumes> argument. (The command is
+shown here on two lines only for legibility reasons.)
 
    % backup addvolentry -name fs2 -server fs2.abc.com \
                         -partition /vicepb -volumes ".*"
 
-The chapter in the I<IBM AFS Administration Guide> about
-configuring the AFS Backup System presents additional examples as well as
-advice on grouping volumes.
+The chapter in the I<IBM AFS Administration Guide> about configuring the
+AFS Backup System presents additional examples as well as advice on
+grouping volumes.
 
 =head1 PRIVILEGE REQUIRED
 
-The issuer must be listed in the /usr/afs/etc/UserList file on
-every machine where the Backup Server is running, or must be logged onto a
-server machine as the local superuser B<root> if the
-B<-localauth> flag is included.
+The issuer must be listed in the F</usr/afs/etc/UserList> file on every
+machine where the Backup Server is running, or must be logged onto a
+server machine as the local superuser C<root> if the B<-localauth> flag is
+included.
 
 =head1 SEE ALSO
 
-L<backup(1)>,
-L<backup_addvolset(1)>,
-L<backup_delvolentry(1)>,
-L<backup_delvolset(1)>,
-L<backup_listvolsets(1)>
+L<backup(8)>,
+L<backup_addvolset(8)>,
+L<backup_delvolentry(8)>,
+L<backup_delvolset(8)>,
+L<backup_listvolsets(8)>
 
 =head1 COPYRIGHT
 
index cd7dfa5..e1575d2 100644 (file)
@@ -4,101 +4,96 @@ backup addvolset - Creates a new (empty) volume set
 
 =head1 SYNOPSIS
 
-B<backup addvolset -name> <I<volume set name>> [-temporary] 
-[B<-localauth>]  [B<-cell> <I<cell name>>]  [B<-help>]
+B<backup addvolset> B<-name> <I<volume set name>> [B<-temporary>]
+    [B<-localauth>] [B<-cell> <I<cell name>>] [B<-help>]
 
-B<backup addvols -n> <I<volume set name>> [B<-t>]  [B<-l>]  [B<-c> <I<cell name>>]  [-h]
+B<backup addvols> B<-n> <I<volume set name>> [B<-t>] [B<-l>]
+    [B<-c> <I<cell name>>] [B<-h>]
 
 =head1 DESCRIPTION
 
-The backup addvolset command creates a new volume set, by
-default adding it to the Backup Database. It is best that the volume
-set's name indicate the volume set's contents; for example,
-define the volume entries in the B<user> volume set to match all user
-volumes. The volume set name must be unique within the Backup Database
-of the local cell.
+The B<backup addvolset> command creates a new volume set, by default
+adding it to the Backup Database. It is best that the volume set's name
+indicate the volume set's contents; for example, define the volume entries
+in the C<user> volume set to match all user volumes. The volume set name
+must be unique within the Backup Database of the local cell.
 
-After issuing this command, issue the backup addvolentry command
-to define the volume entries in the volume set.
+After issuing this command, issue the B<backup addvolentry> command to
+define the volume entries in the volume set.
 
 Sometimes it is convenient to create volume sets without recording them
 permanently in the Backup Database, for example when using the B<backup
 volsetrestore> command to restore a group of volumes that were not
-necessarily backed up together. To create a I<temporary> volume
-set, include the B<-temporary> flag. A temporary volume set
-exists only during the lifetime of the current interactive session, so the
-flag is effective only when used during an interactive session (opened by
-issuing the B<backup interactive> command). If it is included
-when the command is issued at the regular command shell prompt, the command
-appears to succeed, but the volume set is not created. As noted, a
-temporary volume set ceases to exist when the current interactive session
-ends, or use the B<backup delvolset> command to delete it before
-that.
-
-One advantage of temporary volume sets is that the backup
-addvolset command, and any B<backup addvolentry> commands
-subsequently used to add volume entries to it, complete more quickly than for
-regular volume sets, because no records are created in the Backup
-Database.
+necessarily backed up together. To create a I<temporary> volume set,
+include the B<-temporary> flag. A temporary volume set exists only during
+the lifetime of the current interactive session, so the flag is effective
+only when used during an interactive session (opened by issuing the
+B<backup interactive> command). If it is included when the command is
+issued at the regular command shell prompt, the command appears to
+succeed, but the volume set is not created. As noted, a temporary volume
+set ceases to exist when the current interactive session ends, or use the
+B<backup delvolset> command to delete it before that.
+
+One advantage of temporary volume sets is that the B<backup addvolset>
+command, and any B<backup addvolentry> commands subsequently used to add
+volume entries to it, complete more quickly than for regular volume sets,
+because no records are created in the Backup Database.
 
 =head1 OPTIONS
 
 =over 4
 
-=item -name
+=item B<-name> <I<volume set name>>
 
-Names the new volume set. The name can include up to 31 of any
-character other than the period. Avoid other metacharacters as
-well.
+Names the new volume set. The name can include up to 31 of any character
+other than the period. Avoid other metacharacters as well.
 
-=item -temporary
+=item B<-temporary>
 
 Creates a volume set that exists only within the context of the current
 interactive session. It is not added to the Backup Database.
 
-=item -localauth
+=item B<-localauth>
 
 Constructs a server ticket using a key from the local
-B</usr/afs/etc/KeyFile> file. The B<backup> command
-interpreter presents it to the Backup Server, Volume Server and VL Server
-during mutual authentication. Do not combine this flag with the
-B<-cell> argument. For more details, see the introductory
-B<backup> reference page.
+F</usr/afs/etc/KeyFile> file. The B<backup> command interpreter presents
+it to the Backup Server, Volume Server and VL Server during mutual
+authentication. Do not combine this flag with the B<-cell> argument. For
+more details, see L<backup(8)>.
 
-=item -cell
+=item B<-cell> <I<cell name>>
 
-Names the cell in which to run the command. Do not combine this
-argument with the B<-localauth> flag. For more details, see the
-introductory B<backup> reference page.
+Names the cell in which to run the command. Do not combine this argument
+with the B<-localauth> flag. For more details, see L<backup(8)>.
 
-=item -help
+=item B<-help>
 
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
 
 =back
 
 =head1 EXAMPLES
 
-The following command creates a volume set called sys:
+The following command creates a volume set called C<sys>:
 
    % backup addvolset sys
 
 =head1 PRIVILEGE REQUIRED
 
-The issuer must be listed in the /usr/afs/etc/UserList file on
-every machine where the Backup Server is running, or must be logged onto a
-server machine as the local superuser B<root> if the
-B<-localauth> flag is included.
+The issuer must be listed in the F</usr/afs/etc/UserList> file on every
+machine where the Backup Server is running, or must be logged onto a
+server machine as the local superuser C<root> if the B<-localauth> flag is
+included.
 
 =head1 SEE ALSO
 
-L<backup(1)>,
-L<backup_addvolentry(1)>,
-L<backup_delvolentry(1)>,
-L<backup_delvolset(1)>,
-L<backup_listvolsets(1)>,
-L<backup_volsetrestore(1)>
+L<backup(8)>,
+L<backup_addvolentry(8)>,
+L<backup_delvolentry(8)>,
+L<backup_delvolset(8)>,
+L<backup_listvolsets(8)>,
+L<backup_volsetrestore(8)>
 
 =head1 COPYRIGHT
 
index 694c98e..5519253 100644 (file)
@@ -4,33 +4,32 @@ backup apropos - Displays each help entry containing a keyword string
 
 =head1 SYNOPSIS
 
-B<backup apropos -topic> <I<help string>>  [-help] 
+B<backup apropos> B<-topic> <I<help string>> [B<-help>] 
 
-B<backup ap -t> <I<help string>>  [-h]
+B<backup ap> B<-t> <I<help string>> [B<-h>]
 
 =head1 DESCRIPTION
 
-The backup apropos command displays the first line of the online
-help entry for any B<backup> command that has in its name or short
-description the string specified by the B<-topic> argument.
+The B<backup apropos> command displays the first line of the online help
+entry for any B<backup> command that has in its name or short description
+the string specified by the B<-topic> argument.
 
-To display the syntax for a command, use the backup help
-command.
+To display the syntax for a command, use the B<backup help> command.
 
 =head1 OPTIONS
 
 =over 4
 
-=item -topic
+=item B<-topic> <I<help string>>
 
-Specifies the keyword string to match, in lowercase letters only.
-If the string is more than a single word, surround it with double quotes
-(B<" ">) or other delimiters.
+Specifies the keyword string to match, in lowercase letters only.  If the
+string is more than a single word, surround it with double quotes (C<" ">)
+or other delimiters.
 
-=item -help
+=item B<-help>
 
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
 
 =back
 
@@ -38,13 +37,13 @@ are ignored.
 
 The first line of a command's online help entry names it and briefly
 describes its function. This command displays the first line for any
-B<backup> command where the string specified with the
-B<-topic> argument is part of the command name or first line.
+B<backup> command where the string specified with the B<-topic> argument
+is part of the command name or first line.
 
 =head1 EXAMPLES
 
-The following example lists all backup commands that include the
-word B<tape> in their names or short descriptions:
+The following example lists all backup commands that include the word
+C<tape> in their names or short descriptions:
 
    % backup apropos tape
    labeltape: label a tape
@@ -58,8 +57,8 @@ None
 
 =head1 SEE ALSO
 
-L<backup(1)>,
-L<backup_help(1)>
+L<backup(8)>,
+L<backup_help(8)>
 
 =head1 COPYRIGHT
 
index 23826dd..4be9602 100644 (file)
@@ -4,55 +4,54 @@ backup dbverify - Checks the integrity of the Backup Database
 
 =head1 SYNOPSIS
 
-B<backup dbverify> [B<-detail>]  [B<-localauth>]  [B<-cell> <I<cell name>>]  [-help]
+B<backup dbverify> [B<-detail>] [B<-localauth>] [B<-cell> <I<cell name>>]
+    [B<-help>]
 
-B<backup db> [B<-d>]  [B<-l>]  [B<-c> <I<cell name>>]  [-h]
+B<backup db> [B<-d>] [B<-l>] [B<-c> <I<cell name>>] [B<-h>]
 
 =head1 DESCRIPTION
 
-The backup dbverify command checks the integrity of the Backup
-Database. The command's output indicates whether the Backup
-Database is damaged (data is corrupted) or not. If the Backup Database
-is undamaged, it is safe to continue using it. If it is corrupted,
-discontinue any backup operations until it is repaired.
+The B<backup dbverify> command checks the integrity of the Backup
+Database. The command's output indicates whether the Backup Database is
+damaged (data is corrupted) or not. If the Backup Database is undamaged,
+it is safe to continue using it. If it is corrupted, discontinue any
+backup operations until it is repaired.
 
 =head1 CAUTIONS
 
 While this command runs, no other backup operation can access the Backup
 Database; the other commands do not run until this command
 completes. Avoid issuing this command when other backup operations are
-likely to run. The B<backup savedb> command repairs some types
-of corruption.
+likely to run. The B<backup savedb> command repairs some types of
+corruption.
 
 =head1 OPTIONS
 
 =over 4
 
-=item -detail
+=item B<-detail>
 
 Reports the number of orphaned blocks found, any inconsistencies, and the
-name of the server machine running the Backup Server that is checking its copy
-of the database.
+name of the server machine running the Backup Server that is checking its
+copy of the database.
 
-=item -localauth
+=item B<-localauth>
 
 Constructs a server ticket using a key from the local
-B</usr/afs/etc/KeyFile> file. The B<backup> command
-interpreter presents it to the Backup Server, Volume Server and VL Server
-during mutual authentication. Do not combine this flag with the
-B<-cell> argument. For more details, see the introductory
-B<backup> reference page.
+F</usr/afs/etc/KeyFile> file. The B<backup> command interpreter presents
+it to the Backup Server, Volume Server and VL Server during mutual
+authentication. Do not combine this flag with the B<-cell> argument. For
+more details, see L<backup(8)>.
 
-=item -cell
+=item B<-cell> <I<cell name>>
 
-Names the cell in which to run the command. Do not combine this
-argument with the B<-localauth> flag. For more details, see the
-introductory B<backup> reference page.
+Names the cell in which to run the command. Do not combine this argument
+with the B<-localauth> flag. For more details, see L<backup(8)>.
 
-=item -help
+=item B<-help>
 
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
 
 =back
 
@@ -62,49 +61,43 @@ The command displays one of the following two messages:
 
 =over 4
 
-=item C<Database OK
->
+=item Database OK
 
 The database is undamaged and can be used.
 
-=item C<Database not OK
->
+=item Database not OK
 
-The database is damaged. You can use the backup savedb
-command to repair many kinds of corruption as it creates a backup copy.
-For more detailed instructions, see the I<IBM AFS Administration
-Guide> chapter about performing backup operations.
+The database is damaged. You can use the backup savedb command to repair
+many kinds of corruption as it creates a backup copy.  For more detailed
+instructions, see the I<IBM AFS Administration Guide> chapter about
+performing backup operations.
 
 =back
 
-The -detail flag provides additional information:
+The B<-detail> flag provides additional information:
 
 =over 4
 
 =item *
 
-The number of I<orphan blocks> found. These are ranges of
-memory that the Backup Server preallocated in the database but cannot
-use. Orphan blocks do not interfere with database access, but do waste
-disk space. To free the unusable space, dump the database to tape by
-using the B<backup savedb> command, and then restore it by using the
-B<backup restoredb> command.
-
+The number of I<orphan blocks> found. These are ranges of memory that the
+Backup Server preallocated in the database but cannot use. Orphan blocks
+do not interfere with database access, but do waste disk space. To free
+the unusable space, dump the database to tape by using the B<backup
+savedb> command, and then restore it by using the B<backup restoredb>
+command.
 
 =item *
 
 Any inconsistencies in the database, such as invalid hostnames for Tape
 Coordinator machines.
 
-
 =item *
 
 The name of the database server machine on which the Backup Database was
-checked, designated as the C<Database checker>. For a detailed
-trace of the verification operation, see the
-B</usr/afs/logs/BackupLog> file on the indicated machine. You
-can use the B<bos getlog> command to display it.
-
+checked, designated as the C<Database checker>. For a detailed trace of
+the verification operation, see the F</usr/afs/logs/BackupLog> file on the
+indicated machine. You can use the B<bos getlog> command to display it.
 
 =back
 
@@ -117,8 +110,8 @@ The following command confirms that the Backup Database is undamaged:
 
 The following command confirms that the Backup Database is undamaged and
 that it has no orphan blocks or invalid Tape Coordinator entries. The
-Backup Server running on the machine B<db1.abc.com>
-checked its copy of the Database.
+Backup Server running on the machine C<db1.abc.com> checked its copy of
+the Database.
 
    % backup dbverify -detail
    Database OK
@@ -127,18 +120,18 @@ checked its copy of the Database.
 
 =head1 PRIVILEGE REQUIRED
 
-The issuer must be listed in the /usr/afs/etc/UserList file on
-every machine where the Backup Server is running, or must be logged onto a
-server machine as the local superuser B<root> if the
-B<-localauth> flag is included.
+The issuer must be listed in the F</usr/afs/etc/UserList> file on every
+machine where the Backup Server is running, or must be logged onto a
+server machine as the local superuser C<root> if the B<-localauth> flag is
+included.
 
 =head1 SEE ALSO
 
-L<BackupLog(1)>,
-L<bos_getlog(1)>,
-L<backup(1)>,
-L<backup_restoredb(1)>,
-L<backup_savedb(1)>
+L<BackupLog(5)>,
+L<backup(8)>,
+L<backup_restoredb(8)>,
+L<backup_savedb(8)>,
+L<bos_getlog(8)>
 
 =head1 COPYRIGHT
 
index af427eb..848052f 100644 (file)
@@ -4,67 +4,65 @@ backup deldump - Deletes a dump level from the Backup Database
 
 =head1 SYNOPSIS
 
-B<backup deldump -dump> <I<dump level name>>  [-localauth]  
-[B<-cell> <I<cell name>>]  [B<-help>]
+B<backup deldump> B<-dump> <I<dump level name>> [B<-localauth>]
+    [B<-cell> <I<cell name>>] [B<-help>]
 
-B<backup deld -d> <I<dump level name>>  [B<-l>]  [B<-c> <I<cell name>>]  [-h]
+B<backup deld> B<-d> <I<dump level name>> [B<-l>] [B<-c> <I<cell name>>]
+    [B<-h>]
 
 =head1 DESCRIPTION
 
-The backup deldump command deletes the indicated dump level and
-all of its child dump levels from the dump hierarchy in the Backup
-Database. Use the B<backup listdumps> command to display the
-dump hierarchy.
+The B<backup deldump> command deletes the indicated dump level and all of
+its child dump levels from the dump hierarchy in the Backup Database. Use
+the B<backup listdumps> command to display the dump hierarchy.
 
 =head1 OPTIONS
 
 =over 4
 
-=item -dump
+=item B<-dump> <I<dump level name>>
 
 Specifies the complete pathname of the dump level to delete.
 
-=item -localauth
+=item B<-localauth>
 
 Constructs a server ticket using a key from the local
-B</usr/afs/etc/KeyFile> file. The B<backup> command
-interpreter presents it to the Backup Server, Volume Server and VL Server
-during mutual authentication. Do not combine this flag with the
-B<-cell> argument. For more details, see the introductory
-B<backup> reference page.
+F</usr/afs/etc/KeyFile> file. The B<backup> command interpreter presents
+it to the Backup Server, Volume Server and VL Server during mutual
+authentication. Do not combine this flag with the B<-cell> argument. For
+more details, see L<backup(8)>.
 
-=item -cell
+=item B<-cell> <I<cell name>>
 
-Names the cell in which to run the command. Do not combine this
-argument with the B<-localauth> flag. For more details, see the
-introductory B<backup> reference page.
+Names the cell in which to run the command. Do not combine this argument
+with the B<-localauth> flag. For more details, see L<backup(8)>.
 
-=item -help
+=item B<-help>
 
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
 
 =back
 
 =head1 EXAMPLES
 
-The following command deletes the dump level /sunday1/monday1
-from the dump hierarchy, along with any of its child dump levels.
+The following command deletes the dump level C</sunday1/monday1> from the
+dump hierarchy, along with any of its child dump levels.
 
    % backup deldump /sunday1/monday1
 
 =head1 PRIVILEGE REQUIRED
 
-The issuer must be listed in the /usr/afs/etc/UserList file on
-every machine where the Backup Server is running, or must be logged onto a
-server machine as the local superuser B<root> if the
-B<-localauth> flag is included.
+The issuer must be listed in the F</usr/afs/etc/UserList> file on every
+machine where the Backup Server is running, or must be logged onto a
+server machine as the local superuser C<root> if the B<-localauth> flag is
+included.
 
 =head1 SEE ALSO
 
-L<backup(1)>,
-L<backup_adddump(1)>,
-L<backup_listdumps(1)>
+L<backup(8)>,
+L<backup_adddump(8)>,
+L<backup_listdumps(8)>
 
 =head1 COPYRIGHT
 
index ba196d6..e7a1c3a 100644 (file)
@@ -4,19 +4,20 @@ backup deletedump - Deletes one or more dump records from the Backup Database
 
 =head1 SYNOPSIS
 
-B<backup deletedump> [B<-dumpid> <I<dump id>>+]  [B<-from> <I<date time>>+]  [-to <I<date time>>+]
-[B<-localauth>]  [B<-cell> <I<cell name>>]  [B<-help>]
+B<backup deletedump> [B<-dumpid> <I<dump id>>+] [B<-from> <I<date time>>+]
+    [B<-to> <I<date time>>+] [B<-localauth>] [B<-cell> <I<cell name>>]
+    [B<-help>]
 
-B<backup dele> [B<-d> <I<dump id>>+]  [B<-f> <I<date time>>+]  [-t <I<date time>>+]
-[B<-l>]  [B<-c> <I<cell name>>]  [B<-h>]
+B<backup dele> [B<-d> <I<dump id>>+] [B<-f> <I<date time>>+]
+    [-t <I<date time>>+] [B<-l>] [B<-c> <I<cell name>>] [B<-h>]
 
 =head1 DESCRIPTION
 
-The backup deletedump command deletes one or more dump records
-from the Backup Database. Either use the B<-dumpid> argument to
-specify the dump ID number of one or more dumps, or use the B<-from>
-and B<-to> arguments to delete the records for all regular dumps
-created during the time period bracketed by the specified values.
+The B<backup deletedump> command deletes one or more dump records from the
+Backup Database. Either use the B<-dumpid> argument to specify the dump ID
+number of one or more dumps, or use the B<-from> and B<-to> arguments to
+delete the records for all regular dumps created during the time period
+bracketed by the specified values.
 
 Use this command to remove dump records that are incorrect (possibly
 because a dump operation was interrupted or failed), or that correspond to
@@ -25,111 +26,104 @@ dumps that are expired or otherwise no longer needed.
 =head1 CAUTIONS
 
 The only way to remove the dump record for an appended dump is to remove
-the record for its initial dump, and doing so removes the records for all of
-the initial dump's associated appended dumps.
+the record for its initial dump, and doing so removes the records for all
+of the initial dump's associated appended dumps.
 
 The only way to remove the record for a Backup Database dump (created with
-the B<backup savedb> command) is to specify its dump ID number with
-the B<-dumpid> argument. Using the B<-from> and
-B<-to> arguments never removes database dump records.
+the B<backup savedb> command) is to specify its dump ID number with the
+B<-dumpid> argument. Using the B<-from> and B<-to> arguments never removes
+database dump records.
 
 Removing records of a dump makes it impossible to restore data from the
-corresponding tapes or from any dump that refers to the deleted dump as its
-parent, directly or indirectly. That is, restore operations must begin
+corresponding tapes or from any dump that refers to the deleted dump as
+its parent, directly or indirectly. That is, restore operations must begin
 with the full dump and continue with each incremental dump in order. If
 the records for a specific dump are removed, it is not possible to restore
-data from later incremental dumps unless the deleted records are restored by
-running the B<backup scantape> command with the B<-dbadd>
-flag.
+data from later incremental dumps unless the deleted records are restored
+by running the B<backup scantape> command with the B<-dbadd> flag.
 
 If a dump set contains any dumps that were created outside the time range
-specified by the B<-from> and B<-to> arguments, the command
-does not delete any of the records associated with the dump set, even if some
-of them represent dumps created during the time range.
+specified by the B<-from> and B<-to> arguments, the command does not
+delete any of the records associated with the dump set, even if some of
+them represent dumps created during the time range.
 
 =head1 OPTIONS
 
 =over 4
 
-=item -dumpid
+=item B<-dumpid> <I<dump id>>+
 
-Specifies the dump ID of each dump record to delete. The
-corresponding dumps must be initial dumps; it is not possible to delete
-appended dump records directly, but only by deleting the record of their
-associated initial dump. Using this argument is the only way to delete
-records of Backup Database dumps (created with the B<backup savedb>
-command).
+Specifies the dump ID of each dump record to delete. The corresponding
+dumps must be initial dumps; it is not possible to delete appended dump
+records directly, but only by deleting the record of their associated
+initial dump. Using this argument is the only way to delete records of
+Backup Database dumps (created with the B<backup savedb> command).
 
-Provide either this argument or the -to (and optionally
-B<-from>) argument.
+Provide either this argument or the B<-to> (and optionally B<-from>)
+argument.
 
-=item -from
+=item B<-from> <I<date time>>+
 
 Specifies the beginning of a range of dates; the record for any dump
 created during the indicated period of time is deleted.
 
-Omit this argument to indicate the default of midnight (00:00 hours)
-on 1 January 1970 (UNIX time zero), or provide a date value in the format
-I<mm/dd/yyyy> [I<hh:MM>]. The month (I<mm>),
-day (I<dd>), and year (I<yyyy>) are required. The hour and
-minutes (I<hh>:I<MM>) are optional, but if provided must be
-in 24-hour format (for example, the value B<14:36> represents
-2:36 p.m.). If omitted, the time defaults to
-midnight (00:00 hours).
+Omit this argument to indicate the default of midnight (00:00 hours) on 1
+January 1970 (UNIX time zero), or provide a date value in the format
+I<mm/dd/yyyy> [I<hh:MM>]. The month (I<mm>), day (I<dd>), and year
+(I<yyyy>) are required. The hour and minutes (I<hh:MM>) are optional, but
+if provided must be in 24-hour format (for example, the value C<14:36>
+represents 2:36 p.m.). If omitted, the time defaults to midnight (00:00
+hours).
 
-The -to argument must be provided along with this one.
+The B<-to> argument must be provided along with this one.
 
-=item -to
+=item B<-to> <I<date time>>+
 
 Specifies the end of a range of dates; the record of any dump created
 during the range is deleted from the Backup Database.
 
-Provide either the value NOW to indicate the current date and
-time, or a date value in the same format as for the B<-from>
-argument. Valid values for the year (I<yyyy>) range from
-B<1970> to B<2037>; higher values are not valid because
-the latest possible date in the standard UNIX representation is in February
-2038. The command interpreter automatically reduces any later date to
-the maximum value.
-
-If the time portion (I<hh:MM>) is omitted, it defaults to 59
-seconds after midnight (00:00:59 hours). Similarly, the
-B<backup> command interpreter automatically adds 59 seconds to any
-time value provided. In both cases, adding 59 seconds compensates for
-how the Backup Database and B<backup dumpinfo> command represent dump
-creation times in hours and minutes only. For example, the Database
-records a creation timestamp of C<20:55> for any dump operation
-that begins between 20:55:00 and 20:55:59.
-Automatically adding 59 seconds to a time thus includes the records for all
-dumps created during that minute.
-
-Provide either this argument, or the -dumpid argument.
-This argument is required if the B<-from> argument is provided.
-
-B<Caution:> Specifying the value NOW for this
-argument when the B<-from> argument is omitted deletes all dump
-records from the Backup Database (except for Backup Database dump records
-created with the B<backup savedb> command).
-
-=item -localauth
+Provide either the value C<NOW> to indicate the current date and time, or
+a date value in the same format as for the B<-from> argument. Valid values
+for the year (I<yyyy>) range from C<1970> to C<2037>; higher values are
+not valid because the latest possible date in the standard UNIX
+representation is in February 2038. The command interpreter automatically
+reduces any later date to the maximum value.
+
+If the time portion (I<hh:MM>) is omitted, it defaults to 59 seconds after
+midnight (00:00:59 hours). Similarly, the B<backup> command interpreter
+automatically adds 59 seconds to any time value provided. In both cases,
+adding 59 seconds compensates for how the Backup Database and B<backup
+dumpinfo> command represent dump creation times in hours and minutes
+only. For example, the Database records a creation timestamp of C<20:55>
+for any dump operation that begins between 20:55:00 and 20:55:59.
+Automatically adding 59 seconds to a time thus includes the records for
+all dumps created during that minute.
+
+Provide either this argument, or the B<-dumpid> argument.  This argument
+is required if the B<-from> argument is provided.
+
+B<Caution:> Specifying the value C<NOW> for this argument when the
+B<-from> argument is omitted deletes all dump records from the Backup
+Database (except for Backup Database dump records created with the
+B<backup savedb> command).
+
+=item B<-localauth>
 
 Constructs a server ticket using a key from the local
-B</usr/afs/etc/KeyFile> file. The B<backup> command
-interpreter presents it to the Backup Server, Volume Server and VL Server
-during mutual authentication. Do not combine this flag with the
-B<-cell> argument. For more details, see the introductory
-B<backup> reference page.
+F</usr/afs/etc/KeyFile> file. The B<backup> command interpreter presents
+it to the Backup Server, Volume Server and VL Server during mutual
+authentication. Do not combine this flag with the B<-cell> argument. For
+more details, see L<backup(8)>.
 
-=item -cell
+=item B<-cell> <I<cell name>>
 
-Names the cell in which to run the command. Do not combine this
-argument with the B<-localauth> flag. For more details, see the
-introductory B<backup> reference page.
+Names the cell in which to run the command. Do not combine this argument
+with the B<-localauth> flag. For more details, see L<backup(8)>.
 
-=item -help
+=item B<-help>
 
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
 
 =back
 
@@ -139,9 +133,9 @@ At the conclusion of processing, the output lists the dump IDs of all dump
 records deleted in the following format:
 
    The following dumps were deleted:
-        I<dump ID 1>
-        I<dump ID 2>
-        I<etc.>
+        dump ID 1
+        dump ID 2
+        etc.
 
 =head1 EXAMPLES
 
@@ -153,8 +147,8 @@ for any appended dumps associated with it:
         653777462
 
 The following command deletes the Backup Database record of all dumps
-created between midnight on 1 January 1997 and 23:59:59 hours on
-31 December 1997:
+created between midnight on 1 January 1997 and 23:59:59 hours on 31
+December 1997:
 
    % backup deletedump -from 01/01/1997 -to 12/31/1997
    The following dumps were deleted:
@@ -167,16 +161,16 @@ created between midnight on 1 January 1997 and 23:59:59 hours on
 
 =head1 PRIVILEGE REQUIRED
 
-The issuer must be listed in the /usr/afs/etc/UserList file on
-every machine where the Backup Server is running, or must be logged onto a
-server machine as the local superuser B<root> if the
-B<-localauth> flag is included.
+The issuer must be listed in the F</usr/afs/etc/UserList> file on every
+machine where the Backup Server is running, or must be logged onto a
+server machine as the local superuser C<root> if the B<-localauth> flag is
+included.
 
 =head1 SEE ALSO
 
-L<backup(1)>,
-L<backup_dumpinfo(1)>,
-L<backup_scantape(1)>
+L<backup(8)>,
+L<backup_dumpinfo(8)>,
+L<backup_scantape(8)>
 
 =head1 COPYRIGHT
 
index 4aaa854..35a569a 100644 (file)
@@ -4,20 +4,21 @@ backup delhost - Deletes a Tape Coordinator entry from the Backup Database
 
 =head1 SYNOPSIS
 
-B<backup delhost -tapehost> <I<tape machine name>> [-portoffset <I<TC port offset>>]
-[B<-localauth>]  [B<-cell> <I<cell name>>]  [B<-help>]
+B<backup delhost> B<-tapehost> <I<tape machine name>>
+    [B<-portoffset> <I<TC port offset>>] [B<-localauth>]
+    [B<-cell> <I<cell name>>] [B<-help>]
 
-B<backup delh -t> <I<tape machine name>>  [-p <I<TC port offset>>]
-[B<-l>]  [B<-c> <I<cell name>>]  [B<-h>]
+B<backup delh> B<-t> <I<tape machine name>> [B<-p> <I<TC port offset>>]
+    [B<-l>] [B<-c> <I<cell name>>] [B<-h>]
 
 =head1 DESCRIPTION
 
-The backup delhost command deletes the indicated Tape
-Coordinator entry from the Backup Database. It is then impossible to
-submit backup operations to that Tape Coordinator, even if it is still
-running. To keep configuration information consistent, also remove the
-corresponding entry from the B</usr/afs/backup/tapeconfig> file on the
-Tape Coordinator machine.
+The B<backup delhost> command deletes the indicated Tape Coordinator entry
+from the Backup Database. It is then impossible to submit backup
+operations to that Tape Coordinator, even if it is still running. To keep
+configuration information consistent, also remove the corresponding entry
+from the F</usr/afs/backup/tapeconfig> file on the Tape Coordinator
+machine.
 
 To list the Tape Coordinator machines and port offsets defined in the
 Backup Database, issue the B<backup listhosts> command.
@@ -26,39 +27,37 @@ Backup Database, issue the B<backup listhosts> command.
 
 =over 4
 
-=item -tapehost
+=item B<-tapehost> <I<tape machine name>>
 
 Specifies the hostname of the machine housing the Tape Coordinator to
 delete.
 
-=item -portoffset
+=item B<-portoffset> <I<TC port offset>>
 
-Specifies the port offset number of the Tape Coordinator to delete.
-If omitted, it defaults to B<0>. If provided, it is an integer
-between B<0> (zero) and B<58510>, and must match the port
-offset number assigned to the same combination of Tape Coordinator and tape
-device or file in the B</usr/afs/backup/tapeconfig> file on the Tape
-Coordinator machine indicated by the B<-tapehost> argument.
+Specifies the port offset number of the Tape Coordinator to delete.  If
+omitted, it defaults to C<0>. If provided, it is an integer between C<0>
+(zero) and C<58510>, and must match the port offset number assigned to the
+same combination of Tape Coordinator and tape device or file in the
+F</usr/afs/backup/tapeconfig> file on the Tape Coordinator machine
+indicated by the B<-tapehost> argument.
 
-=item -localauth
+=item B<-localauth>
 
 Constructs a server ticket using a key from the local
-B</usr/afs/etc/KeyFile> file. The B<backup> command
-interpreter presents it to the Backup Server, Volume Server and VL Server
-during mutual authentication. Do not combine this flag with the
-B<-cell> argument. For more details, see the introductory
-B<backup> reference page.
+F</usr/afs/etc/KeyFile> file. The B<backup> command interpreter presents
+it to the Backup Server, Volume Server and VL Server during mutual
+authentication. Do not combine this flag with the B<-cell> argument. For
+more details, see L<backup(8)>.
 
-=item -cell
+=item B<-cell> <I<cell name>>
 
-Names the cell in which to run the command. Do not combine this
-argument with the B<-localauth> flag. For more details, see the
-introductory B<backup> reference page.
+Names the cell in which to run the command. Do not combine this argument
+with the B<-localauth> flag. For more details, see L<backup(8)>.
 
-=item -help
+=item B<-help>
 
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
 
 =back
 
@@ -66,22 +65,22 @@ are ignored.
 
 The following command deletes the Backup Database entry for the Tape
 Coordinator with port offset 2 on the Tape Coordinator machine
-B<backup3.abc.com>:
+C<backup3.abc.com>:
 
    % backup delhost -tapehost backup3.abc.com -portoffset 2
 
 =head1 PRIVILEGE REQUIRED
 
-The issuer must be listed in the /usr/afs/etc/UserList file on
-every machine where the Backup Server is running, or must be logged onto a
-server machine as the local superuser B<root> if the
-B<-localauth> flag is included.
+The issuer must be listed in the F</usr/afs/etc/UserList> file on every
+machine where the Backup Server is running, or must be logged onto a
+server machine as the local superuser C<root> if the B<-localauth> flag is
+included.
 
 =head1 SEE ALSO
 
-L<backup(1)>,
-L<backup_addhost(1)>,
-L<backup_listhosts(1)>
+L<backup(8)>,
+L<backup_addhost(8)>,
+L<backup_listhosts(8)>
 
 =head1 COPYRIGHT
 
index d7ad003..bdc344c 100644 (file)
@@ -4,86 +4,84 @@ backup delvolentry - Deletes a volume entry from a volume set
 
 =head1 SYNOPSIS
 
-B<backup delvolentry -name> <I<volume set name>>  -entry <I<volume set index>> 
-[B<-localauth>]  [B<-cell> <I<cell name>>]  [B<-help>]
+B<backup delvolentry> B<-name> <I<volume set name>>
+    B<-entry> <I<volume set index>> [B<-localauth>]
+    [B<-cell> <I<cell name>>] [B<-help>]
 
-B<backup delvole  -n> <I<volume set name>>  -e <I<volume set index>>
-[B<-l>]  [B<-c> <I<cell name>>]  [B<-h>]
+B<backup delvole> B<-n> <I<volume set name>> B<-e> <I<volume set index>>
+    [B<-l>] [B<-c> <I<cell name>>] [B<-h>]
 
 =head1 DESCRIPTION
 
-The backup delvolentry command deletes the indicated volume
-entry from the volume set specified with the B<-name> argument.
-Use the B<-entry> argument to identify the volume entry by its index
-number. To display the index numbers, use the B<backup
-listvolsets> command.
+The B<backup delvolentry> command deletes the indicated volume entry from
+the volume set specified with the B<-name> argument.  Use the B<-entry>
+argument to identify the volume entry by its index number. To display the
+index numbers, use the B<backup listvolsets> command.
 
 If there are any remaining volume entries with index numbers higher than
-the deleted entry, their indexes are automatically decremented to eliminate
-any gaps in the indexing sequence.
+the deleted entry, their indexes are automatically decremented to
+eliminate any gaps in the indexing sequence.
 
 =head1 CAUTIONS
 
-Deleting volume entries from a temporary volume set is possible only within
-the interactive session in which the volume set was created.
+Deleting volume entries from a temporary volume set is possible only
+within the interactive session in which the volume set was created.
 
 =head1 OPTIONS
 
 =over 4
 
-=item -name
+=item B<-name> <I<volume set name>>
 
 Names the volume set from which to delete a volume entry.
 
-=item -entry
+=item B<-entry> <I<volume set index>>
 
-Specifies the index number of the volume entry to delete. Use the
-B<backup listvolsets> command to display the index numbers for a
-volume set's volume entries.
+Specifies the index number of the volume entry to delete. Use the B<backup
+listvolsets> command to display the index numbers for a volume set's
+volume entries.
 
-=item -localauth
+=item B<-localauth>
 
 Constructs a server ticket using a key from the local
-B</usr/afs/etc/KeyFile> file. The B<backup> command
-interpreter presents it to the Backup Server, Volume Server and VL Server
-during mutual authentication. Do not combine this flag with the
-B<-cell> argument. For more details, see the introductory
-B<backup> reference page.
+F</usr/afs/etc/KeyFile> file. The B<backup> command interpreter presents
+it to the Backup Server, Volume Server and VL Server during mutual
+authentication. Do not combine this flag with the B<-cell> argument. For
+more details, see L<backup(8)>.
 
-=item -cell
+=item B<-cell> <I<cell name>>
 
-Names the cell in which to run the command. Do not combine this
-argument with the B<-localauth> flag. For more details, see the
-introductory B<backup> reference page.
+Names the cell in which to run the command. Do not combine this argument
+with the B<-localauth> flag. For more details, see L<backup(8)>.
 
-=item -help
+=item B<-help>
 
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
 
 =back
 
 =head1 EXAMPLES
 
 The following command deletes the fourth volume entry from the volume set
-called B<sys>:
+called C<sys>:
 
    % backup delvolentry -name sys -entry 4
 
 =head1 PRIVILEGE REQUIRED
 
-The issuer must be listed in the /usr/afs/etc/UserList file on
-every machine where the Backup Server is running, or must be logged onto a
-server machine as the local superuser B<root> if the
-B<-localauth> flag is included.
+The issuer must be listed in the F</usr/afs/etc/UserList> file on every
+machine where the Backup Server is running, or must be logged onto a
+server machine as the local superuser C<root> if the B<-localauth> flag is
+included.
 
 =head1 SEE ALSO
 
-L<backup(1)>,
-L<backup_addvolentry(1)>,
-L<backup_addvolset(1)>,
-L<backup_delvolset(1)>,
-L<backup_listvolsets(1)>
+L<backup(8)>,
+L<backup_addvolentry(8)>,
+L<backup_addvolset(8)>,
+L<backup_delvolset(8)>,
+L<backup_listvolsets(8)>
 
 =head1 COPYRIGHT
 
index 9cc0625..77a5c7f 100644 (file)
@@ -4,18 +4,18 @@ backup delvolset - Deletes one or more volume sets from the Backup Database
 
 =head1 SYNOPSIS
 
-backup delvolset -name <I<volume set name>>+
-[B<-localauth>]  [B<-cell> <I<cell name>>]  [B<-help>]
+B<backup delvolset> B<-name> <I<volume set name>>+ [B<-localauth>]
+    [B<-cell> <I<cell name>>] [B<-help>]
 
-B<backup delvols -n> <I<volume set name>>+  [B<-l>]  [B<-c> <I<cell name>>]  [-h]
+B<backup delvols> B<-n> <I<volume set name>>+ [B<-l>]
+    [B<-c> <I<cell name>>] [B<-h>]
 
 =head1 DESCRIPTION
 
-The backup delvolset command deletes each volume set named by
-the B<-name> argument, and the volume entries each contains, from the
-Backup Database. The B<backup listvolsets> command lists the
-volume sets (and their volume entries) currently defined in the Backup
-Database.
+The B<backup delvolset> command deletes each volume set named by the
+B<-name> argument, and the volume entries each contains, from the Backup
+Database. The B<backup listvolsets> command lists the volume sets (and
+their volume entries) currently defined in the Backup Database.
 
 =head1 CAUTIONS
 
@@ -27,53 +27,51 @@ destroys the temporary volume set automatically.
 
 =over 4
 
-=item -name
+=item B<-name> <I<volume set name>>+
 
 Names each volume set to delete.
 
-=item -localauth
+=item B<-localauth>
 
 Constructs a server ticket using a key from the local
-B</usr/afs/etc/KeyFile> file. The B<backup> command
-interpreter presents it to the Backup Server, Volume Server and VL Server
-during mutual authentication. Do not combine this flag with the
-B<-cell> argument. For more details, see the introductory
-B<backup> reference page.
+F</usr/afs/etc/KeyFile> file. The B<backup> command interpreter presents
+it to the Backup Server, Volume Server and VL Server during mutual
+authentication. Do not combine this flag with the B<-cell> argument. For
+more details, see L<backup(8)>.
 
-=item -cell
+=item B<-cell> <I<cell name>>
 
-Names the cell in which to run the command. Do not combine this
-argument with the B<-localauth> flag. For more details, see the
-introductory B<backup> reference page.
+Names the cell in which to run the command. Do not combine this argument
+with the B<-localauth> flag. For more details, see L<backup(8)>.
 
-=item -help
+=item B<-help>
 
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
 
 =back
 
 =head1 EXAMPLES
 
-The following command deletes the volume set called user and all
-volume entries in it:
+The following command deletes the volume set called user and all volume
+entries in it:
 
    % backup delvolset user
 
 =head1 PRIVILEGE REQUIRED
 
-The issuer must be listed in the /usr/afs/etc/UserList file on
-every machine where the Backup Server is running, or must be logged onto a
-server machine as the local superuser B<root> if the
-B<-localauth> flag is included.
+The issuer must be listed in the F</usr/afs/etc/UserList> file on every
+machine where the Backup Server is running, or must be logged onto a
+server machine as the local superuser C<root> if the B<-localauth> flag is
+included.
 
 =head1 SEE ALSO
 
-L<backup(1)>,
-L<backup_addvolentry(1)>,
-L<backup_addvolset(1)>,
-L<backup_delvolentry(1)>,
-L<backup_listvolsets(1)>
+L<backup(8)>,
+L<backup_addvolentry(8)>,
+L<backup_addvolset(8)>,
+L<backup_delvolentry(8)>,
+L<backup_listvolsets(8)>
 
 =head1 COPYRIGHT
 
index 1e14ada..e59e6e8 100644 (file)
@@ -4,70 +4,67 @@ backup diskrestore - Restores the entire contents of a partition
 
 =head1 SYNOPSIS
 
-backup diskrestore -server <I<machine to restore>> 
-B<-partition> <I<partition to restore>>
-                   [-portoffset <I<TC port offset>>+]  
-                   [-newserver <I<destination machine>>]
-                   [-newpartition <I<destination partition>>]
-                   [-extension <I<new volume name extension>>]
-                   [B<-n>]  [B<-localauth>]  [B<-cell> <I<cell name>>]  [-help]
-
-B<backup di -s> <I<machine to restore>> -pa <I<partition to restore>>
-[B<-po> <I<TC port offset>>+]  [B<-news> <I<destination machine>>]
-          [B<-newp> <I<destination partition>>]  [-e <I<new volume name extension>>]
-          [B<-n>]  [B<-l>]  [B<-c> <I<cell name>>]  [-h]
+B<backup diskrestore> B<-server> <I<machine to restore>> 
+    B<-partition> <I<partition to restore>>
+    [B<-portoffset> <I<TC port offset>>+]  
+    [B<-newserver> <I<destination machine>>]
+    [B<-newpartition> <I<destination partition>>]
+    [B<-extension> <I<new volume name extension>>]
+    [B<-n>] [B<-localauth>] [B<-cell> <I<cell name>>] [B<-help>]
+
+B<backup di> B<-s> <I<machine to restore>> B<-pa> <I<partition to restore>>
+    [B<-po> <I<TC port offset>>+] [B<-news> <I<destination machine>>]
+    [B<-newp> <I<destination partition>>]
+    [B<-e> <I<new volume name extension>>] [B<-n>] [B<-l>]
+    [B<-c> <I<cell name>>] [B<-h>]
 
 =head1 DESCRIPTION
 
-The backup diskrestore command restores all of the volumes for
-which the Volume Location Database (VLDB) lists a read/write site on the
-partition specified with the B<-server> and B<-partition>
-arguments. It is useful if a disk or machine failure corrupts or
-destroys the data on an entire partition. (To restore any read-only or
-backup volumes that resided on the partition, use the B<vos release>
-and B<vos backup> commands, respectively, after restoring the
-read/write version.)
+The B<backup diskrestore> command restores all of the volumes for which
+the Volume Location Database (VLDB) lists a read/write site on the
+partition specified with the B<-server> and B<-partition> arguments. It is
+useful if a disk or machine failure corrupts or destroys the data on an
+entire partition. (To restore any read-only or backup volumes that resided
+on the partition, use the B<vos release> and B<vos backup> commands,
+respectively, after restoring the read/write version.)
 
 If restoring only selected volumes to a single site, it is usually more
-efficient to use the B<backup volrestore> command. To restore
-multiple volumes to many different sites, use the B<backup
-volsetrestore> command.
-
-(If the FILE YES instruction appears in the
-B</usr/afs/backup/CFG_>I<device_name> file on the Tape
-Coordinator machine associated with the specified port offset, then the Backup
-System restores data from the backup data file listed for that port offset in
-the Tape Coordinator's B</usr/afs/backup/tapeconfig> file,
-instead of from tape. For the sake of clarity, the following text
-refers to tapes only, but the Backup System handles backup data files in much
-the same way.)
+efficient to use the B<backup volrestore> command. To restore multiple
+volumes to many different sites, use the B<backup volsetrestore> command.
+
+(If the C<FILE YES> instruction appears in the
+F</usr/afs/backup/CFG_I<device_name>> file on the Tape Coordinator machine
+associated with the specified port offset, then the Backup System restores
+data from the backup data file listed for that port offset in the Tape
+Coordinator's F</usr/afs/backup/tapeconfig> file, instead of from
+tape. For the sake of clarity, the following text refers to tapes only,
+but the Backup System handles backup data files in much the same way.)
 
 The Backup System determines whether the read/write or backup version of
-each volume was dumped more recently, and restores the dumps of that version,
-starting with the most recent full dump. It resets the creation
+each volume was dumped more recently, and restores the dumps of that
+version, starting with the most recent full dump. It resets the creation
 timestamp of each restored volume to the date and time at which it begins
-restoring the volume (the creation timestamp appears in the
-C<Creation> field of the output from the B<vos examine> and
-B<vos listvol> commands).
+restoring the volume (the creation timestamp appears in the C<Creation>
+field of the output from the B<vos examine> and B<vos listvol> commands).
 
 If all of the full and incremental dumps of all relevant volumes were not
 written on compatible tape devices, use the B<-portoffset> argument to
-list multiple port offset numbers in the order in which the tapes are needed
-(first list the port offset for the full dump, second the port offset for the
-level 1 incremental dump, and so on). This implies that the full dumps
-of all relevant volumes must have been written to a type of tape that the
-first Tape Coordinator can read, the level 1 incremental dumps to a type of
-tape the second Tape Coordinator can read, and so on. If dumps are on
-multiple incompatible tape types, use the B<backup volrestore> command
-to restore individual volumes, or the B<backup volsetrestore> command
-after defining groups of volumes that were dumped to compatible tape
-types. For further discussion, see the I<IBM AFS Administration
-Guide>.
+list multiple port offset numbers in the order in which the tapes are
+needed (first list the port offset for the full dump, second the port
+offset for the level 1 incremental dump, and so on). This implies that the
+full dumps of all relevant volumes must have been written to a type of
+tape that the first Tape Coordinator can read, the level 1 incremental
+dumps to a type of tape the second Tape Coordinator can read, and so
+on. If dumps are on multiple incompatible tape types, use the B<backup
+volrestore> command to restore individual volumes, or the B<backup
+volsetrestore> command after defining groups of volumes that were dumped
+to compatible tape types. For further discussion, see the I<IBM AFS
+Administration Guide>.
 
 By default, the Backup System restores the contents of the specified
-partition to that same partition. To restore the contents to an
-alternate site, combine the following options as indicated. The Backup
-System removes each volume from the original site, if it still exists, and
+partition to that same partition. To restore the contents to an alternate
+site, combine the following options as indicated. The Backup System
+removes each volume from the original site, if it still exists, and
 records the change of site in the VLDB.
 
 =over 4
@@ -77,134 +74,125 @@ records the change of site in the VLDB.
 To restore to a different partition on the same file server machine,
 provide the B<-newpartition> argument.
 
-
 =item *
 
 To restore to the partition with the same name on a different file server
 machine, provide the B<-newserver> argument.
 
-
 =item *
 
-To restore to a completely different site, combine the
-B<-newserver> and B<-newpartition> arguments.
-
+To restore to a completely different site, combine the B<-newserver> and
+B<-newpartition> arguments.
 
 =back
 
 By default, the Backup System overwrites the contents of existing volumes
-with the restored data. To create a new volume to house the restored
-data instead, use the B<-extension> argument. The Backup System
-creates the new volume at the site designated by the B<-newserver> and
-B<-newpartition> arguments if they are used or the B<-server>
-and B<-partition> arguments otherwise. It derives the volume
-name by adding the extension to the read/write base name listed in the VLDB,
-and creates a new VLDB entry. The command does not affect the existing
-volume in any way. However, if a volume with the specified extension
-also already exists, the command overwrites it.
+with the restored data. To create a new volume to house the restored data
+instead, use the B<-extension> argument. The Backup System creates the new
+volume at the site designated by the B<-newserver> and B<-newpartition>
+arguments if they are used or the B<-server> and B<-partition> arguments
+otherwise. It derives the volume name by adding the extension to the
+read/write base name listed in the VLDB, and creates a new VLDB entry. The
+command does not affect the existing volume in any way. However, if a
+volume with the specified extension also already exists, the command
+overwrites it.
 
 To print out a list of the tapes containing the needed dumps, without
-actually performing the restore operation, include the B<-n> flag
-along with the other options to be used on the actual command.
-
-The Tape Coordinator's default response to this command is to access
-the first tape it needs by invoking the B<MOUNT> instruction in the
-local B<CFG_>I<device_name> file, or by prompting the backup
-operator to insert the tape if there is no B<MOUNT>
-instruction. However, if the B<AUTOQUERY NO> instruction
-appears in the B<CFG_>I<device_name> file, or if the issuer of
-the B<butc> command included the B<-noautoquery> flag, the
-Tape Coordinator instead expects the tape to be in the device already.
-If it is not, or is the wrong tape, the Tape Coordinator invokes the
-B<MOUNT> instruction or prompts the operator. It also invokes
-the B<MOUNT> instruction or prompts for any additional tapes needed to
-complete the restore operation; the backup operator must arrange to
-provide them.
+actually performing the restore operation, include the B<-n> flag along
+with the other options to be used on the actual command.
+
+The Tape Coordinator's default response to this command is to access the
+first tape it needs by invoking the C<MOUNT> instruction in the local
+F<CFG_I<device_name>> file, or by prompting the backup operator to insert
+the tape if there is no C<MOUNT> instruction. However, if the C<AUTOQUERY
+NO> instruction appears in the F<CFG_I<device_name>> file, or if the
+issuer of the B<butc> command included the B<-noautoquery> flag, the Tape
+Coordinator instead expects the tape to be in the device already.  If it
+is not, or is the wrong tape, the Tape Coordinator invokes the C<MOUNT>
+instruction or prompts the operator. It also invokes the C<MOUNT>
+instruction or prompts for any additional tapes needed to complete the
+restore operation; the backup operator must arrange to provide them.
 
 =head1 CAUTIONS
 
-If issuing this command to recover data after a disk crash or other damage,
-be sure not to issue the B<vos syncserv> command first. Doing
-so destroys the VLDB record of the volumes that resided on the
-partition.
+If issuing this command to recover data after a disk crash or other
+damage, be sure not to issue the B<vos syncserv> command first. Doing so
+destroys the VLDB record of the volumes that resided on the partition.
 
 =head1 OPTIONS
 
 =over 4
 
-=item -server
+=item B<-server> <I<machine to restore>>
 
 Names the file server machine that the VLDB lists as the site of the
 volumes that need to be restored.
 
-=item -partition
+=item B<-partition> <I<partition to restore>>
 
 Names the partition that the VLDB lists as the site of the volumes that
 need to be restored.
 
-=item -portoffset
+=item B<-portoffset> <I<TC port offset>>+
 
 Specifies one or more port offset numbers (up to a maximum of 128), each
-corresponding to a Tape Coordinator to use in the operation. If there
-is more than one value, the Backup System uses the first one when restoring
+corresponding to a Tape Coordinator to use in the operation. If there is
+more than one value, the Backup System uses the first one when restoring
 the full dump of each volume, the second one when restoring the level 1
-incremental dump of each volume, and so on. It uses the final value in
-the list when restoring dumps at the corresponding depth in the dump hierarchy
+incremental dump of each volume, and so on. It uses the final value in the
+list when restoring dumps at the corresponding depth in the dump hierarchy
 and at all lower levels.
 
 Provide this argument unless the default value of 0 (zero) is appropriate
-for all dumps. If B<0> is just one of the values in the list,
-provide it explicitly in the appropriate order.
+for all dumps. If C<0> is just one of the values in the list, provide it
+explicitly in the appropriate order.
 
-=item -newserver
+=item B<-newserver> <I<destination machine>>
 
-Names an alternate file server machine to which to restore the
-volumes. If this argument is omitted, the volumes are restored to the
-file server machine named by the B<-server> argument.
+Names an alternate file server machine to which to restore the volumes. If
+this argument is omitted, the volumes are restored to the file server
+machine named by the B<-server> argument.
 
-=item -newpartition
+=item B<-newpartition> <I<destination partition>>
 
 Names an alternate partition to which to restore the data. If this
-argument is omitted, the volumes are restored to the partition named by the
-B<-partition> argument.
+argument is omitted, the volumes are restored to the partition named by
+the B<-partition> argument.
 
-=item -extension
+=item B<-extension> <I<new volume name extension>>
 
 Creates a new volume for each volume being restored, to house the restored
-data. The Backup System derives the new volume's name by appending
-the specified string to the read/write base name listed in the VLDB, and
-creates a new VLDB volume entry. The Backup System preserves the
-contents of the volumes on the partition, if any still exist. Any
-string other than B<.readonly> or B<.backup> is
-acceptable, but the combination of the base name and extension cannot exceed
-22 characters in length. To use a period to separate the extension from
-the name, specify it as the first character of the string (as in
-B<.rst>, for example).
-
-=item -n
+data. The Backup System derives the new volume's name by appending the
+specified string to the read/write base name listed in the VLDB, and
+creates a new VLDB volume entry. The Backup System preserves the contents
+of the volumes on the partition, if any still exist. Any string other than
+C<.readonly> or C<.backup> is acceptable, but the combination of the base
+name and extension cannot exceed 22 characters in length. To use a period
+to separate the extension from the name, specify it as the first character
+of the string (as in C<.rst>, for example).
+
+=item B<-n>
 
 Displays a list of the tapes necessary to perform the requested restore,
 without actually performing the operation.
 
-=item -localauth
+=item B<-localauth>
 
 Constructs a server ticket using a key from the local
-B</usr/afs/etc/KeyFile> file. The B<backup> command
-interpreter presents it to the Backup Server, Volume Server and VL Server
-during mutual authentication. Do not combine this flag with the
-B<-cell> argument. For more details, see the introductory
-B<backup> reference page.
+F</usr/afs/etc/KeyFile> file. The B<backup> command interpreter presents
+it to the Backup Server, Volume Server and VL Server during mutual
+authentication. Do not combine this flag with the B<-cell> argument. For
+more details, see L<backup(8)>.
 
-=item -cell
+=item B<-cell> <I<cell name>>
 
-Names the cell in which to run the command. Do not combine this
-argument with the B<-localauth> flag. For more details, see the
-introductory B<backup> reference page.
+Names the cell in which to run the command. Do not combine this argument
+with the B<-localauth> flag. For more details, see L<backup(8)>.
 
-=item -help
+=item B<-help>
 
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
 
 =back
 
@@ -216,41 +204,39 @@ displays the following messages:
    Restore operation on volume I<name> failed due to tape error
    Do you want to continue (y/n)?
 
-where I<name> is the name of the volume that was being restored when
-the tape error occurred. Enter the value B<y> to continue the
-operation without restoring the indicated volume or the value B<n> to
-terminate the operation. In the latter case, the operator can then
-attempt to determine the cause of the tape error.
+where I<name> is the name of the volume that was being restored when the
+tape error occurred. Enter the value B<y> to continue the operation
+without restoring the indicated volume or the value C<n> to terminate the
+operation. In the latter case, the operator can then attempt to determine
+the cause of the tape error.
 
-If the issuer includes the -n flag with the command, the
-following string appears at the head of the list of the tapes necessary to
-perform the restore operation:
+If the issuer includes the B<-n> flag with the command, the following
+string appears at the head of the list of the tapes necessary to perform
+the restore operation:
 
    Tapes needed:
 
 =head1 EXAMPLES
 
 The following command restores the volumes for which the VLDB lists a
-read/write site on the B</vicepd> partition of the machine
-B<fs5.abc.com>. The Tape Coordinator associated
-with port offset 3 performs the operation.
+read/write site on the F</vicepd> partition of the machine
+C<fs5.abc.com>. The Tape Coordinator associated with port offset 3
+performs the operation.
 
    % backup diskrestore -server fs5.abc.com -partition /vicepd -portoffset 3
 
 The following command restores the volumes for which the VLDB lists a
-read/write site on the B</vicepb> partition of the machine
-B<fs1.abc.com> to a new site: the
-B</vicepa> partition on the machine
-B<fs3.abc.com>. The Tape Coordinator associated
-with port offset 0 performs the operation. (The command appears here on
-two lines only for legibility.)
+read/write site on the F</vicepb> partition of the machine C<fs1.abc.com>
+to a new site: the F</vicepa> partition on the machine C<fs3.abc.com>. The
+Tape Coordinator associated with port offset 0 performs the
+operation. (The command appears here on two lines only for legibility.)
 
    % backup diskrestore  -server fs1.abc.com -partition /vicepb   \
                          -newserver fs3.abc.com -newpartition /vicepa
 
 The following command lists the tapes required to restore the volumes for
-which the VLDB lists a read/write site on the B</vicepm> partition of
-the machine B<fs4.abc.com>:
+which the VLDB lists a read/write site on the F</vicepm> partition of the
+machine C<fs4.abc.com>:
 
    % backup diskrestore -server fs4.abc.com -partition /vicepm -n
    Tapes needed:
@@ -262,20 +248,19 @@ the machine B<fs4.abc.com>:
 
 =head1 PRIVILEGE REQUIRED
 
-The issuer must be listed in the /usr/afs/etc/UserList file on
-every machine where the Backup Server or Volume Location (VL) Server is
-running, and on every file server machine that houses an affected
-volume. If the B<-localauth> flag is included, the issuer must
-instead be logged on to a server machine as the local superuser
-B<root>.
+The issuer must be listed in the F</usr/afs/etc/UserList> file on every
+machine where the Backup Server or Volume Location (VL) Server is running,
+and on every file server machine that houses an affected volume. If the
+B<-localauth> flag is included, the issuer must instead be logged on to a
+server machine as the local superuser C<root>.
 
 =head1 SEE ALSO
 
-L<backup(1)>,
-L<backup_dump(1)>,
-L<backup_volrestore(1)>,
-L<backup_volsetrestore(1)>,
-L<butc(1)>,
+L<backup(8)>,
+L<backup_dump(8)>,
+L<backup_volrestore(8)>,
+L<backup_volsetrestore(8)>,
+L<butc(8)>,
 L<vos_backup(1)>,
 L<vos_examine(1)>,
 L<vos_listvol(1)>,
index 7ba8c62..617f516 100644 (file)
@@ -4,250 +4,238 @@ backup dump - Creates a dump (dumps a volume set at a particular dump level)
 
 =head1 SYNOPSIS
 
-B<backup dump> [B<-volumeset> <I<volume set name>>]  [-dump <I<dump level name>>]
-[B<-portoffset> <I<TC port offset>>]  [B<-at> <I<Date/time to start dump>>+]
-            [B<-append>]  [B<-n>]  [-file <I<load file>>]
-            [B<-localauth>]  [-B<cell> <I<cell name>>]  [-help]
+B<backup dump> [B<-volumeset> <I<volume set name>>]
+    [B<-dump> <I<dump level name>>] [B<-portoffset> <I<TC port offset>>]
+    [B<-at> <I<date/time to start dump>>+] [B<-append>] [B<-n>]
+    [B<-file> <I<load file>>] [B<-localauth>] [-B<cell> <I<cell name>>]
+    [B<-help>]
 
-B<backup dump> [B<-v> <I<volume set name>>]  [-d <I<dump level name>>]
-[B<-p> <I<TC port offset>>]  [B<-at> <I<Date/time to start dump>>+]
-            [B<-ap>]  [B<-n>]  [B<-f> <I<load file>>]  [B<-l>]  [B<-c> <I<cell name>>]  [-h]
+B<backup dump> [B<-v> <I<volume set name>>] [B<-d> <I<dump level name>>]
+    [B<-p> <I<TC port offset>>] [B<-at> <I<Date/time to start dump>>+]
+    [B<-ap>] [B<-n>] [B<-f> <I<load file>>] [B<-l>] [B<-c> <I<cell name>>]
+    [B<-h>]
 
 =head1 DESCRIPTION
 
-The backup dump command either dumps the volume set specified by
-the B<-volumeset> argument at the dump level specified by the
-B<-dump> argument and creates a Backup Database dump record about it,
-or executes the dump instructions listed in the file named by the
-B<-file> argument. The Tape Coordinator indicated by the
-B<-portoffset> argument (or on each command in the file) executes the
-operation.
-
-(If the FILE YES instruction appears in the
-B</usr/afs/backup/CFG_>I<device_name> file on the Tape
-Coordinator machine associated with the specified port offset, then the Backup
-System dumps data to the backup data file listed for that port offset in the
-Tape Coordinator's B</usr/afs/backup/tapeconfig> file, rather
-than to tape. For the sake of clarity, the following text refers to
-tapes only, but the Backup System handles backup data files in much the same
-way.)
-
-The term I<dumping> refers to copying a collection of data to tape
-or a backup data file, and the resulting collection is termed a
-I<dump>. The set of tapes that contain one or more dumps is
-called a I<dump set>. The first dump in a dump set is its
-I<initial dump>, and any dumps subsequently added to the dump set (by
-use of the B<-append> argument) are I<appended dumps>.
-Creating appended dumps is optional, and appended dumps can be of different
-volume sets, and at different dump levels, than the initial dump.
+The B<backup dump> command either dumps the volume set specified by the
+B<-volumeset> argument at the dump level specified by the B<-dump>
+argument and creates a Backup Database dump record about it, or executes
+the dump instructions listed in the file named by the B<-file>
+argument. The Tape Coordinator indicated by the B<-portoffset> argument
+(or on each command in the file) executes the operation.
+
+(If the C<FILE YES> instruction appears in the
+F</usr/afs/backup/CFG_I<device_name>> file on the Tape Coordinator machine
+associated with the specified port offset, then the Backup System dumps
+data to the backup data file listed for that port offset in the Tape
+Coordinator's F</usr/afs/backup/tapeconfig> file, rather than to tape. For
+the sake of clarity, the following text refers to tapes only, but the
+Backup System handles backup data files in much the same way.)
+
+The term I<dumping> refers to copying a collection of data to tape or a
+backup data file, and the resulting collection is termed a I<dump>. The
+set of tapes that contain one or more dumps is called a I<dump set>. The
+first dump in a dump set is its I<initial dump>, and any dumps
+subsequently added to the dump set (by use of the B<-append> argument) are
+I<appended dumps>.  Creating appended dumps is optional, and appended
+dumps can be of different volume sets, and at different dump levels, than
+the initial dump.
 
 A I<full dump>, created at a full dump level in the dump hierarchy,
-contains all of the data that existed at the time of the dump in the volumes
-belonging to the volume set. An I<incremental dump>, created at
-an incremental dump level, contains only data that has changed since the
-volume set was dumped at the incremental level's I<parent dump
-level> (the dump level immediately above the incremental level in the
-hierarchy), which can be a full or incremental level. More
-specifically, an incremental dump includes only the files and directories that
-have modification timestamps later than the I<clone date> of the
-volume included at the parent dump level. For backup and read-only
-volumes, the clone date is the time at which the volume was cloned from its
-read/write source before being included in the parent dump; for
-read/write volumes, it represents the time at which the volume was locked for
-inclusion in the parent dump. The clone date appears in the I<clone
-date> field of the output from the B<backup volinfo>
-command. As an example, an incremental dump at the
-B</full/week1/thursday> level includes only files and directories that
-have changed since the volume set was dumped at the B</full/week1>
-level.
-
-Initiating different types of dump operations
+contains all of the data that existed at the time of the dump in the
+volumes belonging to the volume set. An I<incremental dump>, created at an
+incremental dump level, contains only data that has changed since the
+volume set was dumped at the incremental level's I<parent dump level> (the
+dump level immediately above the incremental level in the hierarchy),
+which can be a full or incremental level. More specifically, an
+incremental dump includes only the files and directories that have
+modification timestamps later than the I<clone date> of the volume
+included at the parent dump level. For backup and read-only volumes, the
+clone date is the time at which the volume was cloned from its read/write
+source before being included in the parent dump; for read/write volumes,
+it represents the time at which the volume was locked for inclusion in the
+parent dump. The clone date appears in the I<clone date> field of the
+output from the B<backup volinfo> command. As an example, an incremental
+dump at the C</full/week1/thursday> level includes only files and
+directories that have changed since the volume set was dumped at the
+C</full/week1> level.
+
+=head2 Initiating different types of dump operations
 
 To initiate a dump operation that is to start as soon as the relevant Tape
-Coordinator is available, provide only the B<-volumeset>,
-B<-dump>, B<-portoffset>, and optionally B<-append>
-options. To schedule a single B<backup dump> command to execute
-in the future, also include the B<-at> argument to specify the start
-time.
+Coordinator is available, provide only the B<-volumeset>, B<-dump>,
+B<-portoffset>, and optionally B<-append> options. To schedule a single
+B<backup dump> command to execute in the future, also include the B<-at>
+argument to specify the start time.
 
-To append a dump to an existing dump set, include the -append
-flag. The Backup System imposes the following conditions on appended
-dumps:
+To append a dump to an existing dump set, include the B<-append> flag. The
+Backup System imposes the following conditions on appended dumps:
 
 =over 4
 
 =item *
 
 If writing to tape, the Tape Coordinator checks that it is the final one
-in a dump set for which there are complete and valid tape and dump records in
-the Backup Database. If not, it rejects the tape and requests an
-acceptable one. The operator can use the B<-dbadd> argument to
-the B<backup scantape> command to insert the necessary records into
-the database.
-
+in a dump set for which there are complete and valid tape and dump records
+in the Backup Database. If not, it rejects the tape and requests an
+acceptable one. The operator can use the B<-dbadd> argument to the
+B<backup scantape> command to insert the necessary records into the
+database.
 
 =item *
 
 The most recent dump on the tape or in the backup data file must have
 completed successfully.
 
-
 =item *
 
 The dump set must begin with an initial dump that is recorded in the
-Backup Database. If there are no dumps on the tape, then the Backup
-System treats the dump operation as an initial dump and imposes the relevant
+Backup Database. If there are no dumps on the tape, then the Backup System
+treats the dump operation as an initial dump and imposes the relevant
 requirements (for example, checks the AFS tape name if appropriate).
 
-
 =back
 
-To schedule multiple dump operations, list the operations in the file named
-by the B<-file> argument. Optionally include the B<-at>
-argument to specify when the B<backup> command interpreter reads the
-file; otherwise it reads it immediately. Do not combine the
-B<-file> argument with the command's first three arguments or the
-B<-append> or B<-n> flags. The commands in the file can
-include any of the B<backup dump> command's arguments, including
-the B<-at> argument to schedule them to run even later in the
-future.
+To schedule multiple dump operations, list the operations in the file
+named by the B<-file> argument. Optionally include the B<-at> argument to
+specify when the B<backup> command interpreter reads the file; otherwise
+it reads it immediately. Do not combine the B<-file> argument with the
+command's first three arguments or the B<-append> or B<-n> flags. The
+commands in the file can include any of the B<backup dump> command's
+arguments, including the B<-at> argument to schedule them to run even
+later in the future.
 
 To generate a list of the volumes included in a dump, without actually
-dumping them, combine the B<-n> flag with the options to be used on
-the actual command.
+dumping them, combine the B<-n> flag with the options to be used on the
+actual command.
 
-How the Backup System executes a dump operation
+=head2 How the Backup System executes a dump operation
 
-Before beginning a dump operation, the Backup System verifies that there is
-a Backup Database entry for the volume set, dump level, and port
-offset. If the command is correctly formed and issued in interactive
-mode, it is assigned a job number and added to the jobs list. List jobs
-in interactive mode by using the B<(backup) jobs> command;
-terminate them with the B<(backup) kill> command.
+Before beginning a dump operation, the Backup System verifies that there
+is a Backup Database entry for the volume set, dump level, and port
+offset. If the command is correctly formed and issued in interactive mode,
+it is assigned a job number and added to the jobs list. List jobs in
+interactive mode by using the B<backup jobs> command; terminate them with
+the B<backup kill> command.
 
 After obtaining the list of volumes to dump from the Volume Location (VL)
 Server, the Backup System sorts the list by site (server and
-partition). It groups volumes from the same site together in the dump
-to minimize the number of times the operator must change tapes during restore
+partition). It groups volumes from the same site together in the dump to
+minimize the number of times the operator must change tapes during restore
 operations.
 
 The dependence of an incremental dump on its parent means that a valid
 parent dump must already exist for the Backup System to create its child
 incremental dump. If the Backup System does not find a record of a dump
-created at the immediate parent dump level, it looks in the Backup Database
-for a dump created at one level higher in the hierarchy, and so on, up to the
-full dump level if necessary. It creates an incremental dump at the
-level one below the lowest valid parent dump set that it finds. If it
-fails to find even a full dump, it dumps the volume set at the full dump
-level.
+created at the immediate parent dump level, it looks in the Backup
+Database for a dump created at one level higher in the hierarchy, and so
+on, up to the full dump level if necessary. It creates an incremental dump
+at the level one below the lowest valid parent dump set that it finds. If
+it fails to find even a full dump, it dumps the volume set at the full
+dump level.
 
 If the Backup System is unable to access a volume during a dump operation,
 it skips the volume and dumps the remaining volumes from the volume
-set. Possible reasons a volume is inaccessible include server machine
-or process outages, or that the volume was moved between the time the Volume
-Location (VL) Server generated the list of sites for the volume in the volume
-set and the time the Backup System actually attempts to dump the data in
-it. After the first dumping pass, the Backup System attempts to dump
-each volume it skipped. If it still cannot dump a volume and the
-B<ASK NO> instruction does not appear in the
-B<CFG_>I<device_name> file, it queries the operator as to
-whether it needs to attempt to dump the volume again, omit the volume from the
-dump, or halt the dump operation altogether. When prompted, the
-operator can attempt to solve whatever problem prevented the Backup System
-from accessing the volumes. If the B<ASK NO> instruction
-appears in the B<CFG_>I<device_name> file, the Backup System
-omits the volume from the dump.
+set. Possible reasons a volume is inaccessible include server machine or
+process outages, or that the volume was moved between the time the Volume
+Location (VL) Server generated the list of sites for the volume in the
+volume set and the time the Backup System actually attempts to dump the
+data in it. After the first dumping pass, the Backup System attempts to
+dump each volume it skipped. If it still cannot dump a volume and the
+C<ASK NO> instruction does not appear in the F<CFG_I<device_name>> file,
+it queries the operator as to whether it needs to attempt to dump the
+volume again, omit the volume from the dump, or halt the dump operation
+altogether. When prompted, the operator can attempt to solve whatever
+problem prevented the Backup System from accessing the volumes. If the
+C<ASK NO> instruction appears in the F<CFG_I<device_name>> file, the
+Backup System omits the volume from the dump.
 
 Before scheduling a dump operation, the Backup System verifies that the
 date specified by the B<-at> argument is in the future, and checks the
-validity of the volume set, dump level and port offset as for a regular dump
-operation. It checks the validity of the parameters again just before
+validity of the volume set, dump level and port offset as for a regular
+dump operation. It checks the validity of the parameters again just before
 actually running the scheduled operation.
 
 Before writing an initial dump to a tape that does not have a permanent
 name on the label, the Backup System checks that the AFS tape name on the
 label is acceptable. If desired, disable name checking by including the
-B<NAME_CHECK NO> instruction in the
-B<CFG_>I<device_name> file.
+C<NAME_CHECK NO> instruction in the F<CFG_I<device_name>> file.
 
 If AFS tape name checking is enabled, the Backup System accepts the
-following three types of values for the AFS tape name. If the name on
-the label does not conform, the Backup System obtains a tape with an
-acceptable label by invoking the B<MOUNT> instruction in the
-B<CFG_>I<device_name> file or prompting the operator.
+following three types of values for the AFS tape name. If the name on the
+label does not conform, the Backup System obtains a tape with an
+acceptable label by invoking the C<MOUNT> instruction in the
+F<CFG_I<device_name>> file or prompting the operator.
 
-=item *
+=over 4
 
-A name of the form
-I<volume_set_name.dump_level_name.tape_index>, where
-I<volume_set_name> matches the value of the B<-volumeset>
-argument, I<dump_level_name> matches the last element in the pathname
-value of the B<-dump> argument, and I<tape_index> reflects the
-tape's place in a multitape dump set. As an example, the first
-tape in a dump set for which the initial dump is of volume set B<user>
-at the dump level B</sunday2/monday> has AFS tape name
-B<user.monday.1>. If the label records this type
-of AFS tape name, the Backup System retains the AFS tape name and writes the
-dump to the tape.
+=item *
 
+A name of the form I<volume_set_name.dump_level_name.tape_index>, where
+I<volume_set_name> matches the value of the B<-volumeset> argument,
+I<dump_level_name> matches the last element in the pathname value of the
+B<-dump> argument, and I<tape_index> reflects the tape's place in a
+multitape dump set. As an example, the first tape in a dump set for which
+the initial dump is of volume set C<user> at the dump level
+C</sunday2/monday> has AFS tape name C<user.monday.1>. If the label
+records this type of AFS tape name, the Backup System retains the AFS tape
+name and writes the dump to the tape.
 
 =item *
 
-The string C<<NULL>>, which usually indicates that a backup
-operator has used the B<backup labeltape> command to write a label on
-the tape, but did not include the B<-name> argument to assign an AFS
-tape name. Presumably, the operator did include the B<-pname>
-argument to assign a permanent name. If the label records a
-C<<NULL>> value, the Backup System constructs and records on the
-label the appropriate AFS tape name, and writes the dump on the tape.
-
+The string C<< <NULL> >>, which usually indicates that a backup operator
+has used the B<backup labeltape> command to write a label on the tape, but
+did not include the B<-name> argument to assign an AFS tape
+name. Presumably, the operator did include the B<-pname> argument to
+assign a permanent name. If the label records a C<< <NULL> >> value, the
+Backup System constructs and records on the label the appropriate AFS tape
+name, and writes the dump on the tape.
 
 =item *
 
 No value at all, because the tape has never been labeled or used in the
-Backup System. As when the AFS tape name is C<<NULL>>, the
-Backup System constructs and records on the label the appropriate AFS tape
-name, and writes the dump on the tape.
+Backup System. As when the AFS tape name is C<< <NULL> >>, the Backup
+System constructs and records on the label the appropriate AFS tape name,
+and writes the dump on the tape.
 
+=back
 
 To determine how much data it can write to a tape, the Tape Coordinator
-reads the capacity recorded on the tape's label (placed there by
-including the B<-size> argument to the B<backup labeltape>
-command). If the label's capacity field is empty, the Tape
-Coordinator uses the capacity recorded for the specified port offset in the
-local B<tapeconfig> file. If the capacity field in the
-B<tapeconfig> file is also empty, the Tape Coordinator uses the
-maximum capacity of 2 TB.
+reads the capacity recorded on the tape's label (placed there by including
+the B<-size> argument to the B<backup labeltape> command). If the label's
+capacity field is empty, the Tape Coordinator uses the capacity recorded
+for the specified port offset in the local F<tapeconfig> file. If the
+capacity field in the F<tapeconfig> file is also empty, the Tape
+Coordinator uses the maximum capacity of 2 TB.
 
 During a dump operation, the Tape Coordinator tracks how much data it has
-written and stops shortly before it reaches what it believes is the
-tape's capacity. If it is in the middle of writing the data for a
-volume when it reaches that point, it writes a special marker that indicates
-an interrupted volume and continues writing the volume on the next
-tape. It can split a volume this way during both an initial and an
-appended dump, and the fact that the volume resides on multiple tapes is
-automatically recorded in the Backup Database.
+written and stops shortly before it reaches what it believes is the tape's
+capacity. If it is in the middle of writing the data for a volume when it
+reaches that point, it writes a special marker that indicates an
+interrupted volume and continues writing the volume on the next tape. It
+can split a volume this way during both an initial and an appended dump,
+and the fact that the volume resides on multiple tapes is automatically
+recorded in the Backup Database.
 
 If the tape is actually larger than the expected capacity, then the Tape
 Coordinator simply does not use the excess tape. If the tape is smaller
 than the expected capacity, the Tape Coordinator can reach the end-of-tape
-(EOT) unexpectedly while it is writing data. If the Tape Coordinator is
-in the middle of the writing data from a volume, it obtains a new tape and
+(EOT) unexpectedly while it is writing data. If the Tape Coordinator is in
+the middle of the writing data from a volume, it obtains a new tape and
 rewrites the entire contents of the interrupted volume to it. The data
-from the volume that was written to the previous tape remains there, but is
-never used.
+from the volume that was written to the previous tape remains there, but
+is never used.
 
-The Backup System allows recycling of tapes (writing a new dump set over an
-old dump set that is no longer needed), but imposes the following
+The Backup System allows recycling of tapes (writing a new dump set over
+an old dump set that is no longer needed), but imposes the following
 conditions:
 
 =over 4
 
 =item *
 
-All dumps in the old dump set must be expired. The Backup System
-always checks expiration dates, even when name checking is disabled.
-
+All dumps in the old dump set must be expired. The Backup System always
+checks expiration dates, even when name checking is disabled.
 
 =item *
 
@@ -256,85 +244,80 @@ checking is enabled, then the AFS tape name derived from the new initial
 dump's volume set name and dump level name must match the AFS tape name
 already recorded on the label.
 
-
 =item *
 
 The tape cannot already have data on it that belongs to the dump currently
 being performed, because that implies that the operator or automated tape
 device has not removed the previous tape from the drive, or has mistakenly
 reinserted it. The Tape Coordinator generates the following message and
-attempts to obtain another tape: 
-
+attempts to obtain another tape:
 
    Can't overwrite tape containing the dump in progress
 
 =item *
 
 The tape cannot contain data from a parent dump of the current
-(incremental) dump, because overwriting a parent dump makes it impossible to
-restore data from the current dump. The Tape Coordinator generates the
-following message and attempts to obtain another tape: 
-
+(incremental) dump, because overwriting a parent dump makes it impossible
+to restore data from the current dump. The Tape Coordinator generates the
+following message and attempts to obtain another tape:
 
    Can't overwrite the parent dump I<parent_name> (I<parent_dump_ID>)
 
 =back
 
 To recycle a tape before all dumps on it have expired or if the AFS tape
-name is wrong, use the B<backup labeltape> command to overwrite the
-tape's label and remove all associated tape and dump records from the
-Backup Database.
-
-The Tape Coordinator's default response to this command is to access
-the first tape by invoking the B<MOUNT> instruction in the
-B<CFG_>I<device_name> file, or by prompting the backup operator
-to insert the tape if there is no B<MOUNT> instruction.
-However, if the B<AUTOQUERY NO> instruction appears in the
-B<CFG_>I<device_name> file, or if the issuer of the
-B<butc> command included the B<-noautoquery> flag, the Tape
-Coordinator instead expects the tape to be in the device already. If it
-is not, the Tape Coordinator invokes the B<MOUNT> instruction or
-prompts the operator. It also invokes the B<MOUNT> instruction
-or prompts for any additional tapes needed to complete the dump
-operation; the issuer must arrange to provide them.
+name is wrong, use the B<backup labeltape> command to overwrite the tape's
+label and remove all associated tape and dump records from the Backup
+Database.
+
+The Tape Coordinator's default response to this command is to access the
+first tape by invoking the C<MOUNT> instruction in the
+F<CFG_I<device_name>> file, or by prompting the backup operator to insert
+the tape if there is no C<MOUNT> instruction.  However, if the C<AUTOQUERY
+NO> instruction appears in the F<CFG_I<device_name>> file, or if the
+issuer of the B<butc> command included the B<-noautoquery> flag, the Tape
+Coordinator instead expects the tape to be in the device already. If it is
+not, the Tape Coordinator invokes the C<MOUNT> instruction or prompts the
+operator. It also invokes the C<MOUNT> instruction or prompts for any
+additional tapes needed to complete the dump operation; the issuer must
+arrange to provide them.
 
 =head1 CAUTIONS
 
 If a dump operation is interrupted or fails for any reason, data from all
 volumes written to tape before the interrupt are valid can be used in a
 restore operation. The Backup Database includes an entry for the failed
-dump and for each volume that was successfully dumped. See the I<IBM
-AFS Administration Guide> for information on dealing with interrupted
-dumps.
+dump and for each volume that was successfully dumped. See the I<IBM AFS
+Administration Guide> for information on dealing with interrupted dumps.
 
 If dumping to tape rather than a backup data file, it is best to use only
-compatible tape devices (ones that can read the same type of tape).
-Using compatible devices greatly simplifies restore operations. The
-B<-portoffset> argument to the B<backup diskrestore> and
-B<backup volsetrestore> commands accepts multiple port offset numbers,
-but the Backup System uses the first listed port offset when restoring all
-full dumps, the second port offset when restoring all level 1 dumps, and so
+compatible tape devices (ones that can read the same type of tape).  Using
+compatible devices greatly simplifies restore operations. The
+B<-portoffset> argument to the B<backup diskrestore> and B<backup
+volsetrestore> commands accepts multiple port offset numbers, but the
+Backup System uses the first listed port offset when restoring all full
+dumps, the second port offset when restoring all level 1 dumps, and so
 on. At the very least, use compatible tape devices to perform dumps at
 each level. If compatible tape devices are not used, the B<backup
 volrestore> command must be used to restore one volume at a time.
 
-Valid (unexpired) administrative tokens must be available to the
-B<backup> command interpreter both when it reads the file named by the
-B<-file> argument and when it runs each operation listed in the
-file. Presumably, the issuer is scheduling dumps for times when no
-human operator is present, and so must arrange for valid tokens to be
-available on the local machine. One option is to issue all commands (or
-run all scripts) on file server machines and use the B<-localauth>
-flag on the B<backup> and B<vos> commands. To protect
-against improper access to the machine or the tokens, the machine must be
-physically secure (perhaps even more protected than a Tape Coordinator machine
-monitored by a human operator during operation). Also, if an unattended
-dump requires multiple tapes, the operator must properly configure a tape
-stacker or jukebox and the device configuration file.
+Valid (unexpired) administrative tokens must be available to the B<backup>
+command interpreter both when it reads the file named by the B<-file>
+argument and when it runs each operation listed in the file. Presumably,
+the issuer is scheduling dumps for times when no human operator is
+present, and so must arrange for valid tokens to be available on the local
+machine. One option is to issue all commands (or run all scripts) on file
+server machines and use the B<-localauth> flag on the B<backup> and B<vos>
+commands. To protect against improper access to the machine or the tokens,
+the machine must be physically secure (perhaps even more protected than a
+Tape Coordinator machine monitored by a human operator during
+operation). Also, if an unattended dump requires multiple tapes, the
+operator must properly configure a tape stacker or jukebox and the device
+configuration file.
 
 When the command is issued in regular (non-interactive) mode, the command
-shell prompt does not return until the dump operation completes. To
-avoid having to open additional connections, issue the command in interactive
+shell prompt does not return until the dump operation completes. To avoid
+having to open additional connections, issue the command in interactive
 mode, especially when including the B<-at> argument to schedule dump
 operations.
 
@@ -342,112 +325,100 @@ operations.
 
 =over 4
 
-=item -volumeset
+=item B<-volumeset> <I<volume set name>>
 
-Names the volume set to dump. The -dump argument must be
-provided along with this one; do not combine them with the
-B<-file> argument. If using a temporary volume set, the
-B<vos dump> command must be issued within the interactive session in
-which the B<backup addvolset> command was issued with the
-B<-temporary> flag.
+Names the volume set to dump. The B<-dump> argument must be provided along
+with this one; do not combine them with the B<-file> argument. If using a
+temporary volume set, the B<vos dump> command must be issued within the
+interactive session in which the B<backup addvolset> command was issued
+with the B<-temporary> flag.
 
-=item -dump
+=item B<-dump> <I<dump level name>>
 
 Specifies the complete pathname of the dump level at which to dump the
-volume set. The B<-volumeset> argument must be provided along
-with this one; do not combine them with the B<-file>
-argument.
+volume set. The B<-volumeset> argument must be provided along with this
+one; do not combine them with the B<-file> argument.
 
-=item -portoffset
+=item B<-portoffset> <I<TC port offset>>
 
 Specifies the port offset number of the Tape Coordinator handling the
-tapes for this operation. It must be provided unless the default value
-of 0 (zero) is appropriate; do not combine it with the B<-file>
-argument.
+tapes for this operation. It must be provided unless the default value of
+0 (zero) is appropriate; do not combine it with the B<-file> argument.
 
-=item -at
->
+=item B<-at> <I<date/time to start dump>>
 
 Specifies the date and time in the future at which to run the command, or
-to read the file named by the B<-file> argument. Provide a
-value in the format I<mm/dd/yyyy> [I<hh:MM>], where the
-month (I<mm>), day (I<dd>), and year (I<yyyy>) are
-required. Valid values for the year range from B<1970> to
-B<2037>; higher values are not valid because the latest possible
-date in the standard UNIX representation is in February 2038. The
-Backup System automatically reduces any later date to the maximum
-value.
+to read the file named by the B<-file> argument. Provide a value in the
+format I<mm/dd/yyyy> [I<hh:MM>], where the month (I<mm>), day (I<dd>), and
+year (I<yyyy>) are required. Valid values for the year range from C<1970>
+to C<2037>; higher values are not valid because the latest possible date
+in the standard UNIX representation is in February 2038. The Backup System
+automatically reduces any later date to the maximum value.
 
-The hour and minutes (I<hh:MM>) are optional, but if provided
-must be in 24-hour format (for example, the value B<14:36>
-represents 2:36 p.m.). If omitted, the time
-defaults to midnight (00:00 hours).
+The hour and minutes (I<hh:MM>) are optional, but if provided must be in
+24-hour format (for example, the value C<14:36> represents 2:36 p.m.). If
+omitted, the time defaults to midnight (00:00 hours).
 
-As an example, the value 04/23/1999 20:20 schedules the
-command for 8:20 p.m. on 23 April 1999.
+As an example, the value 04/23/1999 20:20 schedules the command for 8:20
+p.m. on 23 April 1999.
 
-=item -append
+=item B<-append>
 
 Appends the dump onto the end of a tape that already contains data from
-another dump. However, if the tape is not in fact part of an existing
-dump set, the Backup System creates a new dump set using the parameters of
-this dump. If the tape is not the last tape in the dump set, the Tape
-Coordinator prompts for insertion of the appropriate tape. Do not
-combine this argument with the B<-file> argument.
+another dump. However, if the tape is not in fact part of an existing dump
+set, the Backup System creates a new dump set using the parameters of this
+dump. If the tape is not the last tape in the dump set, the Tape
+Coordinator prompts for insertion of the appropriate tape. Do not combine
+this argument with the B<-file> argument.
 
-=item -n
+=item B<-n>
 
 Displays the names of volumes to be included in the indicated dump,
 without actually performing the dump operation. Do not combine this
 argument with the B<-file> argument.
 
-=item -file
-
-Specifies the local disk or AFS pathname of a file containing
-B<backup> commands. The Backup System reads the file
-immediately, or at the time specified by the B<-at> argument if it is
-provided. A partial pathname is interpreted relative to the current
-working directory.
-
-Place each backup dump command on its own line in the indicated
-file, using the same syntax as for the command line, but without the word
-B<backup> at the start of the line. Each command must include a
-value for the B<-volumeset> and B<-dump> arguments, and for
-the B<-portoffset> argument unless the default value of 0 is
-appropriate. Commands in the file can also include any of the
-B<backup dump> command's optional options. In the
-following example file, the first command runs as soon as the Backup System
-reads the file, whereas the other commands are themselves scheduled; the
-specified date and time must be later than the date and time at which the
-Backup System reads the file.
+=item B<-file> <I<load file>>
+
+Specifies the local disk or AFS pathname of a file containing B<backup>
+commands. The Backup System reads the file immediately, or at the time
+specified by the B<-at> argument if it is provided. A partial pathname is
+interpreted relative to the current working directory.
+
+Place each B<backup dump> command on its own line in the indicated file,
+using the same syntax as for the command line, but without the word
+B<backup> at the start of the line. Each command must include a value for
+the B<-volumeset> and B<-dump> arguments, and for the B<-portoffset>
+argument unless the default value of 0 is appropriate. Commands in the
+file can also include any of the B<backup dump> command's optional
+options. In the following example file, the first command runs as soon as
+the Backup System reads the file, whereas the other commands are
+themselves scheduled; the specified date and time must be later than the
+date and time at which the Backup System reads the file.
 
    dump user /sunday1/wednesday -port 1 
    dump sun4x_56 /sunday1/friday -port 2 -at 04/08/1999
    dump sun4x_55 /sunday1/friday -port 2 -at 04/08/1999 02:00 -append
 
-Do not combine this argument with the -volumeset,
-B<-dump>, B<-portoffset>, B<-append>, or B<-n>
-options.
+Do not combine this argument with the B<-volumeset>, B<-dump>,
+B<-portoffset>, B<-append>, or B<-n> options.
 
-=item -localauth
+=item B<-localauth>
 
 Constructs a server ticket using a key from the local
-B</usr/afs/etc/KeyFile> file. The B<backup> command
-interpreter presents it to the Backup Server, Volume Server and VL Server
-during mutual authentication. Do not combine this flag with the
-B<-cell> argument. For more details, see the introductory
-B<backup> reference page.
+F</usr/afs/etc/KeyFile> file. The B<backup> command interpreter presents
+it to the Backup Server, Volume Server and VL Server during mutual
+authentication. Do not combine this flag with the B<-cell> argument. For
+more details, see L<backup(8)>.
 
-=item -cell
+=item B<-cell> <I<cell name>>
 
-Names the cell in which to run the command. Do not combine this
-argument with the B<-localauth> flag. For more details, see the
-introductory B<backup> reference page.
+Names the cell in which to run the command. Do not combine this argument
+with the B<-localauth> flag. For more details, see L<backup(8)>.
 
-=item -help
+=item B<-help>
 
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
 
 =back
 
@@ -455,8 +426,8 @@ are ignored.
 
 The command interpreter first generates a list of the volumes to be
 included in the dump by matching the entries in the volume set against the
-volumes listed in the Volume Location Database (VLDB). It prints the
-list following the header:
+volumes listed in the Volume Location Database (VLDB). It prints the list
+following the header:
 
    Preparing to dump the following volumes:
 
@@ -466,13 +437,13 @@ processing:
 
    Starting dump.
 
-If the issuer includes the -n flag, the output is of the
-following form:
+If the issuer includes the B<-n> flag, the output is of the following
+form:
 
-   Starting dump of volume set 'I<volume set>' (dump set 'I<dump level>')
-   Total number of volumes : I<number dumped>
+   Starting dump of volume set '<volume set>' (dump set '<dump level>')
+   Total number of volumes : <number dumped>
    Would have dumped the following volumes:
-   I<list_of_volumes>
+   <list_of_volumes>
 
 where I<list_of_volumes> identifies each volume by name and volume ID
 number.
@@ -482,9 +453,9 @@ message in its window and records the error in its log and error files.
 
 =head1 EXAMPLES
 
-The following command dumps the volumes in the volume set called
-B<user> at the dump level B</full/sunday2/monday>. The
-issuer places the necessary tapes in the device with port offset 5.
+The following command dumps the volumes in the volume set called C<user>
+at the dump level C</full/sunday2/monday>. The issuer places the necessary
+tapes in the device with port offset 5.
 
    % backup dump -volumeset user -dump /full/sunday2/monday -portoffset 5
    Preparing to dump the following volumes:
@@ -496,8 +467,7 @@ issuer places the necessary tapes in the device with port offset 5.
    Starting dump.
 
 The following command displays the list of volumes to be dumped when the
-user dumps the B<sys_sun> volume set at the B</full> dump
-level.
+user dumps the C<sys_sun> volume set at the C</full> dump level.
 
    % backup dump -volumeset sys_sun -dump /full -n
    Starting dump of volume set 'sys_sun' (dump set '/full')
@@ -512,31 +482,30 @@ level.
        .            .
 
 The following command schedules a dump of the volumes in the volume set
-B<user> at the dump level B</sunday2/monday1> for 11:00
-p.m. on 14 June 1999. The appropriate Tape Coordinator
-has port offset 0 (zero), so that argument is omitted.
+C<user> at the dump level C</sunday2/monday1> for 11:00 p.m. on 14 June
+1999. The appropriate Tape Coordinator has port offset 0 (zero), so that
+argument is omitted.
 
    % backup dump -volumeset user -dump /sunday2/monday1 -at 06/14/1999 23:00
 
 =head1 PRIVILEGE REQUIRED
 
-The issuer must be listed in the /usr/afs/etc/UserList file on
-every machine where the Backup Server or Volume Location (VL) Server is
-running, and on every file server machine that houses an affected
-volume. If the B<-localauth> flag is included, the issuer must
-instead be logged on to a server machine as the local superuser
-B<root>.
+The issuer must be listed in the F</usr/afs/etc/UserList> file on every
+machine where the Backup Server or Volume Location (VL) Server is running,
+and on every file server machine that houses an affected volume. If the
+B<-localauth> flag is included, the issuer must instead be logged on to a
+server machine as the local superuser C<root>.
 
 =head1 SEE ALSO
 
-L<backup(1)>,
-L<backup_adddump(1)>,
-L<backup_addvolentry(1)>,
-L<backup_addvolset(1)>,
-L<backup_diskrestore(1)>,
-L<backup_labeltape(1)>,
-L<backup_volrestore(1)>,
-L<butc(1)>
+L<backup(8)>,
+L<backup_adddump(8)>,
+L<backup_addvolentry(8)>,
+L<backup_addvolset(8)>,
+L<backup_diskrestore(8)>,
+L<backup_labeltape(8)>,
+L<backup_volrestore(8)>,
+L<butc(8)>
 
 =head1 COPYRIGHT
 
index 02403ff..1b8a7be 100644 (file)
@@ -4,170 +4,153 @@ backup dumpinfo - Displays a dump record from the Backup Database
 
 =head1 SYNOPSIS
 
-B<backup dumpinfo> [B<-ndumps> <I<no. of dumps>>]  [-id <I<dump id>>]
-[B<-verbose>]  [B<-localauth>]  [B<-cell> <I<cell name>>]  [B<-help> ]
+B<backup dumpinfo> [B<-ndumps> <I<number of dumps>>] [B<-id> <I<dump id>>]
+    [B<-verbose>] [B<-localauth>] [B<-cell> <I<cell name>>] [B<-help>]
 
-B<backup dumpi> [B<-n> <I<no. of dumps>>]  [-i <I<dump id>>]
-[B<-v>]  [B<-l>]  [B<-c> <I<cell name>>]  [B<-h>]
+B<backup dumpi> [B<-n> <I<no. of dumps>>] [-i <I<dump id>>] [B<-v>]
+    [B<-l>] [B<-c> <I<cell name>>] [B<-h>]
 
 =head1 DESCRIPTION
 
-The backup dumpinfo command formats and displays the Backup
-Database record for the specified dumps. To specify how many of the
-most recent dumps to display, starting with the newest one and going back in
-time, use the B<-ndumps> argument. To display more detailed
-information about a single dump, use the B<-id> argument. To
-display the records for the 10 most recent dumps, omit both the
-B<-ndumps> and B<-id> arguments.
+The B<backup dumpinfo> command formats and displays the Backup Database
+record for the specified dumps. To specify how many of the most recent
+dumps to display, starting with the newest one and going back in time, use
+the B<-ndumps> argument. To display more detailed information about a
+single dump, use the B<-id> argument. To display the records for the 10
+most recent dumps, omit both the B<-ndumps> and B<-id> arguments.
 
-The -verbose flag produces very detailed information that is
-useful mostly for debugging purposes. It can be combined only with the
-B<-id> argument.
+The B<-verbose> flag produces very detailed information that is useful
+mostly for debugging purposes. It can be combined only with the B<-id>
+argument.
 
 =head1 OPTIONS
 
 =over 4
 
-=item -ndumps
+=item B<-ndumps> <I<number of dumps>>
 
 Displays the Backup Database record for each of the specified number of
 dumps that were most recently performed. If the database contains fewer
 dumps than are requested, the output includes the records for all existing
-dumps. Do not combine this argument with the B<-id> or
-B<-verbose> options; omit all options to display the records for
-the last 10 dumps.
+dumps. Do not combine this argument with the B<-id> or B<-verbose>
+options; omit all options to display the records for the last 10 dumps.
 
-=item -id
+=item B<-id> <I<dump id>>
 
 Specifies the dump ID number of a single dump for which to display the
-Backup Database record. Precede the I<dump id> value with the
-B<-id> switch; otherwise, the command interpreter interprets it
-as the value of the B<-ndumps> argument. Combine this argument
-with the B<-verbose> flag, but not with the B<-ndumps>
-argument; omit all options to display the records for the last 10
-dumps.
+Backup Database record. Precede the I<dump id> value with the B<-id>
+switch; otherwise, the command interpreter interprets it as the value of
+the B<-ndumps> argument. Combine this argument with the B<-verbose> flag,
+but not with the B<-ndumps> argument; omit all options to display the
+records for the last 10 dumps.
 
-=item -verbose
+=item B<-verbose>
 
 Provides more detailed information about the dump specified with the
-B<-id> argument, which must be provided along with it. Do not
-combine this flag with the B<-ndumps> argument.
+B<-id> argument, which must be provided along with it. Do not combine this
+flag with the B<-ndumps> argument.
 
-=item -localauth
+=item B<-localauth>
 
 Constructs a server ticket using a key from the local
-B</usr/afs/etc/KeyFile> file. The B<backup> command
-interpreter presents it to the Backup Server, Volume Server and VL Server
-during mutual authentication. Do not combine this flag with the
-B<-cell> argument. For more details, see the introductory
-B<backup> reference page.
+F</usr/afs/etc/KeyFile> file. The B<backup> command interpreter presents
+it to the Backup Server, Volume Server and VL Server during mutual
+authentication. Do not combine this flag with the B<-cell> argument. For
+more details, see L<backup(8)>.
 
-=item -cell
+=item B<-cell> <I<cell name>>
 
-Names the cell in which to run the command. Do not combine this
-argument with the B<-localauth> flag. For more details, see the
-introductory B<backup> reference page.
+Names the cell in which to run the command. Do not combine this argument
+with the B<-localauth> flag. For more details, see L<backup(8)>.
 
-=item -help
+=item B<-help>
 
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
 
 =back
 
 =head1 OUTPUT
 
-If the -ndumps argument is provided, the output presents the
-following information in table form, with a separate line for each dump:
+If the B<-ndumps> argument is provided, the output presents the following
+information in table form, with a separate line for each dump:
 
 =over 4
 
-=item C<dumpid
->
+=item dumpid
 
 The dump ID number.
 
-=item C<parentid
->
+=item parentid
 
-The dump ID number of the dump's parent dump. A value of
-C<0> (zero) identifies a full dump.
+The dump ID number of the dump's parent dump. A value of C<0> (zero)
+identifies a full dump.
 
-=item C<lv
->
+=item lv
 
 The depth in the dump hierarchy of the dump level used to create the
-dump. A value of C<0> (zero) identifies a full dump, in which
-case the value in the C<parentid> field is also C<0>. A
-value of C<1> or greater indicates an incremental dump made at the
-corresponding level in the dump hierarchy.
+dump. A value of C<0> (zero) identifies a full dump, in which case the
+value in the C<parentid> field is also C<0>. A value of C<1> or greater
+indicates an incremental dump made at the corresponding level in the dump
+hierarchy.
 
-=item C<created
->
+=item created
 
 The date and time at which the Backup System started the dump operation
 that created the dump.
 
-=item C<nt
->
+=item nt
 
-The number of tapes that contain the data in the dump. A value of
-C<0> (zero) indicates that the dump operation was terminated or
-failed. Use the B<backup deletedump> command to remove such
-entries.
+The number of tapes that contain the data in the dump. A value of C<0>
+(zero) indicates that the dump operation was terminated or failed. Use the
+B<backup deletedump> command to remove such entries.
 
-=item C<nvols
->
+=item nvols
 
-The number of volumes from which the dump includes data. If a
-volume spans tapes, it is counted twice. A value of C<0> (zero)
-indicates that the dump operation was terminated or failed; the value in
-the C<nt> field is also C<0> in this case.
+The number of volumes from which the dump includes data. If a volume spans
+tapes, it is counted twice. A value of C<0> (zero) indicates that the dump
+operation was terminated or failed; the value in the C<nt> field is also
+C<0> in this case.
 
-=item C<dump name
->
+=item dump name
 
 The dump name in the form 
 
-   I<volume_set_name>.I<dump_level_name> (I<initial_dump_ID>)
+   <volume_set_name>.<dump_level_name> (<initial_dump_ID>)
 
-where I<volume_set_name> is the name of the volume set, and
-I<dump_level_name> is the last element in the dump level pathname at
-which the volume set was dumped.
+where <volume_set_name> is the name of the volume set, and
+<dump_level_name> is the last element in the dump level pathname at which
+the volume set was dumped.
 
-The I<initial_dump_ID>, if displayed, is the dump ID of the initial
-dump in the dump set to which this dump belongs. If there is no value
-in parentheses, the dump is the initial dump in a dump set that has no
+The <initial_dump_ID>, if displayed, is the dump ID of the initial dump in
+the dump set to which this dump belongs. If there is no value in
+parentheses, the dump is the initial dump in a dump set that has no
 appended dumps.
 
 =back
 
-If the -id argument is provided alone, the first line of output
-begins with the string C<Dump> and reports information for the entire
-dump in the following fields:
+If the B<-id> argument is provided alone, the first line of output begins
+with the string C<Dump> and reports information for the entire dump in the
+following fields:
 
 =over 4
 
-=item C<id
->
+=item id
 
 The dump ID number.
 
-=item C<level
->
+=item level
 
 The depth in the dump hierarchy of the dump level used to create the
-dump. A value of C<0> (zero) identifies a full dump. A
-value of C<1> (one) or greater indicates an incremental dump made at
-the specified level in the dump hierarchy.
+dump. A value of C<0> (zero) identifies a full dump. A value of C<1> (one)
+or greater indicates an incremental dump made at the specified level in
+the dump hierarchy.
 
-=item C<volumes
->
+=item volumes
 
 The number of volumes for which the dump includes data.
 
-=item C<created
->
+=item created
 
 The date and time at which the dump operation began.
 
@@ -176,31 +159,27 @@ The date and time at which the dump operation began.
 If an XBSA server was the backup medium for the dump (rather than a tape
 device or backup data file), the following line appears next:
 
-   Backup Service: I<XBSA_program>: Server: I<hostname>
+   Backup Service: <XBSA_program>: Server: <hostname>
 
-where I<XBSA_program> is the name of the XBSA-compliant program and
-I<hostname> is the name of the machine on which the program runs.
+where <XBSA_program> is the name of the XBSA-compliant program and
+<hostname> is the name of the machine on which the program runs.
 
 Next the output includes an entry for each tape that houses volume data
-from the dump. Following the string C<Tape>, the first two
-lines of each entry report information about that tape in the following
-fields:
+from the dump. Following the string C<Tape>, the first two lines of each
+entry report information about that tape in the following fields:
 
 =over 4
 
-=item C<name
->
+=item name
 
-The tape's permanent name if it has one, or its AFS tape name
-otherwise, and its tape ID number in parentheses.
+The tape's permanent name if it has one, or its AFS tape name otherwise,
+and its tape ID number in parentheses.
 
-=item C<nVolumes
->
+=item nVolumes
 
 The number of volumes for which this tape includes dump data.
 
-=item C<created
->
+=item created
 
 The date and time at which the Tape Coordinator began writing data to this
 tape.
@@ -213,73 +192,64 @@ information appears in columns with the following headings:
 
 =over 4
 
-=item C<Pos
->
+=item Pos
 
-The relative position of each volume in this tape or file. On a
-tape, the counter begins at position 2 (the tape label occupies position 1),
-and increments by one for each volume. For volumes in a backup data
-file, the position numbers start with 1 and do not usually increment only by
-one, because each is the ordinal of the 16 KB offset in the file at which the
+The relative position of each volume in this tape or file. On a tape, the
+counter begins at position 2 (the tape label occupies position 1), and
+increments by one for each volume. For volumes in a backup data file, the
+position numbers start with 1 and do not usually increment only by one,
+because each is the ordinal of the 16 KB offset in the file at which the
 volume's data begins. The difference between the position numbers
-therefore indicates how many 16 KB blocks each volume's data
-occupies. For example, if the second volume is at position 5 and the
-third volume in the list is at position 9, that means that the dump of the
-second volume occupies 64 KB (four 16-KB blocks) of space in the file.
+therefore indicates how many 16 KB blocks each volume's data occupies. For
+example, if the second volume is at position 5 and the third volume in the
+list is at position 9, that means that the dump of the second volume
+occupies 64 KB (four 16-KB blocks) of space in the file.
 
-=item C<Clone time
->
+=item Clone time
 
 For a backup or read-only volume, the time at which it was cloned from its
 read/write source. For a Read/Write volume, it is the same as the dump
 creation date reported on the first line of the output.
 
-=item C<Nbytes
->
+=item Nbytes
 
 The number of bytes of data in the dump of the volume.
 
-=item C<Volume
->
+=item Volume
 
-The volume name, complete with C<.backup> or
-C<.readonly> extension if appropriate.
+The volume name, complete with C<.backup> or C<.readonly> extension if
+appropriate.
 
 =back
 
-If both the B<-id> and -verbose options are provided,
-the output is divided into several sections:
+If both the B<-id> and B<-verbose> options are provided, the output is
+divided into several sections:
 
 =over 4
 
 =item *
 
-The first section, headed by the underlined string C<Dump>,
-includes information about the entire dump. The fields labeled
-C<id>, C<level>, C<created>, and C<nVolumes>
-report the same values (though in a different order) as appear on the first
-line of output when the B<-id> argument is provided by itself.
-Other fields of potential interest to the backup operator are: 
-
+The first section, headed by the underlined string C<Dump>, includes
+information about the entire dump. The fields labeled C<id>, C<level>,
+C<created>, and C<nVolumes> report the same values (though in a different
+order) as appear on the first line of output when the B<-id> argument is
+provided by itself.  Other fields of potential interest to the backup
+operator are:
 
 =over 4
 
-=item C<Group id
->
+=item Group id
 
-The dump's I<group ID number>, which is recorded in the
-dump's Backup Database record if the B<GROUPID> instruction
-appears in the Tape Coordinator's B<
-/usr/afs/backup/CFG_>I<tcid> file when the dump is created.
+The dump's I<group ID number>, which is recorded in the dump's Backup
+Database record if the C<GROUPID> instruction appears in the Tape
+Coordinator's F</usr/afs/backup/CFG_I<tcid>> file when the dump is
+created.
 
-=item C<maxTapes
->
+=item maxTapes
 
-The number of tapes that contain the dump set to which this dump
-belongs.
+The number of tapes that contain the dump set to which this dump belongs.
 
-=item C<Start Tape Seq
->
+=item Start Tape Seq
 
 The ordinal of the tape on which this dump begins in the set of tapes that
 contain the dump set.
@@ -289,60 +259,52 @@ contain the dump set.
 =item *
 
 For each tape that contains data from this dump, there follows a section
-headed by the underlined string C<Tape>. The fields labeled
-C<name>, C<written>, and C<nVolumes> report the same
-values (though in a different order) as appear on the second and third lines
-of output when the B<-id> argument is provided by itself. Other
-fields of potential interest to the backup operator are: 
-
+headed by the underlined string C<Tape>. The fields labeled C<name>,
+C<written>, and C<nVolumes> report the same values (though in a different
+order) as appear on the second and third lines of output when the B<-id>
+argument is provided by itself. Other fields of potential interest to the
+backup operator are:
 
 =over 4
 
-=item C<expires
->
+=item expires
 
 The date and time when this tape can be recycled, because all dumps it
 contains have expired.
 
-=item C<nMBytes Data and C<nBytes Data>
->
+=item nMBytes Data and nBytes Data
 
 Summed together, these fields represent the total amount of dumped data
 actually from volumes (as opposed to labels, filemarks, and other
 markers).
 
-=item C<KBytes Tape Used
->
+=item KBytes Tape Used
 
 The number of kilobytes of tape (or disk space, for a backup data file)
 used to store the dump data. It is generally larger than the sum of the
-values in the C<nMBytes Data> and C<nBytes Data> fields,
-because it includes the space required for the label, file marks and other
-markers, and because the Backup System writes data at 16 KB offsets, even if
-the data in a given block doesn't fill the entire 16 KB.
+values in the C<nMBytes Data> and C<nBytes Data> fields, because it
+includes the space required for the label, file marks and other markers,
+and because the Backup System writes data at 16 KB offsets, even if the
+data in a given block doesn't fill the entire 16 KB.
 
 =back
 
 =item *
 
 For each volume on a given tape, there follows a section headed by the
-underlined string C<Volume>. The fields labeled
-C<name>, C<position>, C<clone>, and C<nBytes>
-report the same values (though in a different order) as appear in the table
-that lists the volumes in each tape when the B<-id> argument is
-provided by itself. Other fields of potential interest to the backup
-operator are: 
-
+underlined string C<Volume>. The fields labeled C<name>, C<position>,
+C<clone>, and C<nBytes> report the same values (though in a different
+order) as appear in the table that lists the volumes in each tape when the
+B<-id> argument is provided by itself. Other fields of potential interest
+to the backup operator are:
 
 =over 4
 
-=item C<id
->
+=item id
 
 The volume ID.
 
-=item C<tape
->
+=item tape
 
 The name of the tape containing this volume data.
 
@@ -362,8 +324,7 @@ The following example displays information about the last five dumps:
    924860000  924424000 1  04/23/1999 05:33  1    58 usr.fri (924424000)
    925033000          0 0  04/25/1999 05:36  2    73 sys.week
 
-The following example displays a more detailed record for a single
-dump.
+The following example displays a more detailed record for a single dump.
 
    % backup dumpinfo -id 922097346
    Dump: id 922097346, level 0, volumes 1, created Mon Mar 22 05:09:06 1999
@@ -373,9 +334,9 @@ dump.
       1 03/22/1999 04:43 27787914 user.pat.backup
 
 The following example displays even more detailed information about the
-dump displayed in the previous example (dump ID 922097346). This
-example includes only one exemplar of each type of section (C<Dump>,
-C<Tape>, and C<Volume>):
+dump displayed in the previous example (dump ID 922097346). This example
+includes only one exemplar of each type of section (C<Dump>, C<Tape>, and
+C<Volume>):
 
    % backup dumpinfo -id 922097346 -verbose
    Dump
@@ -433,15 +394,15 @@ C<Tape>, and C<Volume>):
 
 =head1 PRIVILEGE REQUIRED
 
-The issuer must be listed in the /usr/afs/etc/UserList file on
-every machine where the Backup Server is running, or must be logged onto a
-server machine as the local superuser B<root> if the
-B<-localauth> flag is included.
+The issuer must be listed in the F</usr/afs/etc/UserList> file on every
+machine where the Backup Server is running, or must be logged onto a
+server machine as the local superuser C<root> if the B<-localauth> flag is
+included.
 
 =head1 SEE ALSO
 
-L<backup(1)>,
-L<backup_deletedump(1)>
+L<backup(8)>,
+L<backup_deletedump(8)>
 
 =head1 COPYRIGHT
 
index 3a22ae0..c29e7b7 100644 (file)
@@ -1,77 +1,69 @@
 =head1 NAME
 
-backup help - Displays the syntax of specified backup commands or lists
-functional descriptions of all B<backup> commands
+backup help - Displays help for backup commands
 
 =head1 SYNOPSIS
 
-B<backup help>  [B<-topic> <I<help string>>+]  [-help]
+B<backup help> [B<-topic> <I<help string>>+] [B<-help>]
 
-B<backup h> [B<-t> <I<help string>>+]  [-h]
+B<backup h> [B<-t> <I<help string>>+] [B<-h>]
 
 =head1 DESCRIPTION
 
-The backup help command displays the complete online help entry
-(short description and syntax statement) for each operation code specified by
-the B<-topic> argument. If the B<-topic> argument is
-omitted, the output includes the first line (name and short description) of
-the online help entry for every B<backup> command.
+The B<backup help> command displays the complete online help entry (short
+description and syntax statement) for each operation code specified by the
+B<-topic> argument. If the B<-topic> argument is omitted, the output
+includes the first line (name and short description) of the online help
+entry for every B<backup> command.
 
-To list every backup command whose name or short description
-includes a specified keyword, use the B<backup apropos>
-command.
+To list every backup command whose name or short description includes a
+specified keyword, use the B<backup apropos> command.
 
 =head1 OPTIONS
 
 =over 4
 
-=item -topic
+=item B<-topic> <I<help string>>+
 
 Indicates each command for which to display the complete online help
-entry. Omit the B<backup> part of the command name, providing
-only the operation code (for example, specify B<dump>, not B<backup
-dump>). If this argument is omitted, the output briefly describes
-every B<backup> command.
+entry. Omit the B<backup> part of the command name, providing only the
+operation code (for example, specify B<dump>, not B<backup dump>). If this
+argument is omitted, the output briefly describes every B<backup> command.
 
-=item -help
+=item B<-help>
 
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
 
 =back
 
 =head1 OUTPUT
 
-The online help entry for each backup command consists of the
-following two or three lines:
+The online help entry for each backup command consists of the following
+two or three lines:
 
 =over 4
 
 =item *
 
-The first line names the command and briefly describes its
-function.
-
+The first line names the command and briefly describes its function.
 
 =item *
 
 The second line lists aliases for the command, if any.
 
-
 =item *
 
-The final line, which begins with the string C<Usage>, lists the
-command's options in the prescribed order. Online help entries use
-the same symbols (for example, brackets) as the reference pages in this
-document.
-
+The final line, which begins with the string C<Usage>, lists the command's
+options in the prescribed order. Online help entries use the same symbols
+(for example, brackets) as the reference pages in this document.
 
 =back
 
 =head1 EXAMPLES
 
-The following example displays the online help entry for the backup
-dump command:
+The following example displays the online help entry for the B<backup
+dump> command:
 
    % backup help dump
    backup dump: start dump
@@ -85,8 +77,8 @@ None
 
 =head1 SEE ALSO
 
-L<backup(1)>,
-L<backup_apropos(1)>
+L<backup(8)>,
+L<backup_apropos(8)>
 
 =head1 COPYRIGHT
 
index fa397b9..aab649f 100644 (file)
@@ -4,98 +4,89 @@ backup interactive - Enters interactive mode
 
 =head1 SYNOPSIS
 
-B<backup> [B<interactive>]  [B<-localauth>]  [B<-cell> <I<cell name>>]  [-help]
+B<backup> [B<interactive>] [B<-localauth>] [B<-cell> <I<cell name>>]
+    [B<-help>]
 
-B<backup> [B<i>]  [B<-l>]  [B<-c> <I<cell name>>]  [-h]
+B<backup> [B<i>] [B<-l>] [B<-c> <I<cell name>>] [B<-h>]
 
 =head1 DESCRIPTION
 
-The backup interactive initiates an interactive session for
-issuing B<backup> commands. As indicated in the syntax
-statement, the operation code (B<interactive>) is optional.
+The B<backup interactive> initiates an interactive session for issuing
+B<backup> commands. As indicated in the syntax statement, the operation
+code (B<interactive>) is optional.
 
-Several features of interactive mode distinguish it from regular
-mode:
+Several features of interactive mode distinguish it from regular mode:
 
 =over 4
 
 =item *
 
-In interactive mode, the C<backup>> prompt replaces the system
-(shell) prompt. The operator enters only a command's operation
-code (omitting the command suite name, B<backup>).
-
+In interactive mode, the C<backup>> prompt replaces the system (shell)
+prompt. The operator enters only a command's operation code (omitting the
+command suite name, B<backup>).
 
 =item *
 
-If the B<-localauth> flag or the -cell argument is
-included on the B<backup (interactive)> command, the settings apply to
-all commands issued during that interactive session. The issuer does
-not need to type them on every command. Another consequence is that the
-flag and argument do not appear in the syntax statement generated by the
-B<help> subcommand or B<-help> flag on an individual command
-issued at the C<backup>> prompt.
-
+If the B<-localauth> flag or the B<-cell> argument is included on the
+B<backup interactive> command, the settings apply to all commands issued
+during that interactive session. The issuer does not need to type them on
+every command. Another consequence is that the flag and argument do not
+appear in the syntax statement generated by the B<help> subcommand or
+B<-help> flag on an individual command issued at the C<backup>> prompt.
 
 =item *
 
-The B<(backup) jobs> and (backup) kill commands are
-available only in interactive mode. It is not possible to track and
-terminate backup operations as cleanly in non-interactive mode.
-
+The B<backup jobs> and B<backup kill> commands are available only in
+interactive mode. It is not possible to track and terminate backup
+operations as cleanly in non-interactive mode.
 
 =item *
 
 It is not necessary to enclose strings that include metacharacters in
 double quotes or other delimiters.
 
-
 =item *
 
-The backup command interpreter establishes a connection to the
-Backup Server, Volume Server and Volume Location (VL) Server processes as it
-enters interactive mode, and uses the same connection for all commands during
-the session. Execution time can therefore be faster than in
-non-interactive mode, in which the command interpreter must establish a new
-connection for each command.
-
+The backup command interpreter establishes a connection to the Backup
+Server, Volume Server and Volume Location (VL) Server processes as it
+enters interactive mode, and uses the same connection for all commands
+during the session. Execution time can therefore be faster than in
+non-interactive mode, in which the command interpreter must establish a
+new connection for each command.
 
 =back
 
-To exit an interactive session, issue the (backup) quit
-command.
+To exit an interactive session, issue the B<backup quit> command.
 
 =head1 OPTIONS
 
 =over 4
 
-=item -localauth
+=item B<-localauth>
 
 Constructs a server ticket using a key from the local
-B</usr/afs/etc/KeyFile> file. The B<backup> command
-interpreter presents it to the Backup Server, Volume Server and VL Server
-during mutual authentication. Do not combine this flag with the
-B<-cell> argument. For more details, see the introductory
-B<backup> reference page.
+F</usr/afs/etc/KeyFile> file. The B<backup> command interpreter presents
+it to the Backup Server, Volume Server and VL Server during mutual
+authentication. Do not combine this flag with the B<-cell> argument. For
+more details, see L<backup(8)>.
 
-=item -cell
+=item B<-cell> <I<cell name>>
 
-Names the cell in which to run the command. Do not combine this
-argument with the B<-localauth> flag. For more details, see the
-introductory B<backup> reference page.
+Names the cell in which to run the command. Do not combine this argument
+with the B<-localauth> flag. For more details, see L<backup(8)>.
 
-=item -help
+=item B<-help>
 
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
 
 =back
 
 =head1 EXAMPLES
 
-The following example shows how the -localauth flag and
-B<-cell> argument do not appear when the B<help dump>
-subcommand is issued in interactive mode.
+The following example shows how the B<-localauth> flag and B<-cell>
+argument do not appear when the B<help dump> subcommand is issued in
+interactive mode.
 
    % backup
    backup> help dump
@@ -106,16 +97,16 @@ subcommand is issued in interactive mode.
 
 =head1 PRIVILEGE REQUIRED
 
-None. However, backup commands that require privilege in
-regular mode still require it in interactive mode.
+None. However, B<backup> commands that require privilege in regular mode
+still require it in interactive mode.
 
 =head1 SEE ALSO
 
-L<backup(1)>,
-L<backup_jobs(1)>,
-L<backup_kill(1)>,
-L<backup_quit(1)>,
-L<butc(1)>
+L<backup(8)>,
+L<backup_jobs(8)>,
+L<backup_kill(8)>,
+L<backup_quit(8)>,
+L<butc(8)>
 
 =head1 COPYRIGHT
 
index dd5a120..e848bca 100644 (file)
@@ -4,23 +4,21 @@ backup jobs - Lists pending and running operations in interactive mode
 
 =head1 SYNOPSIS
 
-B<jobs>  [-help]
+B<jobs> [B<-help>]
 
-B<j> [-h]
+B<j> [B<-h>]
 
 =head1 DESCRIPTION
 
-The (backup) jobs command lists the job ID number and status of
-each B<backup> operation running or pending in the current interactive
-session.
+The B<backup jobs> command lists the job ID number and status of each
+B<backup> operation running or pending in the current interactive session.
 
-This command can be issued in interactive mode only. If the issuer
-of the B<backup (interactive)> command included the
-B<-localauth> flag, the B<-cell> argument, or both, those
-settings apply to this command also.
+This command can be issued in interactive mode only. If the issuer of the
+B<backup interactive> command included the B<-localauth> flag, the
+B<-cell> argument, or both, those settings apply to this command also.
 
-To terminate operations that appear in the output, issue the (backup)
-kill command and identify the operation to cancel with the job ID number
+To terminate operations that appear in the output, issue the B<backup
+kill> command and identify the operation to cancel with the job ID number
 from this command's output.
 
 To check the status of a Tape Coordinator, rather than of a certain
@@ -30,59 +28,53 @@ operation, use the B<backup status> command.
 
 =over 4
 
-=item -help
+=item B<-help>
 
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
 
 =back
 
 =head1 OUTPUT
 
 The output always includes the expiration date and time of the tokens that
-the B<backup> command interpreter is using during the current
-interactive session, in the following format: 
+the B<backup> command interpreter is using during the current interactive
+session, in the following format:
 
-   I<date>   I<time>: TOKEN EXPIRATION
+   <date>   <time>: TOKEN EXPIRATION
 
 If the execution date and time specified for a scheduled dump operation is
-later than I<date time>, then its individual line (as described in the
+later than <date time>, then its individual line (as described in the
 following paragraphs) appears below this line to indicate that the current
 tokens will not be available to it.
 
-If the issuer of the backup command included the
-B<-localauth> flag when entering interactive mode, the line instead
-reads as follows:
+If the issuer of the backup command included the B<-localauth> flag when
+entering interactive mode, the line instead reads as follows:
 
    :  TOKEN NEVER EXPIRES
 
 The entry for a scheduled dump operation has the following format:
 
-   Job I<job_ID>:  I<timestamp>:  dump  I<volume_set>  I<dump_level>
+   Job <job_ID>:  <timestamp>:  dump  <volume_set>  <dump_level>
 
 where
 
 =over 4
 
-=item I<job_ID
->
+=item <job_ID>
 
 Is a job identification number assigned by the Backup System.
 
-=item I<timestamp
->
+=item <timestamp>
 
 Indicates the date and time the dump operation is to begin, in the format
-I<month>/I<date>/I<year>
-I<hours>:I<minutes> (in 24-hour format)
+I<month>/I<date>/I<year> I<hours>:I<minutes> (in 24-hour format)
 
-=item I<volume_set
->
+=item <volume_set>
 
 Indicates the volume set to dump.
 
-=item I<dump_level
->
+=item <dump_level>
 
 Indicates the dump level at which to perform the dump operation.
 
@@ -91,119 +83,99 @@ Indicates the dump level at which to perform the dump operation.
 The line for a pending or running operation of any other type has the
 following format:
 
-   Job I<job_ID>:  I<operation>  I<status>
+   Job <job_ID>:  <operation>  <status>
 
 where
 
 =over 4
 
-=item I<job_ID
->
+=item <job_ID>
 
 Is a job identification number assigned by the Backup System.
 
-=item I<operation
->
+=item <operation>
 
 Identifies the operation the Tape Coordinator is performing, which is
 initiated by the indicated command:
 
 =over 4
 
-=item C<Dump C<(>I<dump name>C<)>
->
+=item Dump (I<dump name>)
 
-Initiated by the backup dump command. The I<dump
-name> has the following format: 
+Initiated by the backup dump command. The I<dump name> has the following
+format:
 
-I<volume_set_name>.I<dump_level_name>
+    <volume_set_name>.<dump_level_name>
 
-=item C<Restore
->
+=item Restore
 
-Initiated by the B<backup diskrestore>, backup
-volrestore, or B<backup volsetrestore> command.
+Initiated by the B<backup diskrestore>, B<backup volrestore>, or B<backup
+volsetrestore> command.
 
-=item C<Labeltape C<(>I<tape_label>C<)>
->
+=item Labeltape (I<tape_label>)
 
-Initiated by the backup labeltape command. The
-I<tape_label> is the name specified by the B<backup labeltape>
-command's B<-name> or B<-pname> argument.
+Initiated by the B<backup labeltape>n command. The I<tape_label> is the
+name specified by the B<backup labeltape> command's B<-name> or B<-pname>
+argument.
 
-=item C<Scantape
->
+=item Scantape
 
-Initiated by the backup scantape command.
+Initiated by the B<backup scantape> command.
 
-=item C<SaveDb
->
+=item SaveDb
 
-Initiated by the backup savedb command.
+Initiated by the B<backup savedb> command.
 
-=item C<RestoreDb
->
+=item RestoreDb
 
-Initiated by the backup restoredb command.
+Initiated by the B<backup restoredb> command.
 
 =back
 
-=item I<status
->
+=item <status>
 
-Indicates the job's current status in one of the following
-messages. If no message appears, the job is either still pending or has
-finished.
+Indicates the job's current status in one of the following messages. If no
+message appears, the job is either still pending or has finished.
 
 =over 4
 
-=item I<number C<Kbytes, volume> I<volume_name>
->
+=item I<number> Kbytes, volume I<volume_name>
 
 For a running dump operation, indicates the number of kilobytes copied to
-tape or a backup data file so far, and the volume currently being
-dumped.
+tape or a backup data file so far, and the volume currently being dumped.
 
-=item I<number C<Kbytes, restore.volume>
->
+=item I<number> Kbytes, restore.volume
 
 For a running restore operation, indicates the number of kilobytes copied
 into AFS from a tape or a backup data file so far.
 
-=item C<[abort requested]
->
+=item [abort requested]
 
-The (backup) kill command was issued, but the termination
-signal has yet to reach the Tape Coordinator.
+The B<backup kill> command was issued, but the termination signal has yet
+to reach the Tape Coordinator.
 
-=item C<[abort sent]
->
+=item [abort sent]
 
-The operation is canceled by the (backup) kill command.
-Once the Backup System removes an operation from the queue or stops it from
-running, it no longer appears at all in the output from the command.
+The operation is canceled by the B<backup kill> command.  Once the Backup
+System removes an operation from the queue or stops it from running, it no
+longer appears at all in the output from the command.
 
-=item C<[butc contact lost]
->
+=item [butc contact lost]
 
-The backup command interpreter cannot reach the Tape
-Coordinator. The message can mean either that the Tape Coordinator
-handling the operation was terminated or failed while the operation was
-running, or that the connection to the Tape Coordinator timed out.
+The backup command interpreter cannot reach the Tape Coordinator. The
+message can mean either that the Tape Coordinator handling the operation
+was terminated or failed while the operation was running, or that the
+connection to the Tape Coordinator timed out.
 
-=item C<[done]
->
+=item [done]
 
 The Tape Coordinator has finished the operation.
 
-=item C<[drive wait]
->
+=item [drive wait]
 
-The operation is waiting for the specified tape drive to become
-free.
+The operation is waiting for the specified tape drive to become free.
 
-=item C<[operator wait]
->
+=item [operator wait]
 
 The Tape Coordinator is waiting for the backup operator to insert a tape
 in the drive.
@@ -215,8 +187,8 @@ in the drive.
 =head1 EXAMPLES
 
 The following example shows that two restore operations and one dump
-operation are running (presumably on different Tape Coordinators) and that the
-B<backup> command interpreter's tokens expire on 22 April 1999 at
+operation are running (presumably on different Tape Coordinators) and that
+the B<backup> command interpreter's tokens expire on 22 April 1999 at
 10:45 am:
 
    backup> jobs
@@ -228,15 +200,15 @@ B<backup> command interpreter's tokens expire on 22 April 1999 at
 =head1 PRIVILEGE REQUIRED
 
 None. However, queuing any operation requires privilege, and it is
-possible to issue this command only within the interactive session in which
-the jobs are queued.
+possible to issue this command only within the interactive session in
+which the jobs are queued.
 
 =head1 SEE ALSO
 
-L<backup(1)>,
-L<backup_interactive(1)>,
-L<backup_kill(1)>,
-L<backup_quit(1)>
+L<backup(8)>,
+L<backup_interactive(8)>,
+L<backup_kill(8)>,
+L<backup_quit(8)>
 
 =head1 COPYRIGHT
 
index c920ea0..33c8bf0 100644 (file)
@@ -4,24 +4,23 @@ backup kill - Terminates a pending or running operation
 
 =head1 SYNOPSIS
 
-B<kill -id> <I<job ID or dump set name>> [-help]
+B<kill> B<-id> <I<job ID or dump set name>> [B<-help>]
 
-B<k -i> <I<job ID or dump set name>>  [-h]
+B<k -i> <I<job ID or dump set name>> [B<-h>]
 
 =head1 DESCRIPTION
 
-The (backup) kill command dequeues a Backup System operation
-that is pending, or terminates an operation that is running, in the current
-interactive session. It is available only in interactive mode.
-If the issuer of the B<backup (interactive)> command included the
-B<-localauth> flag, the B<-cell> argument, or both, then those
-settings apply to this command also.
+The B<backup kill> command dequeues a Backup System operation that is
+pending, or terminates an operation that is running, in the current
+interactive session. It is available only in interactive mode.  If the
+issuer of the B<backup interactive> command included the B<-localauth>
+flag, the B<-cell> argument, or both, then those settings apply to this
+command also.
 
 To terminate a dump operation, specify either the dump name
-(I<volume_set_name>.I<dump_level_name>) or its job ID
-number, which appears in the output from the B<(backup) jobs>
-command. To terminate any other type of operation, provide the job ID
-number.
+(I<volume_set_name>.I<dump_level_name>) or its job ID number, which
+appears in the output from the B<backup jobs> command. To terminate any
+other type of operation, provide the job ID number.
 
 The effect of terminating an operation depends on the type and current
 state of the operation:
@@ -33,107 +32,98 @@ state of the operation:
 If an operation is still pending, the Tape Coordinator removes it from the
 queue with no other lasting effects.
 
-
 =item *
 
 If the Tape Coordinator is unable to process the termination signal before
-an operation completes, it simply confirms the operation's
-completion. The operator must take the action necessary to undo the
-effects of the incorrect operation.
-
+an operation completes, it simply confirms the operation's completion. The
+operator must take the action necessary to undo the effects of the
+incorrect operation.
 
 =item *
 
 If a tape labeling operation is running, the effect depends on when the
-Tape Coordinator receives the termination signal. The labeling
-operation is atomic, so it either completes or does not begin at all.
-Use the B<backup readlabel> command to determine if the labeling
-operation completed, and reissue the B<backup labeltape> command to
-overwrite the incorrect label if necessary.
-
+Tape Coordinator receives the termination signal. The labeling operation
+is atomic, so it either completes or does not begin at all.  Use the
+B<backup readlabel> command to determine if the labeling operation
+completed, and reissue the B<backup labeltape> command to overwrite the
+incorrect label if necessary.
 
 =item *
 
 If a tape scanning operation is running, it terminates with no other
-effects unless the B<-dbadd> flag was included on the
-B<backup> command. In that case, the Backup System possibly has
-already written new Backup Database records to represent dumps on the scanned
-tape. If planning to restart the scanning operation, first locate and
-remove the records created during the terminated operation: a repeated
-B<backup scantape> operation exits automatically when it finds that a
-record that it needs to create already exists.
-
+effects unless the B<-dbadd> flag was included on the B<backup>
+command. In that case, the Backup System possibly has already written new
+Backup Database records to represent dumps on the scanned tape. If
+planning to restart the scanning operation, first locate and remove the
+records created during the terminated operation: a repeated B<backup
+scantape> operation exits automatically when it finds that a record that
+it needs to create already exists.
 
 =item *
 
 If a dump operation is running, all of the volumes written to the tape or
-backup data file before the termination signal is received are complete and
-usable. If the operation is restarted, the Backup System performs all
-the dumps again from scratch, and assigns a new dump ID number. If
-writing the new dumps to the same tape or file, the operator must relabel it
-first if the interrupted dump is not expired. If writing the new dump
-to a different tape or file, the operator can remove the dump record
-associated with the interrupted dump to free up space in the database.
-
+backup data file before the termination signal is received are complete
+and usable. If the operation is restarted, the Backup System performs all
+the dumps again from scratch, and assigns a new dump ID number. If writing
+the new dumps to the same tape or file, the operator must relabel it first
+if the interrupted dump is not expired. If writing the new dump to a
+different tape or file, the operator can remove the dump record associated
+with the interrupted dump to free up space in the database.
 
 =item *
 
 If a restore operation is running, completely restored volumes are online
 and usable. However, it is unlikely that many volumes are completely
-restored, given that complete restoration usually requires data from multiple
-tapes. If the termination signal comes before the Backup System has
-accessed all of the necessary tapes, each volume is only partially written and
-is never brought online. It is best to restart the restore operation
-from scratch to avoid possible inconsistencies. See also the
-B<Cautions> section.
-
+restored, given that complete restoration usually requires data from
+multiple tapes. If the termination signal comes before the Backup System
+has accessed all of the necessary tapes, each volume is only partially
+written and is never brought online. It is best to restart the restore
+operation from scratch to avoid possible inconsistencies. See also
+L<CAUTIONS>.
 
 =back
 
 =head1 CAUTIONS
 
-It is best not to issue the (backup) kill command against
-restore operations. If the termination signal interrupts a restore
-operation as the Backup System is overwriting an existing volume, it is
-possible to lose the volume entirely (that is, to lose both the contents of
-the volume as it was before the restore and any data that was restored before
-the termination signal arrived). The data being restored still exists
-on the tape, but some data can be lost permanently.
+It is best not to issue the B<backup kill> command against restore
+operations. If the termination signal interrupts a restore operation as
+the Backup System is overwriting an existing volume, it is possible to
+lose the volume entirely (that is, to lose both the contents of the volume
+as it was before the restore and any data that was restored before the
+termination signal arrived). The data being restored still exists on the
+tape, but some data can be lost permanently.
 
 =head1 OPTIONS
 
 =over 4
 
-=item -id
+=item B<-id> <I<job ID or dump set name>>
 
-Identifies the backup operation to terminate. Provide one of two
-types of values: 
+Identifies the backup operation to terminate. Provide one of two types of
+values:
 
 =over 4
 
 =item *
 
-The operation's job ID number, as displayed in the output of the
-B<(backup) jobs> command.
-
+The operation's job ID number, as displayed in the output of the B<backup
+jobs> command.
 
 =item *
 
 For a dump operation, either the job ID number or a dump name of the form
-I<volume_set_name>.I<dump_level_name>, where
-I<volume_set_name> is the name of the volume set being dumped and
-I<dump_level_name> is the last element in the dump level pathname at
-which the volume set is being dumped. The dump name appears in the
-output of the B<(backup) jobs> command along with the job ID
-number.
-
+I<volume_set_name>.I<dump_level_name>, where I<volume_set_name> is the
+name of the volume set being dumped and I<dump_level_name> is the last
+element in the dump level pathname at which the volume set is being
+dumped. The dump name appears in the output of the B<backup jobs> command
+along with the job ID number.
 
 =back
 
-=item -help
+=item B<-help>
 
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
 
 =back
 
@@ -144,22 +134,22 @@ The following command terminates the operation with job ID 5:
    backup> kill 5
 
 The following command terminates the dump operation called
-B<user.sunday1>:
+C<user.sunday1>:
 
    backup> kill user.sunday1
 
 =head1 PRIVILEGE REQUIRED
 
-The issuer must have the privilege required to initiate the operation being
-cancelled. Because this command can be issued only within the
+The issuer must have the privilege required to initiate the operation
+being cancelled. Because this command can be issued only within the
 interactive session during which the operation was initiated, the required
 privilege is essentially guaranteed.
 
 =head1 SEE ALSO
 
-L<backup(1)>,
-L<backup_interactive(1)>,
-L<backup_jobs(1)>
+L<backup(8)>,
+L<backup_interactive(8)>,
+L<backup_jobs(8)>
 
 =head1 COPYRIGHT
 
index 52cd940..54b1418 100644 (file)
@@ -4,204 +4,187 @@ backup labeltape - Creates the magnetic label on a tape
 
 =head1 SYNOPSIS
 
-B<backup labeltape> [-name <I<AFS tape name, defaults to NULL>>]
-[B<-size> <I<tape size in Kbytes, defaults to size in tapeconfig>>]
-                 [-portoffset <I<TC port offset>>] 
-                 [-pname <I<permanent tape name>>] 
-                 [B<-localauth>]  [B<-cell> <I<cell name>>]  [-help]
+B<backup labeltape> [B<-name> <I<AFS tape name, defaults to NULL>>]
+    [B<-size> <I<tape size in Kbytes, defaults to size in tapeconfig>>]
+    [B<-portoffset> <I<TC port offset>>] [B<-pname> <I<permanent tape name>>]
+    [B<-localauth>] [B<-cell> <I<cell name>>] [B<-help>]
 
-B<backup la> [-n <I<AFS tape name, defaults to NULL>>]
-[B<-s> <I<tape size in Kbytes, defaults to size in tapeconfig>>]
-          [B<-po> <I<TC port offset>>]  [-pn <I<permanent tape name>>]
-          [B<-l>]  [B<-c> <I<cell name>>]  [-h]
+B<backup la> [B<-n> <I<AFS tape name, defaults to NULL>>]
+    [B<-s> <I<tape size in Kbytes, defaults to size in tapeconfig>>]
+    [B<-po> <I<TC port offset>>] [B<-pn> <I<permanent tape name>>]
+    [B<-l>] [B<-c> <I<cell name>>] [B<-h>]
 
 =head1 DESCRIPTION
 
-The backup labeltape command creates a magnetic label, readable
-by the Backup System, at the beginning of a tape. The label records the
-tape's name (either a I<permanent name>, or an I<AFS tape
-name> that reflects the tape's contents in a prescribed format) and
-its capacity.
-
-(If the FILE YES instruction appears in the
-B</usr/afs/backup/CFG_>I<device_name> file on the Tape
-Coordinator machine associated with the specified port offset, then the
-B<backup> command writes label information to the first 16 KB block in
-the backup data file listed for that port offset in the Tape
-Coordinator's B</usr/afs/backup/tapeconfig> file, rather than at
-the beginning of a tape. For the sake of clarity, the following text
-refers to tapes only, but the Backup System handles backup data files in much
-the same way.)
+The B<backup labeltape> command creates a magnetic label, readable by the
+Backup System, at the beginning of a tape. The label records the tape's
+name (either a I<permanent name>, or an I<AFS tape name> that reflects the
+tape's contents in a prescribed format) and its capacity.
+
+(If the C<FILE YES> instruction appears in the
+F</usr/afs/backup/CFG_I<device_name>> file on the Tape Coordinator machine
+associated with the specified port offset, then the B<backup> command
+writes label information to the first 16 KB block in the backup data file
+listed for that port offset in the Tape Coordinator's
+F</usr/afs/backup/tapeconfig> file, rather than at the beginning of a
+tape. For the sake of clarity, the following text refers to tapes only,
+but the Backup System handles backup data files in much the same way.)
 
 Relabeling a tape that already contains AFS backup data effectively makes
-the data unusable, because the command removes the Backup Database record of
-the complete dump set of which the tape is a part. Use this command to
-enable recycling of a tape that contains unexpired dumps that are not actually
-still needed.
-
-To write a permanent name on the label, include the -pname
-argument to specify a string of up to 32 characters. The permanent name
-persists until the B<-pname> argument is again included on the
-B<backup labeltape> command, regardless of the tape's contents
-and of how often the tape is otherwise relabeled or recycled. Include
-this argument or the B<-name> argument, but not both. If this
-argument is included, the AFS tape name is set to C<<NULL>>.
-The permanent name is set to C<<NULL>> if this argument is omitted
-and no permanent name already exists.
-
-The issuer must ensure that a permanent name is unique among the tapes used
-for AFS backup in the cell, because the B<backup> command interpreter
+the data unusable, because the command removes the Backup Database record
+of the complete dump set of which the tape is a part. Use this command to
+enable recycling of a tape that contains unexpired dumps that are not
+actually still needed.
+
+To write a permanent name on the label, include the B<-pname> argument to
+specify a string of up to 32 characters. The permanent name persists until
+the B<-pname> argument is again included on the B<backup labeltape>
+command, regardless of the tape's contents and of how often the tape is
+otherwise relabeled or recycled. Include this argument or the B<-name>
+argument, but not both. If this argument is included, the AFS tape name is
+set to C<< <NULL> >>.  The permanent name is set to C<< <NULL> >> if this
+argument is omitted and no permanent name already exists.
+
+The issuer must ensure that a permanent name is unique among the tapes
+used for AFS backup in the cell, because the B<backup> command interpreter
 does not verify that another tape does not already have the same permanent
-name. When a tape has a permanent name, the Backup System uses it
-instead of the AFS tape name in most prompts and when referring to the tape in
-output from B<backup> commands. The permanent name appears in
-the C<tape> C<name> field of the output from the B<backup
-readlabel> command.
-
-To write an AFS tape name on the label, provide a value for the
-B<-name> argument in the required format described in the
-B<Options> section. Include the B<-name> argument or
-the B<-pname> argument, but not both. If this argument is
-omitted, the AFS tape name is set to C<<NULL>>, but the Backup
-System automatically assigns the appropriate name when the tape is used in a
-future B<backup dump> or B<backup savedb> operation.
-The AFS tape name appears in the C<AFS> C<tape>
-C<name> field of the output from the B<backup readlabel> and
-B<backup scantape> commands.
-
-The backup command interpreter does not accept the
-B<-name> argument if the tape already has a permanent name. To
-erase a tape's permanent name, provide a null value to the
-B<-pname> argument by issuing the following command:
+name. When a tape has a permanent name, the Backup System uses it instead
+of the AFS tape name in most prompts and when referring to the tape in
+output from B<backup> commands. The permanent name appears in the C<tape
+name> field of the output from the B<backup readlabel> command.
+
+To write an AFS tape name on the label, provide a value for the B<-name>
+argument in the required format described in L<OPTIONS>.  Include the
+B<-name> argument or the B<-pname> argument, but not both. If this
+argument is omitted, the AFS tape name is set to C<< <NULL> >>, but the
+Backup System automatically assigns the appropriate name when the tape is
+used in a future B<backup dump> or B<backup savedb> operation.  The AFS
+tape name appears in the C<AFS tape name> field of the output from the
+B<backup readlabel> and B<backup scantape> commands.
+
+The backup command interpreter does not accept the B<-name> argument if
+the tape already has a permanent name. To erase a tape's permanent name,
+provide a null value to the B<-pname> argument by issuing the following
+command:
 
    % backup labeltape -pname ""
 
-To record the tape's capacity on the label, specify a number of
-kilobytes as the B<-size> argument. If the argument is omitted
-the first time a tape is labeled, the Backup System records the default tape
-capacity recorded for the specified port offset in the
-B</usr/afs/backup/tapeconfig> file on the Tape Coordinator
-machine. Subsequently, the value in the size field persists until the
-B<-size> argument is again included on the B<backup labeltape>
-command.
-
-To determine how much data can be written to a tape during a backup
-dump or B<backup savedb> operation, the Tape Coordinator reads
-the capacity recorded on the tape's label (or uses the value associated
-with its port offset in the B</usr/afs/backup/tapeconfig> file, if the
-tape was never labeled). For further description, see the B<backup
-dump> reference page.
-
-The Tape Coordinator's default response to this command is to access
-the tape by invoking the B<MOUNT> instruction in the local
-B</usr/afs/backup/CFG_>I<device_name> file, or by prompting the
-backup operator to insert the tape if there is no B<MOUNT>
-instruction. However, if the B<AUTOQUERY NO> instruction
-appears in the B<CFG_>I<device_name> file, or if the issuer of
-the B<butc> command included the B<-noautoquery> flag, the
-Tape Coordinator instead expects the tape to be in the device already.
-If it is not, the Tape Coordinator invokes the B<MOUNT> instruction or
-prompts the operator.
+To record the tape's capacity on the label, specify a number of kilobytes
+as the B<-size> argument. If the argument is omitted the first time a tape
+is labeled, the Backup System records the default tape capacity recorded
+for the specified port offset in the F</usr/afs/backup/tapeconfig> file on
+the Tape Coordinator machine. Subsequently, the value in the size field
+persists until the B<-size> argument is again included on the B<backup
+labeltape> command.
+
+To determine how much data can be written to a tape during a backup dump
+or B<backup savedb> operation, the Tape Coordinator reads the capacity
+recorded on the tape's label (or uses the value associated with its port
+offset in the F</usr/afs/backup/tapeconfig> file, if the tape was never
+labeled). For further description, see the B<backup dump> reference page.
+
+The Tape Coordinator's default response to this command is to access the
+tape by invoking the C<MOUNT> instruction in the local
+F</usr/afs/backup/CFG_I<device_name>> file, or by prompting the backup
+operator to insert the tape if there is no C<MOUNT> instruction. However,
+if the C<AUTOQUERY NO> instruction appears in the F<CFG_I<device_name>>
+file, or if the issuer of the B<butc> command included the B<-noautoquery>
+flag, the Tape Coordinator instead expects the tape to be in the device
+already.  If it is not, the Tape Coordinator invokes the C<MOUNT>
+instruction or prompts the operator.
 
 =head1 OPTIONS
 
 =over 4
 
-=item -name
+=item B<-name> <I<AFS tape name>>
 
-Specifies the AFS tape name to record on the label. Include this
-argument or the B<-pname> argument, but not both. If this
-argument is omitted, the AFS tape name is set to C<<NULL>>.
-If this argument is provided, it must have the following format:
+Specifies the AFS tape name to record on the label. Include this argument
+or the B<-pname> argument, but not both. If this argument is omitted, the
+AFS tape name is set to C<< <NULL> >>.  If this argument is provided, it
+must have the following format:
 
-   I<volume_set_name>.I<dump_level_name>.I<tape_index>
+   <volume_set_name>.<dump_level_name>.<tape_index>
 
 for the tape to be acceptable for use in a future backup dump
-operation. The I<volume_set_name> must match the volume set name
-of the initial dump to be written to the tape, I<dump_level_name> must
-match the last element of the dump level pathname at which the volume set will
-be dumped, and I<tape_index> indicates the order of the tape in the dump
-set (indexing begins with B<1>). To disable this type of name
-checking, include the B<NAME_CHECK NO> instruction in the
-B<CFG_>I<device_name> file. 
+operation. The <volume_set_name> must match the volume set name of the
+initial dump to be written to the tape, <dump_level_name> must match the
+last element of the dump level pathname at which the volume set will be
+dumped, and <tape_index> indicates the order of the tape in the dump set
+(indexing begins with C<1>). To disable this type of name checking,
+include the C<NAME_CHECK NO> instruction in the F<CFG_I<device_name>>
+file.
 
-For the tape to be acceptable for use in a future backup savedb
-operation, the value specified for the B<-name> argument must have the
-following format:
+For the tape to be acceptable for use in a future backup savedb operation,
+the value specified for the B<-name> argument must have the following
+format:
 
-   Ubik_db_dump.I<tape_index>
+   Ubik_db_dump.<tape_index>
 
-where I<tape_index> indicates the order of the tape in the set of
-tapes that house the Backup Database dump; indexing begins with 1
-(one).
+where <tape_index> indicates the order of the tape in the set of tapes
+that house the Backup Database dump; indexing begins with C<1> (one).
 
-=item -size
+=item B<-size> <I<tape size>>
 
-Specifies the tape capacity to record on the label. Provide an
-integer value followed by a letter that indicates units, with no intervening
-space. A unit value of B<k> or B<K> indicates
-kilobytes, B<m> or B<M> indicates megabytes, and B<g>
-or B<G> indicates gigabytes. If the units letter is omitted,
-the default is kilobytes.
+Specifies the tape capacity to record on the label. Provide an integer
+value followed by a letter that indicates units, with no intervening
+space. A unit value of C<k> or C<K> indicates kilobytes, C<m> or C<M>
+indicates megabytes, and C<g> or C<G> indicates gigabytes. If the units
+letter is omitted, the default is kilobytes.
 
 If this argument is omitted the first time a tape is labeled, the Backup
-System records the capacity that is associated with the specified port offset
-in the B</usr/afs/backup/tapeconfig> file on the Tape Coordinator
+System records the capacity that is associated with the specified port
+offset in the F</usr/afs/backup/tapeconfig> file on the Tape Coordinator
 machine. The value recorded the first time then persists until the
-B<-size> argument is provided on a future issuance of the
-command.
+B<-size> argument is provided on a future issuance of the command.
 
-=item -portoffset
+=item B<-portoffset> <I<TC port offset>>
 
 Specifies the port offset number of the Tape Coordinator handling the tape
 for this operation.
 
-=item -pname
+=item B<-pname> <I<permanent tape name>>
 
-Specifies the permanent name to record on the label. It can be up
-to 32 characters in length, and include any alphanumeric characters.
-Avoid metacharacters that have a special meaning to the shell, to avoid having
+Specifies the permanent name to record on the label. It can be up to 32
+characters in length, and include any alphanumeric characters.  Avoid
+metacharacters that have a special meaning to the shell, to avoid having
 to mark them as literal in commands issued at the shell prompt.
 
-Include this argument or the -name argument, but not
-both. If this argument is provided, the AFS tape name is set to
-C<<NULL>>. If this argument is omitted, any existing
-permanent name is retained.
+Include this argument or the B<-name> argument, but not both. If this
+argument is provided, the AFS tape name is set to C<< <NULL> >>. If this
+argument is omitted, any existing permanent name is retained.
 
-=item -localauth
+=item B<-localauth>
 
 Constructs a server ticket using a key from the local
-B</usr/afs/etc/KeyFile> file. The B<backup> command
-interpreter presents it to the Backup Server, Volume Server and VL Server
-during mutual authentication. Do not combine this flag with the
-B<-cell> argument. For more details, see the introductory
-B<backup> reference page.
+F</usr/afs/etc/KeyFile> file. The B<backup> command interpreter presents
+it to the Backup Server, Volume Server and VL Server during mutual
+authentication. Do not combine this flag with the B<-cell> argument. For
+more details, see L<backup(8)>.
 
-=item -cell
+=item B<-cell> <I<cell name>>
 
-Names the cell in which to run the command. Do not combine this
-argument with the B<-localauth> flag. For more details, see the
-introductory B<backup> reference page.
+Names the cell in which to run the command. Do not combine this argument
+with the B<-localauth> flag. For more details, see L<backup(8)>.
 
-=item -help
+=item B<-help>
 
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
 
 =back
 
 =head1 EXAMPLES
 
-The following command records the AFS tape name
-B<user.monthly.1> on the label of the tape in the device
-with port offset 3:
+The following command records the AFS tape name C<user.monthly.1> on the
+label of the tape in the device with port offset 3:
 
    % backup labeltape -name user.monthly.1 -portoffset 3
 
-The following three commands are equivalent in effect: they all
-record a capacity of 2 GB on the label of the tape in the device with port
-offset 4. They set the AFS tape name to C<<NULL>> and leave
-the permanent name unchanged.
+The following three commands are equivalent in effect: they all record a
+capacity of 2 GB on the label of the tape in the device with port offset
+4. They set the AFS tape name to C<< <NULL> >> and leave the permanent
+name unchanged.
 
    % backup labeltape -size 2g -portoffset 4
    % backup labeltape -size 2048M -portoffset 4
@@ -209,16 +192,15 @@ the permanent name unchanged.
 
 =head1 PRIVILEGE REQUIRED
 
-The issuer must be listed in the /usr/afs/etc/UserList file on
-every machine where the Backup Server is running, or must be logged onto a
-server machine as the local superuser B<root> if the
-B<-localauth> flag is included.
+The issuer must be listed in the F</usr/afs/etc/UserList> file on every
+machine where the Backup Server is running, or must be logged onto a
+server machine as the local superuser C<root> if the B<-localauth> flag is
+included.
 
 =head1 SEE ALSO
 
-L<CFG_I<device_name>(1)>,
-L<backup(1)>,
-L<backup_readlabel(1)>,
+L<backup(8)>,
+L<backup_readlabel(8)>,
 L<butc(1)>
 
 =head1 COPYRIGHT
index 7b32add..dbe7c7f 100644 (file)
@@ -4,38 +4,36 @@ backup listdumps - Displays the dump hierarchy from the Backup Database
 
 =head1 SYNOPSIS
 
-B<backup listdumps>  [B<-localauth>]  [B<-cell> <I<cell name>>]  [-help]
+B<backup listdumps> [B<-localauth>] [B<-cell> <I<cell name>>] [B<-help>]
 
-B<backup listd>  [B<-l>]  [B<-c> <I<cell name>>]  [-h]
+B<backup listd> [B<-l>] [B<-c> <I<cell name>>] [B<-h>]
 
 =head1 DESCRIPTION
 
-The backup listdumps command displays the dump hierarchy from
-the Backup Database.
+The B<backup listdumps> command displays the dump hierarchy from the
+Backup Database.
 
 =head1 OPTIONS
 
 =over 4
 
-=item -localauth
+=item B<-localauth>
 
 Constructs a server ticket using a key from the local
-B</usr/afs/etc/KeyFile> file. The B<backup> command
-interpreter presents it to the Backup Server, Volume Server and VL Server
-during mutual authentication. Do not combine this flag with the
-B<-cell> argument. For more details, see the introductory
-B<backup> reference page.
+F</usr/afs/etc/KeyFile> file. The B<backup> command interpreter presents
+it to the Backup Server, Volume Server and VL Server during mutual
+authentication. Do not combine this flag with the B<-cell> argument. For
+more details, see L<backup(8)>.
 
-=item -cell
+=item B<-cell> <I<cell name>>
 
-Names the cell in which to run the command. Do not combine this
-argument with the B<-localauth> flag. For more details, see the
-introductory B<backup> reference page.
+Names the cell in which to run the command. Do not combine this argument
+with the B<-localauth> flag. For more details, see L<backup(8)>.
 
-=item -help
+=item B<-help>
 
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
 
 =back
 
@@ -56,22 +54,22 @@ indentation indicates the parent/child relationship.
 If a dump level has an associated expiration date, it appears along with
 the level name. Absolute expiration dates appear in the format
 
-   I<dump_level> expires at I<day month date time year>    
+   <dump_level> expires at <day month date time year>    
 
 and relative expiration dates in the format
 
-   I<dump_level> expires in {I<years>y | I<months>m | I<days>d}
+   <dump_level> expires in {<years>y | <months>m | <days>d}
 
 to indicate the number of years, months, days, or combination of the three
 after creation a dump expires when created at this level.
 
 =head1 EXAMPLES
 
-The following example depicts six dump hierarchies. The expiration
-date for all incremental dump levels is 13 days so that the corresponding
-tapes can be recycled two weeks after their creation. The expiration
-dates for all full dump levels is 27 days so that the corresponding tapes can
-be recycled four weeks after their creation.
+The following example depicts six dump hierarchies. The expiration date
+for all incremental dump levels is 13 days so that the corresponding tapes
+can be recycled two weeks after their creation. The expiration dates for
+all full dump levels is 27 days so that the corresponding tapes can be
+recycled four weeks after their creation.
 
    % backup listdumps
    /week1  expires in  27d
@@ -113,16 +111,16 @@ be recycled four weeks after their creation.
 
 =head1 PRIVILEGE REQUIRED
 
-The issuer must be listed in the /usr/afs/etc/UserList file on
-every machine where the Backup Server is running, or must be logged onto a
-server machine as the local superuser B<root> if the
-B<-localauth> flag is included.
+The issuer must be listed in the F</usr/afs/etc/UserList> file on every
+machine where the Backup Server is running, or must be logged onto a
+server machine as the local superuser C<root> if the B<-localauth> flag is
+included.
 
 =head1 SEE ALSO
 
-L<backup(1)>,
-L<backup_adddump(1)>,
-L<backup_deldump(1)>
+L<backup(8)>,
+L<backup_adddump(8)>,
+L<backup_deldump(8)>
 
 =head1 COPYRIGHT
 
index 161bf81..0c308c0 100644 (file)
@@ -1,70 +1,65 @@
 =head1 NAME
 
-backup listhosts - Lists Tape Coordinator machines registered in the Backup Database
+backup listhosts - Lists Tape Coordinators registered in the Backup Database
 
 =head1 SYNOPSIS
 
-B<backup listhosts> [B<-localauth>]  [B<-cell> <I<cell name>>]  [-help]
+B<backup listhosts> [B<-localauth>] [B<-cell> <I<cell name>>] [B<-help>]
 
-B<backup listh> [B<-l>]  [B<-c> <I<cell name>>]  [-h]
+B<backup listh> [B<-l>] [B<-c> <I<cell name>>] [B<-h>]
 
 =head1 DESCRIPTION
 
-The backup listhosts command displays the Backup Database record
-of the port offset numbers defined for Tape Coordinator machines. A
-Tape Coordinator must have an entry in the list to be available for backup
+The B<backup listhosts> command displays the Backup Database record of the
+port offset numbers defined for Tape Coordinator machines. A Tape
+Coordinator must have an entry in the list to be available for backup
 operations.
 
 The existence of an entry does not necessarily indicate that the Tape
-Coordinator process (B<butc>) is currently running at that port
-offset. To check, issue the B<backup status> command.
+Coordinator process (B<butc>) is currently running at that port offset. To
+check, issue the B<backup status> command.
 
 =head1 OPTIONS
 
 =over 4
 
-=item -localauth
+=item B<-localauth>
 
 Constructs a server ticket using a key from the local
-B</usr/afs/etc/KeyFile> file. The B<backup> command
-interpreter presents it to the Backup Server, Volume Server and VL Server
-during mutual authentication. Do not combine this flag with the
-B<-cell> argument. For more details, see the introductory
-B<backup> reference page.
+F</usr/afs/etc/KeyFile> file. The B<backup> command interpreter presents
+it to the Backup Server, Volume Server and VL Server during mutual
+authentication. Do not combine this flag with the B<-cell> argument. For
+more details, see L<backup(8)>.
 
-=item -cell
+=item B<-cell> <I<cell name>>
 
-Names the cell in which to run the command. Do not combine this
-argument with the B<-localauth> flag. For more details, see the
-introductory B<backup> reference page.
+Names the cell in which to run the command. Do not combine this argument
+with the B<-localauth> flag. For more details, see L<backup(8)>.
 
-=item -help
+=item B<-help>
 
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
 
 =back
 
 =head1 OUTPUT
 
-After a C<Tape> C<hosts:> header, the output reports
-two things about each Tape Coordinator currently defined in the Backup
-Database:
+After a C<Tape hosts:> header, the output reports two things about each
+Tape Coordinator currently defined in the Backup Database:
 
 =over 4
 
 =item *
 
-The hostname of the machine housing the Tape Coordinator. The
-format of this name depends on the hostname format used when the B<backup
-addhost> command was issued.
-
+The hostname of the machine housing the Tape Coordinator. The format of
+this name depends on the hostname format used when the B<backup addhost>
+command was issued.
 
 =item *
 
 The Tape Coordinator's port offset number.
 
-
 =back
 
 The Tape Coordinators appear in the order in which they were added to the
@@ -84,17 +79,17 @@ Corporation cell:
 
 =head1 PRIVILEGE REQUIRED
 
-The issuer must be listed in the /usr/afs/etc/UserList file on
-every machine where the Backup Server is running, or must be logged onto a
-server machine as the local superuser B<root> if the
-B<-localauth> flag is included.
+The issuer must be listed in the F</usr/afs/etc/UserList> file on every
+machine where the Backup Server is running, or must be logged onto a
+server machine as the local superuser C<root> if the B<-localauth> flag is
+included.
 
 =head1 SEE ALSO
 
-L<backup(1)>,
-L<backup_addhost(1)>,
-L<backup_delhost(1)>,
-L<backup_status(1)>
+L<backup(8)>,
+L<backup_addhost(8)>,
+L<backup_delhost(8)>,
+L<backup_status(8)>
 
 =head1 COPYRIGHT
 
index ea4780f..858ccb9 100644 (file)
@@ -4,29 +4,28 @@ backup listvolsets - Lists volume set entries from the Backup Database
 
 =head1 SYNOPSIS
 
-B<backup listvolsets> [-name <I<volume set name>>]
-[B<-localauth>]  [B<-cell> <I<cell name>>]  [B<-help>]
+B<backup listvolsets> [B<-name> <I<volume set name>>] [B<-localauth>]
+    [B<-cell> <I<cell name>>] [B<-help>]
 
-B<backup listv> [B<-n> <I<volume set name>>]  [B<-l>]  [B<-c> <I<cell name>>]  [-h]
+B<backup listv> [B<-n> <I<volume set name>>] [B<-l>]
+    [B<-c> <I<cell name>>] [B<-h>]
 
 =head1 DESCRIPTION
 
-The backup listvolsets command displays the Backup Database
-records for either
+The B<backup listvolsets> command displays the Backup Database records for
+either
 
 =over 4
 
 =item *
 
-All volume sets and their volume entries, if the -name argument
-is omitted
-
+All volume sets and their volume entries, if the B<-name> argument is
+omitted.
 
 =item *
 
-The volume set specified by the -name argument, along with its
-volume entries
-
+The volume set specified by the B<-name> argument, along with its volume
+entries.
 
 =back
 
@@ -34,43 +33,40 @@ volume entries
 
 =over 4
 
-=item -name
+=item B<-name> <I<volume set name>>
 
-Names the volume set to display. If this argument is omitted, the
-output lists all volume sets defined in the Backup Database.
+Names the volume set to display. If this argument is omitted, the output
+lists all volume sets defined in the Backup Database.
 
-=item -localauth
+=item B<-localauth>
 
 Constructs a server ticket using a key from the local
-B</usr/afs/etc/KeyFile> file. The B<backup> command
-interpreter presents it to the Backup Server, Volume Server and VL Server
-during mutual authentication. Do not combine this flag with the
-B<-cell> argument. For more details, see the introductory
-B<backup> reference page.
+F</usr/afs/etc/KeyFile> file. The B<backup> command interpreter presents
+it to the Backup Server, Volume Server and VL Server during mutual
+authentication. Do not combine this flag with the B<-cell> argument. For
+more details, see L<backup(8)>.
 
-=item -cell
+=item B<-cell> <I<cell name>>
 
-Names the cell in which to run the command. Do not combine this
-argument with the B<-localauth> flag. For more details, see the
-introductory B<backup> reference page.
+Names the cell in which to run the command. Do not combine this argument
+with the B<-localauth> flag. For more details, see L<backup(8)>.
 
-=item -help
+=item B<-help>
 
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
 
 =back
 
 =head1 OUTPUT
 
-The entry for each volume set begins with the C<Volume set> header
-and the volume set's name. A temporary volume set's name is
-followed by the string C< (temporary)>. Each volume entry
-follows on a separate line, indicating the entry's index number and the
-server, partition, and volume names it matches. The output uses the
-metacharacter notation described on the B<backup addvolentry>
-reference page. Use the index number to identify volume entries when
-deleting them with the B<backup delvolentry> command.
+The entry for each volume set begins with the C<Volume set> header and the
+volume set's name. A temporary volume set's name is followed by the string
+C< (temporary)>. Each volume entry follows on a separate line, indicating
+the entry's index number and the server, partition, and volume names it
+matches. The output uses the metacharacter notation described on the
+B<backup addvolentry> reference page. Use the index number to identify
+volume entries when deleting them with the B<backup delvolentry> command.
 
 =head1 EXAMPLES
 
@@ -88,18 +84,18 @@ currently defined in the Backup Database:
 
 =head1 PRIVILEGE REQUIRED
 
-The issuer must be listed in the /usr/afs/etc/UserList file on
-every machine where the Backup Server is running, or must be logged onto a
-server machine as the local superuser B<root> if the
-B<-localauth> flag is included.
+The issuer must be listed in the F</usr/afs/etc/UserList> file on every
+machine where the Backup Server is running, or must be logged onto a
+server machine as the local superuser C<root> if the B<-localauth> flag is
+included.
 
 =head1 SEE ALSO
 
-L<backup(1)>,
-L<backup_addvolentry(1)>,
-L<backup_addvolset(1)>,
-L<backup_delvolentry(1)>,
-L<backup_delvolset(1)>
+L<backup(8)>,
+L<backup_addvolentry(8)>,
+L<backup_addvolset(8)>,
+L<backup_delvolentry(8)>,
+L<backup_delvolset(8)>
 
 =head1 COPYRIGHT
 
index 8335939..056f257 100644 (file)
@@ -4,50 +4,32 @@ backup quit - Leaves interactive mode
 
 =head1 SYNOPSIS
 
-B<quit>  [-help]
-
-B<q> [-h]
+B<quit> [B<-help>]
 
+B<q> [B<-h>]
 
 =head1 DESCRIPTION
 
-The (backup) quit command exits interactive mode, returning the
-issuer to the regular shell prompt at which the B<backup> or
-B<backup interactive> command was issued to enter interactive
-mode. The command has no effect when issued outside interactive
-mode. Issuing the <B<Ctrl-d>> command also exits interactive
-mode.
+The B<backup quit> command exits interactive mode, returning the issuer to
+the regular shell prompt at which the B<backup> or B<backup interactive>
+command was issued to enter interactive mode. The command has no effect
+when issued outside interactive mode. Issuing the Ctrl-D command also
+exits interactive mode.
 
 =head1 CAUTIONS
 
-To exit interactive mode, all jobs must be completed. Use the
-B<(backup) jobs> command to list any jobs currently pending or
-executing, and the B<(backup) kill> command to terminate them as
-necessary.
+To exit interactive mode, all jobs must be completed. Use the B<backup
+jobs> command to list any jobs currently pending or executing, and the
+B<backup kill> command to terminate them as necessary.
 
 =head1 OPTIONS
 
 =over 4
&n