* 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.
--- /dev/null
+=head1 NAME
+
+xstat_cm_test - Displays data collections from the Cache Manager
+
+=head1 SYNOPSIS
+
+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 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.
+
+=head1 OPTIONS
+
+=over 4
+
+=item I<initcmd>
+
+Accommodates the command's use of the AFS command parser, and is optional.
+
+=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 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.
+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 Cache Manager routines were called since the Cache Manager
+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).
+
+=item 2
+
+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 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_fs_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.
--- /dev/null
+=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.
--- /dev/null
+=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.
--- /dev/null
+=head1 NAME
+
+tapeconfig - Defines configuration parameters for all tape devices and backup data files
+on a Tape Coordinator machine
+
+=head1 DESCRIPTION
+
+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 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:
+
+ [I<capacity> I<filemark_size>] I<device_name> I<port_offset>
+
+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
+to this value in two circumstances:
+
+=over 4
+
+=item *
+
+When the capacity field of a tape or backup data file's label is
+empty (because the tape has never been labeled). The Tape Coordinator
+records this value on the label and uses it when determining how much data it
+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
+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
+System tape label to track how much space remains as it writes data to a tape
+or backup data file. The appropriate value to record for a tape depends
+on the size of the tapes usually used in the device and whether it has a
+compression mode; for suggested values, see the I<IBM AFS
+Administration Guide> chapter on configuring the Backup System. If
+using a value obtained from the B<fms> command, reduce it by 10% to
+15% before recording it in the file.
+
+For a backup data file, it is best to provide a value that helps the Tape
+Coordinator avoid reaching the end-of-file (EOF) unexpectedly. Make it
+at least somewhat smaller than the amount of space available on the partition
+housing the file when the dump operation begins, and never larger than the
+maximum file size allowed by the operating system.
+
+Specify a (positive) integer or decimal value followed by a letter than
+indicates units, with no intervening space. In a decimal number, the
+number of digits after the decimal point must not translate to fractions of
+bytes. The maximum acceptable value is 2048 GB (2 TB). The
+acceptable units letters are as follows; if the letter is omitted, the
+default is kilobytes.
+
+=over 4
+
+=item *
+
+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
+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
+manufacturer. In a dump to tape, the Tape Coordinator inserts filemarks
+at the boundary between the data from each volume, so the filemark size
+affects how much space is available for actual data.
+
+The appropriate value to record for a tape depends on the size of the tapes
+usually used in the device and whether it has a compression mode; for
+suggested values, see the I<IBM AFS Administration Guide> chapter on
+configuring the Backup System. If using a value obtained from the
+B<fms> command, increase it by 10% to 15% before recording it in the
+file.
+
+For backup data files, record a value of 0 (zero). The
+Tape Coordinator actually ignores this field for backup data files, because it
+does not use filemarks when writing to a file.
+
+Use the same notation as for the I<capacity> field, but note that the
+default units is bytes rather than kilobytes. The maximum acceptable
+value is 2048 GB.
+
+If this field is empty, the Tape Coordinator uses the value 0
+(zero). Either leave both this field and the I<capacity> field
+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
+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 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 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
+B<backup> commands.
+
+=back
+
+=head1 PRIVILEGE REQUIRED
+
+Creating the file requires UNIX B<w> (write) and
+B<x> (B<execute>) permissions on the
+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
+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 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.
+
+ 2G 1M /dev/rmt/0h 0
+ 1g 4k /dev/rmt/3h 3
+ 2G 1m /dev/rmt/4h 2
+ 1.5G 0 /dev/FILE 4
+
+=head1 SEE ALSO
+
+L<backup_addhost(8)>,
+L<backup_dump(8)>,
+L<backup_labeltape(8)>,
+L<backup_savedb(8)>,
+L<butc(1)>,
+L<fms(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.
--- /dev/null
+=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.
--- /dev/null
+=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.
=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
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
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 *
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 *
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 *
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
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,
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
/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
=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
=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:
=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
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
=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
=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.)
=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
=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
=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
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
=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
=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
=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
=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
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
=head1 SEE ALSO
-L<backup(1)>,
-L<backup_help(1)>
+L<backup(8)>,
+L<backup_help(8)>
=head1 COPYRIGHT
=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
=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
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
=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
=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
=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
=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
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
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:
=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
=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.
=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
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
=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
=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
=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
=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
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
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:
=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)>,
=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 *
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.
=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
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:
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.
=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:
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')
. .
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
=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.
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.
=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.
=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.
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
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
=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
=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
=head1 SEE ALSO
-L<backup(1)>,
-L<backup_apropos(1)>
+L<backup(8)>,
+L<backup_apropos(8)>
=head1 COPYRIGHT
=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
=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
=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
=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.
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.
=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
=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
=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:
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
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
=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
=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
=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
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
=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
=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
=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
=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
=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
=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
=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
-=item -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.
-
-=item -cell
-
-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.
-
-=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 SEE ALSO
-L<backup(1)>,
-L<backup_interactive(1)>,
-L<backup_jobs(1)>,
-L<backup_kill(1)>
+L<backup(8)>,
+L<backup_interactive(8)>,
+L<backup_jobs(8)>,
+L<backup_kill(8)>
=head1 COPYRIGHT
=head1 SYNOPSIS
-B<backup readlabel> [-portoffset <I<TC port offset>>]
-[B<-localauth>] [B<-cell> <I<cell name>>] [B<-help>]
+B<backup readlabel> [B<-portoffset> <I<TC port offset>>] [B<-localauth>]
+ [B<-cell> <I<cell name>>] [B<-help>]
-B<backup rea> [B<-p> <I<TC port offset>>] [B<-l>] [B<-c> <I<cell name>>] [-h]
+B<backup rea> [B<-p> <I<TC port offset>>] [B<-l>] [B<-c> <I<cell name>>]
+ [B<-h>]
=head1 DESCRIPTION
-The backup readlabel command displays information from the
-magnetic tape label of a tape. The information includes 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 associated with the
-specified port offset, then the B<backup readlabel> command reads the
-label information from 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 from the beginning of
-a tape.
-
-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.
+The B<backup readlabel> command displays information from the magnetic
+tape label of a tape. The information includes 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 associated with the specified
+port offset, then the B<backup readlabel> command reads the label
+information from 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 from the beginning of a tape.
+
+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 -portoffset
+=item B<-portoffset> <I<TC port offset>>
Specifies the port offset number of the Tape Coordinator handling the
tapes for this 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
=head1 OUTPUT
-Output from this command appears in both the shell window where the command
-is issued, and in the Tape Coordinator window.
+Output from this command appears in both the shell window where the
+command is issued, and in the Tape Coordinator window.
If the tape is unlabeled or if the specified tape device is empty, the
output reads
Otherwise, the output in the shell window has the following format:
- Tape read was labelled: I<tape name> (I<dump id>)
- size: I<size> Kbytes
+ Tape read was labelled: <tape name> (<dump id>)
+ size: <size> Kbytes
-where I<tape name> is the permanent name if the tape has one, or the
-AFS tape name otherwise. The I<dump ID> is dump ID of the initial
-dump on the tape, and I<size> is the recorded capacity of the tape in
-kilobytes.
+where <tape name> is the permanent name if the tape has one, or the AFS
+tape name otherwise. The <dump ID> is dump ID of the initial dump on the
+tape, and <size> is the recorded capacity of the tape in kilobytes.
The output in the Tape Coordinator windows is bounded by an underlined
-C<Tape> C<label> header at the top, and the following string
-at the bottom:
+C<Tape label> header at the top, and the following string at the bottom:
-- End of tape label --
=over 4
-=item C<tape name
->
+=item tape name
-The permanent name assigned by using the -pname argument of the
-B<backup labeltape> command. This name remains on the tape
-until that argument is used again, no matter how many times the tape is
-recycled or otherwise relabeled. If the tape does not have a permanent
-name, the value C<<NULL>> appears in this field.
+The permanent name assigned by using the -pname argument of the B<backup
+labeltape> command. This name remains on the tape until that argument is
+used again, no matter how many times the tape is recycled or otherwise
+relabeled. If the tape does not have a permanent name, the value C<<
+<NULL> >> appears in this field.
-=item C<AFS tape name
->
+=item AFS tape name
-A tape name in one of the following prescribed formats. The Backup
-System automatically writes the appropriate AFS tape name to the label as part
-of a B<backup dump> or B<backup savedb> operation, or the
-operator can assign it with the B<-name> argument to the B<backup
-labeltape> command.
+A tape name in one of the following prescribed formats. The Backup System
+automatically writes the appropriate AFS tape name to the label as part of
+a B<backup dump> or B<backup savedb> operation, or the operator can assign
+it with the B<-name> argument to the B<backup labeltape> command.
=over 4
=item *
-I<volume_set_name>B<.>I<dump_level_name>.I<tape_index>,
-if the tape contains volume data. The I<volume_set_name> is the
-name of the volume set that was dumped to create the initial dump in the dump
-set of to which this tape belongs; I<dump_level_name> is the last
-pathname element of the dump level at which the initial dump was backed
-up; and I<tape_index> is the numerical position of the tape in the
-dump set.
-
+I<volume_set_name>B<.>I<dump_level_name>.I<tape_index>, if the tape
+contains volume data. The I<volume_set_name> is the name of the volume set
+that was dumped to create the initial dump in the dump set of to which
+this tape belongs; I<dump_level_name> is the last pathname element of the
+dump level at which the initial dump was backed up; and I<tape_index> is
+the numerical position of the tape in the dump set.
=item *
-C<Ubik.db.dump.>I<tape_index> if the
-tape contains a dump of the Backup Database, created with the B<backup
-savedb> command. The I<tape_index> is the ordinal of the
-tape in the dump set.
-
+C<Ubik.db.dump.>I<tape_index> if the tape contains a dump of the Backup
+Database, created with the B<backup savedb> command. The I<tape_index> is
+the ordinal of the tape in the dump set.
=item *
-C<<NULL>> if the tape has no AFS tape name. This is
-normally the case if the B<-name> argument was not included the last
-time the B<backup labeltape> command was used on this tape, and no
-data has been written to it since.
-
+C<< <NULL> >> if the tape has no AFS tape name. This is normally the case
+if the B<-name> argument was not included the last time the B<backup
+labeltape> command was used on this tape, and no data has been written to
+it since.
=back
-=item C<creationTime
->
+=item creationTime
The date and time at which the Backup System started performing the dump
operation that created the initial dump.
-=item C<cell
->
+=item cell
-The cell in which the dump set was created. This is the cell whose
-Backup Database contains a record of the dump set.
+The cell in which the dump set was created. This is the cell whose Backup
+Database contains a record of the dump set.
-=item C<size
->
+=item size
-The tape's capacity (in kilobytes) as recorded on the label, rather
-than the amount of data on the tape. The value is assigned by the
-B<-size> argument to the B<backup labeltape> command or
-derived from the B</usr/afs/backup/tapeconfig> file on the Tape
-Coordinator machine, not from a measurement of the tape.
+The tape's capacity (in kilobytes) as recorded on the label, rather than
+the amount of data on the tape. The value is assigned by the B<-size>
+argument to the B<backup labeltape> command or derived from the
+F</usr/afs/backup/tapeconfig> file on the Tape Coordinator machine, not
+from a measurement of the tape.
-=item C<dump path
->
+=item dump path
-The dump level of the initial dump in the dump set
+The dump level of the initial dump in the dump set.
-=item C<dump id
->
+=item dump id
The dump ID number of the initial dump in the dump set, as recorded in the
-Backup Database
+Backup Database.
-=item C<useCount
->
+=item useCount
The number of times a dump has been written to the tape, or it has been
-relabeled
+relabeled.
=back
-The message C<ReadLabel: Finished> indicates the completion
-of the output.
+The message C<ReadLabel: Finished> indicates the completion of the output.
=head1 EXAMPLES
The following example shows the output for the tape with permanent name
-B<oct.guest.dump> and capacity 2 MB, expressed in
-kilobyte units (2097152 equals 2 times 10242).
+C<oct.guest.dump> and capacity 2 MB, expressed in kilobyte units (2097152
+equals 2 times 10242).
% backup readlabel -portoffset 6
Tape read was labelled: oct.guest.dump (907215000)
useCount = 5
---- End of tape label ----
-The following example is for a tape that does not have a permanent
-tape.
+The following example is for a tape that does not have a permanent tape.
% backup readlabel -portoffset 6
Tape read was labelled: guests.monthly.2 (909899900)
=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_labeltape(1)>,
-L<butc(1)>
+L<backup(8)>,
+L<backup_labeltape(8)>,
+L<butc(8)>
=head1 COPYRIGHT
=head1 SYNOPSIS
-B<backup restoredb> [-portoffset <I<TC port offset>>]
-[B<-localauth>] [B<-cell> <I<cell name>>] [B<-help>]
+B<backup restoredb> [B<-portoffset> <I<TC port offset>>] [B<-localauth>]
+ [B<-cell> <I<cell name>>] [B<-help>]
-B<backup res> [B<-p> <I<TC port offset>>] [B<-l>] [B<-c> <I<cell name>>] [-h]
+B<backup res> [B<-p> <I<TC port offset>>] [B<-l>] [B<-c> <I<cell name>>]
+ [B<-h>]
=head1 DESCRIPTION
-The backup restoredb command restores to the Backup Server
-machine's local disk a version of the Backup Database previously written
-to tape by using the B<backup savedb> command.
+The B<backup restoredb> command restores to the Backup Server machine's
+local disk a version of the Backup Database previously written to tape by
+using the B<backup savedb> command.
-(If the FILE YES instruction appears in the
-B</usr/afs/backup/CFG_>I<device_name> file associated with the
-specified port offset, then the B<backup restoredb> command 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.)
+(If the C<FILE YES> instruction appears in the
+F</usr/afs/backup/CFG_I<device_name>> file associated with the specified
+port offset, then the B<backup restoredb> command 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 most common reason to run this command is to replace a corrupted or
-otherwise damaged Backup Database; use the B<backup dbverify>
-command to determine the database's status. The command can also
-be used to restore records that were removed from the database when the
-B<-archive> argument was included on a previous B<backup
-savedb> command.
+otherwise damaged Backup Database; use the B<backup dbverify> command to
+determine the database's status. The command can also be used to restore
+records that were removed from the database when the B<-archive> argument
+was included on a previous B<backup savedb> command.
The command completely overwrites the existing Backup Database records for
-volume sets, Tape Coordinators, and the dump hierarchy with the corresponding
-information from the saved version. It does not overwrite existing dump
-records, but instead interleaves the records from the copy being
-restored. If both the existing database (on the Backup Server
+volume sets, Tape Coordinators, and the dump hierarchy with the
+corresponding information from the saved version. It does not overwrite
+existing dump records, but instead interleaves the records from the copy
+being restored. If both the existing database (on the Backup Server
machine's disk) and the copy being restored include a record about the
same dump, the Backup System retains the one in the existing database.
-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</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>
+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</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, 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.
+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 the database is corrupted, do not attempt to restore a saved database on
-top of it. Instead, use the instructions for repairing a corrupted
-database in the I<IBM AFS Administration Guide> chapter about
-performing backup operations.
+If the database is corrupted, do not attempt to restore a saved database
+on top of it. Instead, use the instructions for repairing a corrupted
+database in the I<IBM AFS Administration Guide> chapter about performing
+backup operations.
=head1 OPTIONS
=over 4
-=item -portoffset
+=item B<-portoffset> <I<TC port offset>>
Specifies the port offset number of the Tape Coordinator handling the
tapes for this 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
=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_dbverify(1)>,
-L<backup_savedb(1)>,
-L<butc(1)>
+L<backup(8)>,
+L<backup_dbverify(8)>,
+L<backup_savedb(8)>,
+L<butc(8)>
I<IBM AFS Administration Guide>
=head1 SYNOPSIS
-B<backup savedb> [B<-portoffset> <I<TC port offset>>] [-archive <I<date time>>+]
-[B<-localauth>] [B<-cell> <I<cell name>>] [B<-help>]
+B<backup savedb> [B<-portoffset> <I<TC port offset>>]
+ [B<-archive> <I<date time>>+] [B<-localauth>]
+ [B<-cell> <I<cell name>>] [B<-help>]
-B<backup sa> [B<-p> <I<TC port offset>>] [-a <I<date time>>+]
-[B<-l>] [B<-c> <I<cell name>>] [B<-h>]
+B<backup sa> [B<-p> <I<TC port offset>>] [B<-a> <I<date time>>+]
+ [B<-l>] [B<-c> <I<cell name>>] [B<-h>]
=head1 DESCRIPTION
-The backup savedb command creates a backup copy of the entire
-Backup Database and writes it to the tape in the device controlled by the Tape
-Coordinator indicated with the B<-portoffset> argument. If the
-database is damaged (as reported by the B<backup dbverify> command),
-this command repairs as much of the corruption as possible as it creates the
-saved copy. The Backup Server creates a dump record for the saved
-database in the Backup Database (but in the disk version of the database only,
-not in the version written to tape).
-
-If the FILE YES instruction appears in the
-B</usr/afs/backup/CFG_>I<device_name> file associated with the
-specified port offset, then the B<backup savedb> command dumps the
-database copy to the backup data file listed for that port offset in the Tape
-Coordinator's B</usr/afs/backup/tapeconfig> file, instead of 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.
-
-If the -archive flag is provided, after writing the saved copy
-of the database the Backup System truncates the copy of the database on disk
-by deleting volume dump records with timestamps prior to the specified date
+The B<backup savedb> command creates a backup copy of the entire Backup
+Database and writes it to the tape in the device controlled by the Tape
+Coordinator indicated with the B<-portoffset> argument. If the database is
+damaged (as reported by the B<backup dbverify> command), this command
+repairs as much of the corruption as possible as it creates the saved
+copy. The Backup Server creates a dump record for the saved database in
+the Backup Database (but in the disk version of the database only, not in
+the version written to tape).
+
+If the C<FILE YES> instruction appears in the
+F</usr/afs/backup/CFG_I<device_name>> file associated with the specified
+port offset, then the B<backup savedb> command dumps the database copy to
+the backup data file listed for that port offset in the Tape Coordinator's
+F</usr/afs/backup/tapeconfig> file, instead of 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.
+
+If the B<-archive> flag is provided, after writing the saved copy of the
+database the Backup System truncates the copy of the database on disk by
+deleting volume dump records with timestamps prior to the specified date
and time (it does not delete the dump records created by previous B<backup
savedb> commands, however).
If the tape to which the database copy is written has an AFS tape name, it
-must be B<Ubik_db_dump.1> or C<<NULL>>. Any
-permanent name is acceptable.
-
-The Tape Coordinator's default response to this command is to access
-the first 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. It also invokes the B<MOUNT> instruction
-or prompts for any additional tapes needed to complete the operation; the
-backup operator must arrange to provide them.
+must be C<Ubik_db_dump.1> or C<< <NULL> >>. Any permanent name is
+acceptable.
+
+The Tape Coordinator's default response to this command is to access the
+first 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. It also invokes the C<MOUNT>
+instruction or prompts for any additional tapes needed to complete the
+operation; the backup operator must arrange to provide them.
=head1 OPTIONS
=over 4
-=item -portoffset
+=item B<-portoffset> <I<TC port offset>>
Specifies the port offset number of the Tape Coordinator handling the
tapes for this operation.
-=item -archive
+=item B<-archive> <I<date time>>+
-Specifies a date and time; volume dump records with earlier
-timestamps are deleted from the disk copy of the Backup Database after the
-Backup System dumps the database (a dump's timestamp appears in the
-C<created> field of the output from the B<backup dumpinfo>
-command). However, if a dump set contains any dump created after the
-specified date, none of the dump records associated with the dump set are
-deleted. Dump records for previous dumps of the database (created with
-the B<backup savedb> command) are never deleted; use the
-B<backup deletedump> command to remove them.
+Specifies a date and time; volume dump records with earlier timestamps are
+deleted from the disk copy of the Backup Database after the Backup System
+dumps the database (a dump's timestamp appears in the C<created> field of
+the output from the B<backup dumpinfo> command). However, if a dump set
+contains any dump created after the specified date, none of the dump
+records associated with the dump set are deleted. Dump records for
+previous dumps of the database (created with the B<backup savedb> command)
+are never deleted; use the B<backup deletedump> command to remove them.
Provide one of two values:
=item *
-The string NOW to indicate the current date and time, in which
-case the Backup System deletes all dump records except those for dumps of the
+The string C<NOW> to indicate the current date and time, in which case the
+Backup System deletes all dump records except those for dumps of the
Backup Database itself.
-
=item *
-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, and 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.
-
+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, and 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>: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
+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 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. That is, the Database records a creation timestamp of
-C<20:55> for any dump created 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.
+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. That is, the
+Database records a creation timestamp of C<20:55> for any dump created
+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.
=back
-=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 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_dbverify(1)>,
-L<backup_restoredb(1)>,
-L<butc(1)>
+L<backup(8)>,
+L<backup_dbverify(8)>,
+L<backup_restoredb(8)>,
+L<butc(8)>
=head1 COPYRIGHT
=head1 SYNOPSIS
-B<backup scantape> [B<-dbadd>] [-portoffset <I<TC port offset>>]
-[B<-localauth>] [B<-cell> <I<cell name>>] [B<-help>]
+B<backup scantape> [B<-dbadd>] [B<-portoffset> <I<TC port offset>>]
+ [B<-localauth>] [B<-cell> <I<cell name>>] [B<-help>]
-B<backup sc> [B<-d>] [B<-p> <I<TC port offset>>] [B<-l>] [B<-c> <I<cell name>>] [-help]
+B<backup sc> [B<-d>] [B<-p> <I<TC port offset>>] [B<-l>]
+ [B<-c> <I<cell name>>] [B<-h>]
=head1 DESCRIPTION
-The backup scantape command extracts information from the dump
-labels and volume headers on the tape in the device controlled by the Tape
-Coordinator indicated by the B<-portoffset> argument. The Tape
-Coordinator displays the information for each volume in its window as soon as
-it extracts it (rather than waiting until it has scanned the entire
-tape).
-
-(If the FILE YES instruction appears in the
-B</usr/afs/backup/CFG_>I<device_name> file associated with the
-specified port offset, then the B<backup scantape> command extracts
-dump information from the backup data file named in that port offset's
-entry in the B</usr/afs/backup/tapeconfig> file on the Tape
-Coordinator machine, rather than from 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.)
-
-If the B<-dbadd> flag is provided, the backup scantape
-command creates new dump and volume records in the Backup Database for the
-scanned information. However, if it finds that a record already exists
-in the database for the same dump, it terminates the scanning
-operation.
-
-The scanning operation works only on tapes containing volume data.
-The command fails with an error message if the tape contains a copy of the
-Backup Database (was created with the B<backup savedb> command, or has
-the AFS tape name B<Ubik_db_dump.1>).
-
-The Tape Coordinator's default response to this command is to access
-the 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.
+The B<backup scantape> command extracts information from the dump labels
+and volume headers on the tape in the device controlled by the Tape
+Coordinator indicated by the B<-portoffset> argument. The Tape Coordinator
+displays the information for each volume in its window as soon as it
+extracts it (rather than waiting until it has scanned the entire tape).
+
+(If the C<FILE YES> instruction appears in the
+F</usr/afs/backup/CFG_I<device_name>> file associated with the specified
+port offset, then the B<backup scantape> command extracts dump information
+from the backup data file named in that port offset's entry in the
+F</usr/afs/backup/tapeconfig> file on the Tape Coordinator machine, rather
+than from 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.)
+
+If the B<-dbadd> flag is provided, the backup scantape command creates new
+dump and volume records in the Backup Database for the scanned
+information. However, if it finds that a record already exists in the
+database for the same dump, it terminates the scanning operation.
+
+The scanning operation works only on tapes containing volume data. The
+command fails with an error message if the tape contains a copy of the
+Backup Database (was created with the B<backup savedb> command, or has the
+AFS tape name C<Ubik_db_dump.1>).
+
+The Tape Coordinator's default response to this command is to access the
+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.
To terminate a tape scanning operation in interactive mode, issue the
-B<(backup) kill> command. In noninteractive mode, the only
-choice is to use a termination signal such as <B<Ctrl-c>> to halt
-the Tape Coordinator completely.
+B<backup kill> command. In noninteractive mode, the only choice is to use
+a termination signal such as Ctrl-C to halt the Tape Coordinator
+completely.
=head1 CAUTIONS
A scanning operation does not have to begin with the first tape in a dump
-set, but the Backup System can process tapes only in sequential order after
-the initial tape provided. The Tape Coordinator automatically requests
-any subsequent tapes by invoking the B<MOUNT> instruction in the local
-B</usr/afs/backup/CFG_>I<device_name> file, or by prompting the
-operator if there is no B<MOUNT> instruction.
+set, but the Backup System can process tapes only in sequential order
+after the initial tape provided. The Tape Coordinator automatically
+requests any subsequent tapes by invoking the C<MOUNT> instruction in the
+local F</usr/afs/backup/CFG_I<device_name>> file, or by prompting the
+operator if there is no C<MOUNT> instruction.
The Tape Coordinator's success in scanning a tape that is corrupted or
damaged depends on the extent of the damage and what type of data is
-corrupted. It can almost always scan the tape successfully up to the
-point of damage. If the damage is minor, the Tape Coordinator can
-usually skip over it and scan the rest of the tape, but more major damage can
-prevent further scanning. Because a scanning operation can start on any
-tape in a dump set, damage on one tape does not prevent scanning of the others
-in the dump set. However, it is possible to scan either the tapes that
+corrupted. It can almost always scan the tape successfully up to the point
+of damage. If the damage is minor, the Tape Coordinator can usually skip
+over it and scan the rest of the tape, but more major damage can prevent
+further scanning. Because a scanning operation can start on any tape in a
+dump set, damage on one tape does not prevent scanning of the others in
+the dump set. However, it is possible to scan either the tapes that
precede the damaged one or the ones that follow it, but not both.
-If a tape is relabeled with the backup labeltape command, it is
-not possible to recover data from it for the purposes of rebuilding the Backup
+If a tape is relabeled with the backup labeltape command, it is not
+possible to recover data from it for the purposes of rebuilding the Backup
Database.
-If the -dbadd flag is included on the command, it is best not to
+If the B<-dbadd> flag is included on the command, it is best not to
terminate the tape scanning operation before it completes (for example, by
-issuing the B<(backup) kill> command in interactive mode). The
-Backup System writes a new record in the Backup Database for each dump as soon
-as it scans the relevant information on the tape, and so it possibly has
-already written new records. If the operator wants to rerun the
-scanning operation, he or she must locate and remove the records created
-during the terminated operation: the second operation exits
-automatically if it finds that a record that it needs to create already
-exists.
-
-If the -dbadd flag is included and the first tape provided is
-not the first tape in the dump set, the following restrictions apply:
+issuing the B<backup kill> command in interactive mode). The Backup System
+writes a new record in the Backup Database for each dump as soon as it
+scans the relevant information on the tape, and so it possibly has already
+written new records. If the operator wants to rerun the scanning
+operation, he or she must locate and remove the records created during the
+terminated operation: the second operation exits automatically if it finds
+that a record that it needs to create already exists.
+
+If the B<-dbadd> flag is included and the first tape provided is not the
+first tape in the dump set, the following restrictions apply:
=over 4
=item *
If the first data on the tape is a continuation of a volume that begins on
-the previous (unscanned) tape in the dump set, the Backup System does not add
-a record for that volume to the Backup Database.
-
+the previous (unscanned) tape in the dump set, the Backup System does not
+add a record for that volume to the Backup Database.
=item *
The Backup System must read the marker that indicates the start of an
-appended dump to add database records for the volumes in it. If the
-first volume on the tape belongs to an appended dump, but is not immediately
+appended dump to add database records for the volumes in it. If the first
+volume on the tape belongs to an appended dump, but is not immediately
preceded by the appended-dump marker, the Backup System does not create a
-Backup Database record for it or any subsequent volumes that belong to that
-appended dump.
-
+Backup Database record for it or any subsequent volumes that belong to
+that appended dump.
=back
=over 4
-=item -dbadd
+=item B<-dbadd>
Adds the information extracted from the tape to the Backup Database (but
-only if the database does not already contain an entry with the same dump ID
-number).
+only if the database does not already contain an entry with the same dump
+ID number).
-=item -portoffset
+=item B<-portoffset> <I<TC port offset>>
Specifies the port offset number of the Tape Coordinator handling the
tapes for this 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
=head1 OUTPUT
-For every dump on a tape, the backup scantape command displays
-in the Tape Coordinator window the dump label and the volume header of each
-volume in the dump. If a dump spans more than one tape, the dump label
-does not repeat at the beginning of subsequent tapes.
+For every dump on a tape, the backup scantape command displays in the Tape
+Coordinator window the dump label and the volume header of each volume in
+the dump. If a dump spans more than one tape, the dump label does not
+repeat at the beginning of subsequent tapes.
A dump label contains the following fields, which are the same as in the
output from the B<backup readlabel> command:
=over 4
-=item C<tape nameC<>
->
+=item tape name
-The permanent name assigned by using the -pname argument of the
-B<backup labeltape> command. This name remains on the tape
-until that argument is used again, no matter how many times the tape is
-recycled or otherwise relabeled. If the tape does not have a permanent
-name, the value C<<NULL>> appears in this field.
+The permanent name assigned by using the B<-pname> argument of the
+B<backup labeltape> command. This name remains on the tape until that
+argument is used again, no matter how many times the tape is recycled or
+otherwise relabeled. If the tape does not have a permanent name, the value
+C<< <NULL> >> appears in this field.
-=item C<AFS tape name
->
+=item AFS tape name
-A tape name in one of the following prescribed formats. The Backup
-System automatically writes the appropriate AFS tape name to the label as part
-of a B<backup dump> operation, or the operator can assign it with the
-B<-name> argument to the B<backup labeltape> command.
+A tape name in one of the following prescribed formats. The Backup System
+automatically writes the appropriate AFS tape name to the label as part of
+a B<backup dump> operation, or the operator can assign it with the
+B<-name> argument to the B<backup labeltape> command.
=over 4
=item *
-I<volume_set_name>.I<dump_level_name>.I<tape
-_index>, if the tape contains volume data. The
-I<volume_set_name> is the name of the volume set that was dumped to
-create the initial dump in the dump set of which this tape is a part;
-I<dump_level_name> is the last pathname element of the dump level at
-which the initial dump was backed up; and I<tape_index> is the
-numerical position of the tape in the dump set.
-
+I<volume_set_name>.I<dump_level_name>.I<tape_index>, if the tape contains
+volume data. The I<volume_set_name> is the name of the volume set that was
+dumped to create the initial dump in the dump set of which this tape is a
+part; I<dump_level_name> is the last pathname element of the dump level at
+which the initial dump was backed up; and I<tape_index> is the numerical
+position of the tape in the dump set.
=item *
-C<<NULL>> if the tape has no AFS tape name. This is
-normally the case if the B<-name> argument was not included the last
-time the B<backup labeltape> command was used on this tape, and no
-data has been written to it since.
-
+C<< <NULL> >> if the tape has no AFS tape name. This is normally the case
+if the B<-name> argument was not included the last time the B<backup
+labeltape> command was used on this tape, and no data has been written to
+it since.
=back
-=item C<creationTime
->
+=item creationTime
The date and time at which the Backup System started performing the dump
operation that created the initial dump.
-=item C<cell
->
+=item cell
-The cell in which the dump set was created. This is the cell whose
-Backup Database contains a record of the dump set.
+The cell in which the dump set was created. This is the cell whose Backup
+Database contains a record of the dump set.
-=item C<size
->
+=item size
-The tape's capacity (in kilobytes) as recorded on the label, rather
-than the amount of data on the tape. The value is assigned by the
-B<-size> argument to the B<backup labeltape> command or
-derived from the B</usr/afs/backup/tapeconfig> file on the Tape
-Coordinator machine, not from a measurement of the tape.
+The tape's capacity (in kilobytes) as recorded on the label, rather than
+the amount of data on the tape. The value is assigned by the B<-size>
+argument to the B<backup labeltape> command or derived from the
+F</usr/afs/backup/tapeconfig> file on the Tape Coordinator machine, not
+from a measurement of the tape.
-=item C<dump C<path>
->
+=item dump path
The dump level of the initial dump in the dump set.
-=item C<dump C<id>
->
+=item dump id
The dump ID number of the initial dump in the dump set, as recorded in the
Backup Database.
-=item C<useCount
->
+=item useCount
The number of times a dump has been written to the tape, or it has been
relabeled.
=over 4
-=item C<volume C<name>
->
+=item volume name
-The volume name, complete with a C<.backup> or
-C<.readonly> extension, if appropriate.
+The volume name, complete with a C<.backup> or C<.readonly> extension, if
+appropriate.
-=item C<volume C<ID>
->
+=item volume ID
The volume's volume ID.
-=item C<dumpSetName
->
+=item dumpSetName
The dump to which the volume belongs. The dump name is of the form
-I<volume_set_name>B<.>I<dump_level_name> and
-matches the name displayed in the dump label.
+I<volume_set_name>.I<dump_level_name> and matches the name displayed in
+the dump label.
-=item C<dumpID
->
+=item dumpID
The dump ID of the dump named in the C<dumpSetName> field.
-=item C<level
->
+=item level
The depth in the dump hierarchy of the dump level used in creating the
-dump. A value of C<0> indicates a full dump. A value of
-C<1> or greater indicates an incremental dump made at the indicated
-depth in the hierarchy. The value reported is for the entire dump, not
-necessarily for the volume itself; for example, it is possible for a dump
-performed at an incremental level to include a full dump of an individual
-volume if the volume was omitted from previous dumps.
+dump. A value of C<0> indicates a full dump. A value of C<1> or greater
+indicates an incremental dump made at the indicated depth in the
+hierarchy. The value reported is for the entire dump, not necessarily for
+the volume itself; for example, it is possible for a dump performed at an
+incremental level to include a full dump of an individual volume if the
+volume was omitted from previous dumps.
-=item C<parentID
->
+=item parentID
-The dump ID number of C<dumpSetName>'s parent dump. It
-is C<0> if the value in the C<level> field is
-C<0>.
+The dump ID number of C<dumpSetName>'s parent dump. It is C<0> if the
+value in the C<level> field is C<0>.
-=item C<endTime
->
+=item endTime
Is always C<0>; it is reserved for internal use.
-=item C<cloneDate
->
+=item cloneDate
The date and time at which the volume was created. For a backup or
read-only volume, this represents the time at which it was cloned from its
-read/write source. For a read/write volume, it indicates the time at
-which the Backup System locked the volume for purposes of including it in the
+read/write source. For a read/write volume, it indicates the time at which
+the Backup System locked the volume for purposes of including it in the
dump named in the C<dumpSetName> field.
=back
-The message C<Scantape: Finished> indicates the completion of
-the output.
+The message C<Scantape: Finished> indicates the completion of the output.
-In normal circumstances, the Backup System writes a marker to indicate that
-a volume is the last one on a tape, or that the volume continues on the next
-tape. However, if a backup operation terminated abnormally (for
-example, because the operator terminated the Tape Coordinator by issuing the
-<B<Ctrl-c>> command during the operation), then there is no such
-marker. Some very early versions of the Backup System also did not
-write these markers. If a tape does not conclude with one of the
-expected markers, the Tape Coordinator cannot determine if there is a
-subsequent tape in the dump set and so generates the following message in its
-window:
+In normal circumstances, the Backup System writes a marker to indicate
+that a volume is the last one on a tape, or that the volume continues on
+the next tape. However, if a backup operation terminated abnormally (for
+example, because the operator terminated the Tape Coordinator by issuing
+the Ctrl-C command during the operation), then there is no such
+marker. Some very early versions of the Backup System also did not write
+these markers. If a tape does not conclude with one of the expected
+markers, the Tape Coordinator cannot determine if there is a subsequent
+tape in the dump set and so generates the following message in its window:
Are there more tapes? (y/n)
=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_dump(1)>,
-L<backup_dumpinfo(1)>,
+L<backup(8)>,
+L<backup_dump(8)>,
+L<backup_dumpinfo(8)>,
L<butc(1)>
=head1 COPYRIGHT
=head1 SYNOPSIS
-B<backup setexp -dump> <I<dump level name>>+ [-expires <I<expiration date>>+]
-[B<-localauth>] [B<-cell> <I<cell name>>] [B<-help>]
+B<backup setexp> B<-dump> <I<dump level name>>+
+ [B<-expires> <I<expiration date>>+] [B<-localauth>]
+ [B<-cell> <I<cell name>>] [B<-help>]
-B<backup se -d> <I<dump level name>>+ [-e <I<expiration date>>+]
-[B<-l>] [B<-c> <I<cell name>>] [B<-h>]
+B<backup se> B<-d> <I<dump level name>>+ [B<-e> <I<expiration date>>+]
+ [B<-l>] [B<-c> <I<cell name>>] [B<-h>]
=head1 DESCRIPTION
-The backup setexp command sets or changes the expiration date
+The B<backup setexp> command sets or changes the expiration date
associated with each specified dump level, which must already exist in 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
+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.)
=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
=over 4
-=item -dump
+=item B<-dump> <I<dump level name>>+
Specifies the full pathname of each dump level to assign the expiration
date specified by the B<-expires> argument.
-=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 <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 example associates an absolute expiration date of 10:00
-p.m. on 31 December 1999 with the dump level
-B</1998/december>:
+p.m. on 31 December 1999 with the dump level C</1998/december>:
% backup setexp -dump /1998/december -expires at 12/31/1999 22:00
The following example associates a relative expiration date of 7 days with
-the two dump levels B</monthly/week1> and
-B</monthly/week2>:
+the two dump levels C</monthly/week1> and C</monthly/week2>:
% backup setexp -dump /monthly/week1 /monthly/week -expires 7d
=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_listdumps(1)>
+L<backup(8)>,
+L<backup_adddump(8)>,
+L<backup_deldump(8)>,
+L<backup_listdumps(8)>
=head1 COPYRIGHT
=head1 SYNOPSIS
-B<backup status> [-portoffset <I<TC port offset>>]
-[B<-localauth>] [B<-cell> <I<cell name>>] [B<-help>]
+B<backup status> [B<-portoffset> <I<TC port offset>>] [B<-localauth>]
+ [B<-cell> <I<cell name>>] [B<-help>]
-B<backup st> [B<-p> <I<TC port offset>>] [B<-l>] [B<-c> <I<cell name>>] [-h]
+B<backup st> [B<-p> <I<TC port offset>>] [B<-l>] [B<-c> <I<cell name>>]
+ [B<-h>]
=head1 DESCRIPTION
-The backup status command displays which operation, if any, the
+The B<backup status> command displays which operation, if any, the
indicated Tape Coordinator is currently executing.
=head1 OPTIONS
=over 4
-=item -portoffset
+=item B<-portoffset> <I<TC port offset>>
Specifies the port offset number of the Tape Coordinator for which to
report the status.
-=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
Otherwise, the output includes a message of the following format for each
running or pending operation:
- Task I<task_ID>: I<operation>: I<status>
+ Task <task_ID>: <operation>: <status>
where
=over 4
-=item I<task_ID
->
+=item <task_ID>
-Is a task identification number assigned by the Tape Coordinator.
-It begins with the Tape Coordinator's port offset number.
+Is a task identification number assigned by the Tape Coordinator. It
+begins with the Tape Coordinator's port offset number.
-=item I<operation
->
+=item <operation>
Identifies the operation the Tape Coordinator is performing, which is
initiated by the indicated command:
=over 4
-=item *
+=item Dump
-C<Dump> (the backup dump command)
+The B<backup dump> command.
+=item Restore
-=item *
+The B<backup diskrestore>, B<backup volrestore>, or B<backup
+volsetrestore> commands.
-C<Restore> (the B<backup diskrestore>, backup
-volrestore, or B<backup volsetrestore> commands)
+=item Labeltape
+The B<backup labeltape> command.
-=item *
+=item Scantape
-C<Labeltape> (the backup labeltape command)
+The B<backup scantape> command.
+=item SaveDb
-=item *
+The B<backup savedb> command.
-C<Scantape> (the backup scantape command)
-
-
-=item *
-
-C<SaveDb> (the backup savedb command)
-
-
-=item *
-
-C<RestoreDb> (the backup restoredb command)
+=item RestoreDb
+The B<backup restoredb> command.
=back
-=item I<status
->
+=item <status>
-Indicates the job's current status in one of the following
-messages.
+Indicates the job's current status in one of the following messages.
=over 4
-=item I<number C<Kbytes transferred, volume> I<volume_name>
->
+=item I<number> Kbytes transferred, 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 B<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.
=back
-If the Tape Coordinator is communicating with an XBSA server (a third-party
-backup utility that implements the Open Group's Backup Service API
-[XBSA]), the following message appears last in the output:
+If the Tape Coordinator is communicating with an XBSA server (a
+third-party backup utility that implements the Open Group's Backup Service
+API [XBSA]), the following message appears last in the output:
- I<XBSA_program> Tape coordinator
+ <XBSA_program> Tape coordinator
-where I<XBSA_program> is the name of the XBSA-compliant
-program.
+where <XBSA_program> is the name of the XBSA-compliant program.
=head1 EXAMPLES
The following example shows that the Tape Coordinator with port offset 4
-has so far dumped about 1.5 MB of data for the current dump operation,
-and is currently dumping the volume named
-B<user.pat.backup>:
+has so far dumped about 1.5 MB of data for the current dump operation, and
+is currently dumping the volume named C<user.pat.backup>:
% backup status -portoffset 4
Task 4001: Dump: 1520 Kbytes transferred, volume user.pat.backup
=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<butc(1)>
+L<backup(8)>,
+L<butc(8)>
=head1 COPYRIGHT
=head1 SYNOPSIS
-backup volinfo -volume <I<volume name>>
-[B<-localauth>] [B<-cell> <I<cell name>>] [B<-help>]
+B<backup volinfo> B<-volume> <I<volume name>> [B<-localauth>]
+ [B<-cell> <I<cell name>>] [B<-help>]
-B<backup voli -v> <I<volume name>> [B<-l>] [B<-c> <I<cell name>>] [-h]
+B<backup voli> B<-v> <I<volume name>> [B<-l>] [B<-c> <I<cell name>>] [B<-h>]
=head1 DESCRIPTION
-The backup volinfo command displays a dump history of the
-specified volume, reporting information such as the date on which the volume
-was dumped and the tapes that contain it. Include the
-B<.backup> extension on the volume name if the backup version
-of the volume was dumped.
+The B<backup volinfo> command displays a dump history of the specified
+volume, reporting information such as the date on which the volume was
+dumped and the tapes that contain it. Include the C<.backup> extension on
+the volume name if the backup version of the volume was dumped.
=head1 OPTIONS
=over 4
-=item -volume
+=item B<-volume> <I<volume name>>
-Names the volume for which to display the dump history. Include
-theC< .backup> or C<.readonly> extension if the
-backup or read-only version of the volume was dumped.
+Names the volume for which to display the dump history. Include the
+C<.backup> or C<.readonly> extension if the backup or read-only version of
+the volume was dumped.
-=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 output includes a line for each Backup Database dump record that
-mentions the specified volume, order from most to least recent. The
-output for each record appears in a table with six columns:
+mentions the specified volume, order from most to least recent. The output
+for each record appears in a table with six columns:
=over 4
-=item C<dumpID
->
+=item dumpID
The dump ID of the dump that includes the volume.
-=item C<lvl
->
+=item lvl
The depth in the dump hierarchy of the dump level at which the volume was
-dumped. A value of C<0> indicates a full dump. A value
-of C<1> or greater indicates an incremental dump made at the specified
-depth in the dump hierarchy.
+dumped. A value of C<0> indicates a full dump. A value of C<1> or greater
+indicates an incremental dump made at the specified depth in the dump
+hierarchy.
-=item C<parentid
->
+=item parentid
-The dump ID of the dump's parent dump. A value of C<0>
-indicates a full dump, which has no parent; in this case, the value in
-the C<lvl> column is also C<0>.
+The dump ID of the dump's parent dump. A value of C<0> indicates a full
+dump, which has no parent; in this case, the value in the C<lvl> column is
+also C<0>.
-=item C<creation date
->
+=item creation date
The date and time at which the Backup System started the dump operation
that created the dump.
-=item C<clone date
->
+=item clone date
For a backup or read-only volume, the time at which it was cloned from its
-read/write source. For a read/write volume, the same as the value in
-the C<creation date> field.
-
-=item C<tape name
->
-
-The name of the tape containing the dump: either the permanent tape
-name, or an AFS tape name in the format
-I<volume_set_name>.I<dump_level_name>.I<tape_index>
-where I<volume_set_name> is the name of the volume set associated with
-the initial dump in the dump set of which this tape is a part;
-I<dump_level_name> is the name of the dump level at which the initial
-dump was backed up; I<tape_index> is the ordinal of the tape in
-the dump set. Either type of name can be followed by a dump ID in
-parentheses; if it appears, it is the dump ID of the initial dump in the
-dump set to which this appended dump belongs.
+read/write source. For a read/write volume, the same as the value in the
+C<creation date> field.
+
+=item tape name
+
+The name of the tape containing the dump: either the permanent tape name,
+or an AFS tape name in the format
+I<volume_set_name>.I<dump_level_name>.I<tape_index> where
+I<volume_set_name> is the name of the volume set associated with the
+initial dump in the dump set of which this tape is a part;
+I<dump_level_name> is the name of the dump level at which the initial dump
+was backed up; I<tape_index> is the ordinal of the tape in the dump
+set. Either type of name can be followed by a dump ID in parentheses; if
+it appears, it is the dump ID of the initial dump in the dump set to which
+this appended dump belongs.
=back
=head1 EXAMPLES
The following example shows part of the dump history of the Backup volume
-B<user.smith.backup>:
+C<user.smith.backup>:
% backup volinfo -volume user.smith.backup
DumpID lvl parentID creation date clone date tape name
=head1 SEE ALSO
-L<backup(1)>,
-L<backup_dumpinfo(1)>,
-L<backup_volrestore(1)>
+L<backup(8)>,
+L<backup_dumpinfo(8)>,
+L<backup_volrestore(8)>
=head1 COPYRIGHT
=head1 SYNOPSIS
-backup volrestore -server <I<destination machine>>
-B<-partition> <I<destination partition>>
- -volume <I<volume(s) to restore>>+
- [-extension <I<new volume name extension>>]
- [-date <I<date from which to restore>>+]
- [B<-portoffset> <I<TC port offsets>>+] [-n]
- [B<-localauth>] [B<-cell> <I<cell name>>] [-help]
-
-B<backup volr -s> <I<destination machine>> -pa <I<destination partition>>
-B<-v> <I<volume(s) to restore>>+ [B<-e> <I<new volume name extension>>]
- [B<-d> <I<date from which to restore>>+] [-po <I<TC port offsets>>+]
- [B<-n>] [B<-l>] [B<-c> <I<cell name>>] [-h]
+B<backup volrestore> B<-server> <I<destination machine>>
+ B<-partition> <I<destination partition>>
+ B<-volume> <I<volume(s) to restore>>+
+ [B<-extension> <I<new volume name extension>>]
+ [B<-date> <I<date from which to restore>>+]
+ [B<-portoffset> <I<TC port offsets>>+] [B<-n>]
+ [B<-localauth>] [B<-cell> <I<cell name>>] [B<-help>]
+
+B<backup volr> B<-s> <I<destination machine>>
+ B<-pa> <I<destination partition>> B<-v> <I<volume(s) to restore>>+
+ [B<-e> <I<new volume name extension>>]
+ [B<-d> <I<date from which to restore>>+] [B<-po> <I<TC port offsets>>+]
+ [B<-n>] [B<-l>] [B<-c> <I<cell name>>] [B<-h>]
=head1 DESCRIPTION
-The backup volrestore command restores the contents of one or
-more volumes to the site indicated by the B<-server> and
-B<-partition> arguments. Use the command either to overwrite
-the contents of existing volumes with the restored data or to create new
-volumes while retaining the existing ones. The specified site does not
-have to be the current site for the volumes.
-
-(If the FILE YES instruction appears in the
-B</usr/afs/backup/CFG_>I<device_name> file associated with the
-specified port offset, then the B<backup volrestore> command restores
-data from the backup data file listed for that port offset in the Tape
-Coordinator's B</usr/afs/backup/tapeconfig> file, rather than
-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 B<backup volrestore> command restores the contents of one or more
+volumes to the site indicated by the B<-server> and B<-partition>
+arguments. Use the command either to overwrite the contents of existing
+volumes with the restored data or to create new volumes while retaining
+the existing ones. The specified site does not have to be the current site
+for the volumes.
+
+(If the C<FILE YES> instruction appears in the
+F</usr/afs/backup/CFG_I<device_name>> file associated with the specified
+port offset, then the B<backup volrestore> command restores data from the
+backup data file listed for that port offset in the Tape Coordinator's
+F</usr/afs/backup/tapeconfig> file, rather than 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 command's arguments can be combined as indicated:
=item *
-To preserve a volume's current contents and also create a new volume
-to house the restored version, use the B<-extension> argument.
-The Backup System creates the new volume on the server and partition named by
-the B<-server> and B<-partition> arguments, assigns it the
-same name as the current volume with the addition of the specified extension,
-and creates a new Volume Location Database (VLDB) entry for it.
-Creating a new volume enables the administrator to compare the two
-versions.
-
+To preserve a volume's current contents and also create a new volume to
+house the restored version, use the B<-extension> argument. The Backup
+System creates the new volume on the server and partition named by the
+B<-server> and B<-partition> arguments, assigns it the same name as the
+current volume with the addition of the specified extension, and creates a
+new Volume Location Database (VLDB) entry for it. Creating a new volume
+enables the administrator to compare the two versions.
=item *
-To overwrite a volume's existing contents with the restored version,
-omit the B<-extension> argument, and specify the site as
-indicated:
-
+To overwrite a volume's existing contents with the restored version, omit
+the B<-extension> argument, and specify the site as indicated:
=over 4
=item *
-To retain the current site, specify it with the -server and
+To retain the current site, specify it with the B<-server> and
B<-partition> arguments.
-
=item *
To move the volume to a different site while overwriting it, specify the
-new site with the B<-server> argument, B<-partition> argument,
-or both. The Backup System creates a new volume at that site, removes
-the existing volume, and updates the site information in the volume's
-VLDB entry. The backup version of the volume is not removed
-automatically from the original site, if it exists. Use the B<vos
-remove> command to remove it and the B<vos backup> command to
-create a backup version at the new site.
-
+new site with the B<-server> argument, B<-partition> argument, or
+both. The Backup System creates a new volume at that site, removes the
+existing volume, and updates the site information in the volume's VLDB
+entry. The backup version of the volume is not removed automatically from
+the original site, if it exists. Use the B<vos remove> command to remove
+it and the B<vos backup> command to create a backup version at the new
+site.
=back
=item *
To restore a volume that no longer exists in the file system, specify its
-name with the B<-volume> argument and use the B<-server> and
-B<-partition> arguments to place it at the desired site. The
-Backup System creates a new volume and new VLDB entry.
-
+name with the B<-volume> argument and use the B<-server> and B<-partition>
+arguments to place it at the desired site. The Backup System creates a new
+volume and new VLDB entry.
=back
-In each case, the command sets each volume's creation date to the date
-and time at which it restores it. The creation date appears in the
-C<Creation> field in the output from the B<vos examine> and
-B<vos listvol> commands.
+In each case, the command sets each volume's creation date to the date and
+time at which it restores it. The creation date appears in the C<Creation>
+field in the output from the B<vos examine> and B<vos listvol> commands.
If restoring all of the volumes that resided on a single partition, it is
-usually more efficient to use the B<backup diskrestore>
-command. If restoring multiple volumes to many different sites, it can
-be more efficient to use the B<backup volsetrestore> command.
-
-By default, the backup volrestore command restores the most
-recent full dump and all subsequent incremental dumps for each volume,
-bringing the restored volumes to the most current possible state. To
-restore the volumes to their state at some time in the past, use the
-B<-date> argument. The Backup System restores the most recent
-full dump and each subsequent incremental dump for which the I<clone
-date> of the volume included in the dump is before the indicated date and
-time (the clone date timestamp appears in the C<clone date> field of
-the output from the B<backup volinfo> command). For backup and
-read-only volumes, the clone date represents the time at which the volume was
-copied from its read/write source; for read/write volumes, it represents
-the time at which the volume was locked for inclusion in the dump. The
-resemblance of a restored volume to its actual state at the indicated time
-depends on the amount of time that elapsed between the volume's clone
-date in the last eligible dump and the specified time.
-
-If the -volume argument specifies the base (read/write) form of
-the volume name, the Backup System searches the Backup Database for the newest
-dump set that includes a dump of either the read/write or the backup version
-of the volume. It restores the dumps of that version of the volume,
-starting with the most recent full dump. If, in contrast, the volume
-name explicitly includes the B<.backup> or
-B<.readonly> extension, the Backup System restores dumps of the
-corresponding volume version only.
+usually more efficient to use the B<backup diskrestore> command. If
+restoring multiple volumes to many different sites, it can be more
+efficient to use the B<backup volsetrestore> command.
+
+By default, the backup volrestore command restores the most recent full
+dump and all subsequent incremental dumps for each volume, bringing the
+restored volumes to the most current possible state. To restore the
+volumes to their state at some time in the past, use the B<-date>
+argument. The Backup System restores the most recent full dump and each
+subsequent incremental dump for which the I<clone date> of the volume
+included in the dump is before the indicated date and time (the clone date
+timestamp appears in the C<clone date> field of the output from the
+B<backup volinfo> command). For backup and read-only volumes, the clone
+date represents the time at which the volume was copied from its
+read/write source; for read/write volumes, it represents the time at which
+the volume was locked for inclusion in the dump. The resemblance of a
+restored volume to its actual state at the indicated time depends on the
+amount of time that elapsed between the volume's clone date in the last
+eligible dump and the specified time.
+
+If the B<-volume> argument specifies the base (read/write) form of the
+volume name, the Backup System searches the Backup Database for the newest
+dump set that includes a dump of either the read/write or the backup
+version of the volume. It restores the dumps of that version of the
+volume, starting with the most recent full dump. If, in contrast, the
+volume name explicitly includes the C<.backup> or C<.readonly> extension,
+the Backup System restores dumps of the corresponding volume version only.
To generate a list of the tapes the Backup System needs to perform the
-restore operation, without actually performing it, combine the B<-n>
-flag with the options to be used on the actual command.
+restore operation, without actually performing it, combine the B<-n> flag
+with the options to be used on the actual command.
If all of the full and incremental dumps of all relevant volumes were not
written to a type of tape that a single Tape Coordinator can read, 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
+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). If restoring multiple volumes, the same ordered list of port
-offsets must apply to all of them. If not, either issue this command
-separately for each volume, or use the B<vos volsetrestore> command
-after defining groups of volumes that were dumped to compatible tape
-types. For further discussion, see the I<IBM AFS Administration
-Guide>.
-
-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</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>
+on). If restoring multiple volumes, the same ordered list of port offsets
+must apply to all of them. If not, either issue this command separately
+for each volume, or use the B<vos volsetrestore> command after defining
+groups of volumes that were dumped to compatible tape types. For further
+discussion, see the I<IBM AFS Administration Guide>.
+
+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
+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, 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.
+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 OPTIONS
=over 4
-=item -server
+=item B<-server> <I<destination machine>>
-Names the file server machine on which to restore each volume. If
-this argument and the B<-partition> argument indicate a site other
-than the current site for each volume, and the B<-extension> argument
-is not also provided, the Backup System removes the existing volumes from
-their current sites, places the restored contents at the specified site, and
+Names the file server machine on which to restore each volume. If this
+argument and the B<-partition> argument indicate a site other than the
+current site for each volume, and the B<-extension> argument is not also
+provided, the Backup System removes the existing volumes from their
+current sites, places the restored contents at the specified site, and
changes the site information in the volume's VLDB entry.
-=item -partition
+=item B<-partition> <I<destination partition>>
-Names the partition to which to restore each volume. If this
-argument and the B<-server> argument indicate a site other than the
-current site for each volume, and the B<-extension> argument is not
-also provided, the Backup System removes the existing volumes from their
-current sites, places the restored contents at the specified site, and changes
-the site information in the volume's VLDB entry.
+Names the partition to which to restore each volume. If this argument and
+the B<-server> argument indicate a site other than the current site for
+each volume, and the B<-extension> argument is not also provided, the
+Backup System removes the existing volumes from their current sites,
+places the restored contents at the specified site, and changes the site
+information in the volume's VLDB entry.
-=item -volume
+=item B<-volume> <I<volume to restore>>+
Names one or more volumes to restore, using the volume name as listed in
-the Backup Database. Provide the base (read/write) name of each volume
-to have the Backup System search the Backup Database for the newest dump set
+the Backup Database. Provide the base (read/write) name of each volume to
+have the Backup System search the Backup Database for the newest dump set
that includes a dump of either the read/write or the backup version of the
-volume; it restores the dumps of that version of the volume, starting
-with the most recent full dump. If, in contrast, a volume name
-explicitly includes the B<.backup> or
-B<.readonly> extension, the Backup System restores dumps of the
-corresponding volume version only.
+volume; it restores the dumps of that version of the volume, starting with
+the most recent full dump. If, in contrast, a volume name explicitly
+includes the C<.backup> or C<.readonly> extension, the Backup System
+restores dumps of the corresponding volume version only.
-=item -extension
+=item B<-extension> <I<new volume name extension>>
Creates a new volume to house the restored data, with a name derived by
appending the specified string to each volume named by the B<-volume>
-argument. The Backup System creates a new VLDB entry for the
-volume. Any string other than B<.readonly> or
-B<.backup> is acceptable, but the combination of the existing
-volume 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 -date
-
-Specifies a date and optionally time; the restored volume includes
-data from dumps performed before the date only. Provide a value in the
-format I<mm>/I<dd>/I<yyyy> [I<hh>:I<MM>],
-where the required I<mm/dd/yyyy> portion indicates the month
-(I<mm>), day (I<dd>), and year (I<yyyy>), and the optional
-I<hh:MM> portion indicates the hour and minutes in 24-hour format
-(for example, the value B<14:36> represents 2:36
-p.m.). If omitted, the time defaults to 59 seconds after
-midnight (00:00:59 hours).
-
-Valid values for the year range from 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.
+argument. The Backup System creates a new VLDB entry for the volume. Any
+string other than C<.readonly> or C<.backup> is acceptable, but the
+combination of the existing volume 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<-date> <I<date from which to restore>>+
+
+Specifies a date and optionally time; the restored volume includes data
+from dumps performed before the date only. Provide a value in the format
+I<mm/dd/yyyy> [I<hh>:I<MM>], where the required I<mm/dd/yyyy> portion
+indicates the month (I<mm>), day (I<dd>), and year (I<yyyy>), and the
+optional I<hh:MM> portion indicates the hour and minutes in 24-hour format
+(for example, the value C<14:36> represents 2:36 p.m.). If omitted, the
+time defaults to 59 seconds after midnight (00:00:59 hours).
+
+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 any later date to the maximum value.
If this argument is omitted, the Backup System restores all possible dumps
including the most recently created.
-=item -portoffset
+=item B<-portoffset> <I<TC port offest>>+
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 all dumps at 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 -n
+=item B<-n>
Displays the list of tapes that contain the dumps required by the restore
operation, 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
=head1 OUTPUT
-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
-complete 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 complete
+the restore operation.
Tapes needed:
=head1 EXAMPLES
-The following command restores the volume user.pat to
-partition B</vicepa> on machine
-B<fs5.abc.com>:
+The following command restores the volume user.pat to partition F</vicepa>
+on machine C<fs5.abc.com>:
% backup volrestore -server fs5.abc.com -partition a -volume user.pat
-The following command restores the volumes user.smith and
-B<user.terry> to partition B</vicepb> on machine
-B<fs4.abc.com>, adding a B<.rst>
-extension to each volume name and preserving the existing
-B<user.smith> and B<user.terry> volumes.
-Only dumps created before 5:00 p.m. on 31 January 1998 are
-restored. (The command is shown here on multiple lines only for
-legibility reasons.)
+The following command restores the volumes C<user.smith> and C<user.terry>
+to partition F</vicepb> on machine C<fs4.abc.com>, adding a C<.rst>
+extension to each volume name and preserving the existing C<user.smith>
+and C<user.terry> volumes. Only dumps created before 5:00 p.m. on 31
+January 1998 are restored. (The command is shown here on multiple lines
+only for legibility reasons.)
% backup volrestore -server fs4.abc.com -partition b \
-volume user.smith user.terry \
-extension .rst -date 1/31/1998 17:00
-The following command restores the volume user.pat to
-partition B</vicepb> on machine
-B<fs4.abc.com>. The Tape Coordinator with port
-offset 1 handles the tape containing the full dump; the Tape Coordinator
-with port offset 0 handles all tapes containing incremental dumps. (The
-command is shown here on two lines only for legibility reasons.)
+The following command restores the volume user.pat to partition F</vicepb>
+on machine C<fs4.abc.com>. The Tape Coordinator with port offset 1 handles
+the tape containing the full dump; the Tape Coordinator with port offset 0
+handles all tapes containing incremental dumps. (The command is shown here
+on two lines only for legibility reasons.)
% backup volrestore -server fs5.abc.com -partition a \
-volume user.pat -portoffset 1 0
=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_diskrestore(1)>,
-L<backup_volsetrestore(1)>,
-L<butc(1)>,
+L<backup(8)>,
+L<backup_dump(8)>,
+L<backup_diskrestore(8)>,
+L<backup_volsetrestore(8)>,
+L<butc(8)>,
L<vos_backup(1)>,
L<vos_remove(1)>
=head1 SYNOPSIS
-B<backup volsetrestore> [B<-name> <I<volume set name>>] [-file <I<file name>>]
-[B<-portoffset> <I<TC port offset>>+]
- [-extension <I<new volume name extension>>]
- [B<-n>] [B<-localauth>] [B<-cell> <I<cell name>>] [-help]
+B<backup volsetrestore> [B<-name> <I<volume set name>>]
+ [B<-file> <I<file name>>] [B<-portoffset> <I<TC port offset>>+]
+ [B<-extension> <I<new volume name extension>>] [B<-n>]
+ [B<-localauth>] [B<-cell> <I<cell name>>] [B<-help>]
-B<backup vols> [B<-na> <I<volume set name>>] [-f <I<file name>>]
-[B<-p> <I<TC port offset>>+] [B<-e> <I<new volume name extension>>]
- [B<-n>] [B<-l>] [B<-c> <I<cell name>>] [-h]
+B<backup vols> [B<-na> <I<volume set name>>] [B<-f> <I<file name>>]
+ [B<-p> <I<TC port offset>>+] [B<-e> <I<new volume name extension>>]
+ [B<-n>] [B<-l>] [B<-c> <I<cell name>>] [B<-h>]
=head1 DESCRIPTION
-The backup volsetrestore command restores the complete contents
-of a group of read/write volumes to the file system, by restoring data from
-the last full dump and all subsequent incremental dumps of each volume.
-It is most useful for recovering from loss of data on multiple partitions,
-since it can restore each of a defined set of volumes to a different
-site.
-
-(If the FILE YES instruction appears in the
-B</usr/afs/backup/CFG_>I<device_name> file associated with the
-specified port offset, then the B<backup volsetrestore> command
-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.)
+The B<backup volsetrestore> command restores the complete contents of a
+group of read/write volumes to the file system, by restoring data from the
+last full dump and all subsequent incremental dumps of each volume. It is
+most useful for recovering from loss of data on multiple partitions, since
+it can restore each of a defined set of volumes to a different site.
+
+(If the C<FILE YES> instruction appears in the
+F</usr/afs/backup/CFG_I<device_name>> file associated with the specified
+port offset, then the B<backup volsetrestore> command 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.)
If restoring one or more volumes to a single site only, it is usually more
-efficient to use the B<backup volrestore> command. If restoring
-all volumes that resided on a single partition, it is usually more efficient
+efficient to use the B<backup volrestore> command. If restoring all
+volumes that resided on a single partition, it is usually more efficient
to use the B<backup diskrestore> command.
-Indicate the volumes to restore by providing either the -name
-argument or the B<-file> argument:
+Indicate the volumes to restore by providing either the B<-name> argument
+or the B<-file> argument:
=over 4
=item *
-The -name argument names a volume set. The Backup System
-restores all volumes listed in the Volume Location Database (VLDB) that match
-the server, partition, and volume name criteria defined in the volume
-set's volume entries, and for which dumps are available. It
-restores the volumes to their current site (machine and partition), and by
-default overwrites the existing volume contents.
-
+The B<-name> argument names a volume set. The Backup System restores all
+volumes listed in the Volume Location Database (VLDB) that match the
+server, partition, and volume name criteria defined in the volume set's
+volume entries, and for which dumps are available. It restores the volumes
+to their current site (machine and partition), and by default overwrites
+the existing volume contents.
It is not required that the volume set was previously used to back up
-volumes (was used as the B<-volumeset> option to the B<backup
-dump> command). It can be defined especially to match the volumes
-that need to be restored with this command, and that is usually the better
-choice. Indeed, a I<temporary> volume set, created by including
-the B<-temporary> flag to the B<backup addvolset> command, can
-be especially useful in this context. A temporary volume set is not
-added to the Backup Database and exists only during the current interactive
-backup session, which is suitable if the volume set is needed only to complete
-the single restore operation initialized by this command.
+volumes (was used as the B<-volumeset> option to the B<backup dump>
+command). It can be defined especially to match the volumes that need to
+be restored with this command, and that is usually the better
+choice. Indeed, a I<temporary> volume set, created by including the
+B<-temporary> flag to the B<backup addvolset> command, can be especially
+useful in this context. A temporary volume set is not added to the Backup
+Database and exists only during the current interactive backup session,
+which is suitable if the volume set is needed only to complete the single
+restore operation initialized by this command.
The reason that a specially defined volume set is probably better is that
-volume sets previously defined for use in dump operations usually match the
-backup version of volumes, whereas for a restore operation it is best to
-define volume entries that match the base (read/write) name. In that
-case, the Backup System searches the Backup Database for the newest dump set
-that includes either the read/write or the backup version of the
-volume. If, in contrast, a volume entry explicitly matches the
-volume's backup or read-only version, the Backup System restores dumps of
-that volume version only.
+volume sets previously defined for use in dump operations usually match
+the backup version of volumes, whereas for a restore operation it is best
+to define volume entries that match the base (read/write) name. In that
+case, the Backup System searches the Backup Database for the newest dump
+set that includes either the read/write or the backup version of the
+volume. If, in contrast, a volume entry explicitly matches the volume's
+backup or read-only version, the Backup System restores dumps of that
+volume version only.
=item *
-The -file argument names a file that lists specific volumes and
-the site to which to restore each. The volume name must match the name
-used in Backup Database dump records rather than in the VLDB, if they differ,
+The B<-file> argument names a file that lists specific volumes and the
+site to which to restore each. The volume name must match the name used in
+Backup Database dump records rather than in the VLDB, if they differ,
because the Backup System does not look up volumes in the VLDB. The
-specified site can be different than the volume's current one; in
-that case, the Backup System removes the current version of the volume and
+specified site can be different than the volume's current one; in that
+case, the Backup System removes the current version of the volume and
updates the volume's location information in the VLDB.
-
=back
If all of the full and incremental dumps of all relevant volumes were not
written to a type of tape that a single Tape Coordinator can read, 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
+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 use
-this command after defining new volume sets that group together volumes that
-were dumped to compatible tape types. For further discussion, see the
-I<IBM AFS Administration Guide>.
-
-By default, the Backup System overwrites the contents of an existing volume
-with the restored data. To create a new volume to house the restored
-version instead, use the B<-extension> argument. The Backup
+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 use this command after defining new volume sets that group
+together volumes that were dumped to compatible tape types. For further
+discussion, see the I<IBM AFS Administration Guide>.
+
+By default, the Backup System overwrites the contents of an existing
+volume with the restored data. To create a new volume to house the
+restored version instead, use the B<-extension> argument. The Backup
System derives the new volume's name by adding the specified extension to
-the read/write base name, 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.
-
-The -n flag produces a list of the volumes to be restored if the
-B<-n> flag were not included, without actually restoring any
-volumes. See the B<Output> section of this reference page for a
-detailed description of the output, and suggestions on how to combine it most
-effectively with the B<-file> and B<-name> arguments.
-
-The execution time for a backup volsetrestore command depends on
-the number of volumes to be restored and the amount of data in them, but it
-can take hours to restore a large number of volumes. One way to reduce
-the time is to run multiple instances of the command simultaneously, either
+the read/write base name, 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.
+
+The B<-n> flag produces a list of the volumes to be restored if the B<-n>
+flag were not included, without actually restoring any volumes. See
+L<OUTPUT> for a detailed description of the output, and suggestions on how
+to combine it most effectively with the B<-file> and B<-name> arguments.
+
+The execution time for a B<backup volsetrestore> command depends on the
+number of volumes to be restored and the amount of data in them, but it
+can take hours to restore a large number of volumes. One way to reduce the
+time is to run multiple instances of the command simultaneously, either
using the B<-name> argument to specify disjoint volume sets for each
command, or the B<-file> argument to name files that list different
volumes. This is possible if there are multiple available Tape
Coordinators that can read the required tapes. Depending on how the
-volumes to be restored were dumped to tape, specifying disjoint volume sets
-can also reduce the number of tape changes required.
-
-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</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>
+volumes to be restored were dumped to tape, specifying disjoint volume
+sets can also reduce the number of tape changes required.
+
+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</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, 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.
+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 OPTIONS
=over 4
-=item -name
+=item B<-name> <I<volume set name>>
-Names a volume set to restore. The Backup System restores all of
-the volumes listed in the VLDB that match the volume set's volume
-entries. Provide this argument or the B<-file> argument, but
-not both.
+Names a volume set to restore. The Backup System restores all of the
+volumes listed in the VLDB that match the volume set's volume
+entries. Provide this argument or the B<-file> argument, but not both.
-=item -file
+=item B<-file> <I<file name>>
Specifies the full pathname of a file that lists one or more volumes and
the site (file server machine and partition) to which to restore each.
-Use either this argument or the B<-name> argument, but not
-both.
+Use either this argument or the B<-name> argument, but not both.
-Each volume's entry must appear on its own (unbroken) line in the
-file, and have the following format:
+Each volume's entry must appear on its own (unbroken) line in the file,
+and have the following format:
- I<machine partition
- volume> [I<comments...>]
+ <machine> <partition> <volume> [<comments> ...]
where
=over 4
-=item I<machine
->
+=item <machine>
Names the file server machine to which to restore the volume.
-=item I<partition
->
+=item <partition>
Names the partition to which to restore the volume.
-=item I<volume
->
+=item <volume>
-Names the volume to restore. It is generally best to specify the
-base (read/write) name of each volume. In this case, the Backup System
-searches the Backup Database for the newest dump set that includes a dump of
-either the read/write or the backup version of the volume. It restores
-the dumps of that version of the volume, starting with the most recent full
-dump. If, in contrast, the name explicitly includes the
-B<.backup> or B<.readonly> extension, the Backup
-System restores dumps of that volume version only.
+Names the volume to restore. It is generally best to specify the base
+(read/write) name of each volume. In this case, the Backup System searches
+the Backup Database for the newest dump set that includes a dump of either
+the read/write or the backup version of the volume. It restores the dumps
+of that version of the volume, starting with the most recent full
+dump. If, in contrast, the name explicitly includes the C<.backup> or
+C<.readonly> extension, the Backup System restores dumps of that volume
+version only.
-=item I<comments...
->
+=item <comments> ...
-Is any other text. The Backup System ignores any text on each line
-that appears after the volume name, so this field can be used for notes
-helpful to the backup operator or other administrator.
+Is any other text. The Backup System ignores any text on each line that
+appears after the volume name, so this field can be used for notes helpful
+to the backup operator or other administrator.
=back
-Do not use wildcards (for example, .*) in the
-I<machine>, I<partition>, or I<volume> fields. It is
-acceptable for multiple lines in the file to name the same volume, but the
-Backup System processes only the first of them.
+Do not use wildcards (for example, C<.*>) in the <machine>, <partition>,
+or <volume> fields. It is acceptable for multiple lines in the file to
+name the same volume, but the Backup System processes only the first of
+them.
-=item -extension
+=item B<-extension> <I<new volume name extension>>
-Creates a new volume for each volume specified by the -name or
-B<-file> argument, to house the restored data from that volume.
-The Backup System derives the new volume's name by appending the
-specified string to the read/write base name, and creates a new VLDB volume
-entry. It preserves the contents of each existing volume. 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).
+Creates a new volume for each volume specified by the B<-name> or B<-file>
+argument, to house the restored data from that volume. The Backup System
+derives the new volume's name by appending the specified string to the
+read/write base name, and creates a new VLDB volume entry. It preserves
+the contents of each existing volume. 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 -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 all dumps at 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 -n
+=item B<-n>
Displays a list of the volumes to be restored if the flag were not
-included, without actually restoring them. The B<Output>
-section of this reference page details the format of the output. When
-combined with the B<-name> argument, its output is easily edited for
-use as input to the B<-file> argument on a subsequent B<backup
+included, without actually restoring them. L<OUTPUT> details the format of
+the output. When combined with the B<-name> argument, its output is easily
+edited for use as input to the B<-file> argument on a subsequent B<backup
volsetrestore> command.
-=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 -n flag is not provided, the command displays a unique
-task ID number for the operation, in two places:
+If the B<-n> flag is not provided, the command displays a unique task ID
+number for the operation, in two places:
=over 4
=item *
-In the shell window, directly following the command line
-
+In the shell window, directly following the command line.
=item *
-In the Tape Coordinator window, if the butc process was started
-at debug level 1
-
+In the Tape Coordinator window, if the butc process was started at debug
+level 1.
=back
The task ID number is not the same as the job ID number displayed by the
-B<(backup) jobs> command when the B<(backup) volsetrestore>
-command is issued in interactive mode. The Backup System does not
-assign either type of ID number until the restoration process actually
-begins.
-
-When the -n flag is included, no task ID or job ID numbers are
-reported because none are assigned. Instead, the output begins with a
-count of the number of volumes to be restored, followed by a line for each
-dump of a volume. For each volume, the line representing the most
-recent full dump appears first, and lines for any subsequent incremental dumps
-follow, ordered by dump level. The lines for a given volume do not
-necessarily appear all together, however.
+B<backup jobs> command when the B<backup volsetrestore> command is issued
+in interactive mode. The Backup System does not assign either type of ID
+number until the restoration process actually begins.
+
+When the B<-n> flag is included, no task ID or job ID numbers are reported
+because none are assigned. Instead, the output begins with a count of the
+number of volumes to be restored, followed by a line for each dump of a
+volume. For each volume, the line representing the most recent full dump
+appears first, and lines for any subsequent incremental dumps follow,
+ordered by dump level. The lines for a given volume do not necessarily
+appear all together, however.
The format of each line is as follows (the output is shown here on two
lines only for legibility reasons):
- I<machine partition volume_dumped> # as I<volume_restored>; I<tape_name> (I<tape_ID>); \
- pos I<position_number>; I<date>
+ <machine> <partition> <volume_dumped> # as <volume_restored>; \
+ <tape_name> (<tape_ID>); pos <position_number>; <date>
where
=over 4
-=item I<machine
->
+=item <machine>
Names the file server machine that currently houses the volume, as listed
in the VLDB.
-=item I<partition
->
+=item <partition>
Names the partition that currently houses the volume, as listed in the
VLDB.
-=item I<volume_dumped
->
+=item <volume_dumped>
Specifies the version (read/write or backup) of the volume that was
dumped, as listed in the Backup Database.
-=item I<volume_restored
->
+=item <volume_restored>
-Specifies the name under which to restore the volume. The Backup
-System only restores data to read/write volumes. If the
-B<-extension> argument is included, then the specified extension
-appears on the name in this field (for example,
-C<user.pat.rst>).
+Specifies the name under which to restore the volume. The Backup System
+only restores data to read/write volumes. If the B<-extension> argument is
+included, then the specified extension appears on the name in this field
+(for example, C<user.pat.rst>).
-=item I<tape_name
->
+=item <tape_name>
Names the tape containing the dump of the volume, from the Backup
-Database. If the tape has a permanent name, it appears here;
-otherwise, it is the AFS tape name.
+Database. If the tape has a permanent name, it appears here; otherwise, it
+is the AFS tape name.
-=item I<tape_ID
->
+=item <tape_ID>
The tape ID of the tape containing the dump of the volume, from the Backup
Database.
-=item I<position_number
->
+=item <position_number>
-Specifies the dump's position on the tape (for example, C<31>
-indicates that 30 volume dumps precede the current one on the tape). If
-the dump was written to a backup data file, this number is the ordinal of the
-16 KB-offset at which the volume's data begins.
+Specifies the dump's position on the tape (for example, C<31> indicates
+that 30 volume dumps precede the current one on the tape). If the dump was
+written to a backup data file, this number is the ordinal of the 16
+KB-offset at which the volume's data begins.
-=item I<date
->
+=item <date>
The date and time when the volume was dumped.
=back
-One way to generate a file for use as input to the -file
-argument is to combine the B<-name> and B<-n> options,
-directing the output to a file. The I<IBM AFS Administration
-Guide> section on using the Backup System to restore data explains how to
-edit the file as necessary before using it as input to the B<-file>
-argument.
+One way to generate a file for use as input to the B<-file> argument is to
+combine the B<-name> and B<-n> options, directing the output to a
+file. The I<IBM AFS Administration Guide> section on using the Backup
+System to restore data explains how to edit the file as necessary before
+using it as input to the B<-file> argument.
The output of this command includes only volumes for which the Backup
Database includes at least one dump record. The command interpreter
generates a message on the standard error stream about volumes that do not
-have dump records but either are listed in the file named by the
-B<-file> argument, or appear in the VLDB as a match to a volume entry
-in the volume set named by the B<-name> argument.
+have dump records but either are listed in the file named by the B<-file>
+argument, or appear in the VLDB as a match to a volume entry in the volume
+set named by the B<-name> argument.
=head1 EXAMPLES
The following command restores all volumes included in entries in the
-volume set named B<data.restore>, which was created expressly
-to restore data to a pair of file server machines on which all data was
-corrupted due to a software error. All volumes are restored to the
-sites recorded in their entries in the VLDB.
+volume set named C<data.restore>, which was created expressly to restore
+data to a pair of file server machines on which all data was corrupted due
+to a software error. All volumes are restored to the sites recorded in
+their entries in the VLDB.
% backup volsetrestore -name data.restore
Starting restore
backup: Finished doing restore
The following command restores all volumes that have entries in the file
-named B</tmp/restore>:
+named F</tmp/restore>:
% backup volsetrestore -file /tmp/restore
Starting restore
backup: task ID of restore operation: 113
backup: Finished doing restore
-The /tmp/restore file has the following contents:
+The F</tmp/restore> file has the following contents:
fs1.abc.com b user.pat
fs1.abc.com b user.terry
=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_addvolentry(1)>,
-L<backup_addvolset(1)>,
-L<backup_diskrestore(1)>,
-L<backup_dump(1)>,
-L<backup_volrestore(1)>,
-L<butc(1)>
+L<backup(8)>,
+L<backup_addvolentry(8)>,
+L<backup_addvolset(8)>,
+L<backup_diskrestore(8)>,
+L<backup_dump(8)>,
+L<backup_volrestore(8)>,
+L<butc(8)>
=head1 COPYRIGHT
=head1 DESCRIPTION
-The commands in the bos command suite are the administrative
-interface to the Basic OverSeer (BOS) Server, which runs on every file server
-machine to monitor the other server processes on it. If a process
-fails, the BOS Server can restart it automatically, taking into account
+The commands in the B<bos> command suite are the administrative interface
+to the Basic OverSeer (BOS) Server, which runs on every file server
+machine to monitor the other server processes on it. If a process fails,
+the BOS Server can restart it automatically, taking into account
interdependencies between it and other processes. The BOS Server frees
-system administrators from constantly monitoring the status of server machines
-and processes.
+system administrators from constantly monitoring the status of server
+machines and processes.
-There are several categories of commands in the bos command
-suite:
+There are several categories of commands in the B<bos> command suite:
=over 4
=item *
-Commands to administer server process binary files: bos
-getdate, B<bos install>, B<bos prune>, and B<bos
-uninstall>
-
+Commands to administer server process binary files: B<bos getdate>, B<bos
+install>, B<bos prune>, and B<bos uninstall>.
=item *
-Commands to maintain system configuration files: bos
-addhost, B<bos addkey>, B<bos adduser>, B<bos
-listhosts>, B<bos listkeys>, B<bos listusers>, B<bos
-removehost>, B<bos removekey>, B<bos removeuser>, and
-B<bos setcellname>
-
+Commands to maintain system configuration files: B<bos addhost>, B<bos
+addkey>, B<bos adduser>, B<bos listhosts>, B<bos listkeys>, B<bos
+listusers>, B<bos removehost>, B<bos removekey>, B<bos removeuser>, and
+B<bos setcellname>.
=item *
-Commands to start and stop processes: bos create,
-B<bos delete>, B<bos restart>, B<bos shutdown>,
-B<bos start>, B<bos startup>, and B<bos stop>
-
+Commands to start and stop processes: B<bos create>, B<bos delete>, B<bos
+restart>, B<bos shutdown>, B<bos start>, B<bos startup>, and B<bos stop>.
=item *
-Commands to set and verify server process and server machine status:
-B<bos getlog>, B<bos getrestart>, B<bos setauth>,
-B<bos setrestart>, and B<bos status>
-
+Commands to set and verify server process and server machine status: B<bos
+getlog>, B<bos getrestart>, B<bos setauth>, B<bos setrestart>, and B<bos
+status>.
=item *
-A command to restore file system consistency: bos salvage
-
+A command to restore file system consistency: B<bos salvage>.
=item *
-Commands to obtain help: B<bos apropos> and bos
-help
-
+Commands to obtain help: B<bos apropos> and B<bos help>.
=back
-The BOS Server and the bos commands use and maintain the
-following configuration and log files:
+The BOS Server and the B<bos> commands use and maintain the following
+configuration and log files:
=over 4
=item *
-The /usr/afs/etc/CellServDB file lists the local cell's
-database server machines. These machines run the Authentication,
-Backup, Protection and Volume Location (VL) Server processes, which maintain
-databases of administrative information. The database server processes
-consult the file to learn about their peers, whereas the other server
-processes consult it to learn where to access database information as
-needed. To administer the B<CellServDB> file, use the following
-commands: B<bos addhost>, B<bos listhosts>, B<bos
-removehost>, and B<bos setcellname>.
-
+The F</usr/afs/etc/CellServDB> file lists the local cell's database server
+machines. These machines run the Authentication, Backup, Protection and
+Volume Location (VL) Server processes, which maintain databases of
+administrative information. The database server processes consult the file
+to learn about their peers, whereas the other server processes consult it
+to learn where to access database information as needed. To administer the
+F<CellServDB> file, use the following commands: B<bos addhost>, B<bos
+listhosts>, B<bos removehost>, and B<bos setcellname>.
=item *
-The /usr/afs/etc/KeyFile file lists the server encryption keys
-that the server processes use to decrypt tickets presented by client processes
-and one another. To administer the B<KeyFile> file, use the
-following commands: B<bos addkey>, B<bos listkeys>, and
-B<bos removekey>.
-
+The F</usr/afs/etc/KeyFile> file lists the server encryption keys that the
+server processes use to decrypt tickets presented by client processes and
+one another. To administer the F<KeyFile> file, use the following
+commands: B<bos addkey>, B<bos listkeys>, and B<bos removekey>.
=item *
-The /usr/afs/etc/ThisCell file defines the cell to which the
-server machine belongs for the purposes of server-to-server
-communication. Administer it with the B<bos setcellname>
-command. There is also a B</usr/vice/etc/ThisCell> file that
-defines the machine's cell membership with respect to the AFS command
-suites and Cache Manager access to AFS data.
-
+The F</usr/afs/etc/ThisCell> file defines the cell to which the server
+machine belongs for the purposes of server-to-server communication.
+Administer it with the B<bos setcellname> command. There is also a
+F</usr/vice/etc/ThisCell> file that defines the machine's cell membership
+with respect to the AFS command suites and Cache Manager access to AFS
+data.
=item *
-The /usr/afs/etc/UserList file lists the user name of each
+The F</usr/afs/etc/UserList> file lists the user name of each
administrator authorized to issue privileged B<bos> and B<vos>
-commands. To administer the B<UserList> file, use the following
-commands: B<bos adduser>, B<bos listusers>, and B<bos
-removeuser>.
-
+commands. To administer the F<UserList> file, use the following commands:
+B<bos adduser>, B<bos listusers>, and B<bos removeuser>.
=item *
-The /usr/afs/local/BosConfig file defines which AFS server
-processes run on the server machine, and whether the BOS Server restarts them
+The F</usr/afs/local/BosConfig> file defines which AFS server processes
+run on the server machine, and whether the BOS Server restarts them
automatically if they fail. It also defines when all processes restart
automatically (by default once per week), and when the BOS Server restarts
processes that have new binary files (by default once per day). To
-administer the B<BosConfig> file, use the following commands:
-B<bos create>, B<bos delete>, B<bos getrestart>,
-B<bos setrestart>, B<bos start>, and B<bos
-stop>.
-
+administer the F<BosConfig> file, use the following commands: B<bos
+create>, B<bos delete>, B<bos getrestart>, B<bos setrestart>, B<bos
+start>, and B<bos stop>.
=item *
-The /usr/afs/log/BosLog file records important operations the
-BOS Server performs and error conditions it encounters.
-
+The F</usr/afs/log/BosLog> file records important operations the BOS
+Server performs and error conditions it encounters.
=back
=head1 OPTIONS
The following arguments and flags are available on many commands in the
-B<bos> suite. The reference page for each command also lists
-them, but they are described here in greater detail.
-L<(1)>
-L<(1)>
-L<(1)>
+B<bos> 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.
-L<(1)>
+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.
-=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)
-B<-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<bos> command interpreter presents the ticket, which
-never expires, to the BOS Server during mutual authentication.
+highest key version number in the local F</usr/afs/etc/KeyFile> file. The
+B<bos> command interpreter presents the ticket, which never expires, to
+the BOS 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. Also, do not combine the B<-localauth> and
+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. Also, do not combine the B<-localauth> and
B<-noauth> flags.
-=item L<(1)
-B<-noauth>
->
+=item B<-noauth>
Establishes an unauthenticated connection to the BOS Server, in which the
-BOS Server treats the issuer as the unprivileged user
-B<anonymous>. It is useful only when authorization checking is
-disabled on the server machine (during the installation of a file server
-machine or when the B<bos setauth> command has been used during other
-unusual circumstances). In normal circumstances, the BOS Server allows
-only privileged users to issue commands that change the status of a server or
-configuration file, and refuses to perform such an action even if the
-B<-noauth> flag is provided. Do not combine the
-B<-noauth> and B<-localauth> flags.
-
-=item -server <I<machine name>>
-L<(1)>
->
-
-Indicates the AFS server machine on which to run the command.
-Identify the machine by its IP address in dotted decimal format, its
-fully-qualified host name (for example, B<fs1.abc.com>),
-or by an abbreviated form of its host name that distinguishes it from other
+BOS Server treats the issuer as the unprivileged user C<anonymous>. It is
+useful only when authorization checking is disabled on the server machine
+(during the installation of a file server machine or when the B<bos
+setauth> command has been used during other unusual circumstances). In
+normal circumstances, the BOS Server allows only privileged users to issue
+commands that change the status of a server or configuration file, and
+refuses to perform such an action even if the B<-noauth> flag is
+provided. Do not combine the B<-noauth> and B<-localauth> flags.
+
+=item B<-server> <I<machine name>>
+
+Indicates the AFS server machine on which to run the command. Identify
+the machine by its IP address in dotted decimal format, its
+fully-qualified host name (for example, C<fs1.abc.com>), or by an
+abbreviated form of its host name that distinguishes it from other
machines. Successful use of an abbreviated form depends on the
availability of a name service (such as the Domain Name Service or a local
host table) at the time the command is issued.
For the commands that alter the administrative files shared by all server
-machines in the cell (the B<bos addhost>, B<bos addkey>,
-B<bos adduser>, B<bos removehost>, B<bos removekey>,
-and B<bos removeuser> commands), the appropriate machine depends on
-whether the cell uses the United States or international version of AFS:
+machines in the cell (the B<bos addhost>, B<bos addkey>, B<bos adduser>,
+B<bos removehost>, B<bos removekey>, and B<bos removeuser> commands), the
+appropriate machine depends on whether the cell uses the United States or
+international version of AFS:
=over 4
=item *
-If the cell runs the United States edition of AFS and (as recommended)
-uses the Update Server to distribute the contents of the
-B</usr/afs/etc> directory, provide the name of the system control
-machine. After issuing the command, allow up to five minutes for the
-Update Server to distribute the changed file to the other AFS server machines
-in the cell. If the specified machine is not the system control machine
-but is running an B<upclientetc> process that refers to the system
+If the cell (as recommended) uses the Update Server to distribute the
+contents of the F</usr/afs/etc> directory, provide the name of the system
+control machine. After issuing the command, allow up to five minutes for
+the Update Server to distribute the changed file to the other AFS server
+machines in the cell. If the specified machine is not the system control
+machine but is running an B<upclient> process that refers to the system
control machine, then the change will be overwritten when the process next
brings over the relevant file from the system control machine.
-
=item *
-If the cell runs the international edition of AFS, do not use the Update
-Server to distribute the contents of the B</usr/afs/etc>
-directory. Instead, repeatedly issue the command, naming each of the
-cell's server machines in turn. To avoid possible inconsistency
-problems, finish issuing the commands within a fairly short time.
-
+Otherwise, repeatedly issue the command, naming each of the cell's server
+machines in turn. To avoid possible inconsistency problems, finish issuing
+the commands within a fairly short time.
=back
=head1 PRIVILEGE REQUIRED
-To issue any bos command that changes a configuration file or
-alters process status, the issuer must be listed in the
-B</usr/afs/etc/UserList> file on the server machine named by the
-B<-server> argument. Alternatively, if the
-B<-localauth> flag is included the issuer must be logged on as the
-local superuser B<root>.
+To issue any bos command that changes a configuration file or alters
+process status, the issuer must be listed in the F</usr/afs/etc/UserList>
+file on the server machine named by the B<-server>
+argument. Alternatively, if the B<-localauth> flag is included the issuer
+must be logged on as the local superuser C<root>.
-To issue a bos command that only displays information (other
-than the B<bos listkeys> command), no privilege is required.
+To issue a bos command that only displays information (other than the
+B<bos listkeys> command), no privilege is required.
=head1 SEE ALSO
-L<BosConfig(1)>,
-L<CellServDB (client version)(1)>
-
-L<CellServDB (server version)(1)>
-
-L<KeyFile(1)>,
-L<ThisCell (client version)(1)>
-
-L<ThisCell (server version)(1)>
-
-L<UserList(1)>,
-L<bos_addhost(1)>,
-L<bos_addkey(1)>,
-L<bos_adduser(1)>,
-L<bos_apropos(1)>,
-L<bos_create(1)>,
-L<bos_delete(1)>,
-L<bos_exec(1)>,
-L<bos_getdate(1)>,
-L<bos_getlog(1)>,
-L<bos_getrestart(1)>,
-L<bos_help(1)>,
-L<bos_install(1)>,
-L<bos_listhosts(1)>,
-L<bos_listkeys(1)>,
-L<bos_listusers(1)>,
-L<bos_prune(1)>,
-L<bos_removehost(1)>,
-L<bos_removekey(1)>,
-L<bos_removeuser(1)>,
-L<bos_restart(1)>,
-L<bos_salvage(1)>,
-L<bos_setauth(1)>,
-L<bos_setcellname(1)>,
-L<bos_setrestart(1)>,
-L<bos_shutdown(1)>,
-L<bos_start(1)>,
-L<bos_startup(1)>,
-L<bos_status(1)>,
-L<bos_stop(1)>,
-L<bos_uninstall(1)>
+L<BosConfig(5)>,
+L<CellServDB(5)>,
+L<KeyFile(5)>,
+L<ThisCell(5)>,
+L<UserList(5)>,
+L<bos_addhost(8)>,
+L<bos_addkey(8)>,
+L<bos_adduser(8)>,
+L<bos_apropos(8)>,
+L<bos_create(8)>,
+L<bos_delete(8)>,
+L<bos_exec(8)>,
+L<bos_getdate(8)>,
+L<bos_getlog(8)>,
+L<bos_getrestart(8)>,
+L<bos_help(8)>,
+L<bos_install(8)>,
+L<bos_listhosts(8)>,
+L<bos_listkeys(8)>,
+L<bos_listusers(8)>,
+L<bos_prune(8)>,
+L<bos_removehost(8)>,
+L<bos_removekey(8)>,
+L<bos_removeuser(8)>,
+L<bos_restart(8)>,
+L<bos_salvage(8)>,
+L<bos_setauth(8)>,
+L<bos_setcellname(8)>,
+L<bos_setrestart(8)>,
+L<bos_shutdown(8)>,
+L<bos_start(8)>,
+L<bos_startup(8)>,
+L<bos_status(8)>,
+L<bos_stop(8)>,
+L<bos_uninstall(8)>
=head1 COPYRIGHT
=head1 NAME
-bos addhost - Adds a database server machine to the /usr/afs/etc/CellServDB
-file
+bos addhost - Adds a database server machine to the CellServDB file
=head1 SYNOPSIS
-B<bos addhost -server> <I<machine name>> -host <I<host name>>+
-[B<-cell> <I<cell name>>] [B<-noauth>] [B<-localauth>] [B<-help>]
+B<bos addhost> B<-server> <I<machine name>> B<-host> <I<host name>>+
+ [B<-cell> <I<cell name>>] [B<-noauth>] [B<-localauth>] [B<-help>]
-B<bos addh -s> <I<machine name>> -ho <I<host name>>+
-[B<-c> <I<cell name>>] [B<-n>] [B<-l>] [B<-he>]
+B<bos addh> B<-s> <I<machine name>> B<-ho> <I<host name>>+
+ [B<-c> <I<cell name>>] [B<-n>] [B<-l>] [B<-he>]
=head1 DESCRIPTION
-The bos addhost command adds an entry for each database server
-machine specified with the B<-host> argument to the
-B</usr/afs/etc/CellServDB> file on the machine named by the
-B<-server> argument.
+The B<bos addhost> command adds an entry for each database server machine
+specified with the B<-host> argument to the F</usr/afs/etc/CellServDB>
+file on the machine named by the B<-server> argument.
=head1 CAUTIONS
After executing this command (and waiting for the Update Server to
-propagate the changes, if it is used), restart the database server processes
-on all database server machines to force election of a quorum that includes
-the new set of machines listed in the B</usr/afs/etc/CellServDB>
-file. The I<IBM AFS Quick Beginnings> explains in more detail
-how to add and remove database server machines.
+propagate the changes, if it is used), restart the database server
+processes on all database server machines to force election of a quorum
+that includes the new set of machines listed in the
+F</usr/afs/etc/CellServDB> file. The I<IBM AFS Quick Beginnings> explains
+in more detail how to add and remove database server machines.
It is best to maintain a one-to-one mapping between hostnames and IP
addresses on a multihomed database server machine (this is actually the
-conventional configuration for any AFS machine). The BOS Server uses
-the B<gethostbyname( )> routine to obtain the IP address
-associated with the hostname specified by the B<-host>
-argument. If there is more than one address, the BOS Server records in
-the B<CellServDB> entry the one that appears first in the list of
-addresses returned by the routine. The routine possibly returns
-addresses in a different order on different machines, which can create
-inconsistency.
+conventional configuration for any AFS machine). The BOS Server uses the
+gethostbyname() routine to obtain the IP address associated with the
+hostname specified by the B<-host> argument. If there is more than one
+address, the BOS Server records in the F<CellServDB> entry the one that
+appears first in the list of addresses returned by the routine. The
+routine possibly returns addresses in a different order on different
+machines, which can create inconsistency.
=head1 OPTIONS
=over 4
-=item -server
->
+=item B<-server> <I<machine name>>
Identifies the server machine on which to change the
-B</usr/afs/etc/CellServDB> file. Identify the machine by IP
-address or its host name (either fully-qualified or abbreviated
-unambiguously). For details, see the introductory reference page for
-the B<bos> command suite.
+F</usr/afs/etc/CellServDB> file. Identify the machine by IP address or its
+host name (either fully-qualified or abbreviated unambiguously). For
+details, see L<bos(8)>.
-In cells that run the United States edition of AFS and use the Update
-Server to distribute the contents of the B</usr/afs/etc> directory, it
-is conventional to specify only the system control machine as a value for the
-B<-server> argument. In cells that run the international
-version of AFS, repeat the command for each file server machine. For
-further discussion, see the introductory reference page for the B<bos>
-command suite.
+In cells that use the Update Server to distribute the contents of the
+F</usr/afs/etc> directory, it is conventional to specify only the system
+control machine as a value for the B<-server> argument. Otherwise, repeat
+the command for each file server machine. For further discussion, see
+L<bos(8)>.
-=item -host
->
+=item B<-host> <I<host name>>+
-Specifies the fully-qualified host name (such as
-B<db1.abc.com>) of each database server machine to
-register in the B<CellServDB> file.
+Specifies the fully-qualified host name (such as C<db1.abc.com>) of each
+database server machine to register in the F<CellServDB> file.
-=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<bos> reference page.
+argument with the B<-localauth> flag. For more details, see L<bos(8)>.
-=item -noauth
->
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. Do not combine this flag with the B<-localauth>
-flag. For more details, see the introductory B<bos> reference
-page.
+Assigns the unprivileged identity C<anonymous> to the issuer. Do not combine
+this flag with the B<-localauth> flag. For more details, see L<bos(8)>.
-=item -localauth
->
+=item B<-localauth>
Constructs a server ticket using a key from the local
-B</usr/afs/etc/KeyFile> file. The B<bos> command
-interpreter presents the ticket to the BOS Server during mutual
-authentication. Do not combine this flag with the B<-cell> or
-B<-noauth> options. For more details, see the introductory
-B<bos> reference page.
+F</usr/afs/etc/KeyFile> file. The B<bos> command interpreter presents the
+ticket to the BOS Server during mutual authentication. Do not combine this
+flag with the B<-cell> or B<-noauth> options. For more details, see
+L<bos(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 the database server machines
-B<db2.abc.com> and B<db3.abc.com>
-to the B</usr/afs/etc/CellServDB> file on the machine
-B<fs1.abc.com> (the system control machine).
+The following command adds the database server machines C<db2.abc.com> and
+C<db3.abc.com> to the F</usr/afs/etc/CellServDB> file on the machine
+C<fs1.abc.com> (the system control machine).
% bos addhost -server fs1.abc.com -host db2.abc.com db3.abc.com
=head1 PRIVILEGE REQUIRED
-The issuer must be listed in the /usr/afs/etc/UserList file on
-the machine named by the B<-server> argument, 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 the
+machine named by the B<-server> argument, 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<CellServDB (server version)(1)>
-
-L<KeyFile(1)>,
-L<UserList(1)>,
-L<bos(1)>,
-L<bos_listhosts(1)>,
-L<bos_removehost(1)>
+L<CellServDB(5)>,
+L<KeyFile(5)>,
+L<UserList(5)>,
+L<bos(8)>,
+L<bos_listhosts(8)>,
+L<bos_removehost(8)>
I<IBM AFS Quick Beginnings>
=head1 NAME
-bos addkey - Adds a new server encryption key to the /usr/afs/etc/KeyFile
-file
+bos addkey - Adds a new server encryption key to the KeyFile file
=head1 SYNOPSIS
-B<bos addkey -server> <I<machine name>> [-key <I<key>>]
-B<-kvno> <I<key version number>> [B<-cell> <I<cell name>>]
- [B<-noauth>] [B<-localauth>] [-help]
+B<bos addkey> B<-server> <I<machine name>> [B<-key> <I<key>>]
+ B<-kvno> <I<key version number>> [B<-cell> <I<cell name>>]
+ [B<-noauth>] [B<-localauth>] [B<-help>]
-B<bos addk -s> <I<machine name>> [B<-ke> <I<key>>] -kv <I<key version number>>
-[B<-ce> <I<cell name>>] [B<-n>] [B<-l>] [B<-h>]
+B<bos addk> B<-s> <I<machine name>> [B<-ke> <I<key>>]
+ B<-kv> <I<key version number>> [B<-ce> <I<cell name>>] [B<-n>]
+ [B<-l>] [B<-h>]
=head1 DESCRIPTION
-The bos addkey command constructs a server encryption key from
-the text string provided, assigns it the key version number specified with the
-B<-kvno> argument, and adds it to the B</usr/afs/etc/KeyFile>
-file on the machine specified with the B<-server> argument. Be
-sure to use the B<kas setpassword> or B<kas setkey> command to
-add the same key to the B<afs> entry in the Authentication
-Database.
+The B<bos addkey> command constructs a server encryption key from the text
+string provided, assigns it the key version number specified with the
+B<-kvno> argument, and adds it to the F</usr/afs/etc/KeyFile> file on the
+machine specified with the B<-server> argument. Be sure to use the B<kas
+setpassword> or B<kas setkey> command to add the same key to the C<afs>
+entry in the Authentication Database.
-Do not use the -key argument, which echoes the password string
-visibly on the screen. If the argument is omitted, the BOS Server
-prompts for the string and does not echo it visibly:
+Do not use the B<-key> argument, which echoes the password string visibly
+on the screen. If the argument is omitted, the BOS Server prompts for the
+string and does not echo it visibly:
Input key:
Retype input key:
The BOS Server prohibits reuse of any key version number already listed in
-the B</usr/afs/etc/KeyFile> file. This ensures that users who
-still have tickets sealed with the current key are not prevented from
-communicating with a server process because the current key is overwritten
-with a new key. Use the B<bos listkeys> command to display the
-key version numbers in the B</usr/afs/etc/KeyFile> file.
+the F</usr/afs/etc/KeyFile> file. This ensures that users who still have
+tickets sealed with the current key are not prevented from communicating
+with a server process because the current key is overwritten with a new
+key. Use the B<bos listkeys> command to display the key version numbers in
+the F</usr/afs/etc/KeyFile> file.
=head1 OPTIONS
=over 4
-=item -server
->
+=item B<-server> <I<machine name>>
Indicates the server machine on which to change the
-B</usr/afs/etc/KeyFile> file. Identify the machine by IP
-address or its host name (either fully-qualified or abbreviated
-unambiguously). For details, see the introductory reference page for
-the B<bos> command suite.
-
-In cells that run the United States edition of AFS and use the Update
-Server to distribute the contents of the B</usr/afs/etc> directory, it
-is conventional to specify only the system control machine as a value for the
-B<-server> argument. In cells that run the international
-version of AFS, repeat the command for each file server machine. For
-further discussion, see the introductory reference page for the B<bos>
-command suite.
-
-=item -key
->
-
-Specifies a character string just like a password; the BOS Server
-calls a DES conversion function to encode it into a form appropriate for use
-as an encryption key. Omit this argument to have the BOS Server prompt
-for the string instead.
-
-=item -kvno
->
-
-Defines the new key's key version number. It must be an
-integer in the range from B<0> (zero) through B<255>.
-For the sake of simplicity, use the number one higher than the current highest
-key version number; use the B<bos listkeys> command to display
-key version numbers.
-L<(1)>
-
-=item -cell
->
-
-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<bos> reference page.
-
-=item -noauth
->
-
-Assigns the unprivileged identity anonymous to the
-issuer. Do not combine this flag with the B<-localauth>
-flag. For more details, see the introductory B<bos> reference
-page.
-
-=item -localauth
->
+F</usr/afs/etc/KeyFile> file. Identify the machine by IP address or its
+host name (either fully-qualified or abbreviated unambiguously). For
+details, see L<bos(8)>.
+
+In cells that use the Update Server to distribute the contents of the
+F</usr/afs/etc> directory, it is conventional to specify only the system
+control machine as a value for the B<-server> argument. Otherwise, repeat
+the command for each file server machine. For further discussion, see
+L<bos(8)>.
+
+=item B<-key> <I<key>>
+
+Specifies a character string just like a password; the BOS Server calls a
+DES conversion function to encode it into a form appropriate for use as an
+encryption key. Omit this argument to have the BOS Server prompt for the
+string instead.
+
+=item B<-kvno> <I<key version number>>
+
+Defines the new key's key version number. It must be an integer in the
+range from C<0> (zero) through C<255>. For the sake of simplicity, use
+the number one higher than the current highest key version number; use the
+B<bos listkeys> command to display key version numbers.
+
+=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 L<bos(8)>.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity C<anonymous> to the issuer. Do not combine
+this flag with the B<-localauth> flag. For more details, see L<bos(8)>.
+
+=item B<-localauth>
Constructs a server ticket using a key from the local
-B</usr/afs/etc/KeyFile> file. The B<bos> command
-interpreter presents the ticket to the BOS Server during mutual
-authentication. Do not combine this flag with the B<-cell> or
-B<-noauth> options. For more details, see the introductory
-B<bos> reference page.
+F</usr/afs/etc/KeyFile> file. The B<bos> command interpreter presents the
+ticket to the BOS Server during mutual authentication. Do not combine this
+flag with the B<-cell> or B<-noauth> options. For more details, see
+L<bos(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 strings typed at the C<Input key> and C<Retype input
-key> prompts do not match, the following message appears, and the command
-exits without adding a new key:
+If the strings typed at the C<Input key> and C<Retype input key> prompts
+do not match, the following message appears, and the command exits without
+adding a new key:
Input key mismatch
=head1 EXAMPLES
The following command adds a new server encryption key with key version
-number 14 to the B<KeyFile> file kept on the machine
-B<fs1.abc.com> (the system control machine). The
-issuer omits the B<-key> argument, as recommended, and provides the
-password at the prompts.
+number 14 to the B<KeyFile> file kept on the machine C<fs1.abc.com> (the
+system control machine). The issuer omits the B<-key> argument, as
+recommended, and provides the password at the prompts.
% bos addkey -server fs1.abc.com -kvno 14
Input key:
=head1 PRIVILEGE REQUIRED
-The issuer must be listed in the /usr/afs/etc/UserList file on
-the machine named by the B<-server> argument, 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 the
+machine named by the B<-server> argument, 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<KeyFile(1)>,
-L<UserList(1)>,
-L<bos(1)>,
-L<bos_listkeys(1)>,
-L<bos_removekey(1)>
+L<KeyFile(5)>,
+L<UserList(5)>,
+L<bos(8)>,
+L<bos_listkeys(8)>,
+L<bos_removekey(8)>
=head1 COPYRIGHT
=head1 NAME
-bos adduser - Adds a privileged user to the /usr/afs/etc/UserList file
+bos adduser - Adds a privileged user to the UserList file
=head1 SYNOPSIS
-B<bos adduser -server> <I<machine name>> -user <I<user names>>+
-[B<-cell> <I<cell name>>] [B<-noauth>] [B<-localauth>] [B<-help>]
+B<bos adduser> B<-server> <I<machine name>> B<-user> <I<user names>>+
+ [B<-cell> <I<cell name>>] [B<-noauth>] [B<-localauth>] [B<-help>]
-B<bos addu -s> <I<machine name>> -u <I<user names>>+
-[B<-c> <I<cell name>>] [B<-n>] [B<-l>] [B<-h>]
+B<bos addu> B<-s> <I<machine name>> B<-u> <I<user names>>+
+ [B<-c> <I<cell name>>] [B<-n>] [B<-l>] [B<-h>]
=head1 DESCRIPTION
-The bos adduser command adds each user name specified with the
-B<-user> argument to the B</usr/afs/etc/UserList> file on the
-machine named by the B<-server> argument. It is the
-issuer's responsibility to verify that an entry for the user exists in
-the Authentication and Protection Databases.
+The bos adduser command adds each user name specified with the B<-user>
+argument to the F</usr/afs/etc/UserList> file on the machine named by the
+B<-server> argument. It is the issuer's responsibility to verify that an
+entry for the user exists in the Authentication and Protection Databases.
=head1 OPTIONS
=over 4
-=item -server
->
+=item B<-server> <I<machine name>>
Indicates the server machine on which to change the
-B</usr/afs/etc/UserList> file. Identify the machine by IP
-address or its host name (either fully-qualified or abbreviated
-unambiguously). For details, see the introductory reference page for
-the B<bos> command suite.
+F</usr/afs/etc/UserList> file. Identify the machine by IP address or its
+host name (either fully-qualified or abbreviated unambiguously). For
+details, see L<bos(8)>.
-In cells that run the United States edition of AFS and use the Update
-Server to distribute the contents of the B</usr/afs/etc> directory, it
-is conventional to specify only the system control machine as a value for the
-B<-server> argument. In cells that run the international
-version of AFS, repeat the command for each file server machine. For
-further discussion, see the introductory reference page for the B<bos>
-command suite.
+In cells that use the Update Server to distribute the contents of the
+F</usr/afs/etc> directory, it is conventional to specify only the system
+control machine as a value for the B<-server> argument. Otherwise, repeat
+the command for each file server machine. For further discussion, see
+L<bos(8)>.
-=item -user
->
+=item B<-user> <I<user names>>+
-Specifies each user name to insert into the
-B</usr/afs/etc/UserList> file.
+Specifies each user name to insert into the F</usr/afs/etc/UserList> file.
-=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<bos> 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<bos(8)>.
-=item -noauth
->
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. Do not combine this flag with the B<-localauth>
-flag. For more details, see the introductory B<bos> reference
-page.
+Assigns the unprivileged identity C<anonymous> to the issuer. Do not
+combine this flag with the B<-localauth> flag. For more details, see
+L<bos(8)>.
-=item -localauth
->
+=item B<-localauth>
Constructs a server ticket using a key from the local
-B</usr/afs/etc/KeyFile> file. The B<bos> command
-interpreter presents the ticket to the BOS Server during mutual
-authentication. Do not combine this flag with the B<-cell> or
-B<-noauth> options. For more details, see the introductory
-B<bos> reference page.
+F</usr/afs/etc/KeyFile> file. The B<bos> command interpreter presents the
+ticket to the BOS Server during mutual authentication. Do not combine this
+flag with the B<-cell> or B<-noauth> options. For more details, see
+L<bos(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 the user names pat and
-B<smith> to the B</usr/afs/etc/UserList> file on the machine
-B<fs1.abc.com> (the system control machine).
+The following command adds the user names C<pat> and C<smith> to the
+F</usr/afs/etc/UserList> file on the machine C<fs1.abc.com> (the system
+control machine).
% bos adduser -server fs1.abc.com -user pat smith
=head1 PRIVILEGE REQUIRED
-The issuer must be listed in the /usr/afs/etc/UserList file on
-the machine named by the B<-server> argument, 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 the
+machine named by the B<-server> argument, 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<KeyFile(1)>,
-L<UserList(1)>,
-L<bos(1)>,
-L<bos_listusers(1)>,
-L<bos_removeuser(1)>
+L<KeyFile(5)>,
+L<UserList(5)>,
+L<bos(8)>,
+L<bos_listusers(8)>,
+L<bos_removeuser(8)>
=head1 COPYRIGHT
=head1 SYNOPSIS
-B<bos apropos -topic> <I<help string>> [-help]
+B<bos apropos> B<-topic> <I<help string>> [B<-help>]
-B<bos ap -t> <I<help string>> [-h]
+B<bos ap> B<-t> <I<help string>> [B<-h>]
=head1 DESCRIPTION
-The bos apropos command displays the first line of the online
-help entry for any B<bos> command that has in its name or short
-description the string specified by the B<-topic> argument.
+The B<bos apropos> command displays the first line of the online help
+entry for any B<bos> 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 bos help
-command.
+To display the syntax for a command, use the B<bos 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 ("")
+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
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<bos> command where the string specified with the B<-topic>
-argument is part of the command name or first line.
+B<bos> command where the string specified with the B<-topic> argument is
+part of the command name or first line.
=head1 EXAMPLES
-The following command lists all bos commands that include the
-word B<restart> in their names or short descriptions:
+The following command lists all B<bos> commands that include the word
+C<restart> in their names or short descriptions:
% bos apropos restart
getrestart: get restart times
=head1 SEE ALSO
-L<bos(1)>,
-L<bos_help(1)>
+L<bos(8)>,
+L<bos_help(8)>
=head1 COPYRIGHT
=head1 NAME
-bos create - Defines a new process in the /usr/afs/local/BosConfig file and
-starts it running
+bos create - Defines a new process in the BosConfig file and starts it
=head1 SYNOPSIS
-B<bos create -server> <I<machine name>> -instance <I<server process name>>
-B<-type> <I<server type>> B<-cmd> <I<command lines>>+
- [B<-notifier> <I<Notifier program>>] [-cell <I<cell name>>]
- [B<-noauth>] [B<-localauth>] [-help]
+B<bos create> B<-server> <I<machine name>>
+ B<-instance> <I<server process name>> B<-type> <I<server type>>
+ B<-cmd> <I<command lines>>+ [B<-notifier> <I<notifier program>>]
+ [B<-cell> <I<cell name>>] [B<-noauth>] [B<-localauth>] [B<-help>]
-B<bos c -s> <I<machine name>> B<-i> <I<server process name>> -t <I<server type>>
-B<-cm> <I<command lines>>+ [B<-not> <I<Notifier program>>] [B<-ce> <I<cell name>>]
- [B<-noa>] [B<-l>] [-h]
+B<bos c> B<-s> <I<machine name>> B<-i> <I<server process name>>
+ B<-t> <I<server type>> B<-cm> <I<command lines>>+
+ [B<-not> <I<notifier program>>] [B<-ce> <I<cell name>>] [B<-noa>]
+ [B<-l>] [B<-h>]
=head1 DESCRIPTION
-The bos create command creates a server process entry in the
-B</usr/afs/local/BosConfig> file on the server machine named by the
-B<-server> argument, sets the process's status to B<Run>
-in the B<BosConfig> file and in memory, and starts the process.
+The B<bos create> command creates a server process entry in the
+F</usr/afs/local/BosConfig> file on the server machine named by the
+B<-server> argument, sets the process's status to C<Run> in the
+F<BosConfig> file and in memory, and starts the process.
-A server process's entry in the BosConfig file defines its
-name, its type, the command that initializes it, and optionally, the name of a
+A server process's entry in the F<BosConfig> file defines its name, its
+type, the command that initializes it, and optionally, the name of a
notifier program that runs when the process terminates.
=head1 OPTIONS
=over 4
-=item -server
->
+=item B<-server> <I<machine name>>
Indicates the server machine on which to define and start the new
process. Identify the machine by IP address or its host name (either
-fully-qualified or abbreviated unambiguously). For details, see the
-introductory reference page for the B<bos> command suite.
+fully-qualified or abbreviated unambiguously). For details, see L<bos(8)>.
-=item -instance
->
+=item B<-instance> <I<server process name>>
-Names the process to define and start. Any name is acceptable, but
-for the sake of simplicity it is best to use the last element of the
-process's binary file pathname, and to use the same name on every server
-machine. The conventional names, as used in all AFS documentation,
-are:
+Names the process to define and start. Any name is acceptable, but for the
+sake of simplicity it is best to use the last element of the process's
+binary file pathname, and to use the same name on every server
+machine. The conventional names, as used in all AFS documentation, are:
=over 4
=item buserver
->
-The Backup Server process
-L<(1)>
-L<(1)>
+The Backup Server process.
=item fs
->
The process that combines the File Server, Volume Server, and Salvager
-processes (B<fileserver>, B<volserver>, and
-B<salvager>)
-L<(1)>
-L<(1)>
+processes (B<fileserver>, B<volserver>, and B<salvager>).
=item kaserver
->
-The Authentication Server process
-L<(1)>
-L<(1)>
+The Authentication Server process.
=item ptserver
->
-The Protection Server process
-L<(1)>
-L<(1)>
+The Protection Server process.
=item runntp
->
-The controller process for the Network Time Protocol Daemon
-L<(1)>
-L<(1)>
+The controller process for the Network Time Protocol Daemon.
=item upclientbin
->
The client portion of the Update Server process that retrieves binary
-files from the B</usr/afs/bin> directory of the binary distribution
-machine for this machine's CPU/operating system type. (The name of
-the binary is B<upclient>, but the B<bin> suffix distinguishes
-this process from B<upclientetc>.)
-L<(1)>
-L<(1)>
+files from the F</usr/afs/bin> directory of the binary distribution
+machine for this machine's CPU/operating system type. (The name of the
+binary is B<upclient>, but the C<bin> suffix distinguishes this process
+from C<upclientetc>.)
=item upclientetc
->
The client portion of the Update Server process that retrieves
-configuration files from the B</usr/afs/etc> directory of the system
-control machine. Do not run this process in cells that use the
-international edition of AFS. (The name of the binary is
-B<upclient>, but the B<etc> suffix distinguishes this process
-from B<upclientbin>.)
+configuration files from the F</usr/afs/etc> directory of the system
+control machine. (The name of the binary is B<upclient>, but the C<etc>
+suffix distinguishes this process from C<upclientbin>.)
=item upserver
->
-The server portion of the Update Server process
-L<(1)>
-L<(1)>
+The server portion of the Update Server process.
=item vlserver
->
-The Volume Location (VL) Server process
-L<(1)>
-L<(1)>
+The Volume Location (VL) Server process.
=back
-=item -type
->
+=item B<-type> <I<server type>>
Specifies the process's type. The acceptable values are:
=over 4
=item cron
->
Use this value for cron-type processes that the BOS Server starts only at
a defined daily or weekly time, rather than whenever it detects that the
-process has terminated. AFS does not define any such processes by
-default, but makes this value available for administrator use. Define
-the time for command execution as part of the B<-cmd> argument to the
-B<bos create> command.
+process has terminated. AFS does not define any such processes by default,
+but makes this value available for administrator use. Define the time for
+command execution as part of the B<-cmd> argument to the B<bos create>
+command.
=item fs
->
-Use this value only for the fs process, which combines the File
-Server, Volume Server and Salvager processes. If one of the component
-processes terminates, the BOS Server shuts down and restarts the processes in
-the appropriate order.
+Use this value only for the fs process, which combines the File Server,
+Volume Server and Salvager processes. If one of the component processes
+terminates, the BOS Server shuts down and restarts the processes in the
+appropriate order.
=item simple
->
Use this value for all processes listed as acceptable values to the
-B<-instance> argument, except for the B<fs> process.
-There are no interdependencies between simple processes, so the BOS Server can
-stop and start them independently as necessary.
+B<-instance> argument, except for the B<fs> process. There are no
+interdependencies between simple processes, so the BOS Server can stop and
+start them independently as necessary.
=back
-=item -cmd
->
+=item B<-cmd> <I<command lines>>+
-Specifies each command the BOS Server runs to start the process.
-Specify no more than six commands (which can include the command's
-options, in which case the entire string is surrounded by double quotes);
-any additional commands are ignored.
+Specifies each command the BOS Server runs to start the process. Specify
+no more than six commands (which can include the command's options, in
+which case the entire string is surrounded by double quotes); any
+additional commands are ignored.
For a simple process, provide the complete pathname of the process's
-binary file on the local disk (for example, B</usr/afs/bin/ptserver>
-for the Protection Server). If including any of the initialization
-command's options, surround the entire command in double quotes (B<"
-">). The B<upclient> process has a required argument, and
-the commands for all other processes take optional arguments.
-L<(1)>
-
-For the fs process, provide the complete pathname of the local
-disk binary file for each of the component processes:
-B<fileserver>, B<volserver>, and B<salvager>, in that
-order. The standard binary directory is B</usr/afs/bin>.
-If including any of an initialization command's options, surround the
-entire command in double quotes (B<" ">).
-L<(1)>
+binary file on the local disk (for example, F</usr/afs/bin/ptserver> for
+the Protection Server). If including any of the initialization command's
+options, surround the entire command in double quotes (C<"">). The
+B<upclient> process has a required argument, and the commands for all
+other processes take optional arguments.
+
+For the fs process, provide the complete pathname of the local disk binary
+file for each of the component processes: B<fileserver>, B<volserver>, and
+B<salvager>, in that order. The standard binary directory is
+F</usr/afs/bin>. If including any of an initialization command's options,
+surround the entire command in double quotes (C<"">).
For a cron process, provide two parameters:
-L<(1)>
=over 4
The complete local disk pathname of either an executable file or a command
from one of the AFS suites (complete with all of the necessary
-arguments). Surround this parameter with double quotes (B<" ">)
-if it contains spaces.
-
+arguments). Surround this parameter with double quotes (C<"">) if it
+contains spaces.
=item *
A specification of when the BOS Server executes the file or command
-indicated by the first parameter. There are three acceptable
-values:
-
+indicated by the first parameter. There are three acceptable values:
=over 4
=item *
-The string now, which directs the BOS Server to execute the
-file or command immediately and only once. It is usually simpler to
-issue the command directly or issue the B<bos exec> command.
-
+The string C<now>, which directs the BOS Server to execute the file or
+command immediately and only once. It is usually simpler to issue the
+command directly or issue the B<bos exec> command.
=item *
-A time of day. The BOS Server executes the file or command daily at
-the indicated time. Separate the hours and minutes with a colon
-(I<hh>:I<MM>), and use either 24-hour format, or a value
-in the range from B<1:00> through B<12:59> with
-the addition of B<am> or B<pm>. For example, both
-B<14:30> and B<"2:30 pm"> indicate 2:30 in
-the afternoon. Surround this parameter with double quotes (B<"
-">) if it contains a space.
-
+A time of day. The BOS Server executes the file or command daily at the
+indicated time. Separate the hours and minutes with a colon (I<hh:MM>),
+and use either 24-hour format, or a value in the range from C<1:00>
+through C<12:59> with the addition of C<am> or C<pm>. For example, both
+C<14:30> and C<"2:30 pm"> indicate 2:30 in the afternoon. Surround this
+parameter with double quotes (C<"">) if it contains a space.
=item *
A day of the week and time of day, separated by a space and surrounded
-with double quotes (B<" ">). The BOS Server executes the file
-or command weekly at the indicated day and time. For the day, provide
-either the whole name or the first three letters, all in lowercase letters
-(B<sunday> or B<sun>, B<thursday> or B<thu>,
-and so on). For the time, use the same format as when specifying the
-time alone.
-
+with double quotes (C<"">). The BOS Server executes the file or command
+weekly at the indicated day and time. For the day, provide either the
+whole name or the first three letters, all in lowercase letters (C<sunday>
+or C<sun>, C<thursday> or C<thu>, and so on). For the time, use the same
+format as when specifying the time alone.
=back
=back
-=item -notifier
->
+=item B<-notifier> <I<notifier program>>
Specifies the complete pathname on the local disk of a program that the
-BOS Server invokes when the process terminates. The AFS distribution
-does not include any notifier programs, but this argument is available for
-administrator use. See the B<Related Information>
-section.
+BOS Server invokes when the process terminates. The AFS distribution does
+not include any notifier programs, but this argument is available for
+administrator use. See L<NOTES>.
-=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<bos> 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<bos(8)>.
-=item -noauth
->
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. Do not combine this flag with the B<-localauth>
-flag. For more details, see the introductory B<bos> reference
-page.
+Assigns the unprivileged identity C<anonymous> to the issuer. Do not
+combine this flag with the B<-localauth> flag. For more details, see
+L<bos(8)>.
-=item -localauth
->
+=item B<-localauth>
Constructs a server ticket using a key from the local
-B</usr/afs/etc/KeyFile> file. The B<bos> command
-interpreter presents the ticket to the BOS Server during mutual
-authentication. Do not combine this flag with the B<-cell> or
-B<-noauth> options. For more details, see the introductory
-B<bos> reference page.
+F</usr/afs/etc/KeyFile> file. The B<bos> command interpreter presents the
+ticket to the BOS Server during mutual authentication. Do not combine this
+flag with the B<-cell> or B<-noauth> options. For more details, see
+L<bos(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 and starts the simple process
-B<kaserver> on the machine B<fs3.abc.com>:
+C<kaserver> on the machine C<fs3.abc.com>:
- % bos create -server fs3.abc.com -instance kaserver -type simple \
+ % bos create -server fs3.abc.com -instance kaserver -type simple \
-cmd /usr/afs/bin/kaserver
-The following command defines and starts the simple process
-B<upclientbin> on the machine
-B<fs4.abc.com>. It references
-B<fs1.abc.com> as the source for updates to binary
-files, checking for changes to the B</usr/afs/bin> directory every 120
-seconds.
-
- % bos create -server fs4.abc.com -instance upclientbin -type simple \
- -cmd "/usr/afs/bin/upclient fs1.abc.com -clear -t 120 \
+The following command defines and starts the simple process C<upclientbin>
+on the machine C<fs4.abc.com>. It references C<fs1.abc.com> as the source
+for updates to binary files, checking for changes to the F</usr/afs/bin>
+directory every 120 seconds.
+
+ % bos create -server fs4.abc.com -instance upclientbin -type simple \
+ -cmd "/usr/afs/bin/upclient fs1.abc.com -clear -t 120 \
/usr/afs/bin"
The following command creates the fs process fs on the machine
-B<fs4.abc.com>. Type the command on a single
-line.
+C<fs4.abc.com>. Type the command on a single line.
- % bos create -server fs4.abc.com -instance fs -type fs \
- -cmd /usr/afs/bin/fileserver /usr/afs/bin/volserver \
+ % bos create -server fs4.abc.com -instance fs -type fs \
+ -cmd /usr/afs/bin/fileserver /usr/afs/bin/volserver \
/usr/afs/bin/salvager
-The following command creates a cron process called
-B<userbackup> on the machine B<fs5.abc.com>, so
-that the BOS Server issues the indicated B<vos backupsys> command each
-day at 3:00 a.m. (the command creates a backup version of
-every volume in the file system whose name begins with
-B<user>). Note that the issuer provides the complete pathname
-to the B<vos> command, includes the B<-localauth> flag on it,
-and types the entire B<bos create> command on one line.
+The following command creates a cron process called C<userbackup> on the
+machine C<fs5.abc.com>, so that the BOS Server issues the indicated B<vos
+backupsys> command each day at 3:00 a.m. (the command creates a backup
+version of every volume in the file system whose name begins with
+C<user>). Note that the issuer provides the complete pathname to the
+B<vos> command, includes the B<-localauth> flag on it, and types the
+entire B<bos create> command on one line.
- % bos create -server fs5.abc.com -instance userbackup -type cron \
- -cmd "/usr/afs/bin/vos backupsys -prefix user -localauth" 03:00
+ % bos create -server fs5.abc.com -instance userbackup -type cron \
+ -cmd "/usr/afs/bin/vos backupsys -prefix user -localauth" 03:00
=head1 PRIVILEGE REQUIRED
-The issuer must be listed in the /usr/afs/etc/UserList file on
-the machine named by the B<-server> argument, 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 the
+machine named by the B<-server> argument, or must be logged onto a server
+machine as the local superuser C<root> if the B<-localauth> flag is
+included.
-=head1 SEE ALSO
+=head1 NOTES
-If the -notifier argument is included when this command is used
-to define and start a process, the BOS Server invokes the indicated
-I<notifier program> when the process exits. The intended use of
-a notifier program is to inform administrators when a process exits
-unexpectedly, but it can be used to perform any appropriate actions.
-The following paragraphs describe the B<bnode> and
-B<bnode_proc> structures in which the BOS Server records information
-about the exiting process. The list of AFS commands related to this one
-follows.
+If the B<-notifier> argument is included when this command is used to
+define and start a process, the BOS Server invokes the indicated
+I<notifier program> when the process exits. The intended use of a notifier
+program is to inform administrators when a process exits unexpectedly, but
+it can be used to perform any appropriate actions. The following
+paragraphs describe the bnode and bnode_proc structures in which the
+BOS Server records information about the exiting process.
The BOS Server constructs and sends on the standard output stream one
-B<bnode> and one B<bnode_proc> structure for each exiting
-process associated with the notifier program. It brackets each
-structure with appropriate C<BEGIN> and C<END> statements
-(C<BEGIN bnode> and C<END bnode>, C<BEGIN bnode_proc>
-and C<END bnode_proc>), which immediately follow the preceding newline
-character with no intervening spaces or other characters. If the
-notifier program does not need information from a structure, it can scan ahead
-in the input stream for the C<END> statement.
+bnode and one bnode_proc structure for each exiting process associated
+with the notifier program. It brackets each structure with appropriate
+C<BEGIN> and C<END> statements (C<BEGIN bnode> and C<END bnode>, C<BEGIN
+bnode_proc> and C<END bnode_proc>), which immediately follow the preceding
+newline character with no intervening spaces or other characters. If the
+notifier program does not need information from a structure, it can scan
+ahead in the input stream for the C<END> statement.
In general, each field in a structure is a string of ASCII text terminated
-by the newline character. The format of the information within a
-structure possibly varies slightly depending on the type of process associated
-with the notifier program.
+by the newline character. The format of the information within a structure
+possibly varies slightly depending on the type of process associated with
+the notifier program.
-The C code for the B<bnode> and bnode_proc structures
-follows. Note that the structures sent by the BOS Server do not
-necessarily include all of the fields described here, because some are used
-only for internal record keeping. The notifier process must robustly
-handle the absence of expected fields, as well as the presence of unexpected
-fields, on the standard input stream.
+The C code for the bnode and bnode_proc structures follows. Note that the
+structures sent by the BOS Server do not necessarily include all of the
+fields described here, because some are used only for internal record
+keeping. The notifier process must robustly handle the absence of expected
+fields, as well as the presence of unexpected fields, on the standard
+input stream.
For proper performance, the notifier program must continue processing the
-input stream until it detects the end-of-file (EOF). The BOS Server
-closes the standard input file descriptor to the notifier process when it has
-completed delivery of the data, and it is the responsibility of the notifier
-process to terminate properly.
+input stream until it detects the end-of-file (EOF). The BOS Server closes
+the standard input file descriptor to the notifier process when it has
+completed delivery of the data, and it is the responsibility of the
+notifier process to terminate properly.
-struct bnode contents
+struct bnode contents:
struct bnode {
struct bnode *next; /* next pointer in top-level's list */
char fileGoal; /* same, but to be stored in file */
};
-format of struct bnode explosion
+Format of struct bnode explosion:
printf("name: %s\n",tp->name);
printf("rsTime: %ld\n", tp->rsTime);
printf("lastErrorName: %s\n", tp->lastErrorName);
printf("goal: %d\n", tp->goal);
-struct bnode_proc contents
+struct bnode_proc contents:
struct bnode_proc {
struct bnode_proc *next; /* next guy in top-level's list */
long flags; /* flags giving process state */
};
-format of struct bnode_proc explosion
+Format of struct bnode_proc explosion:
printf("comLine: %s\n", tp->comLine);
printf("coreName: %s\n", tp->coreName);
printf("lastExit: %ld\n", tp->lastExit);
printf("lastSignal: %ld\n", tp->lastSignal);
-L<BosConfig(1)>,
-L<KeyFile(1)>,
-L<UserList(1)>,
-L<bos(1)>,
-L<buserver(1)>,
-L<fileserver(1)>,
-L<kaserver(1)>,
-L<ptserver(1)>,
-L<runntp(1)>,
-L<salvager(1)>,
-L<upclient(1)>,
-L<upserver(1)>,
-L<vlserver(1)>,
-L<volserver(1)>,
+=head1 SEE ALSO
+
+L<BosConfig(5)>,
+L<KeyFile(5)>,
+L<UserList(5)>,
+L<bos(8)>,
+L<buserver(8)>,
+L<fileserver(8)>,
+L<kaserver(8)>,
+L<ptserver(8)>,
+L<salvager(8)>,
+L<upclient(8)>,
+L<upserver(8)>,
+L<vlserver(8)>,
+L<volserver(8)>,
L<vos_backupsys(1)>
=head1 COPYRIGHT
=head1 NAME
-bos delete - Deletes a server process from the /usr/afs/local/BosConfig file
+bos delete - Deletes a server process from the BosConfig file
=head1 SYNOPSIS
-B<bos delete -server> <I<machine name>> -instance <I<server process name>>+
-[B<-cell> <I<cell name>>] [B<-noauth>] [B<-localauth>] [B<-help>]
+B<bos delete> B<-server> <I<machine name>>
+ B<-instance> <I<server process name>>+ [B<-cell> <I<cell name>>]
+ [B<-noauth>] [B<-localauth>] [B<-help>]
-B<bos d -s> <I<machine name>> B<-i> <I<server process name>>+ [-c <I<cell name>>]
-[B<-n>] [B<-l>] [B<-h>]
+B<bos d> B<-s> <I<machine name>> B<-i> <I<server process name>>+
+ [B<-c> <I<cell name>>] [B<-n>] [B<-l>] [B<-h>]
=head1 DESCRIPTION
-The bos delete command removes the
-B</usr/afs/local/BosConfig> entry for each process indicated by the
-B<-instance> argument, on the server machine named by the
-B<-server> argument.
+The B<bos delete> command removes the F</usr/afs/local/BosConfig> entry
+for each process indicated by the B<-instance> argument, on the server
+machine named by the B<-server> argument.
-Before issuing this command, issue the bos stop command to stop
-the process and set its status flag in the B<BosConfig> file to
-C<NotRun>. The B<bos delete> command fails with an
-error message if a process's status flag is C<Run>.
+Before issuing this command, issue the bos stop command to stop the
+process and set its status flag in the F<BosConfig> file to C<NotRun>. The
+B<bos delete> command fails with an error message if a process's status
+flag is C<Run>.
=head1 OPTIONS
=over 4
-=item -server
->
+=item B<-server> <I<machine name>>
Indicates the server machine on which to delete the server process entry
-from the B</usr/afs/local/BosConfig> file. Identify the machine
+from the F</usr/afs/local/BosConfig> file. Identify the machine
by IP address or its host name (either fully-qualified or abbreviated
-unambiguously). For details, see the introductory reference page for
-the B<bos> command suite.
+unambiguously). For details, see L<bos(8)>.
-=item -instance
->
+=item B<-instance> <I<server process name>>+
-Names each process to delete. Use the name assigned with the
-B<-instance> argument to the B<bos create> command;
-process names appear in the output of the B<bos status>
-command.
+Names each process to delete. Use the name assigned with the B<-instance>
+argument to the B<bos create> command; process names appear in the output
+of the B<bos status> command.
-=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<bos> 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<bos(8)>.
-=item -noauth
->
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. Do not combine this flag with the B<-localauth>
-flag. For more details, see the introductory B<bos> reference
-page.
+Assigns the unprivileged identity C<anonymous> to the issuer. Do not
+combine this flag with the B<-localauth> flag. For more details, see
+L<bos(8)>.
-=item -localauth
->
+=item B<-localauth>
Constructs a server ticket using a key from the local
-B</usr/afs/etc/KeyFile> file. The B<bos> command
-interpreter presents the ticket to the BOS Server during mutual
-authentication. Do not combine this flag with the B<-cell> or
-B<-noauth> options. For more details, see the introductory
-B<bos> reference page.
+F</usr/afs/etc/KeyFile> file. The B<bos> command interpreter presents the
+ticket to the BOS Server during mutual authentication. Do not combine this
+flag with the B<-cell> or B<-noauth> options. For more details, see
+L<bos(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 removes the B<buserver>, kaserver,
-B<ptserver>, and B<vlserver> entries from the
-B<BosConfig> file on B<db3.abc.com>, a database
-server machine being decommissioned.
+The following command removes the B<buserver>, B<kaserver>, B<ptserver>,
+and B<vlserver> entries from the F<BosConfig> file on C<db3.abc.com>, a
+database server machine being decommissioned.
- % bos delete -server db3.abc.com -instance buserver kaserver ptserver vlserver
+ % bos delete -server db3.abc.com \
+ -instance buserver kaserver ptserver vlserver
=head1 PRIVILEGE REQUIRED
-The issuer must be listed in the /usr/afs/etc/UserList file on
-the machine named by the B<-server> argument, 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 the
+machine named by the B<-server> argument, 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<BosConfig(1)>,
-L<KeyFile(1)>,
-L<UserList(1)>,
-L<bos(1)>,
-L<bos_create(1)>,
-L<bos_status(1)>
+L<BosConfig(5)>,
+L<KeyFile(5)>,
+L<UserList(5)>,
+L<bos(8)>,
+L<bos_create(8)>,
+L<bos_status(8)>
=head1 COPYRIGHT
=head1 SYNOPSIS
-B<bos exec -server> <I<machine name>> -cmd <I<command to execute>>
-[B<-cell> <I<cell name>>] [B<-noauth>] [B<-localauth>] [B<-help>]
+B<bos exec> B<-server> <I<machine name>> B<-cmd> <I<command to execute>>
+ [B<-cell> <I<cell name>>] [B<-noauth>] [B<-localauth>] [B<-help>]
-B<bos e -s> <I<machine name>> B<-cm> <I<command to execute>> [-ce <I<cell name>>]
-[B<-n>] [B<-l>] [B<-h>]
+B<bos e> B<-s> <I<machine name>> B<-cm> <I<command to execute>>
+ [B<-ce> <I<cell name>>] [B<-n>] [B<-l>] [B<-h>]
=head1 DESCRIPTION
-The bos exec command executes the indicated command on the file
-server machine named by the B<-server> argument. Its intended
-use is to reboot the machine, using the B</etc/reboot> command or
-equivalent.
+The B<bos exec> command executes the indicated command on the file server
+machine named by the B<-server> argument. Its intended use is to reboot
+the machine, using the F</sbin/reboot> command or equivalent.
=head1 OPTIONS
=over 4
-=item -server
->
+=item B<-server> <I<machine name>>
-Indicates the server machine on which to execute the command.
-Identify the machine by IP address or its host name (either fully-qualified or
-abbreviated unambiguously). For details, see the introductory reference
-page for the B<bos> command suite.
+Indicates the server machine on which to execute the command. Identify
+the machine by IP address or its host name (either fully-qualified or
+abbreviated unambiguously). For details, see L<bos(8)>.
-=item -cmd
->
+=item B<-cmd> <I<command to execute>>
Specifies the complete local disk pathname of the command to execute (for
-example, B</etc/reboot>). Surround this argument with double
-quotes ("") if the command contains one or more spaces.
+example, F</sbin/reboot>). Surround this argument with double quotes
+(C<"">) if the command contains one or more spaces.
-=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<bos> 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<bos(8)>.
-=item -noauth
->
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. Do not combine this flag with the B<-localauth>
-flag. For more details, see the introductory B<bos> reference
-page.
+Assigns the unprivileged identity C<anonymous> to the issuer. Do not
+combine this flag with the B<-localauth> flag. For more details, see
+L<bos(8)>.
-=item -localauth
->
+=item B<-localauth>
Constructs a server ticket using a key from the local
-B</usr/afs/etc/KeyFile> file. The B<bos> command
-interpreter presents the ticket to the BOS Server during mutual
-authentication. Do not combine this flag with the B<-cell> or
-B<-noauth> options. For more details, see the introductory
-B<bos> reference page.
+F</usr/afs/etc/KeyFile> file. The B<bos> command interpreter presents the
+ticket to the BOS Server during mutual authentication. Do not combine this
+flag with the B<-cell> or B<-noauth> options. For more details, see
+L<bos(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 reboots the machine
-B<fs2.abc.com>. The issuer has previously issued
-the B<bos shutdown> command to shutdown all processes cleanly.
+The following command reboots the machine C<fs2.abc.com>. The issuer has
+previously issued the B<bos shutdown> command to shutdown all processes
+cleanly.
% bos exec -server fs2.abc.com -cmd /sbin/shutdown -r now
=head1 PRIVILEGE REQUIRED
-The issuer must be listed in the /usr/afs/etc/UserList file on
-the machine named by the B<-server> argument, 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 the
+machine named by the B<-server> argument, 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<bos(1)>
+L<bos(8)>
=head1 COPYRIGHT
=head1 SYNOPSIS
-B<bos getdate -server> <I<machine name>> -file <I<files to check>>+
-[B<-dir> <I<destination dir>>] [B<-cell> <I<cell name>>]
- [B<-noauth>] [B<-localauth>] [-help]
+B<bos getdate> B<-server> <I<machine name>> B<-file> <I<files to check>>+
+ [B<-dir> <I<destination dir>>] [B<-cell> <I<cell name>>]
+ [B<-noauth>] [B<-localauth>] [B<-help>]
-B<bos getd -s> <I<machine name>> B<-f> <I<files to check>>+ [-d <I<destination dir>>]
-[B<-c> <I<cell name>>] [B<-n>] [B<-l>] [B<-h>]
+B<bos getd> B<-s> <I<machine name>> B<-f> <I<files to check>>+
+ [B<-d> <I<destination dir>>] [B<-c> <I<cell name>>] [B<-n>] [B<-l>]
+ [B<-h>]
=head1 DESCRIPTION
-The bos getdate command displays the time stamps on the current
-version,C< .BAK> version (if any) and C<.OLD>
-version (if any) of each binary file named by the B<-file>
-argument. (The BOS Server automatically creates C<.BAK>
-and C<.OLD> versions when new binaries are installed with the
-B<bos install> command.) The files must reside in the
-B</usr/afs/bin> directory on the server machine named by the
-B<-server> argument unless the B<-dir> argument indicates an
-alternate directory.
-
-To revert to the C<.BAK> version of a binary, use the
-B<bos uninstall> command. To remove obsolete binary files from
-the B</usr/afs/bin> directory, use the B<bos prune>
-command.
+The B<bos getdate> command displays the time stamps on the current
+version,C< .BAK> version (if any) and C<.OLD> version (if any) of each
+binary file named by the B<-file> argument. (The BOS Server automatically
+creates C<.BAK> and C<.OLD> versions when new binaries are installed with
+the B<bos install> command.) The files must reside in the F</usr/afs/bin>
+directory on the server machine named by the B<-server> argument unless
+the B<-dir> argument indicates an alternate directory.
+
+To revert to the C<.BAK> version of a binary, use the B<bos uninstall>
+command. To remove obsolete binary files from the F</usr/afs/bin>
+directory, use the B<bos prune> command.
=head1 OPTIONS
=over 4
-=item -server
->
+=item B<-server> <I<machine name>>
-Indicates the server machine from which to list binary files.
-Identify the machine by IP address or its host name (either fully-qualified or
-abbreviated unambiguously). For details, see the introductory reference
-page for the B<bos> command suite.
+Indicates the server machine from which to list binary files. Identify
+the machine by IP address or its host name (either fully-qualified or
+abbreviated unambiguously). For details, see L<bos(8)>.
-All server machines of the same AFS system type show the same timestamps if
-the binaries were installed properly on the binary distribution machine for
-this machine's system type, and if all other machines of that type are
-running the appropriate B<upclientbin> process.
+All server machines of the same AFS system type show the same timestamps
+if the binaries were installed properly on the binary distribution machine
+for this machine's system type, and if all other machines of that type are
+running the appropriate C<upclientbin> process.
-=item -file
->
+=item B<-file> <I<files to check>>+
Names each binary file to list.
-=item -dir
->
+=item B<-dir> <I<destination dir>>
Specifies the complete pathname of the local disk directory containing
-each file named by the B<-file> argument. It is necessary only
-if the files are not in the B</usr/afs/bin> directory.
+each file named by the B<-file> argument. It is necessary only if the
+files are not in the F</usr/afs/bin> directory.
-=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<bos> 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<bos(8)>.
-=item -noauth
->
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. Do not combine this flag with the B<-localauth>
-flag. For more details, see the introductory B<bos> reference
-page.
+Assigns the unprivileged identity C<anonymous> to the issuer. Do not
+combine this flag with the B<-localauth> flag. For more details, see
+L<bos(8)>.
-=item -localauth
->
+=item B<-localauth>
Constructs a server ticket using a key from the local
-B</usr/afs/etc/KeyFile> file. The B<bos> command
-interpreter presents the ticket to the BOS Server during mutual
-authentication. Do not combine this flag with the B<-cell> or
-B<-noauth> options. For more details, see the introductory
-B<bos> reference page.
+F</usr/afs/etc/KeyFile> file. The B<bos> command interpreter presents the
+ticket to the BOS Server during mutual authentication. Do not combine this
+flag with the B<-cell> or B<-noauth> options. For more details, see
+L<bos(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
-For each file specified with the -file argument, the output
-displays the time stamp on the current (unmarked), C<.BAK>, and
-C<.OLD> version. The output explicitly reports that a
-version does not exist, rather than simply omitting it.
+For each file specified with the -file argument, the output displays the
+time stamp on the current (unmarked), C<.BAK>, and C<.OLD> version. The
+output explicitly reports that a version does not exist, rather than
+simply omitting it.
=head1 EXAMPLES
The following command examines the time stamps on the files with basename
-B<kaserver> on the machine B<fs2.abc.com>:
+C<kaserver> on the machine C<fs2.abc.com>:
% bos getdate -server fs2.abc.com -file kaserver
File /usr/afs/bin/kaserver dated Mon Jan 4 10:00:36 1999.
=head1 SEE ALSO
-L<KeyFile(1)>,
-L<bos(1)>,
-L<bos_install(1)>,
-L<bos_prune(1)>,
-L<bos_uninstall(1)>
+L<KeyFile(5)>,
+L<bos(8)>,
+L<bos_install(8)>,
+L<bos_prune(8)>,
+L<bos_uninstall(8)>
=head1 COPYRIGHT
=head1 SYNOPSIS
-B<bos getlog -server> <I<machine name>> -file <I<log file to examine>>
-[B<-cell> <I<cell name>>] [B<-noauth>] [B<-localauth>] [B<-help>]
+B<bos getlog> B<-server> <I<machine name>> B<-file> <I<log file to examine>>
+ [B<-cell> <I<cell name>>] [B<-noauth>] [B<-localauth>] [B<-help>]
-B<bos getl -s> <I<machine name>> B<-f> <I<log file to examine>> [-c <I<cell name>>]
-[B<-n>] [B<-l>] [B<-h>]
+B<bos getl> B<-s> <I<machine name>> B<-f> <I<log file to examine>>
+ [B<-c> <I<cell name>>] [B<-n>] [B<-l>] [B<-h>]
=head1 DESCRIPTION
-The bos getlog command displays on the standard output stream
-the specified log file from the machine named by the B<-server>
-argument. The BOS Server fetches the log file from the
-B</usr/afs/logs> directory unless an alternate pathname is provided as
-part of the B<-file> argument.
+The B<bos getlog> command displays on the standard output stream the
+specified log file from the machine named by the B<-server> argument. The
+BOS Server fetches the log file from the F</usr/afs/logs> directory unless
+an alternate pathname is provided as part of the B<-file> argument.
=head1 CAUTIONS
Log files can grow quite large, especially for the database server
-processes. To keep them to a manageable size, periodically either use
-the UNIX B<rm> command to truncate each log file, or use the B<bos
-restart> command to restart each process.
+processes. To keep them to a manageable size, periodically either use the
+UNIX B<rm> command to truncate each log file, or use the B<bos restart>
+command to restart each process.
It can take up to five minutes after the file is removed or process
restarted for the space occupied by a log file to become available.
=over 4
-=item -server
->
+=item B<-server> <I<machine name>>
Indicates the server machine from which to retrieve the log file.
-Identify the machine by IP address or its host name (either fully-qualified or
-abbreviated unambiguously). For details, see the introductory reference
-page for the B<bos> command suite.
+Identify the machine by IP address or its host name (either
+fully-qualified or abbreviated unambiguously). For details, see L<bos(8)>.
-=item -file
->
+=item B<-file> <I<log file to examine>>
-Names the log file to display. If a filename only is provided, the
-BOS Server fetches the log file from the B</usr/afs/logs>
-directory; the standard values are:
+Names the log file to display. If a filename only is provided, the BOS
+Server fetches the log file from the F</usr/afs/logs> directory; the
+standard values are:
=over 4
-=item AuthLog
->
+=item F<AuthLog>
-The Authentication Server (kaserver) log file
+The Authentication Server (B<kaserver>) log file.
-=item BackupLog
->
+=item F<BackupLog>
-The Backup Server (buserver) log file
+The Backup Server (B<buserver>) log file.
-=item BosLog
->
+=item F<BosLog>
-The BOS Server (bosserver) log file
+The BOS Server (B<bosserver>) log file.
-=item FileLog
->
+=item F<FileLog>
-The File Server (fileserver) log file
+The File Server (B<fileserver>) log file.
-=item SalvageLog
->
+=item F<SalvageLog>
-The Salvager (salvager) log file
+The Salvager (B<salvager>) log file.
-=item VLLog
->
+=item F<VLLog>
-The Volume Location (VL) Server (vlserver) log file
+The Volume Location (VL) Server (B<vlserver>) log file.
-=item VolserLog
->
+=item F<VolserLog>
-The Volume Server (volserver) log file
+The Volume Server (B<volserver>) log file.
=back
-If a pathname and filename are provided, the log file is retrieved from the
-indicated directory. Partial pathnames are interpreted relative to the
-B</usr/afs/logs> directory.
+If a pathname and filename are provided, the log file is retrieved from
+the indicated directory. Partial pathnames are interpreted relative to the
+F</usr/afs/logs> directory.
-=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<bos> 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<bos(8)>.
-=item -noauth
->
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. Do not combine this flag with the B<-localauth>
-flag. For more details, see the introductory B<bos> reference
-page.
+Assigns the unprivileged identity C<anonymous> to the issuer. Do not
+combine this flag with the B<-localauth> flag. For more details, see
+L<bos(8)>.
-=item -localauth
->
+=item B<-localauth>
Constructs a server ticket using a key from the local
-B</usr/afs/etc/KeyFile> file. The B<bos> command
-interpreter presents the ticket to the BOS Server during mutual
-authentication. Do not combine this flag with the B<-cell> or
-B<-noauth> options. For more details, see the introductory
-B<bos> reference page.
+F</usr/afs/etc/KeyFile> file. The B<bos> command interpreter presents the
+ticket to the BOS Server during mutual authentication. Do not combine this
+flag with the B<-cell> or B<-noauth> options. For more details, see
+L<bos(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
The output is preceded by the line
- Fetching log file 'I<filename>'...
+ Fetching log file '<filename>'...
The remainder of the output depends on the particular log file.
=head1 EXAMPLES
The following example displays the FileLog file from the machine
-B<fs3.abc.com>:
+C<fs3.abc.com>:
% bos getlog -server fs3.abc.com -file FileLog
Fetching log file 'FileLog'...
=head1 PRIVILEGE REQUIRED
-The issuer must be listed in the /usr/afs/etc/UserList file on
-the machine named by the B<-server> argument, 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 the
+machine named by the B<-server> argument, 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<bos(1)>
+L<bos(8)>
=head1 COPYRIGHT
=head1 SYNOPSIS
-B<bos getrestart -server> <I<machine name>> [-cell <I<cell name>>]
-[B<-noauth>] [B<-localauth>] [B<-help>]
+B<bos getrestart> B<-server> <I<machine name>> [B<-cell> <I<cell name>>]
+ [B<-noauth>] [B<-localauth>] [B<-help>]
-B<bos getr -s> <I<machine name>> [B<-c> <I<cell name>>] [B<-n>] [B<-l>] [-h]
+B<bos getr> B<-s> <I<machine name>> [B<-c> <I<cell name>>] [B<-n>]
+ [B<-l>] [B<-h>]
=head1 DESCRIPTION
The bos getrestart command displays two restart times from the
-B</usr/afs/local/BosConfig> file on the server machine named by the
+F</usr/afs/local/BosConfig> file on the server machine named by the
B<-server> argument:
=over 4
=item *
-The I<general restart> time at which the BOS Server process
-automatically restarts itself and all processes marked with status
-C<Run> in the B<BosConfig> file. The default is Sunday
-at 4:00 a.m.
-
+The I<general restart> time at which the BOS Server process automatically
+restarts itself and all processes marked with status C<Run> in the
+F<BosConfig> file. The default is Sunday at 4:00 a.m.
=item *
-The I<binary restart> time at which the BOS Server automatically
-restarts any process for which the time stamp on the binary file in the
-B</usr/afs/bin> directory is later than the last restart time for the
-process. The default is 5:00 a.m. Use the B<bos
-getdate> command to list a binary file's timestamp, and the
-B<-long> flag to the B<bos status> command to display a
-process's most recent restart time.
-
+The I<binary restart> time at which the BOS Server automatically restarts
+any process for which the time stamp on the binary file in the
+F</usr/afs/bin> directory is later than the last restart time for the
+process. The default is 5:00 a.m. Use the B<bos getdate> command to list a
+binary file's timestamp, and the B<-long> flag to the B<bos status>
+command to display a process's most recent restart time.
=back
-Use the bos setrestart command to set the restart times.
+Use the B<bos setrestart> command to set the restart times.
=head1 OPTIONS
=over 4
-=item -server
->
+=item B<-server> <I<machine name>>
Indicates the server machine for which to display the restart
times. Identify the machine by IP address or its host name (either
-fully-qualified or abbreviated unambiguously). For details, see the
-introductory reference page for the B<bos> command suite.
+fully-qualified or abbreviated unambiguously). For details, see L<bos(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<bos> 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<bos(8)>.
-=item -noauth
->
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. Do not combine this flag with the B<-localauth>
-flag. For more details, see the introductory B<bos> reference
-page.
+Assigns the unprivileged identity C<anonymous> to the issuer. Do not
+combine this flag with the B<-localauth> flag. For more details, see
+L<bos(8)>.
-=item -localauth
->
+=item B<-localauth>
Constructs a server ticket using a key from the local
-B</usr/afs/etc/KeyFile> file. The B<bos> command
-interpreter presents the ticket to the BOS Server during mutual
-authentication. Do not combine this flag with the B<-cell> or
-B<-noauth> options. For more details, see the introductory
-B<bos> reference page.
+F</usr/afs/etc/KeyFile> file. The B<bos> command interpreter presents the
+ticket to the BOS Server during mutual authentication. Do not combine this
+flag with the B<-cell> or B<-noauth> options. For more details, see
+L<bos(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
The output consists of two lines:
- Server I<machine_name> restarts at I<time>
- Server I<machine_name> restarts for new binaries at I<time>
+ Server <machine_name> restarts at <time>
+ Server <machine_name> restarts for new binaries at <time>
-Possible values for I<time> include:
+Possible values for <time> include:
=over 4
=item *
-C<never>, indicating that the BOS Server never performs that type
-of restart
-
+C<never>, indicating that the BOS Server never performs that type of
+restart.
=item *
-C<now>, indicating that the BOS Server performs that type of
-restart only each time it restarts
-
+C<now>, indicating that the BOS Server performs that type of restart only
+each time it restarts.
=item *
A specified day and time, indicating that the BOS Server performs that
-type of restart once per week. Example: C<sun 4:00
-am>.
-
+type of restart once per week. Example: C<sun 4:00 am>.
=item *
A specified time, indicating that the BOS Server performs that type of
-restart once per day. Examples: C<11:00 pm>,
-C<3:00 am>.
-
+restart once per day. Examples: C<11:00 pm>, C<3:00 am>.
=back
=head1 EXAMPLES
The following example displays the restart times for the machine
-B<db2.abc.com>:
+C<db2.abc.com>:
% bos getrestart db2.abc.com
Server db2.abc.com restarts at sun 4:00 am
Server db2.abc.com restarts for new binaries at 2:15 am
In the following example, the issuer abbreviates the machine name
-B<fs1.abc.com> to B<fs1>, relying on the
-cell's name server to resolve the name. The output echoes the
-abbreviated form.
+C<fs1.abc.com> to C<fs1>, relying on the cell's name server to resolve the
+name. The output echoes the abbreviated form.
% bos getrestart fs1
Server fs1 restarts at sat 5:00 am
=head1 SEE ALSO
-L<BosConfig(1)>,
-L<KeyFile(1)>,
-L<bos(1)>,
-L<bos_getdate(1)>,
-L<bos_setrestart(1)>,
-L<bos_status(1)>
+L<BosConfig(5)>,
+L<KeyFile(5)>,
+L<bos(8)>,
+L<bos_getdate(8)>,
+L<bos_setrestart(8)>,
+L<bos_status(8)>
=head1 COPYRIGHT
=head1 NAME
-bos help - Displays the syntax of specified bos commands or lists
-functional descriptions of all B<bos> commands
+bos help - Displays help for bos commands
=head1 SYNOPSIS
-B<bos help> [B<-topic> <I<help string>>+] [-help]
+B<bos help> [B<-topic> <I<help string>>+] [B<-help>]
-B<bos h> [B<-t> <I<help string>>+] [-h]
+B<bos h> [B<-t> <I<help string>>+] [B<-h>]
=head1 DESCRIPTION
-The bos help command displays the complete online help entry
-(short description and syntax statement) for each command 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<bos> command.
+The B<bos help> command displays the complete online help entry (short
+description and syntax statement) for each command 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<bos> command.
-To list every bos command whose name or short description
-includes a specified keyword, use the B<bos apropos> command.
+To list every bos command whose name or short description includes a
+specified keyword, use the B<bos 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<bos> part of the command name, providing only
-the operation code (for example, specify B<status>, not B<bos
-status>). If this argument is omitted, the output briefly
-describes every B<bos> command.
+entry. Omit the B<bos> part of the command name, providing only the
+operation code (for example, specify B<status>, not B<bos status>). If
+this argument is omitted, the output briefly describes every B<bos>
+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 bos command consists of the
-following two or three lines:
+The online help entry for each bos 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 command displays the online help entry for the bos
-status command:
+The following command displays the online help entry for the B<bos status>
+command:
% bos help status
bos status: show server instance status
=head1 SEE ALSO
-L<bos(1)>,
-L<bos_apropos(1)>
+L<bos(8)>,
+L<bos_apropos(8)>
=head1 COPYRIGHT
=head1 SYNOPSIS
-B<bos install -server> <I<machine name>> -file <I<files to install>>+
-[B<-dir> <I<destination dir>>] [B<-cell> <I<cell name>>]
- [B<-noauth>] [B<-localauth>] [-help]
+B<bos install> B<-server> <I<machine name>> B<-file> <I<files to install>>+
+ [B<-dir> <I<destination dir>>] [B<-cell> <I<cell name>>]
+ [B<-noauth>] [B<-localauth>] [B<-help>]
-B<bos i -s> <I<machine name>> -f <I<files to install>>+
-[B<-d> <I<destination dir>>] [B<-c> <I<cell name>>] [B<-n>] [B<-l>] [B<-h>]
+B<bos i> B<-s> <I<machine name>> B<-f> <I<files to install>>+
+ [B<-d> <I<destination dir>>] [B<-c> <I<cell name>>] [B<-n>]
+ [B<-l>] [B<-h>]
=head1 DESCRIPTION
-The bos install command copies each binary file specified with
-the B<-file> argument to the local disk of the server machine named by
-the B<-server> argument, which is normally the binary distribution
-machine for its CPU/operating system type. The destination directory is
-B</usr/afs/bin> unless the B<-dir> argument indicates an
-alternate directory. The source file's UNIX mode bits are
-preserved in the transfer.
+The B<bos install> command copies each binary file specified with the
+B<-file> argument to the local disk of the server machine named by the
+B<-server> argument, which is normally the binary distribution machine for
+its CPU/operating system type. The destination directory is
+F</usr/afs/bin> unless the B<-dir> argument indicates an alternate
+directory. The source file's UNIX mode bits are preserved in the transfer.
If there is already a file of the same name in the destination directory,
-the BOS Server automatically saves it by adding a C<.BAK>
-extension. If there is a current C<.BAK> version at
-least seven days old, it replaces the current C<.OLD>
-version. If there is no current C<.OLD> version, the
-current C<.BAK> version becomes the C<.OLD>
-version automatically. The B<bos getdate> command displays the
-timestamps on the current versions of the file.
+the BOS Server automatically saves it by adding a C<.BAK> extension. If
+there is a current C<.BAK> version at least seven days old, it replaces
+the current C<.OLD> version. If there is no current C<.OLD> version, the
+current C<.BAK> version becomes the C<.OLD> version automatically. The
+B<bos getdate> command displays the timestamps on the current versions of
+the file.
To start using the new binary immediately, issue the bos restart
-command. Otherwise, the BOS Server automatically restarts the process
-at the time defined in the B</usr/afs/local/BosConfig> file; use
-the B<bos getrestart> command to display the time and the B<bos
-setrestart> time to set it.
+command. Otherwise, the BOS Server automatically restarts the process at
+the time defined in the F</usr/afs/local/BosConfig> file; use the B<bos
+getrestart> command to display the time and the B<bos setrestart> time to
+set it.
=head1 OPTIONS
=over 4
-=item -server
->
+=item B<-server> <I<machine name>>
Indicates the binary distribution machine on which to install the new
binaries. Identify the machine by IP address or its host name (either
-fully-qualified or abbreviated unambiguously). For details, see the
-introductory reference page for the B<bos> command suite.
+fully-qualified or abbreviated unambiguously). For details, see L<bos(8)>.
If the machine is not a binary distribution machine and is running an
-B<upclientbin> process, then the files are overwritten the next time
-the B<upclientbin> process fetches the corresponding file from the
+C<upclientbin> process, then the files are overwritten the next time the
+C<upclientbin> process fetches the corresponding file from the
distribution machine (by default within five minutes).
-=item -file
->
+=item B<-file> <I<files to install>>+
Specifies the complete pathname of each binary file to copy into the
-destination directory. Each source directory can be on the local disk
-or in AFS, in which case the issuer of the B<bos install> command must
-have the necessary AFS access rights and the local machine must run the Cache
-Manager. For the BOS Server to create C<.BAK> and
-C<.OLD> versions, the last element in the pathname (the
-filename) must match the name of a file in the destination directory.
-The reference page for the B<bos create> command lists the standard
-binary file names.
-
-=item -dir
->
+destination directory. Each source directory can be on the local disk or
+in AFS, in which case the issuer of the B<bos install> command must have
+the necessary AFS access rights and the local machine must run the Cache
+Manager. For the BOS Server to create C<.BAK> and C<.OLD> versions, the
+last element in the pathname (the filename) must match the name of a file
+in the destination directory. L<bos_create(8)> lists the standard binary
+file names.
+
+=item B<-dir> <I<destination dir>>
Provides the complete pathname of the local disk directory in which to
install binary files. It is necessary only if the destination directory
-is not B</usr/afs/bin>.
+is not F</usr/afs/bin>.
-=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<bos> 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<bos(8)>.
-=item -noauth
->
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. Do not combine this flag with the B<-localauth>
-flag. For more details, see the introductory B<bos> reference
-page.
+Assigns the unprivileged identity C<anonymous> to the issuer. Do not
+combine this flag with the B<-localauth> flag. For more details, see
+L<bos(8)>.
-=item -localauth
->
+=item B<-localauth>
Constructs a server ticket using a key from the local
-B</usr/afs/etc/KeyFile> file. The B<bos> command
-interpreter presents the ticket to the BOS Server during mutual
-authentication. Do not combine this flag with the B<-cell> or
-B<-noauth> options. For more details, see the introductory
-B<bos> reference page.
+F</usr/afs/etc/KeyFile> file. The B<bos> command interpreter presents the
+ticket to the BOS Server during mutual authentication. Do not combine this
+flag with the B<-cell> or B<-noauth> options. For more details, see
+L<bos(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 copies the file
-B</afs/abc.com/rs_aix42/usr/afs/bin/vlserver> to the file
-B</usr/afs/bin/vlserver> on the machine
-B<fs3.abc.com>, which is the binary distribution machine
-for server machines running AIX 4.2 in the B<abc.com>
-cell. The current version of the B</usr/afs/bin/vlserver> file
-is moved to B</usr/afs/bin/vlserver.BAK>.
-
- % bos install -server fs3.abc.com \
+F</afs/abc.com/rs_aix42/usr/afs/bin/vlserver> to the file
+F</usr/afs/bin/vlserver> on the machine C<fs3.abc.com>, which is the
+binary distribution machine for server machines running AIX 4.2 in the
+C<abc.com> cell. The current version of the F</usr/afs/bin/vlserver> file
+is moved to F</usr/afs/bin/vlserver.BAK>.
+
+ % bos install -server fs3.abc.com \
-file /afs/abc.com/rs_aix42/usr/afs/bin/vlserver
=head1 PRIVILEGE REQUIRED
-The issuer must be listed in the /usr/afs/etc/UserList file on
-the machine named by the B<-server> argument, 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 the
+machine named by the B<-server> argument, 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<BosConfig(1)>,
-L<KeyFile(1)>,
-L<UserList(1)>,
-L<bos(1)>,
-L<bos_getdate(1)>,
-L<bos_getrestart(1)>,
-L<bos_restart(1)>,
-L<bos_setrestart(1)>
+L<BosConfig(5)>,
+L<KeyFile(5)>,
+L<UserList(5)>,
+L<bos(8)>,
+L<bos_getdate(8)>,
+L<bos_getrestart(8)>,
+L<bos_restart(8)>,
+L<bos_setrestart(8)>
=head1 COPYRIGHT
=head1 NAME
-bos listhosts - Displays the contents of the /usr/afs/etc/CellServDB file
+bos listhosts - Displays the contents of the CellServDB file
=head1 SYNOPSIS
-B<bos listhosts -server> <I<machine name>> [-cell <I<cell name>>]
-[B<-noauth>] [B<-localauth>] [B<-help>]
+B<bos listhosts> B<-server> <I<machine name>> [B<-cell> <I<cell name>>]
+ [B<-noauth>] [B<-localauth>] [B<-help>]
-B<bos listh -s> <I<machine name>> [B<-c> <I<cell name>>] [B<-n>] [B<-l>] [-h]
+B<bos listh> B<-s> <I<machine name>> [B<-c> <I<cell name>>] [B<-n>]
+ [B<-l>] [-h]
-B<bos getcell -server> <I<machine name>> [-cell <I<cell name>>]
-[B<-noauth>] [B<-localauth>] [B<-help>]
+B<bos getcell> B<-server> <I<machine name>> [B<-cell> <I<cell name>>]
+ [B<-noauth>] [B<-localauth>] [B<-help>]
-B<bos getc -s> <I<machine name>> [B<-c> <I<cell name>>] [B<-n>] [B<-l>] [-h]
+B<bos getc> B<-s> <I<machine name>> [B<-c> <I<cell name>>] [B<-n>]
+ [B<-l>] [-h]
=head1 DESCRIPTION
-The bos listhosts command formats and displays the list of a
-cell's database server machines from the
-B</usr/afs/etc/CellServDB> file on the server machine named by the
-B<-server> argument.
+The B<bos listhosts> command formats and displays the list of a cell's
+database server machines from the F</usr/afs/etc/CellServDB> file on the
+server machine named by the B<-server> argument.
-To alter the list of machines, use the B<bos addhost> and bos
-removehost commands.
+To alter the list of machines, use the B<bos addhost> and B<bos
+removehost> commands.
=head1 OPTIONS
=over 4
-=item -server
->
+=item B<-server> <I<machine name>>
Indicates the server machine from which to display the
-B</usr/afs/etc/CellServDB> file. Identify the machine by IP
-address or its host name (either fully-qualified or abbreviated
-unambiguously). For details, see the introductory reference page for
-the B<bos> command suite.
+F</usr/afs/etc/CellServDB> file. Identify the machine by IP address or its
+host name (either fully-qualified or abbreviated unambiguously). For
+details, see L<bos(8)>.
For consistent performance in the cell, the output must be the same on
-every server machine. The B<bos addhost> reference page
-explains how to keep the machines synchronized.
+every server machine. The B<bos addhost> reference page explains how to
+keep the machines synchronized.
-=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<bos> 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<bos(8)>.
-=item -noauth
->
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. Do not combine this flag with the B<-localauth>
-flag. For more details, see the introductory B<bos> reference
-page.
+Assigns the unprivileged identity C<anonymous> to the issuer. Do not
+combine this flag with the B<-localauth> flag. For more details, see
+L<bos(8)>.
-=item -localauth
->
+=item B<-localauth>
Constructs a server ticket using a key from the local
-B</usr/afs/etc/KeyFile> file. The B<bos> command
-interpreter presents the ticket to the BOS Server during mutual
-authentication. Do not combine this flag with the B<-cell> or
-B<-noauth> options. For more details, see the introductory
-B<bos> reference page.
+F</usr/afs/etc/KeyFile> file. The B<bos> command interpreter presents the
+ticket to the BOS Server during mutual authentication. Do not combine this
+flag with the B<-cell> or B<-noauth> options. For more details, see
+L<bos(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 first line of the output names the cell to which the server machine
-belongs. Each of the following lines names a database server machine
-for that cell.
+belongs. Each of the following lines names a database server machine for
+that cell.
The C<Host> number assigned to each database server machine is for
-server-internal use only and is not the same as, nor necessarily related to,
-the machine's IP address. The BOS Server assigned it as part of
+server-internal use only and is not the same as, nor necessarily related
+to, the machine's IP address. The BOS Server assigned it as part of
performing the B<bos addhost> command.
=head1 EXAMPLES
The following command displays the database server machines listed in the
-B</usr/afs/etc/CellServDB> file on the machine
-B<fs7.abc.com>.
+F</usr/afs/etc/CellServDB> file on the machine C<fs7.abc.com>.
% bos listhosts fs7.abc.com
Cell name is abc.com
=head1 SEE ALSO
-L<CellServDB (server version)(1)>
-
-L<KeyFile(1)>,
-L<bos(1)>,
-L<bos_addhost(1)>,
-L<bos_removehost(1)>
+L<CellServDB(5)>,
+L<KeyFile(5)>,
+L<bos(8)>,
+L<bos_addhost(8)>,
+L<bos_removehost(8)>
=head1 COPYRIGHT
=head1 NAME
-bos listkeys - Displays the server encryption keys from the
-B</usr/afs/etc/KeyFile> file
+bos listkeys - Displays the server encryption keys from the KeyFile file
=head1 SYNOPSIS
-B<bos listkeys -server> <I<machine name>> [B<-showkey>] [-cell <I<cell name>>]
-[B<-noauth>] [B<-localauth>] [B<-help>]
+B<bos listkeys> B<-server> <I<machine name>> [B<-showkey>]
+ [B<-cell> <I<cell name>>] [B<-noauth>] [B<-localauth>] [B<-help>]
-B<bos listk -se> <I<machine name>> [B<-sh>] [B<-c> <I<cell name>>] [B<-n>] [B<-l>] [-h]
+B<bos listk> B<-se> <I<machine name>> [B<-sh>] [B<-c> <I<cell name>>]
+ [B<-n>] [B<-l>] [B<-h>]
=head1 DESCRIPTION
-The bos listkeys command formats and displays the list of server
-encryption keys from the B</usr/afs/etc/KeyFile> file on the server
+The B<bos listkeys> command formats and displays the list of server
+encryption keys from the F</usr/afs/etc/KeyFile> file on the server
machine named by the B<-server> argument.
-To edit the list of keys, use the B<bos addkey> and bos
-removekey commands.
+To edit the list of keys, use the B<bos addkey> and B<bos removekey>
+commands.
=head1 CAUTIONS
Displaying actual keys on the standard output stream (by including the
-B<-showkey> flag) is a security exposure. Displaying a checksum
-is sufficient for most purposes.
+B<-showkey> flag) is a security exposure. Displaying a checksum is
+sufficient for most purposes.
=head1 OPTIONS
=over 4
-=item -server
->
+=item B<-server> <I<machine name>>
Indicates the server machine from which to display the KeyFile
file. Identify the machine by IP address or its host name (either
-fully-qualified or abbreviated unambiguously). For details, see the
-introductory reference page for the B<bos> command suite.
+fully-qualified or abbreviated unambiguously). For details, see L<bos(8)>.
For consistent performance in the cell, the output must be the same on
-every server machine. The B<bos addkey> reference page explains
-how to keep the machines synchronized.
+every server machine. The B<bos addkey> reference page explains how to
+keep the machines synchronized.
-=item -showkey
->
+=item B<-showkey>
Displays the octal digits that constitute each key.
-=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<bos> 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<bos(8)>.
-=item -noauth
->
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. Do not combine this flag with the B<-localauth>
-flag. For more details, see the introductory B<bos> reference
-page.
+Assigns the unprivileged identity C<anonymous> to the issuer. Do not
+combine this flag with the B<-localauth> flag. For more details, see
+L<bos(8)>.
-=item -localauth
->
+=item B<-localauth>
Constructs a server ticket using a key from the local
-B</usr/afs/etc/KeyFile> file. The B<bos> command
-interpreter presents the ticket to the BOS Server during mutual
-authentication. Do not combine this flag with the B<-cell> or
-B<-noauth> options. For more details, see the introductory
-B<bos> reference page.
+F</usr/afs/etc/KeyFile> file. The B<bos> command interpreter presents the
+ticket to the BOS Server during mutual authentication. Do not combine this
+flag with the B<-cell> or B<-noauth> options. For more details, see
+L<bos(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 output includes one line for each server encryption key listed in the
-B<KeyFile> file, identified by its key version number.
+F<KeyFile> file, identified by its key version number.
-If the -showkey flag is included, the output displays the actual
-string of eight octal numbers that constitute the key. Each octal
-number is a backslash and three decimal digits.
+If the B<-showkey> flag is included, the output displays the actual string
+of eight octal numbers that constitute the key. Each octal number is a
+backslash and three decimal digits.
-If the -showkey flag is not included, the output represents each
-key as a checksum, which is a decimal number derived by encrypting a constant
+If the B<-showkey> flag is not included, the output represents each key as
+a checksum, which is a decimal number derived by encrypting a constant
with the key.
-Following the list of keys or checksums, the string C<Keys last
-changed> indicates when a key was last added to the B<KeyFile>
-file. The words C<All done> indicate the end of the
-output.
+Following the list of keys or checksums, the string C<Keys last changed>
+indicates when a key was last added to the F<KeyFile> file. The words
+C<All done> indicate the end of the output.
For mutual authentication to work properly, the output from the command
-B<kas examine afs> must match the key or checksum with the same key
+C<kas examine afs> must match the key or checksum with the same key
version number in the output from this command.
=head1 EXAMPLES
The following example shows the checksums for the keys stored in the
-B<KeyFile> file on the machine
-B<fs3.abc.com>.
+F<KeyFile> file on the machine C<fs3.abc.com>.
% bos listkeys fs3.abc.com
key 1 has cksum 972037177
Keys last changed on Mon Apr 12 11:24:46 1999.
All done.
-The following example shows the actual keys from the KeyFile
-file on the machine B<fs6.abc.com>.
+The following example shows the actual keys from the F<KeyFile> file on
+the machine C<fs6.abc.com>.
% bos listkeys fs6.abc.com -showkey
key 0 is '\040\205\211\241\345\002\023\211'
=head1 PRIVILEGE REQUIRED
-The issuer must be listed in the /usr/afs/etc/UserList file on
-the machine named by the B<-server> argument, 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 the
+machine named by the B<-server> argument, 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<KeyFile(1)>,
-L<UserList(1)>,
-L<bos_addkey(1)>,
-L<bos_removekey(1)>,
-L<bos_setauth(1)>,
-L<kas_examine(1)>
+L<KeyFile(5)>,
+L<UserList(5)>,
+L<bos_addkey(8)>,
+L<bos_removekey(8)>,
+L<bos_setauth(8)>,
+L<kas_examine(8)>
=head1 COPYRIGHT
=head1 NAME
-bos listusers - Lists the privileged users from the /usr/afs/etc/UserList file
+bos listusers - Lists the privileged users from the UserList file
=head1 SYNOPSIS
-B<bos listusers -server> <I<machine name>> [-cell <I<cell name>>]
-[B<-noauth>] [B<-localauth>] [B<-help>]
+B<bos listusers> B<-server> <I<machine name>> [B<-cell> <I<cell name>>]
+ [B<-noauth>] [B<-localauth>] [B<-help>]
-B<bos listu -s> <I<machine name>> [B<-c> <I<cell name>>] [B<-n>] [B<-l>] [-h]
+B<bos listu> B<-s> <I<machine name>> [B<-c> <I<cell name>>] [B<-n>]
+ [B<-l>] [B<-h>]
=head1 DESCRIPTION
-The bos listusers command lists the user names from the
-B</usr/afs/etc/UserList> file on the file server machine named by the
-B<-server> argument. The users are authorized to issue
-privileged B<bos> and B<vos> commands.
+The B<bos listusers> command lists the user names from the
+F</usr/afs/etc/UserList> file on the file server machine named by the
+B<-server> argument. The users are authorized to issue privileged B<bos>
+and B<vos> commands.
-To edit the list of users, use the B<bos adduser> and bos
-removeuser commands.
+To edit the list of users, use the B<bos adduser> and B<bos removeuser>
+commands.
=head1 OPTIONS
=over 4
-=item -server
->
+=item B<-server> <I<machine name>>
Indicates the server machine from which to display the UserList
file. Identify the machine by IP address or its host name (either
-fully-qualified or abbreviated unambiguously). For details, see the
-introductory reference page for the B<bos> command suite.
+fully-qualified or abbreviated unambiguously). For details, see L<bos(8)>.
For consistent performance in the cell, the output must be the same on
-every server machine. The B<bos adduser> reference page
-explains how to keep the machines synchronized.
+every server machine. The B<bos adduser> reference page explains how to
+keep the machines synchronized.
-=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<bos> 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<bos(8)>.
-=item -noauth
->
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. Do not combine this flag with the B<-localauth>
-flag. For more details, see the introductory B<bos> reference
-page.
+Assigns the unprivileged identity C<anonymous> to the issuer. Do not
+combine this flag with the B<-localauth> flag. For more details, see
+L<bos(8)>.
-=item -localauth
->
+=item B<-localauth>
Constructs a server ticket using a key from the local
-B</usr/afs/etc/KeyFile> file. The B<bos> command
-interpreter presents the ticket to the BOS Server during mutual
-authentication. Do not combine this flag with the B<-cell> or
-B<-noauth> options. For more details, see the introductory
-B<bos> reference page.
+F</usr/afs/etc/KeyFile> file. The B<bos> command interpreter presents the
+ticket to the BOS Server during mutual authentication. Do not combine this
+flag with the B<-cell> or B<-noauth> options. For more details, see
+L<bos(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 lists the users from UserList file on the
-machine B<fs4.abc.com>.
+The following example lists the users from UserList file on the machine
+C<fs4.abc.com>.
% bos listusers fs4.abc.com
SUsers are: pat smith jones terry
=head1 SEE ALSO
-L<KeyFile(1)>,
-L<UserList(1)>,
-L<bos(1)>,
-L<bos_adduser(1)>,
-L<bos_removeuser(1)>
+L<KeyFile(5)>,
+L<UserList(5)>,
+L<bos(8)>,
+L<bos_adduser(8)>,
+L<bos_removeuser(8)>
=head1 COPYRIGHT
=head1 NAME
-bos prune - Removes obsolete versions of files from the /usr/afs/bin and
-B</usr/afs/logs> directories
+bos prune - Removes obsolete files from /usr/afs/bin and /usr/afs/logs
=head1 SYNOPSIS
-B<bos prune -server> <I<machine name>> [B<-bak>] [B<-old>] [B<-core>] [-all]
-[B<-cell> <I<cell name>>] [B<-noauth>] [B<-localauth>] [B<-help>]
+B<bos prune> B<-server> <I<machine name>> [B<-bak>] [B<-old>] [B<-core>]
+ [B<-all>] [B<-cell> <I<cell name>>] [B<-noauth>] [B<-localauth>]
+ [B<-help>]
-B<bos p -s> <I<machine name>> [B<-b>] [B<-o>] [B<-co>] [-a]
-[B<-ce> <I<cell name>>] [B<-n>] [B<-l>] [B<-h>]
+B<bos p> B<-s> <I<machine name>> [B<-b>] [B<-o>] [B<-co>] [B<-a>]
+ [B<-ce> <I<cell name>>] [B<-n>] [B<-l>] [B<-h>]
=head1 DESCRIPTION
-The bos prune command removes files from the local disk of the
-server machine named by the B<-server> argument, as specified by one
-or more of the following flags provided on the command line:
+The B<bos prune> command removes files from the local disk of the server
+machine named by the B<-server> argument, as specified by one or more of
+the following flags provided on the command line:
=over 4
=item *
-The -bak flag removes all files from the
-B</usr/afs/bin> directory that have a C<.BAK>
-extension.
-
+The B<-bak> flag removes all files from the F</usr/afs/bin> directory that
+have a C<.BAK> extension.
=item *
-The -old flag removes all files from the
-B</usr/afs/bin> directory that have a C<.OLD>
-extension.
-
+The B<-old> flag removes all files from the F</usr/afs/bin> directory that
+have a C<.OLD> extension.
=item *
-The -core flag removes all files from the
-B</usr/afs/logs> directory that have a C<core.>
-prefix.
-
+The B<-core> flag removes all files from the F</usr/afs/logs> directory
+that have a C<core.> prefix.
=item *
-The -all flag removes all three types of files at once.
-
+The B<-all> flag removes all three types of files at once.
=back
(If none of these flags are included, the command appears to succeed, but
removes no files at all.)
-To display the timestamp on the current, C<.BAK>, and
-C<.OLD> versions of one or more files, use the B<bos
-getdate> command.
+To display the timestamp on the current, C<.BAK>, and C<.OLD> versions of
+one or more files, use the B<bos getdate> command.
=head1 OPTIONS
=over 4
-=item -server
->
+=item B<-server> <I<machine name>>
-Indicates the server machine from which to remove files. Identify
-the machine by IP address or its host name (either fully-qualified or
-abbreviated unambiguously). For details, see the introductory reference
-page for the B<bos> command suite.
+Indicates the server machine from which to remove files. Identify the
+machine by IP address or its host name (either fully-qualified or
+abbreviated unambiguously). For details, see L<bos(8)>.
-=item -bak
->
+=item B<-bak>
-Removes all files from the /usr/afs/bin directory that have a
-C<.BAK> extension. Do not combine this flag and the
-B<-all> flag.
+Removes all files from the F</usr/afs/bin> directory that have a C<.BAK>
+extension. Do not combine this flag and the B<-all> flag.
-=item -old
->
+=item B<-old>
-Removes all files from the /usr/afs/bin directory that have a
-C<.OLD> extension. Do not combine this flag and the
-B<-all> flag.
+Removes all files from the F</usr/afs/bin> directory that have a C<.OLD>
+extension. Do not combine this flag and the B<-all> flag.
-=item -core
->
+=item B<-core>
-Removes all files from the /usr/afs/logs directory that have a
-C<core.> prefix. Do not combine this flag and the
-B<-all> flag.
+Removes all files from the F</usr/afs/logs> directory that have a C<core.>
+prefix. Do not combine this flag and the B<-all> flag.
-=item -all
->
+=item B<-all>
-Combines the effect of the B<-bak>, -old, and
-B<-core> flags. Do not combine this flag with any of those
-three.
+Combines the effect of the B<-bak>, B<-old>, and B<-core> flags. Do not
+combine this flag with any of those three.
-=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<bos> 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<bos(8)>.
-=item -noauth
->
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. Do not combine this flag with the B<-localauth>
-flag. For more details, see the introductory B<bos> reference
-page.
+Assigns the unprivileged identity C<anonymous> to the issuer. Do not
+combine this flag with the B<-localauth> flag. For more details, see
+L<bos(8)>.
-=item -localauth
->
+=item B<-localauth>
Constructs a server ticket using a key from the local
-B</usr/afs/etc/KeyFile> file. The B<bos> command
-interpreter presents the ticket to the BOS Server during mutual
-authentication. Do not combine this flag with the B<-cell> or
-B<-noauth> options. For more details, see the introductory
-B<bos> reference page.
+F</usr/afs/etc/KeyFile> file. The B<bos> command interpreter presents the
+ticket to the BOS Server during mutual authentication. Do not combine this
+flag with the B<-cell> or B<-noauth> options. For more details, see
+L<bos(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 removes all files from the /usr/afs/bin
-directory on the machine B<fs3.abc.com> that have a
-C<.BAK> or C<.OLD> extension.
+The following example removes all files from the F</usr/afs/bin> directory
+on the machine C<fs3.abc.com> that have a C<.BAK> or C<.OLD> extension.
% bos prune -server fs3.abc.com -bak -old
-The following example removes all files from the /usr/afs/bin
-directory on the machine B<db2.abc.com> that have a
-C<.BAK> or C<.OLD> extension, and all files from
-the B</usr/afs/logs> directory that have a C<core.>
+The following example removes all files from the F</usr/afs/bin> directory
+on the machine C<db2.abc.com> that have a C<.BAK> or C<.OLD> extension,
+and all files from the F</usr/afs/logs> directory that have a C<core.>
prefix.
% bos prune -server db2.abc.com -all
=head1 PRIVILEGE REQUIRED
-The issuer must be listed in the /usr/afs/etc/UserList file on
-the machine named by the B<-server> argument, 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 the
+machine named by the B<-server> argument, 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<KeyFile(1)>,
-L<UserList(1)>,
-L<bos(1)>,
-L<bos_getdate(1)>
+L<KeyFile(5)>,
+L<UserList(5)>,
+L<bos(8)>,
+L<bos_getdate(8)>
=head1 COPYRIGHT
=head1 NAME
-bos removehost - Removes a database server machine from the
-B</usr/afs/etc/CellServDB> file
+bos removehost - Removes a database server machine from the CellServDB file
=head1 SYNOPSIS
-B<bos removehost -server> <I<machine name>> -host <I<host name>>+
-[B<-cell> <I<cell name>>] [B<-noauth>] [B<-localauth>] [B<-help>]
+B<bos removehost> B<-server> <I<machine name>> B<-host> <I<host name>>+
+ [B<-cell> <I<cell name>>] [B<-noauth>] [B<-localauth>] [B<-help>]
-B<bos removeh -s> <I<machine name>> B<-ho> <I<host name>>+ [-c <I<cell name>>]
-[B<-n>] [B<-l>] [B<-he>]
+B<bos removeh> B<-s> <I<machine name>> B<-ho> <I<host name>>+
+ [B<-c> <I<cell name>>] [B<-n>] [B<-l>] [B<-he>]
=head1 DESCRIPTION
-The bos removehost command removes the entry for each database
-server machine specified with the B<-host> argument from the
-B</usr/afs/etc/CellServDB> file on the server machine named by the
+The B<bos removehost> command removes the entry for each database server
+machine specified with the B<-host> argument from the
+F</usr/afs/etc/CellServDB> file on the server machine named by the
B<-server> argument.
=head1 CAUTIONS
After executing this command (and waiting for the Update Server to
-propagate the changes, if it is used), restart the database server processes
-on all database server machines to force election of a quorum that includes
-the new set of machines listed in the B</usr/afs/etc/CellServDB>
-file. The I<IBM AFS Quick Beginnings> explains in more detail
-how to add and remove database server machines.
+propagate the changes, if it is used), restart the database server
+processes on all database server machines to force election of a quorum
+that includes the new set of machines listed in the
+F</usr/afs/etc/CellServDB> file. The I<IBM AFS Quick Beginnings> explains
+in more detail how to add and remove database server machines.
=head1 OPTIONS
=over 4
-=item -server
->
+=item B<-server> <I<machine name>>
Indicates the server machine on which to change the
-B</usr/afs/etc/CellServDB> file. Identify the machine by IP
-address or its host name (either fully-qualified or abbreviated
-unambiguously). For details, see the introductory reference page for
-the B<bos> command suite.
+F</usr/afs/etc/CellServDB> file. Identify the machine by IP address or its
+host name (either fully-qualified or abbreviated unambiguously). For
+details, see L<bos(8)>.
-In cells that run the United States edition of AFS and use the Update
-Server to distribute the contents of the B</usr/afs/etc> directory, it
-is conventional to specify only the system control machine as a value for the
-B<-server> argument. In cells that run the international
-version of AFS, repeat the command for each file server machine. For
-further discussion, see the introductory reference page for the B<bos>
-command suite.
+In cells that use the Update Server to distribute the contents of the
+F</usr/afs/etc> directory, it is conventional to specify only the system
+control machine as a value for the B<-server> argument. Otherwise, repeat
+the command for each file server machine. For further discussion, see
+L<bos(8)>.
-=item -host
->
+=item B<-host> <I<host name>>+
-Specifies the fully-qualified host name (such as
-B<fs2.abc.com>) of each database server machine to
-remove from the B<CellServDB> file.
+Specifies the fully-qualified host name (such as C<fs2.abc.com>) of each
+database server machine to remove from the B<CellServDB> file.
-=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<bos> 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<bos(8)>.
-=item -noauth
->
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. Do not combine this flag with the B<-localauth>
-flag. For more details, see the introductory B<bos> reference
-page.
+Assigns the unprivileged identity C<anonymous> to the issuer. Do not
+combine this flag with the B<-localauth> flag. For more details, see
+L<bos(8)>.
-=item -localauth
->
+=item B<-localauth>
Constructs a server ticket using a key from the local
-B</usr/afs/etc/KeyFile> file. The B<bos> command
-interpreter presents the ticket to the BOS Server during mutual
-authentication. Do not combine this flag with the B<-cell> or
-B<-noauth> options. For more details, see the introductory
-B<bos> reference page.
+F</usr/afs/etc/KeyFile> file. The B<bos> command interpreter presents the
+ticket to the BOS Server during mutual authentication. Do not combine this
+flag with the B<-cell> or B<-noauth> options. For more details, see
+L<bos(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 removes the former database server machine
-B<db2.abc.com> from the B<CellServDB> file on
-the system control machine B<fs1.abc.com>.
+C<db2.abc.com> from the F<CellServDB> file on the system control machine
+C<fs1.abc.com>.
% bos removehost -server fs1.abc.com -host db2.abc.com
=head1 PRIVILEGE REQUIRED
-The issuer must be listed in the /usr/afs/etc/UserList file on
-the machine named by the B<-server> argument, 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 the
+machine named by the B<-server> argument, 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<KeyFile(1)>,
-L<UserList(1)>,
-L<bos(1)>,
-L<bos_addhost(1)>,
-L<bos_listhosts(1)>
+L<KeyFile(5)>,
+L<UserList(5)>,
+L<bos(8)>,
+L<bos_addhost(8)>,
+L<bos_listhosts(8)>
I<IBM AFS Quick Beginnings>
=head1 NAME
-bos removekey - Removes a server encryption key from the /usr/afs/etc/KeyFile
-file
+bos removekey - Removes a server encryption key from the KeyFile file
=head1 SYNOPSIS
-B<bos removekey -server> <I<machine name>> -kvno <I<key version number>>+
-[B<-cell> <I<cell name>>] [B<-noauth>] [B<-localauth>] [B<-help>]
+B<bos removekey> B<-server> <I<machine name>>
+ B<-kvno> <I<key version number>>+ [B<-cell> <I<cell name>>]
+ [B<-noauth>] [B<-localauth>] [B<-help>]
-B<bos removek -s> <I<machine name>> -k <I<key version number>>+
-[B<-c> <I<cell name>>] [B<-n>] [B<-l>] [B<-h>]
+B<bos removek> B<-s> <I<machine name>> B<-k> <I<key version number>>+
+ [B<-c> <I<cell name>>] [B<-n>] [B<-l>] [B<-h>]
=head1 DESCRIPTION
-The bos removekey command removes each specified encryption key
-from the B</usr/afs/etc/KeyFile> file on the machine named by the
-B<-server> argument. Use the B<-kvno> argument to
-identify each key by its key version number; use the B<bos
-listkeys> command to display the key version numbers.
+The B<bos removekey> command removes each specified encryption key from
+the F</usr/afs/etc/KeyFile> file on the machine named by the B<-server>
+argument. Use the B<-kvno> argument to identify each key by its key
+version number; use the B<bos listkeys> command to display the key version
+numbers.
=head1 CAUTIONS
Before removing a obsolete key, verify that the cell's maximum ticket
lifetime has passed since the current key was defined using the B<kas
-setpassword> and B<bos addkey> commands. This ensures that
-no clients still possess tickets encrypted with the obsolete key.
+setpassword> and B<bos addkey> commands. This ensures that no clients
+still possess tickets encrypted with the obsolete key.
=head1 OPTIONS
=over 4
-=item -server
->
+=item B<-server> <I<machine name>>
Indicates the server machine on which to change the
-B</usr/afs/etc/KeyFile> file. Identify the machine by IP
-address or its host name (either fully-qualified or abbreviated
-unambiguously). For details, see the introductory reference page for
-the B<bos> command suite.
-
-In cells that run the United States edition of AFS and use the Update
-Server to distribute the contents of the B</usr/afs/etc> directory, it
-is conventional to specify only the system control machine as a value for the
-B<-server> argument. In cells that run the international
-version of AFS, repeat the command for each file server machine. For
-further discussion, see the introductory reference page for the B<bos>
-command suite.
-
-=item -kvno
->
+F</usr/afs/etc/KeyFile> file. Identify the machine by IP address or its
+host name (either fully-qualified or abbreviated unambiguously). For
+details, see L<bos(8)>.
+
+In cells that use the Update Server to distribute the contents of the
+F</usr/afs/etc> directory, it is conventional to specify only the system
+control machine as a value for the B<-server> argument. Otherwise, repeat
+the command for each file server machine. For further discussion, see
+L<bos(8)>.
+
+=item B<-kvno> <I<key version number>>+
Specifies the key version number of each key to remove.
-=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<bos> 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<bos(8)>.
-=item -noauth
->
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. Do not combine this flag with the B<-localauth>
-flag. For more details, see the introductory B<bos> reference
-page.
+Assigns the unprivileged identity C<anonymous> to the issuer. Do not
+combine this flag with the B<-localauth> flag. For more details, see
+L<bos(8)>.
-=item -localauth
->
+=item B<-localauth>
Constructs a server ticket using a key from the local
-B</usr/afs/etc/KeyFile> file. The B<bos> command
-interpreter presents the ticket to the BOS Server during mutual
-authentication. Do not combine this flag with the B<-cell> or
-B<-noauth> options. For more details, see the introductory
-B<bos> reference page.
+F</usr/afs/etc/KeyFile> file. The B<bos> command interpreter presents the
+ticket to the BOS Server during mutual authentication. Do not combine this
+flag with the B<-cell> or B<-noauth> options. For more details, see
+L<bos(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 removes the keys with key version numbers 5 and 6
-from the B<KeyFile> file on the system control machine
-B<fs1.abc.com>.
+from the F<KeyFile> file on the system control machine C<fs1.abc.com>.
% bos removekey -server fs1.abc.com -kvno 5 6
=head1 PRIVILEGE REQUIRED
-The issuer must be listed in the /usr/afs/etc/UserList file on
-the machine named by the B<-server> argument, 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 the
+machine named by the B<-server> argument, 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<KeyFile(1)>,
-L<UserList(1)>,
-L<bos(1)>,
-L<bos_addkey(1)>,
-L<bos_listkeys(1)>
+L<KeyFile(5)>,
+L<UserList(5)>,
+L<bos(8)>,
+L<bos_addkey(8)>,
+L<bos_listkeys(8)>
=head1 COPYRIGHT
=head1 NAME
-bos removeuser - Removes a privileged user from the /usr/afs/etc/UserList file
+bos removeuser - Removes a privileged user from the UserList file
=head1 SYNOPSIS
-B<bos removeuser -server> <I<machine name>> -user <I<user names>>+
-[B<-cell> <I<cell name>>] [B<-noauth>] [B<-localauth>] [B<-help>]
+B<bos removeuser> B<-server> <I<machine name>> B<-user> <I<user names>>+
+ [B<-cell> <I<cell name>>] [B<-noauth>] [B<-localauth>] [B<-help>]
-B<bos removeu -s> <I<machine name>> B<-u> <I<user names>>+ [-c <I<cell name>>]
-[B<-n>] [B<-l>] [B<-h>]
+B<bos removeu> B<-s> <I<machine name>> B<-u> <I<user names>>+
+ [B<-c> <I<cell name>>] [B<-n>] [B<-l>] [B<-h>]
=head1 DESCRIPTION
-The bos removeuser command removes each user name specified with
-the B<-user> argument from the B</usr/afs/etc/UserList> file
-on the machine named by the B<-server> argument.
+The B<bos removeuser> command removes each user name specified with the
+B<-user> argument from the F</usr/afs/etc/UserList> file on the machine
+named by the B<-server> argument.
=head1 OPTIONS
=over 4
-=item -server
->
+=item B<-server> <I<machine name>>
Indicates the server machine on which to change the
-B</usr/afs/etc/UserList> file. Identify the machine by IP
-address or its host name (either fully-qualified or abbreviated
-unambiguously). For details, see the introductory reference page for
-the B<bos> command suite.
-
-In cells that run the United States edition of AFS and use the Update
-Server to distribute the contents of the B</usr/afs/etc> directory, it
-is conventional to specify only the system control machine as a value for the
-B<-server> argument. In cells that run the international
-version of AFS, repeat the command for each file server machine. For
-further discussion, see the introductory reference page for the B<bos>
-command suite.
-
-=item -user
->
+F</usr/afs/etc/UserList> file. Identify the machine by IP address or its
+host name (either fully-qualified or abbreviated unambiguously). For
+details, see L<bos(8)>.
+
+In cells that use the Update Server to distribute the contents of the
+F</usr/afs/etc> directory, it is conventional to specify only the system
+control machine as a value for the B<-server> argument. Otherwise, repeat
+the command for each file server machine. For further discussion, see
+L<bos(8)>.
+
+=item B<-user> <I<user names>>+
Specifies each user name to remove.
-=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<bos> 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<bos(8)>.
-=item -noauth
->
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. Do not combine this flag with the B<-localauth>
-flag. For more details, see the introductory B<bos> reference
-page.
+Assigns the unprivileged identity C<anonymous> to the issuer. Do not
+combine this flag with the B<-localauth> flag. For more details, see
+L<bos(8)>.
-=item -localauth
->
+=item B<-localauth>
Constructs a server ticket using a key from the local
-B</usr/afs/etc/KeyFile> file. The B<bos> command
-interpreter presents the ticket to the BOS Server during mutual
-authentication. Do not combine this flag with the B<-cell> or
-B<-noauth> options. For more details, see the introductory
-B<bos> reference page.
+F</usr/afs/etc/KeyFile> file. The B<bos> command interpreter presents the
+ticket to the BOS Server during mutual authentication. Do not combine this
+flag with the B<-cell> or B<-noauth> options. For more details, see
+L<bos(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 removes the users B<pat> and jones
-from the B<UserList> file on the system control machine
-B<fs1.abc.com>.
+The following example removes the users C<pat> and C<jones> from the
+F<UserList> file on the system control machine C<fs1.abc.com>.
% bos removeuser -server fs1.abc.com -user pat jones
=head1 PRIVILEGE REQUIRED
-The issuer must be listed in the /usr/afs/etc/UserList file on
-the machine named by the B<-server> argument, 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 the
+machine named by the B<-server> argument, 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<KeyFile(1)>,
-L<UserList(1)>,
-L<bos(1)>,
-L<bos_addkey(1)>,
-L<bos_listkeys(1)>
+L<KeyFile(5)>,
+L<UserList(5)>,
+L<bos(8)>,
+L<bos_addkey(8)>,
+L<bos_listkeys(8)>
=head1 COPYRIGHT
=head1 SYNOPSIS
-B<bos restart -server> <I<machine name>> [B<-instance> <I<instances>>+] [-bosserver]
-[B<-all>] [B<-cell> <I<cell name>>] [B<-noauth>] [B<-localauth>] [B<-help>]
+B<bos restart> B<-server> <I<machine name>> [B<-instance> <I<instances>>+]
+ [B<-bosserver>] [B<-all>] [B<-cell> <I<cell name>>] [B<-noauth>]
+ [B<-localauth>] [B<-help>]
-B<bos res -s> <I<machine name>> [B<-i> <I<instances>>+] [B<-b>] [-a]
-[B<-c> <I<cell name>>] [B<-n>] [B<-l>] [B<-h>]
+B<bos res> B<-s> <I<machine name>> [B<-i> <I<instances>>+] [B<-b>]
+ [B<-a>] [B<-c> <I<cell name>>] [B<-n>] [B<-l>] [B<-h>]
=head1 DESCRIPTION
-The bos restart command stops and immediately restarts server
-processes on the server machine named by the B<-server>
-argument. Indicate which process or processes to restart by providing
-one of the following arguments:
+The B<bos restart> command stops and immediately restarts server processes
+on the server machine named by the B<-server> argument. Indicate which
+process or processes to restart by providing one of the following
+arguments:
=over 4
=item *
-The -instance argument names each AFS server process to stop
-and restart immediately, regardless of its status flag in the
-B</usr/afs/local/BosConfig> file. Do not include
-B<bosserver> in the list of processes; use the
-B<-bosserver> flag instead.
-
+The B<-instance> argument names each AFS server process to stop and
+restart immediately, regardless of its status flag in the
+F</usr/afs/local/BosConfig> file. Do not include B<bosserver> in the list
+of processes; use the B<-bosserver> flag instead.
=item *
-The -bosserver flag stops all AFS server processes running on
-the machine, including the BOS Server. A new BOS Server starts
-immediately, and it starts a new instance of each process that is marked with
-the C<Run> status flag in the B<BosConfig> file.
-
+The B<-bosserver> flag stops all AFS server processes running on the
+machine, including the BOS Server. A new BOS Server starts immediately,
+and it starts a new instance of each process that is marked with the
+C<Run> status flag in the F<BosConfig> file.
=item *
-The -all flag stops all AFS server processes running on the
-machine, except the BOS Server, and immediately restarts the processes that
-are marked with the C<Run> status flag in the B<BosConfig>
-file.
-
+The B<-all> flag stops all AFS server processes running on the machine,
+except the BOS Server, and immediately restarts the processes that are
+marked with the C<Run> status flag in the F<BosConfig> file.
=back
-This command does not change a process's status flag in the
-B<BosConfig> file.
+This command does not change a process's status flag in the F<BosConfig>
+file.
=head1 OPTIONS
=over 4
-=item -server
->
+=item B<-server> <I<machine name>>
-Indicates the server machine on which to restart each process.
-Identify the machine by IP address or its host name (either fully-qualified or
-abbreviated unambiguously). For details, see the introductory reference
-page for the B<bos> command suite.
+Indicates the server machine on which to restart each process. Identify
+the machine by IP address or its host name (either fully-qualified or
+abbreviated unambiguously). For details, see L<bos(8)>.
-=item -instance
->
+=item B<-instance> <I<instances>>+
Names each process to stop and then restart immediately regardless of its
-status flag setting. Use the process name assigned with the
-B<-instance> argument to the B<bos create> command. The
-output from the B<bos status> command lists the names. Provide
-this flag or one of the B<-bosserver> or B<-all> options, but
-do not combine them.
+status flag setting. Use the process name assigned with the B<-instance>
+argument to the B<bos create> command. The output from the B<bos status>
+command lists the names. Provide this flag or one of the B<-bosserver> or
+B<-all> options, but do not combine them.
-=item -bosserver
->
+=item B<-bosserver>
Stops all AFS server processes running on the machine, including the BOS
Server. A new BOS Server instance immediately starts, and starts all
-processes marked with the C<Run> status flag in the
-B<BosConfig> file. Provide this flag or one of the
-B<-instance> or B<-all> options, but do not combine
-them.
+processes marked with the C<Run> status flag in the F<BosConfig>
+file. Provide this flag or one of the B<-instance> or B<-all> options, but
+do not combine them.
-=item -all
->
+=item B<-all>
Stops all AFS server processes running on the machine other than the BOS
Server, and immediately restarts the processes marked with the B<Run>
-status flag in the B<BosConfig> file. Provide this flag or one
-of the B<-instance> or B<-bosserver> options, but do not
-combine them.
+status flag in the F<BosConfig> file. Provide this flag or one of the
+B<-instance> or B<-bosserver> options, but do not combine them.
-=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<bos> 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<bos(8)>.
-=item -noauth
->
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. Do not combine this flag with the B<-localauth>
-flag. For more details, see the introductory B<bos> reference
-page.
+Assigns the unprivileged identity C<anonymous> to the issuer. Do not
+combine this flag with the B<-localauth> flag. For more details, see
+L<bos(8)>.
-=item -localauth
->
+=item B<-localauth>
Constructs a server ticket using a key from the local
-B</usr/afs/etc/KeyFile> file. The B<bos> command
-interpreter presents the ticket to the BOS Server during mutual
-authentication. Do not combine this flag with the B<-cell> or
-B<-noauth> options. For more details, see the introductory
-B<bos> reference page.
+F</usr/afs/etc/KeyFile> file. The B<bos> command interpreter presents the
+ticket to the BOS Server during mutual authentication. Do not combine this
+flag with the B<-cell> or B<-noauth> options. For more details, see
+L<bos(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 stops and restarts all processes running on the
-machine B<fs3.abc.com>, including the BOS Server.
+machine C<fs3.abc.com>, including the BOS Server.
% bos restart -server fs3.abc.com -bosserver
The following command stops and restarts all processes running on the
-machine B<fs5.abc.com>, excluding the BOS Server.
+machine C<fs5.abc.com>, excluding the BOS Server.
% bos restart -server fs5.abc.com -all
The following command stops and restarts the Protection Server and Volume
-Location (VL) Server processes on the machine
-B<db3.abc.com>:
+Location (VL) Server processes on the machine C<db3.abc.com>:
% bos restart -server db3.abc.com -instance ptserver vlserver
=head1 PRIVILEGE REQUIRED
-The issuer must be listed in the /usr/afs/etc/UserList file on
-the machine named by the B<-server> argument, 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 the
+machine named by the B<-server> argument, 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<BosConfig(1)>,
-L<KeyFile(1)>,
-L<UserList(1)>,
-L<bos(1)>,
-L<bos_create(1)>,
-L<bos_status(1)>
+L<BosConfig(5)>,
+L<KeyFile(5)>,
+L<UserList(5)>,
+L<bos(8)>,
+L<bos_create(8)>,
+L<bos_status(8)>
=head1 COPYRIGHT
=head1 SYNOPSIS
-B<bos salvage -server> <I<machine name>> [-partition <I<salvage partition>>]
-[B<-volume> <I<salvage volume number or volume name>>]
- [B<-file> <I<salvage log output file>>] [B<-all>] [-showlog]
- [-parallel <I<# of max parallel partition salvaging>>]
- [-tmpdir <I<directory to place tmp files>>]
- [B<-orphans> <B<ignore> | B<remove> | attach>]
- [-cell <I<cell name>>]
- [B<-noauth>] [B<-localauth>] [-help]
-
-B<bos sa -se> <I<machine name>> [-part <I<salvage partition>>]
-[B<-v> <I<salvage volume number or volume name>>]
- [B<-f> <I<salvage log output file>>] [B<-a>] [-sh]
- [-para <I<# of max parallel partition salvaging>>]
- [-t <I<directory to place tmp files>>]
- [B<-o> <B<ignore> | B<remove> | attach>]
- [B<-c> <I<cell name>>] [B<-n>] [B<-l>] [-h]
+B<bos salvage> B<-server> <I<machine name>>
+ [B<-partition> <I<salvage partition>>]
+ [B<-volume> <I<salvage volume number or volume name>>]
+ [B<-file> <I<salvage log output file>>] [B<-all>] [B<-showlog>]
+ [B<-parallel> <I<# of max parallel partition salvaging>>]
+ [B<-tmpdir> <I<directory to place tmp files>>]
+ [B<-orphans> (ignore | remove | attach)] [B<-cell> <I<cell name>>]
+ [B<-noauth>] [B<-localauth>] [B<-help>]
+
+B<bos sa> B<-se> <I<machine name>> [B<-part> <I<salvage partition>>]
+ [B<-v> <I<salvage volume number or volume name>>]
+ [B<-f> <I<salvage log output file>>] [B<-a>] [B<-sh>]
+ [<-para> <I<# of max parallel partition salvaging>>]
+ [B<-t> <I<directory to place tmp files>>]
+ [B<-o> (ignore | remove | attach)] [B<-c> <I<cell name>>] [B<-n>]
+ [B<-l>] [B<-h>]
=head1 DESCRIPTION
-The bos salvage command salvages (restores internal consistency
-to) one or more volumes on the file server machine named by the
-B<-server> argument. When processing one or more partitions,
-the command restores consistency to corrupted read/write volumes where
-possible. For read-only or backup volumes, it inspects only the volume
-header:
+The B<bos salvage> command salvages (restores internal consistency to) one
+or more volumes on the file server machine named by the B<-server>
+argument. When processing one or more partitions, the command restores
+consistency to corrupted read/write volumes where possible. For read-only
+or backup volumes, it inspects only the volume header:
=over 4
If the volume header is corrupted, the Salvager removes the volume
completely and records the removal in its log file,
-B</usr/afs/logs/SalvageLog>. Issue the B<vos release>
-or B<vos backup> command to create the read-only or backup volume
-again.
-
+F</usr/afs/logs/SalvageLog>. Issue the B<vos release> or B<vos backup>
+command to create the read-only or backup volume again.
=item *
If the volume header is intact, the Salvager skips the volume (does not
-check for corruption in the contents). However, if the File Server
-notices corruption as it initializes, it sometimes refuses to attach the
-volume or bring it online. In this case, it is simplest to remove the
-volume by issuing the B<vos remove> or B<vos zap>
-command. Then issue the B<vos release> or B<vos backup>
-command to create it again.
-
+check for corruption in the contents). However, if the File Server notices
+corruption as it initializes, it sometimes refuses to attach the volume or
+bring it online. In this case, it is simplest to remove the volume by
+issuing the B<vos remove> or B<vos zap> command. Then issue the B<vos
+release> or B<vos backup> command to create it again.
=back
=item *
-To process all volumes on a file server machine, provide the
-B<-server> argument and the B<-all> flag. No volumes on
-the machine are accessible to Cache Managers during the salvage operation,
-because the BOS Server stops the File Server and Volume Server processes while
-the Salvager runs. The BOS Server automatically restarts them when the
-operation completes.
-
+To process all volumes on a file server machine, provide the B<-server>
+argument and the B<-all> flag. No volumes on the machine are accessible to
+Cache Managers during the salvage operation, because the BOS Server stops
+the File Server and Volume Server processes while the Salvager runs. The
+BOS Server automatically restarts them when the operation completes.
=item *
-To process all volumes on one partition, provide the -server
-and B<-partition> arguments. As for a salvage of the entire
-machine, no volumes on the machine are accessible to Cache Managers during the
-salvage operation. The BOS Server automatically restarts the File
-Server and Volume Server when the operation completes.
-
+To process all volumes on one partition, provide the B<-server> and
+B<-partition> arguments. As for a salvage of the entire machine, no
+volumes on the machine are accessible to Cache Managers during the salvage
+operation. The BOS Server automatically restarts the File Server and
+Volume Server when the operation completes.
=item *
-To salvage only one read/write volume, combine the -server,
-B<-partition>, and B<-volume> arguments. Only that
-volume is inaccessible to Cache Managers, because the BOS Server does not
-shutdown the File Server and Volume Server processes during the salvage of a
-single volume. Do not name a read-only or backup volume with the
-B<-volume> argument. Instead, remove the volume, using the
-B<vos remove> or B<vos zap> command. Then create a new
-copy of the volume with the B<vos release> or B<vos backup>
-command.
-
+To salvage only one read/write volume, combine the B<-server>,
+B<-partition>, and B<-volume> arguments. Only that volume is inaccessible
+to Cache Managers, because the BOS Server does not shutdown the File
+Server and Volume Server processes during the salvage of a single
+volume. Do not name a read-only or backup volume with the B<-volume>
+argument. Instead, remove the volume, using the B<vos remove> or B<vos
+zap> command. Then create a new copy of the volume with the B<vos release>
+or B<vos backup> command.
=back
-During the salvage of an entire machine or partition, the bos
-status command reports the B<fs> process's auxiliary status
-as C<Salvaging file system>.
-
-The Salvager always writes a trace to the
-B</usr/afs/logs/SalvageLog> file on the file server machine where it
-runs. To record the trace in another file as well (either in AFS or on
-the local disk of the machine where the B<bos salvage> command is
-issued), name the file with the B<-file> argument. To display
-the trace on the standard output stream as it is written to the
-B</usr/afs/logs/SalvageLog> file, include the B<-showlog>
+During the salvage of an entire machine or partition, the B<bos status>
+command reports the C<fs> process's auxiliary status as C<Salvaging file
+system>.
+
+The Salvager always writes a trace to the F</usr/afs/logs/SalvageLog> file
+on the file server machine where it runs. To record the trace in another
+file as well (either in AFS or on the local disk of the machine where the
+B<bos salvage> command is issued), name the file with the B<-file>
+argument. To display the trace on the standard output stream as it is
+written to the F</usr/afs/logs/SalvageLog> file, include the B<-showlog>
flag.
-By default, multiple Salvager subprocesses run in parallel: one for
-each partition up to four, and four subprocesses for four or more
-partitions. To increase or decrease the number of subprocesses running
-in parallel, provide a positive integer value for the B<-parallel>
-argument.
-
-If there is more than one server partition on a physical disk, the Salvager
-by default salvages them serially to avoid the inefficiency of constantly
-moving the disk head from one partition to another. However, this
-strategy is often not ideal if the partitions are configured as logical
-volumes that span multiple disks. To force the Salvager to salvage
-logical volumes in parallel, provide the string B<all> as the value
-for the B<-parallel> argument. Provide a positive integer to
-specify the number of subprocesses to run in parallel (for example,
-B<-parallel 5all> for five subprocesses), or omit the integer to run
-up to four subprocesses, depending on the number of logical volumes being
-salvaged.
-
-The Salvager creates temporary files as it runs, by default writing them to
-the partition it is salvaging. The number of files can be quite large,
-and if the partition is too full to accommodate them, the Salvager terminates
-without completing the salvage operation (it always removes the temporary
-files before exiting). Other Salvager subprocesses running at the same
-time continue until they finish salvaging all other partitions where there is
-enough disk space for temporary files. To complete the interrupted
-salvage, reissue the command against the appropriate partitions, adding the
-B<-tmpdir> argument to redirect the temporary files to a local disk
-directory that has enough space.
-
-The -orphans argument controls how the Salvager handles orphaned
-files and directories that it finds on server partitions it is
-salvaging. An I<orphaned> element is completely inaccessible
-because it is not referenced by the vnode of any directory that can act as its
-parent (is higher in the filespace). Orphaned objects occupy space on
-the server partition, but do not count against the volume's quota.
+By default, multiple Salvager subprocesses run in parallel: one for each
+partition up to four, and four subprocesses for four or more
+partitions. To increase or decrease the number of subprocesses running in
+parallel, provide a positive integer value for the B<-parallel> argument.
+
+If there is more than one server partition on a physical disk, the
+Salvager by default salvages them serially to avoid the inefficiency of
+constantly moving the disk head from one partition to another. However,
+this strategy is often not ideal if the partitions are configured as
+logical volumes that span multiple disks. To force the Salvager to salvage
+logical volumes in parallel, provide the string C<all> as the value for
+the B<-parallel> argument. Provide a positive integer to specify the
+number of subprocesses to run in parallel (for example, C<-parallel 5all>
+for five subprocesses), or omit the integer to run up to four
+subprocesses, depending on the number of logical volumes being salvaged.
+
+The Salvager creates temporary files as it runs, by default writing them
+to the partition it is salvaging. The number of files can be quite large,
+and if the partition is too full to accommodate them, the Salvager
+terminates without completing the salvage operation (it always removes the
+temporary files before exiting). Other Salvager subprocesses running at
+the same time continue until they finish salvaging all other partitions
+where there is enough disk space for temporary files. To complete the
+interrupted salvage, reissue the command against the appropriate
+partitions, adding the B<-tmpdir> argument to redirect the temporary files
+to a local disk directory that has enough space.
+
+The B<-orphans> argument controls how the Salvager handles orphaned files
+and directories that it finds on server partitions it is salvaging. An
+I<orphaned> element is completely inaccessible because it is not
+referenced by the vnode of any directory that can act as its parent (is
+higher in the filespace). Orphaned objects occupy space on the server
+partition, but do not count against the volume's quota.
=head1 CAUTIONS
Running this command can result in data loss if the Salvager process can
-repair corruption only by removing the offending data. Consult the
-I<IBM AFS Administration Guide> for more information.
+repair corruption only by removing the offending data. Consult the I<IBM
+AFS Administration Guide> for more information.
=head1 OPTIONS
=over 4
-=item -server
+=item B<-server> <I<machine name>>
-Indicates the file server machine on which to salvage volumes.
-Identify the machine by IP address or its host name (either fully-qualified or
-abbreviated unambiguously). For details, see the introductory reference
-page for the B<bos> command suite.
+Indicates the file server machine on which to salvage volumes. Identify
+the machine by IP address or its host name (either fully-qualified or
+abbreviated unambiguously). For details, see L<bos(8)>.
-=item -partition
+=item B<-partition> <I<salvage partition>>
-Specifies a single partition on which to salvage all volumes.
-Provide the complete partition name (for example B</vicepa>) or one of
-the following abbreviated forms:
+Specifies a single partition on which to salvage all volumes. Provide the
+complete partition name (for example F</vicepa>) or one of the following
+abbreviated forms:
- B</vicepa> = B<vicepa> = B<a> = 0
- B</vicepb> = B<vicepb> = B<b> = 1
+ /vicepa = vicepa = a = 0
+ /vicepb = vicepb = b = 1
-After /vicepz (for which the index is 25) comes
+After F</vicepz> (for which the index is 25) comes
- B</vicepaa> = B<vicepaa> = B<aa> = 26
- B</vicepab> = B<vicepab> = B<ab> = 27
+ /vicepaa = vicepaa = aa = 26
+ /vicepab = vicepab = ab = 27
and so on through
- B</vicepiv> = B<vicepiv> = B<iv> = 255
+ /vicepiv = vicepiv = iv = 255
-=item -volume
+=item B<-volume> <I<salvage volume id or name>>
Specifies the name or volume ID number of a read/write volume to
-salvage. The B<-partition> argument must be provided along with
-this one.
+salvage. The B<-partition> argument must be provided along with this one.
-=item -file
+=item B<-file> <I<salvage log output file>>
Specifies the complete pathname of a file into which to write a trace of
-the salvage operation, in addition to the B</usr/afs/logs/SalvageLog>
-file on the server machine. If the file pathname is local, the trace is
-written to the specified file on the local disk of the machine where the
-B<bos salvage> command is issued. If the B<-volume>
-argument is included, the file can be in AFS, though not in the volume being
-salvaged. Do not combine this argument with the B<-showlog>
-flag.
+the salvage operation, in addition to the F</usr/afs/logs/SalvageLog> file
+on the server machine. If the file pathname is local, the trace is written
+to the specified file on the local disk of the machine where the B<bos
+salvage> command is issued. If the B<-volume> argument is included, the
+file can be in AFS, though not in the volume being salvaged. Do not
+combine this argument with the B<-showlog> flag.
-=item -all
+=item B<-all>
Salvages all volumes on all of the partitions on the machine named by the
B<-server> argument.
-=item -showlog
+=item B<-showlog>
Displays the trace of the salvage operation on the standard output stream,
-as well as writing it to the B</usr/afs/logs/SalvageLog> file.
-Do not combine this flag with the B<-file> argument.
+as well as writing it to the F</usr/afs/logs/SalvageLog> file. Do not
+combine this flag with the B<-file> argument.
-=item -parallel
+=item B<-parallel> <I<# of max parallel partition salvaging>>
Specifies the maximum number of Salvager subprocesses to run in
parallel. Provide one of three values:
=item *
-An integer from the range B<1> to 32. A value of
-B<1> means that a single Salvager process salvages the partitions
-sequentially.
-
+An integer from the range C<1> to C<32>. A value of C<1> means that a
+single Salvager process salvages the partitions sequentially.
=item *
-The string all to run up to four Salvager subprocesses in
-parallel on partitions formatted as logical volumes that span multiple
-physical disks. Use this value only with such logical volumes.
-
+The string C<all> to run up to four Salvager subprocesses in parallel on
+partitions formatted as logical volumes that span multiple physical
+disks. Use this value only with such logical volumes.
=item *
-The string all followed immediately (with no intervening space)
-by an integer from the range B<1> to B<32>, to run the
-specified number of Salvager subprocesses in parallel on partitions formatted
-as logical volumes. Use this value only with such logical
-volumes.
-
+The string all followed immediately (with no intervening space) by an
+integer from the range C<1> to C<32>, to run the specified number of
+Salvager subprocesses in parallel on partitions formatted as logical
+volumes. Use this value only with such logical volumes.
=back
The BOS Server never starts more Salvager subprocesses than there are
partitions, and always starts only one process to salvage a single
-volume. If this argument is omitted, up to four Salvager subprocesses
-run in parallel.
+volume. If this argument is omitted, up to four Salvager subprocesses run
+in parallel.
-=item -tmpdir
+=item B<-tmpdir> <I<directory to place tmp files>>
Specifies the full pathname of a local disk directory to which the
Salvager process writes temporary files as it runs. If this argument is
omitted, or specifies an ineligible or nonexistent directory, the Salvager
process writes the files to the partition it is currently salvaging.
-=item -orphans
+=item B<-orphans> (ignore | remove | attach)
-Controls how the Salvager handles orphaned files and directories.
-Choose one of the following three values:
+Controls how the Salvager handles orphaned files and directories. Choose
+one of the following three values:
=over 4
=item ignore
Leaves the orphaned objects on the disk, but prints a message to the
-B</usr/afs/logs/SalvageLog> file reporting how many orphans were found
-and the approximate number of kilobytes they are consuming. This is the
+F</usr/afs/logs/SalvageLog> file reporting how many orphans were found and
+the approximate number of kilobytes they are consuming. This is the
default if the B<-orphans> argument is omitted.
=item remove
Removes the orphaned objects, and prints a message to the
-B</usr/afs/logs/SalvageLog> file reporting how many orphans were
-removed and the approximate number of kilobytes they were consuming.
+F</usr/afs/logs/SalvageLog> file reporting how many orphans were removed
+and the approximate number of kilobytes they were consuming.
=item attach
Attaches the orphaned objects by creating a reference to them in the vnode
-of the volume's root directory. Since each object's actual
-name is now lost, the Salvager assigns each one a name of the following
-form:
+of the volume's root directory. Since each object's actual name is now
+lost, the Salvager assigns each one a name of the following form:
=over 4
+=item *
-_ _ORPHANFILE_ _.I<index> for files
+C<__ORPHANFILE__.I<index>> for files.
+=item *
-_ _ORPHANDIR_ _.I<index> for directories
+C<__ORPHANDIR__.I<index>> for directories.
=back
where I<index> is a two-digit number that uniquely identifies each
-object. The orphans are charged against the volume's quota and
-appear in the output of the B<ls> command issued against the
-volume's root directory.
+object. The orphans are charged against the volume's quota and appear in
+the output of the B<ls> command issued against the volume's root
+directory.
=back
-=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<bos> 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<bos(8)>.
-=item -noauth
->
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. Do not combine this flag with the B<-localauth>
-flag. For more details, see the introductory B<bos> reference
-page.
+Assigns the unprivileged identity C<anonymous> to the issuer. Do not
+combine this flag with the B<-localauth> flag. For more details, see
+L<bos(8)>.
-=item -localauth
->
+=item B<-localauth>
Constructs a server ticket using a key from the local
-B</usr/afs/etc/KeyFile> file. The B<bos> command
-interpreter presents the ticket to the BOS Server during mutual
-authentication. Do not combine this flag with the B<-cell> or
-B<-noauth> options. For more details, see the introductory
-B<bos> reference page.
+F</usr/afs/etc/KeyFile> file. The B<bos> command interpreter presents the
+ticket to the BOS Server during mutual authentication. Do not combine this
+flag with the B<-cell> or B<-noauth> options. For more details, see
+L<bos(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 salvages all volumes on the /vicepd
-partition of the machine B<db3.abc.com>:
+The following command salvages all volumes on the F</vicepd> partition of
+the machine C<db3.abc.com>:
% bos salvage -server db3.abc.com -partition /vicepd
The following command salvages the volume with volume ID number 536870988
-on partition B</vicepb> of the machine
-B<fs2.abc.com>:
+on partition F</vicepb> of the machine C<fs2.abc.com>:
% bos salvage -server fs2.abc.com -partition /vicepb -volume 536870988
The following command salvages all volumes on the machine
-B<fs4.abc.com>. Six Salvager processes run in
-parallel rather than the default four.
+C<fs4.abc.com>. Six Salvager processes run in parallel rather than the
+default four.
% bos salvage -server fs4.abc.com -all -parallel 6
=head1 PRIVILEGE REQUIRED
-The issuer must be listed in the /usr/afs/etc/UserList file on
-the machine named by the B<-server> argument, 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 the
+machine named by the B<-server> argument, 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<KeyFile(1)>,
-L<SalvageLog(1)>,
-L<UserList(1)>,
-L<bos(1)>,
-L<salvager(1)>,
+L<KeyFile(5)>,
+L<SalvageLog(5)>,
+L<UserList(5)>,
+L<bos(8)>,
+L<salvager(8)>,
L<vos_backup(1)>,
L<vos_release(1)>,
L<vos_remove(1)>,
=head1 SYNOPSIS
-bos setauth -server <I<machine name>>
-B<-authrequired> <I<on or off: authentication required for admin requests>>
- [B<-cell> <I<cell name>>] [B<-noauth>] [B<-localauth>] [-help]
+B<bos setauth> B<-server> <I<machine name>> B<-authrequired> (on | off)
+ [B<-cell> <I<cell name>>] [B<-noauth>] [B<-localauth>] [B<-help>]
-bos seta -s <I<machine name>>
-B<-a> <I<on or off: authentication required for admin requests>>
- [B<-c> <I<cell name>>] [B<-n>] [B<-l>] [-h]
+B<bos seta> B<-s> <I<machine name>> B<-a> (on | off)
+ [B<-c> <I<cell name>>] [B<-n>] [B<-l>] [B<-h>]
=head1 DESCRIPTION
-The bos setauth command enables or disables authorization
-checking on the server machine named by the B<-server>
-argument. When authorization checking is enabled (the normal case), the
-AFS server processes running on the machine verify that the issuer of a
-command meets its privilege requirements. When authorization checking
-is disabled, server processes perform any action for anyone, including the
-unprivileged user B<anonymous>; this security exposure precludes
-disabling of authorization checking except during installation or
-emergencies.
+The B<bos setauth> command enables or disables authorization checking on
+the server machine named by the B<-server> argument. When authorization
+checking is enabled (the normal case), the AFS server processes running on
+the machine verify that the issuer of a command meets its privilege
+requirements. When authorization checking is disabled, server processes
+perform any action for anyone, including the unprivileged user
+C<anonymous>; this security exposure precludes disabling of authorization
+checking except during installation or emergencies.
To indicate to the server processes that authorization checking is
disabled, the BOS Server creates the zero-length file
-B</usr/afs/local/NoAuth> on its local disk. All AFS server
-processes constantly monitor for the B<NoAuth> file's presence
-and do not check for authorization when it is present. The BOS Server
-removes the file when this command is used to reenable authorization
-checking.
+F</usr/afs/local/NoAuth> on its local disk. All AFS server processes
+constantly monitor for the F<NoAuth> file's presence and do not check for
+authorization when it is present. The BOS Server removes the file when
+this command is used to reenable authorization checking.
=head1 CAUTIONS
-Do not create the NoAuth file directly, except when directed by
-instructions for dealing with emergencies (doing so requires being logged in
-as the local superuser B<root>). Use this command
-instead.
+Do not create the F<NoAuth> file directly, except when directed by
+instructions for dealing with emergencies (doing so requires being logged
+in as the local superuser C<root>). Use this command instead.
=head1 OPTIONS
=over 4
-=item -server
->
+=item B<-server> <I<machine name>>
Indicates the server machine on which to enable or disable authorization
checking. Identify the machine by IP address or its host name (either
-fully-qualified or abbreviated unambiguously). For details, see the
-introductory reference page for the B<bos> command suite.
+fully-qualified or abbreviated unambiguously). For details, see L<bos(8)>.
-=item -authrequired
->
+=item B<-authrequired> (on | off)
-Enables authorization checking if the value is on, or disables
-it if the value is B<off>.
+Enables authorization checking if the value is C<on>, or disables it if
+the value is C<off>.
-=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<bos> 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<bos(8)>.
-=item -noauth
->
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. Do not combine this flag with the B<-localauth>
-flag. For more details, see the introductory B<bos> reference
-page.
+Assigns the unprivileged identity C<anonymous> to the issuer. Do not
+combine this flag with the B<-localauth> flag. For more details, see
+L<bos(8)>.
-=item -localauth
->
+=item B<-localauth>
Constructs a server ticket using a key from the local
-B</usr/afs/etc/KeyFile> file. The B<bos> command
-interpreter presents the ticket to the BOS Server during mutual
-authentication. Do not combine this flag with the B<-cell> or
-B<-noauth> options. For more details, see the introductory
-B<bos> reference page.
+F</usr/afs/etc/KeyFile> file. The B<bos> command interpreter presents the
+ticket to the BOS Server during mutual authentication. Do not combine this
+flag with the B<-cell> or B<-noauth> options. For more details, see
+L<bos(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 disables authorization checking on the machine
-B<fs7.abc.com>:
+C<fs7.abc.com>:
% bos setauth -server fs7.abc.com -authrequired off
=head1 PRIVILEGE REQUIRED
-The issuer must be listed in the /usr/afs/etc/UserList file on
-the machine named by the B<-server> argument, 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 the
+machine named by the B<-server> argument, 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<KeyFile(1)>,
-L<NoAuth(1)>,
-L<UserList(1)>,
-L<bos(1)>,
-L<bos_restart(1)>
+L<KeyFile(5)>,
+L<NoAuth(5)>,
+L<UserList(5)>,
+L<bos(8)>,
+L<bos_restart(8)>
=head1 COPYRIGHT
=head1 NAME
-bos setcellname - Sets the cell's name in the /usr/afs/etc/ThisCell and
-B</usr/afs/etc/CellServDB> files
+bos setcellname - Sets the cell's name in ThisCell and CellServDB
=head1 SYNOPSIS
-B<bos setcellname -server> <I<machine name>> -name <I<cell name>>
-[B<-cell> <I<cell name>>] [B<-noauth>] [B<-localauth>] [B<-help>]
+B<bos setcellname> B<-server> <I<machine name>> B<-name> <I<cell name>>
+ [B<-cell> <I<cell name>>] [B<-noauth>] [B<-localauth>] [B<-help>]
-B<bos setc -s> <I<machine name>> B<-n> <I<cell name>> [B<-c> <I<cell name>>] [B<-n>] [B<-l>] [-h]
+B<bos setc> B<-s> <I<machine name>> B<-n> <I<cell name>>
+ [B<-c> <I<cell name>>] [B<-n>] [B<-l>] [-h]
=head1 DESCRIPTION
-The bos setcellname command establishes the cell's name and
-makes the server machine named by the B<-server> argument a member of
-it, by recording the value of the B<-name> argument in two files which
-it creates on the local disk:
+The B<bos setcellname> command establishes the cell's name and makes the
+server machine named by the B<-server> argument a member of it, by
+recording the value of the B<-name> argument in two files which it creates
+on the local disk:
=over 4
=item *
-/usr/afs/etc/ThisCell
-
+F</usr/afs/etc/ThisCell>
=item *
-/usr/afs/etc/CellServDB. The cell name appears on the
-first line in the file, preceded by the required C<>> symbol.
-The machine name specified with the B<-server> argument appears on the
-second line along with its IP address as obtained from the cell's naming
-service. The machine is thus designated as the cell's first
-database server machine.
-
+F</usr/afs/etc/CellServDB>. The cell name appears on the first line in the
+file, preceded by the required C<< > >> symbol. The machine name
+specified with the B<-server> argument appears on the second line along
+with its IP address as obtained from the cell's naming service. The
+machine is thus designated as the cell's first database server machine.
=back
=head1 CAUTIONS
-Issue this command only when the installing the cell's first AFS
-server machine. The I<IBM AFS Quick Beginnings> explains how to
-copy over the B<ThisCell> and B<CellServDB> files from this or
-another appropriate machine during installation of additional server
-machines.
+Issue this command only when the installing the cell's first AFS server
+machine. The I<IBM AFS Quick Beginnings> explains how to copy over the
+F<ThisCell> and F<CellServDB> files from this or another appropriate
+machine during installation of additional server machines.
Be sure to choose a satisfactory cell name when issuing this command,
-because changing a cell's name is very complicated; for one thing,
-it requires changing every password in the Authentication Database.
-Consult the I<IBM AFS Administration Guide> for advice on choosing a
-cell name. If changing the cell's name is absolutely necessary,
-contact AFS Product Support for complete instructions.
+because changing a cell's name is very complicated; for one thing, it
+requires changing every password in the Authentication Database. Consult
+the I<IBM AFS Administration Guide> for advice on choosing a cell name.
=head1 OPTIONS
=over 4
-=item -server
->
+=item B<-server> <I<machine name>>
Indicates the server machine on which to set the cell name in the
-B<ThisCell> and B<CellServDB> file. It is always the
-first machine installed in a cell. Identify the machine by IP address
-or its host name (either fully-qualified or abbreviated unambiguously).
-For details, see the introductory reference page for the B<bos>
-command suite.
+F<ThisCell> and F<CellServDB> file. It is always the first machine
+installed in a cell. Identify the machine by IP address or its host name
+(either fully-qualified or abbreviated unambiguously). For details, see
+L<bos(8)>.
-=item -name
->
+=item B<-name> <I<cell name>>
Defines the cell name, using standard Internet domain name format (the
-actual domain name is usually appropriate). Examples are
-B<abc.com> for the ABC Corporation and
-B<stateu.edu> for the State University. It must match
-the value of the B<-cell> argument, if that is provided.
+actual domain name is usually appropriate). Examples are C<abc.com> for
+the ABC Corporation and C<stateu.edu> for the State University. It must
+match the value of the B<-cell> argument, if that is provided.
-=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<bos> 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<bos(8)>.
-=item -noauth
->
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. Do not combine this flag with the B<-localauth>
-flag. For more details, see the introductory B<bos> reference
-page.
+Assigns the unprivileged identity C<anonymous> to the issuer. Do not
+combine this flag with the B<-localauth> flag. For more details, see
+L<bos(8)>.
-=item -localauth
->
+=item B<-localauth>
Constructs a server ticket using a key from the local
-B</usr/afs/etc/KeyFile> file. The B<bos> command
-interpreter presents the ticket to the BOS Server during mutual
-authentication. Do not combine this flag with the B<-cell> or
-B<-noauth> options. For more details, see the introductory
-B<bos> reference page.
+F</usr/afs/etc/KeyFile> file. The B<bos> command interpreter presents the
+ticket to the BOS Server during mutual authentication. Do not combine this
+flag with the B<-cell> or B<-noauth> options. For more details, see
+L<bos(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 the cell name abc.com in
-the B<ThisCell> and B<CellServDB> files on the machine
-B<fs1.abc.com> as it is installed as the cell's
-first server machine.
+The following command defines the cell name C<abc.com> in the F<ThisCell>
+and F<CellServDB> files on the machine C<fs1.abc.com> as it is installed
+as the cell's first server machine.
% bos setcellname -server fs1.abc.com -name abc.com
=head1 PRIVILEGE REQUIRED
-Authorization checking is normally turned off during installation, which is
-the only recommended time to use this command; in this case no privilege
-is required. If authorization checking is turned on, the issuer must be
-listed in the B</usr/afs/etc/UserList> file on the machine named by
-the B<-server> argument, or must be logged in as the local superuser
-B<root> if the B<-localauth> flag is included.
+Authorization checking is normally turned off during installation, which
+is the only recommended time to use this command; in this case no
+privilege is required. If authorization checking is turned on, the issuer
+must be listed in the F</usr/afs/etc/UserList> file on the machine named
+by the B<-server> argument, or must be logged in as the local superuser
+C<root> if the B<-localauth> flag is included.
=head1 SEE ALSO
-L<CellServDB (server version)(1)>
-
-L<KeyFile(1)>,
-L<ThisCell (server version)(1)>
-
-L<UserList(1)>,
-L<bos(1)>
+L<CellServDB(5)>,
+L<KeyFile(5)>,
+L<ThisCell(5)>,
+L<UserList(5)>,
+L<bos(8)>
I<IBM AFS Quick Beginnings>
=head1 NAME
-bos setrestart - Sets the date and time at which the BOS Server restarts processes
+bos setrestart - Sets when the BOS Server restarts processes
=head1 SYNOPSIS
-B<bos setrestart -server> <I<machine name>> -time <I<time to restart server>>
-[B<-general>] [B<-newbinary>] [B<-cell> <I<cell name>>]
- [B<-noauth>] [B<-localauth>] [-help]
+B<bos setrestart> B<-server> <I<machine name>>
+ B<-time> <I<time to restart server>> [B<-general>] [B<-newbinary>]
+ [B<-cell> <I<cell name>>] [B<-noauth>] [B<-localauth>] [B<-help>]
-B<bos setr -s> <I<machine name>> B<-t> <I<time to restart server>> [B<-g>] [-ne]
-[B<-c> <I<cell name>>] [B<-no>] [B<-l>] [B<-h>]
+B<bos setr> B<-s> <I<machine name>> B<-t> <I<time to restart server>>
+ [B<-g>] [B<-ne>] [B<-c> <I<cell name>>] [B<-no>] [B<-l>] [B<-h>]
=head1 DESCRIPTION
-The bos setrestart command records in the
-B</usr/afs/local/BosConfig> file the times at which the BOS Server
-running on the server machine named by the B<-server> argument
-performs two types of restarts:
+The B<bos setrestart> command records in the F</usr/afs/local/BosConfig>
+file the times at which the BOS Server running on the server machine named
+by the B<-server> argument performs two types of restarts:
=over 4
=item *
-A I<general restart>. By default, once per week the BOS
-Server restarts itself and then any AFS process marked with the C<Run>
-status flag in the B<BosConfig> file (equivalent in effect to issuing
-the B<bos restart> command with the B<-bosserver>
-flag). The default setting is 4:00 a.m. each Sunday
-morning.
-
+A I<general restart>. By default, once per week the BOS Server restarts
+itself and then any AFS process marked with the C<Run> status flag in the
+F<BosConfig> file (equivalent in effect to issuing the B<bos restart>
+command with the B<-bosserver> flag). The default setting is 4:00
+a.m. each Sunday morning.
=item *
-A I<binary restart>. By default, once per day the BOS
-Server restarts any currently running process for which the timestamp on the
-binary file in the B</usr/afs/bin> directory is later than the time
-the process last started or restarted. The default is 5:00
-a.m. each day.
-
+A I<binary restart>. By default, once per day the BOS Server restarts any
+currently running process for which the timestamp on the binary file in
+the F</usr/afs/bin> directory is later than the time the process last
+started or restarted. The default is 5:00 a.m. each day.
=back
=head1 CAUTIONS
-Restarting a process makes it unavailable for a period of time. The
-B<fs> process has potentially the longest outage, depending on how
-many volumes the file server machine houses (the File Server and Volume Server
-reattach each volume when they restart). The default settings are
-designed to coincide with periods of low usage, so that the restarts disturb
-the smallest possible number of users.
+Restarting a process makes it unavailable for a period of time. The B<fs>
+process has potentially the longest outage, depending on how many volumes
+the file server machine houses (the File Server and Volume Server reattach
+each volume when they restart). The default settings are designed to
+coincide with periods of low usage, so that the restarts disturb the
+smallest possible number of users.
-If the setting specified with the -time argument is within one
-hour of the current time, the BOS Server does not restart any processes until
-the next applicable opportunity (the next day for binary restarts, or the next
+If the setting specified with the B<-time> argument is within one hour of
+the current time, the BOS Server does not restart any processes until the
+next applicable opportunity (the next day for binary restarts, or the next
week for general restarts).
-The command changes only one type of restart setting at a time; issue
-the command twice to change both settings.
+The command changes only one type of restart setting at a time; issue the
+command twice to change both settings.
=head1 OPTIONS
=over 4
-=item -server
+=item B<-server> <I<machine name>>
-Indicates the server machine on which to set a new restart time.
-Identify the machine by IP address or its host name (either fully-qualified or
-abbreviated unambiguously). For details, see the introductory reference
-page for the B<bos> command suite.
+Indicates the server machine on which to set a new restart time. Identify
+the machine by IP address or its host name (either fully-qualified or
+abbreviated unambiguously). For details, see L<bos(8)>.
-=item -time
+=item B<-time> <I<time to restart server>>
-Specifies the restart time. By convention the general restart is
-defined as weekly (specifies both a day and a time), and the binary restart is
+Specifies the restart time. By convention the general restart is defined
+as weekly (specifies both a day and a time), and the binary restart is
defined as daily (specifies only a time). However, it is acceptable to
define a daily general restart or weekly binary restart.
=item *
-The string never, which directs the BOS Server never to perform
-the indicated type of restart.
-
+The string C<never>, which directs the BOS Server never to perform the
+indicated type of restart.
=item *
-The string now, which directs the BOS Server to perform the
-restart immediately and never again.
-
+The string C<now>, which directs the BOS Server to perform the restart
+immediately and never again.
=item *
A time of day (the conventional type of value for the binary restart
-time). Separate the hours and minutes with a colon
-(I<hh>:I<MM>), and use either 24-hour format, or a value
-in the range from B<1:00> through B<12:59> with
-the addition of B<am> or B<pm>. For example, both
-B<14:30> and B<"2:30 pm"> indicate 2:30 in
-the afternoon. Surround this parameter with double quotes (B<"
-">) if it contains a space.
-
+time). Separate the hours and minutes with a colon (I<hh:MM>), an use
+either 24-hour format, or a value in the range from C<1:00> through
+C<12:59> with the addition of C<am> or C<pm>. For example, both C<14:30>
+and C<"2:30 pm"> indicate 2:30 in the afternoon. Surround this parameter
+with double quotes (C<"">) if it contains a space.
=item *
A day of the week and time of day, separated by a space and surrounded
-with double quotes (B<" ">). This is the conventional type of
-value for the general restart. For the day, provide either the whole
-name or the first three letters, all in lowercase letters (B<sunday>
-or B<sun>, B<thursday> or B<thu>, and so on).
-For the time, use the same format as when specifying the time alone.
-
+with double quotes (C<"">). This is the conventional type of value for the
+general restart. For the day, provide either the whole name or the first
+three letters, all in lowercase letters (C<sunday> or C<sun>, C<thursday>
+or C<thu>, and so on). For the time, use the same format as when
+specifying the time alone.
=back
If desired, precede a time or day and time definition with the string
-B<every> or B<at>. These words do not change the
-meaning, but possibly make the output of the B<bos getrestart> command
-easier to understand.
+C<every> or C<at>. These words do not change the meaning, but possibly
+make the output of the B<bos getrestart> command easier to understand.
-=item -general
->
+=item B<-general>
Sets the general restart time.
-=item -newbinary
->
+=item B<-newbinary>
Sets the binary restart time.
-=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<bos> 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<bos(8)>.
-=item -noauth
->
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. Do not combine this flag with the B<-localauth>
-flag. For more details, see the introductory B<bos> reference
-page.
+Assigns the unprivileged identity C<anonymous> to the issuer. Do not
+combine this flag with the B<-localauth> flag. For more details, see
+L<bos(8)>.
-=item -localauth
->
+=item B<-localauth>
Constructs a server ticket using a key from the local
-B</usr/afs/etc/KeyFile> file. The B<bos> command
-interpreter presents the ticket to the BOS Server during mutual
-authentication. Do not combine this flag with the B<-cell> or
-B<-noauth> options. For more details, see the introductory
-B<bos> reference page.
+F</usr/afs/etc/KeyFile> file. The B<bos> command interpreter presents the
+ticket to the BOS Server during mutual authentication. Do not combine this
+flag with the B<-cell> or B<-noauth> options. For more details, see
+L<bos(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 sets the general restart time on the machine
-B<fs4.abc.com> to Saturday at 3:30 am.
+C<fs4.abc.com> to Saturday at 3:30 am.
% bos setrestart -server fs4.abc.com -time "sat 3:30" -general
The following command sets the binary restart time on the machine
-B<fs6.abc.com> to 11:45 pm.
+C<fs6.abc.com> to 11:45 pm.
% bos setrestart -server fs6.abc.com -time 23:45 -newbinary
=head1 PRIVILEGE REQUIRED
-The issuer must be listed in the /usr/afs/etc/UserList file on
-the machine named by the B<-server> argument, 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 the
+machine named by the B<-server> argument, 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<BosConfig(1)>,
-L<KeyFile(1)>,
-L<UserList(1)>,
-L<bos(1)>,
-L<bos_getrestart(1)>,
-L<bos_restart(1)>
+L<BosConfig(5)>,
+L<KeyFile(5)>,
+L<UserList(5)>,
+L<bos(8)>,
+L<bos_getrestart(8)>,
+L<bos_restart(8)>
=head1 COPYRIGHT
=head1 NAME
-bos shutdown - Stops a process without changing its status flag in the
-B</usr/afs/local/BosConfig> file
+bos shutdown - Stops a process without changing its status flag
=head1 SYNOPSIS
-B<bos shutdown -server> <I<machine name>> [B<-instance> <I<instances>>+] [-wait]
-[B<-cell> <I<cell name>>] [B<-noauth>] [B<-localauth>] [B<-help>]
+B<bos shutdown> B<-server> <I<machine name>>
+ [B<-instance> <I<instances>>+] [B<-wait>] [B<-cell> <I<cell name>>]
+ [B<-noauth>] [B<-localauth>] [B<-help>]
-B<bos sh -s> <I<machine name>> [B<-i> <I<instances>>+] [-w]
-[B<-c> <I<cell name>>] [B<-n>] [B<-l>] [B<-h>]
+B<bos sh> B<-s> <I<machine name>> [B<-i> <I<instances>>+] [B<-w>]
+ [B<-c> <I<cell name>>] [B<-n>] [B<-l>] [B<-h>]
=head1 DESCRIPTION
-The bos shutdown command stops, on the server machine named by
-the B<-server> argument, either
+The B<bos shutdown> command stops, on the server machine named by the
+B<-server> argument, either
=over 4
=item *
-All of the currently running AFS server processes, except the BOS Server
-
+All of the currently running AFS server processes, except the BOS Server.
=item *
-Only the processes specified by the -instance argument
-
+Only the processes specified by the B<-instance> argument.
=back
This command does not change a process's status flag in the
-B</usr/afs/local/BosConfig> file, but only in the BOS Server's
-memory. To stop a process and change its B<BosConfig> status
-flag, use the B<bos stop> command instead.
+F</usr/afs/local/BosConfig> file, but only in the BOS Server's memory. To
+stop a process and change its F<BosConfig> status flag, use the B<bos
+stop> command instead.
Once stopped with this command, a process does not run again until an
-administrator starts it by using the B<bos start>, B<bos
-startup>, or B<bos restart> command, or until the BOS Server
-restarts (assuming that the process's B<BosConfig> status flag is
-C<Run>).
+administrator starts it by using the B<bos start>, B<bos startup>, or
+B<bos restart> command, or until the BOS Server restarts (assuming that
+the process's F<BosConfig> status flag is C<Run>).
=head1 OPTIONS
=over 4
-=item -server
->
+=item B<-server> <I<machine name>>
-Indicates the server machine on which to stop processes. Identify
-the machine by IP address or its host name (either fully-qualified or
-abbreviated unambiguously). For details, see the introductory reference
-page for the B<bos> command suite.
+Indicates the server machine on which to stop processes. Identify the
+machine by IP address or its host name (either fully-qualified or
+abbreviated unambiguously). For details, see L<bos(8)>.
-=item -instance
->
+=item B<-instance> <I<instances>>+
Names each process to stop. Use the process name assigned with the
-B<-instance> argument to the B<bos create> command. The
-output from the B<bos status> command lists the names. Omit
-this argument to stop all processes other than the BOS Server.
+B<-instance> argument to the B<bos create> command. The output from the
+B<bos status> command lists the names. Omit this argument to stop all
+processes other than the BOS Server.
-=item -wait
->
+=item B<-wait>
Delays the return of the command shell prompt until all processes actually
-stop. If this argument is omitted, the prompt returns almost
-immediately even if all processes are not stopped.
+stop. If this argument is omitted, the prompt returns almost immediately
+even if all processes are not stopped.
-=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<bos> 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<bos(8)>.
-=item -noauth
->
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. Do not combine this flag with the B<-localauth>
-flag. For more details, see the introductory B<bos> reference
-page.
+Assigns the unprivileged identity C<anonymous> to the issuer. Do not
+combine this flag with the B<-localauth> flag. For more details, see
+L<bos(8)>.
-=item -localauth
->
+=item B<-localauth>
Constructs a server ticket using a key from the local
-B</usr/afs/etc/KeyFile> file. The B<bos> command
-interpreter presents the ticket to the BOS Server during mutual
-authentication. Do not combine this flag with the B<-cell> or
-B<-noauth> options. For more details, see the introductory
-B<bos> reference page.
+F</usr/afs/etc/KeyFile> file. The B<bos> command interpreter presents the
+ticket to the BOS Server during mutual authentication. Do not combine this
+flag with the B<-cell> or B<-noauth> options. For more details, see
+L<bos(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 stops all processes other than the BOS Server on the
-machine B<fs3.abc.com>.
+machine C<fs3.abc.com>.
% bos shutdown fs3.abc.com
-The following command stops the upserver process (server portion
-of the Update Server) on the machine
-B<fs5.abc.com>.
+The following command stops the C<upserver> process (server portion of the
+Update Server) on the machine C<fs5.abc.com>.
% bos shutdown -server fs5.abc.com -instance upserver
=head1 PRIVILEGE REQUIRED
-The issuer must be listed in the /usr/afs/etc/UserList file on
-the machine named by the B<-server> argument, 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 the
+machine named by the B<-server> argument, 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<BosConfig(1)>,
-L<KeyFile(1)>,
-L<UserList(1)>,
-L<bos(1)>,
-L<bos_create(1)>,
-L<bos_restart(1)>,
-L<bos_start(1)>,
-L<bos_startup(1)>,
-L<bos_status(1)>
+L<BosConfig(5)>,
+L<KeyFile(5)>,
+L<UserList(5)>,
+L<bos(8)>,
+L<bos_create(8)>,
+L<bos_restart(8)>,
+L<bos_start(8)>,
+L<bos_startup(8)>,
+L<bos_status(8)>
=head1 COPYRIGHT
=head1 NAME
-bos start - Starts a process after setting its status flag in the
-B</usr/afs/local/BosConfig> file
+bos start - Starts a process after setting its status flag
=head1 SYNOPSIS
-B<bos start -server> <I<machine name>> -instance <I<server process name>>+
-[B<-cell> <I<cell name>>] [B<-noauth>] [B<-localauth>] [B<-help>]
+B<bos start> B<-server> <I<machine name>>
+ B<-instance> <I<server process name>>+ [B<-cell> <I<cell name>>]
+ [B<-noauth>] [B<-localauth>] [B<-help>]
-B<bos start -s> <I<machine name>> -i <I<server process name>>+
-[B<-c> <I<cell name>>] [B<-n>] [B<-l>] [B<-h>]
+B<bos start> B<-s> <I<machine name>> B<-i> <I<server process name>>+
+ [B<-c> <I<cell name>>] [B<-n>] [B<-l>] [B<-h>]
=head1 DESCRIPTION
-The bos start command sets the status flag for each process
-specified by the B<-instance> argument to C<Run> in the
-B</usr/afs/local/BosConfig> file and in the BOS Server's memory
-on the server machine named by the B<-server> argument, then starts
-it. If the process is already running, the command's only effect
-is to guarantee that the status flag is C<Run>; it does not
-restart the process.
+The B<bos start> command sets the status flag for each process specified
+by the B<-instance> argument to C<Run> in the F</usr/afs/local/BosConfig>
+file and in the BOS Server's memory on the server machine named by the
+B<-server> argument, then starts it. If the process is already running,
+the command's only effect is to guarantee that the status flag is C<Run>;
+it does not restart the process.
-To start a process without changing its status flag in the
-B<BosConfig> file, use the B<bos startup> command
-instead.
+To start a process without changing its status flag in the F<BosConfig>
+file, use the B<bos startup> command instead.
=head1 OPTIONS
=over 4
-=item -server
->
+=item B<-server> <I<machine name>>
-Indicates the server machine on which to start processes. Identify
-the machine by IP address or its host name (either fully-qualified or
-abbreviated unambiguously). For details, see the introductory reference
-page for the B<bos> command suite.
+Indicates the server machine on which to start processes. Identify the
+machine by IP address or its host name (either fully-qualified or
+abbreviated unambiguously). For details, see L<bos(8)>.
-=item -instance
->
+=item B<-instance> <I<server process name>>+
Names each process to start. Use the process name assigned with the
-B<-instance> argument to the B<bos create> command. The
-output from the B<bos status> command lists the names.
+B<-instance> argument to the B<bos create> command. The output from the
+B<bos status> command lists the names.
-=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<bos> 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<bos(8)>.
-=item -noauth
->
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. Do not combine this flag with the B<-localauth>
-flag. For more details, see the introductory B<bos> reference
-page.
+Assigns the unprivileged identity C<anonymous> to the issuer. Do not
+combine this flag with the B<-localauth> flag. For more details, see
+L<bos(8)>.
-=item -localauth
->
+=item B<-localauth>
Constructs a server ticket using a key from the local
-B</usr/afs/etc/KeyFile> file. The B<bos> command
-interpreter presents the ticket to the BOS Server during mutual
-authentication. Do not combine this flag with the B<-cell> or
-B<-noauth> options. For more details, see the introductory
-B<bos> reference page.
+F</usr/afs/etc/KeyFile> file. The B<bos> command interpreter presents the
+ticket to the BOS Server during mutual authentication. Do not combine this
+flag with the B<-cell> or B<-noauth> options. For more details, see
+L<bos(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 changes the status flag for the
-B<upclientbin> and B<upclientetc> processes to C<Run>
-in the B<BosConfig> file on the machine
-B<fs6.abc.com> and starts them running.
+The following command changes the status flag for the C<upclientbin> and
+C<upclientetc> processes to C<Run> in the F<BosConfig> file on the machine
+C<fs6.abc.com> and starts them running.
% bos start -server fs6.abc.com -instance upclientbin upclientetc
=head1 PRIVILEGE REQUIRED
-The issuer must be listed in the /usr/afs/etc/UserList file on
-the machine named by the B<-server> argument, 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 the
+machine named by the B<-server> argument, 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<BosConfig(1)>,
-L<KeyFile(1)>,
-L<UserList(1)>,
-L<bos(1)>,
-L<bos_create(1)>,
-L<bos_startup(1)>,
-L<bos_status(1)>
+L<BosConfig(5)>,
+L<KeyFile(5)>,
+L<UserList(5)>,
+L<bos(8)>,
+L<bos_create(8)>,
+L<bos_startup(8)>,
+L<bos_status(8)>
=head1 COPYRIGHT
=head1 NAME
-bos startup - Starts a process without changing its status flag in the
-B</usr/afs/local/BosConfig> file
+bos startup - Starts a process without changing its status flag
=head1 SYNOPSIS
-B<bos startup -server> <I<machine name>> [-instance <I<instances>>+]
-[B<-cell> <I<cell name>>] [B<-noauth>] [B<-localauth>] [B<-help>]
+B<bos startup> B<-server> <I<machine name>> [B<-instance> <I<instances>>+]
+ [B<-cell> <I<cell name>>] [B<-noauth>] [B<-localauth>] [B<-help>]
-B<bos startu -s> <I<machine name>> [-i <I<instances>>+]
-[B<-c> <I<cell name>>] [B<-n>] [B<-l>] [B<-h>]
+B<bos startu> B<-s> <I<machine name>> [B<-i> <I<instances>>+]
+ [B<-c> <I<cell name>>] [B<-n>] [B<-l>] [B<-h>]
=head1 DESCRIPTION
-The bos startup command starts, on the server machine named by
-the B<-server> argument, either
+The B<bos startup> command starts, on the server machine named by the
+B<-server> argument, either:
=over 4
=item *
-All AFS server processes not currently running but marked with the
-C<Run> status flag in the B</usr/afs/local/BosConfig> file
-
+All AFS server processes not currently running but marked with the C<Run>
+status flag in the F</usr/afs/local/BosConfig> file.
=item *
-Each process specified by -instance argument, even if its
-status flag in the B<BosConfig> file is C<NotRun>.
-
+Each process specified by B<-instance> argument, even if its status flag
+in the B<BosConfig> file is C<NotRun>.
=back
-To start a process and set its BosConfig status flag to
-C<Run>, use the B<bos start> command instead.
+To start a process and set its F<BosConfig> status flag to C<Run>, use the
+B<bos start> command instead.
=head1 OPTIONS
=over 4
-=item -server
->
+=item B<-server> <I<machine name>>
-Indicates the server machine on which to start processes. Identify
-the machine by IP address or its host name (either fully-qualified or
-abbreviated unambiguously). For details, see the introductory reference
-page for the B<bos> command suite.
+Indicates the server machine on which to start processes. Identify the
+machine by IP address or its host name (either fully-qualified or
+abbreviated unambiguously). For details, see L<bos(8)>.
-=item -instance
->
+=item B<-instance> <I<instances>>+
Names each process to start. Use the process name assigned with the
-B<-instance> argument to the B<bos create> command. The
-output from the B<bos status> command lists the names.
+B<-instance> argument to the B<bos create> command. The output from the
+B<bos status> command lists the names.
-=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<bos> 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<bos(8)>.
-=item -noauth
->
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. Do not combine this flag with the B<-localauth>
-flag. For more details, see the introductory B<bos> reference
-page.
+Assigns the unprivileged identity C<anonymous> to the issuer. Do not
+combine this flag with the B<-localauth> flag. For more details, see
+L<bos(8)>.
-=item -localauth
->
+=item B<-localauth>
Constructs a server ticket using a key from the local
-B</usr/afs/etc/KeyFile> file. The B<bos> command
-interpreter presents the ticket to the BOS Server during mutual
-authentication. Do not combine this flag with the B<-cell> or
-B<-noauth> options. For more details, see the introductory
-B<bos> reference page.
+F</usr/afs/etc/KeyFile> file. The B<bos> command interpreter presents the
+ticket to the BOS Server during mutual authentication. Do not combine this
+flag with the B<-cell> or B<-noauth> options. For more details, see
+L<bos(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 starts all processes marked with status flag
-C<Run> in the B<BosConfig> file on the machine
-B<fs3.abc.com> that are not currently running.
+The following command starts all processes marked with status flag C<Run>
+in the F<BosConfig> file on the machine C<fs3.abc.com> that are not
+currently running.
% bos startup fs3.abc.com
-The following command starts the B<buserver>, kaserver,
-B<ptserver>, and B<vlserver> processes running on the machine
-B<db2.abc.com>, even if their status flags in the
-B<BosConfig> file are C<NotRun>.
+The following command starts the B<buserver>, B<kaserver>, B<ptserver>,
+and B<vlserver> processes running on the machine C<db2.abc.com>, even if
+their status flags in the F<BosConfig> file are C<NotRun>.
- % bos startup -server db2.abc.com -instance buserver kaserver ptserver vlserver
+ % bos startup -server db2.abc.com \
+ -instance buserver kaserver ptserver vlserver
=head1 PRIVILEGE REQUIRED
-The issuer must be listed in the /usr/afs/etc/UserList file on
-the machine named by the B<-server> argument, 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 the
+machine named by the B<-server> argument, 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<BosConfig(1)>,
-L<KeyFile(1)>,
-L<UserList(1)>,
-L<bos(1)>,
-L<bos_create(1)>,
-L<bos_start(1)>,
-L<bos_status(1)>
+L<BosConfig(5)>,
+L<KeyFile(5)>,
+L<UserList(5)>,
+L<bos(8)>,
+L<bos_create(8)>,
+L<bos_start(8)>,
+L<bos_status(8)>
=head1 COPYRIGHT
=item *
All of the AFS server processes listed in the
-B</usr/afs/local/BosConfig> file
-
+F</usr/afs/local/BosConfig> file
=item *
Only these processes named by the -instance argument
-
=back
=head1 OPTIONS
=over 4
-=item -server
->
+=item B<-server> <I<machine name>>
Indicates the server machine for which to report server process
status. Identify the machine by IP address or its host name (either
-fully-qualified or abbreviated unambiguously). For details, see the
-introductory reference page for the B<bos> command suite.
+fully-qualified or abbreviated unambiguously). For details, see L<bos(8)>.
=item -instance
->
Names each process for which to report status. Use the process name
assigned with the B<-instance> argument to the B<bos>
names.
=item -long
->
Produces more detailed status information.
-=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<bos> reference page.
+argument with the B<-localauth> flag. For more details, see L<bos(8)>.
-=item -noauth
->
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
+Assigns the unprivileged identity C<anonymous> to the
issuer. Do not combine this flag with the B<-localauth>
-flag. For more details, see the introductory B<bos> reference
-page.
+flag. For more details, see L<bos(8)>.
-=item -localauth
->
+=item B<-localauth>
Constructs a server ticket using a key from the local
-B</usr/afs/etc/KeyFile> file. The B<bos> command
+F</usr/afs/etc/KeyFile> file. The B<bos> command
interpreter presents the ticket to the BOS Server during mutual
authentication. Do not combine this flag with the B<-cell> or
-B<-noauth> options. For more details, see the introductory
-B<bos> reference page.
+B<-noauth> options. For more details, see L<bos(8)>.
-=item -help
+=item B<-help>
Prints the online help for this command. All other valid options
are ignored.
scheduled to run, not necessarily that it was executing when the B<bos
status> command was issued.
-
=item *
C<disabled>. The process is not running, and its
B<BosConfig> status flag is C<NotRun>.
-
=item *
C<temporarily disabled>. The process is not running
C<Run>. Either an administrator used the B<bos
shutdown> command to stop it, or the
-
=item *
BOS Server stopped trying to restart it after numerous failed
attempts. In the second case, the auxiliary message is C<stopped for
too many errors>.
-
=item *
C<temporarily enabled>. The process is running although its
status flag in the B<BosConfig> file is C<NotRun>. An
administrator has used the B<bos startup> command to start it.
-
=back
If one of the following special circumstances applies to the process, the
=item *
C<has core file>. The process failed and created a core
-file in the B</usr/afs/logs> directory. If the BOS Server was
+file in the F</usr/afs/logs> directory. If the BOS Server was
able to restart the process after the failure, the primary status is
C<currently running normally>.
-
=item *
C<stopped for too many errors>. The reason for the primary
status C<temporarily disabled> is that the BOS Server's attempts
to restart the process all failed.
-
=back
The entry for the fs process always includes a second line to
C<file server running>. The File Server and Volume Server
components of the File Server process are running normally.
-
=item *
C<salvaging file system>. The Salvager is running, so the
File Server and Volume Server are temporarily disabled. The BOS Server
restarts them as soon as the Salvager is finished.
-
=back
The entry for a cron process includes an C<Auxiliary
The process's type (C<simple>, C<fs>, or
C<cron>).
-
=item *
The day and time the process last started or restarted.
-
=item *
The number of C<proc starts>, which is how many times the BOS
Server has started or restarted the process since it started itself.
-
=item *
The C<Last exit> time when the process (or one of the component
not appear if the process has not terminated since the BOS Server
started.
-
=item *
The C<Last error exit> time when the process (or one of the
sometimes appears. This line does not appear if the process has not
failed since the BOS Server started.
-
=item *
Each command that the BOS Server invokes to start the process, as
specified by the B<-cmd> argument to the B<bos create>
command.
-
=item *
The pathname of the notifier program that the BOS Server invokes when the
process terminates (if any), as specified by the B<-notifier> argument
to the B<bos create> command.
-
=back
If the -long flag is provided and the BOS Server discovers that
-the mode bits on files and subdirectories in the local B</usr/afs>
+the mode bits on files and subdirectories in the local F</usr/afs>
directory differ from the expected values, it prints the following warning
message:
L<BosConfig(1)>,
L<KeyFile(1)>,
-L<bos(1)>,
-L<bos_create(1)>,
-L<bos_shutdown(1)>,
-L<bos_startup(1)>,
-L<bos_status(1)>
+L<bos(8)>,
+L<bos_create(8)>,
+L<bos_shutdown(8)>,
+L<bos_startup(8)>,
+L<bos_status(8)>
=head1 COPYRIGHT
=head1 NAME
-bos stop - Stops a process after changing its status flag in the
-B</usr/afs/local/BosConfig> file
+bos stop - Stops a process after changing its status flag
=head1 SYNOPSIS
-B<bos stop -server> <I<machine name>> -instance <I<server process name>>+
-[B<-wait>] [B<-cell> <I<cell name>>] [B<-noauth>] [B<-localauth>] [B<-help>]
+B<bos stop> B<-server> <I<machine name>>
+ B<-instance> <I<server process name>>+ [B<-wait>]
+ [B<-cell> <I<cell name>>] [B<-noauth>] [B<-localauth>] [B<-help>]
-B<bos sto -s> <I<machine name>> -i <I<server process name>>+
-[B<-w>] [B<-c> <I<cell name>>] [B<-n>] [B<-l>] [B<-h>]
+B<bos sto> B<-s> <I<machine name>> B<-i> <I<server process name>>+
+ [B<-w>] [B<-c> <I<cell name>>] [B<-n>] [B<-l>] [B<-h>]
=head1 DESCRIPTION
-The bos stop command sets the status flag for each process
-specified with the B<-instance> argument to C<NotRun> in the
-B</usr/afs/local/BosConfig> file on the server machine named by the
+The B<bos stop> command sets the status flag for each process specified
+with the B<-instance> argument to C<NotRun> in the
+F</usr/afs/local/BosConfig> file on the server machine named by the
B<-server> argument, then stops it.
-To stop a process without changing its BosConfig status flag,
-use the B<bos shutdown> command instead.
+To stop a process without changing its F<BosConfig> status flag, use the
+B<bos shutdown> command instead.
=head1 OPTIONS
=over 4
-=item -server
->
+=item B<-server> <I<machine name>>
-Indicates the server machine on which to stop processes. Identify
-the machine by IP address or its host name (either fully-qualified or
-abbreviated unambiguously). For details, see the introductory reference
-page for the B<bos> command suite.
+Indicates the server machine on which to stop processes. Identify the
+machine by IP address or its host name (either fully-qualified or
+abbreviated unambiguously). For details, see L<bos(8)>.
-=item -instance
->
+=item B<-instance> <I<server process name>>+
Names each process to stop. Use the process name assigned with the
-B<-instance> argument to the B<bos create> command. The
-output from the B<bos status> command lists the names.
+B<-instance> argument to the B<bos create> command. The output from the
+B<bos status> command lists the names.
-=item -wait
->
+=item B<-wait>
Delays the return of the command shell prompt until all processes actually
-stop. If this argument is omitted, the prompt returns almost
-immediately even if all processes are not stopped.
+stop. If this argument is omitted, the prompt returns almost immediately
+even if all processes are not stopped.
-=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<bos> 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<bos(8)>.
-=item -noauth
->
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. Do not combine this flag with the B<-localauth>
-flag. For more details, see the introductory B<bos> reference
-page.
+Assigns the unprivileged identity C<anonymous> to the issuer. Do not
+combine this flag with the B<-localauth> flag. For more details, see
+L<bos(8)>.
-=item -localauth
->
+=item B<-localauth>
Constructs a server ticket using a key from the local
-B</usr/afs/etc/KeyFile> file. The B<bos> command
-interpreter presents the ticket to the BOS Server during mutual
-authentication. Do not combine this flag with the B<-cell> or
-B<-noauth> options. For more details, see the introductory
-B<bos> reference page.
+F</usr/afs/etc/KeyFile> file. The B<bos> command interpreter presents the
+ticket to the BOS Server during mutual authentication. Do not combine this
+flag with the B<-cell> or B<-noauth> options. For more details, see
+L<bos(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 command stops the upserver and
-B<runntp> on the machine B<fs7.abc.com>.
+The following example command stops the B<upserver> and B<runntp>
+processes on the machine C<fs7.abc.com>.
% bos stop -server fs7.abc.com -instance upserver runntp
=head1 PRIVILEGE REQUIRED
-The issuer must be listed in the /usr/afs/etc/UserList file on
-the machine named by the B<-server> argument, 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 the
+machine named by the B<-server> argument, 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<BosConfig(1)>,
-L<KeyFile(1)>,
-L<UserList(1)>,
-L<bos(1)>,
-L<bos_create(1)>,
-L<bos_shutdown(1)>,
-L<bos_status(1)>
+L<BosConfig(5)>,
+L<KeyFile(5)>,
+L<UserList(5)>,
+L<bos(8)>,
+L<bos_create(8)>,
+L<bos_shutdown(8)>,
+L<bos_status(8)>
=head1 COPYRIGHT
=head1 SYNOPSIS
-B<bos uninstall -server> <I<machine name>> -file <I<files to uninstall>>+
-[B<-dir> <I<destination dir>>] [B<-cell> <I<cell name>>]
- [B<-noauth>] [B<-localauth>] [-help]
+B<bos uninstall> B<-server> <I<machine name>>
+ B<-file> <I<files to uninstall>>+ [B<-dir> <I<destination dir>>]
+ [B<-cell> <I<cell name>>] [B<-noauth>] [B<-localauth>] [B<-help>]
-B<bos u -s> <I<machine name>> B<-f> <I<files to uninstall>>+ [-d <I<destination dir>>]
-[B<-c> <I<cell name>>] [B<-n>] [B<-l>] [B<-h>]
+B<bos u> B<-s> <I<machine name>> B<-f> <I<files to uninstall>>+
+ [B<-d> <I<destination dir>>] [B<-c> <I<cell name>>] [B<-n>] [B<-l>]
+ [B<-h>]
=head1 DESCRIPTION
-The bos uninstall command replaces each binary file specified by
-the B<-file> argument with its C<.BAK>version on the
-server machine named by the B<-server> argument, which is normally the
-binary distribution machine for its CPU/operating system type. It also
-changes the extension on the current C<.OLD> version (if any)
-to C<.BAK>. Each binary file must reside in the local
-B</usr/afs/bin> directory unless the B<-dir> argument names an
-alternate directory.
-
-To start using the reverted binary immediately, issue the bos
-restart command. Otherwise, the BOS Server automatically restarts
-the process at the time defined in the B</usr/afs/local/BosConfig>
-file; use the B<bos getrestart> command to display the time and
-the B<bos setrestart> time to set it.
+The B<bos uninstall> command replaces each binary file specified by the
+B<-file> argument with its C<.BAK> version on the server machine named by
+the B<-server> argument, which is normally the binary distribution machine
+for its CPU/operating system type. It also changes the extension on the
+current C<.OLD> version (if any) to C<.BAK>. Each binary file must reside
+in the local F</usr/afs/bin> directory unless the B<-dir> argument names
+an alternate directory.
+
+To start using the reverted binary immediately, issue the B<bos restart>
+command. Otherwise, the BOS Server automatically restarts the process at
+the time defined in the F</usr/afs/local/BosConfig> file; use the B<bos
+getrestart> command to display the time and the B<bos setrestart> time to
+set it.
=head1 OPTIONS
=over 4
-=item -server
->
+=item B<-server> <I<machine name>>
Indicates the binary distribution machine on which to revert to the
-C<.BAK> version of binaries. Identify the machine by IP
-address or its host name (either fully-qualified or abbreviated
-unambiguously). For details, see the introductory reference page for
-the B<bos> command suite.
+C<.BAK> version of binaries. Identify the machine by IP address or its
+host name (either fully-qualified or abbreviated unambiguously). For
+details, see L<bos(8)>.
If the machine is not a binary distribution machine and is running an
-B<upclientbin> process, then the files are overwritten the next time
-the B<upclientbin> process fetches the corresponding file from the
+C<upclientbin> process, then the files are overwritten the next time the
+C<upclientbin> process fetches the corresponding file from the
distribution machine (by default within five minutes).
-=item -file
->
+=item B<-file> <I<files to uninstall>>+
-Names each binary file to replace with its C<.BAK>
-version.
+Names each binary file to replace with its C<.BAK> version.
-=item -dir
->
+=item B<-dir> <I<destinatino dir>>
Provides the complete pathname of the local disk directory containing each
-file named by the B<-file> argument. It is necessary only if
-the binaries are not in the B</usr/afs/bin> directory.
+file named by the B<-file> argument. It is necessary only if the binaries
+are not in the F</usr/afs/bin> directory.
-=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<bos> 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<bos(8)>.
-=item -noauth
->
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. Do not combine this flag with the B<-localauth>
-flag. For more details, see the introductory B<bos> reference
-page.
+Assigns the unprivileged identity C<anonymous> to the issuer. Do not
+combine this flag with the B<-localauth> flag. For more details, see
+L<bos(8)>.
-=item -localauth
->
+=item B<-localauth>
Constructs a server ticket using a key from the local
-B</usr/afs/etc/KeyFile> file. The B<bos> command
-interpreter presents the ticket to the BOS Server during mutual
-authentication. Do not combine this flag with the B<-cell> or
-B<-noauth> options. For more details, see the introductory
-B<bos> reference page.
+F</usr/afs/etc/KeyFile> file. The B<bos> command interpreter presents the
+ticket to the BOS Server during mutual authentication. Do not combine this
+flag with the B<-cell> or B<-noauth> options. For more details, see
+L<bos(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 command overwrites the
-B</usr/afs/bin/kaserver> file on the machine
-B<fs4.abc.com> with its C<.BAK>version,
-and the current C<.BAK> version by the
-C<.OLD>version.
+The following example command overwrites the F</usr/afs/bin/kaserver> file
+on the machine C<fs4.abc.com> with its C<.BAK> version, and the current
+C<.BAK> version by the C<.OLD> version.
% bos uninstall -server fs4.abc.com -file kaserver
=head1 PRIVILEGE REQUIRED
-The issuer must be listed in the /usr/afs/etc/UserList file on
-the machine named by the B<-server> argument, 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 the
+machine named by the B<-server> argument, 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<BosConfig(1)>,
-L<KeyFile(1)>,
-L<UserList(1)>,
-L<bos(1)>,
-L<bos_getrestart(1)>,
-L<bos_restart(1)>,
-L<bos_setrestart(1)>,
-L<upclient(1)>
+L<BosConfig(5)>,
+L<KeyFile(5)>,
+L<UserList(5)>,
+L<bos(8)>,
+L<bos_getrestart(8)>,
+L<bos_restart(8)>,
+L<bos_setrestart(8)>,
+L<upclient(8)>
=head1 COPYRIGHT
=head1 SYNOPSIS
-B<bosserver> [B<-noauth>] [B<-log>] [B<-enable_peer_stats>] [-enable_process_stats]
-[B<-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<bosserver> [B<-noauth>] [B<-log>] [B<-enable_peer_stats>]
+ [B<-enable_process_stats>] [B<-help>]
=head1 DESCRIPTION
-The bosserver command initializes the Basic OverSeer (BOS)
-Server (B<bosserver> process). In the conventional
-configuration, the binary file is located in the B</usr/afs/bin>
-directory on a file server machine.
+The bosserver command initializes the Basic OverSeer (BOS) Server
+(B<bosserver> process). In the conventional configuration, the binary file
+is located in the F</usr/afs/bin> directory on a file server machine.
The BOS Server must run on every file server machine and helps to automate
file server administration by performing the following tasks:
Monitors the other AFS server processes on the local machine, to make sure
they are running correctly.
-
=item *
Automatically restarts failed processes, without contacting a human
operator. When restarting multiple server processes simultaneously, the
-BOS Server takes interdependencies into account and initiates restarts in the
-correct order.
-L<(1)>
-L<(1)>
-
+BOS Server takes interdependencies into account and initiates restarts in
+the correct order.
=item *
-Processes commands from the bos suite that administrators issue
-to verify the status of server processes, install and start new processes,
-stop processes either temporarily or permanently, and restart halted
-processes.
-
+Processes commands from the bos suite that administrators issue to verify
+the status of server processes, install and start new processes, stop
+processes either temporarily or permanently, and restart halted processes.
=item *
-Manages system configuration information: the files that list the
-cell's server encryption keys, database server machines, and users
-privileged to issue commands from the B<bos> and B<vos>
-suites.
-
+Manages system configuration information: the files that list the cell's
+server encryption keys, database server machines, and users privileged to
+issue commands from the B<bos> and B<vos> suites.
=back
The BOS Server logs a default set of important events in the file
-B</usr/afs/logs/BosLog>. To record the name of any user who
-performs a privileged B<bos> command (one that requires being listed
-in the B</usr/afs/etc/UserList> file), add the B<-log>
-flag. To display the contents of the B<BosLog> file, use the
-B<bos getlog> command.
+F</usr/afs/logs/BosLog>. To record the name of any user who performs a
+privileged B<bos> command (one that requires being listed in the
+F</usr/afs/etc/UserList> file), add the B<-log> flag. To display the
+contents of the B<BosLog> file, use the B<bos getlog> command.
The first time that the BOS Server initializes on a server machine, it
-creates several files and subdirectories in the local B</usr/afs>
+creates several files and subdirectories in the local F</usr/afs>
directory, and sets their mode bits to protect them from unauthorized
-access. Each time it restarts, it checks that the mode bits still
-comply with the settings listed in the following chart. A question mark
-indicates that the BOS Server initially turns off the bit (sets it to the
-hyphen), but does not check it at restart.
+access. Each time it restarts, it checks that the mode bits still comply
+with the settings listed in the following chart. A question mark indicates
+that the BOS Server initially turns off the bit (sets it to the hyphen),
+but does not check it at restart.
-If the mode bits do not comply, the BOS Server writes the following warning
-to the B<BosLog> file:
+If the mode bits do not comply, the BOS Server writes the following
+warning to the F<BosLog> file:
Bosserver reports inappropriate access on server directories
However, the BOS Server does not reset the mode bits, so the administrator
-can set them to alternate values if desired (with the understanding that the
-warning message then appears at startup).
+can set them to alternate values if desired (with the understanding that
+the warning message then appears at startup).
+
+This command does not use the syntax conventions of the AFS command
+suites. Provide the command name and all option names in full.
=head1 OPTIONS
=over 4
-=item -noauth
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the issuer,
-which is useful only when authorization checking is disabled on the server
-machine (for instance, during the installation of a file server
-machine.)
+Assigns the unprivileged identity C<anonymous> to the issuer, which is
+useful only when authorization checking is disabled on the server machine
+(for instance, during the installation of a file server machine.)
-=item -log
+=item B<-log>
-Records in the /usr/afs/logs/BosLog file the names of all users
-who successfully issue a privileged B<bos> command (one that requires
-being listed in the B</usr/afs/etc/UserList> file).
+Records in the F</usr/afs/logs/BosLog> file the names of all users who
+successfully issue a privileged B<bos> command (one that requires being
+listed in the F</usr/afs/etc/UserList> file).
-=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,
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 PRIVILEGE REQUIRED
-The issuer most be logged onto a file server machine as the local superuser
-B<root>.
+The issuer most be logged onto a file server machine as the local
+superuser C<root>.
=head1 SEE ALSO
-L<BosConfig(1)>,
-L<BosLog(1)>,
-L<bos(1)>,
-L<bos_create(1)>,
-L<bos_exec(1)>,
-L<bos_getlog(1)>,
-L<bos_getrestart(1)>,
-L<bos_restart(1)>,
-L<bos_shutdown(1)>,
-L<bos_start(1)>,
-L<bos_startup(1)>,
-L<bos_status(1)>,
-L<bos_stop(1)>
+L<BosConfig(5)>,
+L<BosLog(5)>,
+L<bos(8)>,
+L<bos_create(8)>,
+L<bos_exec(8)>,
+L<bos_getlog(8)>,
+L<bos_getrestart(8)>,
+L<bos_restart(8)>,
+L<bos_shutdown(8)>,
+L<bos_start(8)>,
+L<bos_startup(8)>,
+L<bos_status(8)>,
+L<bos_stop(8)>
=head1 COPYRIGHT
=head1 SYNOPSIS
-B<buserver> [-database <I<database directory>>]
-[B<-cellservdb> <I<cell configuration directory>>]
- [B<-resetdb>] [B<-noauth>] [-smallht]
- [-servers <I<list of ubik database servers>>+]
- [B<-enable_peer_stats>] [-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<buserver> [B<-database> <I<database directory>>]
+ [B<-cellservdb> <I<cell configuration directory>>] [B<-resetdb>]
+ [B<-noauth>] [B<-smallht>] [-servers <I<list of ubik database servers>>+]
+ [B<-enable_peer_stats>] [-enable_process_stats] [B<-help>]
=head1 DESCRIPTION
-The buserver command initializes the Backup Server, which runs
-on database server machines and maintains the Backup Database. In the
+The B<buserver> command initializes the Backup Server, which runs on
+database server machines and maintains the Backup Database. In the
conventional configuration, the binary file is located in the
-B</usr/afs/bin> directory on a file server machine.
+F</usr/afs/bin> directory on a file server machine.
-The buserver command is not normally issued at the command shell
+The B<buserver> command is not normally issued at the command shell
prompt, but rather placed into a database server machine's
-B</usr/afs/local/BosConfig> file with the B<bos create>
-command. If it is ever issued at the command shell prompt, the issuer
-must be logged onto a file server machine as the local superuser
-B<root>.
+F</usr/afs/local/BosConfig> file with the B<bos create> command. If it is
+ever issued at the command shell prompt, the issuer must be logged onto a
+file server machine as the local superuser C<root>.
As it initializes, the Backup Server process creates the two files that
-constitute the Backup Database, B<bdb.DB0> and
-B<bdb.DBSYS1>, in the B</usr/afs/db> directory if they
-do not already exist. The Backup Database houses information about
-volume sets and entries, the dump hierarchy, Tape Coordinators, and previously
-performed dump sets. Use the commands in the B<backup> suite to
-administer the database.
+constitute the Backup Database, F<bdb.DB0> and F<bdb.DBSYS1>, in the
+F</usr/afs/db> directory if they do not already exist. The Backup Database
+houses information about volume sets and entries, the dump hierarchy, Tape
+Coordinators, and previously performed dump sets. Use the commands in the
+B<backup> suite to administer the database.
The Backup Server records a trace of its activity in the
-B</usr/afs/logs/BackupLog> file. Use the B<bos getlog>
-command to display the contents of the file.
+F</usr/afs/logs/BackupLog> file. Use the B<bos getlog> command to display
+the contents of the file.
+
+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
-The B<buserver> process reserves port 7021 for its
-use. Unexpected behavior can occur if another process tries to reserve
-this port while the B<buserver> process is running.
+The B<buserver> process reserves port 7021 for its use. Unexpected
+behavior can occur if another process tries to reserve this port while the
+B<buserver> process is running.
=head1 OPTIONS
=over 4
-=item -database
+=item B<-database> <I<database directory>>
Specifies the pathname of an alternate directory for the Backup Database
-files, ending in a final slash (B</>). If this argument is not
-provided, the default is the B</usr/afs/db> directory.
+files, ending in a final slash (C</>). If this argument is not provided,
+the default is the F</usr/afs/db> directory.
-=item -cellservdb
+=item B<-cellservdb> <I<cell configuration directory>>
Specifies the pathname of the directory from which the Backup Server reads
-in an alternate version of the B<CellServDB> file. This
-argument is mandatory for correct functioning when the Backup Server is
-running on a subset of the cell's database server machines that is not a
-majority of the machines listed in the standard
-B</usr/afs/etc/CellServDB> file (which the Backup Server consults if
-this argument is not provided). It is not appropriate in any other
-circumstances.
+in an alternate version of the F<CellServDB> file. This argument is
+mandatory for correct functioning when the Backup Server is running on a
+subset of the cell's database server machines that is not a majority of
+the machines listed in the standard F</usr/afs/etc/CellServDB> file (which
+the Backup Server consults if this argument is not provided). It is not
+appropriate in any other circumstances.
-=item -resetdb
+=item B<-resetdb>
Removes all of the information in the Backup Database files in the
-B</usr/afs/db> directory, leaving zero-length versions of them.
-The backup operator must recreate the configuration entries in the database
+F</usr/afs/db> directory, leaving zero-length versions of them. The
+backup operator must recreate the configuration entries in the database
(for volume sets, the dump hierarchy and so on) before performing backup
operations.
-=item -noauth
+=item B<-noauth>
Establishes an unauthenticated connection between the issuer and the
Backup Server, in which the Backup Server treats the issuer as the
-unprivileged user B<anonymous>. It is useful only when
-authorization checking is disabled on the database server machine. In
-normal circumstances, the Backup Server allows only authorized (privileged)
-users to issue commands that affect or contact the Backup Database, and
-refuses to perform such an action even if the B<-noauth> flag is
-used.
+unprivileged user C<anonymous>. It is useful only when authorization
+checking is disabled on the database server machine. In normal
+circumstances, the Backup Server allows only authorized (privileged) users
+to issue commands that affect or contact the Backup Database, and refuses
+to perform such an action even if the B<-noauth> flag is used.
-=item -smallht
+=item B<-smallht>
Directs the Backup Server to use smaller internal hash tables for the
-Backup Database, which reduces memory requirements but can make data access
-take longer.
+Backup Database, which reduces memory requirements but can make data
+access take longer.
-=item -servers
+=item B<-servers> <I<list of ubik database servers>>+
Specifies the database server machines on which to start the Backup
-Server. Use this argument if running the Backup Server on a subset of
-the database server machines that is not a majority of the machines listed in
-the B</usr/afs/etc/CellServDB> file.
+Server. Use this argument if running the Backup Server on a subset of the
+database server machines that is not a majority of the machines listed in
+the F</usr/afs/etc/CellServDB> file.
-=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,
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 following example bos create command creates a
-B<buserver> process on the file server machine
-B<fs3.abc.com>. It appears here on two lines only
-for legibility.
+The following example B<bos create> command creates a C<buserver> process
+on the file server machine C<fs3.abc.com>. It appears here on two lines
+only for legibility.
- % bos create -server fs3.abc.com -instance buserver \
+ % bos create -server fs3.abc.com -instance buserver \
-type simple -cmd /usr/afs/bin/buserver
=head1 PRIVILEGE REQUIRED
-The issuer must be logged in as the superuser root on a file
-server machine to issue the command at a command shell prompt. It is
-conventional instead to create and start the process by issuing the B<bos
-create> command.
+The issuer must be logged in as the superuser C<root> on a file server
+machine to issue the command at a command shell prompt. It is conventional
+instead to create and start the process by issuing the B<bos create>
+command.
=head1 SEE ALSO
-L<BackupLog(1)>,
-L<BosConfig(1)>,
-L<CellServDB (server version)(1)>
-
-L<bdb.DB0 and bdb.DBSYS1(1)>
-
-L<backup(1)>,
-L<bos_create(1)>,
-L<bos_getlog(1)>
+L<BackupLog(5)>,
+L<BosConfig(5)>,
+L<CellServDB(5)>,
+L<bdb.DB0(5)>,
+L<backup(8)>,
+L<bos_create(8)>,
+L<bos_getlog(8)>
=head1 COPYRIGHT
=head1 SYNOPSIS
-B<butc> [B<-port> <I<port offset>>] [B<-debuglevel> < B<0> | B<1> | 2 >]
-[B<-cell> <I<cell name>>] [B<-noautoquery>]
- [B<-localauth>] [-help]
+B<butc> [B<-port> <I<port offset>>] [B<-debuglevel> (0 | 1 | 2)]
+ [B<-cell> <I<cell name>>] [B<-noautoquery>] [B<-localauth>] [B<-help>]
-B<butc> [B<-p> <I<port offset>>] [B<-d> < B<0> | B<1> | 2 >]
-[B<-c> <I<cell name>>] [B<-n>] [B<-l>] [B<-h>]
+B<butc> [B<-p> <I<port offset>>] [B<-d> (0 | 1 | 2)]
+ [B<-c> <I<cell name>>] [B<-n>] [B<-l>] [B<-h>]
=head1 DESCRIPTION
-The butc command initializes a Tape Coordinator process on a
-Tape Coordinator machine, enabling an operator to direct Backup System
-requests to the associated tape device or backup data file. (The Tape
-Coordinator controls a backup data file if the B<FILE YES> instruction
-appears in the B</usr/afs/backup/CFG_>I<device_name> file that
-corresponds to the Tape Coordinator's entry in the
-B</usr/afs/backup/tapeconfig> file. For the sake of simplicity,
-the following discusses tape devices only.)
+The B<butc> command initializes a Tape Coordinator process on a Tape
+Coordinator machine, enabling an operator to direct Backup System requests
+to the associated tape device or backup data file. (The Tape Coordinator
+controls a backup data file if the C<FILE YES> instruction appears in the
+F</usr/afs/backup/CFG_I<device_name>> file that corresponds to the Tape
+Coordinator's entry in the F</usr/afs/backup/tapeconfig> file. For the
+sake of simplicity, the following discusses tape devices only.)
It is conventional to start and run the Tape Coordinator in the
foreground. In this case, it runs on its own connection, which is
-unavailable for any other use and must remain open the entire time the Tape
-Coordinator is to accept backup requests and while it is executing
+unavailable for any other use and must remain open the entire time the
+Tape Coordinator is to accept backup requests and while it is executing
them. (When using a window manager, the connection corresponds to a
separate command shell window.) The Tape Coordinator can run in the
-background if the B<CFG_>I<device_name> file is configured to
-eliminate any need for the Tape Coordinator to prompt the operator. In
-both the foreground and background, the Tape Coordinator writes operation
-traces and other output to the standard output stream on the connection over
-which it was started. Use the B<-debuglevel> argument to
-control the amount of information that appears. The Tape Coordinator
-also writes traces and error messages to two files in the local
-B</usr/afs/backup> directory:
+background if the F<CFG_I<device_name>> file is configured to eliminate
+any need for the Tape Coordinator to prompt the operator. In both the
+foreground and background, the Tape Coordinator writes operation traces
+and other output to the standard output stream on the connection over
+which it was started. Use the B<-debuglevel> argument to control the
+amount of information that appears. The Tape Coordinator also writes
+traces and error messages to two files in the local F</usr/afs/backup>
+directory:
=over 4
=item *
-The TE_I<device_name> file records problems that the Tape
-Coordinator encounters as it executes backup operations.
-
+The F<TE_I<device_name>> file records problems that the Tape Coordinator
+encounters as it executes backup operations.
=item *
-The TL_I<device_name> file records a trace of operations
-as well as the same errors written to the B<TE_>I<device_name>
-file.
-
+The F<TL_I<device_name>> file records a trace of operations as well as the
+same errors written to the F<TE_I<device_name>> file.
=back
-The Tape Coordinator creates the files automatically as it
-initializes. If there are existing files, the Tape Coordinator renames
-them with a B<.old> extension, overwriting the existing
-B<.old> files if they exist. It derives the
-I<device_name> part of the file names by stripping off the device
-name's B</dev/> prefix and replacing any other slashes with
-underscores. For example, the files are called B<TE_rmt_4m> and
-B<TL_rmt_4m> for a device called B</dev/rmt/4m>.
-
-By default, at the beginning of each operation the Tape Coordinator prompts
-for the operator to insert the first tape into the drive and press
-<B<Return>>. To suppress this prompt, include the
-B<-noautoquery> flag on the command line or the instruction
-B<AUTOQUERY NO> in the
-B</usr/afs/backup/CFG_>I<device_name> file. When the
-prompt is suppressed, the first required tape must be in the drive before a
-B<backup> command is issued. For subsequent tapes, the Tape
-Coordinator uses its normal tape acquisition routine: if the
-B</usr/afs/backup/CFG_>I<device_name> file includes a
-B<MOUNT> instruction, the Tape Coordinator invokes the indicated
-command; otherwise, it prompts the operator for the next tape.
+The Tape Coordinator creates the files automatically as it initializes. If
+there are existing files, the Tape Coordinator renames them with a C<.old>
+extension, overwriting the existing C<.old> files if they exist. It
+derives the I<device_name> part of the file names by stripping off the
+device name's F</dev/> prefix and replacing any other slashes with
+underscores. For example, the files are called F<TE_rmt_4m> and
+F<TL_rmt_4m> for a device called F</dev/rmt/4m>.
+
+By default, at the beginning of each operation the Tape Coordinator
+prompts for the operator to insert the first tape into the drive and press
+Return. To suppress this prompt, include the B<-noautoquery> flag on the
+command line or the instruction C<AUTOQUERY NO> in the
+F</usr/afs/backup/CFG_I<device_name>> file. When the prompt is suppressed,
+the first required tape must be in the drive before a B<backup> command is
+issued. For subsequent tapes, the Tape Coordinator uses its normal tape
+acquisition routine: if the F</usr/afs/backup/CFG_I<device_name>> file
+includes a C<MOUNT> instruction, the Tape Coordinator invokes the
+indicated command; otherwise, it prompts the operator for the next tape.
To stop the Tape Coordinator process, enter an interrupt signal such as
-<B<Ctrl-c>> over the dedicated connection (in the command shell
-window).
+Ctrl-C over the dedicated connection (in the command shell window).
-To cancel a backup operation that involves a tape before it
-begins (assuming the initial tape prompt has not been suppressed), enter the
-letter B<a> (for B<abort>) and press <B<Return>> at
-the Tape Coordinator's prompt for the first tape.
+To cancel a backup operation that involves a tape before it begins
+(assuming the initial tape prompt has not been suppressed), enter the
+letter C<a> (for C<abort>) and press Return at the Tape Coordinator's
+prompt for the first tape.
Tape Coordinator operation depends on the correct configuration of certain
files, as described in the following list:
=item *
-The local /usr/afs/backup/tapeconfig file must include an entry
-for the Tape Coordinator that specifies its device name and port offset
-number, among other information; for details, see the
-B<tapeconfig> reference page.
-
+The local F</usr/afs/backup/tapeconfig> file must include an entry for the
+Tape Coordinator that specifies its device name and port offset number,
+among other information; for details, L<tapeconfig(5)>.
=item *
-The port offset number recorded in the Tape Coordinator's entry in
-the Backup Database must match the one in the B<tapeconfig>
-file. Create the Backup Database entry by using the B<backup
-addhost> command.
-
+The port offset number recorded in the Tape Coordinator's entry in the
+Backup Database must match the one in the F<tapeconfig> file. Create the
+Backup Database entry by using the B<backup addhost> command.
=item *
-The optional /usr/afs/backup/CFG_I<device_name> file can
-contain instructions for mounting and unmounting tapes automatically (when
-using a tape stacker or jukebox, for instance) or automating other aspects of
-the backup process. The I<device_name> part of the name is
-derived as described previously for the B<TE_>I<device_name> and
-B<TL_>I<device_name> files.
-
+The optional F</usr/afs/backup/CFG_I<device_name>> file can contain
+instructions for mounting and unmounting tapes automatically (when using a
+tape stacker or jukebox, for instance) or automating other aspects of the
+backup process. The I<device_name> part of the name is derived as
+described previously for the F<TE_I<device_name>> and F<TL_I<device_name>>
+files.
=back
=head1 CAUTIONS
-If the Tape Coordinator machine is an AIX machine, use the SMIT
-utility to set the device's block size to 0 (zero), indicating variable
-block size. Otherwise, tape devices attached to machines running other
-operating systems sometimes cannot read tapes written on AIX machines.
-For instructions, see the I<IBM AFS Administration Guide> chapter
-about configuring the Backup System.
+If the Tape Coordinator machine is an AIX machine, use the SMIT utility to
+set the device's block size to 0 (zero), indicating variable block
+size. Otherwise, tape devices attached to machines running other operating
+systems sometimes cannot read tapes written on AIX machines. For
+instructions, see the I<IBM AFS Administration Guide> chapter about
+configuring the Backup System.
=head1 OPTIONS
=over 4
-=item -port
+=item B<-port> <I<port offset>>
-Specifies the port offset number of the Tape Coordinator to
-initialize.
+Specifies the port offset number of the Tape Coordinator to initialize.
-=item -debuglevel
+=item B<-debuglevel>
Controls the amount and type of messages the Tape Coordinator displays on
-the standard output stream. Provide one of three acceptable
-values:
+the standard output stream. Provide one of three acceptable values:
=over 4
=item *
-0 to display the minimum level of detail required to describe
-Tape Coordinator operations, including prompts for tapes, messages that
-indicate the beginning and end of operations, and error messages. This
-is the default value.
-
+C<0> to display the minimum level of detail required to describe Tape
+Coordinator operations, including prompts for tapes, messages that
+indicate the beginning and end of operations, and error messages. This is
+the default value.
=item *
-1 to display the names of the volumes being dumped or restored
-as well as the information displayed at level 0.
-
+C<1> to display the names of the volumes being dumped or restored as well
+as the information displayed at level C<0>.
=item *
-2 to display all messages also being written to the
-B<TL_>I<device_name> log file.
-
+C<2> to display all messages also being written to the
+F<TL_I<device_name>> log file.
=back
-=item -cell
+=item B<-cell> <I<cell name>>
Names the cell in which the Tape Coordinator operates (the cell to which
the file server machines that house affected volumes belong). If this
-argument is omitted, the Tape Coordinator runs in the local cell as defined in
-the local B</usr/vice/etc/ThisCell> file. Do not combine this
+argument is omitted, the Tape Coordinator runs in the local cell as
+defined in the local F</usr/vice/etc/ThisCell> file. Do not combine this
flag with the B<-localauth> argument.
-=item -noautoquery
+=item B<-noautoquery>
-Suppresses the Tape Coordinator's prompt for insertion of the first
-tape needed for an operation. The operator must insert the tape into
-the drive before issuing the B<backup> command that initializes the
-operation.
+Suppresses the Tape Coordinator's prompt for insertion of the first tape
+needed for an operation. The operator must insert the tape into the drive
+before issuing the B<backup> command that initializes the operation.
-=item -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>. The B<butc> command
-interpreter presents the ticket, which never expires, to the Volume Server and
-Volume Location Server to use in mutual authentication.
+highest key version number in the local F</usr/afs/etc/KeyFile>. The
+B<butc> command interpreter presents the ticket, which never expires, to
+the Volume Server and Volume Location Server to use in mutual
+authentication.
-Do not combine this argument with the -cell flag, and use it
-only when logged on to a server machine as the local superuser
-B<root>; client machines do not have
-B</usr/afs/etc/KeyFile> file.
+Do not combine this argument with the B<-cell> flag, and use it only when
+logged on to a server machine as the local superuser C<root>; client
+machines do not have F</usr/afs/etc/KeyFile> file.
-=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 starts the Tape Coordinator with port offset
-B<7> at debug level B<1>, meaning the Tape Coordinator reports
-the names of volumes it is dumping or restoring.
+The following command starts the Tape Coordinator with port offset C<7> at
+debug level C<1>, meaning the Tape Coordinator reports the names of
+volumes it is dumping or restoring.
% butc -port 7 -debuglevel 1
=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 a volume to be backed
-up. If the B<-localauth> flag is included, the issuer must
-instead be logged on to the Tape Coordinator machine as the local superuser
-B<root.> In addition, the issuer must be able to read and write
-to the log and configuration files in the local B</usr/afs/backup>
-directory.
+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 a volume to be backed up. If
+the B<-localauth> flag is included, the issuer must instead be logged on
+to the Tape Coordinator machine as the local superuser C<root>. In
+addition, the issuer must be able to read and write to the log and
+configuration files in the local F</usr/afs/backup> directory.
=head1 SEE ALSO
-L<CFG_I<device_name>(1)>,
-L<KeyFile(1)>,
-L<TE_I<device_name>(1)>,
-L<ThisCell (client version)(1)>
-
-L<TL_I<device_name>(1)>,
-L<UserList(1)>,
-L<tapeconfig(1)>,
-L<backup_addhost(1)>
+L<KeyFile(5)>,
+L<ThisCell(5)>,
+L<UserList(5)>,
+L<tapeconfig(5)>,
+L<backup_addhost(8)>
=head1 COPYRIGHT
=head1 SYNOPSIS
-B<fileserver> [B<-d> <I<debug level>>] [-p <I<number of processes>>]
-[B<-spare> <I<number of spare blocks>>]
- [B<-pctspare> <I<percentage spare>>] [-b <I<buffers>>]
- [B<-l> <I<large vnodes>>] [-s <I<small nodes>>]
- [B<-vc> <I<volume cachesize>>] [-w <I<call back wait interval>>]
- [-cb <I<number of call backs>>]
- [-banner (print banner every 10 minutes)]
- [-novbc (whole volume cbs disabled)]
- [-implicit <I<admin mode bits: rlidwka>>]
- [-hr <I<number of hours between refreshing the host cps>>]
- [-busyat <I<redirect clients when queue > n>>]
- [-rxpck <I<number of rx extra packets>>]
- [-rxdbg (enable rx debugging)]
- [-rxdbge (enable rxevent debugging)]
- [-m <I<min percentage spare in partition>>]
- [-lock (keep fileserver from swapping)]
- [B<-L> (large server conf)] [-S (small server conf)]
- [B<-k> <I<stack size>>] [-realm <I<Kerberos realm name>>]
- [-udpsize <I<size of socket buffer in bytes>>]
- [B<-enable_peer_stats>] [-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<fileserver> [B<-d> <I<debug level>>] [B<-p> <I<number of processes>>]
+ [B<-spare> <I<number of spare blocks>>]
+ [B<-pctspare> <I<percentage spare>>] [B<-b> <I<buffers>>]
+ [B<-l> <I<large vnodes>>] [B<-s> <I<small nodes>>]
+ [B<-vc> <I<volume cachesize>>] [B<-w> <I<call back wait interval>>]
+ [B<-cb> <I<number of call backs>>] [B<-banner>] [B<-novbc>]
+ [B<-implicit> <I<admin mode bits: rlidwka>>]
+ [B<-hr> <I<number of hours between refreshing the host cps>>]
+ [B<-busyat> <I<< redirect clients when queue > n >>>]
+ [B<-rxpck> <I<number of rx extra packets>>]
+ [B<-rxdbg>] [B<-rxdbge>] [B<-m> <I<min percentage spare in partition>>]
+ [B<-lock>] [B<-L>] [B<-S>] [B<-k> <I<stack size>>]
+ [B<-realm> <I<Kerberos realm name>>]
+ [B<-udpsize> <I<size of socket buffer in bytes>>]
+ [B<-enable_peer_stats>] [B<-enable_process_stats>] [B<-help>]
=head1 DESCRIPTION
-The fileserver command initializes the File Server component of
-the B<fs> process. In the conventional configuration, its
-binary file is located in the B</usr/afs/bin> directory on a file
-server machine.
+The B<fileserver> command initializes the File Server component of the
+C<fs> process. In the conventional configuration, its binary file is
+located in the F</usr/afs/bin> directory on a file server machine.
-The fileserver command is not normally issued at the command
-shell prompt, but rather placed into a database server machine's
-B</usr/afs/local/BosConfig> file with the B<bos create>
-command. If it is ever issued at the command shell prompt, the issuer
-must be logged onto a file server machine as the local superuser
-B<root>.
+The B<fileserver> command is not normally issued at the command shell
+prompt, but rather placed into a database server machine's
+F</usr/afs/local/BosConfig> file with the B<bos create> command. If it is
+ever issued at the command shell prompt, the issuer must be logged onto a
+file server machine as the local superuser C<root>.
-The File Server creates the /usr/afs/logs/FileLog log file as it
+The File Server creates the F</usr/afs/logs/FileLog> log file as it
initializes, if the file does not already exist. It does not write a
-detailed trace by default, but use the B<-d> option to increase the
-amount of detail. Use the B<bos getlog> command to display the
-contents of the log file.
-
-The command's arguments enable the administrator to control many
-aspects of the File Server's performance, as detailed in the
-B<Options> section. By default the B<fileserver>
-command sets values for many arguments that are suitable for a medium-sized
-file server machine. To set values suitable for a small or large file
-server machine, use the B<-S> or B<-L> flag
+detailed trace by default, but use the B<-d> option to increase the amount
+of detail. Use the B<bos getlog> command to display the contents of the
+log file.
+
+The command's arguments enable the administrator to control many aspects
+of the File Server's performance, as detailed in L<OPTIONS>. By default
+the B<fileserver> command sets values for many arguments that are suitable
+for a medium-sized file server machine. To set values suitable for a small
+or large file server machine, use the B<-S> or B<-L> flag
respectively. The following list describes the parameters and
-corresponding argument for which the B<fileserver> command sets
-default values, and L<Table_1(1)> summarizes the setting for each of the three machine
-sizes.
+corresponding argument for which the B<fileserver> command sets default
+values, and the table below summarizes the setting for each of the three
+machine sizes.
=over 4
=item *
The maximum number of lightweight processes (LWPs) the File Server uses to
-handle requests for data; corresponds to the B<-p>
-argument. The File Server always uses a minimum of 32 KB for these
-processes.
-
+handle requests for data; corresponds to the B<-p> argument. The File
+Server always uses a minimum of 32 KB for these processes.
=item *
-The maximum number of directory blocks the File Server caches in
-memory; corresponds to the B<-b> argument. Each cached
-directory block (buffer) consumes 2,092 bytes of memory.
-
+The maximum number of directory blocks the File Server caches in memory;
+corresponds to the B<-b> argument. Each cached directory block (buffer)
+consumes 2,092 bytes of memory.
=item *
The maximum number of large vnodes the File Server caches in memory for
-tracking directory elements; corresponds to the B<-l>
-argument. Each large vnode consumes 292 bytes of memory.
-
+tracking directory elements; corresponds to the B<-l> argument. Each large
+vnode consumes 292 bytes of memory.
=item *
The maximum number of small vnodes the File Server caches in memory for
-tracking file elements; corresponds to the B<-s> argument.
-Each small vnode consumes 100 bytes of memory.
-
+tracking file elements; corresponds to the B<-s> argument. Each small
+vnode consumes 100 bytes of memory.
=item *
Server can cache in memory before having to retrieve data from disk;
corresponds to the B<-vc> argument.
-
=item *
The maximum number of callback structures the File Server caches in
-memory; corresponds to the B<-cb> argument. Each callback
-structure consumes 16 bytes of memory.
-
+memory; corresponds to the B<-cb> argument. Each callback structure
+consumes 16 bytes of memory.
=item *
-The maximum number of Rx packets the File Server uses;
-corresponds to the B<-rxpck> argument. Each packet consumes
-1544 bytes of memory.
-
+The maximum number of Rx packets the File Server uses; corresponds to the
+B<-rxpck> argument. Each packet consumes 1544 bytes of memory.
=back
-L<Table 1. File Server configuration parameters(1)>
+The default values are:
-To override any of the values, provide the indicated argument (which can be
-combined with the B<-S> or B<-L> flag).
+ Parameter (Argument) Small (-S) Medium Large (-L)
+ ---------------------------------------------------------------------
+ Number of LWPs (-p) 6 9 12
+ Number of cached dir blocks (-b) 70 90 120
+ Number of cached large vnodes (-l) 200 400 600
+ Number of cached small vnodes (-s) 200 400 600
+ Maximum volume cache size (-vc) 200 400 600
+ Number of callbacks (-cb) 20,000 60,000 64,000
+ Number of Rx packets (-rxpck) 100 150 200
-The amount of memory required for the File Server varies. The
-approximate default memory usage is 751 KB when the B<-S> flag is used
-(small configuration), 1.1 MB when all defaults are used (medium
-configuration), and 1.4 MB when the B<-L> flag is used (large
-configuration). If additional memory is available, increasing the value
-of the B<-cb> and B<-vc> arguments can improve File Server
-performance most directly.
+To override any of the values, provide the indicated argument (which can
+be combined with the B<-S> or B<-L> flag).
+
+The amount of memory required for the File Server varies. The approximate
+default memory usage is 751 KB when the B<-S> flag is used (small
+configuration), 1.1 MB when all defaults are used (medium configuration),
+and 1.4 MB when the B<-L> flag is used (large configuration). If
+additional memory is available, increasing the value of the B<-cb> and
+B<-vc> arguments can improve File Server performance most directly.
By default, the File Server allows a volume to exceed its quota by 1 MB
-when an application is writing data to an existing file in a volume that is
-full. The File Server still does not allow users to create new files in
-a full volume. To change the default, use one of the following
-arguments:
-L<(1)>
+when an application is writing data to an existing file in a volume that
+is full. The File Server still does not allow users to create new files in
+a full volume. To change the default, use one of the following arguments:
=over 4
=item *
-Set the -spare argument to the number of extra kilobytes that
-the File Server allows as overage. A value of B<0> allows no
-overage.
-
+Set the B<-spare> argument to the number of extra kilobytes that the File
+Server allows as overage. A value of C<0> allows no overage.
=item *
-Set the -pctspare argument to the percentage of the
-volume's quota the File Server allows as overage.
-
+Set the B<-pctspare> argument to the percentage of the volume's quota the
+File Server allows as overage.
=back
-By default, the File Server implicitly grants the a
-(B<administer>) and B<l> (B<lookup>) permissions to
-the B<system:administrators> on the access control list (ACL) of
-every directory in the volumes stored on its file server machine. In
-other words, the group's members can exercise those two permissions even
-when an entry for the group does not appear on an ACL. To change the
-set of default permissions, use the B<-implicit> argument.
-
-The File Server maintains a I<host current protection subgroup>
-(I<host CPS>) for each client machine from which it has received a
-data access request. Like the CPS for a user, a host CPS lists all of
-the Protection Database groups to which the machine belongs, and the File
-Server compares the host CPS to a directory's ACL to determine in what
-manner users on the machine are authorized to access the directory's
-contents. When the B<pts adduser> or B<pts removeuser>
-command is used to change the groups to which a machine belongs, the File
-Server must recompute the machine's host CPS in order to notice the
-change. By default, the File Server contacts the Protection Server
-every two hours to recompute host CPSs, implying that it can take that long
-for changed group memberships to become effective. To change this
-frequency, use the B<-hr> argument.
+By default, the File Server implicitly grants the C<a> (administer) and
+C<l> (lookup) permissions to system:administrators on the access control
+list (ACL) of every directory in the volumes stored on its file server
+machine. In other words, the group's members can exercise those two
+permissions even when an entry for the group does not appear on an ACL. To
+change the set of default permissions, use the B<-implicit> argument.
+
+The File Server maintains a I<host current protection subgroup> (I<host
+CPS>) for each client machine from which it has received a data access
+request. Like the CPS for a user, a host CPS lists all of the Protection
+Database groups to which the machine belongs, and the File Server compares
+the host CPS to a directory's ACL to determine in what manner users on the
+machine are authorized to access the directory's contents. When the B<pts
+adduser> or B<pts removeuser> command is used to change the groups to
+which a machine belongs, the File Server must recompute the machine's host
+CPS in order to notice the change. By default, the File Server contacts
+the Protection Server every two hours to recompute host CPSs, implying
+that it can take that long for changed group memberships to become
+effective. To change this frequency, use the B<-hr> argument.
The File Server generates the following message when a partition is nearly
full:
No space left on device
+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 B<-k> and -w arguments, which are
-intended for use by the AFS Development group only. Changing them from
-their default values can result in unpredictable File Server behavior.
-In any case, on many operating systems the File Server uses native threads
-rather than the LWP threads, so using the B<-k> argument to set the
-number of LWP threads has no effect.
+Do not use the B<-k> and -w arguments, which are intended for use by the
+AFS Development group only. Changing them from their default values can
+result in unpredictable File Server behavior. In any case, on many
+operating systems the File Server uses native threads rather than the LWP
+threads, so using the B<-k> argument to set the number of LWP threads has
+no effect.
-Do not specify both the B<-spare> and -pctspare
-arguments. Doing so causes the File Server to exit, leaving an error
-message in the B</usr/afs/logs/FileLog> file.
+Do not specify both the B<-spare> and B<-pctspare> arguments. Doing so
+causes the File Server to exit, leaving an error message in the
+F</usr/afs/logs/FileLog> file.
-Options that are available only on some system types, such as the
-B<-m> and B<-lock> options, appear in the output generated by
-the B<-help> option only on the relevant system type.
+Options that are available only on some system types, such as the B<-m>
+and B<-lock> options, appear in the output generated by the B<-help>
+option only on the relevant system type.
=head1 OPTIONS
=over 4
-=item -d
+=item B<-d> <I<debug level>>
Sets the detail level for the debugging trace written to the
-B</usr/afs/logs/FileLog> file. Provide one of the following
-values, each of which produces an increasingly detailed trace:
-B<0>, B<1>, B<5>, B<25>, and
-B<125>. The default value of B<0> produces only a few
-messages.
+F</usr/afs/logs/FileLog> file. Provide one of the following values, each
+of which produces an increasingly detailed trace: C<0>, C<1>, C<5>, C<25>,
+and C<125>. The default value of C<0> produces only a few messages.
-=item -p
+=item B<-p> <I<number of processes>>
-Sets the number of threads to run. Provide a positive
-integer. The File Server creates and uses five threads for special
-purposes, in addition to the number specified (but if this argument specifies
-the maximum possible number, the File Server automatically uses five of the
-threads for its own purposes).
+Sets the number of threads to run. Provide a positive integer. The File
+Server creates and uses five threads for special purposes, in addition to
+the number specified (but if this argument specifies the maximum possible
+number, the File Server automatically uses five of the threads for its own
+purposes).
-The maximum number of threads can differ in each release of AFS.
-Consult the I<IBM AFS Release Notes> for the current release.
+The maximum number of threads can differ in each release of AFS. Consult
+the I<IBM AFS Release Notes> for the current release.
-=item -spare
+=item B<-spare> <I<number of spare blocks>>
Specifies the number of additional kilobytes an application can store in a
-volume after the quota is exceeded. Provide a positive integer; a
-value of B<0> prevents the volume from ever exceeding its
-quota. Do not combine this argument with the B<-pctspare>
-argument.
+volume after the quota is exceeded. Provide a positive integer; a value of
+C<0> prevents the volume from ever exceeding its quota. Do not combine
+this argument with the B<-pctspare> argument.
-=item -pctspare
+=item B<-pctspare> <I<percentage spare>>
Specifies the amount by which the File Server allows a volume to exceed
-its quota, as a percentage of the quota. Provide an integer between
-B<0> and B<99>. A value of B<0> prevents the
-volume from ever exceeding its quota. Do not combine this argument with
-the B<-spare> argument.
+its quota, as a percentage of the quota. Provide an integer between C<0>
+and C<99>. A value of C<0> prevents the volume from ever exceeding its
+quota. Do not combine this argument with the B<-spare> argument.
-=item -b
+=item B<-b> <I<buffers>>
-Sets the number of directory buffers. Provide a positive
-integer.
+Sets the number of directory buffers. Provide a positive integer.
-=item -l
+=item B<-l> <I<large vnodes>>
Sets the number of large vnodes available in memory for caching directory
elements. Provide a positive integer.
-=item -s
+=item B<-s> <I<small nodes>>
Sets the number of small vnodes available in memory for caching file
elements. Provide a positive integer.
-=item -vc
+=item B<-vc> <I<volume cachesize>>
-Sets the number of volumes the File Server can cache in memory.
-Provide a positive integer.
+Sets the number of volumes the File Server can cache in memory. Provide a
+positive integer.
-=item -w
+=item B<-w> <I<call back wait interval>>
Sets the interval at which the daemon spawned by the File Server performs
-its maintenance tasks. Do not use this argument; changing the
-default value can cause unpredictable behavior.
+its maintenance tasks. Do not use this argument; changing the default
+value can cause unpredictable behavior.
-=item -cb
+=item B<-cb> <I<number of callbacks>>
-Sets the number of callbacks the File Server can track. Provide a
-positive integer.
+Sets the number of callbacks the File Server can track. Provide a positive
+integer.
-=item -banner
+=item B<-banner>
-Prints the following banner to /dev/console about every 10
-minutes.
+Prints the following banner to F</dev/console> about every 10 minutes.
File Server is running at I<time>.
-=item -novbc
+=item B<-novbc>
Prevents the File Server from breaking the callbacks that Cache Managers
hold on a volume that the File Server is reattaching after the volume was
-offline (as a result of the B<vos restore> command, for
-example). Use of this flag is strongly discouraged.
+offline (as a result of the B<vos restore> command, for example). Use of
+this flag is strongly discouraged.
-=item -implicit
+=item B<-implicit> <I<admin mode bits>>
Defines the set of permissions granted by default to the
-B<system:administrators> group on the ACL of every directory in
-a volume stored on the file server machine. Provide one or more of the
-standard permission letters (B<rlidwka>) and auxiliary permission
-letters (B<ABCDEFGH>), or one of the shorthand notations for groups of
-permissions (B<all>, B<none>, B<read>, and
-B<write>). To review the meaning of the permissions, see the
-B<fs setacl> reference page.
+system:administrators group on the ACL of every directory in a volume
+stored on the file server machine. Provide one or more of the standard
+permission letters (C<rlidwka>) and auxiliary permission letters
+(C<ABCDEFGH>), or one of the shorthand notations for groups of permissions
+(C<all>, C<none>, C<read>, and C<write>). To review the meaning of the
+permissions, see the B<fs setacl> reference page.
-=item -hr
->
+=item B<-hr> <I<number of hours between refreshing the host cps>>
Specifies how often the File Server refreshes its knowledge of the
machines that belong to protection groups (refreshes the host CPSs for
from machines recently added to protection groups to access data for which
those machines now have the necessary ACL permissions.
-=item -busyat
+=item B<-busyat> <I<< redirect clients when queue > n >>>
Defines the number of incoming RPCs that can be waiting for a response
from the File Server before the File Server returns the error code
-B<VBUSY> to the Cache Manager that sent the latest RPC. In
-response, the Cache Manager retransmits the RPC after a delay. This
-argument prevents the accumulation of so many waiting RPCs that the File
-Server can never process them all. Provide a positive integer.
-The default value is 600.
+C<VBUSY> to the Cache Manager that sent the latest RPC. In response, the
+Cache Manager retransmits the RPC after a delay. This argument prevents
+the accumulation of so many waiting RPCs that the File Server can never
+process them all. Provide a positive integer. The default value is
+C<600>.
-=item -rxpck
+=item B<-rxpck> <I<number of rx extra packets>>
Controls the number of Rx packets the File Server uses to store data for
-incoming RPCs that it is currently handling, that are waiting for a response,
-and for replies that are not yet complete. Provide a positive
+incoming RPCs that it is currently handling, that are waiting for a
+response, and for replies that are not yet complete. Provide a positive
integer.
-=item -rxdbg
+=item B<-rxdbg>
-Writes a trace of the File Server's operations on Rx packets to the
-file B</usr/afs/logs/rx_dbg>.
+Writes a trace of the File Server's operations on Rx packets to the file
+F</usr/afs/logs/rx_dbg>.
-=item -rxdbge
+=item F<-rxdbge>
Writes a trace of the File Server's operations on Rx events (such as
-retransmissions) to the file B</usr/afs/logs/rx_dbg>.
+retransmissions) to the file F</usr/afs/logs/rx_dbg>.
-=item -m
+=item F<-m> <I<min percentage spare in partition>>
Specifies the percentage of each AFS server partition that the AIX version
-of the File Server creates as a reserve. Specify an integer value
-between B<0> and B<30>; the default is 8%. A value
-of B<0> means that the partition can become completely full, which can
-have serious negative consequences.
+of the File Server creates as a reserve. Specify an integer value between
+C<0> and C<30>; the default is 8%. A value of C<0> means that the
+partition can become completely full, which can have serious negative
+consequences.
-=item -lock
+=item B<-lock>
-Prevents any portion of the fileserver binary from being paged
-(swapped) out of memory on a file server machine running the IRIX operating
-system.
+Prevents any portion of the fileserver binary from being paged (swapped)
+out of memory on a file server machine running the IRIX operating system.
-=item -L
->
+=item B<-L>
Sets values for many arguments in a manner suitable for a large file
-server machine. Combine this flag with any option except the
-B<-S> flag; omit both flags to set values suitable for a
-medium-sized file server machine.
+server machine. Combine this flag with any option except the B<-S> flag;
+omit both flags to set values suitable for a medium-sized file server
+machine.
-=item -S
->
+=item B<-S>
Sets values for many arguments in a manner suitable for a small file
-server machine. Combine this flag with any option except the
-B<-L> flag; omit both flags to set values suitable for a
-medium-sized file server machine.
+server machine. Combine this flag with any option except the B<-L> flag;
+omit both flags to set values suitable for a medium-sized file server
+machine.
-=item -k
+=item B<-k> <I<stack size>>
-Sets the LWP stack size in units of 1 kilobyte. Do not use this
-argument, and in particular do not specify a value less than the default of
-24.
+Sets the LWP stack size in units of 1 kilobyte. Do not use this argument,
+and in particular do not specify a value less than the default of C<24>.
-=item -realm
+=item B<-realm> <I<Kerberos realm name>>
Defines the Kerberos realm name for the File Server to use. If this
argument is not provided, it uses the realm name corresponding to the cell
-listed in the local B</usr/afs/etc/ThisCell> file.
+listed in the local F</usr/afs/etc/ThisCell> file.
-=item -udpsize
+=item B<-udpsize> <I<size of socket buffer in bytes>>
-Sets the size of the UDP buffer, which is 64 KB by default. Provide
-a positive integer, preferably larger than the default.
+Sets the size of the UDP buffer, which is 64 KB by default. Provide a
+positive integer, preferably larger than the default.
-=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,
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 following B<bos create> command creates an fs
-process on the file server machine B<fs2.abc.com> that
-uses the large configuration size, and allows volumes to exceed their quota by
-10%. Type the command on a single line:
+The following B<bos create> command creates an fs process on the file
+server machine C<fs2.abc.com> that uses the large configuration size, and
+allows volumes to exceed their quota by 10%. Type the command on a single
+line:
- % bos create -server fs2.abc.com -instance fs -type fs \
+ % bos create -server fs2.abc.com -instance fs -type fs \
-cmd "/usr/afs/bin/fileserver -pctspare 10 \
-L" /usr/afs/bin/volserver /usr/afs/bin/salvager
=head1 PRIVILEGE REQUIRED
-The issuer must be logged in as the superuser root on a file
-server machine to issue the command at a command shell prompt. It is
-conventional instead to create and start the process by issuing the B<bos
-create> command.
+The issuer must be logged in as the superuser C<root> on a file server
+machine to issue the command at a command shell prompt. It is conventional
+instead to create and start the process by issuing the B<bos create>
+command.
=head1 SEE ALSO
-L<BosConfig(1)>,
-L<FileLog(1)>,
-L<bos_create(1)>,
-L<bos_getlog(1)>,
+L<BosConfig(5)>,
+L<FileLog(5)>,
+L<bos_create(8)>,
+L<bos_getlog(8)>,
L<fs_setacl(1)>,
-L<salvager(1)>,
-L<volserver(1)>
+L<salvager(8)>,
+L<volserver(8)>
=head1 COPYRIGHT
=head1 SYNOPSIS
-B<fms -tape> <I<tape special file>> [-help]
+B<fms> B<-tape> <I<tape special file>> [B<-help>]
-B<fms -t> <I<tape special file>> [-h]
+B<fms> B<-t> <I<tape special file>> [B<-h>]
=head1 DESCRIPTION
-The fms command determines the capacity of the tape currently in
-the tape device identified by the B<-tape> argument, along with the
-size of the filemark for the device. The filemark is also referred to
-as the device's end-of-file (EOF) marker, and can differ for each
-combination of tape and tape device.
+The B<fms> command determines the capacity of the tape currently in the
+tape device identified by the B<-tape> argument, along with the size of
+the filemark for the device. The filemark is also referred to as the
+device's end-of-file (EOF) marker, and can differ for each combination of
+tape and tape device.
As the Tape Coordinator writes a dump, it writes a filemark between the
-data included from each volume and also tracks the amount of space left before
-the end of the tape (EOT). For some tape devices, the filemark is large
-enough (multiple megabytes) that failure to consider it leads the Tape
-Coordinator significantly to overestimate the available space.
-
-The intended use of this command is to determine tape capacity and filemark
-size values that can be specified in a tape device's entry in the
-B</usr/afs/backup/tapeconfig> file. For certain types of tape
-drives, the Tape Coordinator operates more efficiently when the
-B<tapeconfig> file lists accurate values. For further
-discussion, see the I<IBM AFS Administration Guide> chapter on
-configuring the Backup System.
+data included from each volume and also tracks the amount of space left
+before the end of the tape (EOT). For some tape devices, the filemark is
+large enough (multiple megabytes) that failure to consider it leads the
+Tape Coordinator significantly to overestimate the available space.
+
+The intended use of this command is to determine tape capacity and
+filemark size values that can be specified in a tape device's entry in the
+F</usr/afs/backup/tapeconfig> file. For certain types of tape drives, the
+Tape Coordinator operates more efficiently when the F<tapeconfig> file
+lists accurate values. For further discussion, see the I<IBM AFS
+Administration Guide> chapter on configuring the Backup System.
Insert a tape in the drive before issuing this command.
Do not use this command on compressing tape devices in compression mode or
with tape devices that handle tapes of multigigabyte (or multiterabyte)
-capacity. It does not produce accurate results in those cases.
-For alternate suggestions on the values to record in the B<tapeconfig>
-file for compressing drives, see the I<IBM AFS Administration Guide>
-chapter on configuring the Backup System.
+capacity. It does not produce accurate results in those cases. For
+alternate suggestions on the values to record in the B<tapeconfig> file
+for compressing drives, see the I<IBM AFS Administration Guide> chapter on
+configuring the Backup System.
Running the command completely overwrites the tape, so use a blank one or
one that can be recycled.
-Because it writes filemarks to the complete length of the tape, the command
-can take from several hours to more than a day to complete.
+Because it writes filemarks to the complete length of the tape, the
+command can take from several hours to more than a day to complete.
=head1 OPTIONS
=over 4
-=item -tape
+=item B<-tape> <I<tape special file>>
Specifies the UNIX device name of the tape device for which to determine
filemark size and the capacity of the tape it currently contains. The
-format varies on different system types, but usually begins with
-B</dev>; an example is B</dev/sd0a>.
+format varies on different system types, but usually begins with F</dev>;
+an example is F</dev/sd0a>.
-=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 command generates output both on the standard output stream and in the
-B<fms.log> file that it creates in the current working
-directory. The output reports the capacity of the tape in the device
-and the device's filemark size.
+F<fms.log> file that it creates in the current working directory. The
+output reports the capacity of the tape in the device and the device's
+filemark size.
The first few lines of output include status information about the
-execution of the command, including such information as the number of blocks
-and the number of file marks written to the tape by the command. The
-last two lines of both screen and file output provide the following
-information:
+execution of the command, including such information as the number of
+blocks and the number of file marks written to the tape by the
+command. The last two lines of both screen and file output provide the
+following information:
=over 4
=item *
-C<Tape capacity is> I<number> C<bytes>:
-specifies the size, in bytes, of the tape in the device.
-
+C<Tape capacity is I<number> bytes>: specifies the size, in bytes, of the
+tape in the device.
=item *
-C<File marks are> I<number> C<bytes>:
-specifies the device's filemark size in bytes.
-
+C<File marks are I<number> bytes>: specifies the device's filemark size in
+bytes.
=back
-The following message indicates that the fms command interpreter
-cannot access the tape device. The command halts.
+The following message indicates that the fms command interpreter cannot
+access the tape device. The command halts.
Can't open tape drive I<device>
The following message indicates that the command interpreter cannot create
-the B<fms.log> log file. Again, the command
-halts.
+the F<fms.log> log file. Again, the command halts.
Can't open log file
=head1 EXAMPLES
The following command illustrates the output for the device called
-B</dev/rmt1h>:
+F</dev/rmt1h>:
% fms /dev/rmt1h
wrote block: 130408
Tape capacity is 2136604672 bytes
File marks are 1910205 bytes
-The following appears in the fms.log file:
+The following appears in the F<fms.log> file:
fms test started
wrote 9230 blocks
=head1 PRIVILEGE REQUIRED
The issuer must be able to insert and write to files in the currently
-working directory, if the B<fms.log> file does not already
-exist. If it already exists, the issuer need only be able to write to
-it.
+working directory, if the F<fms.log> file does not already exist. If it
+already exists, the issuer need only be able to write to it.
=head1 SEE ALSO
-L<fms.log(1)>,
-L<tapeconfig(1)>
+L<fms.log(5)>,
+L<tapeconfig(5)>
=head1 COPYRIGHT
=head1 DESCRIPTION
-The commands in the fstrace command suite are the interface that
-system administrators employ to trace Cache Manager operations for debugging
-purposes. Examples of Cache Manager operations are fetching file data
-or the status information used to produce output for the UNIX B<ls>
-command.
-
-The fstrace command interpreter defines an extensive set of
-Cache Manager operations as the B<cm> I<event set>.
-When the event set is activated, the Cache Manager writes a message to the
-B<cmfx> I<trace log> in kernel memory each time it performs
-one of the defined operations. The log expands only to a defined size
-(by default, 60 KB), after which it is overwritten in a circular fashion (new
-trace messages overwrite the oldest ones). If an operation of
-particular interest occurs, the administrator can afterward display the log on
-the standard output stream or write it to a file for later study. For
-more specific procedural instructions, see the I<IBM AFS Administration
-Guide>.
-
-There are several categories of commands in the fstrace command
-suite:
+The commands in the B<fstrace> command suite are the interface that system
+administrators employ to trace Cache Manager operations for debugging
+purposes. Examples of Cache Manager operations are fetching file data or
+the status information used to produce output for the UNIX B<ls> command.
+
+The B<fstrace> command interpreter defines an extensive set of Cache
+Manager operations as the C<cm> I<event set>. When the event set is
+activated, the Cache Manager writes a message to the C<cmfx> I<trace log>
+in kernel memory each time it performs one of the defined operations. The
+log expands only to a defined size (by default, 60 KB), after which it is
+overwritten in a circular fashion (new trace messages overwrite the oldest
+ones). If an operation of particular interest occurs, the administrator
+can afterward display the log on the standard output stream or write it to
+a file for later study. For more specific procedural instructions, see the
+I<IBM AFS Administration Guide>.
+
+There are several categories of commands in the B<fstrace> command suite:
=over 4
=item *
-Commands to administer or display information about the trace log:
-
-
-B<fstrace clear>, B<fstrace lslog>, fstrace
-setlog
+Commands to administer or display information about the trace log:
+B<fstrace clear>, B<fstrace lslog>, B<fstrace setlog>.
=item *
-Commands to set or display the status of the event set:
-
-
-B<fstrace lsset> and fstrace setset
+Commands to set or display the status of the event set: B<fstrace lsset>
+and B<fstrace setset>.
=item *
-A command to display the contents of the trace log: fstrace
-dump
-
+A command to display the contents of the trace log: B<fstrace dump>.
=item *
-Commands to obtain help: B<fstrace apropos> and fstrace
-help
-
+Commands to obtain help: B<fstrace apropos> and B<fstrace help>.
=back
=head1 OPTIONS
-All fstrace commands accept the following optional flag.
-It is listed in the command descriptions and described in detail here:
-L<(1)>
+All B<fstrace> commands accept the following optional flag. It is listed
+in the command descriptions and described in detail here:
=over 4
-=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.
=back
=head1 PRIVILEGE REQUIRED
-To issue most fstrace commands, the issuer must be logged on as
-the local superuser B<root> on the machine that is generating the
-trace log.
+To issue most B<fstrace> commands, the issuer must be logged on as the
+local superuser C<root> on the machine that is generating the trace log.
=head1 SEE ALSO
-L<fstrace_apropos(1)>,
-L<fstrace_clear(1)>,
-L<fstrace_dump(1)>,
-L<fstrace_help(1)>,
-L<fstrace_lslog(1)>,
-L<fstrace_lsset(1)>,
-L<fstrace_setlog(1)>,
-L<fstrace_setset(1)>
+L<fstrace_apropos(8)>,
+L<fstrace_clear(8)>,
+L<fstrace_dump(8)>,
+L<fstrace_help(8)>,
+L<fstrace_lslog(8)>,
+L<fstrace_lsset(8)>,
+L<fstrace_setlog(8)>,
+L<fstrace_setset(8)>
=head1 COPYRIGHT
=head1 SYNOPSIS
-B<fstrace apropos -topic> <I<help string>> [-help]
+B<fstrace apropos> B<-topic> <I<help string>> [B<-help>]
-B<fstrace ap -t> <I<help string>> [-h]
+B<fstrace ap> B<-t> <I<help string>> [B<-h>]
=head1 DESCRIPTION
-The fstrace apropos command displays the first line of the
-online help entry for any B<fstrace> command that contains in its name
-or short description the string specified with the B<-topic>
-argument.
+The B<fstrace apropos> command displays the first line of the online help
+entry for any B<fstrace> command that contains in its name or short
+description the string specified with the B<-topic> argument.
-To display a command's complete syntax, use the fstrace
-help command.
+To display a command's complete syntax, use the B<fstrace 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 ("")
+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
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<fstrace> command where the string specified with the
-B<-topic> argument is part of the command name or first line.
+B<fstrace> command where the string specified with the B<-topic> argument
+is part of the command name or first line.
=head1 EXAMPLES
-The following command lists all fstrace commands that include
-the word B<set> in their names or short descriptions:
+The following command lists all B<fstrace> commands that include the word
+C<set> in their names or short descriptions:
% fstrace apropos set
clear: clear logs by logname or by event set
=head1 SEE ALSO
-L<fstrace(1)>,
-L<fstrace_help(1)>
+L<fstrace(8)>,
+L<fstrace_help(8)>
=head1 COPYRIGHT
=head1 SYNOPSIS
-B<fstrace clear> [B<-set> <I<set_name>>+] [B<-log> <I<log_name>>+] [-help]
+B<fstrace clear> [B<-set> <I<set name>>+] [B<-log> <I<log name>>+]
+ [B<-help>]
-B<fstrace c> [B<-s> <I<set_name>>+] [B<-l> <I<log_name>>+] [-h]
+B<fstrace c> [B<-s> <I<set name>>+] [B<-l> <I<log name>>+] [B<-h>]
=head1 DESCRIPTION
-The fstrace clear command erases the contents of the trace log
-from kernel memory, but leaves kernel memory allocated for the log.
+The B<fstrace clear> command erases the contents of the trace log from
+kernel memory, but leaves kernel memory allocated for the log.
=head1 OPTIONS
=over 4
-=item -set
+=item B<-set> <I<set name>>+
-Names the event set for which to clear the associated trace log.
-The only acceptable value is B<cm> (for which the associated trace log
-is B<cmfx>). Provide either this argument or the
-B<-log> argument, or omit both to clear the B<cmfx> log by
-default.
+Names the event set for which to clear the associated trace log. The only
+acceptable value is C<cm> (for which the associated trace log is
+C<cmfx>). Provide either this argument or the B<-log> argument, or omit
+both to clear the C<cmfx> log by default.
-=item -log
+=item B<-log> <I<log name>>+
Names the trace log to clear. The only acceptable value is
-B<cmfx>. Provide either this argument or the B<-set>
-argument, or omit both to clear the B<cmfx> log by default.
+C<cmfx>. Provide either this argument or the B<-set> argument, or omit
+both to clear the C<cmfx> log by default.
-=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 clears the cmfx trace log on the local
-machine:
+The following command clears the C<cmfx> trace log on the local machine:
# fstrace clear
=head1 PRIVILEGE REQUIRED
-The issuer must be logged in as the local superuser root.
+The issuer must be logged in as the local superuser C<root>.
=head1 SEE ALSO
-L<fstrace(1)>,
-L<fstrace_lslog(1)>,
-L<fstrace_lsset(1)>
+L<fstrace(8)>,
+L<fstrace_lslog(8)>,
+L<fstrace_lsset(8)>
=head1 COPYRIGHT
=head1 SYNOPSIS
-B<fstrace dump> [B<-set> <I<set_name>>+] [-follow <I<log_name>>]
-[B<-file> <I<output_filename>>]
- [B<-sleep> <I<seconds_between_reads>>] [-help]
+B<fstrace dump> [B<-set> <I<set name>>+] [B<-follow> <I<log name>>]
+ [B<-file> <I<output filename>>] [B<-sleep> <I<seconds between reads>>]
+ [B<-help>]
-B<fstrace d> [B<-se> <I<set_name>>+] [B<-fo> <I<log_name>>] [-fi <I<output_filename>>]
-[B<-sl> <I<seconds_between_reads>>] [B<-h>]
+B<fstrace d> [B<-se> <I<set name>>+] [B<-fo> <I<log name>>]
+ [B<-fi> <I<output filename>>] [B<-sl> <I<seconds between reads>>]
+ [B<-h>]
=head1 DESCRIPTION
-The fstrace dump command displays the current contents of the
-B<cmfx> trace log on the standard output stream or writes it to the
-file named by the B<-file> argument.
+The B<fstrace dump> command displays the current contents of the C<cmfx>
+trace log on the standard output stream or writes it to the file named by
+the B<-file> argument.
To write the log continuously to the standard output stream or to a file,
-use the B<-follow> argument. By default, the log's
-contents are written out every ten seconds and then automatically
-cleared. To change the interval between writes, use the
-B<-sleep> argument.
+use the B<-follow> argument. By default, the log's contents are written
+out every ten seconds and then automatically cleared. To change the
+interval between writes, use the B<-sleep> argument.
=head1 CAUTIONS
-This command produces output only if the cm event set is
-active. To display or set the event set's state, use the
-B<fstrace lsset> or B<fstrace setset> command
-respectively.
+This command produces output only if the C<cm> event set is active. To
+display or set the event set's state, use the B<fstrace lsset> or
+B<fstrace setset> command respectively.
To make the output from this command maximally readable, the message
-catalog file called B<afszcm.cat> must reside in the local
-B</usr/vice/etc/C> directory. If necessary, copy the file to
-that directory from the AFS Binary Distribution before activating
-tracing.
-
-When the cm event set is active, a defined amount of kernel
-memory (by default, 60 KB) is allocated for the B<cmfx> trace
-log. As described on the introductory B<fstrace> reference
-page, when the buffer is full, messages are overwritten in a circular fashion
-(new messages overwrite the oldest ones). To allocate more kernel
-memory for the log, use the B<fstrace setlog> command; to display
-the log buffer's current size, use the B<fstrace lslog> command
+catalog file called F<afszcm.cat> must reside in the local
+F</usr/vice/etc/C> directory. If necessary, copy the file to that
+directory from the AFS Binary Distribution before activating tracing.
+
+When the C<cm> event set is active, a defined amount of kernel memory (by
+default, 60 KB) is allocated for the C<cmfx> trace log. As described in
+L<fstrace(8)>, when the buffer is full, messages are overwritten in a
+circular fashion (new messages overwrite the oldest ones). To allocate
+more kernel memory for the log, use the B<fstrace setlog> command; to
+display the log buffer's current size, use the B<fstrace lslog> command
with the B<-long> argument.
=head1 OPTIONS
=over 4
-=item -set
+=item B<-set> <I<set name>>+
-Names the event set for which to write out the associated trace
-log. The only acceptable value is B<cm> (for which the
-associated trace log is B<cmfx>). Provide either this argument
-or the B<-log> argument, or omit both to write out the B<cmfx>
-log by default.
+Names the event set for which to write out the associated trace log. The
+only acceptable value is C<cm> (for which the associated trace log is
+C<cmfx>). Provide either this argument or the B<-log> argument, or omit
+both to write out the C<cmfx> log by default.
-=item -follow
+=item B<-follow> <I<log name>>
Names the trace log to write out continuously at a specified interval (by
-default, every ten seconds; use the B<-sleep> argument to change
-the interval). The log is cleared after each write operation.
+default, every ten seconds; use the B<-sleep> argument to change the
+interval). The log is cleared after each write operation.
-The only acceptable value is cmfx. Provide either this
-argument or the B<-set> argument, or omit both to write out the
-B<cmfx> log by default.
+The only acceptable value is C<cmfx>. Provide either this argument or the
+B<-set> argument, or omit both to write out the C<cmfx> log by default.
-=item -file
+=item B<-file> <I<output filename>>
Specifies the pathname of the file to which to write the trace log's
-contents. It can be in AFS or on the local disk. Partial
-pathnames are interpreted relative to the current working directory. If
-this argument is omitted, the trace log appears on the standard output
-stream.
+contents. It can be in AFS or on the local disk. Partial pathnames are
+interpreted relative to the current working directory. If this argument is
+omitted, the trace log appears on the standard output stream.
-=item -sleep
+=item B<-sleep> <I<seconds between reads>>
-Sets the number of seconds between writes of the trace log's contents
-when it is dumped continuously. Provide the B<-follow> argument
-along with this one. If this argument is omitted, the default interval
-is ten seconds.
+Sets the number of seconds between writes of the trace log's contents when
+it is dumped continuously. Provide the B<-follow> argument along with this
+one. If this argument is omitted, the default interval is ten seconds.
-=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 begins with a header specifying the date and time at which the
-write operation began. If the B<-follow> argument is not
-included, the header also reports the number of logs being dumped; it is
-always C<1>, since there is only the B<cmfx> trace log.
-The format of the header is as follows:
+write operation began. If the B<-follow> argument is not included, the
+header also reports the number of logs being dumped; it is always C<1>,
+since there is only the C<cmfx> trace log. The format of the header is as
+follows:
AFS Trace Dump -
Date: I<starting_timestamp>
Each subsequent message describes a Cache Manager operation in the
following format:
- time I<timestamp>, pid I<pid>:I<event_message>
+ time <timestamp>, pid <pid>:<event_message>
where
=over 4
-=item I<timestamp
->
+=item <timestamp>
Specifies the time at which the Cache Manager performed the operation, as
-the number of seconds since the dump began
+the number of seconds since the dump began.
-=item I<pid
->
+=item <pid>
Specifies the process ID of the process or thread associated with the
-message
+message.
-=item I<event_message
->
+=item <event_message>
-Is the message itself. They are generally meaningful only to
-someone familiar with the AFS source code.
+Is the message itself. They are generally meaningful only to someone
+familiar with the AFS source code.
=back
-In addition, every 1024 seconds the fstrace command interpreter
-writes a message that records the current clock time, in the following
-format:
+In addition, every 1024 seconds the fstrace command interpreter writes a
+message that records the current clock time, in the following format:
- time I<timestamp>, pid I<pid>: Current time: I<unix_time>
+ time <timestamp>, pid <pid>: Current time: <unix_time>
where
=over 4
-=item I<timestamp
->
+=item <timestamp>
-Is the number of seconds from the start of trace logging
+Is the number of seconds from the start of trace logging.
-=item I<pid
->
+=item <pid>
-Is the process ID number
+Is the process ID number.
-=item I<unix_time
->
+=item <unix_time>
-Is the machine's clock time, represent in the standard UNIX time
-format as the number of seconds since midnight on January 1, 1970.
+Is the machine's clock time, represent in the standard UNIX time format as
+the number of seconds since midnight on January 1, 1970.
=back
Use this message to determine the actual clock time associated with each
log message. Determine the actual time as follows:
+=over 4
+
=item *
Locate the message of interest.
-
=item *
Search backward through the trace file for the closest current time
message.
-
=item *
-If the current time message's I<timestamp> is smaller than the
-log message's I<timestamp>, subtract former from the latter.
-If the current time message's I<timestamp> is larger than the log
-message's I<timestamp>, add 1024 to the latter and subtract the
-former from the result.
-
+If the current time message's timestamp is smaller than the log message's
+timestamp, subtract former from the latter. If the current time message's
+timestamp is larger than the log message's timestamp, add 1024 to the
+latter and subtract the former from the result.
=item *
-Add the resulting number to the current time message's
-I<unix_time> to determine the log message's actual time.
-
+Add the resulting number to the current time message's <unix_time> to
+determine the log message's actual time.
If any of the data in the kernel trace buffer has been overwritten since
-tracing was activated, the following message appears at the appropriate place
-in the output:
+tracing was activated, the following message appears at the appropriate
+place in the output:
Log wrapped; data missing.
-To reduce the likelihood of overwriting, use the fstrace setlog
-command to increase the kernel buffer's size. To display the
-current defined buffer size, use the B<fstrace lslog> command with the
-B<-long> argument.
+To reduce the likelihood of overwriting, use the B<fstrace setlog> command
+to increase the kernel buffer's size. To display the current defined
+buffer size, use the B<fstrace lslog> command with the B<-long> argument.
The following message at the end of the log dump indicates that it is
completed:
=head1 EXAMPLES
-The following command dumps the log associated with the cm event
-set to the standard output stream.
+The following command dumps the log associated with the cm event set to
+the standard output stream.
# fstrace dump -set cm
AFS Trace Dump -
time 71.464989, pid 38267: Gn_open vp 0x5bbd000 flags 0x0 (returns 0x0)
AFS Trace Dump - Completed
-The following command dumps the trace log associated with the cm
-event set on the local machine to the file
-B<cmfx.dump.file.1>, using the default interval
-of 10 seconds between successive dumps:
+The following command dumps the trace log associated with the cm event set
+on the local machine to the file C<cmfx.dump.file.1>, using the default
+interval of 10 seconds between successive dumps:
# fstrace dump -follow cmfx -file cmfx.dump.file.1
=head1 PRIVILEGE REQUIRED
-The issuer must be logged in as the local superuser root.
+The issuer must be logged in as the local superuser C<root>.
=head1 SEE ALSO
-L<afszcm.cat(1)>,
-L<fstrace(1)>,
-L<fstrace_lslog(1)>,
-L<fstrace_setlog(1)>,
-L<fstrace_lsset(1)>
+L<afszcm.cat(5)>,
+L<fstrace(8)>,
+L<fstrace_lslog(8)>,
+L<fstrace_setlog(8)>,
+L<fstrace_lsset(8)>
=head1 COPYRIGHT
=head1 NAME
-fstrace help - Displays the syntax of specified fstrace commands or lists
-functional descriptions of all B<fstrace> commands
+fstrace help - Displays help for fstrace commands
=head1 SYNOPSIS
-B<fstrace help> [B<-topic> <I<help string>>+] [-help]
+B<fstrace help> [B<-topic> <I<help string>>+] [B<-help>]
-B<fstrace h> [B<-t> <I<help string>>+] [-h]
+B<fstrace h> [B<-t> <I<help string>>+] [B<-h>]
=head1 DESCRIPTION
-The fstrace help command displays the complete online help entry
-(short description and syntax statement) for each command 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<fstrace>
-command.
+The B<fstrace help> command displays the complete online help entry (short
+description and syntax statement) for each command 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<fstrace> command.
-To list every fstrace command whose name or short description
-includes a specified keyword, use the B<fstrace apropos>
-command.
+To list every fstrace command whose name or short description includes a
+specified keyword, use the B<fstrace 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<fstrace> part of the command name, providing
-only the operation code (for example, specify B<clear>, not
-B<fstrace clear>). If this argument is omitted, the output
-briefly describes every B<fstrace> command.
+entry. Omit the B<fstrace> part of the command name, providing only the
+operation code (for example, specify B<clear>, not B<fstrace clear>). If
+this argument is omitted, the output briefly describes every B<fstrace>
+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 fstrace command consists of two
-or three lines:
+The online help entry for each B<fstrace> command consists of 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 command displays the online help entry for the fstrace
-setset command:
+The following command displays the online help entry for the B<fstrace
+setset> command:
% fstrace help -topic setset
fstrace setset: set state of event sets
=head1 SEE ALSO
-L<fstrace(1)>,
-L<fstrace_apropos(1)>
+L<fstrace(8)>,
+L<fstrace_apropos(8)>
=head1 COPYRIGHT
=head1 SYNOPSIS
-B<fstrace lslog> [B<-set> <I<set_name>>+] [B<-log> <I<log_name>>] [B<-long>] [-help]
+B<fstrace lslog> [B<-set> <I<set name>>+] [B<-log> <I<log name>>]
+ [B<-long>] [B<-help>]
-B<fstrace lsl> [B<-s> <I<set_name>>+] [B<-log> <I<log_name>>] [B<-lon>] [-h]
+B<fstrace lsl> [B<-s> <I<set name>>+] [B<-log> <I<log name>>] [B<-lon>]
+ [B<-h>]
=head1 DESCRIPTION
-The B<fstrace lslog> command reports whether the cmfx
-log is available for use. If the B<-long> argument is included,
-the output reports the log's defined size, and whether that amount of
-space is currently allocated in kernel memory or not.
+The B<fstrace lslog> command reports whether the C<cmfx> log is available
+for use. If the B<-long> argument is included, the output reports the
+log's defined size, and whether that amount of space is currently
+allocated in kernel memory or not.
-To change the B<cmfx> trace log's size, use the fstrace
-setlog command. To display or set whether space is allocated for
-it in kernel memory, use the B<fstrace lsset> or B<fstrace
-setset> command to display or set the state of the corresponding
-B<cm> event set, respectively.
+To change the C<cmfx> trace log's size, use the B<fstrace setlog>
+command. To display or set whether space is allocated for it in kernel
+memory, use the B<fstrace lsset> or B<fstrace setset> command to display
+or set the state of the corresponding C<cm> event set, respectively.
=head1 OPTIONS
=over 4
-=item -set
+=item B<-set> <I<set name>>+
Names the event set for which to display information about the
-corresponding trace log. The only acceptable value is B<cm>
-(for which the associated trace log is B<cmfx>). Provide either
-this argument or the B<-log> argument, or omit both to display
-information about the B<cmfx> log by default.
+corresponding trace log. The only acceptable value is C<cm> (for which the
+associated trace log is C<cmfx>). Provide either this argument or the
+B<-log> argument, or omit both to display information about the C<cmfx>
+log by default.
-=item -log
+=item B<-log> <I<log name>>
-Names the trace log about which to report. The only acceptable
-value is B<cmfx>. Provide either this argument or the
-B<-set> argument, or omit both to report on the B<cmfx> log by
-default.
+Names the trace log about which to report. The only acceptable value is
+C<cmfx>. Provide either this argument or the B<-set> argument, or omit
+both to report on the C<cmfx> log by default.
-=item -long
+=item B<-long>
Reports the defined size of the log in kilobyte units and whether that
amount of space is currently allocated in kernel memory.
-=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
-By default, the fstrace lslog command displays only the name of
-the available log, B<cmfx>, in the following format:
+By default, the B<fstrace lslog> command displays only the name of the
+available log, C<cmfx>, in the following format:
Available logs:
cmfx
-When the -long flag is included, the output also reports the
-defined size of the log in kilobytes, and whether or not that amount of space
-is currently allocated in kernel memory, in the following format:
+When the B<-long> flag is included, the output also reports the defined
+size of the log in kilobytes, and whether or not that amount of space is
+currently allocated in kernel memory, in the following format:
Available logs:
- cmfx : I<log_size> kbytes (allocated | unallocated)
-
-The C<allocated> state indicates that the indicated number of
-kilobytes is reserved for the B<cmfx> trace log in kernel
-memory. The B<cm> event set's state is either
-C<active> or C<inactive>, as reported by the B<fstrace
-lsset> command, and set by the B<fstrace setset> command's
-B<-active> or B<-inactive> flags respectively.
-
-The C<unallocated> state indicates that no kernel memory is
-currently reserved for the B<cmfx> trace log. The B<cm>
-event set's state is C<dormant>, as reported by the B<fstrace
-lsset> command and set by the B<fstrace setset> command's
-B<-dormant> flag. If the event set's state is later
-changed to active or inactive, the number of kilobytes indicated as
-I<log_size> are again allocated in kernel memory.
+ cmfx : <log_size> kbytes (allocated | unallocated)
+
+The C<allocated> state indicates that the indicated number of kilobytes is
+reserved for the C<cmfx> trace log in kernel memory. The C<cm> event set's
+state is either C<active> or C<inactive>, as reported by the B<fstrace
+lsset> command, and set by the B<fstrace setset> command's B<-active> or
+B<-inactive> flags respectively.
+
+The C<unallocated> state indicates that no kernel memory is currently
+reserved for the C<cmfx> trace log. The B<cm> event set's state is
+C<dormant>, as reported by the B<fstrace lsset> command and set by the
+B<fstrace setset> command's B<-dormant> flag. If the event set's state is
+later changed to active or inactive, the number of kilobytes indicated as
+<log_size> are again allocated in kernel memory.
=head1 EXAMPLES
The following example uses the -long flag to display information
-about the B<cmfx> log:
+about the C<cmfx> log:
# fstrace lslog -log cmfx -long
Available logs:
=head1 PRIVILEGE REQUIRED
-The issuer must be logged in as the local superuser root.
+The issuer must be logged in as the local superuser C<root>.
=head1 SEE ALSO
-L<fstrace(1)>,
-L<fstrace_lsset(1)>,
-L<fstrace_setlog(1)>
+L<fstrace(8)>,
+L<fstrace_lsset(8)>,
+L<fstrace_setlog(8)>
=head1 COPYRIGHT
=head1 SYNOPSIS
-B<fstrace lsset> [B<-set> <I<set_name>>+] [-help]
+B<fstrace lsset> [B<-set> <I<set name>>+] [B<-help>]
-B<fstrace lss> [B<-s> <I<set_name>>+] [-h]
+B<fstrace lss> [B<-s> <I<set name>>+] [B<-h>]
=head1 DESCRIPTION
-The fstrace lsset command displays a list of the available event
-sets and reports their current status (active, inactive, or dormant).
+The B<fstrace lsset> command displays a list of the available event sets
+and reports their current status (active, inactive, or dormant).
-To change an event set's status, use the fstrace setset
-command.
+To change an event set's status, use the B<fstrace setset> command.
=head1 OPTIONS
=over 4
-=item -set
+=item B<-set> <I<set name>>+
-Names the event set for which to display the status. The only
-acceptable value is B<cm>, which is also the default if this argument
-is omitted.
+Names the event set for which to display the status. The only acceptable
+value is C<cm>, which is also the default if this argument is omitted.
-=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
following format:
Available sets:
- cm {active | inactive | dormant}
+ cm (active | inactive | dormant)
where
=over 4
-=item C<active
->
+=item active
Indicates that tracing is enabled for the event set, and kernel memory
allocated for the corresponding trace log.
-=item C<inactive
->
+=item inactive
Indicates that tracing is temporarily disabled for the event set, but
kernel memory still allocated for the corresponding trace log.
-=item C<dormant
->
+=item dormant
Indicates that tracing is disabled for the event set, and no kernel memory
allocated for the corresponding trace log.
=head1 EXAMPLES
-The following example displays the available event set and its
-status:
+The following example displays the available event set and its status:
# fstrace lsset
Available sets:
=head1 PRIVILEGE REQUIRED
-The issuer must be logged in as the local superuser root.
+The issuer must be logged in as the local superuser C<root>.
=head1 SEE ALSO
-L<fstrace(1)>,
-L<fstrace_setset(1)>
+L<fstrace(8)>,
+L<fstrace_setset(8)>
=head1 COPYRIGHT
=head1 SYNOPSIS
-B<fstrace setlog> [B<-log> <I<log_name>>+] B<-buffersize> <I<1-kilobyte_units>> [-help]
+B<fstrace setlog> [B<-log> <I<log name>>+]
+ B<-buffersize> <I<1-kilobyte units>> [B<-help>]
-B<fstrace setl> [B<-l> <I<log_name>>+] B<-b> <I<1-kilobyte_units>> [-h]
+B<fstrace setl> [B<-l> <I<log name>>+] B<-b> <I<1-kilobyte units>> [B<-h>]
-B<fstrace sl> [B<-l> <I<log_name>>+] B<-b> <I<1-kilobyte_units>> [-h]
+B<fstrace sl> [B<-l> <I<log name>>+] B<-b> <I<1-kilobyte units>> [B<-h>]
=head1 DESCRIPTION
-The fstrace setlog command defines the number of kilobytes of
-kernel memory allocated for the B<cmfx> trace log. If kernel
-memory is currently allocated, the command clears the current log and creates
-a new log buffer of the specified size.
+The B<fstrace setlog> command defines the number of kilobytes of kernel
+memory allocated for the C<cmfx> trace log. If kernel memory is currently
+allocated, the command clears the current log and creates a new log buffer
+of the specified size.
-To display the current defined size of the log buffer, issue the
-B<fstrace lslog> command with the B<-long> argument. To
-control whether the indicated amount of space is actually allocated, use the
-B<fstrace setset> command to set the status of the B<cm> event
-set; to display the event set's status, use the B<fstrace
-lsset> command.
+To display the current defined size of the log buffer, issue the B<fstrace
+lslog> command with the B<-long> argument. To control whether the
+indicated amount of space is actually allocated, use the B<fstrace setset>
+command to set the status of the C<cm> event set; to display the event
+set's status, use the B<fstrace lsset> command.
=head1 OPTIONS
=over 4
-=item -log
+=item B<-log> <I<log name>>+
Names trace log for which to set the size. The only acceptable
-value is B<cmfx>, which is also the default if this argument is
+value is C<cmfx>, which is also the default if this argument is
omitted.
-=item -buffersize
+=item B<-buffersize> <I<1-kilobyte units>>
Specifies the number of 1-kilobyte blocks of kernel memory to allocate for
the trace log.
-=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 allocated 80 KB of kernel memory for the
-B<cmfx> trace log:
+The following command allocated 80 KB of kernel memory for the C<cmfx>
+trace log:
# fstrace setlog -log cmfx -buffersize 80
=head1 PRIVILEGE REQUIRED
-The issuer must be logged in as the local superuser root.
+The issuer must be logged in as the local superuser C<root>.
=head1 SEE ALSO
-L<fstrace(1)>,
-L<fstrace_lslog(1)>,
-L<fstrace_lsset(1)>,
-L<fstrace_setset(1)>
+L<fstrace(8)>,
+L<fstrace_lslog(8)>,
+L<fstrace_lsset(8)>,
+L<fstrace_setset(8)>
=head1 COPYRIGHT
=head1 SYNOPSIS
-B<fstrace setset> [B<-set> <I<set_name>>+] [B<-active>] [B<-inactive>] [B<-dormant>] [-help]
+B<fstrace setset> [B<-set> <I<set name>>+] [B<-active>] [B<-inactive>]
+ [B<-dormant>] [B<-help>]
-B<fs set> [B<-s> <I<set_name>>+] [B<-a>] [B<-i>] [B<-d>] [-h]
+B<fs set> [B<-s> <I<set name>>+] [B<-a>] [B<-i>] [B<-d>] [B<-h>]
=head1 DESCRIPTION
-The B<fstrace setset> command sets the status of the cm
-kernel event set on the local machine, which determines whether trace messages
-are recorded in the log buffer in kernel memory.
+The B<fstrace setset> command sets the status of the C<cm> kernel event
+set on the local machine, which determines whether trace messages are
+recorded in the log buffer in kernel memory.
=head1 OPTIONS
=over 4
-=item -set
+=item B<-set> <I<set name>>+
-Names the event set for which to set the status. The only
-acceptable value B<cm>, which is also the default if this argument is
-omitted.
+Names the event set for which to set the status. The only acceptable value
+C<cm>, which is also the default if this argument is omitted.
-=item -active
+=item B<-active>
Enables tracing for the event set and allocates kernel memory for the
-associated trace log buffer. Provide one of this flag, the
-B<-inactive> flag, or the B<-dormant> flag.
+associated trace log buffer. Provide one of this flag, the B<-inactive>
+flag, or the B<-dormant> flag.
-=item -inactive
+=item B<-inactive>
Temporarily disables tracing for the event set, but does not change the
-allocation of kernel memory for the associated trace log buffer.
-Provide one of this flag, the B<-active> flag, or the
-B<-dormant> flag.
+allocation of kernel memory for the associated trace log buffer. Provide
+one of this flag, the B<-active> flag, or the B<-dormant> flag.
-=item -dormant
+=item B<-dormant>
Disables tracing for the event set and frees the kernel memory previously
-allocated for the associated trace log buffer. Provide one of this
-flag, the B<-active> flag, or the B<-inactive> flag.
+allocated for the associated trace log buffer. Provide one of this flag,
+the B<-active> flag, or the B<-inactive> flag.
-=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 sets the cm event set's status to
-B<inactive>:
+The following example sets the cm event set's status to inactive:
# fstrace setset -set cm -inactive
=head1 PRIVILEGE REQUIRED
-The issuer must be logged in as the local superuser root.
+The issuer must be logged in as the local superuser C<root>.
=head1 SEE ALSO
-L<fstrace(1)>,
-L<fstrace_lsset(1)>,
-L<fstrace_setlog(1)>
+L<fstrace(8)>,
+L<fstrace_lsset(8)>,
+L<fstrace_setlog(8)>
=head1 COPYRIGHT
=head1 SYNOPSIS
-B<kadb_check -database> <I<kadb_file>> [B<-uheader>] [B<-kheader>] [-entries]
-[B<-verbose>] [B<-rebuild> <I<out_file>>] [B<-help>]
+B<kadb_check> B<-database> <I<kadb file>> [B<-uheader>] [B<-kheader>]
+ [B<-entries>] [B<-verbose>] [B<-rebuild> <I<out file>>] [B<-help>]
-B<kadb_check -d> <I<kadb_file>> [B<-u>] [B<-k>] [B<-e>] [B<-v>] [B<-r> <I<out_file>>] [-h]
+B<kadb_check> B<-d> <I<kadb file>> [B<-u>] [B<-k>] [B<-e>] [B<-v>]
+ [B<-r> <I<out file>>] [B<-h>]
=head1 DESCRIPTION
-The kadb_check command checks the integrity of the Protection
-Database, reporting any errors or corruption it finds. If there are
-problems, do not issue any B<kas> commands until the database is
-repaired.
+The B<kadb_check> command checks the integrity of the Protection Database,
+reporting any errors or corruption it finds. If there are problems, do not
+issue any B<kas> commands until the database is repaired.
=head1 CAUTIONS
-The results can be unpredictable if the Authentication Server makes changes
-to the Authentication Database while this command is running. Use the
-B<bos shutdown> command to shutdown the local B<kaserver>
-process before running this command, or before creating a second copy of the
-B<kaserver.DB0> file (with a different name) on which to run
-the command.
+The results can be unpredictable if the Authentication Server makes
+changes to the Authentication Database while this command is running. Use
+the B<bos shutdown> command to shutdown the local B<kaserver> process
+before running this command, or before creating a second copy of the
+F<kaserver.DB0> file (with a different name) on which to run the command.
=head1 OPTIONS
=over 4
-=item -database
+=item B<-database> <I<kadb file>>
-Names the Authentication Database (copy of the
-B<kaserver.DB0> file) to check. If the current working
-directory is not the location of the file, provide a pathname, either full or
-relative to the current working directory.
+Names the Authentication Database (copy of the F<kaserver.DB0> file) to
+check. If the current working directory is not the location of the file,
+provide a pathname, either full or relative to the current working
+directory.
-=item -uheader
+=item B<-uheader>
-Displays information which Ubik maintains in the database's
-header.
+Displays information which Ubik maintains in the database's header.
-=item -kheader
+=item B<-kheader>
Displays information which the Authentication Server maintains in the
database's header.
-=item -entries
+=item B<-entries>
Outputs every entry in the database, providing information similar to that
returned by the B<kas examine> command.
-=item -verbose
+=item B<-verbose>
Reports additional information about the database, including the number of
free (allocated but unused) entries in the database.
-=item -rebuild
+=item B<-rebuild> <I<out file>>
-Names the file in which to record a list of kas commands which,
-if issued in the command shell, recreate the current state of the database
-being verified. Partial pathnames are interpreted relative to the
-current working directory.
+Names the file in which to record a list of B<kas> commands which, if
+issued in the command shell, recreate the current state of the database
+being verified. Partial pathnames are interpreted relative to the current
+working directory.
-=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 there are errors in the database, the output always reports them on the
-standard error stream. If any options other than B<-database>
-or B<-help> are provided, the output written to the standard output
-stream includes additional information as described for each option in the
-preceding B<Options> section of this reference page. The output
-is intended for debugging purposes and is meaningful to someone familiar with
-the internal structure of the Authentication Database.
+standard error stream. If any options other than B<-database> or B<-help>
+are provided, the output written to the standard output stream includes
+additional information as described for each option in L<OPTIONS>. The
+output is intended for debugging purposes and is meaningful to someone
+familiar with the internal structure of the Authentication Database.
=head1 PRIVILEGE REQUIRED
-The issuer must be logged in as the local superuser root.
+The issuer must be logged in as the local superuser C<root>.
=head1 SEE ALSO
-L<kaserver.DB0 and kaserver.DBSYS1(1)>
-
-L<bos_shutdown(1)>,
-L<kas_examine(1)>,
-L<kaserver(1)>
+L<kaserver.DB0(5)>,
+L<bos_shutdown(8)>,
+L<kas_examine(8)>,
+L<kaserver(8)>
=head1 COPYRIGHT
=head1 DESCRIPTION
-The commands in the kas command suite are the administrative
-interface to the Authentication Server, which runs on each database server
-machine in a cell, maintains the Authentication Database, and provides the
-authentication tickets that client applications must present to AFS servers in
-order to obtain access to AFS data and other services.
+The commands in the B<kas> command suite are the administrative interface
+to the Authentication Server, which runs on each database server machine
+in a cell, maintains the Authentication Database, and provides the
+authentication tickets that client applications must present to AFS
+servers in order to obtain access to AFS data and other services.
-There are several categories of commands in the kas command
-suite:
+There are several categories of commands in the B<kas> command suite:
=over 4
=item *
Commands to create, modify, examine and delete entries in the
-Authentication Database, including passwords: B<kas create>,
-B<kas delete>, B<kas examine>, B<kas list>, B<kas
-setfields>, B<kas setkey>, B<kas setpassword>, and
-B<kas unlock>
-
+Authentication Database, including passwords: B<kas create>, B<kas
+delete>, B<kas examine>, B<kas list>, B<kas setfields>, B<kas setkey>,
+B<kas setpassword>, and B<kas unlock>.
=item *
-Commands to create, delete, and examine tokens and server tickets:
-B<kas forgetticket>, B<kas listtickets>, B<kas
-noauthentication>, and B<kas stringtokey>
-
+Commands to create, delete, and examine tokens and server tickets: B<kas
+forgetticket>, B<kas listtickets>, B<kas noauthentication>, and B<kas
+stringtokey>.
=item *
-A command to enter interactive mode: kas interactive
-
+A command to enter interactive mode: B<kas interactive>.
=item *
-A command to trace Authentication Server operations: kas
-statistics
-
+A command to trace Authentication Server operations: B<kas statistics>.
=item *
-Commands to obtain help: B<kas apropos> and kas
-help
-
+Commands to obtain help: B<kas apropos> and B<kas help>.
=back
Because of the sensitivity of information in the Authentication Database,
the Authentication Server authenticates issuers of B<kas> commands
directly, rather than accepting the standard token generated by the Ticket
-Granting Service. Any B<kas> command that requires
-administrative privilege prompts the issuer for a password. The
-resulting ticket is valid for six hours unless the maximum ticket lifetime for
-the issuer or the Authentication Server's Ticket Granting Service is
-shorter.
-L<(1)>
-L<(1)>
-
-To avoid having to provide a password repeatedly when issuing a sequence of
-B<kas> commands, enter I<interactive mode> by issuing the
-B<kas interactive> command, typing B<kas> without any
-operation code, or typing B<kas> followed by a user and cell name,
-separated by an at-sign (B<@>; an example is B<kas
-smith.admin@abc.com>). After prompting once for a
+Granting Service. Any B<kas> command that requires administrative
+privilege prompts the issuer for a password. The resulting ticket is valid
+for six hours unless the maximum ticket lifetime for the issuer or the
+Authentication Server's Ticket Granting Service is shorter.
+
+To avoid having to provide a password repeatedly when issuing a sequence
+of B<kas> commands, enter I<interactive mode> by issuing the B<kas
+interactive> command, typing B<kas> without any operation code, or typing
+B<kas> followed by a user and cell name, separated by an at-sign (C<@>; an
+example is C<kas smith.admin@abc.com>). After prompting once for a
password, the Authentication Server accepts the resulting token for every
-command issued during the interactive session. See the reference page
-for the B<kas interactive> command for a discussion of when to use
-each method for entering interactive mode and of the effects of entering a
-session.
+command issued during the interactive session. See L<kas_interactive(8)>
+for a discussion of when to use each method for entering interactive mode
+and of the effects of entering a session.
The Authentication Server maintains two databases on the local disk of the
machine where it runs:
=item *
-The Authentication Database (/usr/afs/db/kaserver.DB0)
-stores the information used to provide AFS authentication services to users
-and servers, including the password scrambled as an encryption key. The
-reference page for the B<kas examine> command describes the
-information in a database entry.
-
+The Authentication Database (F</usr/afs/db/kaserver.DB0>) stores the
+information used to provide AFS authentication services to users and
+servers, including the password scrambled as an encryption key. The
+reference page for the B<kas examine> command describes the information in
+a database entry.
=item *
-An auxiliary file (/usr/afs/local/kaauxdb by default) that
-tracks how often the user has provided an incorrect password to the local
-Authentication Server. The reference page for the B<kas
-setfields> command describes how the Authentication Server uses this file
-to enforce the limit on consecutive authentication failures. To
-designate an alternate directory for the file, use the B<kaserver>
-command's B<-localfiles> argument.
-
+An auxiliary file (F</usr/afs/local/kaauxdb> by default) that tracks how
+often the user has provided an incorrect password to the local
+Authentication Server. The reference page for the B<kas setfields> command
+describes how the Authentication Server uses this file to enforce the
+limit on consecutive authentication failures. To designate an alternate
+directory for the file, use the B<kaserver> command's B<-localfiles>
+argument.
=back
=head1 OPTIONS
The following arguments and flags are available on many commands in the
-B<kas> suite. (Some of them are unavailable on commands entered
-in interactive mode, because the information they specify is established when
-entering interactive mode and cannot be changed except by leaving interactive
-mode.) The reference page for each command also lists them, but they
-are described here in greater detail.
+B<kas> suite. (Some of them are unavailable on commands entered in
+interactive mode, because the information they specify is established when
+entering interactive mode and cannot be changed except by leaving
+interactive mode.) The reference page for each command also lists them,
+but they are described here in greater detail.
=over 4
-=item L<(1)
-B<-admin_username>
->
+=item B<-admin_username> <I<user name>>
Specifies the user identity under which to authenticate with the
Authentication Server for execution of the command. If this argument is
-omitted, the B<kas> command interpreter requests authentication for
-the identity under which the issuer is logged onto the local machine.
-Do not combine this argument with the B<-noauth> flag.
-L<(1)>
+omitted, the B<kas> command interpreter requests authentication for the
+identity under which the issuer is logged onto the local machine. Do not
+combine this argument with the B<-noauth> flag.
-=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
-The -cell argument is not available on commands issued in
-interactive mode. The cell defined when the B<kas> 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<kas> 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)
-B<-noauth>
->
+=item B<-noauth>
Establishes an unauthenticated connection to the Authentication Server, in
which the Authentication Server treats the issuer as the unprivileged user
-B<anonymous>. It is useful only when authorization checking is
-disabled on the server machine (during the installation of a server machine or
-when the B<bos setauth> command has been used during other unusual
-circumstances). In normal circumstances, the Authentication Server
-allows only privileged users to issue most B<kas> commands, and
-refuses to perform such an action even if the B<-noauth> flag is
-provided. Do not combine this flag with the B<-admin_username>
-and B<-password_for_admin> arguments.
-
-=item L<(1)
-B<-password_for_admin>
->
-
-Specifies the password of the command's issuer. It is best to
-omit this argument, which echoes the password visibly in the command shell,
-instead enter the password at the prompt. Do not combine this argument
-with the B<-noauth> flag.
-
-=item L<(1)
-B<-servers>
->
+C<anonymous>. It is useful only when authorization checking is disabled on
+the server machine (during the installation of a server machine or when
+the B<bos setauth> command has been used during other unusual
+circumstances). In normal circumstances, the Authentication Server allows
+only privileged users to issue most B<kas> commands, and refuses to
+perform such an action even if the B<-noauth> flag is provided. Do not
+combine this flag with the B<-admin_username> and B<-password_for_admin>
+arguments.
+
+=item B<-password_for_admin> <I<password>>
+
+Specifies the password of the command's issuer. It is best to omit this
+argument, which echoes the password visibly in the command shell, instead
+enter the password at the prompt. Do not combine this argument with the
+B<-noauth> flag.
+
+=item B<-servers> <I<machine name>>+
Establishes a connection with the Authentication Server running on each
-specified database server machine, instead of on each machine listed in the
-local B</usr/vice/etc/CellServDB> file. In either case, the
-B<kas> command interpreter then chooses one of the machines at random
-to contact for execution of each subsequent command. The issuer can
-abbreviate the machine name to the shortest form that allows the local name
-service to identify it uniquely.
+specified database server machine, instead of on each machine listed in
+the local F</usr/vice/etc/CellServDB> file. In either case, the B<kas>
+command interpreter then chooses one of the machines at random to contact
+for execution of each subsequent command. The issuer can abbreviate the
+machine name to the shortest form that allows the local name service to
+identify it uniquely.
=back
=head1 PRIVILEGE REQUIRED
-To issue most kas commands, the issuer must have the
-C<ADMIN> flag set in his or her Authentication Database entry (use the
-B<kas setfields> command to turn the flag on).
+To issue most kas commands, the issuer must have the C<ADMIN> flag set in
+his or her Authentication Database entry (use the B<kas setfields> command
+to turn the flag on).
=head1 SEE ALSO
-L<CellServDB (client version)(1)>
-
-L<kaserver.DB0 and kaserver.DBSYS1(1)>
-
-L<kaserverauxdb(1)>,
-L<kas_apropos(1)>,
-L<kas_create(1)>,
-L<kas_delete(1)>,
-L<kas_examine(1)>,
-L<kas_forgetticket(1)>,
-L<kas_help(1)>,
-L<kas_interactive(1)>,
-L<kas_list(1)>,
-L<kas_listtickets(1)>,
-L<kas_noauthentication(1)>,
-L<kas_quit(1)>,
-L<kas_setfields(1)>,
-L<kas_setpassword(1)>,
-L<kas_statistics(1)>,
-L<kas_stringtokey(1)>,
-L<kas_unlock(1)>,
-L<kaserver(1)>
+L<CellServDB(5)>,
+L<kaserver.DB0(5)>,
+L<kaserverauxdb(5)>,
+L<kas_apropos(8)>,
+L<kas_create(8)>,
+L<kas_delete(8)>,
+L<kas_examine(8)>,
+L<kas_forgetticket(8)>,
+L<kas_help(8)>,
+L<kas_interactive(8)>,
+L<kas_list(8)>,
+L<kas_listtickets(8)>,
+L<kas_noauthentication(8)>,
+L<kas_quit(8)>,
+L<kas_setfields(8)>,
+L<kas_setpassword(8)>,
+L<kas_statistics(8)>,
+L<kas_stringtokey(8)>,
+L<kas_unlock(8)>,
+L<kaserver(8)>
=head1 COPYRIGHT
=head1 SYNOPSIS
-B<kas apropos -topic> <I<help string>> [-help]
+B<kas apropos> B<-topic> <I<help string>> [B<-help>]
-B<kas a -t> <I<help string>> [-h]
+B<kas a> B<-t> <I<help string>> [B<-h>]
=head1 DESCRIPTION
-The kas apropos command displays the first line of the online
-help entry for any B<kas> command that has the string specified by the
+The B<kas apropos> command displays the first line of the online help
+entry for any B<kas> command that has the string specified by the
B<-topic> argument in its name or short description.
-To display the syntax for a command, use the kas help
-command.
+To display the syntax for a command, use the B<kas 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 ("")
+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
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<kas> command where the string specified with the B<-topic>
-argument is part of the command name or first line.
+B<kas> command where the string specified with the B<-topic> argument is
+part of the command name or first line.
=head1 EXAMPLES
-The following command lists all kas commands that include the
-word B<key> in their names or short descriptions:
+The following command lists all B<kas> commands that include the word
+C<key> in their names or short descriptions:
% kas apropos key
setkey: set a user's key
=head1 SEE ALSO
-L<kas(1)>,
-L<kas_help(1)>
+L<kas(8)>,
+L<kas_help(8)>
=head1 COPYRIGHT
=head1 SYNOPSIS
-B<kas create -name> <I<name of user>> [-initial_password <I<initial password>>]
-[B<-admin_username> <I<admin principal to use for authentication>>]
- [B<-password_for_admin> <I<admin password>>] [-cell <I<cell name>>]
- [-servers <I<explicit list of authentication servers>>+]
- [B<-noauth>] [-help]
-
-B<kas c -na> <I<name of user>> [-i <I<initial password>>]
-[B<-a> <I<admin principal to use for authentication>>]
- [B<-p> <I<admin password>>] [-c <I<cell name>>]
- [B<-s> <I<explicit list of authentication servers>>+] [B<-no>] [-h]
+B<kas create> B<-name> <I<name of user>>
+ [B<-initial_password> <I<initial password>>]
+ [B<-admin_username> <I<admin principal to use for authentication>>]
+ [B<-password_for_admin> <I<admin password>>] [B<-cell> <I<cell name>>]
+ [B<-servers> <I<explicit list of authentication servers>>+]
+ [B<-noauth>] [B<-help>]
+
+B<kas c> B<-na> <I<name of user>> [B<-i> <I<initial password>>]
+ [B<-a> <I<admin principal to use for authentication>>]
+ [B<-p> <I<admin password>>] [B<-c> <I<cell name>>]
+ [B<-s> <I<explicit list of authentication servers>>+] [B<-no>] [B<-h>]
=head1 DESCRIPTION
-The kas create command creates an entry in the Authentication
-Database for the user named by the B<-name> argument.
+The B<kas create> command creates an entry in the Authentication Database
+for the user named by the B<-name> argument.
-To avoid having the account's initial password echo visibly at the
-shell prompt, omit the B<-initial_password> argument; the command
-interpreter prompts for the password and does not echo it visibly.
-Whether or not B<-initial_password> is omitted, the Authentication
-Server converts the password into a form suitable for use as an encryption
-key, and records it in the entry's key field.
+To avoid having the account's initial password echo visibly at the shell
+prompt, omit the B<-initial_password> argument; the command interpreter
+prompts for the password and does not echo it visibly. Whether or not
+B<-initial_password> is omitted, the Authentication Server converts the
+password into a form suitable for use as an encryption key, and records it
+in the entry's key field.
-To alter settings in an Authentication Database entry, use the kas
-setfields command. To examine an entry, use the B<kas
-examine> command. To list every entry in the database, use the
-B<kas list> command.
+To alter settings in an Authentication Database entry, use the B<kas
+setfields> command. To examine an entry, use the B<kas examine>
+command. To list every entry in the database, use the B<kas list> command.
=head1 OPTIONS
=over 4
-=item -name
+=item B<-name> <I<name of user>>
-Names the new Authentication Database entry. Because it is the name
-under which the user logs in, it must obey the restrictions that many
-operating systems impose on user names (usually, to contain no more than eight
+Names the new Authentication Database entry. Because it is the name under
+which the user logs in, it must obey the restrictions that many operating
+systems impose on user names (usually, to contain no more than eight
lowercase letters).
-=item -initial_password
+=item B<-initial_password> <I<initial password>>
-Sets the user's password; provide a character string that can
-include uppercase and lowercase letters, numerals and punctuation. The
-Authentication Server scrambles the string into an octal string suitable for
-use as an encryption key before placing it in the entry's key
+Sets the user's password; provide a character string that can include
+uppercase and lowercase letters, numerals and punctuation. The
+Authentication Server scrambles the string into an octal string suitable
+for use as an encryption key before placing it in the entry's key
field. If this argument is omitted, the command interpreter prompts for
the string and does not echo it visibly.
-=item -admin_username
+=item B<-admin_username> <I<admin principal>>
Specifies the user identity under which to authenticate with the
Authentication Server for execution of the command. For more details,
-see the introductory B<kas> reference page.
+see L<kas(8)>.
-=item -password_for_admin
+=item B<-password_for_admin> <I<admin password>>
-Specifies the password of the command's issuer. If it is
-omitted (as recommended), the B<kas> command interpreter prompts for
-it and does not echo it visibly. For more details, see the introductory
-B<kas> reference page.
+Specifies the password of the command's issuer. If it is omitted (as
+recommended), the B<kas> command interpreter prompts for it and does not
+echo it visibly. For more details, see L<kas(8)>.
-=item -cell
+=item B<-cell> <I<cell name>>
Names the cell in which to run the command. For more details, see
-the introductory B<kas> reference page.
+L<kas(8)>.
-=item -servers
+=item B<-servers> <I<authentication servers>>
Names each machine running an Authentication Server with which to
-establish a connection. For more details, see the introductory
-B<kas> reference page.
+establish a connection. For more details, see L<kas(8)>.
-=item -noauth
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. For more details, see the introductory B<kas> reference
-page.
+Assigns the unprivileged identity C<anonymous> to the issuer. For more
+details, see L<kas(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 the prompts that appear when an administrator
-logged in as B<admin> creates an Authentication Database entry for the
-user B<smith>, and does not include either the
-B<-initial_password> or B<-password_for_admin>
-arguments.
+logged in as C<admin> creates an Authentication Database entry for the
+user C<smith>, and does not include either the B<-initial_password> or
+B<-password_for_admin> arguments.
% kas create smith
Password for admin:
=head1 PRIVILEGE REQUIRED
-The issuer must have the C<ADMIN> flag set on his or her
-Authentication Database entry.
+The issuer must have the C<ADMIN> flag set on his or her Authentication
+Database entry.
=head1 SEE ALSO
-L<kas(1)>,
-L<kas_examine(1)>,
-L<kas_list(1)>,
-L<kas_setfields(1)>
+L<kas(8)>,
+L<kas_examine(8)>,
+L<kas_list(8)>,
+L<kas_setfields(8)>
=head1 COPYRIGHT
=head1 SYNOPSIS
-kas delete -name <I<name of user>>
-[B<-admin_username> <I<admin principal to use for authentication>>]
- [B<-password_for_admin> <I<admin password>>] [-cell <I<cell name>>]
- [-servers <I<explicit list of authentication servers>>+]
- [B<-noauth>] [-help]
-
-B<kas d -na> <I<name of user>> [-a <I<admin principal to use for authentication>>]
-[B<-p> <I<admin password>>] [B<-c> <I<cell name>>]
- [B<-s> <I<explicit list of authentication servers>>+] [B<-no>] [-h]
+B<kas delete> B<-name> <I<name of user>>
+ [B<-admin_username> <I<admin principal to use for authentication>>]
+ [B<-password_for_admin> <I<admin password>>] [B<-cell> <I<cell name>>]
+ [B<-servers> <I<explicit list of authentication servers>>+]
+ [B<-noauth>] [B<-help>]
+
+B<kas d> B<-na> <I<name of user>>
+ [B<-a> <I<admin principal to use for authentication>>]
+ [B<-p> <I<admin password>>] [B<-c> <I<cell name>>]
+ [B<-s> <I<explicit list of authentication servers>>+] [B<-no>] [B<-h>]
-B<kas rm -na> <I<name of user>> [-a <I<admin principal to use for authentication>>]
-[B<-p> <I<admin password>>] [B<-c> <I<cell name>>]
- [B<-s> <I<explicit list of authentication servers>>+] [B<-no>] [-h]
+B<kas rm> B<-na> <I<name of user>>
+ [B<-a> <I<admin principal to use for authentication>>]
+ [B<-p> <I<admin password>>] [B<-c> <I<cell name>>]
+ [B<-s> <I<explicit list of authentication servers>>+] [B<-no>] [B<-h>]
=head1 DESCRIPTION
-The kas delete command removes from the Authentication Database
-the user entry named by the B<-name> argument. The indicated
-user becomes unable to log in, or the indicated server becomes unreachable
-(because the Authentication Server's Ticket Granting Service module no
-longer has a key with which to seal tickets for the server).
+The B<kas delete> command removes from the Authentication Database the
+user entry named by the B<-name> argument. The indicated user becomes
+unable to log in, or the indicated server becomes unreachable (because the
+Authentication Server's Ticket Granting Service module no longer has a key
+with which to seal tickets for the server).
=head1 OPTIONS
=over 4
-=item -name
+=item B<-name> <I<name of user>>
Names the Authentication Database entry to delete.
-=item -admin_username
+=item B<-admin_username> <I<admin principal>>
Specifies the user identity under which to authenticate with the
-Authentication Server for execution of the command. For more details,
-see the introductory B<kas> reference page.
+Authentication Server for execution of the command. For more details, see
+L<kas(8)>.
-=item -password_for_admin
+=item B<-password_for_admin> <I<admin password>>
-Specifies the password of the command's issuer. If it is
-omitted (as recommended), the B<kas> command interpreter prompts for
-it and does not echo it visibly. For more details, see the introductory
-B<kas> reference page.
+Specifies the password of the command's issuer. If it is omitted (as
+recommended), the B<kas> command interpreter prompts for it and does not
+echo it visibly. For more details, see L<kas(8)>.
-=item -cell
+=item B<-cell> <I<cell name>>
Names the cell in which to run the command. For more details, see
-the introductory B<kas> reference page.
+L<kas(8)>.
-=item -servers
+=item B<-servers> <I<authentication servers>>+
Names each machine running an Authentication Server with which to
-establish a connection. For more details, see the introductory
-B<kas> reference page.
+establish a connection. For more details, see L<kas(8)>.
-=item -noauth
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. For more details, see the introductory B<kas> reference
-page.
+Assigns the unprivileged identity C<anonymous> to the issuer. For more
+details, see L<kas(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 the administrative user admin
-entering interactive mode to delete three accounts.
+The following example shows the administrative user C<admin> entering
+interactive mode to delete three accounts.
% kas
Password for admin:
=head1 PRIVILEGE REQUIRED
-The issuer must have the C<ADMIN> flag set on his or her
-Authentication Database entry.
+The issuer must have the C<ADMIN> flag set on his or her Authentication
+Database entry.
=head1 SEE ALSO
-L<kas(1)>,
-L<kas_create(1)>
+L<kas(8)>,
+L<kas_create(8)>
=head1 COPYRIGHT
=head1 SYNOPSIS
-B<kas examine -name> <I<name of user>> [-showkey]
-[B<-admin_username> <I<admin principal to use for authentication>>]
- [B<-password_for_admin> <I<admin password>>] [-cell <I<cell name>>]
- [-servers <I<explicit list of authentication servers>>+]
- [B<-noauth>] [-help]
+B<kas examine> B<-name> <I<name of user>> [B<-showkey>]
+
[B<-admin_username> <I<admin principal to use for authentication>>]
+ [B<-password_for_admin> <I<admin password>>] [B<-cell> <I<cell name>>]
+ [B<-servers> <I<explicit list of authentication servers>>+]
+ [B<-noauth>] [B<-help>]
-B<kas e -na> <I<name of user>> [-sh]
-[B<-a> <I<admin principal to use for authentication>>]
- [B<-p> <I<admin password>>] [-c <I<cell name>>]
- [B<-se> <I<explicit list of authentication servers>>+] [B<-no>] [-h]
+B<kas e> B<-na> <I<name of user>> [B<-sh>]
+
[B<-a> <I<admin principal to use for authentication>>]
+ [B<-p> <I<admin password>>] [B<-c> <I<cell name>>]
+ [B<-se> <I<explicit list of authentication servers>>+] [B<-no>] [B<-h>]
=head1 DESCRIPTION
-The kas examine command formats and displays information from
-the Authentication Database entry of the user named by the B<-name>
-argument.
+The B<kas examine> command formats and displays information from the
+Authentication Database entry of the user named by the B<-name> argument.
-To alter the settings displayed with this command, issue the kas
-setfields command.
+To alter the settings displayed with this command, issue the B<kas
+setfields> command.
=head1 CAUTIONS
Displaying actual keys on the standard output stream by including the
-B<-showkey> flag constitutes a security exposure. For most
-purposes, it is sufficient to display a checksum.
+B<-showkey> flag constitutes a security exposure. For most purposes, it is
+sufficient to display a checksum.
=head1 OPTIONS
=over 4
-=item -name
+=item B<-name> <I<name of user>>
-Names the Authentication Database entry from which to display
-information.
+Names the Authentication Database entry from which to display information.
-=item -showkey
->
+=item B<-showkey>
-Displays the octal digits that constitute the key. The issuer must
-have the C<ADMIN> flag on his or her Authentication Database
-entry.
+Displays the octal digits that constitute the key. The issuer must have
+the C<ADMIN> flag on his or her Authentication Database entry.
-=item -admin_username
+=item B<-admin_username> <I<admin principal>>
Specifies the user identity under which to authenticate with the
-Authentication Server for execution of the command. For more details,
-see the introductory B<kas> reference page.
+Authentication Server for execution of the command. For more details, see
+L<kas(8)>.
-=item -password_for_admin
+=item B<-password_for_admin> <I<admin password>>
-Specifies the password of the command's issuer. If it is
-omitted (as recommended), the B<kas> command interpreter prompts for
-it and does not echo it visibly. For more details, see the introductory
-B<kas> reference page.
+Specifies the password of the command's issuer. If it is omitted (as
+recommended), the B<kas> command interpreter prompts for it and does not
+echo it visibly. For more details, see L<kas(8)>.
-=item -cell
+=item B<-cell> <I<cell name>>
Names the cell in which to run the command. For more details, see
-the introductory B<kas> reference page.
+L<kas(8)>.
-=item -servers
+=item B<-servers> <I<authentication servers>>+
Names each machine running an Authentication Server with which to
-establish a connection. For more details, see the introductory
-B<kas> reference page.
+establish a connection. For more details, see L<kas(8)>.
-=item -noauth
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. For more details, see the introductory B<kas> reference
-page.
+Assigns the unprivileged identity C<anonymous> to the issuer. For more
+details, see L<kas(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
The entry name, following the string C<User data for>.
-
=item *
One or more status flags in parentheses; they appear only if an
-administrator has used the B<kas setfields> command to change them
-from their default values. A plus sign (C<+>) separates the
-flags if there is more than one. The nondefault values that can appear,
-and their meanings, are as follows:
-
+administrator has used the B<kas setfields> command to change them from
+their default values. A plus sign (C<+>) separates the flags if there is
+more than one. The nondefault values that can appear, and their meanings,
+are as follows:
=over 4
-=item C<ADMIN
->
+=item ADMIN
-Enables the user to issue privileged kas commands (default is
-C<NOADMIN>)
+Enables the user to issue privileged B<kas> commands (default is
+C<NOADMIN>).
-=item C<NOTGS
->
+=item NOTGS
-Prevents the user from obtaining tickets from the Authentication
-Server's Ticket Granting Service (default is C<TGS>)
+Prevents the user from obtaining tickets from the Authentication Server's
+Ticket Granting Service (default is C<TGS>).
-=item C<NOSEAL
->
+=item NOSEAL
-Prevents the Ticket Granting Service from using the entry's key field
-as an encryption key (default is C<SEAL>)
+Prevents the Ticket Granting Service from using the entry's key field as
+an encryption key (default is C<SEAL>).
-=item C<NOCPW
->
+=item NOCPW
-Prevents the user from changing his or her password (default is
-C<CPW>)
+Prevents the user from changing his or her password (default is C<CPW>).
=back
=item *
-The key version number, in parentheses, following the word C<key>,
-then one of the following.
-
+The key version number, in parentheses, following the word C<key>, then
+one of the following.
=over 4
=item *
-A checksum equivalent of the key, following the string C<cksum
-is>, if the B<-showkey> flag is not included. The checksum
-is a decimal number derived by encrypting a constant with the key. In
-the case of the B<afs>> entry, this number must match the
-checksum with the corresponding key version number in the output of the
-B<bos listkeys> command; if not, follow the instructions in the
-I<IBM AFS Administration Guide> for creating a new server encryption
-key.
-
+A checksum equivalent of the key, following the string C<cksum is>, if the
+B<-showkey> flag is not included. The checksum is a decimal number derived
+by encrypting a constant with the key. In the case of the C<afs> entry,
+this number must match the checksum with the corresponding key version
+number in the output of the B<bos listkeys> command; if not, follow the
+instructions in the I<IBM AFS Administration Guide> for creating a new
+server encryption key.
=item *
-The actual key, following a colon, if the -showkey flag is
-included. The key consists of eight octal numbers, each represented as
-a backslash followed by three decimal digits.
-
+The actual key, following a colon, if the B<-showkey> flag is
+included. The key consists of eight octal numbers, each represented as a
+backslash followed by three decimal digits.
=back
=item *
The date the user last changed his or her own password, following the
-string C<last cpw> (which stands for "last change of
-password").
-
+string C<last cpw> (which stands for "last change of password").
=item *
-The string C<password will never expire> indicates that the
-associated password never expires; the string C<password will
-expire> is followed by the password's expiration date. After
-the indicated date, the user cannot authenticate, but has 30 days after it in
-which to use the B<kpasswd> or B<kas setpassword> command to
-set a new password. After 30 days, only an administrator (one whose
-account is marked with the C<ADMIN> flag) can change the password by
-using the B<kas setpassword> command. To set the password
-expiration date, use the B<kas setfields> command's
-B<-pwexpires> argument.
-
+The string C<password will never expire> indicates that the associated
+password never expires; the string C<password will expire> is followed by
+the password's expiration date. After the indicated date, the user cannot
+authenticate, but has 30 days after it in which to use the B<kpasswd> or
+B<kas setpassword> command to set a new password. After 30 days, only an
+administrator (one whose account is marked with the C<ADMIN> flag) can
+change the password by using the B<kas setpassword> command. To set the
+password expiration date, use the B<kas setfields> command's B<-pwexpires>
+argument.
=item *
The number of times the user can fail to provide the correct password
-before the account locks, followed by the string C<consecutive unsuccessful
-authentications are permitted>, or the string C<An unlimited number of
-unsuccessful authentications is permitted> to indicate that there is no
-limit. To set the limit, use the B<kas setfields>
-command's B<-attempts> argument. To unlock a locked
-account, use the B<kas unlock> command. The B<kas
-setfields> reference page discusses how the implementation of the lockout
-feature interacts with this setting.
-
+before the account locks, followed by the string C<consecutive
+unsuccessful authentications are permitted>, or the string C<An unlimited
+number of unsuccessful authentications is permitted> to indicate that
+there is no limit. To set the limit, use the B<kas setfields> command's
+B<-attempts> argument. To unlock a locked account, use the B<kas unlock>
+command. The B<kas setfields> reference page discusses how the
+implementation of the lockout feature interacts with this setting.
=item *
The number of minutes for which the Authentication Server refuses the
user's login attempts after the limit on consecutive unsuccessful
authentication attempts is exceeded, following the string C<The lock time
-for this user is>. Use the B<kas> command's
-B<-locktime> argument to set the lockout time. This line
-appears only if a limit on the number of unsuccessful authentication attempts
-has been set with the the B<kas setfields> command's
-B<-attempts> argument.
-
+for this user is>. Use the B<kas> command's B<-locktime> argument to set
+the lockout time. This line appears only if a limit on the number of
+unsuccessful authentication attempts has been set with the the B<kas
+setfields> command's B<-attempts> argument.
=item *
An indication of whether the Authentication Server is currently refusing
-the user's login attempts. The string C<User is not
-locked> indicates that authentication can succeed, whereas the string
-C<User is locked until> I<time> indicates that the user cannot
-authenticate until the indicated time. Use the B<kas unlock>
-command to enable a user to attempt authentication. This line appears
-only if a limit on the number of unsuccessful authentication attempts has been
-set with the B<kas setfields> command's B<-attempts>
-argument.
-
+the user's login attempts. The string C<User is not locked> indicates that
+authentication can succeed, whereas the string C<User is locked until>
+I<time> indicates that the user cannot authenticate until the indicated
+time. Use the B<kas unlock> command to enable a user to attempt
+authentication. This line appears only if a limit on the number of
+unsuccessful authentication attempts has been set with the B<kas
+setfields> command's B<-attempts> argument.
=item *
The date on which the Authentication Server entry expires, or the string
-C<entry never expires> to indicate that the entry does not
-expire. A user becomes unable to authenticate when his or her entry
-expires. Use the B<kas setfields> command's
-B<-expiration> argument to set the expiration date.
-
+C<entry never expires> to indicate that the entry does not expire. A user
+becomes unable to authenticate when his or her entry expires. Use the
+B<kas setfields> command's B<-expiration> argument to set the expiration
+date.
=item *
The maximum possible lifetime of the tokens that the Authentication Server
-grants the user. This value interacts with several others to determine
-the actual lifetime of the token, as described on the B<klog>
-reference page. Use the B<kas setfields> command's
-B<-lifetime> argument to set this value.
-
+grants the user. This value interacts with several others to determine the
+actual lifetime of the token, as described in L<klog(1)>. Use the B<kas
+setfields> command's B<-lifetime> argument to set this value.
=item *
-The date on which the entry was last modified, following the string
-C<last mod on> and the user name of the administrator who modified
-it. The date on which a user changed his or her own password is
-recorded on the second line of output as C<last cpw> instead.
-
+The date on which the entry was last modified, following the string C<last
+mod on> and the user name of the administrator who modified it. The date
+on which a user changed his or her own password is recorded on the second
+line of output as C<last cpw> instead.
=item *
An indication of whether the user can reuse one of his or her last twenty
-passwords when issuing the B<kpasswd>, B<kas setpassword>, or
-B<kas setkey> commands. Use the B<kas setfields>
-command's B<-reuse> argument to set this restriction.
-
+passwords when issuing the B<kpasswd>, B<kas setpassword>, or B<kas
+setkey> commands. Use the B<kas setfields> command's B<-reuse> argument to
+set this restriction.
=back
=head1 EXAMPLES
-The following example command shows the user smith displaying
-her own Authentication Database entry. Note the C<ADMIN> flag,
-which shows that B<smith> is privileged.
+The following example command shows the user smith displaying her own
+Authentication Database entry. Note the C<ADMIN> flag, which shows that
+C<smith> is privileged.
% kas examine smith
Password for smith:
last mod on Tue Jan 5 08:22:29 1999 by admin
permit password reuse
-In the following example, the user pat examines his
-Authentication Database entry to determine when the account lockout currently
-in effect will end.
+In the following example, the user C<pat> examines his Authentication
+Database entry to determine when the account lockout currently in effect
+will end.
% kas examine pat
Password for pat:
last mod on Thu Feb 4 08:22:29 1999 by admin
permit password reuse
-In the following example, an administrator logged in as admin
-uses the B<-showkey> flag to display the octal digits that constitute
-the
key in the B<afs> entry.
+In the following example, an administrator logged in as C<admin> uses the
+B<-showkey> flag to display the octal digits that constitute the key in
% kas examine -name afs -showkey
Password for admin: I<admin_password>
=head1 PRIVILEGE REQUIRED
-A user can examine his or her own entry. To examine others'
-entries or to include the B<-showkey> flag, the issuer must have the
-C<ADMIN> flag set in his or her Authentication Database entry.
+A user can examine his or her own entry. To examine others' entries or to
+include the B<-showkey> flag, the issuer must have the C<ADMIN> flag set
+in his or her Authentication Database entry.
=head1 SEE ALSO
-L<bos_addkey(1)>,
-L<bos_listkeys(1)>,
-L<bos_setauth(1)>,
-L<kas(1)>,
-L<kas_setfields(1)>,
-L<kas_setpassword(1)>,
-L<kas_unlock(1)>,
+L<bos_addkey(8)>,
+L<bos_listkeys(8)>,
+L<bos_setauth(8)>,
+L<kas(8)>,
+L<kas_setfields(8)>,
+L<kas_setpassword(8)>,
+L<kas_unlock(8)>,
L<klog(1)>,
L<kpasswd(1)>
=head1 SYNOPSIS
-B<kas forgetticket> [B<-all>] [-help]
+B<kas forgetticket> [B<-all>] [B<-help>]
-B<kas f> [B<-a>] [-h]
+B<kas f> [B<-a>] [B<-h>]
=head1 DESCRIPTION
-The kas forgetticket command discards all of the issuer's
-tickets stored in the local machine's kernel memory. This includes
-the AFS server ticket from each cell in which the user has authenticated, and
-any tickets that the user have acquired during the current B<kas>
-session (either when entering the session or by using the B<kas
-getticket> command).
+The B<kas forgetticket> command discards all of the issuer's tickets
+stored in the local machine's kernel memory. This includes the AFS server
+ticket from each cell in which the user has authenticated, and any tickets
+that the user have acquired during the current B<kas> session (either when
+entering the session or by using the B<kas getticket> command).
=head1 OPTIONS
=over 4
-=item -all
+=item B<-all>
-Discards all tickets. This argument explicitly invokes the
-command's default behavior.
+Discards all tickets. This argument explicitly invokes the command's
+default behavior.
-=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 SEE ALSO
-L<kas(1)>
+L<kas(8)>
=head1 COPYRIGHT
=head1 NAME
-kas help - Displays the syntax of each specified kas command or lists
-functional descriptions of all B<kas> commands
+kas help - Displays help for kas commands
=head1 SYNOPSIS
-B<kas help >[B<-topic> <I<help string>>+] [-help]
+B<kas help> [B<-topic> <I<help string>>+] [B<-help>]
-B<kas h> [B<-t> <I<help string>>+] [-h]
+B<kas h> [B<-t> <I<help string>>+] [B<-h>]
=head1 DESCRIPTION
-The kas help command displays the complete online help entry
-(short description and syntax statement) for each command 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<kas> command.
+The B<kas help> command displays the complete online help entry (short
+description and syntax statement) for each command 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<kas> command.
-To list every kas command whose name or short description
-includes a specified keyword, use the B<kas apropos> command.
+To list every kas command whose name or short description includes a
+specified keyword, use the B<kas 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<kas> part of the command name, providing only
-the operation code (for example, specify B<setpassword>, not B<kas
-setpassword>). If this argument is omitted, the output briefly
-describes every B<kas> command.
+entry. Omit the B<kas> part of the command name, providing only the
+operation code (for example, specify B<setpassword>, not B<kas
+setpassword>). If this argument is omitted, the output briefly describes
+every B<kas> 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 kas command consists of the
-following two or three lines:
+The online help entry for each B<kas> 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 command displays the online help entry for the kas
-setpassword command:
+The following command displays the online help entry for the B<kas
+setpassword> command:
% kas help setpassword
kas setpassword: set a user's password
=head1 SEE ALSO
-L<kas(1)>,
-L<kas_apropos(1)>
+L<kas(8)>,
+L<kas_apropos(8)>
=head1 COPYRIGHT
=head1 SYNOPSIS
-B<kas interactive> [-admin_username <I<admin principal to use for authentication>>]
-[B<-password_for_admin> <I<admin password>>] [B<-cell> <I<cell name>>]
- [-servers <I<explicit list of authentication servers>>+]
- [B<-noauth>] [-help]
+B<kas interactive>
+ [B<-admin_username> <I<admin principal to use for authentication>>]
+ [B<-password_for_admin> <I<admin password>>] [B<-cell> <I<cell name>>]
+ [B<-servers> <I<explicit list of authentication servers>>+]
+ [B<-noauth>] [B<-help>]
-B<kas i> [
-a <I<admin principal to use for authentication>>]
-[B<-p> <I<admin password>>] [B<-c> <I<cell name>>]
- [B<-s> <I<explicit list of authentication servers>>+] [B<-n>] [-h]
+B<kas i> [
B<-a> <I<admin principal to use for authentication>>]
+ [B<-p> <I<admin password>>] [B<-c> <I<cell name>>]
+ [B<-s> <I<explicit list of authentication servers>>+] [B<-n>] [B<-h>]
=head1 DESCRIPTION
-The kas interactive command establishes an interactive session
-for the issuer of the command. By default, the command interpreter
-establishes an authenticated connection for the user logged into the local
-file system with all of the Authentication Servers listed in the local
-B</usr/vice/etc/CellServDB> file for the cell named in the local
-B</usr/vice/etc/ThisCell> file. To specify an alternate
-identity, cell name, or list of Authentication Servers, include the
-B<-admin_username>, B<-cell>, or B<-servers> arguments
-respectively. Interactive mode lasts for six hours unless the maximum
-ticket lifetime for the issuer or the Authentication Server's Ticket
-Granting Service is shorter.
+The B<kas interactive> command establishes an interactive session for the
+issuer of the command. By default, the command interpreter establishes an
+authenticated connection for the user logged into the local file system
+with all of the Authentication Servers listed in the local
+F</usr/vice/etc/CellServDB> file for the cell named in the local
+F</usr/vice/etc/ThisCell> file. To specify an alternate identity, cell
+name, or list of Authentication Servers, include the B<-admin_username>,
+B<-cell>, or B<-servers> arguments respectively. Interactive mode lasts
+for six hours unless the maximum ticket lifetime for the issuer or the
+Authentication Server's Ticket Granting Service is shorter.
There are two other ways to enter interactive mode, in addition to the
B<kas interactive> command:
-=item *
+=over 4
-Type the kas command at the shell prompt without any operation
-code. If appropriate, include one or more of the
-B<-admin_username>, B<-password_for_admin>, B<-cell>,
-and B<-servers> arguments.
+=item *
+Type the kas command at the shell prompt without any operation code. If
+appropriate, include one or more of the B<-admin_username>,
+B<-password_for_admin>, B<-cell>, and B<-servers> arguments.
=item *
-Type the kas command followed by a user name and cell name,
-separated by an B<@> sign (for example: B<kas
-admin@abc.com>), to establish a connection under the specified
-identity with the Authentication Servers listed in the local
-B</usr/vice/etc/CellServDB> file for the indicated cell. If
-appropriate, provide the B<-servers> argument to specify an alternate
-list of Authentication Server machines that belong to the indicated
-cell.
+Type the kas command followed by a user name and cell name, separated by
+an C<@> sign (for example: B<kas admin@abc.com>), to establish a
+connection under the specified identity with the Authentication Servers
+listed in the local F</usr/vice/etc/CellServDB> file for the indicated
+cell. If appropriate, provide the B<-servers> argument to specify an
+alternate list of Authentication Server machines that belong to the
+indicated cell.
+=back
There are several consequences of entering interactive mode:
=item *
-The C<ka>> prompt replaces the system (shell) prompt. When
-typing commands at this prompt, provide only the operation code (omit the
-command suite name, B<kas>).
-
+The C<< ka> >> prompt replaces the system (shell) prompt. When typing
+commands at this prompt, provide only the operation code (omit the command
+suite name, B<kas>).
=item *
-The command interpreter does not prompt for the issuer's
-password.
-
+The command interpreter does not prompt for the issuer's password.
The issuer's identity and password, the relevant cell, and the set of
-Authentication Server machines specified when entering interactive mode apply
-to all commands issued during the session. They cannot be changed
-without leaving the session, except by using the B<(kas)
-noauthentication> command to replace the current authenticated
-connections with unauthenticated ones. The B<-admin_username>,
-B<-password_for_admin>, B<-cell>, and B<-servers>
-arguments are ignored if provided on a command issued during interactive
-mode.
+Authentication Server machines specified when entering interactive mode
+apply to all commands issued during the session. They cannot be changed
+without leaving the session, except by using the B<kas noauthentication>
+command to replace the current authenticated connections with
+unauthenticated ones. The B<-admin_username>, B<-password_for_admin>,
+B<-cell>, and B<-servers> arguments are ignored if provided on a command
+issued during interactive mode.
=back
To establish an unauthenticated connection to the Authentication Server,
-include the B<-noauth> flag or provide an incorrect password.
-Unless authorization checking is disabled on each Authentication Server
-machine involved, however, it is not possible to perform any privileged
-operations within such a session.
+include the B<-noauth> flag or provide an incorrect password. Unless
+authorization checking is disabled on each Authentication Server machine
+involved, however, it is not possible to perform any privileged operations
+within such a session.
To end the current authenticated connection and establish an
-unauthenticated one, issue the B<(kas) noauthentication>
-command. To leave interactive mode and return to the regular shell
-prompt, issue the B<(kas) quit> command.
+unauthenticated one, issue the B<kas noauthentication> command. To leave
+interactive mode and return to the regular shell prompt, issue the B<kas
+quit> command.
=head1 OPTIONS
=over 4
-=item -admin_username
+=item B<-admin_username> <I<admin principal>>
Specifies the user identity under which to authenticate with the
-Authentication Server for execution of the command. For more details,
-see the introductory B<kas> reference page.
+Authentication Server for execution of the command. For more details, see
+L<kas(8)>.
-=item -password_for_admin
+=item B<-password_for_admin> <I<admin password>>
-Specifies the password of the command's issuer. If it is
-omitted (as recommended), the B<kas> command interpreter prompts for
-it and does not echo it visibly. For more details, see the introductory
-B<kas> reference page.
+Specifies the password of the command's issuer. If it is omitted (as
+recommended), the B<kas> command interpreter prompts for it and does not
+echo it visibly. For more details, see L<kas(8)>.
-=item -cell
+=item B<-cell> <I<cell name>>
Names the cell in which to run the command. For more details, see
-the introductory B<kas> reference page.
+L<kas(8)>.
-=item -servers
+=item B<-servers> <I<authentication servers>>+
Names each machine running an Authentication Server with which to
-establish a connection. For more details, see the introductory
-B<kas> reference page.
+establish a connection. For more details, see L<kas(8)>.
-=item -noauth
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. For more details, see the introductory B<kas> reference
-page.
+Assigns the unprivileged identity C<anonymous> to the issuer. For more
+details, see L<kas(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 a user entering interactive mode as the
-privileged user
B<admin>.
+privileged user
C<admin>.
% kas interactive admin
Password for admin: I<admin_password>
=head1 SEE ALSO
-L<kas(1)>,
-L<kas_noauthentication(1)>,
-L<kas_quit(1)>
+L<kas(8)>,
+L<kas_noauthentication(8)>,
+L<kas_quit(8)>
=head1 COPYRIGHT
=head1 SYNOPSIS
-B<kas list> [B<-long>] [B<-showadmin>] [-showkey]
-[B<-admin_username> <I<admin principal to use for authentication>>]
- [B<-password_for_admin> <I<admin password>>] [-cell <I<cell name>>]
- [-servers <I<explicit list of authentication servers>>+]
- [B<-noauth>] [-help]
+B<kas list> [B<-long>] [B<-showadmin>] [B<-showkey>]
+
[B<-admin_username> <I<admin principal to use for authentication>>]
+ [B<-password_for_admin> <I<admin password>>] [B<-cell> <I<cell name>>]
+ [B<-servers> <I<explicit list of authentication servers>>+]
+ [B<-noauth>] [B<-help>]
-B<kas ls> [B<-l>] [B<-showa>] [-showk]
-[B<-a> <I<admin principal to use for authentication>>]
- [B<-p> <I<admin password>>] [-c <I<cell name>>]
- [B<-se> <I<explicit list of authentication servers>>+] [B<-n>] [-h]
+B<kas ls> [B<-l>] [B<-showa>] [B<-showk>]
+
[B<-a> <I<admin principal to use for authentication>>]
+ [B<-p> <I<admin password>>] [B<-c> <I<cell name>>]
+ [B<-se> <I<explicit list of authentication servers>>+] [B<-n>] [B<-h>]
=head1 DESCRIPTION
-The kas list command either displays all entries from the
+The B<kas list> command either displays all entries from the
Authentication Database by name, or displays the full database entry for a
defined set of entries, as determined by the flag provided:
To display every entry in the Authentication Database in full, include the
B<-long> flag.
-
=item *
-To display only those entries in full that have the C<ADMIN> flag
-set, include the B<-showadmin> flag.
-
+To display only those entries in full that have the C<ADMIN> flag set,
+include the B<-showadmin> flag.
=item *
To list only the name of each Authentication Database entry, omit both the
B<-long> and B<-showadmin> flags.
-
=back
By default, full entries include a checksum for the encryption key, rather
-than the actual octal digits that constitute the key. To display the
-octal digits, include the B<-showkey> flag with the B<-long>
-or B<-showadmin> flag.
+than the actual octal digits that constitute the key. To display the octal
+digits, include the B<-showkey> flag with the B<-long> or B<-showadmin>
+flag.
=head1 OPTIONS
=over 4
-=item -long
+=item B<-long>
-Displays every Authentication Database entry in full. Provide this
-flag or the B<-showadmin> flag, or omit both to display just the name
-of every database entry.
+Displays every Authentication Database entry in full. Provide this flag or
+the B<-showadmin> flag, or omit both to display just the name of every
+database entry.
-=item -showadmin
+=item B<-showadmin>
Displays in full only the Authentication Database entries that have the
-C<ADMIN> flag set. Provide this flag or the B<-long>
-flag, or omit both to display just the name of every database entry.
+C<ADMIN> flag set. Provide this flag or the B<-long> flag, or omit both to
+display just the name of every database entry.
-=item -showkey
+=item B<-showkey>
Displays the octal digits that constitute the key in each full
-entry. Provide either the B<-long> or B<-showadmin>
-flag along with this one.
+entry. Provide either the B<-long> or B<-showadmin> flag along with this
+one.
-=item -admin_username
+=item B<-admin_username> <I<admin principal>>
Specifies the user identity under which to authenticate with the
-Authentication Server for execution of the command. For more details,
-see the introductory B<kas> reference page.
+Authentication Server for execution of the command. For more details, see
+L<kas(8)>.
-=item -password_for_admin
+=item B<-password_for_admin> <I<admin password>>
-Specifies the password of the command's issuer. If it is
-omitted (as recommended), the B<kas> command interpreter prompts for
-it and does not echo it visibly. For more details, see the introductory
-B<kas> reference page.
+Specifies the password of the command's issuer. If it is omitted (as
+recommended), the B<kas> command interpreter prompts for it and does not
+echo it visibly. For more details, see L<kas(8)>.
-=item -cell
+=item B<-cell> <I<cell name>>
Names the cell in which to run the command. For more details, see
-the introductory B<kas> reference page.
+L<kas(8)>.
-=item -servers
+=item B<-servers> <I<authentication servers>>+
Names each machine running an Authentication Server with which to
-establish a connection. For more details, see the introductory
-B<kas> reference page.
+establish a connection. For more details, see L<kas(8)>.
-=item -noauth
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. For more details, see the introductory B<kas> reference
-page.
+Assigns the unprivileged identity C<anonymous> to the issuer. For more
+details, see L<kas(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 neither the B<-long> or -showadmin flag is provided,
-the output lists the name of each entry in the Authentication Database on its
-own line.
+If neither the B<-long> or B<-showadmin> flag is provided, the output
+lists the name of each entry in the Authentication Database on its own
+line.
-If the -long flag is included, the output includes every
-Authentication Database entry in full. If the B<-showadmin>
-flag is included, the output includes in full only the Authentication Database
-entries that have the C<ADMIN> flag set. If the
-B<-showkey> is provided along with either one, the output includes the
-octal digits that constitute the encryption key in each entry.
+If the B<-long> flag is included, the output includes every Authentication
+Database entry in full. If the B<-showadmin> flag is included, the output
+includes in full only the Authentication Database entries that have the
+C<ADMIN> flag set. If the B<-showkey> is provided along with either one,
+the output includes the octal digits that constitute the encryption key in
+each entry.
A full Authentication Database entry includes the same information
-displayed by the B<kas examine> command; for details, see that
-command's reference page.
+displayed by the B<kas examine> command; for details, see that command's
+reference page.
=head1 PRIVILEGE REQUIRED
-The issuer must have the C<ADMIN> flag set on his or her
-Authentication Database entry.
+The issuer must have the C<ADMIN> flag set on his or her Authentication
+Database entry.
=head1 SEE ALSO
-L<kas(1)>,
-L<kas_examine(1)>
+L<kas(8)>,
+L<kas_examine(8)>
=head1 COPYRIGHT
=head1 SYNOPSIS
-B<kas listtickets> [B<-name> <I<name of server>>] [B<-long>] [-help]
+B<kas listtickets> [B<-name> <I<name of server>>] [B<-long>] [B<-help>]
-B<kas listt> [B<-n> <I<name of server>>] [B<-l>] [-h]
+B<kas listt> [B<-n> <I<name of server>>] [B<-l>] [B<-h>]
=head1 DESCRIPTION
-The kas listtickets command displays the associated user ID (AFS
-UID), cell name, and expiration date of some or all of the issuer's
-tickets (tokens), depending on which options are provided:
+The B<kas listtickets> command displays the associated user ID (AFS UID),
+cell name, and expiration date of some or all of the issuer's tickets
+(tokens), depending on which options are provided:
=over 4
=item *
-To display all tokens, provide neither the -name argument nor
-B<-long> flag. The output is similar to that of the
-B<tokens> command.
-
+To display all tokens, provide neither the B<-name> argument nor B<-long>
+flag. The output is similar to that of the B<tokens> command.
=item *
-To display a single token, provide the -name argument to
-specify name of the Authentication Database entry for the entity that accepts
-the token. All AFS server processes accept tokens sealed with the key
-from the B<afs> entry.
-
+To display a single token, provide the B<-name> argument to specify name
+of the Authentication Database entry for the entity that accepts the
+token. All AFS server processes accept tokens sealed with the key from the
+C<afs> entry.
=item *
To display in addition the octal numbers that constitute the token and
session key, provide the B<-long> flag.
-
=back
=head1 OPTIONS
=over 4
-=item -name
+=item B<-name> <I<name of server>>
Names the Authentication Database entry of the entity (usually a server
process) that accepts the token to display.
-=item -long
+=item B<-long>
-Displays the octal numbers that constitute the session key and
-ticket.
+Displays the octal numbers that constitute the session key and ticket.
-=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 reports the AFS UID of the user who owns the token, the service
-(usually, C<afs>) and cell for which it is valid, and its expiration
-date, using the following format. If the message does not specify a
-cell, the ticket is for the local cell.
+(usually, C<afs>) and cell for which it is valid, and its expiration date,
+using the following format. If the message does not specify a cell, the
+ticket is for the local cell.
- User's (AFS ID I<AFS UID>) tokens for I<service>[@I<cellname>] [Expires I<date>]
+ User's (AFS ID <AFS UID>) tokens for <service>[@<cellname>] \
+ [Expires <date>]
-If the -long flag is provided, the output also includes the
-octal numbers making up the session key and token, along with the key version
-number and the number of bytes in the token (if the number of bytes is not 56,
-there is an error).
+If the B<-long> flag is provided, the output also includes the octal
+numbers making up the session key and token, along with the key version
+number and the number of bytes in the token (if the number of bytes is not
+56, there is an error).
-If the marker C<[>> POSTDATED <]> appears instead of an
-expiration date, the ticket does not become valid until the indicated
-time. (Only internal calls can create a postdated ticket; there is
-no standard interface that allows users to do this.)
+If the marker C<<< [>> POSTDATED <] >>> appears instead of an expiration
+date, the ticket does not become valid until the indicated time. (Only
+internal calls can create a postdated ticket; there is no standard
+interface that allows users to do this.)
=head1 EXAMPLES
The following two examples are for a user with AFS UID 1020 in the
-B<abc.com> cell and AFS UID 35 in the
-B<test.abc.com> cell. He is working on a machine
-in the first cell and is authenticated in both cells.
+C<abc.com> cell and AFS UID 35 in the C<test.abc.com> cell. He is working
+on a machine in the first cell and is authenticated in both cells.
% kas listtickets
User's (AFS ID 1020) tokens for afs [Expires Wed Mar 31 9:30:54 1999]
- User's (AFS ID 35@test.abc.com) tokens for afs@test.abc.com \
+ User's (AFS ID 35@test.abc.com) tokens for afs@test.abc.com \
[Expires Wed Mar 31 13:54:26 1999]
% kas listtickets -name afs -long
User's (AFS ID 1020) tokens for afs [Expires Wed Mar 31 9:30:54 1999]
SessionKey: \375\205\351\227\032\310\263\013
- Ticket: (kvno = 0, len = 56): \033\005\221\156\203\278\312\058\016\133 I<(etc.)>
-
+ Ticket: (kvno = 0, len = 56): \033\005\221\156\203\278\312\058\016\133...
=head1 PRIVILEGE REQUIRED
=head1 SEE ALSO
-L<kas(1)>,
+L<kas(8)>,
L<tokens(1)>
=head1 COPYRIGHT
=head1 SYNOPSIS
-B<noauthentication> [-help]
+B<noauthentication> [B<-help>]
-B<n> [-h]
+B<n> [B<-h>]
=head1 DESCRIPTION
-The kas noauthentication command closes the (presumably
-authenticated) connection that the issuer established with one or more
-Authentication Server processes when entering interactive mode. It
-opens a new unauthenticated connection to each server, assigning the issuer
-the unprivileged identity B<anonymous>. It does not actually
-discard the user's tokens from the Cache Manager's memory (as the
-B<unlog> or B<kas forgetticket> command does). Unless
-authorization checking is disabled on each Authentication Server machine, it
-becomes impossible to perform any privileged operations within the session
-established by this command.
+The B<kas noauthentication> command closes the (presumably authenticated)
+connection that the issuer established with one or more Authentication
+Server processes when entering interactive mode. It opens a new
+unauthenticated connection to each server, assigning the issuer the
+unprivileged identity B<anonymous>. It does not actually discard the
+user's tokens from the Cache Manager's memory (as the B<unlog> or B<kas
+forgetticket> command does). Unless authorization checking is disabled on
+each Authentication Server machine, it becomes impossible to perform any
+privileged operations within the session established by this command.
-This command is operative only during interactive mode, so omit the
-B<kas> command suite name from the command line.
+This command is operative only during interactive mode, so omit the B<kas>
+command suite name from the command line.
=head1 OPTIONS
=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 SEE ALSO
-L<kas(1)>,
-L<kas_forgetticket(1)>,
-L<kas_interactive(1)>,
+L<kas(8)>,
+L<kas_forgetticket(8)>,
+L<kas_interactive(8)>,
L<unlog(1)>
=head1 COPYRIGHT
=head1 SYNOPSIS
-B<quit> [-help]
+B<quit> [B<-help>]
-B<q> [-h]
+B<q> [B<-h>]
=head1 DESCRIPTION
-The kas quit command ends interactive mode, severing the
-authenticated connection to one or more Authentication Server processes and
-returning the issuer to the normal shell prompt.
+The B<kas quit> command ends interactive mode, severing the authenticated
+connection to one or more Authentication Server processes and returning
+the issuer to the normal shell prompt.
-This command is operative only during interactive mode, so omit the
-B<kas> command suite name from the command line.
+This command is operative only during interactive mode, so omit the B<kas>
+command suite name from the command line.
=head1 OPTIONS
=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 SEE ALSO
-L<kas(1)>,
-L<kas_interactive(1)>
+L<kas(8)>,
+L<kas_interactive(8)>
=head1 COPYRIGHT
=head1 NAME
-kas setfields - Sets optional characteristics in an Authentication Database entry
+kas setfields - Sets fields in an Authentication Database entry
=head1 SYNOPSIS
-kas setfields -name <I<name of user>>
-[B<-flags> <I<hex flag value or flag name expression>>]
- [-expiration <I<date of account expiration>>]
- [-lifetime <I<maximum ticket lifetime>>]
- [-pwexpires <I<number days password is valid ([0..254])>>]
- [-reuse <I<permit password reuse (yes/no)>>]
- [-attempts <I<maximum successive failed login tries ([0..254])>>]
- [-locktime <I<failure penalty [hh:mm or minutes]>>]
- [-admin_username <I<admin principal to use for authentication>>]
- [B<-password_for_admin> <I<admin password>>] [-cell <I<cell name>>]
- [-servers <I<explicit list of authentication servers>>+]
- [B<-noauth>] [-help]
-
-B<kas setf -na> <I<name of user>> [-f <I<hex flag value or flag name expression>>]
-[B<-e> <I<date of account expiration>>] [B<-li> <I<maximum ticket lifetime>>]
- [-pw <I<number days password is valid ([0..254])>>]
- [-r <I<permit password reuse (yes/no)>>]
- [-at <I<maximum successive failed login tries ([0..254])>>]
- [-lo <I<failure penalty [hh:mm or minutes]>>]
- [-ad <I<admin principal to use for authentication>>]
- [B<-pa> <I<admin password>>] [-c <I<cell name>>]
- [B<-s> <I<explicit list of authentication servers>>+] [B<-no>] [-h]
+B<kas setfields> B<-name> <I<name of user>>
+ [B<-flags> <I<hex flag value or flag name expression>>]
+ [B<-expiration> <I<date of account expiration>>]
+ [B<-lifetime> <I<maximum ticket lifetime>>]
+ [B<-pwexpires> <I<number days password is valid ([0..254])>>]
+ [B<-reuse> <I<permit password reuse (yes/no)>>]
+ [B<-attempts> <I<maximum successive failed login tries ([0..254])>>]
+ [B<-locktime> <I<failure penalty [hh:mm or minutes]>>]
+ [B<-admin_username> <I<admin principal to use for authentication>>]
+ [B<-password_for_admin> <I<admin password>>] [B<-cell> <I<cell name>>]
+ [B<-servers> <I<explicit list of authentication servers>>+]
+ [B<-noauth>] [B<-help>]
+
+B<kas setf> B<-na> <I<name of user>>
+ [B<-f> <I<hex flag value or flag name expression>>]
+ [B<-e> <I<date of account expiration>>]
+ [B<-li> <I<maximum ticket lifetime>>]
+ [B<-pw> <I<number days password is valid ([0..254])>>]
+ [B<-r> <I<permit password reuse (yes/no)>>]
+ [B<-at> <I<maximum successive failed login tries ([0..254])>>]
+ [B<-lo> <I<failure penalty [hh:mm or minutes]>>]
+ [B<-ad> <I<admin principal to use for authentication>>]
+ [B<-pa> <I<admin password>>] [B<-c> <I<cell name>>]
+ [B<-s> <I<explicit list of authentication servers>>+] [B<-no>] [B<-h>]
-B<kas sf -na> <I<name of user>> [-f <I<hex flag value or flag name expression>>]
-[B<-e> <I<date of account expiration>>] [B<-li> <I<maximum ticket lifetime>>]
- [-pw <I<number days password is valid ([0..254])>>]
- [-r <I<permit password reuse (yes/no)>>]
- [-at <I<maximum successive failed login tries ([0..254])>>]
- [-lo <I<failure penalty [hh:mm or minutes]>>]
- [-ad <I<admin principal to use for authentication>>]
- [B<-pa> <I<admin password>>] [-c <I<cell name>>]
- [B<-s> <I<explicit list of authentication servers>>+] [B<-no>] [-h]
+B<kas sf> B<-na> <I<name of user>>
+ [B<-f> <I<hex flag value or flag name expression>>]
+ [B<-e> <I<date of account expiration>>]
+ [B<-li> <I<maximum ticket lifetime>>]
+ [B<-pw> <I<number days password is valid ([0..254])>>]
+ [B<-r> <I<permit password reuse (yes/no)>>]
+ [B<-at> <I<maximum successive failed login tries ([0..254])>>]
+ [B<-lo> <I<failure penalty [hh:mm or minutes]>>]
+ [B<-ad> <I<admin principal to use for authentication>>]
+ [B<-pa> <I<admin password>>] [B<-c> <I<cell name>>]
+ [B<-s> <I<explicit list of authentication servers>>+] [B<-no>] [B<-h>]
=head1 DESCRIPTION
-The kas setfields command changes the Authentication Database
-entry for the user named by the B<-name> argument in the manner
-specified by the various optional arguments, which can occur singly or in
-combination:
+The B<kas setfields> command changes the Authentication Database entry for
+the user named by the B<-name> argument in the manner specified by the
+various optional arguments, which can occur singly or in combination:
=over 4
=item *
To set the flags that determine whether the user has administrative
-privileges to the Authentication Server, can obtain a ticket, can change his
-or her password, and so on, include the B<-flags> argument.
-
+privileges to the Authentication Server, can obtain a ticket, can change
+his or her password, and so on, include the B<-flags> argument.
=item *
To set when the Authentication Database entry expires, include the
B<-expiration> argument.
-
=item *
To set the maximum ticket lifetime associated with the entry, include the
-B<-lifetime> argument. The reference page for the
-B<klog> command explains how this value interacts with others to
-determine the actual lifetime of a token.
-
+B<-lifetime> argument. L<klog(1)> explains how this value interacts with
+others to determine the actual lifetime of a token.
=item *
-To set when the user's password expires, include the
-B<-pwexpires> argument.
-
+To set when the user's password expires, include the B<-pwexpires>
+argument.
=item *
To set whether the user can reuse any of the previous twenty passwords
when creating a new one, include the B<-reuse> argument.
-
=item *
To set the maximum number of times the user can provide an incorrect
-password before the Authentication Server refuses to accept any more attempts
-(locks the issuer out), include the B<-attempts> argument.
-After the sixth failed authentication attempt, the Authentication Server logs
-a message in the UNIX system log file (the B<syslog> file or
-equivalent, for which the standard location varies depending on the operating
-system).
-
+password before the Authentication Server refuses to accept any more
+attempts (locks the issuer out), include the B<-attempts> argument. After
+the sixth failed authentication attempt, the Authentication Server logs a
+message in the UNIX system log file (the F<syslog> file or equivalent, for
+which the standard location varies depending on the operating system).
=item *
authentication attempts for a locked-out user, set the B<-locktime>
argument.
-
=back
-The kas examine command displays the settings made with this
-command.
+The B<kas examine> command displays the settings made with this command.
=head1 CAUTIONS
-The password lifetime set with the -pwexpires argument begins at
-the time the user's password was last changed, rather than when this
-command is issued. It can therefore be retroactive. If, for
-example, a user changed her password 100 days ago and the password lifetime is
-set to 100 days or less, the password effectively expires immediately.
-To avoid retroactive expiration, instruct the user to change the password just
+The password lifetime set with the B<-pwexpires> argument begins at the
+time the user's password was last changed, rather than when this command
+is issued. It can therefore be retroactive. If, for example, a user
+changed her password 100 days ago and the password lifetime is set to 100
+days or less, the password effectively expires immediately. To avoid
+retroactive expiration, instruct the user to change the password just
before setting a password lifetime.
-Administrators whose authentication accounts have the C<ADMIN> flag
-enjoy complete access to the sensitive information in the Authentication
-Database. To prevent access by unauthorized users, use the
-B<-attempts> argument to impose a fairly strict limit on the number of
-times that a user obtaining administrative tokens can provide an incorrect
-password. Note, however, that there must be more than one account in
-the cell with the C<ADMIN> flag. The B<kas unlock>
-command requires the C<ADMIN> privilege, so it is important that the
-locked-out administrator (or a colleague) can access another
-C<ADMIN>-privileged account to unlock the current account.
+Administrators whose authentication accounts have the C<ADMIN> flag enjoy
+complete access to the sensitive information in the Authentication
+Database. To prevent access by unauthorized users, use the B<-attempts>
+argument to impose a fairly strict limit on the number of times that a
+user obtaining administrative tokens can provide an incorrect
+password. Note, however, that there must be more than one account in the
+cell with the C<ADMIN> flag. The B<kas unlock> command requires the
+C<ADMIN> privilege, so it is important that the locked-out administrator
+(or a colleague) can access another C<ADMIN>-privileged account to unlock
+the current account.
In certain circumstances, the mechanism used to enforce the number of
-failed authentication attempts can cause a lockout even though the number of
-failed attempts is less than the limit set by the B<-attempts>
-argument. Client-side authentication programs such as B<klog>
-and an AFS-modified login utility normally choose an Authentication Server at
-random for each authentication attempt, and in case of a failure are likely to
-choose a different Authentication Server for the next attempt. The
-Authentication Servers running on the various database server machines do not
-communicate with each other about how many times a user has failed to provide
-the correct password to them. Instead, each Authentication Server
-maintains its own separate copy of the auxiliary database file
-B<kaserverauxdb> (located in the B</usr/afs/local> directory
-by default), which records the number of consecutive authentication failures
-for each user account and the time of the most recent failure. This
-implementation means that on average each Authentication Server knows about
-only a fraction of the total number of failed attempts. The only way to
-avoid allowing more than the number of attempts set by the
-B<-attempts> argument is to have each Authentication Server allow only
-some fraction of the total. More specifically, if the limit on failed
-attempts is I<f>, and the number of Authentication Servers is
-I<S>, then each Authentication Server can only permit a number of
-attempts equal to I<f> divided by I<S> (the Ubik
-synchronization site for the Authentication Server tracks any remainder,
-I<fmodS>).
+failed authentication attempts can cause a lockout even though the number
+of failed attempts is less than the limit set by the B<-attempts>
+argument. Client-side authentication programs such as B<klog> and an
+AFS-modified login utility normally choose an Authentication Server at
+random for each authentication attempt, and in case of a failure are
+likely to choose a different Authentication Server for the next
+attempt. The Authentication Servers running on the various database server
+machines do not communicate with each other about how many times a user
+has failed to provide the correct password to them. Instead, each
+Authentication Server maintains its own separate copy of the auxiliary
+database file F<kaserverauxdb> (located in the F</usr/afs/local> directory
+by default), which records the number of consecutive authentication
+failures for each user account and the time of the most recent
+failure. This implementation means that on average each Authentication
+Server knows about only a fraction of the total number of failed
+attempts. The only way to avoid allowing more than the number of attempts
+set by the B<-attempts> argument is to have each Authentication Server
+allow only some fraction of the total. More specifically, if the limit on
+failed attempts is I<f>, and the number of Authentication Servers is I<S>,
+then each Authentication Server can only permit a number of attempts equal
+to I<f> divided by I<S> (the Ubik synchronization site for the
+Authentication Server tracks any remainder, I<f> mod I<S>).
Normally, this implementation does not reduce the number of allowed
-attempts to less than the configured limit (I<f>). If one
-Authentication Server refuses an attempt, the client contacts another instance
-of the server, continuing until either it successfully authenticates or has
+attempts to less than the configured limit (I<f>). If one Authentication
+Server refuses an attempt, the client contacts another instance of the
+server, continuing until either it successfully authenticates or has
contacted all of the servers. However, if one or more of the
Authentication Server processes is unavailable, the limit is effectively
-reduced by a percentage equal to the quantity I<U> divided by
-I<S>, where I<U> is the number of unavailable servers and
-I<S> is the number normally available.
+reduced by a percentage equal to the quantity I<U> divided by I<S>, where
+I<U> is the number of unavailable servers and I<S> is the number normally
+available.
To avoid the undesirable consequences of setting a limit on failed
authentication attempts, note the following recommendations:
=item *
-Do not set the -attempts argument (the limit on failed
-authentication attempts) too low. A limit of nine failed attempts is
-recommended for regular user accounts, to allow three failed attempts per
-Authentication Server in a cell with three database server machines.
-
+Do not set the B<-attempts> argument (the limit on failed authentication
+attempts) too low. A limit of nine failed attempts is recommended for
+regular user accounts, to allow three failed attempts per Authentication
+Server in a cell with three database server machines.
=item *
-Set fairly short lockout times when including the -locktime
-argument. Although guessing passwords is a common method of attack, it
-is not a very sophisticated one. Setting a lockout time can help
-discourage attackers, but excessively long times are likely to be more of a
-burden to authorized users than to potential attackers. A lockout time
-of 25 minutes is recommended for regular user accounts.
-
+Set fairly short lockout times when including the B<-locktime>
+argument. Although guessing passwords is a common method of attack, it is
+not a very sophisticated one. Setting a lockout time can help discourage
+attackers, but excessively long times are likely to be more of a burden to
+authorized users than to potential attackers. A lockout time of 25 minutes
+is recommended for regular user accounts.
=item *
Do not assign an infinite lockout time on an account (by setting the
-B<-locktime> argument to B<0> [zero]) unless there is a highly
-compelling reason. Such accounts almost inevitably become locked at
-some point, because each Authentication Server never resets the account's
-failure counter in its copy of the B<kaauxdb> file (in contrast, when
-the lockout time is not infinite, the counter resets after the specified
-amount of time has passed since the last failed attempt to that Authentication
-Server). Furthermore, the only way to unlock an account with an
-infinite lockout time is for an administrator to issue the B<kas
-unlock> command. It is especially dangerous to set an infinite
-lockout time on an administrative account; if all administrative accounts
-become locked, the only way to unlock them is to shut down all instances of
-the Authentication Server and remove the B<kaauxdb> file on
-each.
-
+B<-locktime> argument to C<0> [zero]) unless there is a highly compelling
+reason. Such accounts almost inevitably become locked at some point,
+because each Authentication Server never resets the account's failure
+counter in its copy of the F<kaauxdb> file (in contrast, when the lockout
+time is not infinite, the counter resets after the specified amount of
+time has passed since the last failed attempt to that Authentication
+Server). Furthermore, the only way to unlock an account with an infinite
+lockout time is for an administrator to issue the B<kas unlock>
+command. It is especially dangerous to set an infinite lockout time on an
+administrative account; if all administrative accounts become locked, the
+only way to unlock them is to shut down all instances of the
+Authentication Server and remove the F<kaauxdb> file on each.
=back
=over 4
-=item -name
+=item B<-name> <I<name of user>>
-Names the Authentication Database account for which to change
-settings.
+Names the Authentication Database account for which to change settings.
-=item -flags
+=item B<-flags> <I<hex flag or flag name expression>>
Sets one or more of four toggling flags, adding them to any flags
currently set. Either specify one or more of the following strings, or
-specify a hexidecimal number that combines the indicated values. To
-return all four flags to their defaults, provide a value of B<0>
-(zero). To set more than one flag at once using the strings, connect
-them with plus signs (example: B<NOTGS+ADMIN+CPW>). To
-remove all the current flag settings before setting new ones, precede the list
-with an equal sign (example: B<=NOTGS+ADMIN+CPW>).
+specify a hexidecimal number that combines the indicated values. To return
+all four flags to their defaults, provide a value of C<0> (zero). To set
+more than one flag at once using the strings, connect them with plus signs
+(example: C<NOTGS+ADMIN+CPW>). To remove all the current flag settings
+before setting new ones, precede the list with an equal sign (example:
+C<=NOTGS+ADMIN+CPW>).
=over 4
=item ADMIN
-The user is allowed to issue privileged kas commands
-(hexadecimal equivalent is B<0x004>, default is
-B<NOADMIN>).
-L<(1)>
+The user is allowed to issue privileged kas commands (hexadecimal
+equivalent is C<0x004>, default is C<NOADMIN>).
=item NOTGS
-The Authentication Server's Ticket Granting Service (TGS) refuses to
-issue tickets to the user (hexadecimal equivalent is B<0x008>, default
-is B<TGS>).
-L<(1)>
+The Authentication Server's Ticket Granting Service (TGS) refuses to issue
+tickets to the user (hexadecimal equivalent is C<0x008>, default is
+C<TGS>).
=item NOSEAL
-The Ticket Granting Service cannot use the contents of this entry's
-key field as an encryption key (hexadecimal equivalent is B<0x020>,
-default is B<SEAL>).
-L<(1)>
+The Ticket Granting Service cannot use the contents of this entry's key
+field as an encryption key (hexadecimal equivalent is C<0x020>, default is
+C<SEAL>).
=item NOCPW
The user cannot change his or her own password or key (hexadecimal
-equivalent is B<0x040>, default is B<CPW>).
-L<(1)>
+equivalent is C<0x040>, default is C<CPW>).
=back
-=item -expiration
+=item B<-expiration> <I<date of account expiration>>
-Determines when the entry itself expires. When a user entry
-expires, the user becomes unable to log in; when a server entry such as
-B<afs> expires, all server processes that use the associated key
-become inaccessible. Provide one of the three acceptable values:
+Determines when the entry itself expires. When a user entry expires, the
+user becomes unable to log in; when a server entry such as C<afs> expires,
+all server processes that use the associated key become inaccessible.
+Provide one of the three acceptable values:
=over 4
The account never expires (the default).
-=item I<mm/dd/yyyy
->
+=item I<mm/dd/yyyy>
-Sets the expiration date to 12:00 a.m. on the
-indicated date (month/day/year). Examples: B<01/23/1999>,
-B<10/07/2000>.
+Sets the expiration date to 12:00 a.m. on the indicated date
+(month/day/year). Examples: C<01/23/1999>, C<10/07/2000>.
-=item "I<mm/dd/yyyy hh:MM"
->
+=item "I<mm/dd/yyyy hh:MM>"
-Sets the expiration date to the indicated time (hours:minutes) on
-the indicated date (month/day/year). Specify the time in 24-hour format
-(for example, B<20:30> is 8:30 p.m.) Date
-format is the same as for a date alone. Surround the entire instance
-with quotes because it contains a space. Examples:
-B<"01/23/1999 22:30">, B<"10/07/2000
-3:45">.
+Sets the expiration date to the indicated time (hours:minutes) on the
+indicated date (month/day/year). Specify the time in 24-hour format (for
+example, C<20:30> is 8:30 p.m.) Date format is the same as for a date
+alone. Surround the entire instance with quotes because it contains a
+space. Examples: C<"01/23/1999 22:30">, C<"10/07/2000 3:45">.
=back
-Acceptable values for the year range from 1970 (1 January 1970
-is time 0 in the standard UNIX date representation) through B<2037>
-(2037 is the maximum because the UNIX representation cannot accommodate dates
-later than a value in February 2038).
+Acceptable values for the year range from C<1970> (1 January 1970 is time
+0 in the standard UNIX date representation) through C<2037> (2037 is the
+maximum because the UNIX representation cannot accommodate dates later
+than a value in February 2038).
-=item -lifetime
+=item B<-lifetime> <I<maximum ticket lifetime>>
-Specifies the maximum lifetime that the Authentication Server's
-Ticket Granting Service (TGS) can assign to a ticket. If the account
-belongs to a user, this value is the maximum lifetime of a token issued to the
-user. If the account corresponds to a server such as B<afs>,
-this value is the maximum lifetime of a ticket that the TGS issues to clients
-for presentation to the server during mutual authentication.
+Specifies the maximum lifetime that the Authentication Server's Ticket
+Granting Service (TGS) can assign to a ticket. If the account belongs to a
+user, this value is the maximum lifetime of a token issued to the user. If
+the account corresponds to a server such as C<afs>, this value is the
+maximum lifetime of a ticket that the TGS issues to clients for
+presentation to the server during mutual authentication.
-Specify an integer that represents a number of seconds (3600
-equals one hour), or include a colon in the number to indicate a number of
-hours and minutes (B<10:00> equals 10 hours). If this
-argument is omitted, the default setting is 100:00 hours (360000
-seconds).
+Specify an integer that represents a number of seconds (3600 equals one
+hour), or include a colon in the number to indicate a number of hours and
+minutes (C<10:00> equals 10 hours). If this argument is omitted, the
+default setting is 100:00 hours (360000 seconds).
-=item -pwexpires
+=item B<-pwexpires> <I<number of days password is valid>>
-Sets the number of days after the user's password was last 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).
+Sets the number of days after the user's password was last changed that it
+remains valid. Provide an integer from the range C<1> through C<254> to
+specify the number of days until expiration, or the value C<0> to indicate
+that the password never expires (the default).
When the password expires, the user is unable to authenticate, but has 30
-days after the expiration date in which to use the B<kpasswd> command
-to change the password (after that, only an administrator can change it by
-using the B<kas setpassword> command). Note that the clock
-starts at the time the password was last changed, not when the B<kas
-setfields> command is issued. To avoid retroactive expiration,
-have the user change the password just before issuing a command that includes
-this argument.
+days after the expiration date in which to use the B<kpasswd> command to
+change the password (after that, only an administrator can change it by
+using the B<kas setpassword> command). Note that the clock starts at the
+time the password was last changed, not when the B<kas setfields> command
+is issued. To avoid retroactive expiration, have the user change the
+password just before issuing a command that includes this argument.
-=item -reuse
+=item B<-reuse> (yes | no)
Specifies whether or not the user can reuse any of his or her last 20
-passwords. The acceptable values are B<yes> to allow reuse of
-old passwords (the default) and B<no> to prohibit reuse of a password
-that is similar to one of the previous 20 passwords.
+passwords. The acceptable values are C<yes> to allow reuse of old
+passwords (the default) and C<no> to prohibit reuse of a password that is
+similar to one of the previous 20 passwords.
-=item -attempts
+=item B<-attempts> <I<maximum successive failed login tries>>
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 attempts (locks the user out) for the
-amount of time specified by the B<-locktime> argument. Provide
-an integer from the range B<1> through B<254> to specify the
-number of failures allowed, or B<0> to indicate that there is no limit
-on authentication attempts (the default value).
+Authentication Server rejects further attempts (locks the user out) for
+the amount of time specified by the B<-locktime> argument. Provide an
+integer from the range C<1> through C<254> to specify the number of
+failures allowed, or C<0> to indicate that there is no limit on
+authentication attempts (the default value).
-=item -locktime
+=item B<-locktime> <I<failure penalty>>
Specifies how long the Authentication Server refuses authentication
attempts from a user who has exceeded the failure limit set by the
B<-attempts> argument.
-Specify a number of hours and minutes (I<hh>:I<mm>) or
-minutes only (I<mm>), from the range B<01> (one minute) through
-B<36:00> (36 hours). The B<kas> command
-interpreter 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 issue the B<kas unlock>
-command to unlock the account.
+Specify a number of hours and minutes (I<hh:mm>) or minutes only (I<mm>),
+from the range C<01> (one minute) through C<36:00> (36 hours). The B<kas>
+command interpreter automatically reduces any larger value to C<36:00> and
+also rounds up any non-zero value to the next higher multiple of 8.5
+minutes. A value of C<0> (zero) sets an infinite lockout time; an
+administrator must issue the B<kas unlock> command to unlock the account.
-=item -admin_username
+=item B<-admin_username> <I<admin principal>>
Specifies the user identity under which to authenticate with the
-Authentication Server for execution of the command. For more details,
-see the introductory B<kas> reference page.
+Authentication Server for execution of the command. For more details, see
+L<kas(8)>.
-=item -password_for_admin
+=item B<-password_for_admin> <I<admin password>>
-Specifies the password of the command's issuer. If it is
-omitted (as recommended), the B<kas> command interpreter prompts for
-it and does not echo it visibly. For more details, see the introductory
-B<kas> reference page.
+Specifies the password of the command's issuer. If it is omitted (as
+recommended), the B<kas> command interpreter prompts for it and does not
+echo it visibly. For more details, see L<kas(8)>.
-=item -cell
+=item B<-cell> <I<cell name>>
Names the cell in which to run the command. For more details, see
-the introductory B<kas> reference page.
+L<kas(8)>.
-=item -servers
+=item B<-servers> <I<authentication servers>>+
Names each machine running an Authentication Server with which to
-establish a connection. For more details, see the introductory
-B<kas> reference page.
+establish a connection. For more details, see L<kas(8)>.
-=item -noauth
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. For more details, see the introductory B<kas> reference
-page.
+Assigns the unprivileged identity C<anonymous> to the issuer. For more
+details, see L<kas(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
-In the following example, an administrator using the admin
-account grants administrative privilege to the user B<smith>, and sets
-the Authentication Database entry to expire at midnight on 31 December
-2000.
+In the following example, an administrator using the C<admin> account
+grants administrative privilege to the user C<smith>, and sets the
+Authentication Database entry to expire at midnight on 31 December 2000.
% kas setfields -name smith -flags ADMIN -expiration 12/31/2000
Password for admin:
-In the following example, an administrator using the admin
-account sets the user B<pat>'s password to expire in 60 days from
-when it last changed, and prohibits reuse of passwords.
+In the following example, an administrator using the C<admin> account sets
+the user C<pat>'s password to expire in 60 days from when it last changed,
+and prohibits reuse of passwords.
% kas setfields -name pat -pwexpires 60 -reuse no
Password for admin:
=head1 PRIVILEGE REQUIRED
-The issuer must have the C<ADMIN> flag set on his or her
-Authentication Database entry.
+The issuer must have the C<ADMIN> flag set on his or her Authentication
+Database entry.
=head1 SEE ALSO
-L<kaserverauxdb(1)>,
-L<kas(1)>,
-L<kas_examine(1)>,
-L<kas_setpassword(1)>,
-L<kas_unlock(1)>,
+L<kaserverauxdb(5)>,
+L<kas(8)>,
+L<kas_examine(8)>,
+L<kas_setpassword(8)>,
+L<kas_unlock(8)>,
L<klog(1)>,
L<kpasswd(1)>
=head1 SYNOPSIS
-B<kas setpassword -name> <I<name of user>> [-new_password <I<new password>>]
-[B<-kvno> <I<key version number>>]
-
[-admin_username <I<admin principal to use for authentication>>]
- [B<-password_for_admin> <I<admin password>>] [-cell <I<cell name>>]
- [-servers <I<explicit list of authentication servers>>+]
- [B<-noauth>] [-help]
-
-B<kas setpasswd -na> <I<name of user>> [-ne <I<new password>>]
-[B<-k> <I<key version number>>]
-
[-a <I<admin principal to use for authentication>>]
- [-p <I<admin password>>] [-c <I<cell name>>]
- [B<-s> <I<explicit list of authentication servers>>+] [B<-no>] [-h]
+B<kas setpassword> B<-name> <I<name of user>>
+ [B<-new_password> <I<new password>>] [B<-kvno> <I<key version number>>]
+
[B<-admin_username> <I<admin principal to use for authentication>>]
+ [B<-password_for_admin> <I<admin password>>] [B<-cell> <I<cell name>>]
+ [B<-servers> <I<explicit list of authentication servers>>+]
+ [B<-noauth>] [B<-help>]
+
+B<kas setpasswd> B<-na> <I<name of user>> [B<-ne> <I<new password>>]
+ [B<-k> <I<key version number>>]
+
[B<-a> <I<admin principal to use for authentication>>]
+ [B<-p> <I<admin password>>] [B<-c> <I<cell name>>]
+ [B<-s> <I<explicit list of authentication servers>>+] [B<-no>] [B<-h>]
-B<kas setp -na> <I<name of user>> [B<-ne> <I<new password>>] [-k <I<key version number>>]
-[B<-a> <I<admin principal to use for authentication>>]
- [-p <I<admin password>>] [-c <I<cell name>>]
- [B<-s> <I<explicit list of authentication servers>>+] [B<-no>] [-h]
+B<kas setp> B<-na> <I<name of user>> [B<-ne> <I<new password>>]
+ [B<-k> <I<key version number>>]
+ [B<-a> <I<admin principal to use for authentication>>]
+ [B<-p> <I<admin password>>] [B<-c> <I<cell name>>]
+ [B<-s> <I<explicit list of authentication servers>>+] [B<-no>] [B<-h>]
-B<kas sp -na> <I<name of user>> [B<-ne> <I<new password>>] [-k <I<key version number>>]
-[B<-a> <I<admin principal to use for authentication >>]
- [B<-p> <I<admin password>>] [-c <I<cell name>>]
- [B<-s> <I<explicit list of authentication servers>>+] [B<-no>] [-h]
+B<kas sp> B<-na> <I<name of user>> [B<-ne> <I<new password>>]
+ [B<-k> <I<key version number>>]
+ [B<-a> <I<admin principal to use for authentication>>]
+ [B<-p> <I<admin password>>] [B<-c> <I<cell name>>]
+ [B<-s> <I<explicit list of authentication servers>>+] [B<-no>] [B<-h>]
=head1 DESCRIPTION
-The kas setpassword command accepts a character string of
-unlimited length, scrambles it into a form suitable for use as an encryption
-key, places it in the key field of the Authentication Database entry named by
-the B<-name> argument, and assigns it the key version number specified
-by the B<-kvno> argument.
+The B<kas setpassword> command accepts a character string of unlimited
+length, scrambles it into a form suitable for use as an encryption key,
+places it in the key field of the Authentication Database entry named by
+the B<-name> argument, and assigns it the key version number specified by
+the B<-kvno> argument.
To avoid making the password string visible at the shell prompt, omit the
-B<-new_password> argument. Prompts then appear at the shell
-which do not echo the password visibly.
+B<-new_password> argument. Prompts then appear at the shell which do not
+echo the password visibly.
-When changing the B<afs> server key, also issue bos
-addkey command to add the key (with the same key version number) to the
-B</usr/afs/etc/KeyFile> file. See the I<IBM AFS
-Administration Guide> for instructions.
+When changing the B<afs> server key, also issue B<bos addkey> command to
+add the key (with the same key version number) to the
+F</usr/afs/etc/KeyFile> file. See the I<IBM AFS Administration Guide> for
+instructions.
-The command interpreter checks the password string subject to the following
-conditions:
+The command interpreter checks the password string subject to the
+following conditions:
=over 4
=item *
-If there is a program called kpwvalid in the same directory as
-the B<kas> binary, the command interpreter invokes it to process the
-password. For details, see the B<kpwvalid> reference
-page.
-
+If there is a program called kpwvalid in the same directory as the B<kas>
+binary, the command interpreter invokes it to process the password. For
+details, see L<kpwvalid(8)>.
=item *
-If the B<-reuse> argument to the kas setfields command
-has been used to prohibit reuse of previous passwords, the command interpreter
-verifies that the password is not too similar too any of the user's
-previous 20 passwords. It generates the following error message at the
-shell:
-
+If the B<-reuse> argument to the B<kas setfields> command has been used to
+prohibit reuse of previous passwords, the command interpreter verifies
+that the password is not too similar too any of the user's previous 20
+passwords. It generates the following error message at the shell:
Password was not changed because it seems like a reused password
-To prevent a user from subverting this restriction by changing the password
-twenty times in quick succession (manually or by running a script), use the
-B<-minhours> argument on the B<kaserver> initialization
-command. The following error message appears if a user attempts to
-change a password before the minimum time has passed:
+To prevent a user from subverting this restriction by changing the
+password twenty times in quick succession (manually or by running a
+script), use the B<-minhours> argument on the B<kaserver> initialization
+command. The following error message appears if a user attempts to change
+a password before the minimum time has passed:
Password was not changed because you changed it too
recently; see your systems administrator
=over 4
-=item -name
+=item B<-name> <I<name of user>>
Names the entry in which to record the new key.
-=item -new_password
+=item B<-new_password> <I<new password>>
Specifies the character string the user types when authenticating to
AFS. Omit this argument and type the string at the resulting prompts so
-that the password does not echo visibly. Note that some non-AFS
-programs cannot handle passwords longer than eight characters.
+that the password does not echo visibly. Note that some non-AFS programs
+cannot handle passwords longer than eight characters.
-=item -kvno
+=item B<-kvno> <I<key version number>>
-Specifies the key version number associated with the new key.
-Provide an integer in the range from B<0> through
-B<255>. If omitted, the default is 0 (zero), which is probably
-not desirable for server keys.
+Specifies the key version number associated with the new key. Provide an
+integer in the range from C<0> through C<255>. If omitted, the default is
+C<0> (zero), which is probably not desirable for server keys.
-=item -admin_username
+=item B<-admin_username> <I<admin principal>>
Specifies the user identity under which to authenticate with the
-Authentication Server for execution of the command. For more details,
-see the introductory B<kas> reference page.
+Authentication Server for execution of the command. For more details, see
+L<kas(8)>.
-=item -password_for_admin
+=item B<-password_for_admin> <I<admin password>>
-Specifies the password of the command's issuer. If it is
-omitted (as recommended), the B<kas> command interpreter prompts for
-it and does not echo it visibly. For more details, see the introductory
-B<kas> reference page.
+Specifies the password of the command's issuer. If it is omitted (as
+recommended), the B<kas> command interpreter prompts for it and does not
+echo it visibly. For more details, see L<kas(8)>.
-=item -cell
+=item B<-cell> <I<cell name>>
Names the cell in which to run the command. For more details, see
-the introductory B<kas> reference page.
+L<kas(8)>.
-=item -servers
+=item B<-servers> <I<authentication servers>>+
Names each machine running an Authentication Server with which to
-establish a connection. For more details, see the introductory
-B<kas> reference page.
+establish a connection. For more details, see L<kas(8)>.
-=item -noauth
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. For more details, see the introductory B<kas> reference
-page.
+Assigns the unprivileged identity C<anonymous> to the issuer. For more
+details, see L<kas(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
-In the following example, an administrator using the admin
-account changes the password for B<pat> (presumably because
-B<pat> forgot the former password or got locked out of his account in
-some other way).
+In the following example, an administrator using the C<admin> account
+changes the password for C<pat> (presumably because C<pat> forgot the
+former password or got locked out of his account in some other way).
% kas setpassword pat
Password for admin:
=head1 PRIVILEGE REQUIRED
-Individual users can change their own passwords. To change another
-user's password or the password (server encryption key) for server
-entries such as B<afs>, the issuer must have the C<ADMIN> flag
-set in his or her Authentication Database entry.
+Individual users can change their own passwords. To change another user's
+password or the password (server encryption key) for server entries such
+as C<afs>, the issuer must have the C<ADMIN> flag set in his or her
+Authentication Database entry.
=head1 SEE ALSO
-L<bos_addkey(1)>,
-L<kas(1)>,
+L<bos_addkey(8)>,
+L<kas(8)>,
L<kaserver(1)>,
L<kpwvalid(1)>
=head1 SYNOPSIS
-B<kas statistics> [-admin_username <I<admin principal to use for authentication>>]
-[B<-password_for_admin> <I<admin password>>] [B<-cell> <I<cell name>>]
- [-servers <I<explicit list of authentication servers>>+]
- [B<-noauth>] [-help]
+B<kas statistics>
+ [B<-admin_username> <I<admin principal to use for authentication>>]
+ [B<-password_for_admin> <I<admin password>>] [B<-cell> <I<cell name>>]
+ [B<-servers> <I<explicit list of authentication servers>>+]
+ [B<-noauth>] [B<-help>]
-B<kas sta> [
-a <I<admin principal to use for authentication>>]
-[B<-p> <I<admin password>>] [B<-c> <I<cell name>>]
- [B<-s> <I<explicit list of authentication servers>>+] [B<-n>] [-h]
+B<kas sta> [
B<-a> <I<admin principal to use for authentication>>]
+
[B<-p> <I<admin password>>] [B<-c> <I<cell name>>]
+ [B<-s> <I<explicit list of authentication servers>>+] [B<-n>] [B<-h>]
=head1 DESCRIPTION
-The kas statistics command displays statistics from the
-Authentication Server running on one of the cell's database server
-machines. Use the B<-servers> argument to name a specific
-machine, or the command interpreter chooses one at random from all the
-database server machines with which it has established connections.
+The B<kas statistics> command displays statistics from the Authentication
+Server running on one of the cell's database server machines. Use the
+B<-servers> argument to name a specific machine, or the command
+interpreter chooses one at random from all the database server machines
+with which it has established connections.
=head1 CAUTIONS
-The -servers argument is not available in interactive mode,
-making it impossible to specify a certain machine.
+The B<-servers> argument is not available in interactive mode, making it
+impossible to specify a certain machine.
=head1 OPTIONS
=over 4
-=item -admin_username
+=item B<-admin_username> <I<admin principal>>
Specifies the user identity under which to authenticate with the
-Authentication Server for execution of the command. For more details,
-see the introductory B<kas> reference page.
+Authentication Server for execution of the command. For more details, see
+L<kas(8)>.
-=item -password_for_admin
+=item B<-password_for_admin> <I<admin password>>
-Specifies the password of the command's issuer. If it is
-omitted (as recommended), the B<kas> command interpreter prompts for
-it and does not echo it visibly. For more details, see the introductory
-B<kas> reference page.
+Specifies the password of the command's issuer. If it is omitted (as
+recommended), the B<kas> command interpreter prompts for it and does not
+echo it visibly. For more details, see L<kas(8)>.
-=item -cell
+=item B<-cell> <I<cell name>>
Names the cell in which to run the command. For more details, see
-the introductory B<kas> reference page.
+L<kas(8)>.
-=item -servers
+=item B<-servers> <I<authentication servers>>+
Names each machine running an Authentication Server with which to
-establish a connection. For more details, see the introductory
-B<kas> reference page.
+establish a connection. For more details, see L<kas(8)>.
-=item -noauth
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. For more details, see the introductory B<kas> reference
-page.
+Assigns the unprivileged identity C<anonymous> to the issuer. For more
+details, see L<kas(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
The number of allocation and freeing operations the Authentication Server
has performed, and how many password change requests it has processed.
-
=item *
An indication of its hash table use.
-
=item *
The server machine's IP address in hexadecimal and the date when the
current instance of the Authentication Server started.
-
=item *
The number of requests and aborted requests for various services:
authentication, ticket granting, password setting, entry listing, and so
on.
-
=item *
The amount of CPU time that the Authentication Server has used to process
-requests since it started. The amount is not accurate on all system
-types, however.
-
+requests since it started. The amount is not accurate on all system types,
+however.
=item *
The number of entries in the Authentication Database that are marked with
the C<ADMIN> flag.
-
=back
=head1 EXAMPLES
-In the following example, an administrator using the admin
-account gathers statistics from the Authentication Server running on the
-machine B<fs1.abc.com>.
+In the following example, an administrator using the admin account gathers
+statistics from the Authentication Server running on the machine
+C<fs1.abc.com>.
% kas statistics -servers fs1.abc.com
56 allocs, 46 frees, 0 password changes
=head1 PRIVILEGE REQUIRED
-The issuer must have the C<ADMIN> flag set on his or her
-Authentication Database entry.
+The issuer must have the C<ADMIN> flag set on his or her Authentication
+Database entry.
=head1 SEE ALSO
-L<kas(1)>
+L<kas(8)>
=head1 COPYRIGHT
=head1 SYNOPSIS
-B<kas stringtokey -string> <I<password string>> [B<-cell> <I<cell name>>] [-help]
+B<kas stringtokey> B<-string> <I<password string>>
+ [B<-cell> <I<cell name>>] [B<-help>]
-B<kas str -s> <I<password string>> [B<-c> <I<cell name>>] [-h]
+B<kas str> B<-s> <I<password string>> [B<-c> <I<cell name>>] [B<-h>]
=head1 DESCRIPTION
-The kas stringtokey command converts the character string
-specified with the B<-string> argument into an octal string suitable
-for use as an encryption key.
+The B<kas stringtokey> command converts the character string specified
+with the B<-string> argument into an octal string suitable for use as an
+encryption key.
-The kas command interpreter generates the octal key by using an
-encryption algorithm on the combination of the specified string and the name
-of the local cell (as recorded in the local B</usr/vice/etc/ThisCell>
+The B<kas> command interpreter generates the octal key by using an
+encryption algorithm on the combination of the specified string and the
+name of the local cell (as recorded in the local F</usr/vice/etc/ThisCell>
file). Use the B<-cell> argument to convert a string into a key
appropriate for a cell other than the local one.
=head1 CAUTIONS
This command writes the key to the standard output stream, on which it can
-possibly be intercepted by third parties. It is not very secure to use
-the key in an actual Authentication Database entry.
+possibly be intercepted by third parties. It is not very secure to use the
+key in an actual Authentication Database entry.
=head1 OPTIONS
=over 4
-=item -string
+=item B<-string> <I<password string>>
Specifies the character string to convert into an octal key.
-=item -cell
+=item B<-cell> <I<cell name>>
Specifies the complete Internet domain name of the cell to combine with
-the password string while generating the key. If this argument is
-omitted, the B<kas> command interpreter determines the name of the
-local cell by consulting:
+the password string while generating the key. If this argument is omitted,
+the B<kas> command interpreter determines the name of the local cell by
+consulting:
=over 4
First, the value of the environment variable AFSCELL.
-
=item *
-Second, the cellname in the /usr/vice/etc/ThisCell file on the
-local machine.
-
+Second, the cellname in the F</usr/vice/etc/ThisCell> file on the local
+machine.
=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
=head1 EXAMPLES
The following example shows the octal key equivalent of the string
-B<new_pswd> in the ABC Corporation cell.
+C<new_pswd> in the ABC Corporation cell.
% kas stringtokey new_pswd
Converting new_pswd in realm 'ABC.COM' yields
=head1 SEE ALSO
-L<ThisCell (client version)(1)>
-
-L<kas(1)>
+L<ThisCell(5)>,
+L<kas(8)>
=head1 COPYRIGHT
=head1 SYNOPSIS
-
kas unlock -name <I<authentication ID>>
-[B<-admin_username> <I<admin principal to use for authentication>>]
- [B<-password_for_admin> <I<admin password>>] [-cell <I<cell name>>]
- [-servers <I<explicit list of authentication servers>>+]
- [B<-noauth>] [-help]
+
B<kas unlock> B<-name> <I<authentication ID>>
+
[B<-admin_username> <I<admin principal to use for authentication>>]
+ [B<-password_for_admin> <I<admin password>>] [B<-cell> <I<cell name>>]
+ [B<-servers> <I<explicit list of authentication servers>>+]
+ [B<-noauth>] [B<-help>]
-kas u -na <I<authentication ID>>
-[B<-a> <I<admin principal to use for authentication>>]
- [B<-p> <I<admin password>>] [-c <I<cell name>>]
- [B<-s> <I<explicit list of authentication servers>>+] [B<-no>] [-h]
+B<kas u> B<-na> <I<authentication ID>>
+
[B<-a> <I<admin principal to use for authentication>>]
+ [B<-p> <I<admin password>>] [B<-c> <I<cell name>>]
+ [B<-s> <I<explicit list of authentication servers>>+] [B<-no>] [B<-h>]
=head1 DESCRIPTION
-The kas unlock command unlocks the Authentication Database entry
-named by the B<-name> argument. An entry becomes locked when
-the user exceeds the limit on failed authentication attempts, generally by
-providing the wrong password to either an AFS-modified login utility or the
-B<klog> command. Use the B<kas setfields> command to
-set the limit and the lockout time, and the B<kas examine> command to
-examine the settings.
+The B<kas unlock> command unlocks the Authentication Database entry named
+by the B<-name> argument. An entry becomes locked when the user exceeds
+the limit on failed authentication attempts, generally by providing the
+wrong password to either an AFS-modified login utility or the B<klog>
+command. Use the B<kas setfields> command to set the limit and the lockout
+time, and the B<kas examine> command to examine the settings.
-To unlock all locked user accounts at once, shutdown the
-B<kaserver> process on every database server machine, and remove the
-B</usr/afs/local/kaauxdb> file from each one. The
-B<kaserver> process recreates the file as it restarts.
+To unlock all locked user accounts at once, shutdown the B<kaserver>
+process on every database server machine, and remove the
+F</usr/afs/local/kaauxdb> file from each one. The B<kaserver> process
+recreates the file as it restarts.
=head1 OPTIONS
=over 4
-=item -name
+=item B<-name> <I<authentication ID>>
Names the Authentication Database entry to unlock.
-=item -admin_username
+=item B<-admin_username> <I<admin principal>>
Specifies the user identity under which to authenticate with the
-Authentication Server for execution of the command. For more details,
-see the introductory B<kas> reference page.
+Authentication Server for execution of the command. For more details, see
+L<kas(8)>.
-=item -password_for_admin
+=item B<-password_for_admin> <I<admin password>>
-Specifies the password of the command's issuer. If it is
-omitted (as recommended), the B<kas> command interpreter prompts for
-it and does not echo it visibly. For more details, see the introductory
-B<kas> reference page.
+Specifies the password of the command's issuer. If it is omitted (as
+recommended), the B<kas> command interpreter prompts for it and does not
+echo it visibly. For more details, see L<kas(8)>.
-=item -cell
+=item B<-cell> <I<cell name>>
Names the cell in which to run the command. For more details, see
-the introductory B<kas> reference page.
+L<kas(8)>.
-=item -servers
+=item B<-servers> <I<authentication servers>>+
Names each machine running an Authentication Server with which to
-establish a connection. For more details, see the introductory
-B<kas> reference page.
+establish a connection. For more details, see L<kas(8)>.
-=item -noauth
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. For more details, see the introductory B<kas> reference
-page.
+Assigns the unprivileged identity C<anonymous> to the issuer. For more
+details, see L<kas(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
-In the following example, an administrator using the admin
-account unlocks the entry for B<jones>:
+In the following example, an administrator using the C<admin> account
+unlocks the entry for C<jones>:
% kas unlock -name jones -admin_username admin
Administrator's (admin) Password:
=head1 PRIVILEGE REQUIRED
-The issuer must have the C<ADMIN> flag set on his or her
-Authentication Database entry.
+The issuer must have the C<ADMIN> flag set on his or her Authentication
+Database entry.
=head1 SEE ALSO
-L<kas(1)>,
-L<kas_examine(1)>,
-L<kas_setfields(1)>,
+L<kas(8)>,
+L<kas_examine(8)>,
+L<kas_setfields(8)>,
L<klog(1)>
=head1 COPYRIGHT
=head1 DESCRIPTION
-B<kaserver> [B<-noAuth>] [B<-fastKeys>] [-database <I<dbpath>>]
-[B<-localfiles> <I<lclpath>>] [B<-minhours> <I<n>>]
- [B<-servers> <I<serverlist>>] [-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<kaserver> [B<-noAuth>] [B<-fastKeys>] [B<-database> <I<dbpath>>]
+ [B<-localfiles> <I<lclpath>>] [B<-minhours> <I<n>>]
+ [B<-servers> <I<serverlist>>] [B<-enable_peer_stats>]
+ [B<-enable_process_stats>] [B<-help>]
=head1 DESCRIPTION
-The kaserver command initializes the Authentication Server,
-which runs on every database server machine. In the conventional
-configuration, its binary file is located in the B</usr/afs/bin>
-directory on a file server machine.
+The B<kaserver> command initializes the Authentication Server, which runs
+on every database server machine. In the conventional configuration, its
+binary file is located in the F</usr/afs/bin> directory on a file server
+machine.
-The kaserver command is not normally issued at the command shell
-prompt but rather placed into a file server machine's
-B</usr/afs/local/BosConfig> file with the B<bos create>
-command. If it is ever issued at the command shell prompt, the issuer
-must be logged onto a database server machine as the local superuser
-B<root>.
+The B<kaserver> command is not normally issued at the command shell prompt
+but rather placed into a file server machine's F</usr/afs/local/BosConfig>
+file with the B<bos create> command. If it is ever issued at the command
+shell prompt, the issuer must be logged onto a database server machine as
+the local superuser C<root>.
As it initializes, the Authentication Server process creates the two files
-that constitute the Authentication Database, B<kaserver.DB0>
-and B<kaserver.DBSYS1>, in the B</usr/afs/db> directory
-if they do not already exist. Use the commands in the B<kas>
-suite to administer the database.
+that constitute the Authentication Database, F<kaserver.DB0> and
+F<kaserver.DBSYS1>, in the F</usr/afs/db> directory if they do not already
+exist. Use the commands in the B<kas> suite to administer the database.
The Authentication Server is responsible for several aspects of AFS
security, including:
Maintenance of all AFS server encryption keys and user passwords in the
Authentication Database.
-
=item *
Creation of the tickets and tokens that users and servers use to establish
-secure connections. Its Ticket Granting Service (TGS) component
-performs this function.
-
+secure connections. Its Ticket Granting Service (TGS) component performs
+this function.
=back
The Authentication Server records a trace of its activity in the
-B</usr/afs/logs/AuthLog> file. Use the B<bos getlog>
-command to display the contents of the file. Use the B<kdb>
-command to read the protected files associated with the B<AuthLog>
-file, B<AuthLog.dir> and B<AuthLog.pag>.
+F</usr/afs/logs/AuthLog> file. Use the B<bos getlog> command to display
+the contents of the file. Use the B<kdb> command to read the protected
+files associated with the F<AuthLog> file, F<AuthLog.dir> and
+F<AuthLog.pag>.
+
+This command does not use the syntax conventions of the AFS command
+suites. Provide the command name and all option names in full.
=head1 OPTIONS
=over 4
-=item -noAuth
+=item B<-noAuth>
-Assigns the unprivileged identity anonymous to the
-issuer. Thus, it establishes an unauthenticated connection between the
-issuer and the Authentication Server. It is useful only when
-authorization checking is disabled on the database server machine. In
-normal circumstances, the Authentication Server allows only authorized
-(privileged) users to issue commands that affect or contact the Authentication
-Database and will refuse to perform such an action even if the
-B<-noAuth> flag is used.
+Assigns the unprivileged identity C<anonymous> to the issuer. Thus, it
+establishes an unauthenticated connection between the issuer and the
+Authentication Server. It is useful only when authorization checking is
+disabled on the database server machine. In normal circumstances, the
+Authentication Server allows only authorized (privileged) users to issue
+commands that affect or contact the Authentication Database and will
+refuse to perform such an action even if the B<-noAuth> flag is used.
-=item -fastKeys
+=item B<-fastKeys>
Is a test flag for use by the AFS Development staff; it serves no
functional purpose.
-=item -database
+=item B<-database> <I<dbpath>>
Specifies the pathname of an alternate directory in which the
Authentication Database files reside. Provide the complete pathname,
-ending in the base filename to which the B<.DB0> and
-B<.DBSYS1> extensions are appended. For example, the
-appropriate value for the default database files is
-B</usr/afs/db/kaserver>.
+ending in the base filename to which the C<.DB0> and C<.DBSYS1> extensions
+are appended. For example, the appropriate value for the default database
+files is F</usr/afs/db/kaserver>.
-Provide the -localfiles argument along with this one;
-otherwise, the B<-localfiles> argument is also set to the value of
-this argument, which is probably inappropriate.
+Provide the B<-localfiles> argument along with this one; otherwise, the
+B<-localfiles> argument is also set to the value of this argument, which
+is probably inappropriate.
-=item -localfiles
+=item B<-localfiles> <I<lclpath>>
Specifies the pathname of an alternate directory in which the auxiliary
Authentication Database file resides. Provide the complete pathname,
-ending in the base filename to which the B<auxdb> suffix is
-appended. For example, the appropriate value for the default auxiliary
-database file is B</usr/afs/local/kaserver>.
+ending in the base filename to which the C<auxdb> suffix is appended. For
+example, the appropriate value for the default auxiliary database file is
+F</usr/afs/local/kaserver>.
-=item -minhours
+=item B<-minhours> <I<n>>
Specifies the minimum number of hours that must pass between password
-changes made by any regular user. System administrators (with the
-C<ADMIN> flag in their Authentication Database entry) can change
-passwords as often as desired. Setting a minimum time between password
-changes is not recommended.
+changes made by any regular user. System administrators (with the C<ADMIN>
+flag in their Authentication Database entry) can change passwords as often
+as desired. Setting a minimum time between password changes is not
+recommended.
-=item -servers
+=item B<-servers> <I<authentication servers>>+
Names each database server machine running an Authentication Server with
which the local Authentication Server is to synchronize its copy of the
-Authentication Database , rather than with the machines listed in the local
-B</usr/afs/etc/CellServDB> file.
+Authentication Database, rather than with the machines listed in the local
+F</usr/afs/etc/CellServDB> file.
-=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,
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 following B<bos create> command creates a kaserver
-process on B<fs3.abc.com> (the command appears on two
-lines here only for legibility):
+The following B<bos create> command creates a C<kaserver> process on
+C<fs3.abc.com> (the command appears on two lines here only for
+legibility):
% bos create -server fs3.abc.com -instance kaserver \
-type simple -cmd /usr/afs/bin/kaserver
=head1 PRIVILEGE REQUIRED
-The issuer must be logged in as the superuser root on a file
-server machine to issue the command at a command shell prompt. It is
-conventional instead to create and start the process by issuing the B<bos
-create> command.
+The issuer must be logged in as the superuser C<root> on a file server
+machine to issue the command at a command shell prompt. It is conventional
+instead to create and start the process by issuing the B<bos create>
+command.
=head1 SEE ALSO
-L<AuthLog(1)>,
-L<BosConfig(1)>,
-L<CellServDB (server version)(1)>
-
-L<kaserver.DB0 and kaserver.DBSYS1(1)>
-
-L<kaserverauxdb(1)>,
-L<bos(1)>,
-L<bos_create(1)>,
-L<bos_getlog(1)>,
-L<kas(1)>,
-L<kdb(1)>
+L<AuthLog(5)>,
+L<BosConfig(5)>,
+L<CellServDB(5)>,
+L<kaserver.DB0(5)>,
+L<kaserverauxdb(5)>,
+L<bos(8)>,
+L<bos_create(8)>,
+L<bos_getlog(8)>,
+L<kas(8)>,
+L<kdb(8)>
=head1 COPYRIGHT
=head1 SYNOPSIS
-B<kdb> [-dbmfile <I<dbmfile to use (default /usr/afs/logs/AuthLog)>>]
-[B<-key> <I<extract entries that match specified key>>] [B<-help>]
+B<kdb> [B<-dbmfile> <I<dbmfile to use (default /usr/afs/logs/AuthLog)>>]
+ [B<-key> <I<extract entries that match specified key>>] [B<-help>]
=head1 DESCRIPTION
-The kdb command displays the contents of the
-B<AuthLog.dir> and B<AuthLog.pag> files
-associated with the B<AuthLog> file that resides on the local disk, by
-default in the B</usr/afs/logs> directory. The files must exist
-in that directory, which normally implies that the Authentication Server is
-running on the machine. The files contain information on privileged
-actions performed by the Authentication Server.
+The B<kdb> command displays the contents of the F<AuthLog.dir> and
+F<AuthLog.pag> files associated with the F<AuthLog> file that resides on
+the local disk, by default in the F</usr/afs/logs> directory. The files
+must exist in that directory, which normally implies that the
+Authentication Server is running on the machine. The files contain
+information on privileged actions performed by the Authentication Server.
=head1 CAUTIONS
It is possible that on some operating systems that AFS otherwise supports,
-the Authentication Server cannot create the
-B</usr/afs/logs/AuthLog.dir> and
-B</usr/afs/logs/AuthLog.pag> files, making this command
-inoperative. See the I<IBM AFS Release Notes> for
-details.
+the Authentication Server cannot create the F</usr/afs/logs/AuthLog.dir>
+and F</usr/afs/logs/AuthLog.pag> files, making this command
+inoperative. See the I<IBM AFS Release Notes> for details.
=head1 OPTIONS
=over 4
-=item -dbmfile
+=item B<-dbmfile> <I<dbmfile to use>>
-Specifies the pathname of the file to display. Provide either a
-complete pathname, a pathname relative to the B</usr/afs/logs>
-directory, or a filename only, in which case the file must reside in the
-B</usr/afs/logs> directory. Omit this argument to display
-information from the B<AuthLog.dir> and
-B<AuthLog.pag> files in the B</usr/afs/logs>
-directory.
+Specifies the pathname of the file to display. Provide either a complete
+pathname, a pathname relative to the F</usr/afs/logs> directory, or a
+filename only, in which case the file must reside in the F</usr/afs/logs>
+directory. Omit this argument to display information from the
+F<AuthLog.dir> and F<AuthLog.pag> files in the F</usr/afs/logs> directory.
-=item -key
+=item B<-key> <I<extract entries that match specified key>>
Specifies each entry to be displayed from the indicated file.
-=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 first line of output indicates the location of the files from which the
-subsequent information is derived:
+The first line of output indicates the location of the files from which
+the subsequent information is derived:
- Printing all entries found in I<file_location>
+ Printing all entries found in <file_location>
-Each entry then includes the following two fields, separated by a
-colon:
+Each entry then includes the following two fields, separated by a colon:
=over 4
-=item C<user/server
->
+=item user/server
Identifies the user requesting the corresponding service and the server
-that performed that service. In cases where no user is directly
-involved, only the server appears; in cases where no server is directly
-involved, only the user appears.
+that performed that service. In cases where no user is directly involved,
+only the server appears; in cases where no server is directly involved,
+only the user appears.
-=item C<service
->
+=item service
Identifies one of the following actions or services performed by the user
-or server process.
+or server process.
=over 4
=item *
-C<auth>: Obtained a ticket-granting ticket
-
+C<auth>: Obtained a ticket-granting ticket.
=item *
-C<chp>: Changed a user password
-
+C<chp>: Changed a user password.
=item *
-C<cruser>: Created a user entry in the Authentication
-Database
-
+C<cruser>: Created a user entry in the Authentication Database.
=item *
-C<delu>: Deleted a user entry from the Authentication
-Database
-
+C<delu>: Deleted a user entry from the Authentication Database.
=item *
-C<gtck>: Obtained a ticket other than a ticket-granting
-ticket
-
+C<gtck>: Obtained a ticket other than a ticket-granting ticket.
=item *
-C<setf>: Set fields in an Authentication Database entry
-
+C<setf>: Set fields in an Authentication Database entry.
=item *
-C<unlok>: Unlocked an Authentication Database entry
-
+C<unlok>: Unlocked an Authentication Database entry.
=back
=head1 EXAMPLES
-The following example shows the output of the kdb command in the
-
ABC Corporation cell (B<abc.com>):
+The following example shows the output of the B<kdb> command in the ABC
+
Corporation cell (C<abc.com>):
% kdb
Printing all entries found in /usr/afs/logs/AuthLog
=head1 PRIVILEGE REQUIRED
-The issuer must be logged in as the local superuser root.
+The issuer must be logged in as the local superuser C<root>.
=head1 SEE ALSO
-L<AuthLog.dir,_AuthLog.pag(1)>,
-L<bos_getlog(1)>,
-L<kaserver(1)>
+L<AuthLog.dir(5)>,
+L<bos_getlog(8)>,
+L<kaserver(8)>
=head1 COPYRIGHT
kpwvalid - Checks quality of new password
+=head1 SYNOPSIS
+
+B<kpwvalid>
+
=head1 DESCRIPTION
-The kpwvalid command checks the quality of a new password passed
-to it from the B<kpasswd> or B<kas setpassword>
-command. It is optional. If it exists, it must reside in the
-same AFS directory as the binaries for the B<kpasswd> and
-B<kas> command suites (create a symbolic link from the client
-machine's local disk to this directory). The directory's ACL
-must extend the B<a> (B<administer>) and B<w>
-(B<write>) permissions to the B<system:administrators>
-group only. These requirements prevent unauthorized users from
-substituting a spurious B<kpwvalid> binary.
-
-The AFS distribution includes an example kpwvalid program that
-checks that the password is at least eight characters long; the code for
-it appears in the following B<Examples> section.
+The B<kpwvalid> command checks the quality of a new password passed to it
+from the B<kpasswd> or B<kas setpassword> command. It is optional. If it
+exists, it must reside in the same AFS directory as the binaries for the
+B<kpasswd> and B<kas> command suites (create a symbolic link from the
+client machine's local disk to this directory). The directory's ACL must
+extend the C<a> (administer) and C<w> (write) permissions to the
+system:administrators group only. These requirements prevent unauthorized
+users from substituting a spurious B<kpwvalid> binary.
+
+The AFS distribution includes an example B<kpwvalid> program that checks
+that the password is at least eight characters long; the code for it
+appears in L<EXAMPLES> below.
The script or program must accept a sequence of password strings, one per
-line, on the standard input stream. The first is the current password
-and is ignored. Each subsequent string is a candidate password to be
+line, on the standard input stream. The first is the current password and
+is ignored. Each subsequent string is a candidate password to be
checked. The program must write the following to the standard output
stream for each one:
=item *
-C<0> (zero) and a newline character to indicate that the password
-is acceptable
-
+C<0> (zero) and a newline character to indicate that the password is
+acceptable.
=item *
A non-zero decimal number and a newline character to indicate that the
-password is not acceptable
-
+password is not acceptable.
=back
=head1 SEE ALSO
-L<kas_setpassword(1)>,
+L<kas_setpassword(8)>,
L<kpasswd(1)>
=head1 COPYRIGHT
=head1 SYNOPSIS
-B<package> [B<initcmd>] [-config <I<base name of configuration file>>]
-[B<-fullconfig> <I<full name of configuration file, or stdin for standard input>>]
- [B<-overwrite>] [B<-noaction>] [B<-verbose>] [B<-silent>] [-rebootfiles]
- [B<-debug>] [-help]
+B<package> [I<initcmd>] [B<-config> <I<base name of configuration file>>]
+ [B<-fullconfig> <I<full name of configuration file, or stdin>>]
+ [B<-overwrite>] [B<-noaction>] [B<-verbose>] [B<-silent>]
+ [B<-rebootfiles>] [B<-debug>] [B<-help>]
-B<package> [B<i>] [-c <I<base name of configuration file>>]
-[B<-f> <I<full name of configuration file, or stdin for standard input>>]
- [B<-o>] [B<-n>] [B<-v>] [B<-s>] [B<-r>] [B<-d>] [-h]
+B<package> [B<i>] [B<-c> <I<base name of configuration file>>]
+ [B<-f> <I<full name of configuration file, or stdin>>]
+ [B<-o>] [B<-n>] [B<-v>] [B<-s>] [B<-r>] [B<-d>] [B<-h>]
=head1 DESCRIPTION
-The package command configures the machine's local disk to
-comply with the instructions in the configuration file named by the
-B<-config> or B<-fullconfig> argument.
+The B<package> command configures the machine's local disk to comply with
+the instructions in the configuration file named by the B<-config> or
+B<-fullconfig> argument.
-By default, the package command alters any existing local disk
-element whose contents or configuration does not match the element defined in
-the configuration file. For example, if a configuration file
-B<D> instruction defines a directory that has the same name as a
-symbolic link on the local disk, the B<package> command replaces the
-symbolic link with the directory. The B<F> and B<L>
-instructions include an optional I<update_code> field that alters this
-behavior.
+By default, the package command alters any existing local disk element
+whose contents or configuration does not match the element defined in the
+configuration file. For example, if a configuration file C<D> instruction
+defines a directory that has the same name as a symbolic link on the local
+disk, the B<package> command replaces the symbolic link with the
+directory. The C<F> and C<L> instructions include an optional
+I<update_code> field that alters this behavior.
-Also by default, the package command takes no action on elements
-on the local disk that are not mentioned in the configuration file. Use
-the B<D> instruction's B<R> update code to remove files
-from the disk directory that are not mentioned in the configuration
-file.
+Also by default, the package command takes no action on elements on the
+local disk that are not mentioned in the configuration file. Use the C<D>
+instruction's C<R> update code to remove files from the disk directory
+that are not mentioned in the configuration file.
-Before running the package command, the administrator must
-create the template file and other files on the local disk. For
-instructions, see the I<IBM AFS Administration Guide>.
+Before running the package command, the administrator must create the
+template file and other files on the local disk. For instructions, see the
+I<IBM AFS Administration Guide>.
-It is not possible to configure a remote client machine's disk using
-this command.
+It is not possible to configure a remote client machine's disk using this
+command.
=head1 CAUTIONS
-The package command interpreter exits without executing any
-instruction if there are any syntax errors or incorrect values in the
-configuration file.
+The package command interpreter exits without executing any instruction if
+there are any syntax errors or incorrect values in the configuration file.
=head1 OPTIONS
=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 -config
+=item B<-config> <I<base name of configuration file>>
Specifies the pathname of the configuration file to use, ending in the
file's base name, which omits the suffix that indicates the machine
-type. The B<package> command determines the machine's
-system type name and automatically appends it to the base name. An
-example of the proper value for this argument is B<staff> rather than
-B<staff.rs_aix42>. Partial pathnames are interpreted
-relative to the current working directory.
+type. The B<package> command determines the machine's system type name and
+automatically appends it to the base name. An example of the proper value
+for this argument is C<staff> rather than C<staff.rs_aix42>. Partial
+pathnames are interpreted relative to the current working directory.
-Provide this argument or the -fullconfig argument.
+Provide this argument or the B<-fullconfig> argument.
-=item -fullconfig
+=item B<-fullconfig> <I<full name of configuration file, or stdin>>
Specifies the configuration file to use. Two types of values are
-acceptable:
+acceptable:
=over 4
=item *
The full pathname of the configuration file to use, complete with an
-extension indicating the machine type (examples:
-B<staff.rs_aix42>, B<admin.sun4x_56>).
-
+extension indicating the machine type (examples: C<staff.rs_aix42>,
+C<admin.sun4x_56>).
=item *
-The string stdin to indicate that the issuer is providing
-configuration information via the standard input stream, either by piping in
-the contents of a file, or by typing configuration lines at the shell.
-In the latter case, type B<<Ctrl-d>> to conclude the input.
-
+The string C<stdin> to indicate that the issuer is providing configuration
+information via the standard input stream, either by piping in the
+contents of a file, or by typing configuration lines at the shell. In the
+latter case, type Ctrl-D to conclude the input.
=back
-Provide this argument or the -config argument.
+Provide this argument or the B<-config> argument.
-=item -overwrite
+=item B<-overwrite>
Overwrites elements on the local disk with the source version indicated in
-the configuration file, even if the owner B<write> (B<w>) mode
-bit is turned on the disk element. Files protected by the B<I>
-update code on an B<F> line in the configuration file are not
-overwritten.
+the configuration file, even if the owner write (C<w>) mode bit is turned
+on the disk element. Files protected by the C<I> update code on an C<F>
+line in the configuration file are not overwritten.
-=item -noaction
+=item B<-noaction>
Checks the sequence of operations to be performed when the command
actually runs and reports any problems that the B<package> command
-interpreter expects to encounter. No elements on the local disk or in
-AFS are changed. If the B<-verbose> flag is also provided, the
-trace includes all actions to be performed as well as anticipated
-errors.
+interpreter expects to encounter. No elements on the local disk or in AFS
+are changed. If the B<-verbose> flag is also provided, the trace includes
+all actions to be performed as well as anticipated errors.
-=item -silent
+=item B<-silent>
Suppresses some of the trace messages sent to the standard output stream
by default. The output still reports major problems.
-=item -verbose
+=item B<-verbose>
-Produces on the standard output stream a detailed trace of the
-command's execution. If this argument is omitted, only warnings
-and error messages appear.
+Produces on the standard output stream a detailed trace of the command's
+execution. If this argument is omitted, only warnings and error messages
+appear.
-=item -rebootfiles
+=item B<-rebootfiles>
-Prevents overwriting of any file marked with the Q update code
-on an B<F> line in the configuration file. This effectively
-prevents the machine from rebooting automatically again when the
-B<package> command is invoked in the machine's AFS initialization
-file.
+Prevents overwriting of any file marked with the C<Q> update code on an
+C<F> line in the configuration file. This effectively prevents the machine
+from rebooting automatically again when the B<package> command is invoked
+in the machine's AFS initialization file.
-=item -debug
+=item B<-debug>
Enables debugging output, which is directed to the standard output stream
by default. By default, no debugging output is produced.
-=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
-This command is usually invoked in a client machine's AFS
-initialization file (B</etc/rc> or equivalent), rather than issued at
-the command shell prompt.
+This command is usually invoked in a client machine's AFS initialization
+file (F</etc/rc> or equivalent), rather than issued at the command shell
+prompt.
-The following command invokes the version of the staff
-configuration file appropriate for this machine's system type, and
-produces verbose output.
+The following command invokes the version of the staff configuration file
+appropriate for this machine's system type, and produces verbose output.
# /etc/package -c staff -v
-The following example uses the configuration file whose basename is defined
-in the B</.package> file on the local machine. This
-method enables the administrator to use the same B<package> command in
-every machine's AFS initialization file but still customize configuration
-by putting the appropriate basename in the B</.package>
-file.
+The following example uses the configuration file whose basename is
+defined in the F</.package> file on the local machine. This method enables
+the administrator to use the same B<package> command in every machine's
+AFS initialization file but still customize configuration by putting the
+appropriate basename in the F</.package> file.
# /etc/package -c `cat /.package` -v
=head1 PRIVILEGE REQUIRED
-The issuer must be logged in as the local superuser root.
+The issuer must be logged in as the local superuser C<root>.
=head1 SEE ALSO
-L<package Configuration File(1)>
+L<package(5)>
=head1 COPYRIGHT
+++ /dev/null
-=head1 NAME
-
-package apropos - Displays each help entry containing a keyword string
-
-=head1 SYNOPSIS
-
-B<package apropos> [B<-topic> <I<help string>>] [-help]
-
-B<package a> [B<-t> <I<help string>>] [-h]
-
-=head1 DESCRIPTION
-
-The package apropos command displays the first line of the
-online help entry for any B<package> 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 package help
-command.
-
-=head1 OPTIONS
-
-=over 4
-
-=item -topic
-
-Specifies the keyword string to match, in lowercase letters only.
-If the string is more than a single word, surround it with double quotes ("")
-or other delimiters.
-
-=item -help
-
-Prints the online help for this command. All other valid options
-are ignored.
-
-=back
-
-=head1 OUTPUT
-
-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<package> command where the string specified with the
-B<-topic> argument is part of the command name or first line.
-
-=head1 EXAMPLES
-
-The following command lists all package commands that include
-the word B<help> in their names or short descriptions:
-
- % package apropos help
- apropos: search by help text
- help: get help on commands
-
-=head1 PRIVILEGE REQUIRED
-
-None
-
-=head1 SEE ALSO
-
-L<package(1)>,
-L<package_help(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.
+++ /dev/null
-=head1 NAME
-
-package help - Displays the syntax of specified package commands or lists
-functional descriptions of all B<package> commands
-
-=head1 SYNOPSIS
-
-B<package help> [B<-topic> <I<help string>>+] [-help]
-
-B<package h> [B<-t> <I<help string>>+] [-h]
-
-=head1 DESCRIPTION
-
-The package help command displays the complete online help entry
-(short description and syntax statement) for each command 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<package>
-command.
-
-To list every package command whose name or short description
-includes a specified keyword, use the B<package apropos>
-command.
-
-=head1 OPTIONS
-
-=over 4
-
-=item -topic
-
-Indicates each command for which to display the complete online help
-entry. Omit the B<package> part of the command name, providing
-only the operation code (for example, specify B<initcmd>, not
-B<package initcmd>). If this argument is omitted, the output
-briefly describes every B<package> command.
-
-=item -help
-
-Prints the online help for this command. All other valid options
-are ignored.
-
-=back
-
-=head1 OUTPUT
-
-The online help entry for each package command consists of the
-following two or three lines:
-
-=over 4
-
-=item *
-
-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.
-
-
-=back
-
-=head1 EXAMPLES
-
-The following command displays the online help entry for the package
-initcmd command:
-
- % package help initcmd
- package initcmd: initialize the program
- Usage: package [initcmd] [-config <base name of configuration file>]
- [-fullconfig <full name of configuration file, or stdin for standard input>]
- [-overwrite] [-noaction] [-verbose] [-silent] [-rebootfiles]
- [-debug] [-help]
-
-=head1 PRIVILEGE REQUIRED
-
-None
-
-=head1 SEE ALSO
-
-L<package(1)>,
-L<package_apropos(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.
+++ /dev/null
-=head1 NAME
-
-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.
-
-=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.
-
-=head1 OPTIONS
-
-=over 4
-
-=item I<config file
->
-
-Specifies the package configuration file to validate.
-
-=back
-
-=head1 EXAMPLES
-
-The following example tests the validity of the package
-configuration file I<staff.sun4x_56>.
-
- % package_test staff.sun4x_56
-
-=head1 PRIVILEGE REQUIRED
-
-None
-
-=head1 SEE ALSO
-
-L<package Configuration File(1)>
-
-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.
=head1 SYNOPSIS
-B<prdb_check -database> <I<ptdb_file>> [B<-uheader>] [B<-pheader>] [-entries]
-[B<-verbose>] [B<-help>]
+B<prdb_check> B<-database> <I<ptdb file>> [B<-uheader>] [B<-pheader>]
+ [B<-entries>] [B<-verbose>] [B<-help>]
-B<prdb_check -d> <I<ptdb_file>> [B<-u>] [B<-p>] [B<-e>] [B<-v>] [-h]
+B<prdb_check> B<-d> <I<ptdb file>> [B<-u>] [B<-p>] [B<-e>] [B<-v>] [B<-h>]
=head1 DESCRIPTION
-The prdb_check command checks the integrity of the Protection
-Database, reporting any errors or corruption it finds. If there are
-problems, do not issue any B<pts> commands until the database is
-repaired.
+The B<prdb_check> command checks the integrity of the Protection Database,
+reporting any errors or corruption it finds. If there are problems, do not
+issue any B<pts> commands until the database is repaired.
=head1 CAUTIONS
The results can be unpredictable if the Protection Server makes changes to
the Protection Database while this command is running. Use the B<bos
-shutdown> command to shutdown the local B<ptserver> process
-before running this command, or before creating a second copy of the
-B<prdb.DB0> file (with a different name) on which to run the
-command.
+shutdown> command to shutdown the local B<ptserver> process before running
+this command, or before creating a second copy of the F<prdb.DB0> file
+(with a different name) on which to run the command.
=head1 OPTIONS
=over 4
-=item -database
+=item B<-database> <I<ptdb file>>
-Names the Protection Database (copy of the prdb.DB0
-file) to check. If the current working directory is not the location of
-the file, provide a pathname, either full or relative to the current working
-directory.
+Names the Protection Database (copy of the F<prdb.DB0> file) to check. If
+the current working directory is not the location of the file, provide a
+pathname, either full or relative to the current working directory.
-=item -uheader
+=item B<-uheader>
-Displays information which Ubik maintains in the database's
-header.
+Displays information which Ubik maintains in the database's header.
-=item -pheader
+=item B<-pheader>
Displays information which the Protection Server maintains in the
database's header.
-=item -entries
+=item B<-entries>
-Outputs every entry in the database. Some of the information is
-
similar to that returned by the B<pts examine> command.
+Outputs every entry in the database. Some of the information is similar to
+that returned by the B<pts examine> command.
-=item -verbose
+=item B<-verbose>
Reports additional information about the database, including the number of
-entries in the database and a trace of the internal database structures the
-command is verifying.
+entries in the database and a trace of the internal database structures
+the command is verifying.
-=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 there are errors in the database, the output always reports them on the
-standard error stream. If any options other than B<-database>
-or B<-help> are provided, the output written to the standard output
-stream includes additional information as described for each option in the
-preceding B<Options> section of this reference page. The output
-is intended for debugging purposes and is meaningful to someone familiar with
-the internal structure of the Protection Database.
+standard error stream. If any options other than B<-database> or B<-help>
+are provided, the output written to the standard output stream includes
+additional information as described for each option in L<OPTIONS>. The
+output is intended for debugging purposes and is meaningful to someone
+familiar with the internal structure of the Protection Database.
=head1 PRIVILEGE REQUIRED
-The issuer must be logged in as the local superuser root.
+The issuer must be logged in as the local superuser C<root>.
=head1 SEE ALSO
-L<prdb.DB0 and prdb.DBSYS1(1)>
-
-L<bos_shutdown(1)>,
+L<prdb.DB0(5)>,
+L<bos_shutdown(8)>,
L<pts_examine(1)>,
-L<ptserver(1)>
+L<ptserver(8)>
=head1 COPYRIGHT
=head1 SYNOPSIS
-B<ptserver> [B<-database> <I<db path>>] [B<-p> <I<number of processes>>] [-rebuildDB]
-[B<-enable_peer_stats>] [B<-enable_process_stats>] [B<-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<ptserver> [B<-database> <I<db path>>] [B<-p> <I<number of processes>>]
+ [B<-rebuildDB>] [B<-enable_peer_stats>] [B<-enable_process_stats>]
+ [B<-help>]
=head1 DESCRIPTION
-The ptserver command initializes the Protection Server, which
-must run on every database server machine. In the conventional
-configuration, its binary file is located in the B</usr/afs/bin>
-directory on a file server machine.
+The B<ptserver> command initializes the Protection Server, which must run
+on every database server machine. In the conventional configuration, its
+binary file is located in the F</usr/afs/bin> directory on a file server
+machine.
-The ptserver command is not normally issued at the command shell
-prompt, but rather placed into a database server machine's
-B</usr/afs/local/BosConfig> file with the B<bos create>
-command. If it is ever issued at the command shell prompt, the issuer
-must be logged onto a file server machine as the local superuser
-B<root>.
+The ptserver command is not normally issued at the command shell prompt,
+but rather placed into a database server machine's
+F</usr/afs/local/BosConfig> file with the B<bos create> command. If it is
+ever issued at the command shell prompt, the issuer must be logged onto a
+file server machine as the local superuser C<root>.
The Protection Server performs the following tasks:
=item *
Maintains the Protection Database, which contains entries for every user
-and group in the cell. Use the B<pts> commands to administer
-the database.
-
+and group in the cell. Use the B<pts> commands to administer the database.
=item *
Allocates AFS IDs for new user, machine and group entries and maps each ID
to the corresponding name.
-
=item *
Generates a current protection subgroup (CPS) at the File Server's
-request. The CPS lists all groups to which a user or machine
-belongs.
-
+request. The CPS lists all groups to which a user or machine belongs.
=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 OPTIONS
=over 4
-=item -database
+=item B<-database> <I<db path>>
Specifies the pathname of an alternate directory in which the Protection
-Database files reside. Provide the complete pathname, ending in the
-base filename to which the B<.DB0> and
-B<.DBSYS1> extensions are appended. For example, the
-appropriate value for the default database files is
-B</usr/afs/db/prdb>.
+Database files reside. Provide the complete pathname, ending in the base
+filename to which the C<.DB0> and C<.DBSYS1> extensions are appended. For
+example, the appropriate value for the default database files is
+F</usr/afs/db/prdb>.
-=item -p
+=item B<-p> <I<number of processes>>
-Sets the number of server lightweight processes (LWPs) to run.
-Provide a positive integer from the range B<3> to
-B<16>. The default value is 3.
+Sets the number of server lightweight processes (LWPs) to run. Provide a
+positive integer from the range C<3> to C<16>. The default value is C<3>.
-=item -rebuildDB
+=item B<-rebuildDB>
Rebuilds the Protection Database at the beginning of Protection Server
initialization. Use this argument only in consultation with AFS
Development or Product Support.
-=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,
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 following B<bos create> command creates a ptserver
-process on the machine B<fs3.abc.com>. The
-command appears here on multiple lines only for legibility.
+The following B<bos create> command creates a C<ptserver> process on the
+machine C<fs3.abc.com>. The command appears here on multiple lines only
+for legibility.
- % bos create -server fs3.abc.com -instance ptserver \
+ % bos create -server fs3.abc.com -instance ptserver \
-type simple -cmd /usr/afs/bin/ptserver
=head1 PRIVILEGE REQUIRED
-The issuer must be logged in as the superuser root on a file
-server machine to issue the command at a command shell prompt. It is
-conventional instead to create and start the process by issuing the B<bos
-create> command.
+The issuer must be logged in as the superuser C<root> on a file server
+machine to issue the command at a command shell prompt. It is conventional
+instead to create and start the process by issuing the B<bos create>
+command.
=head1 SEE ALSO
-L<BosConfig(1)>,
-L<prdb.DB0 and prdb.DBSYS1(1)>
-
-L<bos_create(1)>,
-L<bos_getlog(1)>,
+L<BosConfig(5)>,
+L<prdb.DB0(5)>,
+L<bos_create(8)>,
+L<bos_getlog(8)>,
L<pts(1)>
=head1 COPYRIGHT
=head1 SYNOPSIS
-B<salvager> [B<initcmd>] [-partition <I<Name of partition to salvage>>]
-[B<-volumeid> <I<Volume Id to salvage>>] [B<-debug>]
- [B<-nowrite>] [B<-inodes>] [B<-force>] [-oktozap]
- [B<-rootinodes>] [B<-salvagedirs>] [-blockreads]
- [-parallel <I<# of max parallel partition salvaging>>]
- [-tmpdir <I<Name of dir to place tmp files>>]
- [B<-showlog>] [B<-showsuid>] [-showmounts]
- [B<-orphans> <B<ignore> | B<remove> | B<attach>>] [-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<salvager> [I<initcmd>] [B<-partition> <I<name of partition to salvage>>]
+ [B<-volumeid> <I<volume id to salvage>>] [B<-debug>] [B<-nowrite>]
+ [B<-inodes>] [B<-force>] [B<-oktozap>] [B<-rootinodes>]
+ [B<-salvagedirs>] [B<-blockreads>]
+ [B<-parallel> <I<# of max parallel partition salvaging>>]
+ [B<-tmpdir> <I<name of dir to place tmp files>>]
+ [B<-showlog>] [B<-showsuid>] [B<-showmounts>]
+ [B<-orphans> (ignore | remove | attach)] [B<-help>]
=head1 DESCRIPTION
-The salvager command initializes the Salvager component of the
-B<fs> process. In the conventional configuration, its binary
-file is located in the B</usr/afs/bin> directory on a file server
-machine.
+The B<salvager> command initializes the Salvager component of the C<fs>
+process. In the conventional configuration, its binary file is located in
+the F</usr/afs/bin> directory on a file server machine.
The Salvager restores internal consistency to corrupted read/write volumes
-on the local file server machine where possible. For read-only or
-backup volumes, it inspects only the volume header:
+on the local file server machine where possible. For read-only or backup
+volumes, it inspects only the volume header:
=over 4
If the volume header is corrupted, the Salvager removes the volume
completely and records the removal in its log file,
-B</usr/afs/logs/SalvageLog>. Issue the B<vos release>
-or B<vos backup> command to create the read-only or backup volume
-again.
-
+F</usr/afs/logs/SalvageLog>. Issue the B<vos release> or B<vos backup>
+command to create the read-only or backup volume again.
=item *
If the volume header is intact, the Salvager skips the volume (does not
-check for corruption in the contents). However, if the File Server
-notices corruption as it initializes, it sometimes refuses to attach the
-volume or bring it online. In this case, it is simplest to remove the
-volume by issuing the B<vos remove> or B<vos zap>
-command. Then issue the B<vos release> or B<vos backup>
-command to create it again.
-
+check for corruption in the contents). However, if the File Server notices
+corruption as it initializes, it sometimes refuses to attach the volume or
+bring it online. In this case, it is simplest to remove the volume by
+issuing the B<vos remove> or B<vos zap> command. Then issue the B<vos
+release> or B<vos backup> command to create it again.
=back
-Unlike other server process initialization commands, the
-B<salvager> command is designed to be issued at the command shell
-prompt, as well as being placed into a file server machine's
-B</usr/afs/local/BosConfig> file with the B<bos create>
-command. It is also possible to invoke the Salvager remotely by issuing
-the B<bos salvage> command.
+Unlike other server process initialization commands, the B<salvager>
+command is designed to be issued at the command shell prompt, as well as
+being placed into a file server machine's F</usr/afs/local/BosConfig> file
+with the B<bos create> command. It is also possible to invoke the Salvager
+remotely by issuing the B<bos salvage> command.
-Combine the command's options as indicated to salvage different
-numbers of read/write volumes:
+Combine the command's options as indicated to salvage different numbers of
+read/write volumes:
=over 4
=item *
-To salvage all volumes on the file server machine, provide no
-arguments. No volumes on the machine are accessible to Cache Managers
-during the salvage, because the BOS Server stops the File Server and Volume
-Server processes while the Salvager runs.
-
+To salvage all volumes on the file server machine, provide no arguments.
+No volumes on the machine are accessible to Cache Managers during the
+salvage, because the BOS Server stops the File Server and Volume Server
+processes while the Salvager runs.
=item *
-To salvage all of the volumes on one partition, provide the
-B<-partition> argument. As for a salvage of all volumes on the
-machine, no volumes on the machine are accessible to Cache Managers during the
-salvage operation.
-
+To salvage all of the volumes on one partition, provide the B<-partition>
+argument. As for a salvage of all volumes on the machine, no volumes on
+the machine are accessible to Cache Managers during the salvage operation.
=item *
-To salvage only one volume, combine the -partition and
-B<-volumeid> arguments. Only that volume is inaccessible to
-Cache Managers, because the BOS Server does not shutdown the File Server and
-Volume Server processes.
-
+To salvage only one volume, combine the B<-partition> and B<-volumeid>
+arguments. Only that volume is inaccessible to Cache Managers, because the
+BOS Server does not shutdown the File Server and Volume Server processes.
=back
The Salvager normally salvages only those read/write volumes that are
-marked as having been active when a crash occurred. To have it salvage
-all relevant read/write volumes, add the B<-force> flag.
+marked as having been active when a crash occurred. To have it salvage all
+relevant read/write volumes, add the B<-force> flag.
-The Salvager normally creates new inodes as it repairs damage. If
-the partition is so full that there is no room for new inodes, use the
+The Salvager normally creates new inodes as it repairs damage. If the
+partition is so full that there is no room for new inodes, use the
B<-nowrite> argument to bringing undamaged volumes online without
-attempting to salvage damaged volumes. Then use the B<vos move>
-command to move one or more of the undamaged volumes to other partitions,
-freeing up the space that the Salvager needs to create new inodes.
-
-By default, multiple Salvager subprocesses run in parallel: one for
-each partition up to four, and four subprocesses for four or more
-partitions. To increase or decrease the number of subprocesses running
-in parallel, provide a positive integer value for the B<-parallel>
-argument.
-
-If there is more than one server partition on a physical disk, the Salvager
-by default salvages them serially to avoid the inefficiency of constantly
-moving the disk head from one partition to another. However, this
-strategy is often not ideal if the partitions are configured as logical
-volumes that span multiple disks. To force the Salvager to salvage
-logical volumes in parallel, provide the string B<all> as the value
-for the B<-parallel> argument. Provide a positive integer to
-specify the number of subprocesses to run in parallel (for example,
-B<-parallel 5all> for five subprocesses), or omit the integer to run
-up to four subprocesses, depending on the number of logical volumes being
-salvaged.
-
-The Salvager creates temporary files as it runs, by default writing them to
-the partition it is salvaging. The number of files can be quite large,
-and if the partition is too full to accommodate them, the Salvager terminates
-without completing the salvage operation (it always removes the temporary
-files before exiting). Other Salvager subprocesses running at the same
-time continue until they finish salvaging all other partitions where there is
-enough disk space for temporary files. To complete the interrupted
-salvage, reissue the command against the appropriate partitions, adding the
-B<-tmpdir> argument to redirect the temporary files to a local disk
-directory that has enough space.
-
-The -orphans argument controls how the Salvager handles orphaned
-files and directories that it finds on server partitions it is
-salvaging. An I<orphaned> element is completely inaccessible
-because it is not referenced by the vnode of any directory that can act as its
-parent (is higher in the filespace). Orphaned objects occupy space on
-the server partition, but do not count against the volume's quota.
+attempting to salvage damaged volumes. Then use the B<vos move> command to
+move one or more of the undamaged volumes to other partitions, freeing up
+the space that the Salvager needs to create new inodes.
+
+By default, multiple Salvager subprocesses run in parallel: one for each
+partition up to four, and four subprocesses for four or more
+partitions. To increase or decrease the number of subprocesses running in
+parallel, provide a positive integer value for the B<-parallel> argument.
+
+If there is more than one server partition on a physical disk, the
+Salvager by default salvages them serially to avoid the inefficiency of
+constantly moving the disk head from one partition to another. However,
+this strategy is often not ideal if the partitions are configured as
+logical volumes that span multiple disks. To force the Salvager to salvage
+logical volumes in parallel, provide the string C<all> as the value for
+the B<-parallel> argument. Provide a positive integer to specify the
+number of subprocesses to run in parallel (for example, C<-parallel 5all>
+for five subprocesses), or omit the integer to run up to four
+subprocesses, depending on the number of logical volumes being salvaged.
+
+The Salvager creates temporary files as it runs, by default writing them
+to the partition it is salvaging. The number of files can be quite large,
+and if the partition is too full to accommodate them, the Salvager
+terminates without completing the salvage operation (it always removes the
+temporary files before exiting). Other Salvager subprocesses running at
+the same time continue until they finish salvaging all other partitions
+where there is enough disk space for temporary files. To complete the
+interrupted salvage, reissue the command against the appropriate
+partitions, adding the B<-tmpdir> argument to redirect the temporary files
+to a local disk directory that has enough space.
+
+The B<-orphans> argument controls how the Salvager handles orphaned files
+and directories that it finds on server partitions it is salvaging. An
+I<orphaned> element is completely inaccessible because it is not
+referenced by the vnode of any directory that can act as its parent (is
+higher in the filespace). Orphaned objects occupy space on the server
+partition, but do not count against the volume's quota.
To generate a list of all mount points that reside in one or more volumes,
-rather than actually salvaging them, include the B<-showmounts>
-flag.
+rather than actually salvaging them, include the B<-showmounts> flag.
+
+This command does not use the syntax conventions of the AFS command
+suites. Provide the command name and all option names in full.
=head1 OPTIONS
=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 -partition
+=item B<-partition> <I<name of partition to salvage>>
-Specifies the name of the partition to salvage. Specify the full
-partition name using the form B</vicep>I<x> or
-B</vicep>I<xx>. Omit this argument to salvage every
-partition on the file server machine.
+Specifies the name of the partition to salvage. Specify the full partition
+name using the form F</vicepI<x>> or F</vicepI<xx>>. Omit this argument to
+salvage every partition on the file server machine.
-=item -volumeid
+=item B<-volumeid> <I<volume id to salvage>>
-Specifies the volume ID of a specific read/write volume to salvage.
-The B<-partition> argument must be provided along with this one and
-specify the volume's actual site.
+Specifies the volume ID of a specific read/write volume to salvage. The
+B<-partition> argument must be provided along with this one and specify
+the volume's actual site.
-=item -debug
+=item B<-debug>
Allows only one Salvager subprocess to run at a time, regardless of the
-setting of the B<-parallel> option. Include it when running the
-Salvager in a debugger to make the trace easier to interpret.
+setting of the B<-parallel> option. Include it when running the Salvager
+in a debugger to make the trace easier to interpret.
-=item -nowrite
+=item B<-nowrite>
Brings all undamaged volumes online without attempting to salvage any
damaged volumes.
-=item -inodes
+=item B<-inodes>
-Records in the /usr/afs/logs/SalvageLog file a list of all AFS
-inodes that the Salvager modified.
+Records in the F</usr/afs/logs/SalvageLog> file a list of all AFS inodes
+that the Salvager modified.
-=item -force
+=item B<-force>
Inspects all volumes for corruption, not just those that are marked as
having been active when a crash occurred.
-=item -oktozap
+=item B<-oktozap>
-Removes a volume that is so damaged that even issuing the vos
-zap command with the B<-force> flag is ineffective. Use
-this argument only in consultation with AFS Development or Product
-Support. Combine it with the B<-partition> and
-B<-volumeid> arguments to identify the volume to remove.
+Removes a volume that is so damaged that even issuing the B<vos zap>
+command with the B<-force> flag is ineffective. Use this argument only in
+consultation with AFS Development or Product Support. Combine it with the
+B<-partition> and B<-volumeid> arguments to identify the volume to remove.
-=item -rootinodes
+=item B<-rootinodes>
-Records in the /usr/afs/logs/SalvageLog file a list of all AFS
-inodes owned by the local superuser B<root>.
+Records in the F</usr/afs/logs/SalvageLog> file a list of all AFS inodes
+owned by the local superuser C<root>.
-=item -salvagedirs
+=item B<-salvagedirs>
Salvages entire directory structures, even if they do not appear to be
damaged. By default, the Salvager salvages a directory only if it is
flagged as corrupted.
-=item -blockreads
+=item B<-blockreads>
Forces the Salvager to read a partition one disk block (512 bytes) at a
time and to skip any blocks that are too badly damaged to be salvaged.
This allows it to salvage as many volumes as possible. By default, the
-Salvager reads large disk blocks, which can cause it to exit prematurely if it
-encounters disk errors. Use this flag if the partition to be salvaged
-has disk errors.
+Salvager reads large disk blocks, which can cause it to exit prematurely
+if it encounters disk errors. Use this flag if the partition to be
+salvaged has disk errors.
-=item -parallel
+=item B<-parallel> <I<# of max parallel partition salvaging>>
-Specifies the maximum number of Salvager subprocesses to run in
-parallel. Provide one of three values:
+Specifies the maximum number of Salvager subprocesses to run in parallel.
+Provide one of three values:
=over 4
=item *
-An integer from the range B<1> to 32. A value of
-B<1> means that a single Salvager process salvages the partitions
-sequentially.
-
+An integer from the range C<1> to C<32>. A value of C<1> means that a
+single Salvager process salvages the partitions sequentially.
=item *
-The string all to run up to four Salvager subprocesses in
-parallel on partitions formatted as logical volumes that span multiple
-physical disks. Use this value only with such logical volumes.
-
+The string C<all> to run up to four Salvager subprocesses in parallel on
+partitions formatted as logical volumes that span multiple physical
+disks. Use this value only with such logical volumes.
=item *
-The string all followed immediately (with no intervening space)
-by an integer from the range B<1> to B<32>, to run the
-specified number of Salvager subprocesses in parallel on partitions formatted
-as logical volumes. Use this value only with such logical
-volumes.
-
+The string C<all> followed immediately (with no intervening space) by an
+integer from the range C<1> to C<32>, to run the specified number of
+Salvager subprocesses in parallel on partitions formatted as logical
+volumes. Use this value only with such logical volumes.
=back
The BOS Server never starts more Salvager subprocesses than there are
partitions, and always starts only one process to salvage a single
-volume. If this argument is omitted, up to four Salvager subprocesses
-run in parallel.
+volume. If this argument is omitted, up to four Salvager subprocesses run
+in parallel.
-=item -tmpdir
+=item B<-tmpdir> <I<name of dir to place tmp files>>
Names a local disk directory in which the Salvager places the temporary
-files it creates during a salvage operation, instead of writing them to the
-partition being salvaged (the default). If the Salvager cannot write to
-the specified directory, it attempts to write to the partition being
+files it creates during a salvage operation, instead of writing them to
+the partition being salvaged (the default). If the Salvager cannot write
+to the specified directory, it attempts to write to the partition being
salvaged.
-=item -showlog
+=item B<-showlog>
Displays on the standard output stream all log data that is being written
-to the B</usr/afs/logs/SalvageLog> file.
+to the F</usr/afs/logs/SalvageLog> file.
-=item -showsuid
+=item B<-showsuid>
Displays a list of the pathnames for all files that have the setuid or
setgid mode bit set.
-=item -showmounts
+=item B<-showmounts>
-Records in the /usr/afs/logs/SalvageLog file all mount points
-found in each volume. The Salvager does not repair corruption in the
-volumes, if any exists.
+Records in the F</usr/afs/logs/SalvageLog> file all mount points found in
+each volume. The Salvager does not repair corruption in the volumes, if
+any exists.
-=item -orphans
+=item B<-orphans> (ignore | remove | attach)
-Controls how the Salvager handles orphaned files and directories.
-Choose one of the following three values:
+Controls how the Salvager handles orphaned files and directories. Choose
+one of the following three values:
=over 4
=item ignore
Leaves the orphaned objects on the disk, but prints a message to the
-B</usr/afs/logs/SalvageLog> file reporting how many orphans were found
-and the approximate number of kilobytes they are consuming. This is the
+F</usr/afs/logs/SalvageLog> file reporting how many orphans were found and
+the approximate number of kilobytes they are consuming. This is the
default if the B<-orphans> argument is omitted.
=item remove
Removes the orphaned objects, and prints a message to the
-B</usr/afs/logs/SalvageLog> file reporting how many orphans were
-removed and the approximate number of kilobytes they were consuming.
+F</usr/afs/logs/SalvageLog> file reporting how many orphans were removed
+and the approximate number of kilobytes they were consuming.
=item attach
Attaches the orphaned objects by creating a reference to them in the vnode
-of the volume's root directory. Since each object's actual
-name is now lost, the Salvager assigns each one a name of the following
-form:
+of the volume's root directory. Since each object's actual name is now
+lost, the Salvager assigns each one a name of the following form:
=over 4
+=item C<__ORPHANFILE__.I<index>> for files.
-_ _ORPHANFILE_ _.I<index> for files
-
-
-_ _ORPHANDIR_ _.I<index> for directories
+=item C<__ORPHANDIR__.I<index>> for directories.
=back
where I<index> is a two-digit number that uniquely identifies each
-object. The orphans are charged against the volume's quota and
-appear in the output of the B<ls> command issued against the
-volume's root directory.
+object. The orphans are charged against the volume's quota and appear in
+the output of the B<ls> command issued against the volume's root
+directory.
=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
=head1 EXAMPLES
The following command instructs the Salvager to attempt to salvage the
-volume with volume ID 258347486 on B</vicepg> on the local
-machine.
+volume with volume ID 258347486 on F</vicepg> on the local machine.
% /usr/afs/bin/salvager -partition /vicepg -volumeid 258347486
=head1 PRIVILEGE REQUIRED
To issue the command at the shell prompt, the issuer must be logged in as
-the local superuser B<root>.
+the local superuser C<root>.
=head1 SEE ALSO
-L<BosConfig(1)>,
-L<SalvageLog(1)>,
-L<bos_create(1)>,
-L<bos_getlog(1)>,
-L<bos_salvage(1)>,
+L<BosConfig(5)>,
+L<SalvageLog(5)>,
+L<bos_create(8)>,
+L<bos_getlog(8)>,
+L<bos_salvage(8)>,
L<vos_move(1)>
=head1 COPYRIGHT
+++ /dev/null
-=head1 NAME
-
-tapeconfig - Defines configuration parameters for all tape devices and backup data files
-on a Tape Coordinator machine
-
-=head1 DESCRIPTION
-
-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
-instruction for each tape device or backup data file appears on its own line
-and each has the following format:
-
- [I<capacity> I<filemark_size>] I<device_name> I<port_offset>
-
-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
-to this value in two circumstances:
-
-=over 4
-
-=item *
-
-When the capacity field of a tape or backup data file's label is
-empty (because the tape has never been labeled). The Tape Coordinator
-records this value on the label and uses it when determining how much data it
-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
-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
-System tape label to track how much space remains as it writes data to a tape
-or backup data file. The appropriate value to record for a tape depends
-on the size of the tapes usually used in the device and whether it has a
-compression mode; for suggested values, see the I<IBM AFS
-Administration Guide> chapter on configuring the Backup System. If
-using a value obtained from the B<fms> command, reduce it by 10% to
-15% before recording it in the file.
-
-For a backup data file, it is best to provide a value that helps the Tape
-Coordinator avoid reaching the end-of-file (EOF) unexpectedly. Make it
-at least somewhat smaller than the amount of space available on the partition
-housing the file when the dump operation begins, and never larger than the
-maximum file size allowed by the operating system.
-
-Specify a (positive) integer or decimal value followed by a letter than
-indicates units, with no intervening space. In a decimal number, the
-number of digits after the decimal point must not translate to fractions of
-bytes. The maximum acceptable value is 2048 GB (2 TB). The
-acceptable units letters are as follows; if the letter is omitted, the
-default is kilobytes.
-
-=over 4
-
-=item *
-
-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
-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
-manufacturer. In a dump to tape, the Tape Coordinator inserts filemarks
-at the boundary between the data from each volume, so the filemark size
-affects how much space is available for actual data.
-
-The appropriate value to record for a tape depends on the size of the tapes
-usually used in the device and whether it has a compression mode; for
-suggested values, see the I<IBM AFS Administration Guide> chapter on
-configuring the Backup System. If using a value obtained from the
-B<fms> command, increase it by 10% to 15% before recording it in the
-file.
-
-For backup data files, record a value of 0 (zero). The
-Tape Coordinator actually ignores this field for backup data files, because it
-does not use filemarks when writing to a file.
-
-Use the same notation as for the I<capacity> field, but note that the
-default units is bytes rather than kilobytes. The maximum acceptable
-value is 2048 GB.
-
-If this field is empty, the Tape Coordinator uses the value 0
-(zero). Either leave both this field and the I<capacity> field
-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
-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
-(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
-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
-B<backup> commands.
-
-=back
-
-=head1 PRIVILEGE REQUIRED
-
-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
-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
-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>,
-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.
-
- 2G 1M /dev/rmt/0h 0
- 1g 4k /dev/rmt/3h 3
- 2G 1m /dev/rmt/4h 2
- 1.5G 0 /dev/FILE 4
-
-=head1 SEE ALSO
-
-L<backup_addhost(1)>,
-L<backup_dump(1)>,
-L<backup_labeltape(1)>,
-L<backup_savedb(1)>,
-L<butc(1)>,
-L<fms(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.
=head1 SYNOPSIS
-B<upclient> <I<hostname>> [B<-crypt>] [B<-clear>] [-t <I<retry time>>]
-[B<-verbose>]* <I<dir>>+ [B<-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<upclient> <I<hostname>> [B<-crypt>] [B<-clear>] [B<-t> <I<retry time>>]
+ [B<-verbose>]* <I<dir>>+ [B<-help>]
=head1 DESCRIPTION
-The upclient command initializes the client portion of the
-Update Server. In the conventional configuration, its binary file is
-located in the B</usr/afs/bin> directory on a file server
-machine.
-
-The upclient command is not normally issued at the command shell
-prompt but rather placed into a file server machine's
-B</usr/afs/local/BosConfig> file with the B<bos create>
-command. If it is ever issued at the command shell prompt, the issuer
-must be logged onto a database server machine as the local superuser
-B<root>.
-
-The upclient process periodically checks that all files in each
-local directory named by the I<dir> argument match the files in the
-corresponding directory on the source machine named by the
-I<hostname>argument. If a file does not match, the
-B<upclient> process requests the source copy from the
-B<upserver> process running on the source machine.
-
-By default, the upclient process in the United States edition of
-AFS requests that the B<upserver> process encrypt the data before
-transferring it, whereas in the international edition it requests unencrypted
-transfer. If using the United States edition, use the B<-clear>
-flag to request unencrypted transfer if appropriate. (The
-B<-crypt> flag explicitly sets the default in the United States
-edition, and is not available in the international edition.)
-
-In the conventional configuration, separate instances of the
-B<upclient> process request data from the B</usr/afs/bin> and
-B</usr/afs/etc> directories, except on machines for which the system
-control machine is also the binary distribution machine for the machine's
-system type. The conventional names for the separate instances are
-B<upclientbin> and B<upclientetc> respectively.
-
-The B<upclient> and upserver processes always mutually
-authenticate, whether or not the data they pass is encrypted; they use
-the key with the highest key version number in the
-B</usr/afs/etc/KeyFile> file to construct a server ticket for mutual
-authentication.
+The upclient command initializes the client portion of the Update
+Server. In the conventional configuration, its binary file is located in
+the F</usr/afs/bin> directory on a file server machine.
+
+The upclient command is not normally issued at the command shell prompt
+but rather placed into a file server machine's F</usr/afs/local/BosConfig>
+file with the B<bos create> command. If it is ever issued at the command
+shell prompt, the issuer must be logged onto a database server machine as
+the local superuser C<root>.
+
+The upclient process periodically checks that all files in each local
+directory named by the I<dir> argument match the files in the
+corresponding directory on the source machine named by the I<hostname>
+argument. If a file does not match, the B<upclient> process requests the
+source copy from the B<upserver> process running on the source machine.
+
+By default, the B<upclient> process requests that the B<upserver> process
+encrypt the data before transferring it. Use the B<-clear> flag to
+request unencrypted transfer if appropriate. (The B<-crypt> flag
+explicitly sets the default.)
+
+In the conventional configuration, separate instances of the B<upclient>
+process request data from the F</usr/afs/bin> and F</usr/afs/etc>
+directories, except on machines for which the system control machine is
+also the binary distribution machine for the machine's system type. The
+conventional names for the separate instances are C<upclientbin> and
+C<upclientetc> respectively.
+
+The B<upclient> and B<upserver> processes always mutually authenticate,
+whether or not the data they pass is encrypted; they use the key with the
+highest key version number in the F</usr/afs/etc/KeyFile> file to
+construct a server ticket for mutual authentication.
+
+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 Update Server to distribute the contents of the
-B</usr/afs/etc> directory if using the international edition of
-AFS. The contents of this directory are sensitive and the international
-edition of AFS does not include the encryption routines necessary for
-encrypting files before transfer across the network.
+F</usr/afs/etc> directory using the B<-clear> option. The contents of
+this directory are sensitive.
=head1 OPTIONS
=over 4
-=item I<hostname
->
+=item <I<hostname>>
-Names either the cell's system control machine (if the requested
-directory is B</usr/afs/etc>), or the binary distribution machine for
-the local machine's CPU and operating system type (if the requested
-directory is B</usr/afs/bin>).
+Names either the cell's system control machine (if the requested directory
+is F</usr/afs/etc>), or the binary distribution machine for the local
+machine's CPU and operating system type (if the requested directory is
+F</usr/afs/bin>).
-=item -crypt
+=item B<-crypt>
-Requests the transfer of data from the upserver process in
-encrypted form. With the United States edition of AFS, use this flag to
-set the default explicitly. Provide this flag or the B<-crypt>
-flag, but not both.
+Requests the transfer of data from the upserver process in encrypted
+form. This is the default; this flag just sets the default explicitly.
+Do not use this flag with the B<-clear> flag.
-=item -clear
+=item B<-clear>
-Requests transfer of data from the upserver process in
-unencrypted form. Use this flag to change from the default for the
-United States edition of AFS. Provide this flag or the
-B<-crypt> flag, but not both.
+Requests transfer of data from the B<upserver> process in unencrypted
+form. Provide this flag or the B<-crypt> flag, but not both.
-=item -t
+=item B<-t> <I<retry time>>
Specifies how often to check for changes in each specified directory, as a
-number of seconds. If this argument is omitted, the default is 300 (5
-minutes). This argument determines the maximum amount of time it takes
-for a change made on the source machine to propagate to this machine.
+number of seconds. If this argument is omitted, the default is C<300> (5
+minutes). This argument determines the maximum amount of time it takes for
+a change made on the source machine to propagate to this machine.
-=item -verbose
+=item B<-verbose>*
-Writes a trace of the upclient process's operations on the
-standard output stream, which usually corresponds to the machine
-console. Provide one, two, or three instances of the flag; each
-additional instance generates increasingly numerous and detailed
-messages.
+Writes a trace of the upclient process's operations on the standard output
+stream, which usually corresponds to the machine console. Provide one,
+two, or three instances of the flag; each additional instance generates
+increasingly numerous and detailed messages.
-=item I<dir
->
+=item <I<dir>>+
-Names each directory to check for modified files. The conventional
-choices are the following:
+Names each directory to check for modified files. The conventional choices
+are the following:
=over 4
=item *
-/usr/afs/bin, in which case the recommended name for the
-process (assigned with the B<-instance> argument to the B<bos
-create> command) is B<upclientbin>. The I<hostname>
-is the binary distribution machine for the local machine's system
-type. Use the B<-clear> flag be used for the
-B</usr/afs/bin> directory, since binaries are not particularly
-sensitive and encrypting them can take a long time.
-
+F</usr/afs/bin>, in which case the recommended name for the process
+(assigned with the B<-instance> argument to the B<bos create> command) is
+C<upclientbin>. The I<hostname> is the binary distribution machine for the
+local machine's system type. You may wish to use the B<-clear> flag for
+the F</usr/afs/bin> directory, since binaries are not particularly
+sensitive and encrypting them takes system resources.
=item *
-/usr/afs/etc, in which case the recommended name for the
-process (assigned with the B<-instance> argument to the B<bos
-create> command) is B<upclientetc>. The I<hostname>
-is the cell's system control machine. Use the B<-crypt>
-flag for the B</usr/afs/etc> directory, since it contains the
-B<KeyFile> file and other data vital to cell security.
-
-
-As a reminder, do not use the Update Server to transfer the contents of the
-B</usr/afs/etc> directory if using the international edition of
-AFS.
+F</usr/afs/etc>, in which case the recommended name for the process
+(assigned with the B<-instance> argument to the B<bos create> command) is
+C<upclientetc>. The I<hostname> is the cell's system control machine. Use
+the B<-crypt> flag for the F</usr/afs/etc> directory, since it contains
+the F<KeyFile> file and other data vital to cell security.
=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
=head1 EXAMPLES
-The following bos create command creates an
-B<upclientbin> process on the machine
-B<fs4.abc.com> that refers to the machine
-B<fs1.abc.com> as the source for the
-B</usr/afs/bin> directory (thus B<fs1.abc.com>
-is the binary distribution machine for machines of
-B<fs4.abc.com>'s type). The files in the
-B</usr/afs/bin> directory are distributed every 120 seconds.
+The following bos create command creates an C<upclientbin> process on the
+machine C<fs4.abc.com> that refers to the machine C<fs1.abc.com> as the
+source for the F</usr/afs/bin> directory (thus C<fs1.abc.com> is the
+binary distribution machine for machines of C<fs4.abc.com>'s type). The
+files in the F</usr/afs/bin> directory are distributed every 120 seconds.
The command requests transfer in unencrypted form.
- % bos create -server fs4.abc.com -instance upclientbin -type simple \
- -cmd "/usr/afs/bin/upclient fs1.abc.com -clear \
+ % bos create -server fs4.abc.com -instance upclientbin -type simple \
+ -cmd "/usr/afs/bin/upclient fs1.abc.com -clear \
-t 120 /usr/afs/bin"
=head1 PRIVILEGE REQUIRED
-The issuer must be logged in as the superuser root on a file
-server machine to issue the command at a command shell prompt. It is
-conventional instead to create and start the process by issuing the B<bos
-create> command.
+The issuer must be logged in as the superuser C<root> on a file server
+machine to issue the command at a command shell prompt. It is conventional
+instead to create and start the process by issuing the B<bos create>
+command.
=head1 SEE ALSO
-L<BosConfig(1)>,
-L<bos_create(1)>,
-L<upserver(1)>
+L<BosConfig(5)>,
+L<bos_create(8)>,
+L<upserver(8)>
=head1 COPYRIGHT
=head1 SYNOPSIS
-B<upserver> [<I<directory>>+] [B<-crypt> <I<directory>>+] [-clear <I<directory>>+]
-[B<-auth> <I<directory>>+] [B<-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<upserver> [<I<directory>>+] [B<-crypt> <I<directory>>+]
+ [B<-clear> <I<directory>>+] [B<-auth> <I<directory>>+] [B<-help>]
=head1 DESCRIPTION
-The upserver command initializes the server portion of the
-Update Server (the B<upserver> process). In the conventional
-configuration, its binary file is located in the B</usr/afs/bin>
-directory on a file server machine.
-
-The upserver command is not normally issued at the command shell
-prompt but rather placed into a file server machine's
-B</usr/afs/local/BosConfig> file with the B<bos create>
-command. If it is ever issued at the command shell prompt, the issuer
-must be logged onto a database server machine as the local superuser
-B<root>.
-
-The upserver command specifies which of the directories on the
-local disk are eligible for distribution in response to requests from the
-client portion of the Update Server (the B<upclient> process) running
-on other machines. If no directories are specified, the
-B<upserver> process distributes the contents of any directory on its
-local disk.
-
-The upserver process can distribute a directory's contents
-in encrypted or unencrypted form. By default, it does not use
-encryption unless an B<upclient> process requests it (this default is
-equivalent to setting the B<-clear> flag). When the
-B<-crypt> flag is provided, the B<upserver> process only
-fulfills requests for encrypted transfer.
-
-For the United States edition of AFS, using the -crypt flag
-guarantees that the B<upserver> process transfers a directory's
-contents only in encrypted form. For the international edition, using
-the B<-crypt> flag completely blocks data transfer, because the
-international edition of the B<upclient> process cannot request
-encrypted transfer (the B<upclient> initialization command does not
-include the B<-crypt> flag).
-
-The B<upclient> and upserver processes always mutually
-authenticate, whether or not the data they pass is encrypted; they use
-the key with the highest key version number in the
-B</usr/afs/etc/KeyFile> file to construct a server ticket for mutual
-authentication.
+The B<upserver> command initializes the server portion of the Update
+Server (the C<upserver> process). In the conventional configuration, its
+binary file is located in the F</usr/afs/bin> directory on a file server
+machine.
+
+The B<upserver> command is not normally issued at the command shell prompt
+but rather placed into a file server machine's F</usr/afs/local/BosConfig>
+file with the B<bos create> command. If it is ever issued at the command
+shell prompt, the issuer must be logged onto a database server machine as
+the local superuser C<root>.
+
+The B<upserver> command specifies which of the directories on the local
+disk are eligible for distribution in response to requests from the client
+portion of the Update Server (the B<upclient> process) running on other
+machines. If no directories are specified, the B<upserver> process
+distributes the contents of any directory on its local disk.
+
+The B<upserver> process can distribute a directory's contents in encrypted
+or unencrypted form. By default, it does not use encryption unless an
+B<upclient> process requests it (this default is equivalent to setting the
+B<-clear> flag). When the B<-crypt> flag is provided, the B<upserver>
+process only fulfills requests for encrypted transfer.
+
+The B<upclient> and B<upserver> processes always mutually authenticate,
+whether or not the data they pass is encrypted; they use the key with the
+highest key version number in the F</usr/afs/etc/KeyFile> file to
+construct a server ticket for mutual authentication.
+
+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 Update Server to distribute the contents of the
-B</usr/afs/etc> directory if using the international edition of
-AFS. The contents of this directory are sensitive and the international
-edition of AFS does not include the encryption routines necessary for
-encrypting files before transfer across the network.
+F</usr/afs/etc> directory without the B<-crypt> flag. The contents of
+this directory are sensitive.
=head1 OPTIONS
=over 4
-=item I<directory
->
+=item <I<directory>>+
Names each directory to distribute in unencrypted form (because they
-appear before the first B<-crypt> or B<-clear> flag on the
-command line). If this argument is omitted, all directories on the
-machine's local disk are eligible for distribution.
+appear before the first B<-crypt> or B<-clear> flag on the command
+line). If this argument is omitted, all directories on the machine's local
+disk are eligible for distribution.
-=item -crypt
+=item B<-crypt> <I<directory>>+
-Precedes a list of one or more directories that the upserver
-process distributes only in encrypted form.
+Precedes a list of one or more directories that the B<upserver> process
+distributes only in encrypted form.
-=item -clear
+=item B<-clear> <I<directory>>+
-Precedes a list of one or more directories that the upserver
-process distributes in unencrypted form unless the B<upclient> process
-requests them in encrypted form. Use this argument only if a list of
-directories headed by the B<-crypt> flag precedes it on the command
-line.
+Precedes a list of one or more directories that the B<upserver> process
+distributes in unencrypted form unless the B<upclient> process requests
+them in encrypted form. Use this argument only if a list of directories
+headed by the B<-crypt> flag precedes it on the command line.
-=item -auth
+=item B<-auth> <I<directory>>+
-Precedes a list of one or more directories which the upserver
-process distributes using a form of encryption that is intermediate in
-complexity and security between the unencrypted and encrypted levels set by
-the B<-clear> and B<-crypt> arguments. Do not use this
-argument, because the B<upclient> process does not have a
-corresponding argument that it can use to request data transfer at this
-level.
+Precedes a list of one or more directories which the upserver process
+distributes using a form of encryption that is intermediate in complexity
+and security between the unencrypted and encrypted levels set by the
+B<-clear> and B<-crypt> arguments. Do not use this argument, because the
+B<upclient> process does not have a corresponding argument that it can use
+to request data transfer at this level.
-=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 bos create command defines and starts an
-B<upserver> process on the host machine
-B<fs1.abc.com>. The last parameter (enclosed in
-quotes) instructs the B<upserver> process to distribute the contents
-of the B</usr/afs/bin> directory in unencrypted form and the contents
-of the B</usr/afs/etc> directory in encrypted form.
+The following example bos create command defines and starts an B<upserver>
+process on the host machine C<fs1.abc.com>. The last parameter (enclosed
+in quotes) instructs the B<upserver> process to distribute the contents of
+the F</usr/afs/bin> directory in unencrypted form and the contents of the
+F</usr/afs/etc> directory in encrypted form.
- % bos create -server fs1.abc.com -instance upserver -type simple \
- -cmd "/usr/afs/bin/upserver /usr/afs/bin -crypt /usr/afs/etc"
+ % bos create -server fs1.abc.com -instance upserver -type simple \
+ -cmd "/usr/afs/bin/upserver /usr/afs/bin -crypt /usr/afs/etc"
=head1 PRIVILEGE REQUIRED
-The issuer must be logged in as the superuser root on a file
-server machine to issue the command at a command shell prompt. It is
-conventional instead to create and start the process by issuing the B<bos
-create> command.
+The issuer must be logged in as the superuser C<root> on a file server
+machine to issue the command at a command shell prompt. It is conventional
+instead to create and start the process by issuing the B<bos create>
+command.
=head1 SEE ALSO
-L<BosConfig(1)>,
-L<bos_create(1)>,
-L<upclient(1)>
+L<BosConfig(5)>,
+L<bos_create(8)>,
+L<upclient(8)>
=head1 COPYRIGHT
=head1 DESCRIPTION
-The commands in the uss command suite help administrators to
-create AFS user accounts more easily and efficiently. If B<uss>
-commands are not used, creating an account requires issuing at least six
-separate commands to five different AFS servers.
+The commands in the B<uss> command suite help administrators to create AFS
+user accounts more easily and efficiently. If B<uss> commands are not
+used, creating an account requires issuing at least six separate commands
+to five different AFS servers.
There are three main commands in the suite:
=item *
-The uss add command creates a single complete user account,
-based on command line arguments and instructions in a template file.
-
+The B<uss add> command creates a single complete user account, based on
+command line arguments and instructions in a template file.
=item *
-The uss bulk command creates multiple complete accounts at
-once, based on command line arguments, instructions in a template file and a
-bulk input file.
-
+The B<uss bulk> command creates multiple complete accounts at once, based
+on command line arguments, instructions in a template file and a bulk
+input file.
=item *
-the uss delete command removes most parts of a user
-account.
-
+The B<uss delete> command removes most parts of a user account.
=back
-To obtain help, issue the B<uss apropos> and uss help
-commands.
+To obtain help, issue the B<uss apropos> and B<uss help> commands.
=head1 OPTIONS
The following arguments and flags are available on many commands in the
-B<uss> suite. The reference page for each command also lists
-them, but they are described here in greater detail.
+B<uss> suite. The reference page for each command also lists them, but
+they are described here in greater detail.
=over 4
-=item -admin <I<administrator to authenticate>
->
+=item B<-admin> <I<administrator to authenticate>>
Specifies the AFS user name under which to establish a connection to the
AFS server processes that administer the various parts of a user
account. If it is omitted, the connection is established under the
issuer's effective user ID (his or her identity in the local file
system). Even when this argument is included, UNIX commands that run
-during the B<uss> operation (for instance, the UNIX
-B</etc/chown> command) run under the effective user ID.
+during the B<uss> operation (for instance, the UNIX F</etc/chown> command)
+run under the effective user ID.
-=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
-=item -dryrun
+=item B<-dryrun>
Reports actions that the command interpreter needs to perform when
-executing the B<uss> operation, without actually performing
-them. Include this flag to verify that the command produces the desired
-account configuration. Combine it with the B<-verbose> flag to
-yield even more detailed information. Note that the output does not
-necessarily reveal all possible problems that can prevent successful execution
-of the command, especially those that result from transient server or network
-outages.
+executing the B<uss> operation, without actually performing them. Include
+this flag to verify that the command produces the desired account
+configuration. Combine it with the B<-verbose> flag to yield even more
+detailed information. Note that the output does not necessarily reveal all
+possible problems that can prevent successful execution of the command,
+especially those that result from transient server or network outages.
-=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 -skipauth
+=item B<-skipauth>
Bypasses mutual authentication with the AFS Authentication Server,
-allowing a site that uses Kerberos instead of the AFS Authentication Server to
-substitute that form of authentication.
+allowing a site that uses Kerberos instead of the AFS Authentication
+Server to substitute that form of authentication.
=back
=head1 PRIVILEGE REQUIRED
-The issuer of a uss command must have all the rights required
-for performing the equivalent actions individually. See each
-B<uss> command's reference page.
+The issuer of a B<uss> command must have all the rights required for
+performing the equivalent actions individually. See each B<uss> command's
+reference page.
=head1 SEE ALSO
-L<uss Bulk Input File(1)>
-
-L<uss Template File(1)>
-
-L<uss_add(1)>,
-L<uss_apropos(1)>,
-L<uss_bulk(1)>,
-L<uss_delete(1)>,
-L<uss_help(1)>
+L<uss(5)>,
+L<uss_bulk(5)>,
+L<uss_add(8)>,
+L<uss_apropos(8)>,
+L<uss_bulk(8)>,
+L<uss_delete(8)>,
+L<uss_help(8)>
=head1 COPYRIGHT
=head1 SYNOPSIS
-B<uss add -user> <I<login name>> [-realname <I<full name in quotes>>]
-[B<-pass> <I<initial password>>]
- [-pwexpires <I<password expires in [0..254] days (0 => never)>>]
- [-server <I<FileServer for home volume>>]
- [-partition <I<FileServer's disk partition for home volume>>]
- [-mount <I<home directory mount point>>]
- [-uid <I<uid to assign the user>>]
- [-template <I<pathname of template file>>]
- [B<-verbose>] [-var <I<auxiliary argument pairs (Num val)>>+]
- [B<-cell> <I<cell name>>] [-admin <I<administrator to authenticate>>]
- [B<-dryrun>] [B<-skipauth>] [B<-overwrite>] [-help]
-
-B<uss ad -us> <I<login name>> [-r <I<full name in quotes>>]
-[B<-pas> <I<initial password>>]
- [-pw <I<password expires in [0..254] days (0 => never)>>]
- [-se <I<FileServer for home volume>>]
- [-par <I<FileServer's disk partition for home volume>>]
- [B<-m> <I<home directory mount point>>] [-ui <I<uid to assign the user>>]
- [B<-t> <I<pathname of template file>>] [-ve]
- [B<-va> <I<auxiliary argument pairs (Num val)>>+] [-c <I<cell name>>]
- [B<-a> <I<administrator to authenticate>>] [B<-d>] [B<-sk>] [B<-o>] [-h]
+B<uss add> B<-user> <I<login name>> [B<-realname> <I<full name in quotes>>]
+ [B<-pass> <I<initial password>>]
+ [B<-pwexpires> <I<< password expires in [0..254] days (0 => never) >>>]
+ [B<-server> <I<file server for home volume>>]
+ [B<-partition> <I<file server's disk partition for home volume>>]
+ [B<-mount> <I<home directory mount point>>]
+ [B<-uid> <I<uid to assign the user>>]
+ [B<-template> <I<pathname of template file>>]
+ [B<-verbose>] [B<-var> <I<auxiliary argument pairs (Num val)>>+]
+ [B<-cell> <I<cell name>>] [B<-admin> <I<administrator to authenticate>>]
+ [B<-dryrun>] [B<-skipauth>] [B<-overwrite>] [B<-help>]
+
+B<uss ad> B<-us> <I<login name>> [B<-r> <I<full name in quotes>>]
+ [B<-pas> <I<initial password>>]
+ [B<-pw> <I<< password expires in [0..254] days (0 => never) >>>]
+ [B<-se> <I<FileServer for home volume>>]
+ [B<-par> <I<FileServer's disk partition for home volume>>]
+ [B<-m> <I<home directory mount point>>]
+ [B<-ui> <I<uid to assign the user>>]
+ [B<-t> <I<pathname of template file>>] [B<-ve>]
+ [B<-va> <I<auxiliary argument pairs (Num val)>>+] [B<-c> <I<cell name>>]
+ [B<-a> <I<administrator to authenticate>>] [B<-d>] [B<-sk>] [B<-o>]
+ [B<-h>]
=head1 DESCRIPTION
-The uss add command creates entries in the Protection Database
-and Authentication Database for the user name specified by the
-B<-user> argument. By default, the Protection Server
-automatically allocates an AFS user ID (UID) for the new user; to specify
-an alternate AFS UID, include the B<-uid> argument. If a
-password is provided with the B<-pass> argument, it is stored as the
-user's password in the Authentication Database after conversion into a
-form suitable for use as an encryption key. Otherwise, the string
-B<changeme> is assigned as the user's initial password.
+The B<uss add> command creates entries in the Protection Database and
+Authentication Database for the user name specified by the B<-user>
+argument. By default, the Protection Server automatically allocates an AFS
+user ID (UID) for the new user; to specify an alternate AFS UID, include
+the B<-uid> argument. If a password is provided with the B<-pass>
+argument, it is stored as the user's password in the Authentication
+Database after conversion into a form suitable for use as an encryption
+key. Otherwise, the string C<changeme> is assigned as the user's initial
+password.
The other results of the command depend on which instructions and which of
a defined set of variables appear in the template file specified with the
-B<-template> argument. Many of the command's arguments
-supply a value for one of the defined variables, and failure to provide an
-argument when the corresponding variable appears in the template file halts
-the account creation process at the point where the command interpreter first
+B<-template> argument. Many of the command's arguments supply a value for
+one of the defined variables, and failure to provide an argument when the
+corresponding variable appears in the template file halts the account
+creation process at the point where the command interpreter first
encounters the variable in the template file.
-To create multiple accounts with a single command, use the uss
-bulk command. To delete accounts with a single command, use the
-B<uss delete> command.
+To create multiple accounts with a single command, use the B<uss bulk>
+command. To delete accounts with a single command, use the B<uss delete>
+command.
=head1 OPTIONS
=over 4
-=item -user
+=item B<-user> <I<login name>>
Names the user's Authentication Database and Protection Database
-entries. It can include up to eight alphanumeric characters, but not
-any of the following characters: B<:> (colon),
-B<@> (at-sign), B<.> (period), space, or
-newline. 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).
+entries. It can include up to eight alphanumeric characters, but not any
+of the following characters: C<:> (colon), C<@> (at-sign), C<.> (period),
+space, or newline. 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 variable in the template file: $USER.
-=item -realname
+=item B<-realname> <I<full name in quotes>>
-Specifies the user's full name. If it contains spaces or
-punctuation, surround it with double quotes. If not provided, it
-defaults to the user name provided with the B<-user> argument.
+Specifies the user's full name. If it contains spaces or punctuation,
+surround it with double quotes. If not provided, it defaults to the user
+name provided with the B<-user> argument.
-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.
+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 (F</etc/passwd> or equivalent), and this variable can be used to pass
+a value to be used in that field.
-=item -pass
+=item B<-pass> <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>.
+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 C<changeme>.
Corresponding variable in the template file: none.
-=item -pwexpires
+=item B<-pwexpires> <I<password expiration>>
-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).
+Sets the number of days after a user's password is changed that it remains
+valid. Provide an integer from the range C<1> through C<254> to specify
+the number of days until expiration, or the value C<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).
+command to change the password (after that, only an administrator can
+change it).
Corresponding variable in the template file: $PWEXPIRES.
-=item -server
+=item B<-server> <I<file server name>>
-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.
+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,
+C<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 variable in the template file: $SERVER.
-=item -partition
+=item B<-partition> <I<file server partition>>
-Specifies the partition on which to create the user's volume; it
-must be on the file server machine named by the B<-server>
-argument. Provide the complete partition name (for example
-B</vicepa>) or one of the following abbreviated forms:
+Specifies the partition on which to create the user's volume; it must be
+on the file server machine named by the B<-server> argument. Provide the
+complete partition name (for example F</vicepa>) or one of the following
+abbreviated forms:
- B</vicepa> = B<vicepa> = B<a> = 0
- B</vicepb> = B<vicepb> = B<b> = 1
+ /vicepa = vicepa = a = 0
+ /vicepb = vicepb = b = 1
-After /vicepz (for which the index is 25) comes
+After F</vicepz> (for which the index is 25) comes
- B</vicepaa> = B<vicepaa> = B<aa> = 26
- B</vicepab> = B<vicepab> = B<ab> = 27
+ /vicepaa = vicepaa = aa = 26
+ /vicepab = vicepab = ab = 27
and so on through
- B</vicepiv> = B<vicepiv> = B<iv> = 255
+ /vicepiv = vicepiv = iv = 255
Corresponding variable in the template file: $PART.
-=item -mount
+=item B<-mount> <I<home directory mount point>>
-Specifies the pathname for the user's home directory. Partial
-pathnames are interpreted relative to the current working directory.
+Specifies the pathname for the user's home directory. Partial pathnames
+are interpreted relative to the current working directory.
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. 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
-B<fs mkmount> reference page.
-
-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
-B<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 B<mount_point> field.
-
-=item -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, it is best first to use the B<pts examine> command to verify
-that no existing account already has the desired AFS UID; it one does,
-the account creation process terminates with an error.
+F</afs/.abc.com>). For further discussion of the concept of read/write and
+read-only paths through the filespace, see the B<fs mkmount> reference
+page.
+
+Corresponding variable in template: $MTPT, but in the template file's C<V>
+instruction only. Occurrences of the $MTPT variable in template
+instructions that follow the C<V> instruction take their value from the
+C<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 C<V> instruction only if the string $MTPT appears alone in
+the C<V> instruction's I<mount_point> field.
+
+=item B<-uid> <I<uid to assign the user>>
+
+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 user id>
+counter (use the B<pts listmax> command to display the counter). If
+including this argument, it is best first to use the B<pts examine>
+command to verify that no existing account already has the desired AFS
+UID; it one does, the account creation process terminates with an error.
Corresponding variable in the template file: $UID.
-=item -template
+=item B<-template> <I<pathname of template file>>
-Specifies the pathname of the template file. If this argument is
-omitted, the command interpreter searches the following directories in the
-indicated order for a file called B<uss.template>:
+Specifies the pathname of the template file. If this argument is omitted,
+the command interpreter searches the following directories in the
+indicated order for a file called C<uss.template>:
-=item *
+=over 4
-The current working directory
+=item *
+The current working directory.
=item *
-B</afs/>I<cellname>/common/uss, where
-I<cellname> names the local cell
-
+F</afs/I<cellname>/common/uss>, where I<cellname> names the local cell.
=item *
-/etc
+F</etc>
+=back
-If the issuer provides a filename other than uss.template
-but without a pathname, the command interpreter searches for it in the
-indicated directories. If the issuer provides a full or partial
-pathname, the command interpreter consults the specified file only; it
-interprets partial pathnames relative to the current working directory.
+If the issuer provides a filename other than C<uss.template> but without a
+pathname, the command interpreter searches for it in the indicated
+directories. If the issuer provides a full or partial pathname, the
+command interpreter consults the specified file only; it interprets
+partial pathnames relative to the current working directory.
If the specified template file is empty (zero-length), the command creates
-Protection and Authentication Database entries only.
+Protection and Authentication Database entries only.
-The uss Template File reference page details the file's
-format.
+L<uss(5)> details the file's format.
-=item -verbose
+=item B<-verbose>
-Produces on the standard output stream a detailed trace of the
-command's execution. If this argument is omitted, only warnings
-and error messages appear.
+Produces on the standard output stream a detailed trace of the command's
+execution. If this argument is omitted, only warnings and error messages
+appear.
-=item -var
+=item B<-var> <I<auxilliary argument pairs>>
Specifies values for each of the number variables $1 through $9 that can
-appear in the template file. Use the number variables to assign values
-to variables in the B<uss> template file that are not part of the
-standard set.
+appear in the template file. Use the number variables to assign values to
+variables in the B<uss> template file that are not part of the standard
+set.
Corresponding variables in the template file: $1 through $9.
For each instance of this argument, provide two parts in the indicated
-order, separated by a space:
+order, separated by a space:
=over 4
=item *
-The integer from the range B<1> through 9 that matches
-the variable in the template file. Do not precede it with a dollar
-sign.
-
+The integer from the range C<1> through C<9> that matches the variable in
+the template file. Do not precede it with a dollar sign.
=item *
A string of alphanumeric characters to assign as the value of the
variable.
-
=back
-See the chapter on uss in the I<IBM AFS Administration
-Guide> for further explanation.
+See the chapter on uss in the I<IBM AFS Administration Guide> for further
+explanation.
-=item -cell
+=item B<-cell> <I<cell name>>
-Specifies the cell in which to run the command. For more details,
-see the introductory B<uss> reference page.
+Specifies the cell in which to run the command. For more details, see
+L<uss(8)>.
-=item -admin
+=item B<-admin> <I<administrator to authenticate>>
Specifies the AFS user name under which to establish authenticated
-connections to the AFS server processes that maintain the various components
-of a user account. For more details, see the introductory
-B<uss> reference page.
+connections to the AFS server processes that maintain the various
+components of a user account. For more details, see L<uss(8)>.
-=item -dryrun
+=item B<-dryrun>
Reports actions that the command interpreter needs to perform while
-executing the command, without actually performing them. For more
-details, see the introductory B<uss> reference page.
+executing the command, without actually performing them. For more details,
+see L<uss(8)>.
-=item -skipauth
+=item B<-skipauth>
Prevents authentication with the AFS Authentication Server, allowing a
site using Kerberos to substitute that form of authentication.
-=item -overwrite
+=item B<-overwrite>
Overwrites any directories, files and links that exist in the file system
-and for which there are definitions in B<D>, B<E>,
-B<F>, B<L>, or B<S> instructions in the template file
-named by the B<-template> argument. If this flag is omitted,
-the command interpreter prompts once for confirmation that it is to overwrite
-all such elements.
+and for which there are definitions in C<D>, C<E>, C<F>, C<L>, or C<S>
+instructions in the template file named by the B<-template> argument. If
+this flag is omitted, the command interpreter prompts once for
+confirmation that it is to overwrite all such elements.
-=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 combination of the following example uss add command and
-B<V> instruction in a template file called B<uss.tpl>
-creates Protection and Authentication Database entries named B<smith>,
-and a volume called C<user.smith> with a quota of 2500 kilobyte
-blocks, mounted at the pathname
-B</afs/abc.com/usr/smith>. The access control list (ACL)
-on the mount point grants B<smith> all rights.
-
-The issuer of the uss add command provides only the template
-file's name, not its complete pathname, because it resides in the current
-working directory. The command and B<V> instruction appear here
-on two lines only for legibility; there are no line breaks in the actual
-instruction or command.
-
- V user.$USER $SERVER.abc.com /vice$PART $1 \
+The combination of the following example uss add command and C<V>
+instruction in a template file called C<uss.tpl> creates Protection and
+Authentication Database entries named C<smith>, and a volume called
+C<user.smith> with a quota of 2500 kilobyte blocks, mounted at the
+pathname F</afs/abc.com/usr/smith>. The access control list (ACL) on the
+mount point grants C<smith> all rights.
+
+The issuer of the B<uss add> command provides only the template file's
+name, not its complete pathname, because it resides in the current working
+directory. The command and C<V> instruction appear here on two lines only
+for legibility; there are no line breaks in the actual instruction or
+command.
+
+ V user.$USER $SERVER.abc.com /vice$PART $1 \
/afs/abc.com/usr/$USER $UID $USER all
- % uss add -user smith -realname "John Smith" -pass js_pswd -server fs2 \
- -partition b -template uss.tpl -var 1 2500
-
+ % uss add -user smith -realname "John Smith" -pass js_pswd \
+ -server fs2 -partition b -template uss.tpl -var 1 2500
=head1 PRIVILEGE REQUIRED
-The issuer (or the user named by the -admin argument) must
-belong to the B<system:administrators> group in the Protection
-Database and must have the C<ADMIN> flag turned on in his or her
-Authentication Database entry.
+The issuer (or the user named by the B<-admin> argument) must belong to
+the system:administrators group in the Protection Database and must have
+the C<ADMIN> flag turned on in his or her Authentication Database entry.
-If the template contains a V instruction, the issuer must be
-listed in the B</usr/afs/etc/UserList> file and must have at least
-B<a> (B<administer>) and B<i> (B<insert>)
-permissions on the ACL of the directory that houses the new mount
-point. If the template file includes instructions for creating other
-types of objects (directories, files or links), the issuer must have each
-privilege necessary to create them.
+If the template contains a C<V> instruction, the issuer must be listed in
+the F</usr/afs/etc/UserList> file and must have at least C<a> (administer)
+and C<i> (insert) permissions on the ACL of the directory that houses the
+new mount point. If the template file includes instructions for creating
+other types of objects (directories, files or links), the issuer must have
+each privilege necessary to create them.
=head1 SEE ALSO
-L<UserList(1)>,
-L<uss Template File(1)>
-
+L<UserList(5)>,
+L<uss(5)>,
L<fs_mkmount(1)>,
-L<uss(1)>,
-L<uss_bulk(1)>,
-L<uss_delete(1)>
+L<uss(8)>,
+L<uss_bulk(8)>,
+L<uss_delete(8)>
=head1 COPYRIGHT
=head1 SYNOPSIS
-B<uss apropos -topic> <I<help string>> [-help]
+B<uss apropos> B<-topic> <I<help string>> [B<-help>]
-B<uss ap -t> <I<help string>> [-h]
+B<uss ap> B<-t> <I<help string>> [B<-h>]
=head1 DESCRIPTION
-The uss apropos command displays the first line of the online
-help entry for any B<uss> command that has in its name or short
-description the string specified by the B<-topic> argument.
+The B<uss apropos> command displays the first line of the online help
+entry for any B<uss> 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 uss help
-command.
+To display the syntax for a command, use the B<uss 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 ("")
+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
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<uss> command where the string specified by the B<-topic>
-argument is part of the command name or first line.
+B<uss> command where the string specified by the B<-topic> argument is
+part of the command name or first line.
=head1 EXAMPLES
-The following command lists all uss commands that include the
-word B<create> in their names or short descriptions:
+The following command lists all uss commands that include the word
+C<create> in their names or short descriptions:
% uss apropos create
add: create a new user
=head1 SEE ALSO
-L<uss(1)>,
-L<uss_help(1)>
+L<uss(8)>,
+L<uss_help(8)>
=head1 COPYRIGHT
=head1 SYNOPSIS
-B<uss bulk -file> <I<bulk input file>> [-template <I<pathname of template file>>]
-[B<-verbose>] [B<-cell> <I<cell name>>]
- [B<-admin> <I<administrator to authenticate>>] [-dryrun]
- [B<-skipauth>] [-overwrite]
- [-pwexpires <I<password expires in [0..254] days (0 => never)>>]
- [B<-pipe>] [-help]
-
-B<uss b -f> <I<bulk input file>> [B<-t> <I<pathname of template file>>] [-v]
-[B<-c> <I<cell name>>] [B<-a> <I<administrator to authenticate>>] [B<-d>] [B<-s>]
- [B<-o>] [-pw <I<password expires in [0..254] days (0 => never)>>]
- [B<-pi>] [-h]
+B<uss bulk> B<-file> <I<bulk input file>>
+ [B<-template> <I<pathname of template file>>] [B<-verbose>]
+ [B<-cell> <I<cell name>>]
+ [B<-admin> <I<administrator to authenticate>>] [B<-dryrun>]
+ [B<-skipauth>] [B<-overwrite>]
+ [B<-pwexpires> <I<password expires in [0..254] days (0 => never)>>]
+ [B<-pipe>] [B<-help>]
+
+B<uss b> B<-f> <I<bulk input file>> [B<-t> <I<pathname of template file>>]
+ [B<-v>] [B<-c> <I<cell name>>]
+ [B<-a> <I<administrator to authenticate>>] [B<-d>] [B<-s>]
+ [B<-o>] [B<-pw> <I<password expires in [0..254] days (0 => never)>>]
+ [B<-pi>] [B<-h>]
=head1 DESCRIPTION
-The B<uss bulk> command executes the uss commands listed
-in the B<bulk input file> specified with the B<-file>
-argument. If the bulk input file includes B<add> instructions
-that reference a template file, then the B<-template> argument is
-required.
+The B<uss bulk> command executes the uss commands listed in the I<bulk
+input file> specified with the B<-file> argument. If the bulk input file
+includes B<add> instructions that reference a template file, then the
+B<-template> argument is required.
-To create a single account, use the uss add command. To
-delete one or more accounts, use the B<uss delete> command.
+To create a single account, use the B<uss add> command. To delete one or
+more accounts, use the B<uss delete> command.
=head1 OPTIONS
=over 4
-=item -file
+=item B<-file> <I<bulk input file>>
-Specifies the pathname of the bulk input file. Partial pathnames
-are interpreted relative to the current working directory. For details
-on the file's format, see L<uss Bulk Input File(1)>.
+Specifies the pathname of the bulk input file. Partial pathnames are
+interpreted relative to the current working directory. For details on the
+file's format, see L<uss_bulk(5)>.
-=item -template
+=item B<-template> <I<pathname of template file>>
-Specifies the pathname of the template file for any uss add
-commands that appear in the bulk input file. Partial pathnames are
-interpreted relative to the current working directory. For details on
-the file's format, see L<uss Template File(1)>.
+Specifies the pathname of the template file for any uss add commands that
+appear in the bulk input file. Partial pathnames are interpreted relative
+to the current working directory. For details on the file's format, see
+L<uss(5)>.
-=item -verbose
+=item B<-verbose>
-Produces on the standard output stream a detailed trace of the
-command's execution. If this argument is omitted, only warnings
-and error messages appear.
+Produces on the standard output stream a detailed trace of the command's
+execution. If this argument is omitted, only warnings and error messages
+appear.
-=item -cell
+=item B<-cell> <I<cell name>>
-Specifies the cell in which to run the command. For more details,
-see the introductory B<uss> reference page.
+Specifies the cell in which to run the command. For more details, see
+L<uss(8)>.
-=item -admin
+=item B<-admin> <I<administrator to authenticate>>
Specifies the AFS user name under which to establish authenticated
-connections to the AFS server processes that maintain the various components
-of a user account. For more details, see the introductory
-B<uss> reference page.
+connections to the AFS server processes that maintain the various
+components of a user account. For more details, see L<uss(8)>.
-=item -dryrun
+=item B<-dryrun>
Reports actions that the command interpreter needs to perform while
-executing the command, without actually performing them. For more
-details, see the introductory B<uss> reference page.
+executing the command, without actually performing them. For more details,
+see L<uss(8)>.
-=item -skipauth
+=item B<-skipauth>
Prevents authentication with the AFS Authentication Server, allowing a
site using Kerberos to substitute that form of authentication.
-=item -overwrite
+=item B<-overwrite>
Overwrites any directories, files and links that exist in the file system
-and for which there are also B<D>, B<E>, B<F>,
-B<L>, or B<S> instructions in a template file referenced by an
-B<add> instruction in the bulk input file. If this flag is
-omitted, the command interpreter prompts, once for each B<add>
-instruction in the bulk input file, for confirmation that it should overwrite
-such elements. Do not include this flag if the bulk input file does not
-contain B<add> instructions.
-
-=item -pwexpires
-
-Sets the number of days after a user's password is changed that it
-remains valid, for each user named by an B<add> instruction in the
-bulk input file. 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).
+and for which there are also C<D>, C<E>, C<F>, C<L>, or C<S> instructions
+in a template file referenced by an C<add> instruction in the bulk input
+file. If this flag is omitted, the command interpreter prompts, once for
+each C<add> instruction in the bulk input file, for confirmation that it
+should overwrite such elements. Do not include this flag if the bulk input
+file does not contain C<add> instructions.
+
+=item B<-pwexpires> <I<password expiration>>
+
+Sets the number of days after a user's password is changed that it remains
+valid, for each user named by an C<add> instruction in the bulk input
+file. Provide an integer from the range C<1> through C<254> to specify the
+number of days until expiration, or the value C<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).
+command to change the password (after that, only an administrator can
+change it).
-=item -pipe
+=item B<-pipe>
Suppresses the Authentication Server's prompt for the password of the
issuer or the user named by the B<-admin> argument (the Authentication
Server always separately authenticates the creator of an entry in the
Authentication Database). Instead, the command interpreter accepts the
password via the standard input stream, as piped in from another
-program. This enables the B<uss bulk> command to run as part of
-unattended batch jobs.
+program. This enables the B<uss bulk> command to run as part of unattended
+batch jobs.
-=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 command executes the instructions in the bulk input
-file called B<new_students>, which includes B<add>
-instructions that refer to the template file
-B<student.template>. Both files reside in the current
+file called F<new_students>, which includes C<add> instructions that refer
+to the template file F<student.template>. Both files reside in the current
working directory.
% uss bulk new_students student.template
=head1 PRIVILEGE REQUIRED
-The issuer (or the user named by the -admin argument) must have
-the privileges necessary to run the commands that correspond to instructions
+The issuer (or the user named by the B<-admin> argument) must have the
+privileges necessary to run the commands that correspond to instructions
in the bulk input file.
=head1 SEE ALSO
-L<uss Bulk Input File(1)>
-
-L<uss Template File(1)>
-
-L<uss(1)>,
-L<uss_add(1)>,
-L<uss_delete(1)>
+L<uss(5)>,
+L<uss_bulk(5)>,
+L<uss(8)>,
+L<uss_add(8)>,
+L<uss_delete(8)>
=head1 COPYRIGHT
=head1 SYNOPSIS
-B<uss delete -user> <I<login name>> [-mountpoint <I<mountpoint for user's volume>>]
-[B<-savevolume>] [B<-verbose>] [B<-cell> <I<cell name>>]
- [B<-admin> <I<administrator to authenticate>>] [-dryrun]
- [B<-skipauth>] [-help]
+B<uss delete> B<-user> <I<login name>>
+ [B<-mountpoint> <I<mountpoint for user's volume>>]
+ [B<-savevolume>] [B<-verbose>] [B<-cell> <I<cell name>>]
+ [B<-admin> <I<administrator to authenticate>>] [B<-dryrun>]
+ [B<-skipauth>] [B<-help>]
-B<uss d -u> <I<login name>> [B<-m> <I<mountpoint for user's volume>>] [B<-sa>] [-v]
-[B<-c> <I<cell name>>] B<-a> <I<administrator to authenticate>>]
- [B<-d>] [B<-sk>] [-h]
+B<uss d> B<-u> <I<login name>> [B<-m> <I<mountpoint for user's volume>>]
+ [B<-sa>] [B<-v>] [B<-c> <I<cell name>>]
+ [B<-a> <I<administrator to authenticate>>] [B<-d>] [B<-sk>] [B<-h>]
=head1 DESCRIPTION
-The uss delete command removes the Authentication Database and
-Protection Database entries for the user named by B<-user>
-argument. In addition, it can remove the user's home volume and
-associated VLDB entry, a mount point for the volume or both, depending on
-whether the B<-mountpoint> and B<-savevolume> options are
-provided.
+The B<uss delete> command removes the Authentication Database and
+Protection Database entries for the user named by B<-user> argument. In
+addition, it can remove the user's home volume and associated VLDB entry,
+a mount point for the volume or both, depending on whether the
+B<-mountpoint> and B<-savevolume> options are provided.
=over 4
=item *
-To remove both the volume and mount point, use the -mountpoint
-argument to name the user's home directory. It is best to create a
-tape backup of a volume before deleting it. Note that other mount
-points for the volume are not removed, if they exist.
-
+To remove both the volume and mount point, use the B<-mountpoint> argument
+to name the user's home directory. It is best to create a tape backup of a
+volume before deleting it. Note that other mount points for the volume are
+not removed, if they exist.
=item *
-To remove the mount point only, provide both the -mountpoint
-and B<-savevolume> options.
-
+To remove the mount point only, provide both the B<-mountpoint> and
+B<-savevolume> options.
=item *
-To preserve both the volume and mount point, omit the
-B<-mountpoint> argument (or both it and the B<-savevolume>
-flag).
-
+To preserve both the volume and mount point, omit the B<-mountpoint>
+argument (or both it and the B<-savevolume> flag).
=back
=over 4
-=item -user
+=item B<-user> <I<login name>>
Names the entry to delete from the Protection and Authentication
Databases.
-=item -mountpoint
+=item B<-mountpoint> <I<mountpoint for the user's volume>>
-Specifies the pathname to the user's home directory, which is deleted
-from the filespace. By default, the volume referenced by the mount
-point is also removed from the file server machine that houses it, along with
-its Volume Location Database (VLDB) entry. To retain the volume and
-VLDB entry, include the B<-savevolume> flag. Partial pathnames
-are interpreted relative to the current working directory.
+Specifies the pathname to the user's home directory, which is deleted from
+the filespace. By default, the volume referenced by the mount point is
+also removed from the file server machine that houses it, along with its
+Volume Location Database (VLDB) entry. To retain the volume and VLDB
+entry, include the B<-savevolume> flag. Partial pathnames are interpreted
+relative to the current working directory.
Specify the read/write path to the mount point, to avoid the failure that
results from attempting to remove a mount point from 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
-B<fs mkmount> reference page.
+F</afs/.abc.com>). For further discussion of the concept of read/write and
+read-only paths through the filespace, see the B<fs mkmount> reference
+page.
-=item -savevolume
+=item B<-savevolume>
Preserves the user's volume and VLDB entry.
-=item -verbose
+=item B<-verbose>
-Produces on the standard output stream a detailed trace of the
-command's execution. If this argument is omitted, only warnings
-and error messages appear.
+Produces on the standard output stream a detailed trace of the command's
+execution. If this argument is omitted, only warnings and error messages
+appear.
-=item -cell
+=item B<-cell> <I<cell name>>
-Specifies the cell in which to run the command. For more details,
-see the introductory B<uss> reference page.
+Specifies the cell in which to run the command. For more details, see
+L<uss(8)>.
-=item -admin
+=item B<-admin> <I<administrator to authenticate>>
Specifies the AFS user name under which to establish authenticated
-connections to the AFS server processes that maintain the various components
-of a user account. For more details, see the introductory
-B<uss> reference page.
+connections to the AFS server processes that maintain the various
+components of a user account. For more details, see L<uss(8)>.
-=item -dryrun
+=item B<-dryrun>
Reports actions that the command interpreter needs to perform while
-executing the command, without actually performing them. For more
-details, see the introductory B<uss> reference page.
+executing the command, without actually performing them. For more details,
+see L<uss(8)>.
-=item -skipauth
+=item B<-skipauth>
Prevents authentication with the AFS Authentication Server, allowing a
site using Kerberos to substitute that form of authentication.
-=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 removes smith's user account from the
-B<abc.com> cell. The B<-savevolume> argument
-retains the C<user.smith> volume on its file server
-machine.
+The following command removes smith's user account from the C<abc.com>
+cell. The B<-savevolume> argument retains the C<user.smith> volume on its
+file server machine.
% uss delete smith -mountpoint /afs/abc.com/usr/smith -savevolume
=head1 PRIVILEGE REQUIRED
-The issuer (or the user named by -admin argument) must belong to
-the B<system:administrators> group in the Protection Database,
-must have the C<ADMIN> flag turned on in his or her Authentication
-Database entry, and must have at least B<a> (B<administer>)
-and B<d> (B<delete>) permissions on the access control list
-(ACL) of the mount point's parent directory. If the
-B<-savevolume> flag is not included, the issuer must also be listed in
-the B</usr/afs/etc/UserList> file.
+The issuer (or the user named by B<-admin> argument) must belong to the
+system:administrators group in the Protection Database, must have the
+C<ADMIN> flag turned on in his or her Authentication Database entry, and
+must have at least C<a> (administer) and C<d> (delete) permissions on the
+access control list (ACL) of the mount point's parent directory. If the
+B<-savevolume> flag is not included, the issuer must also be listed in the
+F</usr/afs/etc/UserList> file.
=head1 SEE ALSO
-L<UserList(1)>,
+L<UserList(5)>,
L<fs_mkmount(1)>,
-L<uss(1)>
+L<uss(8)>
=head1 COPYRIGHT
=head1 NAME
-uss help - Displays the syntax of specified uss commands or lists
-functional descriptions of all B<uss> commands
+uss help - Displays help for uss commands
=head1 SYNOPSIS
-B<uss help> [B<-topic> <I<help string>>+] [-help]
+B<uss help> [B<-topic> <I<help string>>+] [B<-help>]
-B<uss h> [B<-t> <I<help string>>+] [-h]
+B<uss h> [B<-t> <I<help string>>+] [B<-h>]
=head1 DESCRIPTION
-The uss help command displays the complete online help entry
-(short description and syntax statement) for each command 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<uss> command.
+The B<uss help> command displays the complete online help entry (short
+description and syntax statement) for each command 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<uss> command.
-To list every uss command whose name or short description
-includes a specified keyword, use the B<uss apropos> command.
+To list every uss command whose name or short description includes a
+specified keyword, use the B<uss 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<uss> part of the command name, providing only
-the operation code (for example, specify B<bulk>, not B<uss
-bulk>). If this argument is omitted, the output briefly describes
-every B<uss> command.
+entry. Omit the B<uss> part of the command name, providing only the
+operation code (for example, specify B<bulk>, not B<uss bulk>). If this
+argument is omitted, the output briefly describes every B<uss> 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 uss command consists of the
-following two or three lines:
+The online help entry for each uss 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 command displays the online help entry for the uss
-bulk command:
+The following command displays the online help entry for the B<uss bulk>
+command:
% uss help bulk
uss bulk: bulk input mode
=head1 SEE ALSO
-L<uss(1)>,
-L<uss_apropos(1)>
+L<uss(8)>,
+L<uss_apropos(8)>
=head1 COPYRIGHT
=head1 SYNOPSIS
-B<vldb_check -database> <I<vldb_file>> [B<-uheader>] [B<-vheader>] [-servers]
-[B<-entries>] [B<-verbose>] [B<-help>]
+B<vldb_check> B<-database> <I<vldb file>> [B<-uheader>] [B<-vheader>]
+ [B<-servers>] [B<-entries>] [B<-verbose>] [B<-help>]
-B<vldb_check -d> <I<vldb_file>> [B<-u>] [B<-vh>] [B<-s>] [B<-e>] [B<-ve>] [-h]
+B<vldb_check> B<-d> <I<vldb file>> [B<-u>] [B<-vh>] [B<-s>] [B<-e>]
+ [B<-ve>] [B<-h>]
=head1 DESCRIPTION
-The vldb_check command checks the integrity of the Volume
-Location Database (VLDB), reporting any errors or corruption it finds.
-If there are problems, do not issue any B<vos> commands until the
-database is repaired.
+The B<vldb_check> command checks the integrity of the Volume Location
+Database (VLDB), reporting any errors or corruption it finds. If there
+are problems, do not issue any B<vos> commands until the database is
+repaired.
=head1 CAUTIONS
The results can be unpredictable if the Volume Location (VL) Server makes
-changes to the VLDB while this command is running. Use the B<bos
-shutdown> command to shutdown the local B<vlserver> process
-before running this command, or before creating a second copy of the
-B<vldb.DB0> file (with a different name) on which to run the
-command.
+changes to the VLDB while this command is running. Use the B<bos shutdown>
+command to shutdown the local B<vlserver> process before running this
+command, or before creating a second copy of the F<vldb.DB0> file (with a
+different name) on which to run the command.
=head1 OPTIONS
=over 4
-=item -database
+=item B<-database> <I<vldb file>>
-Names the VLDB (copy of the vldb.DB0 file) to
-check. If the current working directory is not the location of the
-file, provide a pathname, either full or relative to the current working
-directory.
+Names the VLDB (copy of the F<vldb.DB0> file) to check. If the current
+working directory is not the location of the file, provide a pathname,
+either full or relative to the current working directory.
-=item -uheader
+=item B<-uheader>
-Displays information which Ubik maintains in the database's
-header.
+Displays information which Ubik maintains in the database's header.
-=item -pheader
+=item B<-pheader>
Displays information which the VL Server maintains in the database's
header.
-=item -servers
+=item B<-servers> <I<authentication servers>>+
Outputs the server entries from the VLDB, which list the IP addresses
registered for each file server machine in the cell.
-=item -entries
+=item B<-entries>
-Outputs every volume entry in the database. The information
-includes the volume's name and the volume ID number for each of its
-versions.
+Outputs every volume entry in the database. The information includes the
+volume's name and the volume ID number for each of its versions.
-=item -verbose
+=item B<-verbose>
Reports additional information about the database, including the number of
entries for each type of volume.
-=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 there are errors in the database, the output always reports them on the
-standard error stream. If any options other than B<-database>
-or B<-help> are provided, the output written to the standard output
-stream includes additional information as described for each option in the
-preceding B<Options> section of this reference page. The output
-is intended for debugging purposes and is meaningful to someone familiar with
-the internal structure of the VLDB.
+standard error stream. If any options other than B<-database> or B<-help>
+are provided, the output written to the standard output stream includes
+additional information as described for each option in L<OPTIONS>. The
+output is intended for debugging purposes and is meaningful to someone
+familiar with the internal structure of the VLDB.
=head1 PRIVILEGE REQUIRED
-The issuer must be logged in as the local superuser root.
+The issuer must be logged in as the local superuser C<root>.
=head1 SEE ALSO
-L<vldb.DB0 and vldb.DBSYS1(1)>
-
-L<bos_shutdown(1)>,
-L<vlserver(1)>
+L<vldb.DB0(5)>,
+L<bos_shutdown(8)>,
+L<vlserver(8)>
=head1 COPYRIGHT
=head1 SYNOPSIS
-B<vlserver> [B<-p> <I<lwp processes>>] [-nojumbo]
-[B<-enable_peer_stats>] [B<-enable_process_stats>] [B<-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<vlserver> [B<-p> <I<lwp processes>>] [B<-nojumbo>]
+ [B<-enable_peer_stats>] [B<-enable_process_stats>] [B<-help>]
=head1 DESCRIPTION
-The vlserver command initializes the Volume Location (VL)
-Server, which runs on every database server machine. In the
-conventional configuration, its binary file is located in the
-B</usr/afs/bin> directory on a file server machine.
+The B<vlserver> command initializes the Volume Location (VL) Server, which
+runs on every database server machine. In the conventional configuration,
+its binary file is located in the F</usr/afs/bin> directory on a file
+server machine.
-The vlserver command is not normally issued at the command shell
-prompt but rather placed into a file server machine's
-B</usr/afs/local/BosConfig> file with the B<bos create>
-command. If it is ever issued at the command shell prompt, the issuer
-must be logged onto a database server machine as the local superuser
-B<root>.
+The B<vlserver> command is not normally issued at the command shell prompt
+but rather placed into a file server machine's F</usr/afs/local/BosConfig>
+file with the B<bos create> command. If it is ever issued at the command
+shell prompt, the issuer must be logged onto a database server machine as
+the local superuser C<root>.
As it initializes, the VL Server process creates the two files that
-constitute the Volume Location Database (VLDB), B<vldb.DB0> and
-B<vldb.DBSYS1>, in the B</usr/afs/db> directory if they
-do not already exist. Use the commands in the B<vos> suite to
-administer the database.
+constitute the Volume Location Database (VLDB), F<vldb.DB0> and
+F<vldb.DBSYS1>, in the F</usr/afs/db> directory if they do not already
+exist. Use the commands in the B<vos> suite to administer the database.
The VL Server maintains the record of volume locations in the Volume
-Location Database (VLDB). When the Cache Manager fills a file request
-from an application program, it first contacts the VL Server to learn which
+Location Database (VLDB). When the Cache Manager fills a file request from
+an application program, it first contacts the VL Server to learn which
file server machine currently houses the volume that contains the file.
-The Cache Manager then requests the file from the File Server process running
-on that file server machine.
+The Cache Manager then requests the file from the File Server process
+running on that file server machine.
The VL Server records a trace of its activity in the
-B</usr/afs/logs/VLLog> file. Use the B<bos getlog>
-command to display the contents of the file. By default, it records on
-a minimal number of messages. For instructions on increasing the amount
-of logging, see the B<VLLog> reference page.
+F</usr/afs/logs/VLLog> file. Use the B<bos getlog> command to display the
+contents of the file. By default, it records on a minimal number of
+messages. For instructions on increasing the amount of logging, see
+L<VLLog(5)>.
By default, the VL Server runs nine lightweight processes (LWPs). To
change the number, use the B<-p> argument.
+This command does not use the syntax conventions of the AFS command
+suites. Provide the command name and all option names in full.
+
=head1 OPTIONS
=over 4
-=item -p
+=item B<-p> <I<lwp processes>>
-Sets the number of server lightweight processes (LWPs) to run.
-Provide an integer between B<4> and B<16>. The default
-is 9.
+Sets the number of server lightweight processes (LWPs) to run. Provide an
+integer between C<4> and C<16>. The default is C<9>.
-=item -nojumbo
+=item B<-nojumbo>
-Prohibits the server from sending or receiving jumbograms. A
-jumbogram is a large-size packet composed of 2 to 4 normal Rx data packets
-that share the same header. The VL Server uses jumbograms by default,
-but some routers are not capable of properly breaking the jumbogram into
-smaller packets and reassembling them.
+Prohibits the server from sending or receiving jumbograms. A jumbogram is
+a large-size packet composed of 2 to 4 normal Rx data packets that share
+the same header. The VL Server uses jumbograms by default, but some
+routers are not capable of properly breaking the jumbogram into smaller
+packets and reassembling them.
-=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,
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 following B<bos create> command creates a vlserver
-process on the machine B<fs2.abc.com> that uses six
-lightweight processes. Type the command on a single line:
+The following B<bos create> command creates a vlserver process on the
+machine C<fs2.abc.com> that uses six lightweight processes. Type the
+command on a single line:
- % bos create -server fs2.abc.com -instance vlserver -type simple \
+ % bos create -server fs2.abc.com -instance vlserver -type simple \
-cmd "/usr/afs/bin/vlserver -p 6"
=head1 PRIVILEGE REQUIRED
-The issuer must be logged in as the superuser root on a file
-server machine to issue the command at a command shell prompt. It is
-conventional instead to create and start the process by issuing the B<bos
-create> command.
+The issuer must be logged in as the superuser C<root> on a file server
+machine to issue the command at a command shell prompt. It is conventional
+instead to create and start the process by issuing the B<bos create>
+command.
=head1 SEE ALSO
-L<BosConfig(1)>,
-L<VLLog(1)>,
-L<vldb.DB0 and vldb.DBSYS1(1)>
-
-L<bos_create(1)>,
-L<bos_getlog(1)>
+L<BosConfig(5)>,
+L<VLLog(5)>,
+L<vldb.DB0(5)>,
+L<bos_create(8)>,
+L<bos_getlog(8)>
=head1 COPYRIGHT
=head1 NAME
-volinfo - Produces detailed statistics about one or more volume headers and the
-partition that houses them
+volinfo - Produces detailed statistics about AFS volume headers
=head1 SYNOPSIS
-B<volinfo> [B<-online>] [B<-vnode>] [B<-date>] [B<-inode>] [-itime]
-
[B<-part> <I<AFS partition name (default current partition)>>+]
- [B<-volumeid> <I<Volume id>>+] [B<-header>] [B<-sizeOnly>] [-fixheader]
- [B<-saveinodes>] [B<-orphaned>] [-help]
+B<volinfo> [B<-online>] [B<-vnode>] [B<-date>] [B<-inode>] [B<-itime>]
+
[B<-part> <I<AFS partition name (default current partition)>>+]
+ [B<-volumeid> <I<volume id>>+] [B<-header>] [B<-sizeOnly>]
+ [B<-fixheader>] [B<-saveinodes>] [B<-orphaned>] [B<-help>]
=head1 DESCRIPTION
-The volinfo command displays detailed statistics about one or
-more volume headers and the partition that houses them. The command
-must be issued on a file server machine and by default produces output for
-every volume on every AFS server partition on the machine. To display
-output for the volumes on one partition only, include the B<-part>
-argument. To display output for one volume only, include the
-B<-volumeid> argument.
+The B<volinfo> command displays detailed statistics about one or more
+volume headers and the partition that houses them. The command must be
+issued on a file server machine and by default produces output for every
+volume on every AFS server partition on the machine. To display output for
+the volumes on one partition only, include the B<-part> argument. To
+display output for one volume only, include the B<-volumeid> argument.
=head1 OPTIONS
=over 4
-=item -online
+=item B<-online>
Is nonoperational.
-=item -vnode
+=item B<-vnode>
Displays a table for each volume which lists the large (directory) and
small (file) vnodes in it, in addition to the default output.
-=item -date
+=item B<-date>
-When combined with the -vnode flag, adds the
-C<ServerModTime> field to each vnode entry in the large vnode and
-small vnode tables, reporting its most recent modification time.
+When combined with the B<-vnode> flag, adds the C<ServerModTime> field to
+each vnode entry in the large vnode and small vnode tables, reporting its
+most recent modification time.
-=item -inode
+=item B<-inode>
-When combined with the -vnode flag, adds the C<inode>
-field to each vnode entry in the large vnode and small vnode tables, reporting
-the associated inode number.
+When combined with the B<-vnode> flag, adds the C<inode> field to each
+vnode entry in the large vnode and small vnode tables, reporting the
+associated inode number.
-=item -itime
+=item B<-itime>
-When combined with the -vnode flag, displays a change,
-modification, and access timestamp for each of the large vnode and small vnode
-tables.
+When combined with the B<-vnode> flag, displays a change, modification,
+and access timestamp for each of the large vnode and small vnode tables.
-=item -part
+=item B<-part> <I<partition name>>+
Specifies the partition that houses each volume for which to produce
-output. Use the format B</vicep>I<xx>, where I<xx>
-is one or two lowercase letters. This argument can be omitted if the
-current working directory is the mount location for an AFS server
-partition; it is not the mount location for an AFS server partition, the
-command produces output for every volume on all local AFS server
-partitions.
+output. Use the format F</vicepI<xx>>, where I<xx> is one or two lowercase
+letters. This argument can be omitted if the current working directory is
+the mount location for an AFS server partition; it is not the mount
+location for an AFS server partition, the command produces output for
+every volume on all local AFS server partitions.
-=item -volumeid
+=item B<-volumeid> <I<volume id>>+
-Specifies the ID number of one volume for which to produce output.
-The B<-part> argument must be provided along with this one unless the
-current working directory is the mount location for the AFS server partition
-that houses the volume.
+Specifies the ID number of one volume for which to produce output. The
+B<-part> argument must be provided along with this one unless the current
+working directory is the mount location for the AFS server partition that
+houses the volume.
-=item -header
+=item B<-header>
Displays statistics about the volume header of each volume, in addition to
the default output.
-=item -sizeOnly
+=item B<-sizeOnly>
Displays a single line of output for each volume, reporting the size of
various structures associated with it. The default output is suppressed
and any flags that modify it (such as B<-vnode>) are ignored.
-=item -fixheader
+=item B<-fixheader>
-Repairs damaged inodes in each volume if possible. If there are
-any, it reports the action it is taking to repair them. Otherwise, it
-produces no output in addition to the default output.
+Repairs damaged inodes in each volume if possible. If there are any, it
+reports the action it is taking to repair them. Otherwise, it produces no
+output in addition to the default output.
-=item -saveinodes
+=item B<-saveinodes>
Creates a file in the current working directory for each inode in each
-volume. Each file is called
-B<TmpInode.>I<vnode_number> and contains the inode's
-contents. The default output is suppressed and any flags that modify it
-(such as B<-vnode>) are ignored.
+volume. Each file is called F<TmpInode.I<vnode_number>> and contains the
+inode's contents. The default output is suppressed and any flags that
+modify it (such as B<-vnode>) are ignored.
-=item -orphaned
+=item B<-orphaned>
Displays a large vnode and small vnode table for each volume, which lists
-only orphaned vnodes (vnodes that have no parent). If there are none,
-the tables are empty (only the headers appear).
+only orphaned vnodes (vnodes that have no parent). If there are none, the
+tables are empty (only the headers appear).
-=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
By default, the command produces several line of statistics for each
volume. Adding other options produces or substitutes additional
-information as described in the preceding B<Options> section of this
-reference page. The output is intended for debugging purposes and is
-meaningful to someone familiar with the internal structure of volume
-headers.
+information as described in L<OPTIONS>. The output is intended for
+debugging purposes and is meaningful to someone familiar with the internal
+structure of volume headers.
=head1 PRIVILEGE REQUIRED
-The issuer must be logged in as the local superuser root.
+The issuer must be logged in as the local superuser C<root>.
=head1 SEE ALSO
-L<vldb.DB0 and vldb.DBSYS1(1)>
-
-L<volserver(1)>
+L<vldb.DB0(5)>,
+L<volserver(8)>
=head1 COPYRIGHT
=head1 SYNOPSIS
-B<volserver> [B<-log>] [-p <I<number of processes>>]
-[B<-udpsize> <I<size of socket buffer in bytes>>]
- [B<-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<volserver> [B<-log>] [B<-p> <I<number of processes>>]
+ [B<-udpsize> <I<size of socket buffer in bytes>>]
+ [B<-enable_peer_stats>] [B<-enable_process_stats>] [B<-help>]
=head1 DESCRIPTION
-The volserver command initializes the Volume Server component of
-the B<fs> process. In the conventional configuration, its
-binary file is located in the B</usr/afs/bin> directory on a file
-server machine.
+The B<volserver> command initializes the Volume Server component of the
+C<fs> process. In the conventional configuration, its binary file is
+located in the F</usr/afs/bin> directory on a file server machine.
-The volserver command is not normally issued at the command
-shell prompt but rather placed into a file server machine's
-B</usr/afs/local/BosConfig> file with the B<bos create>
-command. If it is ever issued at the command shell prompt, the issuer
-must be logged onto a database server machine as the local superuser
-B<root>.
+The B<volserver> command is not normally issued at the command shell
+prompt but rather placed into a file server machine's
+F</usr/afs/local/BosConfig> file with the B<bos create> command. If it is
+ever issued at the command shell prompt, the issuer must be logged onto a
+database server machine as the local superuser C<root>.
The Volume Server records a trace of its activity in the
-B</usr/afs/logs/VolserLog> file. Use the B<bos getlog>
-command to display the contents of the file.
+F</usr/afs/logs/VolserLog> file. Use the B<bos getlog> command to display
+the contents of the file.
-The Volume Server processes the vos commands that administrators
-use to create, delete, move, and replicate volumes, as well as prepare them
-for archiving to tape or other media.
+The Volume Server processes the B<vos> commands that administrators use to
+create, delete, move, and replicate volumes, as well as prepare them for
+archiving to tape or other media.
By default, the VL Server runs nine lightweight processes (LWPs). To
change the number, use the B<-p> argument.
+This command does not use the syntax conventions of the AFS command
+suites. Provide the command name and all option names in full.
+
=head1 OPTIONS
=over 4
-=item -log
+=item B<-log>
-Records in the /usr/afs/logs/VolserLog file the names of all
-users who successfully initiate a B<vos> command. The Volume
-Server also records any file removals that result from issuing the B<vos
-release> command with the B<-f> flag.
+Records in the /usr/afs/logs/VolserLog file the names of all users who
+successfully initiate a B<vos> command. The Volume Server also records any
+file removals that result from issuing the B<vos release> command with the
+B<-f> flag.
-=item -p
+=item B<-p> <I<number of processes>>
-Sets the number of server lightweight processes (LWPs) to run.
-Provide an integer between B<4> and B<16>. The default
-is 9.
+Sets the number of server lightweight processes (LWPs) to run. Provide an
+integer between C<4> and C<16>. The default is C<9>.
-=item -udpsize
+=item B<-udpsize> <I<size of socket buffer>>
-Sets the size of the UDP buffer, which is 64 KB by default. Provide
-a positive integer, preferably larger than the default.
+Sets the size of the UDP buffer in bytes, which is 64 KB by
+default. Provide a positive integer, preferably larger than the default.
-=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,
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 following B<bos create> command creates a volserver
-process on the machine B<fs2.abc.com>:
+The following B<bos create> command creates a C<volserver> process on the
+machine C<fs2.abc.com>:
- % bos create -server fs2.abc.com -instance volserver -type simple \
+ % bos create -server fs2.abc.com -instance volserver -type simple \
-cmd /usr/afs/bin/volserver
=head1 PRIVILEGE REQUIRED
-The issuer must be logged in as the superuser root on a file
-server machine to issue the command at a command shell prompt. It is
-conventional instead to create and start the process by issuing the B<bos
-create> command.
+The issuer must be logged in as the superuser C<root> on a file server
+machine to issue the command at a command shell prompt. It is conventional
+instead to create and start the process by issuing the B<bos create>
+command.
=head1 SEE ALSO
-L<BosConfig(1)>,
-L<VolserLog(1)>,
-L<bos_create(1)>,
-L<bos_getlog(1)>,
+L<BosConfig(5)>,
+L<VolserLog(5)>,
+L<bos_create(8)>,
+L<bos_getlog(8)>,
L<vos(1)>
=head1 COPYRIGHT
=head1 NAME
-xfs_size_check - Verifies proper inode configuration
+xfs_size_check - Verifies proper IRIX inode configuration
=head1 SYNOPSIS
-xfs_size_check
+B<xfs_size_check>
=head1 DESCRIPTION
-The xfs_size_check command, when run on a file server machine
-that runs IRIX version 6.2 or higher and uses XFS-formatted partitions
-as server partitions (conventionally mounted at B</vicep>
-directories), verifies that each partition uses 512-byte inodes. AFS
-stores information in the inodes on server partitions, and the 256-byte inode
-size that XFS uses by default is not large enough.
+The B<xfs_size_check> command, when run on a file server machine that runs
+IRIX version 6.2 or higher and uses XFS-formatted partitions as server
+partitions (conventionally mounted at F</vicep> directories), verifies
+that each partition uses 512-byte inodes. AFS stores information in the
+inodes on server partitions, and the 256-byte inode size that XFS uses by
+default is not large enough.
=head1 CAUTIONS
and then the following message for each partition on which to run the IRIX
B<mkfs> command with the indicated options:
- I<device>: mkfs -t xfs -i size=512 -l size=4000b I<device>
+ <device>: mkfs -t xfs -i size=512 -l size=4000b <device>
-where I<device> is in a format like /dev/dsk/dks0d0s0 for
-a single disk partition or B</dev/xlv/xlv0> for a logical
-volume.
+where <device> is in a format like C</dev/dsk/dks0d0s0> for a single disk
+partition or C</dev/xlv/xlv0> for a logical volume.
=head1 PRIVILEGE REQUIRED
-The issuer must be logged in as the local superuser root.
+The issuer must be logged in as the local superuser C<root>.
=head1 COPYRIGHT
+++ /dev/null
-=head1 NAME
-
-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]
-
-=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 command produces a large volume of output; to save it for later
-analysis, direct it to a file.
-
-=head1 OPTIONS
-
-=over 4
-
-=item initcmd
-
-Accommodates the command's use of the AFS command parser, and is
-optional.
-
-=item -cmname
-
-Specifies the fully qualified hostname of each client machine for which to
-monitor the Cache Manager.
-
-=item -collID
-
-Specifies each data collection to return, which defines the type and
-amount of data the command interpreter gathers about the Cache Manager.
-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 Cache Manager routines were called since the Cache Manager
-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).
-
-=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,
-and PAG information associated with data access).
-
-=back
-
-=item -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.
-
-=item -frequency
-
-Sets the frequency in seconds at which the program initiates probes to the
-Cache Manager. The default is 30 seconds.
-
-=item -period
-
-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
-
-Displays a trace on the standard output stream as the command runs.
-
-=item -help
-
-Prints the online help for this command. All other valid options
-are ignored.
-
-=back
-
-=head1 SEE ALSO
-
-L<xstat_fs_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.
+++ /dev/null
-=head1 NAME
-
-xstat_fs_test - Displays data collections from the File Server process
-
-=head1 SYNOPSIS
-
-B<xstat_fs_test> [B<initcmd>] -fsname <I<File Server 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_fs_test> [B<initcmd>] -fs <I<File Server name(s) to monitor>>+
-B<-c> <I<Collection(s) to fetch>>+ [B<-o>]
- [-fr <I<poll frequency, in seconds>>]
- [B<-p> <I<data collection time, in minutes>>] [B<-d>] [-h]
-
-=head1 DESCRIPTION
-
-The xstat_fs_test command tests the routines in the
-B<libxstat_fs.a> library and displays the data collections
-associated with the File Server (the B<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 initcmd
-
-Accommodates the command's use of the AFS command parser, and is
-optional.
-
-=item -fsname
-
-Specifies the fully qualified hostname of each file server machine for
-which to monitor the File Server process.
-
-=item -collID
-
-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 B<Rx> protocol activity).
-
-=item 2
-
-Reports all of the internal performance statistics provided by the
-B<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 -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.
-
-=item -frequency
-
-Sets the frequency in seconds at which the program initiates probes to the
-Cache Manager. The default is 30 seconds.
-
-=item -period
-
-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
-
-Displays a trace on the standard output stream as the command runs.
-
-=item -help
-
-Prints the online help for this command. All other valid options
-are ignored.
-
-=back
-
-=head1 SEE ALSO
-
-=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.
projects / packages / o / openafs.git / commitdiff