For the complete OpenAFS manual, install openafs-doc. This is the same
documentation as found at <http://www.openafs.org/>, and is
unfortunately outdated in several respects, but it's the best that we
- have at present. The Administrative Reference manual is one of the most
- useful, as it contains man-page-like pages on most of the AFS commands.
-
- No manual pages are included. Work is underway upstream to write man
- pages for all of the commands based on the old HTML reference manual,
- but that work is not complete yet.
+ have at present.
If want to set up a new cell, read README.servers and then look at the
example session in configuration-transcript.txt.gz in this directory.
the openafs-kpasswd package to get the administrative utilities for
managing those Kerberos accounts.
- -- Russ Allbery <rra@stanford.edu>, Tue Dec 20 17:24:51 2005
+ -- Russ Allbery <rra@debian.org>, Tue Dec 27 15:53:28 2005
compiler other than the default system compiler. (Closes: #338306)
* Call kernel-version correctly from prep-modules, which fixes build
issues with manually-built kernels. (Closes: #344851)
+ * Backport man pages from upstream CVS. (Closes: #79763)
* Include afsmonitor and livesys in openafs-client.
* Include volinfo in openafs-fileserver.
* Document FAM's lack of support for AFS's security model and recommend
goes into each package.
* Don't ignore make distclean errors.
- -- Russ Allbery <rra@debian.org> Mon, 26 Dec 2005 16:17:15 -0800
+ -- Russ Allbery <rra@debian.org> Tue, 27 Dec 2005 15:34:16 -0800
openafs (1.4.0-2) unstable; urgency=low
--- /dev/null
+#!/bin/sh
+#
+# Install man pages, but fixing up paths as we go. All of the man pages
+# are written to use the Transarc paths, and this script fixes those paths to
+# be correct for the chosen configure options as the man pages are installed.
+
+set -e
+
+manpage="$1"
+dest="$2"
+
+afsbackupdir=/var/lib/openafs/backup
+afsbosconfigdir=/etc/openafs
+afsconfdir=/etc/openafs/server
+afsdbdir=/var/lib/openafs/db
+afslocaldir=/etc/openafs/server-local
+afslogsdir=/var/log/openafs
+afssrvlibexecdir=/usr/lib/openafs
+viceetcdir=/etc/openafs
+
+# Build a particular man page. Takes the section title, the section number,
+# the filename of the POD page, and the output file.
+buildpage () {
+ pod2man -c "$1" -r OpenAFS -s "$2" "$3" | \
+ sed -e "s%/usr/afs/local/BosConfig%${afsbosconfigdir}/BosConfig%g" \
+ -e "s%/usr/afs/etc%${afsconfdir}%g" \
+ -e "s%/usr/afs/backup%${afsbackupdir}%g" \
+ -e "s%/usr/afs/bin%${afssrvlibexecdir}%g" \
+ -e "s%/usr/afs/db%${afsdbdir}%g" \
+ -e "s%/usr/afs/local%${afslocaldir}%g" \
+ -e "s%/usr/afs/logs%${afslogsdir}%g" \
+ -e "s%/usr/vice/etc%${viceetcdir}%g" > "$4"
+}
+
+# Create the output directories.
+mkdir -p man1 man5 man8
+
+# Do the work with lots of calls to buildpage.
+cd pod1
+for f in *.pod ; do
+ buildpage 'AFS Command Reference' 1 "$f" \
+ ../man1/`echo "$f" | sed 's/\.pod$//'`.1
+done
+cd ..
+cd pod5
+for f in *.pod ; do
+ buildpage 'AFS File Reference' 5 "$f" \
+ ../man5/`echo "$f" | sed 's/\.pod$//'`.5
+done
+cd ..
+cd pod8
+for f in *.pod ; do
+ buildpage 'AFS Command Reference' 8 "$f" \
+ ../man8/`echo "$f" | sed 's/\.pod$//'`.8
+done
+cd ..
--- /dev/null
+=head1 NAME
+
+afs - Introduction to AFS commands
+
+=head1 DESCRIPTION
+
+AFS provides many commands that enable users and system administrators to
+use and customize its features. Many of the commands belong to the
+following categories, called I<command suites>.
+
+=over 4
+
+=item backup
+
+Interface for configuring and operating the AFS Backup System.
+
+=item bos
+
+Interface to the Basic Overseer (BOS) Server for administering server
+processes and configuration files.
+
+=item fs
+
+Interface for administering access control lists (ACLs), the Cache
+Manager, and other miscellaneous file system functions.
+
+=item fstrace
+
+Interface for tracing Cache Manager operations when debugging problems.
+
+=item kas
+
+Interface to the Authentication Server for administering security and
+authentication information.
+
+=item pts
+
+Interface to the Protection Server for administering AFS ID and group
+membership information.
+
+=item uss
+
+Interface for automated administration of user accounts.
+
+=item vos
+
+Interface to the Volume Server and Volume Location (VL) Server for
+administering volumes.
+
+=back
+
+In addition, there are several commands that do not belong to
+suites.
+
+=head2 AFS Command Syntax
+
+AFS commands that belong to suites have the following structure:
+
+I<command_suite> I<operation_code> B<-switch> <I<value>>[+] [B<-flag>]
+
+=head3 Command Names
+
+Together, the I<command_suite> and I<operation_code> make up the I<command
+name>.
+
+The I<command_suite> specifies the group of related commands to which the
+command belongs, and indicates which command interpreter and server
+process perform the command. AFS has several command suites, including
+B<bos>, B<fs>, B<kas>, B<package>, B<pts>, B<uss> and B<vos>. Some of
+these suites have an interactive mode in which the issuer omits the
+I<operation_code> portion of the command name.
+
+The I<operation_code> tells the command interpreter and server process
+which action to perform. Most command suites include several operation
+codes. The man pages for each command name describe each operation code in
+detail, and the I<IBM AFS Administration Guide> describes how to use them
+in the context of performing administrative tasks.
+
+Several AFS commands do not belong to a suite and so their names do not
+have a I<command_suite> portion. Their structure is otherwise similar to
+the commands in the suites.
+
+=head3 Options
+
+The term I<option> refers to both arguments and flags, which are described
+in the following sections.
+
+=head3 Arguments
+
+One or more arguments can follow the command name. Arguments specify the
+entities on which to act while performing the command (for example, which
+server machine, server process, or file). To minimize the potential for
+error, provide a command's arguments in the order prescribed in its syntax
+definition.
+
+Each argument has two parts, which appear in the indicated order:
+
+=over 4
+
+=item *
+
+The I<switch> specifies the argument's type and is preceded by a hyphen
+(B<->). For instance, the switch B<-server> usually indicates that the
+argument names a server machine. Switches can often be omitted, subject to
+the rules outlined in L<"Conditions for Omitting Switches">.
+
+=item *
+
+The I<value> names a particular entity of the type specified by the
+preceding switch. For example, the proper value for a B<-server> switch is
+a server machine name like C<fs3.abc.com>. Unlike switches (which have a
+required form), values vary depending on what the issuer wants to
+accomplish. Values appear surrounded by angle brackets (C<< <> >>) in
+command descriptions and the online help to show that they are
+user-supplied variable information.
+
+=back
+
+Some arguments accept multiple values, as indicated by trailing plus sign
+(C<+>) in the command descriptions and online help. How many of a
+command's arguments take multiple values, and their ordering with respect
+to other arguments, determine when it is acceptable to omit switches. See
+L<"Conditions for Omitting Switches">.
+
+Some commands have optional as well as required arguments; the command
+descriptions and online help show optional arguments in square brackets
+(C<[]>).
+
+=head3 Flags
+
+Some commands have one or more flags, which specify the manner in which
+the command interpreter and server process perform the command, or what
+kind of output it produces. Flags are preceded by hyphens like switches,
+but they take no values. Although the command descriptions and online help
+generally list a command's flags after its arguments, there is no
+prescribed order for flags. They can appear anywhere on the command line
+following the operation code, except in between the parts of an
+argument. Flags are always optional.
+
+=head3 An Example Command
+
+The following example illustrates the different parts of a command that
+belongs to an AFS command suite.
+
+ % bos getdate -server fs1.abc.com -file ptserver kaserver
+
+where
+
+=over 4
+
+=item *
+
+B<bos> is the command suite. The BOS Server executes most of the commands
+in this suite.
+
+=item *
+
+B<getdate> is the operation code. It tells the BOS Server on the specified
+server machine (in this case C<fs1.abc.com>) to report the modification
+dates of binary files in the local F</usr/afs/bin> directory.
+
+=item *
+
+C<-server fs1.abc.com> is one argument, with B<-server> as the switch and
+C<fs1.abc.com> as the value. This argument specifies the server machine on
+which BOS Server is to collect and report binary dates.
+
+=item *
+
+C<-file ptserver kaserver> is an argument that takes multiple values. The
+switch is B<-file> and the values are C<ptserver> and C<kaserver>. This
+argument tells the BOS Server to report the modification dates on the
+files F</usr/afs/bin/kaserver> and F</usr/afs/bin/ptserver>.
+
+=back
+
+=head3 Rules for Entering AFS Commands
+
+Enter each AFS command on a single line (press <Return> only at the end of
+the command). Some commands in this document appear broken across multiple
+lines, but that is for legibility only.
+
+Use a space to separate each element on a command line from its
+neighbors. Spaces rather than commas also separate multiple values of an
+argument.
+
+In many cases, the issuer of a command can reduce the amount of typing
+necessary by using one or both of the following methods:
+
+=over 4
+
+=item *
+
+Omitting switches.
+
+=item *
+
+Using accepted abbreviations for operation codes, switches (if they are
+included at all), and some types of values.
+
+=back
+
+The following sections explain the conditions for omitting or shortening
+parts of the command line. It is always acceptable to type a command in
+full, with all of its switches and no abbreviations.
+
+=head4 Conditions for Omitting Switches
+
+It is always acceptable to type the switch part of an argument, but in
+many cases it is not necessary. Specifically, switches can be omitted if
+the following conditions are met.
+
+=over 4
+
+=item *
+
+All of the command's required arguments appear in the order prescribed by
+the syntax statement.
+
+=item *
+
+No switch is provided for any argument.
+
+=item *
+
+There is only one value for each argument (but note the important
+exception discussed in the following paragraph).
+
+=back
+
+Omitting switches is possible only because there is a prescribed order for
+each command's arguments. When the issuer does not include switches, the
+command interpreter relies instead on the order of arguments; it assumes
+that the first element after the operation code is the command's first
+argument, the next element is the command's second argument, and so
+on. The important exception is when a command's final required argument
+accepts multiple values. In this case, the command interpreter assumes
+that the issuer has correctly provided one value for each argument up
+through the final one, so any additional values at the end belong to the
+final argument.
+
+The following list describes the rules for omitting switches from the
+opposite perspective: an argument's switch must be provided when any of
+the following conditions apply.
+
+=over 4
+
+=item *
+
+The command's arguments do not appear in the prescribed order.
+
+=item *
+
+An optional argument is omitted but a subsequent optional argument is
+provided.
+
+=item *
+
+A switch is provided for a preceding argument.
+
+=item *
+
+More than one value is supplied for a preceding argument (which must take
+multiple values, of course); without a switch on the current argument, the
+command interpreter assumes that the current argument is another value for
+the preceding argument.
+
+=back
+
+=head4 An Example of Omitting Switches
+
+Consider again the example command from L<"An Example Command">.
+
+ % bos getdate -server fs1.abc.com -file ptserver kaserver
+
+This command has two required arguments: the server machine name
+(identified by the B<-server> switch) and binary file name (identified by
+the B<-file> switch). The second argument accepts multiple values. By
+complying with all three conditions, the issuer can omit the switches:
+
+ % bos getdate fs1.abc.com ptserver kaserver
+
+Because there are no switches, the bos command interpreter relies on the
+order of arguments. It assumes that the first element following the
+operation code, C<fs1.abc.com>, is the server machine name, and that the
+next argument, C<ptserver>, is a binary file name. Then, because the
+command's second (and last) argument accepts multiple values, the command
+interpreter correctly interprets C<kaserver> as an additional value for
+it.
+
+On the other hand, the following is not acceptable because it violates the
+first two conditions in L<"Conditions for Omitting Switches">: even though
+there is only one value per argument, the arguments do not appear in the
+prescribed order, and a switch is provided for one argument but not the
+other.
+
+ % bos getdate ptserver -server fs1.abc.com
+
+=head3 Rules for Using Abbreviations and Aliases
+
+This section explains how to abbreviate operation codes, option names,
+server machine names, partition names, and cell names. It is not possible
+to abbreviate other types of values.
+
+=head4 Abbreviating Operation Codes
+
+It is acceptable to abbreviate an operation code to the shortest form that
+still distinguishes it from the other operation codes in its suite.
+
+For example, it is acceptable to shorten B<bos install> to B<bos i>
+because there are no other operation codes in the B<bos> command suite
+that begin with the letter C<i>. In contrast, there are several B<bos>
+operation codes that start with the letter C<s>, so the abbreviations must
+be longer to remain unambiguous:
+
+=over 4
+
+=item B<bos sa> for bos salvage
+
+=item B<bos seta> for bos setauth
+
+=item B<bos setc> for bos setcellname
+
+=item B<bos setr> for bos setrestart
+
+=item B<bos sh> for bos shutdown
+
+=item B<bos start> for bos start
+
+=item B<bos startu> for bos startup
+
+=item B<bos stat> for bos status
+
+=item B<bos sto> for bos stop
+
+=back
+
+In addition to abbreviations, some operation codes have an I<alias>, a
+short form that is not derived by abbreviating the operation code to its
+shortest unambiguous form. For example, the alias for the B<fs setacl>
+command is B<fs sa>, whereas the shortest unambiguous abbreviation is B<fs
+seta>.
+
+There are two usual reasons an operation code has an alias:
+
+=over 4
+
+=item *
+
+Because the command is frequently issued, it is convenient to have a form
+shorter than the one derived by abbreviating. The B<fs setacl> command is
+an example.
+
+=item *
+
+Because the command's name has changed, but users of previous versions of
+AFS know the former name. For example, B<bos listhosts> has the alias
+B<bos getcell>, its former name. It is acceptable to abbreviate aliases
+to their shortest unambiguous form (for example, B<bos getcell> to B<bos
+getc>).
+
+=back
+
+Even if an operation code has an alias, it is still acceptable to use the
+shortest unambiguous form. Thus, the B<fs setacl> command has three
+acceptable forms: B<fs setacl> (the full form), B<fs seta> (the shortest
+abbreviation), and B<fs sa> (the alias).
+
+=head4 Abbreviating Switches and Flags
+
+It is acceptable to shorten a switch or flag to the shortest form that
+distinguishes it from the other switches and flags for its operation
+code. It is often possible to omit switches entirely, subject to the
+conditions listed in L<"Conditions for Omitting Switches">.
+
+=head4 Abbreviating Server Machine Names
+
+AFS server machines must have fully-qualified Internet-style host names
+(for example, C<fs1.abc.com>), but it is not always necessary to type the
+full name on the command line. AFS commands accept unambiguous shortened
+forms, but depend on the cell's name service (such as the Domain Name
+Service) or a local host table to resolve a shortened name to the
+fully-qualified equivalent when the command is issued.
+
+Most commands also accept the dotted decimal form of the machine's IP
+address as an identifier.
+
+=head4 Abbreviating Partition Names
+
+Partitions that house AFS volumes must have names of the form
+F</vicepI<x>> or F</vicepI<xx>>, where the variable final portion is one
+or two lowercase letters. By convention, the first server partition
+created on a file server machine is called F</vicepa>, the second
+F</vicepb>, and so on. The I<IBM AFS Quick Beginnings> explains how to
+configure and name a file server machine's partitions in preparation for
+storing AFS volumes on them.
+
+When issuing AFS commands, you can abbreviate a partition name using any
+of the following forms:
+
+ /vicepa = vicepa = a = 0
+ /vicepb = vicepb = b = 1
+
+After /vicepz (for which the index is 25) comes
+
+ /vicepaa = vicepaa = aa = 26
+ /vicepab = vicepab = ab = 27
+
+and so on through
+
+ /vicepiv = vicepiv = iv = 255
+
+=head4 Abbreviating Cell Names
+
+A cell's full name usually matches its Internet domain name (such as
+B<stateu.edu> for the State University or C<abc.com> for ABC
+Corporation). Some AFS commands accept unambiguous shortened forms,
+usually with respect to the local F</usr/vice/etc/CellServDB file> but
+sometimes depending on the ability of the local name service to resolve
+the corresponding domain name.
+
+=head3 Displaying Online Help for AFS Commands
+
+To display online help for AFS commands that belong to suites, use the
+B<help> and B<apropos> operation codes. A B<-help> flag is also available
+on every almost every AFS command.
+
+The online help entry for a command consists of two or three lines:
+
+=over 4
+
+=item *
+
+The first line names the command and briefly describes what it does.
+
+=item *
+
+If the command has aliases, they appear on the next line.
+
+=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 typographical symbols (brackets and so on) as this documentation.
+
+=back
+
+If no operation code is specified, the B<help> operation code displays the
+first line (short description) for every operation code in the suite:
+
+ % <command_suite> help
+
+If the issuer specifies one or more operation codes, the B<help> operation
+code displays each command's complete online entry (short description,
+alias if any, and syntax):
+
+ % <command_suite> help <operation_code>+
+
+The B<-help> flag displays a command's syntax but not the short
+description or alias:
+
+ % <command_name> -help
+
+The apropos operation code displays the short description of any command
+in a suite whose operation code or short description includes the
+specified keyword:
+
+ % <command_suite> apropos "<help string>"
+
+The following example command displays the complete online help entry for
+the B<fs setacl> command:
+
+ % fs help setacl
+ fs setacl: set access control list
+ aliases: sa
+ Usage: fs setacl -dir <directory>+ -acl <access list entries>+
+ [-clear] [-negative] [-id] [-if] [-help]
+
+To see only the syntax statement, use the B<-help> flag:
+
+ % fs setacl -help
+ Usage: fs setacl -dir <directory>+ -acl <access list entries>+
+ [-clear] [-negative] [-id] [-if] [-help]
+
+In the following example, a user wants to display the quota for her home
+volume. She knows that the relevant command belongs to the B<fs> suite,
+but cannot remember the operation code. She uses B<quota> as the keyword:
+
+ % fs apropos quota
+ listquota: list volume quota
+ quota: show volume quota usage
+ setquota: set volume quota
+
+The following illustrates the error message that results if no command
+name or short description contains the keyword:
+
+ % fs apropos "list quota"
+ Sorry, no commands found
+
+=head1 PRIVILEGE REQUIRED
+
+Many AFS commands require one or more types of administrative
+privilege. See the reference page for each command.
+
+=head1 SEE ALSO
+
+=over 4
+
+L<afsd(8)>,
+L<afsmonitor(1)>,
+L<backup(8)>,
+L<bos(1)>,
+L<bosserver(8)>,
+L<buserver(8)>,
+L<butc(8)>,
+L<dlog(1)>,
+L<dpass(1)>,
+L<fileserver(8)>,
+L<fms(8)>,
+L<fs(1)>,
+L<fstrace(8)>,
+L<kadb_check(8)>,
+L<kas(8)>,
+L<kaserver(8)>,
+L<kdb(8)>,
+L<klog(1)>,
+L<knfs(1)>,
+L<kpasswd(1)>,
+L<kpwvalid(8)>,
+L<package(1)>,
+L<pagsh(1)>,
+L<prdb_check(8)>,
+L<pts(1)>,
+L<ptserver(8)>,
+L<rxdebug(1)>,
+L<salvager(8)>,
+L<scout(1)>,
+L<sys(1)>,
+L<tokens(1)>,
+L<translate_et(1)>,
+L<unlog(1)>,
+L<up(1)>,
+L<upclient(8)>,
+L<upserver(8)>,
+L<uss(8)>,
+L<vldb_check(8)>,
+L<vlserver(8)>,
+L<volinfo(8)>,
+L<volserver(8)>,
+L<vos(1)>,
+L<xfs_size_check(8)>,
+L<xstat_cm_test(8)>,
+L<xstat_fs_test(8)>
+
+=back
+
+=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
+
+afsmonitor - Monitors File Servers and Cache Managers
+
+=head1 DESCRIPTION
+
+B<afsmonitor> [B<initcmd>] [-config <I<configuration file>>]
+ [B<-frequency> <I<poll frequency, in seconds>>]
+ [B<-output> <I<storage file name>>] [B<-detailed>]
+ [B<-debug> <I<debug output file>>]
+ [B<-fshosts> <I<list of file servers to monitor>>+]
+ [B<-cmhosts> <I<list of cache managers to monitor>>+]
+ [B<-buffers> <I<number of buffer slots>>] [B<-help>]
+
+B<afsmonitor> [B<i>] [-co <I<configuration file>>]
+ [B<-fr> <I<poll frequency, in seconds>>]
+ [B<-o> <I<storage file name>>] [B<-det>]
+ [B<-deb> <I<debug output file>>]
+ [B<-fs> <I<list of file servers to monitor>>+]
+ [B<-cm> <I<list of cache managers to monitor>>+]
+ [B<-b> <I<number of buffer slots>>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The afsmonitor command initializes a program that gathers and displays
+statistics about specified File Server and Cache Manager operations. It
+allows the issuer to monitor, from a single location, a wide range of File
+Server and Cache Manager operations on any number of machines in both
+local and foreign cells.
+
+There are 271 available File Server statistics and 571 available Cache
+Manager statistics, listed in the appendix about B<afsmonitor> statistics
+in the I<IBM AFS Administration Guide>. By default, the command displays
+all of the relevant statistics for the file server machines named by the
+B<-fshosts> argument and the client machines named by the B<-cmhosts>
+argument. To limit the display to only the statistics of interest, list
+them in the configuration file specified by the B<-config> argument. In
+addition, use the configuration file for the following purposes:
+
+=over 4
+
+=item *
+
+To set threshold values for any monitored statistic. When the value of a
+statistic exceeds the threshold, the B<afsmonitor> command displays it in
+reverse video. There are no default threshold values.
+
+=item *
+
+To invoke a program or script automatically when a statistic exceeds its
+threshold. The AFS distribution does not include any such scripts.
+
+=item *
+
+To list the file server and client machines to monitor, instead of using
+the B<-fshosts> and B<-cmhosts> arguments.
+
+=back
+
+For a description of the configuration file, see L<afsmonitor(5)>.
+
+=head1 CAUTIONS
+
+The following software must be accessible to a machine where the
+B<afsmonitor> program is running:
+
+=over 4
+
+=item *
+
+The AFS xstat libraries, which the afsmonitor program uses to gather data.
+
+=item *
+
+The curses graphics package, which most UNIX distributions provide as a
+standard utility.
+
+=back
+
+The B<afsmonitor> screens format successfully both on so-called dumb
+terminals and in windowing systems that emulate terminals. For the output
+to looks its best, the display environment needs to support reverse video
+and cursor addressing. Set the TERM environment variable to the correct
+terminal type, or to a value that has characteristics similar to the
+actual terminal type. The display window or terminal must be at least 80
+columns wide and 12 lines long.
+
+The B<afsmonitor> program must run in the foreground, and in its own
+separate, dedicated window or terminal. The window or terminal is
+unavailable for any other activity as long as the B<afsmonitor> program is
+running. Any number of instances of the B<afsmonitor> program can run on a
+single machine, as long as each instance runs in its own dedicated window
+or terminal. Note that it can take up to three minutes to start an
+additional instance.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<initcmd>
+
+Accommodates the command's use of the AFS command parser, and is optional.
+
+=item B<-config> <I<file>>
+
+Names the configuration file which lists the machines to monitor,
+statistics to display, and threshold values, if any. A partial pathname is
+interpreted relative to the current working directory. Provide this
+argument if not providing the B<-fshosts> argument, B<-cmhosts> argument,
+or neither. For instructions on creating this file, see the preceding
+B<DESCRIPTION> section, and the section on the B<afsmonitor> program in
+the I<IBM AFS Administration Guide>.
+
+=item B<-frequency> <I<poll frequency>>
+
+Specifies in seconds how often the afsmonitor program probes the File
+Servers and Cache Managers. Valid values range from C<1> to C<86400>
+(which is 24 hours); the default value is C<60>. This frequency applies to
+both File Servers and Cache Managers, but the B<afsmonitor> program
+initiates the two types of probes, and processes their results,
+separately. The actual interval between probes to a host is the probe
+frequency plus the time required for all hosts to respond.
+
+=item B<-output> <I<file>>
+
+Names the file to which the afsmonitor program writes all of the
+statistics that it collects. By default, no output file is created. See
+the section on the B<afsmonitor> command in the I<IBM AFS Administration
+Guide> for information on this file.
+
+=item B<-detailed>
+
+Formats the information in the output file named by B<-output> argument in
+a maximally readable format. Provide the B<-output> argument along with
+this one.
+
+=item B<-fshosts> <I<host>>+
+
+Names one or more machines from which to gather File Server
+statistics. For each machine, provide either a fully qualified host name,
+or an unambiguous abbreviation (the ability to resolve an abbreviation
+depends on the state of the cell's name service at the time the command is
+issued). This argument can be combined with the B<-cmhosts> argument, but
+not with the B<-config> argument.
+
+=item B<-cmhosts> <I<host>>+
+
+Names one or more machines from which to gather Cache Manager
+statistics. For each machine, provide either a fully qualified host name,
+or an unambiguous abbreviation (the ability to resolve an abbreviation
+depends on the state of the cell's name service at the time the command is
+issued). This argument can be combined with the B<-fshosts> argument, but
+not with the B<-config> argument.
+
+=item B<-buffers> <I<slots>>
+
+Is nonoperational and provided to accommodate potential future
+enhancements to the program.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+The afsmonitor program displays its data on three screens:
+
+=over 4
+
+=item System Overview
+
+This screen appears automatically when the B<afsmonitor> program
+initializes. It summarizes separately for File Servers and Cache Managers
+the number of machines being monitored and how many of them have I<alerts>
+(statistics that have exceeded their thresholds). It then lists the
+hostname and number of alerts for each machine being monitored, indicating
+if appropriate that a process failed to respond to the last probe.
+
+=item File Server
+
+This screen displays File Server statistics for each file server machine
+being monitored. It highlights statistics that have exceeded their
+thresholds, and identifies machines that failed to respond to the last
+probe.
+
+=item Cache Managers
+
+This screen displays Cache Manager statistics for each client machine
+being monitored. It highlights statistics that have exceeded their
+thresholds, and identifies machines that failed to respond to the last
+probe.
+
+=back
+
+Fields at the corners of every screen display the following information:
+
+=over 4
+
+=item *
+
+In the top left corner, the program name and version number.
+
+=item *
+
+In the top right corner, the screen name, current and total page numbers,
+and current and total column numbers. The page number (for example, C<p. 1
+of 3>) indicates the index of the current page and the total number of
+(vertical) pages over which data is displayed. The column number (for
+example, C<c. 1 of 235>) indicates the index of the current leftmost
+column and the total number of columns in which data appears. (The symbol
+C<<<< >>> >>>> indicates that there is additional data to the right; the
+symbol C<<<< <<< >>>> indicates that there is additional data to the
+left.)
+
+=item *
+
+In the bottom left corner, a list of the available commands. Enter the
+first letter in the command name to run that command. Only the currently
+possible options appear; for example, if there is only one page of data,
+the C<next> and C<prev> commands, which scroll the screen up and down
+respectively, do not appear. For descriptions of the commands, see the
+following section about navigating the display screens.
+
+=item *
+
+In the bottom right corner, the C<probes> field reports how many times the
+program has probed File Servers (C<fs>), Cache Managers (C<cm>), or
+both. The counts for File Servers and Cache Managers can differ. The
+C<freq> field reports how often the program sends probes.
+
+=back
+
+=head2 Navigating the afsmonitor Display Screens
+
+As noted, the lower left hand corner of every display screen displays the
+names of the commands currently available for moving to alternate screens,
+which can either be a different type or display more statistics or
+machines of the current type. To execute a command, press the lowercase
+version of the first letter in its name. Some commands also have an
+uppercase version that has a somewhat different effect, as indicated in
+the following list.
+
+=over 4
+
+=item C<cm>
+
+Switches to the C<Cache Managers> screen. Available only on the C<System
+Overview> and C<File Servers> screens.
+
+=item C<fs>
+
+Switches to the C<File Servers> screen. Available only on the C<System
+Overview> and the C<Cache Managers> screens.
+
+=item C<left>
+
+Scrolls horizontally to the left, to access the data columns situated to
+the left of the current set. Available when the C<<<< <<< >>>> symbol
+appears at the top left of the screen. Press uppercase C<L> to scroll
+horizontally all the way to the left (to display the first set of data
+columns).
+
+=item C<next>
+
+Scrolls down vertically to the next page of machine names. Available when
+there are two or more pages of machines and the final page is not
+currently displayed. Press uppercase C<N> to scroll to the final page.
+
+=item C<oview>
+
+Switches to the C<System Overview> screen. Available only on the C<Cache
+Managers> and C<File Servers> screens.
+
+=item C<prev>
+
+Scrolls up vertically to the previous page of machine names. Available
+when there are two or more pages of machines and the first page is not
+currently displayed. Press uppercase C<N> to scroll to the first page.
+
+=item C<right>
+
+Scrolls horizontally to the right, to access the data columns situated to
+the right of the current set. This command is available when the C<<<< >>>
+>>>> symbol appears at the upper right of the screen. Press uppercase C<R>
+to scroll horizontally all the way to the right (to display the final set
+of data columns).
+
+=back
+
+=head2 The System Overview Screen
+
+The C<System Overview> screen appears automatically as the B<afsmonitor>
+program initializes. This screen displays the status of as many File
+Server and Cache Manager processes as can fit in the current window;
+scroll down to access additional information.
+
+The information on this screen is split into File Server information on
+the left and Cache Manager information on the right. The header for each
+grouping reports two pieces of information:
+
+=over 4
+
+=item *
+
+The number of machines on which the program is monitoring the indicated
+process.
+
+=item *
+
+The number of alerts and the number of machines affected by them (an
+I<alert> means that a statistic has exceeded its threshold or a process
+failed to respond to the last probe).
+
+=back
+
+A list of the machines being monitored follows. If there are any alerts on
+a machine, the number of them appears in square brackets to the left of
+the hostname. If a process failed to respond to the last probe, the
+letters C<PF> (probe failure) appear in square brackets to the left of the
+hostname.
+
+=head2 The File Servers Screen
+
+The C<File Servers> screen displays the values collected at the most
+recent probe for File Server statistics.
+
+A summary line at the top of the screen (just below the standard program
+version and screen title blocks) specifies the number of monitored File
+Servers, the number of alerts, and the number of machines affected by the
+alerts.
+
+The first column always displays the hostnames of the machines running the
+monitored File Servers.
+
+To the right of the hostname column appear as many columns of statistics
+as can fit within the current width of the display screen or window; each
+column requires space for 10 characters. The name of the statistic appears
+at the top of each column. If the File Server on a machine did not respond
+to the most recent probe, a pair of dashes (C<-->) appears in each
+column. If a value exceeds its configured threshold, it is highlighted in
+reverse video. If a value is too large to fit into the allotted column
+width, it overflows into the next row in the same column.
+
+=head2 The Cache Managers Screen
+
+The C<Cache Managers> screen displays the values collected at the most
+recent probe for Cache Manager statistics.
+
+A summary line at the top of the screen (just below the standard program
+version and screen title blocks) specifies the number of monitored Cache
+Managers, the number of alerts, and the number of machines affected by the
+alerts.
+
+The first column always displays the hostnames of the machines running the
+monitored Cache Managers.
+
+To the right of the hostname column appear as many columns of statistics
+as can fit within the current width of the display screen or window; each
+column requires space for 10 characters. The name of the statistic appears
+at the top of each column. If the Cache Manager on a machine did not
+respond to the most recent probe, a pair of dashes (C<-->) appears in each
+column. If a value exceeds its configured threshold, it is highlighted in
+reverse video. If a value is too large to fit into the allotted column
+width, it overflows into the next row in the same column.
+
+=head2 Writing to an Output File
+
+Include the B<-output> argument to name the file into which the
+B<afsmonitor> program writes all of the statistics it collects. The
+output file can be useful for tracking performance over long periods of
+time, and enables the administrator to apply post-processing techniques
+that reveal system trends. The AFS distribution does not include any
+post-processing programs.
+
+The output file is in ASCII format and records the same information as the
+C<File Server> and C<Cache Manager> display screens. Each line in the
+file uses the following format to record the time at which the
+B<afsmonitor> program gathered the indicated statistic from the Cache
+Manager (C<CM>) or File Server (C<FS>) running on the machine called
+I<host_name>. If a probe failed, the error code C<-1> appears in the
+I<statistic> field.
+
+ <time> <host_name> CM|FS <statistic>
+
+If the administrator usually reviews the output file manually, rather than
+using it as input to an automated analysis program or script, including
+the B<-detail> flag formats the data in a more easily readable form.
+
+=head1 EXAMPLES
+
+For examples of commands, display screens, and configuration files, see
+the section about the B<afsmonitor> program in the I<IBM AFS
+Administration Guide>.
+
+=head1 PRIVILEGE REQUIRED
+
+None
+
+=head1 SEE ALSO
+
+L<afsmonitor(5)>
+L<fstrace(8)>,
+L<scout(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
+
+bos - Introduction to the bos command suite
+
+=head1 DESCRIPTION
+
+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.
+
+There are several categories of commands in the B<bos> command suite:
+
+=over 4
+
+=item *
+
+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: 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: 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>.
+
+=item *
+
+A command to restore file system consistency: B<bos salvage>.
+
+=item *
+
+Commands to obtain help: B<bos apropos> and B<bos help>.
+
+=back
+
+The BOS Server and the B<bos> commands use and maintain the following
+configuration and log files:
+
+=over 4
+
+=item *
+
+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 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 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 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 F<UserList> file, use the following commands:
+B<bos adduser>, B<bos listusers>, and B<bos removeuser>.
+
+=item *
+
+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 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 F</usr/afs/log/BosLog> file records important operations the BOS
+Server performs and error conditions it encounters.
+
+=back
+
+For more details, see the reference page for each file.
+
+=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.
+
+=over 4
+
+=item B<-cell> <I<cell name>>
+
+Names the cell in which to run the command. It is acceptable to abbreviate
+the cell name to the shortest form that distinguishes it from the other
+entries in the F</usr/vice/etc/CellServDB> file on the local machine. If
+the B<-cell> argument is omitted, the command interpreter determines the
+name of the local cell by reading the following in order:
+
+=over 4
+
+=item *
+
+The value of the AFSCELL environment variable.
+
+=item *
+
+The local F</usr/vice/etc/ThisCell> file.
+
+=back
+
+Do not combine the B<-cell> and B<-localauth> options. A command on which
+the B<-localauth> flag is included always runs in the local cell (as
+defined in the server machine's local F</usr/afs/etc/ThisCell> file),
+whereas a command on which the B<-cell> argument is included runs in the
+specified foreign cell.
+
+=item B<-help>
+
+Prints a command's online help message on the standard output stream. Do
+not combine this flag with any of the command's other options; when it is
+provided, the command interpreter ignores all other options, and only
+prints the help message.
+
+=item B<-localauth>
+
+Constructs a server ticket using the server encryption key with the
+highest key version number in the local F</usr/afs/etc/KeyFile> file. The
+B<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 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 B<-noauth>
+
+Establishes an unauthenticated connection to the BOS Server, in which the
+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:
+
+=over 4
+
+=item *
+
+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 *
+
+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
+
+=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 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.
+
+=head1 SEE ALSO
+
+L<BosConfig(5)>,
+L<CellServDB(5)>,
+L<KeyFile(5)>,
+L<ThisCell(5)>,
+L<UserList(5)>,
+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)>
+
+=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
+
+bos addhost - Adds a database server machine to the CellServDB file
+
+=head1 SYNOPSIS
+
+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> B<-s> <I<machine name>> B<-ho> <I<host name>>+
+ [B<-c> <I<cell name>>] [B<-n>] [B<-l>] [B<-he>]
+
+=head1 DESCRIPTION
+
+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
+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
+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 B<-server> <I<machine name>>
+
+Identifies the server machine on which to change the
+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(1)>.
+
+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(1)>.
+
+=item B<-host> <I<host name>>+
+
+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 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(1)>.
+
+=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(1)>.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+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(1)>.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+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 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(5)>,
+L<KeyFile(5)>,
+L<UserList(5)>,
+L<bos(1)>,
+L<bos_listhosts(1)>,
+L<bos_removehost(1)>
+
+I<IBM AFS Quick Beginnings>
+
+=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
+
+bos addkey - Adds a new server encryption key to the KeyFile file
+
+=head1 SYNOPSIS
+
+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> 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 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 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 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 B<-server> <I<machine name>>
+
+Indicates the server machine on which to change the
+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(1)>.
+
+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(1)>.
+
+=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(1)>.
+
+=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(1)>.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+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(1)>.
+
+=item B<-help>
+
+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:
+
+ 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 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:
+ Retype input key:
+
+=head1 PRIVILEGE REQUIRED
+
+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(5)>,
+L<UserList(5)>,
+L<bos(1)>,
+L<bos_listkeys(1)>,
+L<bos_removekey(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
+
+bos adduser - Adds a privileged user to the UserList file
+
+=head1 SYNOPSIS
+
+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> 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 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 B<-server> <I<machine name>>
+
+Indicates the server machine on which to change the
+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(1)>.
+
+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(1)>.
+
+=item B<-user> <I<user names>>+
+
+Specifies each user name to insert into the F</usr/afs/etc/UserList> file.
+
+=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(1)>.
+
+=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(1)>.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+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(1)>.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+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 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(5)>,
+L<UserList(5)>,
+L<bos(1)>,
+L<bos_listusers(1)>,
+L<bos_removeuser(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
+
+bos apropos - Displays each help entry containing a keyword string
+
+=head1 SYNOPSIS
+
+B<bos apropos> B<-topic> <I<help string>> [B<-help>]
+
+B<bos ap> B<-t> <I<help string>> [B<-h>]
+
+=head1 DESCRIPTION
+
+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 B<bos help> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=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 (C<"">)
+or other delimiters.
+
+=item B<-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<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 B<bos> commands that include the word
+C<restart> in their names or short descriptions:
+
+ % bos apropos restart
+ getrestart: get restart times
+ restart: restart all processes
+ setrestart: set restart times
+
+=head1 PRIVILEGE REQUIRED
+
+None
+
+=head1 SEE ALSO
+
+L<bos(1)>,
+L<bos_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
+
+bos create - Defines a new process in the BosConfig file and starts it
+
+=head1 SYNOPSIS
+
+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> 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 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 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 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 L<bos(1)>.
+
+=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:
+
+=over 4
+
+=item buserver
+
+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>).
+
+=item kaserver
+
+The Authentication Server process.
+
+=item ptserver
+
+The Protection Server process.
+
+=item runntp
+
+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 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 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.
+
+=item vlserver
+
+The Volume Location (VL) Server process.
+
+=back
+
+=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.
+
+=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.
+
+=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.
+
+=back
+
+=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.
+
+For a simple process, provide the complete pathname of the process's
+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:
+
+=over 4
+
+=item *
+
+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 (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:
+
+=over 4
+
+=item *
+
+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: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 (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 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 L<NOTES>.
+
+=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(1)>.
+
+=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(1)>.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+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(1)>.
+
+=item B<-help>
+
+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
+C<kaserver> on the machine C<fs3.abc.com>:
+
+ % bos create -server fs3.abc.com -instance kaserver -type simple \
+ -cmd /usr/afs/bin/kaserver
+
+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
+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 \
+ /usr/afs/bin/salvager
+
+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
+
+=head1 PRIVILEGE REQUIRED
+
+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 NOTES
+
+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
+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.
+
+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.
+
+struct bnode contents:
+
+ struct bnode {
+ struct bnode *next; /* next pointer in top-level's list */
+ char *name; /* instance name */
+ long nextTimeout; /* next time this guy should be awakened */
+ long period; /* period between calls */
+ long rsTime; /* time we started counting restarts */
+ long rsCount; /* count of restarts since rsTime */
+ struct bnode_type *type; /* type object */
+ struct bnode_ops *ops; /* functions implementing bnode class */
+ long procStartTime; /* last time a process was started */
+ long procStarts; /* number of process starts */
+ long lastAnyExit; /* last time a process exited for any reason */
+ long lastErrorExit; /* last time a process exited unexpectedly */
+ long errorCode; /* last exit return code */
+ long errorSignal; /* last proc terminating signal */
+ char *lastErrorName; /* name of proc that failed last */
+ short refCount; /* reference count */
+ short flags; /* random flags */
+ char goal; /* 1=running or 0=not running */
+ char fileGoal; /* same, but to be stored in file */
+};
+
+Format of struct bnode explosion:
+
+ printf("name: %s\n",tp->name);
+ printf("rsTime: %ld\n", tp->rsTime);
+ printf("rsCount: %ld\n", tp->rsCount);
+ printf("procStartTime: %ld\n", tp->procStartTime);
+ printf("procStarts: %ld\n", tp->procStarts);
+ printf("lastAnyExit: %ld\n", tp->lastAnyExit);
+ printf("lastErrorExit: %ld\n", tp->lastErrorExit);
+ printf("errorCode: %ld\n", tp->errorCode);
+ printf("errorSignal: %ld\n", tp->errorSignal);
+ printf("lastErrorName: %s\n", tp->lastErrorName);
+ printf("goal: %d\n", tp->goal);
+
+struct bnode_proc contents:
+
+ struct bnode_proc {
+ struct bnode_proc *next; /* next guy in top-level's list */
+ struct bnode *bnode; /* bnode creating this process */
+ char *comLine; /* command line used to start this process */
+ char *coreName; /* optional core file component name */
+ long pid; /* pid if created */
+ long lastExit; /* last termination code */
+ long lastSignal; /* last signal that killed this guy */
+ long flags; /* flags giving process state */
+};
+
+Format of struct bnode_proc explosion:
+
+ printf("comLine: %s\n", tp->comLine);
+ printf("coreName: %s\n", tp->coreName);
+ printf("pid: %ld\n", tp->pid);
+ printf("lastExit: %ld\n", tp->lastExit);
+ printf("lastSignal: %ld\n", tp->lastSignal);
+
+=head1 SEE ALSO
+
+L<BosConfig(5)>,
+L<KeyFile(5)>,
+L<UserList(5)>,
+L<bos(1)>,
+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
+
+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
+
+bos delete - Deletes a server process from the BosConfig file
+
+=head1 SYNOPSIS
+
+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> 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 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 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 B<-server> <I<machine name>>
+
+Indicates the server machine on which to delete the server process entry
+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 L<bos(1)>.
+
+=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.
+
+=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(1)>.
+
+=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(1)>.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+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(1)>.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+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
+
+=head1 PRIVILEGE REQUIRED
+
+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(5)>,
+L<KeyFile(5)>,
+L<UserList(5)>,
+L<bos(1)>,
+L<bos_create(1)>,
+L<bos_status(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
+
+bos exec - Executes a command on a remote server machine
+
+=head1 SYNOPSIS
+
+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> 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 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 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 L<bos(1)>.
+
+=item B<-cmd> <I<command to execute>>
+
+Specifies the complete local disk pathname of the command to execute (for
+example, F</sbin/reboot>). Surround this argument with double quotes
+(C<"">) if the command contains one or more spaces.
+
+=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(1)>.
+
+=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(1)>.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+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(1)>.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+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 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)>
+
+=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
+
+bos getdate - Displays the time stamps on an AFS binary file
+
+=head1 SYNOPSIS
+
+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> 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 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 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 L<bos(1)>.
+
+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 B<-file> <I<files to check>>+
+
+Names each binary file to list.
+
+=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 F</usr/afs/bin> directory.
+
+=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(1)>.
+
+=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(1)>.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+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(1)>.
+
+=item B<-help>
+
+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.
+
+=head1 EXAMPLES
+
+The following command examines the time stamps on the files with basename
+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.
+ .BAK file dated Wed Dec 9 18:55:04 1998, no .OLD file.
+
+=head1 PRIVILEGE REQUIRED
+
+None
+
+=head1 SEE ALSO
+
+L<KeyFile(5)>,
+L<bos(1)>,
+L<bos_install(1)>,
+L<bos_prune(1)>,
+L<bos_uninstall(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
+
+bos getlog - Prints a server process's log file
+
+=head1 SYNOPSIS
+
+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> 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 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.
+
+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.
+
+=head1 OPTIONS
+
+=over 4
+
+=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 L<bos(1)>.
+
+=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 F</usr/afs/logs> directory; the
+standard values are:
+
+=over 4
+
+=item F<AuthLog>
+
+The Authentication Server (B<kaserver>) log file.
+
+=item F<BackupLog>
+
+The Backup Server (B<buserver>) log file.
+
+=item F<BosLog>
+
+The BOS Server (B<bosserver>) log file.
+
+=item F<FileLog>
+
+The File Server (B<fileserver>) log file.
+
+=item F<SalvageLog>
+
+The Salvager (B<salvager>) log file.
+
+=item F<VLLog>
+
+The Volume Location (VL) Server (B<vlserver>) log file.
+
+=item F<VolserLog>
+
+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
+F</usr/afs/logs> directory.
+
+=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(1)>.
+
+=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(1)>.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+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(1)>.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+The output is preceded by the line
+
+ 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
+C<fs3.abc.com>:
+
+ % bos getlog -server fs3.abc.com -file FileLog
+ Fetching log file 'FileLog'...
+ Sun Nov 8 04:00:34 1998 File server starting
+ Sun Nov 8 04:00:39 1998 Partition /vicepa: attached 21 volumes;
+ 0 volumes not attached
+ Sun Nov 8 04:00:40 1998 File Server started Sun Nov 8 04:00:40
+ 1998
+ Mon Nov 9 21:45:06 1998 CB: RCallBack (zero fid probe in host.c)
+ failed for host 28cf37c0.22811
+
+=head1 PRIVILEGE REQUIRED
+
+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)>
+
+=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
+
+bos getrestart - Displays the automatic restart times for server processes
+
+=head1 SYNOPSIS
+
+B<bos getrestart> B<-server> <I<machine name>> [B<-cell> <I<cell name>>]
+ [B<-noauth>] [B<-localauth>] [B<-help>]
+
+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
+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
+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
+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 B<bos setrestart> command to set the restart times.
+
+=head1 OPTIONS
+
+=over 4
+
+=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 L<bos(1)>.
+
+=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(1)>.
+
+=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(1)>.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+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(1)>.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+The output consists of two lines:
+
+ Server <machine_name> restarts at <time>
+ Server <machine_name> restarts for new binaries at <time>
+
+Possible values for <time> include:
+
+=over 4
+
+=item *
+
+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.
+
+=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>.
+
+=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>.
+
+=back
+
+=head1 EXAMPLES
+
+The following example displays the restart times for the machine
+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
+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
+ Server fs1 restarts for new binaries at 11:30 pm
+
+=head1 PRIVILEGE REQUIRED
+
+None
+
+=head1 SEE ALSO
+
+L<BosConfig(5)>,
+L<KeyFile(5)>,
+L<bos(1)>,
+L<bos_getdate(1)>,
+L<bos_setrestart(1)>,
+L<bos_status(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
+
+bos help - Displays help for bos commands
+
+=head1 SYNOPSIS
+
+B<bos help> [B<-topic> <I<help string>>+] [B<-help>]
+
+B<bos h> [B<-t> <I<help string>>+] [B<-h>]
+
+=head1 DESCRIPTION
+
+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.
+
+=head1 OPTIONS
+
+=over 4
+
+=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.
+
+=item B<-help>
+
+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:
+
+=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 B<bos status>
+command:
+
+ % bos help status
+ bos status: show server instance status
+ Usage: bos status -server <machine name> [-instance <server
+ process name>+] [-long] [-cell <cell name>] [-noauth]
+ [-localauth] [-help]
+
+=head1 PRIVILEGE REQUIRED
+
+None
+
+=head1 SEE ALSO
+
+L<bos(1)>,
+L<bos_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
+
+bos install - Installs a new version of a binary file
+
+=head1 SYNOPSIS
+
+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> 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 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.
+
+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 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 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 L<bos(1)>.
+
+If the machine is not a binary distribution machine and is running an
+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 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. L<bos_create(1)> 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 F</usr/afs/bin>.
+
+=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(1)>.
+
+=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(1)>.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+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(1)>.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command copies the file
+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 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(5)>,
+L<KeyFile(5)>,
+L<UserList(5)>,
+L<bos(1)>,
+L<bos_getdate(1)>,
+L<bos_getrestart(1)>,
+L<bos_restart(1)>,
+L<bos_setrestart(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
+
+bos listhosts - Displays the contents of the CellServDB file
+
+=head1 SYNOPSIS
+
+B<bos listhosts> B<-server> <I<machine name>> [B<-cell> <I<cell name>>]
+ [B<-noauth>] [B<-localauth>] [B<-help>]
+
+B<bos listh> B<-s> <I<machine name>> [B<-c> <I<cell name>>] [B<-n>]
+ [B<-l>] [-h]
+
+B<bos getcell> B<-server> <I<machine name>> [B<-cell> <I<cell name>>]
+ [B<-noauth>] [B<-localauth>] [B<-help>]
+
+B<bos getc> B<-s> <I<machine name>> [B<-c> <I<cell name>>] [B<-n>]
+ [B<-l>] [-h]
+
+=head1 DESCRIPTION
+
+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 B<bos
+removehost> commands.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-server> <I<machine name>>
+
+Indicates the server machine from which to display the
+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(1)>.
+
+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.
+
+=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(1)>.
+
+=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(1)>.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+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(1)>.
+
+=item B<-help>
+
+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.
+
+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
+performing the B<bos addhost> command.
+
+=head1 EXAMPLES
+
+The following command displays the database server machines listed in the
+F</usr/afs/etc/CellServDB> file on the machine C<fs7.abc.com>.
+
+ % bos listhosts fs7.abc.com
+ Cell name is abc.com
+ Host 1 is db1.abc.com
+ Host 2 is db2.abc.com
+ Host 3 is db3.abc.com
+
+=head1 PRIVILEGE REQUIRED
+
+None
+
+=head1 SEE ALSO
+
+L<CellServDB(5)>,
+L<KeyFile(5)>,
+L<bos(1)>,
+L<bos_addhost(1)>,
+L<bos_removehost(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
+
+bos listkeys - Displays the server encryption keys from the KeyFile file
+
+=head1 SYNOPSIS
+
+B<bos listkeys> B<-server> <I<machine name>> [B<-showkey>]
+ [B<-cell> <I<cell name>>] [B<-noauth>] [B<-localauth>] [B<-help>]
+
+B<bos listk> B<-se> <I<machine name>> [B<-sh>] [B<-c> <I<cell name>>]
+ [B<-n>] [B<-l>] [B<-h>]
+
+=head1 DESCRIPTION
+
+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 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.
+
+=head1 OPTIONS
+
+=over 4
+
+=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 L<bos(1)>.
+
+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.
+
+=item B<-showkey>
+
+Displays the octal digits that constitute each key.
+
+=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(1)>.
+
+=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(1)>.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+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(1)>.
+
+=item B<-help>
+
+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
+F<KeyFile> file, identified by its key version number.
+
+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 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 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
+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
+F<KeyFile> file on the machine C<fs3.abc.com>.
+
+ % bos listkeys fs3.abc.com
+ key 1 has cksum 972037177
+ key 3 has cksum 2825175022
+ key 4 has cksum 260617746
+ key 6 has cksum 4178774593
+ Keys last changed on Mon Apr 12 11:24:46 1999.
+ All done.
+
+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'
+ key 1 is '\343\315\307\227\255\320\135\244'
+ key 2 is '\310\310\255\253\326\236\261\211'
+ Keys last changed on Wed Mar 31 11:24:46 1999.
+ All done.
+
+=head1 PRIVILEGE REQUIRED
+
+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(5)>,
+L<UserList(5)>,
+L<bos_addkey(1)>,
+L<bos_removekey(1)>,
+L<bos_setauth(1)>,
+L<kas_examine(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+bos listusers - Lists the privileged users from the UserList file
+
+=head1 SYNOPSIS
+
+B<bos listusers> B<-server> <I<machine name>> [B<-cell> <I<cell name>>]
+ [B<-noauth>] [B<-localauth>] [B<-help>]
+
+B<bos listu> B<-s> <I<machine name>> [B<-c> <I<cell name>>] [B<-n>]
+ [B<-l>] [B<-h>]
+
+=head1 DESCRIPTION
+
+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 B<bos removeuser>
+commands.
+
+=head1 OPTIONS
+
+=over 4
+
+=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 L<bos(1)>.
+
+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.
+
+=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(1)>.
+
+=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(1)>.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+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(1)>.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+The output lists the user name of each user entitled to issue privileged
+B<bos> and B<vos> commands.
+
+=head1 EXAMPLES
+
+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 PRIVILEGE REQUIRED
+
+None
+
+=head1 SEE ALSO
+
+L<KeyFile(5)>,
+L<UserList(5)>,
+L<bos(1)>,
+L<bos_adduser(1)>,
+L<bos_removeuser(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
+
+bos prune - Removes obsolete files from /usr/afs/bin and /usr/afs/logs
+
+=head1 SYNOPSIS
+
+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> 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 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 B<-bak> flag removes all files from the F</usr/afs/bin> directory that
+have a C<.BAK> extension.
+
+=item *
+
+The B<-old> flag removes all files from the F</usr/afs/bin> directory that
+have a C<.OLD> extension.
+
+=item *
+
+The B<-core> flag removes all files from the F</usr/afs/logs> directory
+that have a C<core.> prefix.
+
+=item *
+
+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.
+
+=head1 OPTIONS
+
+=over 4
+
+=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 L<bos(1)>.
+
+=item B<-bak>
+
+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 B<-old>
+
+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 B<-core>
+
+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 B<-all>
+
+Combines the effect of the B<-bak>, B<-old>, and B<-core> flags. Do not
+combine this flag with any of those three.
+
+=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(1)>.
+
+=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(1)>.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+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(1)>.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+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 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 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(5)>,
+L<UserList(5)>,
+L<bos(1)>,
+L<bos_getdate(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
+
+bos removehost - Removes a database server machine from the CellServDB file
+
+=head1 SYNOPSIS
+
+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> B<-s> <I<machine name>> B<-ho> <I<host name>>+
+ [B<-c> <I<cell name>>] [B<-n>] [B<-l>] [B<-he>]
+
+=head1 DESCRIPTION
+
+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
+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 B<-server> <I<machine name>>
+
+Indicates the server machine on which to change the
+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(1)>.
+
+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(1)>.
+
+=item B<-host> <I<host name>>+
+
+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 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(1)>.
+
+=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(1)>.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+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(1)>.
+
+=item B<-help>
+
+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
+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 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(5)>,
+L<UserList(5)>,
+L<bos(1)>,
+L<bos_addhost(1)>,
+L<bos_listhosts(1)>
+
+I<IBM AFS Quick Beginnings>
+
+=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
+
+bos removekey - Removes a server encryption key from the KeyFile file
+
+=head1 SYNOPSIS
+
+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> 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 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.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-server> <I<machine name>>
+
+Indicates the server machine on which to change the
+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(1)>.
+
+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(1)>.
+
+=item B<-kvno> <I<key version number>>+
+
+Specifies the key version number of each key to remove.
+
+=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(1)>.
+
+=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(1)>.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+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(1)>.
+
+=item B<-help>
+
+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 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 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(5)>,
+L<UserList(5)>,
+L<bos(1)>,
+L<bos_addkey(1)>,
+L<bos_listkeys(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
+
+bos removeuser - Removes a privileged user from the UserList file
+
+=head1 SYNOPSIS
+
+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> B<-s> <I<machine name>> B<-u> <I<user names>>+
+ [B<-c> <I<cell name>>] [B<-n>] [B<-l>] [B<-h>]
+
+=head1 DESCRIPTION
+
+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 B<-server> <I<machine name>>
+
+Indicates the server machine on which to change the
+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(1)>.
+
+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(1)>.
+
+=item B<-user> <I<user names>>+
+
+Specifies each user name to remove.
+
+=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(1)>.
+
+=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(1)>.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+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(1)>.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+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 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(5)>,
+L<UserList(5)>,
+L<bos(1)>,
+L<bos_addkey(1)>,
+L<bos_listkeys(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
+
+bos restart - Restarts a server process
+
+=head1 SYNOPSIS
+
+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> 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 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 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 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 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 F<BosConfig>
+file.
+
+=head1 OPTIONS
+
+=over 4
+
+=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 L<bos(1)>.
+
+=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.
+
+=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 F<BosConfig>
+file. Provide this flag or one of the B<-instance> or B<-all> options, but
+do not combine them.
+
+=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 F<BosConfig> file. Provide this flag or one of the
+B<-instance> or B<-bosserver> options, but do not combine them.
+
+=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(1)>.
+
+=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(1)>.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+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(1)>.
+
+=item B<-help>
+
+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 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 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 C<db3.abc.com>:
+
+ % bos restart -server db3.abc.com -instance ptserver vlserver
+
+=head1 PRIVILEGE REQUIRED
+
+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(5)>,
+L<KeyFile(5)>,
+L<UserList(5)>,
+L<bos(1)>,
+L<bos_create(1)>,
+L<bos_status(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
+
+bos salvage - Restores internal consistency to a file system or volume
+
+=head1 SYNOPSIS
+
+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 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
+
+=item *
+
+If the volume header is corrupted, the Salvager removes the volume
+completely and records the removal in its log file,
+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.
+
+=back
+
+Use the indicated arguments to salvage a specific number of volumes:
+
+=over 4
+
+=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.
+
+=item *
+
+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 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 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 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.
+
+=head1 OPTIONS
+
+=over 4
+
+=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 L<bos(1)>.
+
+=item B<-partition> <I<salvage partition>>
+
+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:
+
+ /vicepa = vicepa = a = 0
+ /vicepb = vicepb = b = 1
+
+After F</vicepz> (for which the index is 25) comes
+
+ /vicepaa = vicepaa = aa = 26
+ /vicepab = vicepab = ab = 27
+
+and so on through
+
+ /vicepiv = vicepiv = iv = 255
+
+=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.
+
+=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 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 B<-all>
+
+Salvages all volumes on all of the partitions on the machine named by the
+B<-server> argument.
+
+=item B<-showlog>
+
+Displays the trace of the salvage operation on the standard output stream,
+as well as writing it to the F</usr/afs/logs/SalvageLog> file. Do not
+combine this flag with the B<-file> argument.
+
+=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:
+
+=over 4
+
+=item *
+
+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 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 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.
+
+=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 B<-orphans> (ignore | remove | attach)
+
+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
+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
+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:
+
+=over 4
+
+=item *
+
+C<__ORPHANFILE__.I<index>> for files.
+
+=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.
+
+=back
+
+=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(1)>.
+
+=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(1)>.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+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(1)>.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+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 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
+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 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(5)>,
+L<SalvageLog(5)>,
+L<UserList(5)>,
+L<bos(1)>,
+L<salvager(8)>,
+L<vos_backup(1)>,
+L<vos_release(1)>,
+L<vos_remove(1)>,
+L<vos_zap(1)>
+
+I<IBM AFS Administration Guide>
+
+=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
+
+bos setauth - Sets authorization checking requirements for all server processes
+
+=head1 SYNOPSIS
+
+B<bos setauth> B<-server> <I<machine name>> B<-authrequired> (on | off)
+ [B<-cell> <I<cell name>>] [B<-noauth>] [B<-localauth>] [B<-help>]
+
+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 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
+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 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 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 L<bos(1)>.
+
+=item B<-authrequired> (on | off)
+
+Enables authorization checking if the value is C<on>, or disables it if
+the value is C<off>.
+
+=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(1)>.
+
+=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(1)>.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+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(1)>.
+
+=item B<-help>
+
+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
+C<fs7.abc.com>:
+
+ % bos setauth -server fs7.abc.com -authrequired off
+
+=head1 PRIVILEGE REQUIRED
+
+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(5)>,
+L<NoAuth(5)>,
+L<UserList(5)>,
+L<bos(1)>,
+L<bos_restart(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
+
+bos setcellname - Sets the cell's name in ThisCell and CellServDB
+
+=head1 SYNOPSIS
+
+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> B<-s> <I<machine name>> B<-n> <I<cell name>>
+ [B<-c> <I<cell name>>] [B<-n>] [B<-l>] [-h]
+
+=head1 DESCRIPTION
+
+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 *
+
+F</usr/afs/etc/ThisCell>
+
+=item *
+
+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
+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.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-server> <I<machine name>>
+
+Indicates the server machine on which to set the cell name in the
+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(1)>.
+
+=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 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 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(1)>.
+
+=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(1)>.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+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(1)>.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+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 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(5)>,
+L<KeyFile(5)>,
+L<ThisCell(5)>,
+L<UserList(5)>,
+L<bos(1)>
+
+I<IBM AFS Quick Beginnings>
+
+I<IBM AFS Administration Guide>
+
+=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
+
+bos setrestart - Sets when the BOS Server restarts processes
+
+=head1 SYNOPSIS
+
+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> 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 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
+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 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.
+
+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.
+
+=head1 OPTIONS
+
+=over 4
+
+=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 L<bos(1)>.
+
+=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
+defined as daily (specifies only a time). However, it is acceptable to
+define a daily general restart or weekly binary restart.
+
+There are four acceptable values for either type of restart setting:
+
+=over 4
+
+=item *
+
+The string C<never>, which directs the BOS Server never to perform the
+indicated type of restart.
+
+=item *
+
+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: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 (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
+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 B<-general>
+
+Sets the general restart time.
+
+=item B<-newbinary>
+
+Sets the binary restart time.
+
+=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(1)>.
+
+=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(1)>.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+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(1)>.
+
+=item B<-help>
+
+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
+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
+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 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(5)>,
+L<KeyFile(5)>,
+L<UserList(5)>,
+L<bos(1)>,
+L<bos_getrestart(1)>,
+L<bos_restart(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
+
+bos shutdown - Stops a process without changing its status flag
+
+=head1 SYNOPSIS
+
+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> 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 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.
+
+=item *
+
+Only the processes specified by the B<-instance> argument.
+
+=back
+
+This command does not change a process's status flag in the
+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 F<BosConfig> status flag is C<Run>).
+
+=head1 OPTIONS
+
+=over 4
+
+=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 L<bos(1)>.
+
+=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.
+
+=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.
+
+=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(1)>.
+
+=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(1)>.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+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(1)>.
+
+=item B<-help>
+
+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 C<fs3.abc.com>.
+
+ % bos shutdown fs3.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 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(5)>,
+L<KeyFile(5)>,
+L<UserList(5)>,
+L<bos(1)>,
+L<bos_create(1)>,
+L<bos_restart(1)>,
+L<bos_start(1)>,
+L<bos_startup(1)>,
+L<bos_status(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
+
+bos start - Starts a process after setting its status flag
+
+=head1 SYNOPSIS
+
+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> 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 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 F<BosConfig>
+file, use the B<bos startup> command instead.
+
+=head1 OPTIONS
+
+=over 4
+
+=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 L<bos(1)>.
+
+=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.
+
+=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(1)>.
+
+=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(1)>.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+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(1)>.
+
+=item B<-help>
+
+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 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 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(5)>,
+L<KeyFile(5)>,
+L<UserList(5)>,
+L<bos(1)>,
+L<bos_create(1)>,
+L<bos_startup(1)>,
+L<bos_status(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
+
+bos startup - Starts a process without changing its status flag
+
+=head1 SYNOPSIS
+
+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> B<-s> <I<machine name>> [B<-i> <I<instances>>+]
+ [B<-c> <I<cell name>>] [B<-n>] [B<-l>] [B<-h>]
+
+=head1 DESCRIPTION
+
+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 F</usr/afs/local/BosConfig> file.
+
+=item *
+
+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 F<BosConfig> status flag to C<Run>, use the
+B<bos start> command instead.
+
+=head1 OPTIONS
+
+=over 4
+
+=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 L<bos(1)>.
+
+=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.
+
+=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(1)>.
+
+=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(1)>.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+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(1)>.
+
+=item B<-help>
+
+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 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>, 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
+
+=head1 PRIVILEGE REQUIRED
+
+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(5)>,
+L<KeyFile(5)>,
+L<UserList(5)>,
+L<bos(1)>,
+L<bos_create(1)>,
+L<bos_start(1)>,
+L<bos_status(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
+
+bos status - Displays the status of server processes
+
+=head1 SYNOPSIS
+
+B<bos status -server> <I<machine name>> [-instance <I<server process name>>+]
+[B<-long>] [B<-cell> <I<cell name>>] [B<-noauth>] [B<-localauth>] [B<-help>]
+
+B<bos stat -s> <I<machine name>> [-i <I<server process name>>+]
+[B<-lon>] [B<-c> <I<cell name>>] [B<-n>] [B<-loc>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The bos status command reports the status of processes on the
+server machine named by the B<-server> argument, either
+
+=over 4
+
+=item *
+
+All of the AFS server processes listed in the
+F</usr/afs/local/BosConfig> file
+
+=item *
+
+Only these processes named by the -instance argument
+
+=back
+
+=head1 OPTIONS
+
+=over 4
+
+=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 L<bos(1)>.
+
+=item -instance
+
+Names each process for which to report status. Use the process name
+assigned with the B<-instance> argument to the B<bos>
+command. The output from the B<bos status> command lists the
+names.
+
+=item -long
+
+Produces more detailed status information.
+
+=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(1)>.
+
+=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(1)>.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+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(1)>.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options
+are ignored.
+
+=back
+
+=head1 OUTPUT
+
+The output for a process includes at least one line, which reports one of
+the following as the process's current status:
+
+=over 4
+
+=item *
+
+C<currently running normally>. The process's status
+flag in the B<BosConfig> file is C<Run>. For
+B<cron> entries, this message indicates only that the command is
+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
+although its status flag in the B<BosConfig> file is
+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
+indicated message appears in its entry:
+
+=over 4
+
+=item *
+
+C<has core file>. The process failed and created a core
+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
+report the process's C<Auxiliary status>, which is one of the
+following:
+
+=over 4
+
+=item *
+
+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
+status> that reports when the command will next execute.
+
+If the -long flag is used, each entry includes the following
+additional information:
+
+=over 4
+
+=item *
+
+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
+processes in the B<fs> process) last terminated. This line does
+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
+component processes in the B<fs> process) last failed due to an
+error. A further explanation such as C<due to shutdown request>
+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 F</usr/afs>
+directory differ from the expected values, it prints the following warning
+message:
+
+ Bosserver reports inappropriate access on server directories
+
+The following chart summarizes the expected mode bit settings. A
+question mark indicates that the BOS Server does not check that bit.
+
+=head1 EXAMPLES
+
+The following example command displays the status of processes on the
+machine B<fs3.abc.com>:
+
+ % bos status fs3.abc.com
+ Instance buserver, currently running normally.
+ Instance kaserver, currently running normally.
+ Instance ptserver, currently running normally.
+ Instance vlserver, currently running normally.
+ Instance fs, has core file, currently running normally.
+ Auxiliary status is: file server running.
+ Instance upserver, currently running normally.
+ Instance runntp, currently running normally.
+
+The following example command displays a detailed status report for the
+B<fs> and B<ptserver> processes on the machine
+B<fs1.abc.com>.
+
+ % bos status -server fs1.abc.com -instance fs ptserver -long
+ Instance fs, (type is fs), currently running normally.
+ Auxiliary status is: file server running.
+ Process last started at Wed Jan 7 5:34:49 1998 (3 proc starts)
+ Last exit at Wed Jan 7 5:34:49 1998
+ Last error exit at Wed Jan 7 5:34:49 1998, due to shutdown
+ request
+ Command 1 is '/usr/afs/bin/fileserver'
+ Command 2 is '/usr/afs/bin/volserver'
+ Command 3 is '/usr/afs/bin/salvager'
+ Instance ptserver, (type is simple) currently running normally.
+ Process last started at Tue Jan 6 8:29:19 1998 (1 proc starts)
+ Command 1 is '/usr/afs/bin/ptserver'
+
+=head1 PRIVILEGE REQUIRED
+
+None
+
+=head1 SEE ALSO
+
+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)>
+
+=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
+
+bos stop - Stops a process after changing its status flag
+
+=head1 SYNOPSIS
+
+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> 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 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 F<BosConfig> status flag, use the
+B<bos shutdown> command instead.
+
+=head1 OPTIONS
+
+=over 4
+
+=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 L<bos(1)>.
+
+=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.
+
+=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.
+
+=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(1)>.
+
+=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(1)>.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+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(1)>.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+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 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(5)>,
+L<KeyFile(5)>,
+L<UserList(5)>,
+L<bos(1)>,
+L<bos_create(1)>,
+L<bos_shutdown(1)>,
+L<bos_status(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
+
+bos uninstall - Reverts to the former version of a process's binary file
+
+=head1 SYNOPSIS
+
+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> 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 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 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 L<bos(1)>.
+
+If the machine is not a binary distribution machine and is running an
+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 B<-file> <I<files to uninstall>>+
+
+Names each binary file to replace with its C<.BAK> version.
+
+=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 F</usr/afs/bin> directory.
+
+=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(1)>.
+
+=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(1)>.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+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(1)>.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+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 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(5)>,
+L<KeyFile(5)>,
+L<UserList(5)>,
+L<bos(1)>,
+L<bos_getrestart(1)>,
+L<bos_restart(1)>,
+L<bos_setrestart(1)>,
+L<upclient(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+cmdebug - Reports the status of a host Cache Manager
+
+=head1 SYNOPSIS
+
+B<cmdebug> B<-servers> <I<machine>> [B<-port> <I<IP port>>]
+ [B<-long>] [B<-refcounts>] [B<-callbacks>] [B<-addrs>] [B<-cache>]
+
+B<cmdebug> B<-s> <I<machine>> [B<-p> <I<IP port>>] [B<-l>] [B<-r>] [B<-c>]
+ [B<-a>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<cmdebug> command displays information about the Cache Manager and
+client cache status on an AFS client machine. By default, it displays all
+locked cache entries, but other information can be requested via various
+options.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-servers> <I<machine>>
+
+Names the client machine for which to display Cache Manager status.
+Provide the machine's IP address in dotted decimal format, its fully
+qualified host name (for example, B<fs1.abc.com>), or the shortest
+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 resolution service (such as the Domain Name Service
+or a local host table) at the time the command is issued.
+
+=item B<-port> <I<IP port>>
+
+Identifies the port on which to contact the Cache Manager. By default,
+the standard port 7001 is used, so this option is very rarely needed.
+
+=item B<-long>
+
+Reports on all lock statuses and all cache entries, rather than only
+locked cache entries. Do not use this option with B<-refcounts>,
+B<-callbacks>, B<-addrs>, or B<-cache>.
+
+=item B<-refcounts>
+
+Reports only those cache entries with non-zero reference counts. Do not
+use this option with B<-long>, B<-callbacks>, B<-addrs>, or B<-cache>.
+
+=item B<-callbacks>
+
+Reports only those cache entries with callbacks. Do not use this option
+with B<-long>, B<-refcounts>, B<-addrs>, or B<-cache>.
+
+=item B<-addrs>
+
+Rather than showing any cache entries, displays the interfaces the Cache
+Manager answers on, including their netmasks and MTUs. This is useful for
+analyzing clients that are multihomed and identifying problems with
+netmasks or MTU settings. Do not use this option with B<-long>,
+B<-refcounts>, B<-callbacks>, or B<-cache>.
+
+=item B<-cache>
+
+Rather than showing any cache entries, displays the cache configuration
+for the client machine. The information displayed is essentially the
+information that can be configured via parameters to B<afsd>. Do not use
+this option with B<-long>, B<-refcounts>, B<-callbacks>, or B<-addrs>.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+Displays all of the locked cache entries on C<client1>:
+
+ % cmdebug client1
+
+Displays the cache configuration for C<client1.abc.com>:
+
+ % cmdebug client1.abc.com -cache
+
+Displays all cache entries for C<client2.abc.com>:
+
+ % cmdebug client2.abc.com -long
+
+=head1 PRIVILEGE REQUIRED
+
+None
+
+=head1 SEE ALSO
+
+L<afsd(8)>
+
+=head1 COPYRIGHT
+
+Copyright 2005 Russ Allbery <rra@stanford.edu>
+
+This documentation is covered by the IBM Public License Version 1.0. This
+man page was written by Russ Allbery for OpenAFS.
--- /dev/null
+=head1 NAME
+
+fs - Introduction to the fs command suite
+
+=head1 DESCRIPTION
+
+The commands in the B<fs> command suite constitute the main administrative
+interface to the Cache Manager on an AFS client machine, which is
+responsible for fetching AFS data from file server machines on behalf of
+applications running on the client machine.
+
+There are several categories of commands in the B<fs> command suite:
+
+=over 4
+
+=item *
+
+Commands to set and report how the Cache Manager interacts with server
+machines: B<fs checkservers>, B<fs getcellstatus>, B<fs getserverprefs>,
+B<fs listcells>, B<fs newcell>, B<fs setcell>, B<fs setserverprefs>, B<fs
+sysname>, and B<fs wscell>.
+
+=item *
+
+Commands to administer access control lists (ACLs): B<fs cleanacl>, B<fs
+copyacl>, B<fs listacl>, and B<fs setacl>.
+
+=item *
+
+Commands to administer server machines, volumes or partitions that house a
+given file or directory: B<fs diskfree>, B<fs examine>, B<fs listquota>,
+B<fs quota>, B<fs setquota>, B<fs setvol>, B<fs whereis>, and B<fs
+whichcell>.
+
+=item *
+
+Commands to administer the local client cache and related information:
+B<fs checkvolumes>, B<fs flush>, B<fs flushvolume>, B<fs getcacheparms>,
+and B<fs setcachesize>.
+
+=item *
+
+Commands to administer volume mount points: B<fs lsmount>, B<fs mkmount>,
+and B<fs rmmount>.
+
+=item *
+
+Commands to control monitoring and tracing: B<fs debug>, and B<fs
+messages>.
+
+=item *
+
+A command to administer the Cache Manager's interaction with other
+file systems: B<fs exportafs>.
+
+=item *
+
+Commands to obtain help: B<fs apropos> and B<fs help>.
+
+=back
+
+The Cache Manager and the fs commands use and maintain the following
+configuration files:
+
+=over 4
+
+=item F</usr/vice/etc/CellServDB>
+
+Lists the database server machines in the local cell and any foreign cell
+to which the administrator wishes to enable AFS access for users working
+on the machine. The database server machines run the Authentication,
+Backup, Protection and Volume Location (VL) Server processes, which
+maintain databases of administrative information. For users to access a
+cell, its C<root.cell> volume must also be mounted in the local cell's AFS
+file tree.
+
+=item F</usr/vice/etc/ThisCell>
+
+Defines the machine's cell membership with respect to the AFS command
+suites and Cache Manager access to AFS data.
+
+=item F</usr/vice/etc/cacheinfo>
+
+Defines configuration parameters for the cache, including its size and
+whether it is in memory or on disk.
+
+=back
+
+In addition, the Cache Manager automatically creates files on the cache
+partition (by default, F</usr/vice/cache> for caching and tracking files
+fetched from file server machines.
+
+For more details, see the reference page for each file.
+
+=head1 OPTIONS
+
+The following flag is available on every command in the fs suite. The
+reference page for each command also lists it, but it is described here in
+greater detail.
+
+=over 4
+
+=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.
+
+=back
+
+=head1 PRIVILEGE REQUIRED
+
+The privileges required for fs commands vary more than for other command
+suites. Pay special attention to the PRIVILEGE REQUIRED section of each
+command description.
+
+The various types of necessary privilege include:
+
+=over 4
+
+=item *
+
+Having permissions on a directory's ACL. For example, creating and
+removing mount points requires C<a> (administer), C<i> (insert), and C<d>
+(delete) permissions on the ACL of the directory in which the mount point
+resides.
+
+=item *
+
+Being logged onto the machine as the local superuser C<root>. This is
+necessary when issuing commands that affect Cache Manager configuration.
+
+=item *
+
+Belonging to the system:administrators group in the Protection Database.
+
+=item *
+
+No privilege. Many B<fs> commands simply list information.
+
+=back
+
+=head1 SEE ALSO
+
+L<afs_cache(5)>,
+L<CellServDB(5)>,
+L<ThisCell(5)>
+L<cacheinfo(5)>,
+L<fs_apropos(1)>,
+L<fs_checkservers(1)>,
+L<fs_checkvolumes(1)>,
+L<fs_cleanacl(1)>,
+L<fs_copyacl(1)>,
+L<fs_diskfree(1)>,
+L<fs_examine(1)>,
+L<fs_exportafs(1)>,
+L<fs_flush(1)>,
+L<fs_flushmount(1)>,
+L<fs_flushvolume(1)>,
+L<fs_getcacheparms(1)>,
+L<fs_getcellstatus(1)>,
+L<fs_getclientaddrs(1)>,
+L<fs_getserverprefs(1)>,
+L<fs_help(1)>,
+L<fs_listacl(1)>,
+L<fs_listcells(1)>,
+L<fs_listquota(1)>,
+L<fs_lsmount(1)>,
+L<fs_messages(1)>,
+L<fs_mkmount(1)>,
+L<fs_newcell(1)>,
+L<fs_quota(1)>,
+L<fs_rmmount(1)>,
+L<fs_setacl(1)>,
+L<fs_setcachesize(1)>,
+L<fs_setcell(1)>,
+L<fs_setclientaddrs(1)>,
+L<fs_setquota(1)>,
+L<fs_setserverprefs(1)>,
+L<fs_setvol(1)>,
+L<fs_storebehind(1)>,
+L<fs_sysname(1)>,
+L<fs_whereis(1)>,
+L<fs_whichcell(1)>,
+L<fs_wscell(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
+
+fs apropos - Displays each help entry containing a keyword string
+
+=head1 SYNOPSIS
+
+B<fs apropos> B<-topic> <I<help string>> [B<-help>]
+
+B<fs ap> B<-t> <I<help string>> [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<fs apropos> command displays the first line of the online help entry
+for any B<fs> 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 B<fs help> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=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 ("") or
+other delimiters.
+
+=item B<-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<fs>
+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 fs commands that include the word C<cache>
+in their names or short online descriptions:
+
+ % fs apropos cache
+ setcachesize: set cache size
+ flush: flush file from cache
+ getcacheparms: get cache usage info
+ monitor: set cache monitor host address
+
+=head1 PRIVILEGE REQUIRED
+
+None
+
+=head1 SEE ALSO
+
+L<fs(1)>,
+L<fs_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
+
+fs checkservers - Displays the status of server machines
+
+=head1 SYNOPSIS
+
+B<fs checkservers> [B<-cell> <I<cell to check>>] [B<-all>] [B<-fast>]
+ [B<-interval> <I<seconds between probes>>] [B<-help>]
+
+B<fs checks> [B<-c> <I<cell to check>>] [B<-a>] [B<-f>]
+ [B<-i> <I<seconds between probes>>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<fs checkservers> command reports whether certain AFS server machines
+are accessible from the local client machine. The machines belong to one
+of two classes, and the Cache Manager maintains a list of them in kernel
+memory:
+
+=over 4
+
+=item *
+
+The database server machines in every cell listed in the local
+F</usr/vice/etc/CellServDB file>, plus any machines added to the memory
+list by the B<fs newcell> command since the last reboot.
+
+=item *
+
+All file server machines the Cache Manager has recently contacted, and
+which it probably needs to contact again soon. In most cases, the Cache
+Manager holds a callback on a file or volume fetched from the machine.
+
+=back
+
+If the Cache Manager is unable to contact the vlserver process on a
+database server machine or the B<fileserver> process on a file server
+machine, it marks the machine as inaccessible. (Actually, if a file server
+machine is multihomed, the Cache Manager attempts to contact all of the
+machine's interfaces, and only marks the machine as down if the
+B<fileserver> fails to reply via any of them.) The Cache Manager then
+periodically (by default, every three minutes) sends a probe to each
+marked machine, to see if it is still inaccessible. If a previously
+inaccessible machine responds, the Cache Manager marks it as accessible
+and no longer sends the periodic probes to it.
+
+The B<fs checkservers> command updates the list of inaccessible machines
+by having the Cache Manager probe a specified set of them:
+
+=over 4
+
+=item *
+
+By default, only machines that are marked inaccessible and belong to the
+local cell (the cell listed in the local F</usr/vice/etc/ThisCell>
+file).
+
+=item *
+
+If the B<-cell> argument is included, only machines that are marked
+inaccessible and belong to the specified cell.
+
+=item *
+
+If the B<-all> flag is included, all machines marked inaccessible.
+
+=back
+
+If the B<-fast> flag is included, the Cache Manager does not probe any
+machines, but instead reports the results of the most recent previous
+probe.
+
+To set the interval between probes rather than produce a list of
+inaccessible machines, use the B<-interval> argument. The non-default
+setting persists until the machine reboots; to preserve it across reboots,
+put the appropriate B<fs checkservers> command in the machine's AFS
+initialization files.
+
+=head1 CAUTIONS
+
+The command can take quite a while to complete, if a number of machines do
+not respond to the Cache Manager's probe. The Cache Manager probes
+machines sequentially and waits a standard timeout period before marking
+the machine as unresponsive, to allow for slow network communication. To
+make the command shell prompt return quickly, put the command in the
+background. It is harmless to interrupt the command by typing Ctrl-C or
+another interrupt signal.
+
+Note that the Cache Manager probes only server machines marked
+inaccessible in its memory list. A server machine's absence from the
+output does not necessarily mean that it is functioning, because it
+possibly is not included in the memory list at all (if, for example, the
+Cache Manager has not contacted it recently). For the same reason, the
+output is likely to vary on different client machines.
+
+Unlike most B<fs> commands, the fs checkservers command does not refer to
+the AFSCELL environment variable.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-cell> <I<cell to check>>
+
+Names each cell in which to probe server machines marked as
+inaccessible. Provide the fully qualified domain name, or a shortened form
+that disambiguates it from the other cells listed in the local
+F</usr/vice/etc/CellServDB> file. Combine this argument with the B<-fast>
+flag if desired, but not with the B<-all> flag. Omit both this argument
+and the B<-all> flag to probe machines in the local cell only.
+
+=item B<-all>
+
+Probes all machines in the Cache Manager's memory list that are marked
+inaccessible. Combine this argument with the B<-fast> flag if desired, but
+not with the B<-cell> argument. Omit both this flag and the B<-cell>
+argument to probe machines in the local cell only.
+
+=item B<-fast>
+
+Displays the Cache Manager's current list of machines that are
+inaccessible, rather than sending new probes. The output can as old as the
+current setting of the probe interval (by default three minutes, and
+maximum ten minutes).
+
+=item B<-interval> <I<seconds between probes>>
+
+Sets or reports the number of seconds between the Cache Manager's probes
+to machines in the memory list that are marked inaccessible:
+
+=over 4
+
+=item *
+
+To set the interval, specify a value from the range between 1 and C<600>
+(10 minutes); the default is C<180> (three minutes). The issuer must be
+logged in as the local superuser C<root>. The altered setting persists
+until again changed with this command, or until the machine reboots, at
+which time the setting returns to the default.
+
+=item *
+
+Provide a value of C<0> (zero) to display the current interval setting. No
+privilege is required. Do not combine this argument with any other.
+
+=back
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+If there are no machines marked as inaccessible, or if all of them now
+respond to the Cache Manager's probe, the output is:
+
+ All servers are running.
+
+Note that this message does not mean that all server machines in each
+relevant cell are running. The output indicates the status of only those
+machines that the Cache Manager probes.
+
+If a machine fails to respond to the probe within the timeout period, the
+output begins with the string
+
+ These servers unavailable due to network or server problems:
+
+and lists the hostname of each machine on its own line. The Cache Manager
+stores machine records by Internet address, so the format of each hostname
+(uppercase or lowercase letters, or an Internet address in dotted decimal
+format) depends on how the local cell's name service translates it at the
+time the command is issued. If a server machine is multihomed, the output
+lists only one of its interfaces (usually, the currently most preferred
+one).
+
+If the B<-interval> argument is provided with a value between C<1> and
+C<600>, there is no output. If the value is C<0>, the output reports the
+probe interval as follows:
+
+ The current down server probe interval is <interval> secs
+
+=head1 EXAMPLES
+
+The following command displays the Cache Manager's current list of
+unresponsive machines in the local cell, rather than probing them
+again. The output indicates that if there were any machines marked
+inaccessible, they all responded to the previous probe.
+
+ % fs checkservers -fast
+ All servers are running.
+
+The following example probes machines in the Cache Manager's memory list
+that belong to the C<stateu.edu> cell:
+
+ % fs checkservers -cell stateu.edu
+ All servers are running.
+
+The following example probes all server machines in the Cache Manager's
+memory list. It reports that two machines did not respond to the probe.
+
+ % fs checkservers -all
+ These servers unavailable due to network or server problems:
+ fs1.abc.com SV3.STATE.EDU.
+
+=head1 PRIVILEGE REQUIRED
+
+To set the probe interval, the issuer must be logged in as the local
+superuser C<root>. Otherwise, no privilege is required.
+
+=head1 SEE ALSO
+
+L<CellServDB(5)>,
+L<ThisCell(5)>,
+L<fs_newcell(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
+
+fs checkvolumes - Forces the Cache Manager to update volume information
+
+=head1 SYNOPSIS
+
+B<fs checkvolumes> [B<-help>]
+
+B<fs checkv> [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<fs checkvolumes> command discards the table of mappings between
+volume names and volume ID numbers that the Cache Manager stores in memory
+and uses when fetching data from volumes. The next time an application
+requests AFS data, the Cache Manager must contact the Volume Location (VL)
+Server for volume location information, and then an appropriate file
+server machine for the actual data.
+
+The Cache Manager updates the table of mappings periodically (by default,
+hourly), but this command is useful if the issuer knows that a volume's
+name has changed, or that new read-only replicas of a volume have been
+released, because issuing it forces the Cache Manager to reference the
+changed volume.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+The following message confirms that the command ran successfully.
+
+ All volumeID/name mappings checked.
+
+=head1 PRIVILEGE REQUIRED
+
+None
+
+=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
+
+fs cleanacl - Remove obsolete entries from an ACL
+
+=head1 SYNOPSIS
+
+B<fs cleanacl> [B<-path> <I<dir/file path>>+] [B<-help>]
+
+B<fs cl> [B<-p> <I<dir/file path>>+] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<fs cleanacl> command removes from the access control list (ACL) of
+each specified directory or file any entry that refers to a user or group
+that no longer has a Protection Database entry. Such an entry appears on
+the ACL as an AFS user ID number (UID) rather than a name, because without
+a Protection Database entry, the File Server cannot translate the UID into
+a name.
+
+Cleaning access control lists in this way not only keeps them from
+becoming crowded with irrelevant information, but also prevents the new
+possessor of a recycled AFS UID from obtaining access intended for the
+former possessor of the AFS UID. (Note that recycling UIDs is not
+recommended in any case.)
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-path> <I<dir/file path>>+
+
+Names each directory for which to clean the ACL (specifying a filename
+cleans its directory's ACL). If this argument is omitted, the current
+working directory's ACL is cleaned.
+
+Specify the read/write path to each directory, to avoid the failure that
+results from attempting to change 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, 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 B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+If there are no obsolete entries on the ACL, the following message
+appears:
+
+ Access list for <path> is fine.
+
+Otherwise, the output reports the resulting state of the ACL, following the
+header
+
+ Access list for <path> is now
+
+At the same time, the following error message appears for each file in the
+cleaned directories:
+
+ fs: '<filename>': Not a directory
+
+=head1 EXAMPLES
+
+The following example illustrates the cleaning of the ACLs on the current
+working directory and two of its subdirectories. Only the second
+subdirectory had obsolete entries on it.
+
+ % fs cleanacl -path . ./reports ./sources
+ Access list for . is fine.
+ Access list for ./reports is fine.
+ Access list for ./sources is now
+ Normal rights:
+ system:authuser rl
+ pat rlidwka
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must have the C<a> (administer) permission on each directory's
+ACL (or the ACL of each file's parent directory); the directory's owner
+and the members of the system:administrators group have the right
+implicitly, even if it does not appear on the ACL.
+
+=head1 SEE ALSO
+
+L<fs_listacl(1)>,
+L<fs_mkmount(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
+
+fs copyacl - Copies an ACL from a directory to one or more other directories
+
+=head1 SYNOPSIS
+
+B<fs copyacl> B<-fromdir> <I<source directory (or DFS file)>>
+ B<-todir> <I<destination directory (or DFS file)>>+
+ [B<-clear>] [B<-id>] [B<-if>] [-help]
+
+B<fs co> B<-f> <I<source directory (or DFS file)>>
+ B<-t> <I<destination directory (or DFS file)>>+
+ [B<-c>] [B<-id>] [B<-if>] [-h]
+
+=head1 DESCRIPTION
+
+The fs copyacl command copies the access control list (ACL) from a source
+directory to each specified destination directory. The source directory's
+ACL is unchanged, and changes to the destination directory's ACL obey the
+following rules:
+
+=over 4
+
+=item *
+
+If an entry on the source ACL does not already exist on the destination
+ACL, it is added.
+
+=item *
+
+If an entry exists on both the source and destination ACLs, the
+permissions from the source ACL entry replace the current permissions on
+the destination ACL entry.
+
+=item *
+
+If an entry on the destination ACL has no corresponding entry on the
+source ACL, it is removed if the B<-clear> flag is included and is
+unchanged otherwise. In other words, if the B<-clear> flag is provided,
+the source ACL completely replaces the destination ACL.
+
+=back
+
+When using this command to copy ACLs between objects in DFS filespace
+accessed via the AFS/DFS Migration Toolkit Protocol Translator, it is
+possible to specify files, as well as directories, with the B<-fromdir>
+and B<-todir> arguments. For more information on copying ACLs between DFS
+directories and files, refer to the I<IBM AFS/DFS Migration Toolkit
+Administration Guide and Reference>.
+
+=head1 CAUTIONS
+
+Do not copy ACLs between AFS and DFS files or directories. The ACL formats
+are incompatible.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-fromdir> <I<source directory>>
+
+Specifies the source directory from which to copy the ACL. (Specifying an
+AFS file copies its directory's ACL, but specifying a DFS file copies its
+own ACL.) A partial pathname is interpreted relative to the current
+working directory.
+
+=item B<-todir> <I<destination directory>>
+
+Specifies each directory for which to alter the ACL to match the source
+ACL. (Specifying an AFS file halts the command with an error, but
+specifying a DFS file alters the file's ACL). A partial pathname is
+interpreted relative to the current working directory.
+
+Specify the read/write path to each directory (or DFS file), to avoid the
+failure that results from attempting to change 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,
+C</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 B<-clear>
+
+Replaces the ACL of each destination directory with the source ACL.
+
+=item B<-id>
+
+Modifies the Initial Container ACL of each DFS directory named by the
+B<-todir> argument, rather than the regular Object ACL. This argument is
+supported only when both the source and each destination directory reside
+in DFS and are accessed via the AFS/DFS Migration Toolkit Protocol
+Translator.
+
+=item B<-if>
+
+Modifies the Initial Object ACL of each DFS directory named by the
+B<-todir> argument, rather than the regular Object ACL. This argument is
+supported only when both the source and each destination directory reside
+in DFS and are accessed via the AFS/DFS Migration Toolkit Protocol
+Translator.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following example command copies the current working directory's ACL
+to its subdirectory called F<reports>. Note that the source directory's
+ACL is unaffected. Entries on the F<reports> directory's that are not on
+the source ACL of the current directory remain unaffected as well, because
+the B<-clear> flag is not used.
+
+ % fs listacl . reports
+ Access list for . is
+ Normal rights:
+ pat rlidwka
+ smith rlidwk
+ Access list for reports is
+ Normal rights:
+ pat rl
+ pat:friends rl
+ Negative rights
+ jones rlidwka
+
+ % fs copyacl -fromdir . -todir reports
+
+ % fs listacl . reports
+ Access list for . is
+ Normal rights:
+ pat rlidwka
+ smith rlidwk
+ Access list for reports is
+ Normal rights:
+ pat rlidwka
+ pat:friends rl
+ smith rlidwk
+ Negative rights
+ jones rlidwka
+
+=head1 PRIVILEGE REQUIRED
+
+To copy an ACL between AFS objects, the issuer must have the C<l> (lookup)
+permission on the source directory's ACL and the C<a> (administer)
+permission on each destination directory's ACL. If the B<-fromdir>
+argument names a file rather than a directory, the issuer must have both
+the C<l> and C<r> (read) permissions on the ACL of the file's directory.
+
+To copy an ACL between DFS objects, the issuer must have the r permission
+on the source directory or file's ACL and the C<c> (control) permission on
+each destination directory or file's ACL.
+
+=head1 SEE ALSO
+
+L<fs_listacl(1)>,
+L<fs_mkmount(1)>,
+L<fs_setacl(1)>
+
+I<IBM AFS/DFS Migration Toolkit Administration Guide and Reference>
+
+=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
+
+fs diskfree - Shows data about the partition housing a directory or file
+
+=head1 SYNOPSIS
+
+B<fs diskfree> [B<-path> <I<dir/file path>>+] [B<-help>]
+
+B<fs df> [B<-p> <I<dir/file path>>+] [B<-h>]
+
+B<fs di> [B<-p> <I<dir/file path>>+] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<fs diskfree> command formats and displays information about the
+partition that houses the volume containing the specified directory or
+file, including its size and how much space is currently used.
+
+To display information about the volume itself, use the B<fs examine>
+command. The B<fs examine> and B<fs quota> commands also display
+information about a volume.
+
+=head1 CAUTIONS
+
+The partition-related statistics in this command's output do not always
+agree with the corresponding values in the output of the standard UNIX
+B<df> command. The statistics reported by this command can be up to five
+minutes old, because the Cache Manager polls the File Server for partition
+information at that frequency. Also, on some operating systems, the B<df>
+command's report of partition size includes reserved space not included in
+this command's calculation, and so is likely to be about 10% larger.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-path> <I<dir/file path>>+
+
+Names a file or directory that resides on the partition about which to
+produce output. Partial pathnames are interpreted relative to the current
+working directory, which is also the default value if this argument is
+omitted.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+The output reports the following information about the volume and
+partition that houses each file or directory:
+
+=over 4
+
+=item Volume Name
+
+The name of the volume.
+
+=item kbytes
+
+The partition's total size in kilobytes.
+
+=item used
+
+The number of kilobytes used on the partition.
+
+=item avail
+
+The number of kilobytes available on the partition.
+
+=item %used
+
+The percentage of the partition's total space that is used (the C<used>
+statistic divided by the C<kbytes> statistic, times 100).
+
+=back
+
+If the C<%used> statistic is greater than 90%, it is marked with the
+string C<<< <<WARNING >>> at the right margin.
+
+If the volume is a read-only volume, the output includes information about
+only one of the partitions that houses it, generally the one on the file
+server machine with the lowest preference rank. To verify which machine
+the output is referring to, use the B<vos listvldb> command to list the
+volume's locations, and the B<vos partinfo> command to display the size of
+each one.
+
+=head1 EXAMPLES
+
+The following example shows the output for the partitions housing the
+volumes C<user.smith> and C<sun4x_56.bin>:
+
+ % fs diskfree -path /afs/abc.com/usr/smith /afs/abc.com/sun4x_56/bin
+ Volume Name kbytes used avail %used
+ user.smith 4177920 3841258 336662 92% <<WARNING
+ sun4x_56.bin 4423680 3174500 1249180 72%
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must have the C<l> (lookup) permission on the ACL of the root
+directory of the volume that houses the file or directory named by the
+B<-path> argument, and on the ACL of each directory that precedes it in
+the pathname.
+
+=head1 SEE ALSO
+
+L<fs_examine(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
+
+fs examine - Shows data about the volume containing a directory or file
+
+=head1 SYNOPSIS
+
+B<fs examine> [B<-path> <I<dir/file path>>+] [B<-help>]
+
+B<fs exa> [B<-p> <I<dir/file path>>+] [B<-h>]
+
+B<fs listvol> [B<-p> <I<dir/file path>>+] [B<-h>]
+
+B<fs listv> [B<-p> <I<dir/file path>>+] [B<-h>]
+
+B<fs lv> [B<-p> <I<dir/file path>>+] [B<-h>]
+
+=head1 DESCRIPTION
+
+The fs examine command displays information about the volume containing
+each specified directory or file, including its volume ID number, quota
+and the percentage of its quota that is used.
+
+This command provides the most information about a volume, but the B<fs
+listquota> command displays similar information in tabular format, and the
+B<fs quota> command reports only the percentage of quota used.
+
+To set volume quota, use the B<fs setquota> or B<fs setvol> command.
+
+=head1 CAUTIONS
+
+The partition-related statistics in this command's output do not always
+agree with the corresponding values in the output of the standard UNIX
+B<df> command. The statistics reported by this command can be up to five
+minutes old, because the Cache Manager polls the File Server for partition
+information at that frequency. Also, on some operating systems, the B<df>
+command's report of partition size includes reserved space not included in
+this command's calculation, and so is likely to be about 10% larger.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-path> <I<dir/file path>>+
+
+Names a file or directory that resides in the volume about which to
+produce output. Partial pathnames are interpreted relative to the current
+working directory, which is also the default value if this argument is
+omitted.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+The output displays information about the volume that houses each
+specified directory or file, in the following format
+
+ Volume status for vid = I<volume ID> named I<volume name>
+ Current offline message is I<message>
+ Current disk quota is I<quota in kilobytes>
+ Current blocks used are I<volume size in kilobytes>
+ The partition has I<available partition> blocks available out of
+ I<partition size>
+
+where the first line specifies the volume's ID number and name. The
+C<Current offline message> line appears only if an administrator has
+included the B<-offlinemsg> argument to the B<fs setvol> command. The
+remaining lines report, respectively,
+
+=over 4
+
+=item *
+
+The volume's quota in kilobytes, or the string C<unlimited> to indicate an
+unlimited quota.
+
+=item *
+
+The volume's current size in kilobytes.
+
+=item *
+
+The number of blocks available and total size of the host partition, both
+in kilobytes.
+
+=back
+
+=head1 EXAMPLES
+
+The following example shows the output for the volume C<user.smith> and
+the partition housing it:
+
+ % fs examine -path /afs/abc.com/usr/smith
+ Volume status for vid = 50489902 named user.smith
+ Current maximum quota is 15000
+ Current blocks used are 5073
+ The partition has 336662 blocks available out of 4177920
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must have the C<l> (lookup) permission on the ACL of the root
+directory of the volume that houses the file or directory named by the
+B<-path> argument, and on the ACL of each directory that precedes it in
+the pathname.
+
+=head1 SEE ALSO
+
+L<fs_listquota(1)>,
+L<fs_quota(1)>,
+L<fs_setquota(1)>,
+L<fs_setvol(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
+
+fs exportafs - Configures export of AFS to clients of other file systems
+
+=head1 SYNOPSIS
+
+B<fs exportafs> B<-type> <I<exporter name>>
+ [B<-start> <I<start/stop translator (on | off)>>]
+ [B<-convert> <I<convert from afs to unix mode (on | off)>>]
+ [B<-uidcheck> <I<run on strict 'uid check' mode (on | off)>>]
+ [B<-submounts> <I<allow nfs mounts to subdirs of /afs/.. (on | off)>>]
+ [B<-help>]
+
+B<fs exp> B<-t> <I<exporter name>>
+ [B<-st> <I<start/stop translator (on | off)>>]
+ [B<-c> <I<convert from afs to unix mode (on | off)>>]
+ [B<-u> <I<run on strict 'uid check' mode (on | off)>>]
+ [B<-su> <I<allow nfs mounts to subdirs of /afs/.. (on | off)>>]
+ [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<fs exportafs> command sets (if the B<-start> argument is provided)
+or reports (if it is omitted) whether the machine can reexport the AFS
+filespace to clients of a non-AFS file system. To control certain features
+of the translation protocol, use the following arguments:
+
+=over 4
+
+=item *
+
+To control whether the UNIX group and other mode bits on an AFS file or
+directory are set to match the owner mode bits when it is exported to the
+non-AFS file system, use the B<-convert> argument.
+
+=item *
+
+To control whether tokens can be placed in a credential structure
+identified by a UID that differs from the local UID of the entity that is
+placing the tokens in the structure, use the B<-uidcheck> argument. The
+most common use is to control whether issuers of the B<knfs> command can
+specify a value for its B<-id> argument that does not match their local
+UID on the NFS/AFS translator machine.
+
+=item *
+
+To control whether users can create mounts in the non-AFS filespace to an
+AFS directory other than F</afs>, use the B<-submounts> argument.
+
+=back
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-type> <I<exporter name>>
+
+Names the alternate file system to which to reexport the AFS
+filespace. The only acceptable value is C<nfs>, in lowercase letters only.
+
+=item B<-start> on
+=item B<-start> off
+
+Enables the local machine to reexport the AFS filespace if the value is
+C<on>, or disables it if the value is C<off>. Omit this argument to report
+the current setting for all of the configurable parameters.
+
+=item B<-convert> on
+=item B<-convert> off
+
+Controls the setting of the UNIX group and other mode bits on AFS files
+and directories exported to the non-AFS file system. If the value is
+C<on>, they are set to match the B<owner> mode bits. If the value is
+C<off>, the bits are not changed. If this argument is omitted, the default
+value is C<on>.
+
+=item B<-uidcheck> on
+=item B<-uidcheck> off
+
+Controls whether tokens can be placed in a credential structure identified
+by a UID that differs from the local UID of the entity that is placing the
+tokens in the structure.
+
+=over 4
+
+=item *
+
+If the value is on, the UID that identifies the credential structure must
+match the local UID.
+
+With respect to the B<knfs> command, this value means that the value of
+B<-id> argument must match the issuer's local UID on the translator
+machine. In practice, this setting makes it pointless to include the
+B<-id> argument to the B<knfs> command, because the only acceptable value
+(the issuer's local UID) is already used when the B<-id> argument is
+omitted.
+
+Enabling UID checking also makes it impossible to issue the B<klog> and
+B<pagsh> commands on a client machine of the non-AFS file system even
+though it is a system type supported by AFS. For an explanation, see
+L<klog(1)>.
+
+=item *
+
+If the value is off (the default), tokens can be assigned to a local UID
+in the non-AFS file system that does not match the local UID of the entity
+assigning the tokens.
+
+With respect to the B<knfs> command, it means that the issuer can use the
+B<-id> argument to assign tokens to a local UID on the NFS client machine
+that does not match his or her local UID on the translator machine. (An
+example is assigning tokens to the MFS client machine's local superuser
+C<root>.) This setting allows more than one issuer of the B<knfs> command
+to make tokens available to the same user on the NFS client machine. Each
+time a different user issues the B<knfs> command with the same value for
+the B<-id> argument, that user's tokens overwrite the existing ones. This
+can result in unpredictable access for the user on the NFS client machine.
+
+=back
+
+=item B<-submounts> on
+=item B<-submounts> off
+
+Controls whether a user of the non-AFS filesystem can mount any directory
+in the AFS filespace other than the top-level F</afs> directory. If the
+value is C<on>, such submounts are allowed. If the value is C<off>, only
+mounts of the F</afs> directory are allowed. If this argument is omitted,
+the default value is C<off>.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+If the machine is not even configured as a server of the non-AFS file
+system, the following message appears:
+
+ Sorry, the <file_system>-exporter type is currently not supported on
+ this AFS client
+
+If the machine is configured as a server of the non-AFS file system but is
+not currently enabled to reexport AFS to it (because the B<-start>
+argument to this command is not set to C<on>), the message is as follows:
+
+ '<file_system>' translator is disabled
+
+If the machine is enabled to reexport AFS, the following message precedes
+messages that report the settings of the other parameters.
+
+ '<file_system>' translator is enabled with the following options:
+
+The following messages indicate that the B<-convert> argument is set to
+C<on> or C<off> respectively:
+
+ Running in convert owner mode bits to world/other mode
+ Running in strict unix mode
+
+The following messages indicate that the B<-uidcheck> argument is set to
+C<on> or C<off> respectively:
+
+ Running in strict 'passwd sync' mode
+ Running in no 'passwd sync' mode
+
+The following messages indicate that the B<-submounts> argument is set to
+C<on> or C<off> respectively:
+
+ Allow mounts of /afs/.. subdirs
+ Only mounts to /afs allowed
+
+=head1 EXAMPLES
+
+The following example shows that the local machine can export AFS to NFS
+client machines.
+
+ % fs exportafs nfs
+ 'nfs' translator is enabled with the following options:
+ Running in convert owner mode bits to world/other mode
+ Running in no 'passwd sync' mode
+ Only mounts to /afs allowed
+
+The following example enables the machine as an NFS server and converts
+the UNIX group and other mode bits on exported AFS directories and files
+to match the UNIX owner mode bits.
+
+ % fs exportafs -type nfs -start on -convert on
+
+The following example disables the machine from reexporting AFS to NFS
+client machines:
+
+ % fs exportafs -type nfs -start off
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be logged in as the local superuser root.
+
+=head1 SEE ALSO
+
+L<klog(1)>,
+L<knfs(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
+
+fs flush - Forces the Cache Manager to discard a cached file or directory
+
+=head1 SYNOPSIS
+
+B<fs flush> [B<-path> <I<dir/file path>>+] [B<-help>]
+
+B<fs flush> [B<-p> <I<dir/file path>>+] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<fs flush> command removes from the cache all data and status
+information associated with each specified file or directory. The next
+time an application requests data from the flushed directory or file, the
+Cache Manager fetches the most current version from a File Server, along
+with a new callback (if necessary) and associated status information. This
+command has no effect on two types of data:
+
+=over 4
+
+=item *
+
+Data in application program buffers.
+
+=item *
+
+Data that has been changed locally and written to the cache but not yet
+written to the copy on the file server machine.
+
+=back
+
+To flush all data in the cache that was fetched from the same volume as a
+specified file or directory, use the B<fs flushvolume> command. To flush
+a corrupted mount point, use the B<fs flushmount> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-path> <I<dir/file path>>+
+
+Names each file or directory to flush from the cache. If it is a
+directory, only the directory element itself is flushed, not data cached
+from files or subdirectories that reside in it. Partial pathnames are
+interpreted relative to the current working directory, which is also the
+default value if this argument is omitted.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command flushes from the cache the file C<projectnotes> in
+the current working directory and all data from the subdirectory C<plans>:
+
+ % fs flush -path projectnotes ./plans/*
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must have the C<l> (lookup) permission on the ACL of the root
+directory of the volume that houses the file or directory named by the
+B<-path> argument, and on the ACL of each directory that precedes it in
+the pathname.
+
+=head1 SEE ALSO
+
+L<fs_flushmount(1)>,
+L<fs_flushvolume(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
+
+fs flushmount - Forces the Cache Manager to discard a mount point
+
+=head1 SYNOPSIS
+
+B<fs flushmount> [B<-path> <I<dir/file path>>+] [B<-help>]
+
+B<fs flushm> [B<-p> <I<dir/file path>>+] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<fs flushmount> command removes from the cache all information
+associated with each mount point named by the B<-path> argument. The next
+time an application accesses the mount point, the Cache Manager fetches
+the most current version of it from the File Server. Data cached from the
+associated volume is not affected.
+
+The command's intended use is to discard information about mount points
+that has become corrupted in the cache. (The Cache Manager periodically
+refreshes cached mount points, but the only other way to discard them
+immediately is to reinitialize the Cache Manager by rebooting the
+machine.) Symptoms of a corrupted mount point included garbled output from
+the B<fs lsmount> command, and failed attempts to change directory to or
+list the contents of a mount point.
+
+To flush cached data rather than a mount point, use the B<fs flush> or
+B<fs flushvolume> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-path> <I<dir/file path>>+
+
+Names each mount point to flush from the cache. Partial pathnames are
+interpreted relative to the current working directory, which is also the
+default value if this argument is omitted.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command flushes from the cache the mount point for user
+C<pat>'s home directory:
+
+ % fs flushm /afs/abc.com/usr/pat
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must have the C<l> (lookup) permission on the ACL of the root
+directory of the volume that houses the file or directory named by the
+B<-path> argument, and on the ACL of each directory that precedes it in
+the pathname.
+
+=head1 SEE ALSO
+
+L<fs_flush(1)>,
+L<fs_flushvolume(1)>,
+L<fs_lsmount(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
+
+fs flushvolume - Forces the Cache Manager to discard cached data from a volume
+
+=head1 SYNOPSIS
+
+B<fs flushvolume> [B<-path> <I<dir/file path>>+] [B<-help>]
+
+B<fs flushv> [B<-p> <I<dir/file path>>+] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<fs flushvolume> command removes from the cache all data that was
+fetched from the same volume as each specified directory or file. It does
+not discard cached status information. The next time an application
+requests data from a flushed directory or file, the Cache Manager fetches
+the most current version from a File Server, along with a new callback (if
+necessary) and associated status information. This command has no effect
+on two types of data:
+
+=over 4
+
+=item *
+
+Data in application program buffers.
+
+=item *
+
+Data that has been changed locally and written to the cache but not yet
+written to the copy on the file server machine.
+
+=back
+
+To discard the data and status information associated with individual
+files and directories, use the B<fs flush> command. To flush a corrupted
+mount point, use the B<fs flushmount> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-path> <I<dir/file path>>+
+
+Names a file or directory from each volume for which to discard all cached
+data. Partial pathnames are interpreted relative to the current working
+directory, which is also the default value if this argument is omitted.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command flushes from the cache all data fetched from the
+volume that contains the current working directory:
+
+ % fs flushvolume
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must have the C<l> (lookup) permission on the ACL of the root
+directory of the volume that houses the file or directory named by the
+B<-path> argument, and on the ACL of each directory that precedes it in
+the pathname.
+
+=head1 SEE ALSO
+
+L<fs_flush(1)>,
+L<fs_flushmount(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
+
+fs getcacheparms - Displays the current size and usage of the cache
+
+=head1 SYNOPSIS
+
+B<fs getcacheparms> [B<-help>]
+
+B<fs getca> [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<fs getcacheparms> command displays the current size of the cache
+(which can be in memory or on disk), and the amount currently in use.
+
+The reported statistics are from kernel memory, so the reported size can
+differ from the setting specified in the F</usr/vice/etc/cacheinfo> file
+on a machine using a disk cache, if the B<fs setcachesize> command has
+been used to alter cache size.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+The output reports
+
+ AFS using <amount> of the cache's available <size> 1K byte blocks.
+
+where <amount> is the number of kilobyte blocks currently used to cache
+data and status information, and <size> is the total current cache size.
+
+=head1 EXAMPLES
+
+The following example shows the output on a machine with a 25000 kilobyte
+cache.
+
+ % fs getcacheparms
+ AFS using 22876 of the cache's available 25000 1K byte blocks.
+
+=head1 PRIVILEGE REQUIRED
+
+None
+
+=head1 SEE ALSO
+
+L<fs_setcachesize(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
+
+fs getcellstatus - Reports whether setuid programs are honored in a cell
+
+=head1 SYNOPSIS
+
+B<fs getcellstatus> B<-cell> <I<cell name>>+ [B<-help>]
+
+B<fs getce> B<-c> <I<cell name>>+ [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<fs getcellstatus> command reports whether the Cache Manager allows
+programs fetched from each specified cell to run with setuid
+permission. To set a cell's setuid status, use the B<fs setcell> command;
+L<fs_setcell(1)> fully describes how AFS treats setuid programs.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-cell> <I<cell name>>+
+
+Names each cell for which to report setuid status. Provide the fully
+qualified domain name, or a shortened form that disambiguates it from the
+other cells listed in the local F</usr/vice/etc/CellServDB> file.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+The output reports one of the following two values as appropriate:
+
+ Cell <cell> status: setuid allowed
+ Cell <cell> status: no setuid allowed
+
+=head1 EXAMPLES
+
+The following example indicates that programs from the cell C<abc.com> are
+not allowed to run with setuid permission.
+
+ % fs getcellstatus abc.com
+ Cell abc.com status: no setuid allowed
+
+=head1 PRIVILEGE REQUIRED
+
+None
+
+=head1 SEE ALSO
+
+L<CellServDB(5)>,
+L<fs_setcell(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
+
+fs getclientaddrs - Displays the client interfaces to register
+
+=head1 SYNOPSIS
+
+B<fs getclientaddrs> [B<-help>]
+
+B<fs gc> [B<-h>]
+
+B<fs getcl> [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<fs getclientaddrs> command displays the IP addresses of the
+interfaces that the local Cache Manager registers with a File Server when
+first establishing a connection to it.
+
+The File Server uses the addresses when it initiates a remote procedure
+call (RPC) to the Cache Manager (as opposed to responding to an RPC sent
+by the Cache Manager). There are two common circumstances in which the
+File Server initiates RPCs: when it breaks callbacks and when it pings the
+client machine to verify that the Cache Manager is still accessible.
+
+If an RPC to that interface fails, the File Server simultaneously sends
+RPCs to all of the other interfaces in the list, to learn which of them
+are still available. Whichever interface replies first is the one to which
+the File Server then sends pings and RPCs to break callbacks.
+
+L<fs_setclientaddrs(1)> explains how the Cache Manager constructs the list
+automatically in kernel memory as it initializes, and how to use that
+command to alter the kernel list after initialization.
+
+=head1 CAUTIONS
+
+The File Server uses the list of interfaces displayed by this command only
+when selecting an alternative interface after a failed attempt to break a
+callback or ping the Cache Manager. When responding to the Cache Manager's
+request for file system data, the File Server replies to the interface
+which the Cache Manager used when sending the request. If the File
+Server's reply to a data request fails, the file server machine's network
+routing configuration determines which alternate network routes to the
+client machine are available for resending the reply.
+
+The displayed list applies to all File Servers to which the Cache Manager
+connects in the future. It is not practical to register different sets of
+addresses with different File Servers, because it requires using the B<fs
+setclientaddrs> command to change the list and then rebooting each
+relevant File Server immediately.
+
+The displayed list is not necessarily governing the behavior of a given
+File Server, if an administrator has issued the B<fs setclientaddrs>
+command since the Cache Manager first contacted that File Server. It
+determines only which addresses the Cache Manager registers when
+connecting to File Servers in the future.
+
+The list of interfaces does not influence the Cache Manager's choice of
+interface when establishing a connection to a File Server.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+The output displays the IP address of each interface that the Cache
+Manager is currently registering with File Server processes that it
+contacts, with one address per line. The File Server initially uses the
+first address for breaking callbacks and pinging the Cache Manager, but
+the ordering of the other interfaces is not meaningful.
+
+=head1 EXAMPLES
+
+The following example displays the two interfaces that the Cache Manager
+is registering with File Servers.
+
+ % fs getclientaddrs
+ 192.12.105.68
+ 192.12.108.84
+
+=head1 PRIVILEGE REQUIRED
+
+None
+
+=head1 SEE ALSO
+
+L<fileserver(1)>,
+L<fs_setclientaddrs(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
+
+fs getserverprefs - Displays preference ranks for file servers or VL servers
+
+=head1 SYNOPSIS
+
+B<fs getserverprefs> [B<-file> <I<output to named file>>]
+ [B<-numeric>] [B<-vlservers>] [B<-help>]
+
+B<fs gets> [B<-f> <I<output to named file>>] [B<-n>] [B<-v>] [B<-h>]
+
+B<fs gp> [B<-f> <I<output to named file>>] [B<-n>] [B<-v>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<fs getserverprefs> command displays preference ranks for file server
+machine interfaces (file server machines run the B<fs> process) or, if the
+B<-vlserver> flag is provided, for Volume Location (VL) Server machines
+(which run the B<vlserver> process). For file server machines, the Cache
+Manager tracks up to 15 interfaces per machine and assigns a separate rank
+to each interface. The ranks indicate the order in which the local Cache
+Manager attempts to contact the interfaces of machines that are housing a
+volume when it needs to fetch data from the volume. For VL Server
+machines, the ranks indicate the order in which the Cache Manager attempts
+to contact a cell's VL Servers when requesting VLDB information. For both
+types of rank, lower integer values are more preferred.
+
+The Cache Manager stores ranks in kernel memory. Once set, a rank persists
+until the machine reboots, or until the B<fs setserverprefs> command is
+used to change it. The reference page for the B<fs setserverprefs> command
+explains how the Cache Manager sets default ranks, and how to use that
+command to change the default values.
+
+Default VL Server ranks range from 10,000 to 10,126, and the Cache Manager
+assigns them to every machine listed in its copy of the
+F</usr/vice/etc/CellServDB> file. When the Cache Manager needs to fetch
+VLDB information from a cell, it compares the ranks for the VL Server
+machines belonging to that cell, and attempts to contact the VL Server
+with the lowest integer rank. If the Cache Manager cannot reach the VL
+Server (because of server process, machine or network outage), it tries to
+contact the VL Server with the next lowest integer rank, and so on. If all
+of a cell's VL Server machines are unavailable, the Cache Manager cannot
+fetch data from the cell.
+
+Default file server ranks range from 5,000 to 40,000, excluding the range
+used for VL Servers (10,000 to 10,126); the maximum possible rank is
+65,534. When the Cache Manager needs to fetch data from a volume, it
+compares the ranks for the interfaces of machines that house the volume,
+and attempts to contact the interface that has the lowest integer rank. If
+it cannot reach the B<fileserver> process via that interface (because of
+server process, machine or network outage), it tries to contact the
+interface with the next lowest integer rank, and so on. If it cannot reach
+any of the interfaces for machines that house the volume, it cannot fetch
+data from the volume.
+
+For both file server machines and VL Server machines, it is possible for a
+machine or interface in a foreign cell to have the same rank as a machine
+or interface in the local cell. This does not present a problem, because
+the Cache Manager only ever compares ranks for machines belonging to one
+cell at a time.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-file> <I<output file>>
+
+Specifies the full pathname of a file to which to write the preference
+ranks. If the specified file already exists, the command overwrites its
+contents. If the pathname is invalid, the command fails. If this argument
+is not provided, the preference ranks appear on the standard output
+stream.
+
+=item B<-numeric>
+
+Displays the IP addresses of file server machine interfaces or VL Server
+machines, rather than their hostnames. If this argument is not provided,
+the B<fs> command interpreter has the IP addresses translated to hostnames
+such as C<fs1.abc.com>.
+
+=item B<-vlservers>
+
+Displays preference ranks for VL Server machines rather than file server
+machine interfaces.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+The output consists of a separate line for each file server machine
+interface or VL Server machine, pairing the machine's hostname or IP
+address with its rank. The Cache Manager stores IP addresses in its kernel
+list of ranks, but the command by default identifies interfaces by
+hostname, by calling a translation routine that refers to either the
+cell's name service (such as the Domain Name Server) or the local host
+table. If an IP address appears in the output, it is because the
+translation attempt failed. To bypass the translation step and display IP
+addresses rather than hostnames, include the B<-numeric> flag. This can
+significantly speed the production of output.
+
+By default, the command writes to the standard output stream. Use the
+B<-file> argument to write the output to a file instead.
+
+=head1 EXAMPLES
+
+The following example displays the local Cache Manager's preference ranks
+for file server machines. The local machine belongs to the AFS cell named
+B<abc.com>, and in this example the ranks of file server machines in its
+local cell are lower than the ranks of file server machines from the
+foreign cell, C<def.com>. It is not possible to translate the IP addresses
+of two machines on the 138.255 network.
+
+ % fs getserverprefs
+ fs2.abc.com 20007
+ fs3.abc.com 30002
+ fs1.abc.com 20011
+ fs4.abc.com 30010
+ server1.def.com 40002
+ 138.255.33.34 40000
+ server6.def.com 40012
+ 138.255.33.37 40005
+
+The following example shows hows the output displays IP addresses when the
+B<-numeric> flag is included, and illustrates how network proximity
+determines default ranks (as described on the B<fs setserverprefs>
+reference page). The local machine has IP address 192.12.107.210, and the
+two file server machines on its subnetwork have ranks of 20,007 and
+20,011. The two file server machines on a different subnetwork of the
+local machine's network have higher ranks, 30,002 and 30,010, whereas the
+ranks of the remaining machines range from 40,000 to 40,012 because they
+are in a completely different network.
+
+ % fs getserverprefs -numeric
+ 192.12.107.214 20007
+ 192.12.105.99 30002
+ 192.12.107.212 20011
+ 192.12.105.100 30010
+ 138.255.33.41 40002
+ 138.255.33.34 40000
+ 138.255.33.36 40012
+ 138.255.33.37 40005
+
+The example shows how the B<-vlservers> flag displays preference ranks for
+VL Server machines:
+
+ % fs getserverprefs -vlservers
+ fs2.abc.com 10052
+ fs3.abc.com 10113
+ fs1.abc.com 10005
+
+=head1 PRIVILEGE REQUIRED
+
+None
+
+=head1 SEE ALSO
+
+L<fs_setserverprefs(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
+
+fs help - Displays help for fs commands
+
+=head1 SYNOPSIS
+
+B<fs help> [B<-topic> <I<help string>>+] [B<-help>]
+
+B<fs h> [B<-t> <I<help string>>+] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<fs 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<fs> command.
+
+To display every B<fs> command whose name or short description includes a
+specified keyword, use the B<fs apropos> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-topic> <I<help string>>+
+
+Indicates each command for which to display the complete online help
+entry. Omit the B<fs> part of the command name, providing only the
+operation code (for example, specify C<setacl>, not C<fs setacl>). If this
+argument is omitted, the output briefly describes every B<fs> command.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+The online help entry for each fs 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 B<fs setacl>
+command:
+
+ % fs help setacl
+ fs setacl: set access control list
+ aliases: sa
+ Usage: fs setacl -dir <directory>+
+ -acl <access list entries>+ [-clear] [-negative] [-help]
+
+=head1 PRIVILEGE REQUIRED
+
+None
+
+=head1 SEE ALSO
+
+L<fs(1)>,
+L<fs_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
+
+fs listacl - Displays ACLs
+
+=head1 SYNOPSIS
+
+B<fs listacl> [B<-path> <I<dir/file path>>+] [B<-id>] [B<-if>] [B<-help>]
+
+B<fs la> [B<-p> <I<dir/file path>>+] [B<-id>] [B<-if>] [B<-h>]
+
+B<fs lista> [B<-p> <I<dir/file path>>+] [B<-id>] [B<-if>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<fs listacl> command displays the access control list (ACL)
+associated with each specified file, directory, or symbolic link. The
+specified element can reside in the DFS filespace if the issuer is using
+the AFS/DFS Migration Toolkit Protocol Translator to access DFS data (and
+DFS does implement per-file ACLs). To display the ACL of the current
+working directory, omit the B<-path> argument.
+
+To alter an ACL, use the fs setacl command. To copy an ACL from one
+directory to another, use the B<fs copyacl> command. To remove obsolete
+entries from an ACL, use the B<fs cleanacl> command.
+
+=head1 CAUTIONS
+
+Placing a user or group on the C<Negative rights> section of the ACL does
+not guarantee denial of permissions, if the C<Normal rights> section
+grants the permissions to members of the system:anyuser group. In that
+case, the user needs only to issue the B<unlog> command to obtain the
+permissions granted to the system:anyuser group.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-path> <I<dir/file path>>+
+
+Names each directory or file for which to display the ACL. For AFS files,
+the output displays the ACL from the file's parent directory; DFS files do
+have their own ACL. Incomplete pathnames are interpreted relative to the
+current working directory, which is also the default value if this
+argument is omitted.
+
+=item B<-id>
+
+Displays the Initial Container ACL of each DFS directory. This argument is
+supported only on DFS directories accessed via the AFS/DFS Migration
+Toolkit Protocol Translator.
+
+=item B<-if>
+
+Displays the Initial Object ACL of each DFS directory. This argument is
+supported only on DFS directories accessed via the AFS/DFS Migration
+Toolkit Protocol Translator.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+The first line of the output for each file, directory, or symbolic link
+reads as follows:
+
+ Access list for <directory> is
+
+If the issuer used shorthand notation in the pathname, such as the period
+(C<.>) to represent the current current directory, that notation sometimes
+appears instead of the full pathname of the directory.
+
+Next, the C<Normal rights> header precedes a list of users and groups who
+are granted the indicated permissions, with one pairing of user or group
+and permissions on each line. If negative permissions have been assigned
+to any user or group, those entries follow a C<Negative rights>
+header. The format of negative entries is the same as those on the
+C<Normal rights> section of the ACL, but the user or group is denied
+rather than granted the indicated permissions.
+
+AFS does not implement per-file ACLs, so for a file the command displays
+the ACL on its directory. The output for a symbolic link displays the ACL
+that applies to its target file or directory, rather than the ACL on the
+directory that houses the symbolic link.
+
+The permissions for AFS enable the possessor to perform the indicated
+action:
+
+=over 4
+
+=item a (administer)
+
+Change the entries on the ACL.
+
+=item d (delete)
+
+Remove files and subdirectories from the directory or move them to other
+directories.
+
+=item i (insert)
+
+Add files or subdirectories to the directory by copying, moving or
+creating.
+
+=item k (lock)
+
+Set read locks or write locks on the files in the directory.
+
+=item l (lookup)
+
+List the files and subdirectories in the directory, stat the directory
+itself, and issue the B<fs listacl> command to examine the directory's
+ACL.
+
+=item r (read)
+
+Read the contents of files in the directory; issue the C<ls -l> command to
+stat the elements in the directory.
+
+=item w (write)
+
+Modify the contents of files in the directory, and issue the UNIX B<chmod>
+command to change their mode bits
+
+=item A, B, C, D, E, F, G, H
+
+Have no default meaning to the AFS server processes, but are made
+available for applications to use in controlling access to the directory's
+contents in additional ways. The letters must be uppercase.
+
+=back
+
+For DFS files and directories, the permissions are similar, except that
+the DFS C<x> (execute) permission replaces the AFS C<l> (lookup)
+permission, DFS C<c> (control) replaces AFS C<a> (administer), and there
+is no DFS equivalent to the AFS C<k> (lock) permission. The meanings of
+the various permissions also differ slightly, and DFS does not implement
+negative permissions. For a complete description of DFS permissions, see
+the DFS documentation and the I<IBM AFS/DFS Migration Toolkit
+Administration Guide and Reference>.
+
+=head1 EXAMPLES
+
+The following command displays the ACL on the home directory of the user
+C<pat> (the current working directory), and on its C<private>
+subdirectory.
+
+ % fs listacl -path . private
+ Access list for . is
+ Normal rights:
+ system:authuser rl
+ pat rlidwka
+ pat:friends rlid
+ Negative rights:
+ smith rlidwka
+ Access list for private is
+ Normal rights:
+ pat rlidwka
+
+=head1 PRIVILEGE REQUIRED
+
+If the B<-path> argument names an AFS directory, the issuer must have the
+C<l> (lookup) permission on its ACL and the ACL for every directory that
+precedes it in the pathname.
+
+If the B<-path> argument names an AFS file, the issuer must have the C<l>
+(lookup) and C<r> (read) permissions on the ACL of the file's directory,
+and the B<l> permission on the ACL of each directory that precedes it in
+the pathname.
+
+If the B<-path> argument names a DFS directory or file, the issuer must
+have the C<x> (execute) permission on its ACL and on the ACL of each
+directory that precedes it in the pathname.
+
+=head1 SEE ALSO
+
+L<fs_cleanacl(1)>,
+L<fs_copyacl(1)>,
+L<fs_setacl(1)>
+
+I<IBM AFS/DFS Migration Toolkit Administration Guide and Reference>
+
+=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
+
+fs listcells - Displays the database server machines known to the Cache Manager
+
+=head1 SYNOPSIS
+
+B<fs listcells> [B<-numeric>] [B<-help>]
+
+B<fs listc> [B<-n>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<fs listcells> command formats and displays the list of the database
+server machines that the Cache Manager stores in kernel memory for its
+home cell and foreign cells.
+
+At each reboot of the client machine, the Cache Manager copies the
+contents of F</usr/vice/etc/CellServDB> into kernel memory. To modify the
+list between reboots, use the B<fs newcell> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-numeric>
+
+Displays each database server machine's IP address rather than hostname.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+The output includes a line for each cell included in the Cache Manager's
+kernel memory list, in the following format:
+
+ Cell <cell> on hosts <database server machines>
+
+The Cache Manager stores IP addresses, but by default has them translated
+to hostnames before reporting them, by passing them to the cell's name
+service (such as the Domain Name Service or a local host table). The name
+service sometimes returns hostnames in uppercase letters, or an IP address
+if it cannot resolve a name.
+
+Using the B<-numeric> flag bypasses the translation to hostnames, which
+can result in significantly faster production of output. The output
+includes IP addresses only.
+
+=head1 EXAMPLES
+
+The following example shows output for several cells as illustrations of
+the different formats for machine names:
+
+ % fs listcells
+ Cell abc.com on hosts fs1.abc.com fs2.abc.com fs3.abc.com
+ Cell stateu.edu on hosts DB1.FS.STATEU.EDU
+ DB2.FS.STATEU.EDU DB3.FS.STATEU.EDU
+ Cell def.gov on hosts 138.255.0.2 sv3.def.gov
+
+=head1 PRIVILEGE REQUIRED
+
+None
+
+=head1 SEE ALSO
+
+L<CellServDB(5)>,
+L<fs_newcell(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
+
+fs listquota - Displays quota information for a volume
+
+=head1 SYNOPSIS
+
+B<fs listquota> [B<-path> <I<dir/file path>>+] [B<-help>]
+
+B<fs listq> [B<-p> <I<dir/file path>>+] [B<-h>]
+
+B<fs lq> [B<-p> <I<dir/file path>>+] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<fs listquota> command displays information about the volume
+containing each specified directory or file (its name, quota, and amount
+of disk space used), along with an indicator of the percentage of space
+used on the host partition.
+
+To display more information about the host partition, use the B<fs
+examine> command.
+
+To set volume quota, use the B<fs setquota> or B<fs setvol> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-path> <I<dir/file path>>+
+
+Names a file or directory that resides in the volume about which to
+produce output. Partial pathnames are interpreted relative to the current
+working directory, which is also the default value if this argument is
+omitted.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+The output displays information about the volume that houses each
+specified directory or file, in a tabular format that uses the following
+headers:
+
+=over 4
+
+=item Volume Name
+
+The name of the volume.
+
+=item Quota
+
+The volume's quota in kilobytes, or the string C<no limit> to indicate an
+unlimited quota.
+
+=item Used
+
+The number of kilobytes of quota used.
+
+=item % Used
+
+The percentage of the volume's quota that is used (the C<Used> statistic
+divided by the C<Quota> statistic, times 100).
+
+=item Partition
+
+The percentage of space used on the partition that houses the
+volume. Although not directly related to how much of the user's quota is
+used, it is reported because a full partition can cause writing of data
+back to the volume to fail even when the volume has not reached its quota.
+
+=back
+
+=head1 EXAMPLES
+
+The following example shows the output for the volume C<user.smith>:
+
+ % fs listquota -path /afs/abc.com/usr/smith
+ Volume Name Quota Used % Used Partition
+ user.smith 15000 5071 34% 86%
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must have the C<l> (lookup) permission on the ACL of the root
+directory of the volume that houses the file or directory named by the
+B<-path> argument, and on the ACL of each directory that precedes it in
+the pathname.
+
+=head1 SEE ALSO
+
+L<fs_diskfree(1)>,
+L<fs_examine(1)>,
+L<fs_quota(1)>,
+L<fs_setquota(1)>,
+L<fs_setvol(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
+
+fs lsmount - Reports the volume for which a directory is the mount point.
+
+=head1 SYNOPSIS
+
+B<fs lsmount> B<-dir> <I<directory>>+ [B<-help>]
+
+B<fs ls -d> <I<directory>>+ [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<fs lsmount> command reports the volume for which each specified
+directory is a mount point, or indicates with an error message that a
+directory is not a mount point or is not in AFS.
+
+To create a mount point, use the B<fs mkmount> command. To remove one, use
+the B<fs rmmount> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-dir> <I<directory>>+
+
+Names the directory that serves as a mount point for a volume. The last
+element in the pathname provided must be an actual name, not a shorthand
+notation such as one or two periods (C<.> or C<..>).
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options
+are ignored.
+
+=back
+
+=head1 OUTPUT
+
+If the specified directory is a mount point, the output is of the
+following form:
+
+ '<directory>' is a mount point for volume '<volume name>'
+
+where
+
+=over 4
+
+=item *
+
+A number sign (C<#>) precedes the <volume name> string for a regular mount
+point.
+
+=item *
+
+A percent sign (C<%>) precedes the <volume name> string for a read/write
+mount point.
+
+=item *
+
+A cell name and colon (C<:>) follow the number or percent sign and precede
+the <volume name> string for a cellular mount point.
+
+=back
+
+The B<fs mkmount> reference page explains how the Cache Manager interprets
+each of the three types of mount points.
+
+If the directory is a symbolic link to a mount point, the output is of the
+form:
+
+ '<directory>' is a symbolic link, leading to a mount point for volume
+ '<volume name>'
+
+If the directory is not a mount point or is not in AFS, the output reads:
+
+ '<directory>' is not a mount point.
+
+If the output is garbled, it is possible that the mount point has become
+corrupted in the local AFS client cache. Use the B<fs flushmount> command
+to discard it, which forces the Cache Manager to refetch the mount point.
+
+=head1 EXAMPLES
+
+The following example shows the mount point for the home directory of user
+C<smith>:
+
+ % fs lsmount /afs/abc.com/usr/smith
+ '/afs/abc.com/usr/smith' is a mount point for volume '#user.smith'
+
+The following example shows both the regular and read/write mount points
+for the ABC Corporation cell's C<root.cell> volume.
+
+ % fs lsmount /afs/abc.com
+ '/afs/abc.com' is a mount point for volume '#root.cell'
+
+ % fs lsmount /afs/.abc.com
+ '/afs/.abc.com' is a mount point for volume '%root.cell'
+
+The following example shows a cellular mount point: the State University
+cell's C<root.cell> volume as mounted in the ABC Corporation cell's tree.
+
+ % fs lsmount /afs/stateu.edu
+ '/afs/stateu.edu' is a mount point for volume '#stateu.edu:root.cell'
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must have the C<l> (lookup) permission on the ACL of the root
+directory of the volume that houses the file or directory named by the
+B<-dir> argument, and on the ACL of each directory that precedes it in the
+pathname.
+
+=head1 SEE ALSO
+
+L<fs_flushmount(1)>,
+L<fs_mkmount(1)>,
+L<fs_rmmount(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
+
+fs messages - Sets whether the Cache Manager writes log messages
+
+=head1 SYNOPSIS
+
+B<fs messages> [B<-show> (user|console|all|none)] [B<-help>]
+
+B<fs me> [B<-s> (user|console|all|none)] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<fs messages> command controls whether the Cache Manager displays
+status and warning messages on user screens, the client machine console,
+on both, or on neither.
+
+There are two types of Cache Manager messages:
+
+=over 4
+
+=item *
+
+User messages provide user-level status and warning information, and the
+Cache Manager directs them to user screens.
+
+=item *
+
+Console messages provide system-level status and warning information, and
+the Cache Manager directs them to the client machine's designated console.
+
+=back
+
+Disabling messaging completely is not recommended, because the messages
+provide useful status and warning information.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-show> (user|console|all|none)
+
+Specifies the types of messages to display. Choose one of the following
+values:
+
+=over 4
+
+=item user
+
+Send user messages to user screens.
+
+=item console
+
+Send console messages to the console.
+
+=item all
+
+Send user messages to user screens and console messages to the console
+(the default if the B<-show> argument is omitted).
+
+=item none
+
+Do not send any messages to user screens or the console.
+
+=back
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command instructs the Cache Manager to display both types of
+messages:
+
+ % fs messages -show all
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be logged in as the local superuser root.
+
+=head1 SEE ALSO
+
+L<afsd(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+fs mkmount - Creates a mount point for a volume
+
+=head1 SYNOPSIS
+
+B<fs mkmount> B<-dir> <I<directory>> B<-vol> <I<volume name>>
+ [B<-cell> <I<cell name>>] [B<-rw>] [B<-fast>] [B<-help>]
+
+B<fs mk> B<-d> <I<directory>> B<-v> <I<volume name>>
+ [B<-c> <I<cell name>>] [B<-r>] [B<-f>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<fs mkmount> command creates a mount point for the volume named by
+the B<-vol> argument at the location in the AFS file space specified by
+the B<-dir> argument. The mount point looks like a standard directory
+element, and serves as the volume's root directory, but is actually a
+special file system object that refers to an AFS volume. When the Cache
+Manager first encounters a given mount point during pathname traversal, it
+contacts the VL Server to learn which file server machines house the
+indicated volume, then fetches a copy of the volume's root directory from
+the appropriate file server machine.
+
+It is possible, although not recommended, to create more than one mount
+point to a volume. The Cache Manager can become confused if a volume is
+mounted in two places along the same path through the filespace.
+
+The Cache Manager observes three basic rules as it traverses the AFS
+filespace and encounters mount points:
+
+=over 4
+
+=item Rule 1: Access Backup and Read-only Volumes When Specified
+
+When the Cache Manager encounters a mount point that specifies a volume
+with either a C<.readonly> or a C<.backup> extension, it accesses that
+type of volume only. If a mount point does not have either a C<.backup> or
+C<.readonly> extension, the Cache Manager uses Rules 2 and 3.
+
+For example, the Cache Manager never accesses the read/write version of a
+volume if the mount point names the backup version. If the specified
+version is inaccessible, the Cache Manager reports an error.
+
+=item Rule 2: Follow the Read-only Path When Possible
+
+If a mount point resides in a read-only volume and the volume that it
+references is replicated, the Cache Manager attempts to access a read-only
+copy of the volume; if the referenced volume is not replicated, the Cache
+Manager accesses the read/write copy. The Cache Manager is thus said to
+prefer a I<read-only path> through the filespace, accessing read-only
+volumes when they are available.
+
+The Cache Manager starts on the read-only path in the first place because
+it always accesses a read-only copy of the B<root.afs> volume if it
+exists; the volume is mounted at the root of a cell's AFS filespace (named
+F</afs> by convention). That is, if the C<root.afs> volume is replicated,
+the Cache Manager attempts to access a read-only copy of it rather than
+the read/write copy. This rule then keeps the Cache Manager on a read-only
+path as long as each successive volume is replicated. The implication is
+that both the C<root.afs> and C<root.cell> volumes must be replicated for
+the Cache Manager to access replicated volumes mounted below them in the
+AFS filespace. The volumes are conventionally mounted at the F</afs> and
+F</afs/I<cellname>> directories, respectively.
+
+=item Rule 3: Once on a Read/write Path, Stay There
+
+If a mount point resides in a read/write volume and the volume name does
+not have a C<.readonly> or a C<.backup> extension, the Cache Manager
+attempts to access only the a read/write version of the volume. The access
+attempt fails with an error if the read/write version is inaccessible,
+even if a read-only version is accessible. In this situation the Cache
+Manager is said to be on a I<read/write path> and cannot switch back to
+the read-only path unless mount point explicitly names a volume with a
+C<.readonly> extension. (Cellular mount points are an important exception
+to this rule, as explained in the following discussion.
+
+=back
+
+There are three types of mount points, each appropriate for a different
+purpose because of the manner in which the Cache Manager interprets them.
+
+=over 4
+
+=item *
+
+When the Cache Manager crosses a I<regular> mount point, it obeys all
+three of the mount point traversal rules previously described. To create a
+regular mount point, include only the required B<-dir> and B<-vol>
+arguments to the B<fs mkmount> command.
+
+=item *
+
+When the Cache Manager crosses a I<read/write> mount point, it attempts to
+access only the volume version named in the mount point. If the volume
+name is the base (read/write) form, without a C<.readonly> or C<.backup>
+extension, the Cache Manager accesses the read/write version of the
+volume, even if it is replicated. In other words, the Cache Manager
+disregards the second mount point traversal rule when crossing a
+read/write mount point: it switches to the read/write path through the
+filespace.
+
+To create a read/write mount point, include the B<-rw> flag on the B<fs
+mkmount> command. It is conventional to create only one read/write mount
+point in a cell's filespace, using it to mount the cell's C<root.cell>
+volume just below the AFS filespace root (by convention,
+F</afs/.I<cellname>>). See the I<IBM AFS Quick Beginnings> for
+instructions and the chapter about volume management in the I<IBM AFS
+Administration Guide> for further discussion.
+
+Creating a read/write mount point for a read-only or backup volume is
+acceptable, but unnecessary. The first rule of mount point traversal
+already specifies that the Cache Manager accesses them if the volume name
+in a regular mount point has a C<.readonly> or C<.backup> extension.
+
+=item *
+
+When the Cache Manager crosses a I<cellular> mount point, it accesses the
+indicated volume in the specified cell, which is normally a foreign
+cell. (If the mount point does not name a cell along with the volume, the
+Cache Manager accesses the volume in the cell where the mount point
+resides.) The Cache Manager disregards the third mount point traversal
+rule when crossing a regular cellular mount point: it accesses a read-only
+version of the volume if it is replicated, even if the volume that houses
+the mount point is read/write. Switching to the read-only path in this way
+is designed to avoid imposing undue load on the file server machines in
+foreign cells.
+
+To create a regular cellular mount point, include the B<-cell> argument on
+the B<fs mkmount> command. It is conventional to create cellular mount
+points only at the second level in a cell's filespace, using them to mount
+foreign cells' B<root.cell> volumes just below the AFS filespace root (by
+convention, at F</afs/I<foreign_cellname>>). The mount point enables local
+users to access the foreign cell's filespace, assuming they have the
+necessary permissions on the ACL of the volume's root directory and that
+there is an entry for the foreign cell in each local client machine's
+F</usr/vice/etc/CellServDB> file. In the output of the B<fs lsmount>
+command, the cell name and a colon (C<:>) appear between the initial
+number sign and the volume name in a regular cellular mount point name.
+
+=back
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-dir> <I<directory>>+
+
+Names the directory to create as a mount point. The directory must not
+already exist. Relative pathnames are interpreted with respect 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,
+F</afs/.abc.com>). For further discussion of the concept of read/write and
+read-only paths through the filespace, see L<DESCRIPTION>.
+
+=item B<-vol> <I<volume name>>
+
+Specifies the name or volume ID number of the volume to mount. If
+appropriate, add the C<.readonly> or C<.backup> extension to the name, or
+specify the appropriate volume ID number.
+
+=item B<-cell> <I<cell name>>
+
+Names the cell in which the volume resides (creates a cellular mount
+point). Provide the fully qualified domain name, or a shortened form that
+disambiguates it from the other cells listed in the local
+F</usr/vice/etc/CellServDB> file.
+
+If this argument is omitted, no cell indicator appears in the mount
+point. When the Cache Manager interprets it, it assumes that the volume
+named in the mount point resides in the same cell as the volume that
+houses the mount point.
+
+=item B<-rw>
+
+Creates a read/write mount point. Omit this flag to create a regular mount
+point.
+
+=item B<-fast>
+
+Prevents the Volume Location (VL) Server from checking that the volume has
+a VLDB entry and printing a warning message if it does not. Whether or not
+this flag is included, the File Server creates the mount point even when
+the volume has no VLDB entry.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command creates a regular mount point, mounting the volume
+C<user.smith> at F</afs/abc.com/usr/smith>:
+
+ % cd /afs/abc.com/usr
+ % fs mkmount -dir smith -vol user.smith
+
+The following commands create a read/write mount point and a regular mount
+point for the ABC Corporation cell's C<root.cell> volume in that cell's
+file tree. The second command follows the convention of putting a period
+at the beginning of the read/write mount point's name.
+
+ % fs mkmount -dir /afs/abc.com -vol root.cell
+ % fs mkmount -dir /afs/.abc.com -vol root.cell -rw
+
+The following command mounts the State University cell's C<root.cell>
+volume in the ABC Corporation cell's file tree, creating a regular
+cellular mount point called F</afs/stateu.edu>. When a ABC Corporation
+Cache Manager encounters this mount point, it crosses into the State
+University cell on a read-only path.
+
+ % fs mkmount -dir /afs/stateu.edu -vol root.cell -c stateu.edu
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must have the C<i> (insert) and C<a> (administer) permissions
+on the ACL of the directory that is to house the mount point.
+
+=head1 SEE ALSO
+
+L<CellServDB(5)>,
+L<fs_lsmount(1)>,
+L<fs_rmmount(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
+
+fs newcell - Changes the kernel-resident list of a cell's database servers
+
+=head1 SYNOPSIS
+
+B<fs newcell> B<-name> <I<cell name>> -servers <I<primary servers>>+
+ [B<-linkedcell> <I<linked cell name>>] [B<-help>]
+
+B<fs n> B<-n> <I<cell name>> B<-s> <I<primary servers>>+
+ [B<-l> <I<linked cell name>>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<fs newcell> command removes the Cache Manager's kernel-resident list
+of database server machines for the cell specified by the B<-name>
+argument and replaces it with the database server machines named by the
+B<-servers> argument.
+
+Each time the machine reboots, the Cache Manager constructs the kernel
+list of cells and database server machines by reading the local
+F</usr/vice/etc/CellServDB> file. This command does not change the
+F<CellServDB> file, so any changes made with it persist only until the
+next reboot, unless the issuer also edits the file. The output of the B<fs
+listcells> command reflects changes made with this command, because that
+command consults the kernel-resident list rather than the F<CellServDB>
+file.
+
+This command can introduce a completely new cell into the kernel-resident
+list, but cannot make a cell inaccessible (it is not possible to remove a
+cell's entry from the kernel-resident list by providing no values for the
+B<-server> argument). To make a cell inaccessible, remove its entry from
+the F<CellServDB> file and reboot the machine.
+
+If the B<-name> argument names a DCE cell, then the B<-servers> argument
+names DFS Fileset Location (FL) Server machines. The B<-linkedcell>
+argument specifies the name of the AFS cell to link to a DCE cell for the
+purpose of DFS fileset location. Refer to the I<IBM AFS/DFS Migration
+Toolkit Administration Guide and Reference> for more information on
+linking AFS clients to DCE cells using this command or by editing the
+F</usr/vice/etc/CellServDB> file.
+
+=head1 CAUTIONS
+
+Some commands, such as the B<klog> command, work correctly only when the
+information is accurate for a cell in both the F<CellServDB> file and the
+kernel-resident list.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-name> <I<cell name>>
+
+Specifies the fully-qualified cell name of the AFS or DCE cell.
+
+=item B<-servers> <I<primary servers>>+
+
+Specifies the fully-qualified hostnames of all AFS database server
+machines or DFS Fileset Location (FL) Server machines for the cell named
+by the B<-name> argument. If FL Server machines are specified, the local
+machine must be running the AFS/DFS Migration Toolkit Protocol Translator.
+
+=item B<-linkedcell> <I<linked cell name>>
+
+Specifies the name of the AFS cell to link to a DCE cell for the purpose
+of DFS fileset location.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following example changes the machine's kernel-resident list of
+database server machines for the ABC Corporation cell to include the
+machines C<db1.abc.com> and C<db2.abc.com>:
+
+ % fs newcell -name abc.com -servers db1.abc.com db2.abc.com
+
+The following example links the DCE cell C<dce.abc.com> to the AFS cell
+C<abc.com>. The AFS client contacts the Fileset Location (FL) servers
+C<db1.dce.abc.com> and C<db2.dce.abc.com> for fileset location information
+as it interprets a DFS pathname.
+
+ % fs newcell -name dce.abc.com \
+ -servers db1.dce.abc.com db2.dce.abc.com \
+ -linkedcell abc.com
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be logged in as the local superuser root.
+
+=head1 SEE ALSO
+
+L<CellServDB(5)>,
+L<fs_listcells(1)>
+
+I<IBM AFS/DFS Migration Toolkit Administration Guide and Reference>
+
+I<IBM AFS/DFS Migration Toolkit Administration Installation and
+Configuration Guide>
+
+=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
+
+fs quota - Displays the quota used in the volume containing a directory or file
+
+=head1 SYNOPSIS
+
+B<fs quota> [B<-path> <I<dir/file path>>+] [B<-help>]
+
+B<fs q> [B<-p> <I<dir/file path>>+] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<fs quota> command displays the percent of quota consumed in the
+volume that contains each specified directory or file.
+
+To display more detailed information about the volume and the partition it
+resides on, use the B<fs examine> and B<fs listquota> commands.
+
+To set volume quota, use the B<fs setquota> or B<fs setvol> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-path> <I<dir/file path>>
+
+Names each file or directory for which to display the quota consumed in
+its parent volume. Partial pathnames are interpreted relative to the
+current working directory, which is also the default value if this
+argument is omitted.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+The output reports the percent of volume quota used, in the following
+format:
+
+ <percent>% of quota used.
+
+=head1 EXAMPLES
+
+The following command lists the percent quota used of the volume housing
+the current working directory:
+
+ % fs quota
+ 17% of quota used.
+
+The following command lists the percent quota used of both the volume
+housing the current working directory's parent directory and the volume
+housing the directory F</afs/abc.com/usr/smith>:
+
+ % fs quota -path .. /afs/abc.com/usr/smith
+ 43% of quota used.
+ 92% of quota used.
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must have the C<l> (lookup) permission on the ACL of the root
+directory of the volume that houses the file or directory named by the
+B<-path> argument, and on the ACL of each directory that precedes it in
+the pathname.
+
+=head1 SEE ALSO
+
+L<fs_examine(1)>,
+L<fs_listquota(1)>,
+L<fs_setquota(1)>,
+L<fs_setvol(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
+
+fs rmmount - Removes a mount point
+
+=head1 SYNOPSIS
+
+B<fs rmmount> B<-dir> <I<directory>>+ [B<-help>]
+
+B<fs rm> B<-d> <I<directory>>+ [B<-h>]
+
+=head1 DESCRIPTION
+
+The fs rmmount command removes the mount point named by the B<-dir>
+argument from the file system. The corresponding volume remains on its
+host partition or partitions, but is inaccessible if there are no other
+mount points for it.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-dir> <I<directory>>+
+
+Names the mount point to delete from the file system. The last element in
+the pathname must be an actual name, not a shorthand notation such as
+"dot" (C<.>) or "dot dot" (C<..>).
+
+Specify the read/write path to the directory, to avoid the failure that
+results from attempting to delete 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,
+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 B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command removes the mount points F<jones> and F<terry> from
+the current working directory (the F</afs/abc.com/usr> directory).
+
+ % fs rmmount jones terry
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must have the C<d> (delete) permission on the ACL of the
+directory that houses each mount point.
+
+=head1 SEE ALSO
+
+L<fs_lsmount(1)>,
+L<fs_mkmount(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
+
+fs setacl - Sets the ACL for a directory
+
+=head1 SYNOPSIS
+
+B<fs setacl> B<-dir> <I<directory>>+ B<-acl> <I<access list entries>>+
+ [B<-clear>] [B<-negative>] [B<-id>] [B<-if>] [B<-help>]
+
+B<fs sa> B<-d> <I<directory>>+ B<-a> <I<access list entries>>+
+ [B<-c>] [B<-n>] [B<-id>] [B<-if>] [B<-h>]
+
+B<fs seta> B<-d> <I<directory>>+ B<-a> <I<access list entries>>+
+ [B<-c>] [B<-n>] [B<-id>] [B<-if>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<fs setacl> command adds the access control list (ACL) entries
+specified with the B<-acl> argument to the ACL of each directory named by
+the B<-dir> argument.
+
+If the B<-dir> argument designates a pathname in DFS filespace (accessed
+via the AFS/DFS Migration Toolkit Protocol Translator), it can be a file
+as well as a directory. The ACL must already include an entry for
+C<mask_obj>, however. For more details, refer to the I<IBM AFS/DFS
+Migration Toolkit Administration Guide and Reference>.
+
+Only user and group entries are acceptable values for the B<-acl>
+argument. Do not place machine entries (IP addresses) directly on an ACL;
+instead, make the machine entry a group member and place the group on the
+ACL.
+
+To completely erase the existing ACL before adding the new entries,
+provide the B<-clear> flag. To add the specified entries to the C<Negative
+rights> section of the ACL (deny rights to specified users or groups),
+provide the B<-negative> flag.
+
+To display an ACL, use the fs listacl command. To copy an ACL from one
+directory to another, use the B<fs copyacl> command.
+
+=head1 CAUTIONS
+
+If the ACL already grants certain permissions to a user or group, the
+permissions specified with the B<fs setacl> command replace the existing
+permissions, rather than being added to them.
+
+Setting negative permissions is generally unnecessary and not
+recommended. Simply omitting a user or group from the C<Normal rights>
+section of the ACL is normally adequate to prevent access. In particular,
+note that it is futile to deny permissions that are granted to members of
+the system:anyuser group on the same ACL; the user needs only to issue the
+B<unlog> command to receive the denied permissions.
+
+When including the B<-clear> option, be sure to reinstate an entry for
+each directory's owner that includes at least the C<l> (lookup)
+permission. Without that permission, it is impossible to resolve the "dot"
+(C<.>) and "dot dot" (C<..>) shorthand from within the directory. (The
+directory's owner does implicitly have the C<a> (administer) permission
+even on a cleared ACL, but must know to use it to add other permissions.)
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-dir> <I<directory>>+
+
+Names each AFS directory, or DFS directory or file, for which the set the
+ACL. Partial pathnames are interpreted relative to the current working
+directory.
+
+Specify the read/write path to each directory (or DFS file), to avoid the
+failure that results from attempting to change 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,
+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 B<-acl> <I<access list entries>>+
+
+Defines a list of one or more ACL entries, each a pair that names:
+
+=over 4
+
+=item *
+
+A user name or group name as listed in the Protection Database.
+
+=item *
+
+One or more ACL permissions, indicated either by combining the individual
+letters or by one of the four acceptable shorthand words.
+
+=back
+
+in that order, separated by a space (thus every instance of this argument
+has two parts). The accepted AFS abbreviations and shorthand words, and
+the meaning of each, are as follows:
+
+=over 4
+
+=item a (administer)
+
+Change the entries on the ACL.
+
+=item d (delete)
+
+Remove files and subdirectories from the directory or move them to other
+directories.
+
+=item i (insert)
+
+Add files or subdirectories to the directory by copying, moving or
+creating.
+
+=item k (lock)
+
+Set read locks or write locks on the files in the directory.
+
+=item l (lookup)
+
+List the files and subdirectories in the directory, stat the directory
+itself, and issue the B<fs listacl> command to examine the directory's
+ACL.
+
+=item r (read)
+
+Read the contents of files in the directory; issue the C<ls -l> command to
+stat the elements in the directory.
+
+=item w (write)
+
+Modify the contents of files in the directory, and issue the UNIX B<chmod>
+command to change their mode bits.
+
+=item A, B, C, D, E, F, G, H
+
+Have no default meaning to the AFS server processes, but are made
+available for applications to use in controlling access to the directory's
+contents in additional ways. The letters must be uppercase.
+
+=item all
+
+Equals all seven permissions (C<rlidwka>).
+
+=item none
+
+No permissions. Removes the user/group from the ACL, but does not
+guarantee they have no permissions if they belong to groups that remain on
+the ACL.
+
+=item read
+
+Equals the C<r> (read) and C<l> (lookup) permissions.
+
+=item write
+
+Equals all permissions except C<a> (administer), that is, C<rlidwk>.
+
+=back
+
+It is acceptable to mix entries that combine the individual letters with
+entries that use the shorthand words, but not use both types of notation
+within an individual pairing of user or group and permissions.
+
+To learn the proper format and acceptable values for DFS ACL entries, see
+the I<IBM AFS/DFS Migration Toolkit Administration Guide and Reference>.
+
+=item B<-clear>
+
+Removes all existing entries on each ACL before adding the entries
+specified with the B<-acl> argument.
+
+=item B<-negative>
+
+Places the specified ACL entries in the C<Negative rights> section of each
+ACL, explicitly denying the rights to the user or group, even if entries
+on the accompanying C<Normal rights> section of the ACL grant them
+permissions.
+
+This argument is not supported for DFS files or directories, because DFS
+does not implement negative ACL permissions.
+
+=item B<-id>
+
+Places the ACL entries on the Initial Container ACL of each DFS directory,
+which are the only file system objects for which this flag is supported.
+
+=item B<-if>
+
+Places the ACL entries on the Initial Object ACL of each DFS directory,
+which are the only file system objects for which this flag is supported.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following example adds two entries to the C<Normal rights> section of
+the current working directory's ACL: the first entry grants C<r> (read)
+and C<l> (lookup) permissions to the group pat:friends, while the other
+(using the C<write> shorthand) gives all permissions except C<a>
+(administer) to the user C<smith>.
+
+ % fs setacl -dir . -acl pat:friends rl smith write
+
+ % fs listacl -path .
+ Access list for . is
+ Normal rights:
+ pat:friends rl
+ smith rlidwk
+
+The following example includes the B<-clear> flag, which removes the
+existing permissions (as displayed with the B<fs listacl> command) from
+the current working directory's F<reports> subdirectory and replaces them
+with a new set.
+
+ % fs listacl -dir reports
+ Access list for reports is
+ Normal rights:
+ system:authuser rl
+ pat:friends rlid
+ smith rlidwk
+ pat rlidwka
+ Negative rights:
+ terry rl
+
+ % fs setacl -clear -dir reports -acl pat all smith write system:anyuser rl
+
+ % fs listacl -dir reports
+ Access list for reports is
+ Normal rights:
+ system:anyuser rl
+ smith rlidwk
+ pat rlidwka
+
+The following example use the B<-dir> and B<-acl> switches because it sets
+the ACL for more than one directory (both the current working directory
+and its F<public> subdirectory).
+
+ % fs setacl -dir . public -acl pat:friends rli
+
+ % fs listacl -path . public
+ Access list for . is
+ Normal rights:
+ pat rlidwka
+ pat:friends rli
+ Access list for public is
+ Normal rights:
+ pat rlidwka
+ pat:friends rli
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must have the C<a> (administer) permission on the directory's
+ACL; the directory's owner and the members of the system:administrators
+group have the right implicitly, even if it does not appear on the ACL.
+
+=head1 SEE ALSO
+
+L<fs_copyacl(1)>,
+L<fs_listacl(1)>,
+L<fs_mkmount(1)>
+
+I<IBM AFS/DFS Migration Toolkit Administration Guide and Reference>
+
+=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
+
+fs setcachesize - Sets the size of the disk cache
+
+=head1 SYNOPSIS
+
+B<fs setcachesize> [B<-blocks> <I<size in 1K byte blocks (0 => reset)>>]
+ [B<-reset>] [B<-help>]
+
+B<fs setca> [B<-b> <I<size in 1K byte blocks (0 => reset)>>]
+ [B<-r>] [B<-h>]
+
+B<fs cachesize> [B<-b> <I<size in 1K byte blocks (0 => reset)>>]
+ [B<-r>] [B<-h>]
+
+B<fs ca> [B<-b> <I<size in 1K byte blocks (0 => reset)>>]
+ [B<-r>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<fs setcachesize> command changes the number of kilobyte blocks of
+local disk space available to the Cache Manager for its data cache, on
+machines that use a disk cache. The command is not operative on machines
+that use a memory cache.
+
+To return the cache size to the default value specified in the third field
+of the local F</usr/vice/etc/cacheinfo> file, provide a value of C<0> to
+the B<-blocks> argument.
+
+To return the cache size to the value set when the machine was last
+rebooted, use the B<-reset> flag instead of the B<-blocks> argument. This
+is normally the amount specified in the F<cacheinfo> file, unless the
+B<-blocks> argument was included on the B<afsd> command to override the
+B<cacheinfo> value.
+
+To display the current cache size and amount of cache in use, for both
+disk and memory caches, use the B<fs getcacheparms> command.
+
+=head1 CAUTIONS
+
+This command is not operative on machines using a memory cache, and
+results in an error message. To change memory cache size, edit the
+B<cacheinfo> file and reboot, or reboot and provide the B<-blocks>
+argument to the B<afsd> command.
+
+On machines using a disk cache, do not set the cache size to exceed 85% to
+90% of the actual disk space available for the cache directory. The cache
+implementation itself requires a small amount of space on the partition.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-blocks> <I<size in 1K byte blocks>>
+
+Specifies the number of one-kilobyte blocks of disk space available for
+the Cache Manager to devote to the cache. Provide a value of C<0> to set
+cache size to the default specified in the F<cacheinfo> file.
+
+=item B<-reset>
+
+Returns the cache size to the value set when the machine was last
+booted. This agrees with the value in the F<cacheinfo> file unless the
+B<-blocks> argument was used on the B<afsd> command.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command sets the disk cache size to 25000 kilobyte blocks.
+
+ % fs setcachesize -blocks 25000
+
+Both of the following commands reset the disk cache size to the value in
+the F<cacheinfo> file, assuming that the B<-blocks> argument to the
+B<afsd> command was not used.
+
+ % fs setcachesize -blocks 0
+ % fs setcachesize -reset
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be logged in as the local superuser root.
+
+=head1 SEE ALSO
+
+L<cacheinfo(1)>,
+L<afsd(1)>,
+L<fs_getcacheparms(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
+
+fs setcell - Configures permissions for setuid programs from specified cells
+
+=head1 SYNOPSIS
+
+B<fs setcell> B<-cell> <I<cell name>>+ [B<-suid>] [B<-nosuid>] [B<-help>]
+
+B<fs setce> B<-c> <I<cell name>>+ [B<-s>] [B<-n>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<fs setcell> command sets whether the Cache Manager allows programs
+(and other executable files) from each cell named by the B<-cell> argument
+to run with setuid permission. By default, the Cache Manager allows
+programs from its home cell to run with setuid permission, but not
+programs from any foreign cells. A program belongs to the same cell as the
+file server machine that houses the volume in which the program's binary
+file resides, as specified in the file server machine's
+F</usr/afs/etc/ThisCell> file. The Cache Manager determines its own home
+cell by reading the F</usr/vice/etc/ThisCell> file at initialization.
+
+To enable programs from each specified cell to run with setuid permission,
+include the B<-suid> flag. To prohibit programs from running with setuid
+permission, include the B<-nosuid> flag, or omit both flags.
+
+The B<fs setcell> command directly alters a cell's setuid status as
+recorded in kernel memory, so rebooting the machine is unnecessary.
+However, non-default settings do not persist across reboots of the machine
+unless the appropriate B<fs setcell> command appears in the machine's AFS
+initialization file.
+
+To display a cell's setuid status, issue the B<fs getcellstatus> command.
+
+=head1 CAUTIONS
+
+AFS does not recognize effective UID: if a setuid program accesses AFS
+files and directories, it does so using the current AFS identity of the
+AFS user who initialized the program, not of the program's owner. Only
+the local file system recognizes effective UID.
+
+Only members of the system:administrators group can turn on the setuid
+mode bit on an AFS file or directory.
+
+When the setuid mode bit is turned on, the UNIX C<ls -l> command displays
+the third user mode bit as an C<s> instead of an C<x>. However, the C<s>
+does not appear on an AFS file or directory unless setuid permission is
+enabled for the cell in which the file resides.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-cell> <I<cell name>>+
+
+Names each cell for which to set setuid status. Provide the fully
+qualified domain name, or a shortened form that disambiguates it from the
+other cells listed in the local F</usr/vice/etc/CellServDB> file.
+
+=item B<-suid>
+
+Allows programs from each specified cell to run with setuid
+privilege. Provide it or the B<-nosuid> flag, or omit both flags to
+disallow programs from running with setuid privilege.
+
+=item B<-nosuid>
+
+Prevents programs from each specified cell from running with setuid
+privilege. Provide it or the B<-suid> flag, or omit both flags to disallow
+programs form running with setuid privilege.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command enables executable files from the State University
+cell to run with setuid privilege on the local machine:
+
+ % fs setcell -cell stateu.edu -suid
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be logged in as the local superuser root.
+
+=head1 SEE ALSO
+
+L<fs_getcellstatus(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
+
+fs setclientaddrs - Sets the client interfaces to register with the File Server
+
+=head1 SYNOPSIS
+
+B<fs setclientaddrs> [B<-address> <I<client network interfaces>>+] [B<-help>]
+
+B<fs setcl> [B<-a> <I<client network interfaces>>+] [B<-h>]
+
+B<fs sc> [B<-a> <I<client network interfaces>>+] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<fs setclientaddrs> command defines the IP addresses of the
+interfaces that the local Cache Manager registers with a File Server when
+first establishing a connection to it.
+
+The File Server uses the addresses when it initiates a remote procedure
+call (RPC) to the Cache Manager (as opposed to responding to an RPC sent
+by the Cache Manager). There are two common circumstances in which the
+File Server initiates RPCs: when it breaks callbacks and when it pings the
+client machine to verify that the Cache Manager is still accessible.
+
+The list of interfaces specified with this command replaces the list that
+the Cache Manager constructs and records in kernel memory as it
+initializes. At that time, if the file F</usr/vice/etc/NetInfo> exists on
+the client machine's local disk, the Cache Manager uses its contents as
+the basis for the list of interfaces addresses. If the file does not
+exist, the Cache Manager instead uses the network interfaces configured
+with the operating system. It then removes from the list any address
+included in the local F</usr/vice/etc/NetRestrict> file. It records the
+final list in kernel memory. (An administrator must create the F<NetInfo>
+and F<NetRestrict> files; there are no default versions of them.)
+
+If an RPC to that interface fails, the File Server simultaneously sends
+RPCs to all of the other interfaces in the list, to learn which of them
+are still available. Whichever interface replies first is the one to which
+the File Server then sends pings and RPCs to break callbacks.
+
+To list the interfaces that the Cache Manager is currently registering
+with File Servers, use the B<fs getclientaddrs> command.
+
+=head1 CAUTIONS
+
+The list specified with this command persists in kernel memory only until
+the client machine reboots. To preserve it across reboots, either list the
+interfaces in the local F</usr/vice/etc/NetInfo> file, or place the
+appropriate B<fs setclientaddrs> command in the machine's AFS
+initialization script.
+
+Changes made with this command do not propagate automatically to File
+Servers to which the Cache Manager has already established a
+connection. To force such File Servers to use the revised list, either
+reboot each file server machine, or change the F<NetInfo> file and reboot
+the client machine.
+
+The fs command interpreter verifies that each of the addresses specified
+as a value for the B<-address> argument is actually configured with the
+operating system on the client machine. If it is not, the command fails
+with an error message that marks the address as a C<Nonexistent
+interface>.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-address> <I<client network interfaces>>+
+
+Specifies each IP address to place in the list of interfaces, in dotted
+decimal format. Hostnames are not acceptable. Separate each address with
+one or more spaces.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+The message
+
+ Adding <interface>
+
+confirms that each new interface was added to the Cache Manager's
+list. The address appears in hexadecimal format to match the notation used
+in the File Server log, F</usr/afs/logs/FileLog>.
+
+=head1 EXAMPLES
+
+The following example sets the two interfaces that the Cache Manager
+registers with File Servers.
+
+ % fs setclientaddrs 191.255.105.68 191.255.108.84
+ Adding 0xbfff6944
+ Adding 0xbfff6c54
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be logged in as the local superuser root.
+
+=head1 SEE ALSO
+
+L<NetInfo(5)>,
+L<NetRestrict(5)>,
+L<fileserver(8)>,
+L<fs_getclientaddrs(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
+
+fs setquota - Sets the quota for the volume containing a file or directory
+
+=head1 SYNOPSIS
+
+B<fs setquota> [B<-path> <I<dir/file path>>]
+ B<-max> <I<max quota in kbytes>> [B<-help>]
+
+B<fs setq> [B<-p> <I<dir/file path>>] B<-m> <I<max quota in kbytes>> [B<-h>]
+
+B<fs sq> [B<-p> <I<dir/file path>>] B<-m> <I<max quota in kbytes>> [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<fs setquota> command sets the quota (maximum possible size) of the
+read/write volume that contains the directory or file named by the
+B<-path> argument.
+
+To set the quota on multiple volumes at the same time, use the B<fs
+setvol> command.
+
+To display a volume's quota, use the B<fs examine>, B<fs listquota>, or
+B<fs quota> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-path> <I<dir/file path>>
+
+Names the directory or file for which to set the host volume's
+quota. Partial pathnames are interpreted relative to the current working
+directory, which is also the default value if this argument is omitted.
+
+Specify the read/write path to the file or directory, to avoid the failure
+that results from attempting to change 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, 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 B<-max> <I<max quota in kbytes>>
+
+Sets the maximum amount of file server disk space the volume can
+occupy. Specify the number of one-kilobyte blocks as a positive integer
+(C<1024> is one megabyte). A value of C<0> sets an unlimited quota, but
+the size of the disk partition that houses the volume places an absolute
+limit on the volume's size.
+
+If the B<-path> argument is omitted (to set the quota of the volume
+housing the current working directory), the B<-max> switch must be
+included with this argument.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command imposes a maximum quota of 3000 kilobytes on the
+volume that houses the F</afs/abc.com/usr/smith> directory:
+
+ % fs setquota -path /afs/abc.com/usr/smith -max 3000
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must belong to the system:administrators group.
+
+=head1 SEE ALSO
+
+L<fs_examine(1)>,
+L<fs_listquota(1)>,
+L<fs_quota(1)>,
+L<fs_mkmount(1)>,
+L<fs_setvol(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
+
+fs setserverprefs - Sets the preference ranks for file servers or VL servers
+
+=head1 SYNOPSIS
+
+B<fs setserverprefs> [B<-servers> <I<fileserver names and ranks>>+]
+ [B<-vlservers> <I<VL server names and ranks>>+]
+ [B<-file> <I<input from named file>>] [B<-stdin>] [B<-help>]
+
+B<fs sets> [B<-se> <I<fileserver names and ranks>>+]
+ [B<-vl> <I<VL server names and ranks>>+]
+ [B<-f> <I<input from named file>>] [B<-st>] [B<-h>]
+
+B<fs sp> [B<-se> <I<fileserver names and ranks>>+]
+ [B<-vl> <I<VL server names and ranks>>+]
+ [B<-f> <I<input from named file>>] [B<-st>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<fs setserverprefs> command sets the local Cache Manager's preference
+ranks for one or more file server machine interfaces or, if the
+B<-vlserver> argument is provided, for Volume Location (VL) Server
+machines. For file server machines, the numerical ranks determine the
+order in which the Cache Manager attempts to contact the interfaces of
+machines that are housing a volume. For VL Server machines, the ranks
+determine the order in which the Cache Manager attempts to contact a
+cell's VL Servers when requesting VLDB information.
+
+The B<fs getserverprefs> reference page explains how the Cache Manager
+uses preference ranks when contacting file server machines or VL Server
+machines. The following paragraphs explain how the Cache Manager
+calculates default ranks, and how to use this command to change the
+defaults.
+
+=head2 Calculation of Default Preference Ranks
+
+The Cache Manager stores a preference rank in kernel memory as a paired IP
+address and numerical rank. If a file server machine is multihomed, the
+Cache Manager assigns a distinct rank to each of the machine's addresses
+(up to the number of addresses that the VLDB can store per machine, which
+is specified in the I<IBM AFS Release Notes>). Once calculated, a rank
+persists until the machine reboots, or until this command is used to
+change it.
+
+The Cache Manager sets default VL Server preference ranks as it
+initializes, randomly assigning a rank from the range 10,000 to 10,126 to
+each of the machines listed in the local F</usr/vice/etc/CellServDB>
+file. Machines from different cells can have the same rank, but this does
+not present a problem because the Cache Manager consults only one cell's
+ranks at a time.
+
+The Cache Manager sets default preference ranks for file server machine as
+it fetches volume location information from the VLDB. Each time it learns
+about file server machine interfaces for which it has not already set
+ranks, it assigns a rank to each interface. If the local client machine
+has only one IP address, the Cache Manager compares it to the server
+interface's IP address and sets a rank according to the following
+algorithm. If the client machine is multihomed, the Cache Manager applies
+the algorithm to each of the client machine's addresses and assigns to the
+file server machine interface the lowest rank that results.
+
+=over 4
+
+=item *
+
+If the local machine is a file server machine, the base rank for each of
+its interfaces is 5,000.
+
+=item *
+
+If the file server machine interface is on the same subnetwork as the
+client interface, its base rank is 20,000.
+
+=item *
+
+If the file server machine interface is on the same network as the client
+interface, or is at the distant end of a point-to-point link with the
+client interface, its base rank is 30,000.
+
+=item *
+
+If the file server machine interface is on a different network than the
+client interface, or the Cache Manager cannot obtain network information
+about it, its base rank is 40,000.
+
+=back
+
+After assigning a base rank to a file server machine interface, the Cache
+Manager adds to it a number randomly chosen from the range 0 (zero) to
+14. As an example, a file server machine interface in the same subnetwork
+as the local machine receives a base rank of 20,000, but the Cache Manager
+records the actual rank as an integer between 20,000 and 20,014. This
+process reduces the number of interfaces that have exactly the same
+rank. As with VL Server machine ranks, it is possible for file server
+machine interfaces from foreign cells to have the same rank as interfaces
+in the local cell, but this does not present a problem. Only the relative
+ranks of the interfaces that house a given volume are relevant, and AFS
+only supports storage of a volume in one cell at a time.
+
+=head2 Setting Non-default Preference Ranks
+
+Use the B<fs setserverprefs> command to reset an existing preference rank,
+or to set the initial rank of a file server machine interface or VL Server
+machine for which the Cache Manager has no rank. To make a rank persist
+across a reboot of the local machine, place the appropriate B<fs
+setserverprefs> command in the machine's AFS initialization file.
+
+Specify each preference rank as a pair of values separated by one or more
+spaces:
+
+=over 4
+
+=item *
+
+The first member of the pair is the fully-qualified hostname (for example,
+C<fs1.abc.com>), or the IP address in dotted decimal format, of a file
+server machine interface or VL Server machine
+
+=item *
+
+The second member of the pair is an integer. The possible ranks range from
+C<1> through C<65535>.
+
+=back
+
+As with default ranks, the Cache Manager adds a randomly chosen integer to
+a rank specified by this command. For file server machine interfaces, the
+integer is from the range 0 (zero) to 14; for VL Server machines, it is
+from the range 0 (zero) to 126. For example, if the administrator assigns
+a rank of 15,000 to a file server machine interface, the Cache Manager
+stores an integer between 15,000 to 15,014.
+
+There are several ways to provide ranks for file server machine interfaces
+(but not for VL Server machines):
+
+=over 4
+
+=item *
+
+On the command line, following the B<-servers> argument.
+
+=item *
+
+In a file named by the B<-file> argument. Place each pair on its own line
+in the file. Directing the output from the B<fs getserverprefs> command to
+a file automatically generates a file with the proper format.
+
+=item *
+
+Via the standard input stream, by providing the B<-stdin> flag. This
+method enables the issuer to feed in values directly from a program or
+script that generates preference ranks by using an algorithm appropriate
+to the local cell. The AFS distribution does not include such programs or
+scripts.
+
+=back
+
+When setting file server machine preference ranks, it is legal to combine
+the B<-servers>, B<-file>, and B<-stdin> options on a single command
+line. If different options specify a different rank for the same
+interface, the Cache Manager stores and uses the rank assigned with the
+B<-servers> argument.
+
+The B<-vlservers> argument is the only way to assign VL Server machine
+ranks. It can be combined with one or more of the B<-servers>, B<-file>,
+and B<-stdin> options, but the Cache Manager applies the values provided
+for those options to file server machine ranks only.
+
+The fs command interpreter does not verify hostnames or IP addresses, and
+so assigns preference ranks to invalid machine names or addresses. The
+Cache Manager never uses such ranks unless the same incorrect information
+is in the VLDB.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-servers> <I<file server names and ranks>>+
+
+Specifies one or more file server machine preference ranks. Each rank
+pairs the fully-qualified hostname or IP address (in dotted decimal
+format) of a file server machine's interface with an integer rank,
+separated by one or more spaces; also separate each pair with one or more
+spaces. Acceptable values for the rank range from C<1> through C<65521>; a
+lower value indicates a greater preference. Providing ranks outside this
+range can have unpredictable results. Providing a value no larger than
+C<65521> guarantees that the rank does not exceed the maximum possible
+value of 65,535 even if the largest random factor (14) is added.
+
+This argument can be combined with the B<-file> argument, B<-stdin> flag,
+or both. If more than one of the arguments sets a rank for the same
+interface, the rank set by this argument takes precedence. It can also be
+combined with the B<-vlservers> argument, but does not interact with it.
+
+=item B<-vlservers> <I<VL server names and ranks>>+
+
+Specifies one or more VL Server preference ranks. Each rank pairs the
+fully-qualified hostname or IP address (in dotted decimal format) of a VL
+Server machine with an integer rank, separated by one or more spaces; also
+separate each pair with one or more spaces. Acceptable values for the rank
+range from C<1> through C<65521>; a lower value indicates a greater
+preference. Providing ranks outside this range can have unpredictable
+results. Providing a value no larger than C<65521> guarantees that the
+rank does not exceed the maximum possible value of 65,535 even if the
+largest random factor (14) is added.
+
+This argument can be combined with the B<-servers> argument, B<-file>
+argument, B<-stdin> flag, or any combination of the three, but does not
+interact with any of them. They apply only to file server machine ranks.
+
+=item B<-file> <I<input file>>
+
+Specifies the full pathname of a file from which to read pairs of file
+server machine interfaces and their ranks, using the same notation and
+range of values as for the B<-servers> argument. In the file, place each
+pair on its own line and separate the two parts of each pair with one or
+more spaces.
+
+This argument can be combined with the B<-servers> argument, B<-stdin>
+flag, or both. If more than one of the arguments sets a rank for the same
+interface, the rank set by the B<-server> argument takes precedence. It
+can also be combined with the B<-vlservers> argument, but does not
+interact with it.
+
+=item B<-stdin>
+
+Reads pairs of file server machine interface and integer rank from the
+standard input stream. The intended use is to accept input piped in from a
+user-defined program or script that generates ranks in the appropriate
+format, but it also accepts input typed to the shell. Format the interface
+and rank pairs as for the B<-file> argument. If typing at the shell, type
+Ctrl-D after the final newline to complete the input.
+
+This argument can be combined with the B<-servers> argument, the B<-file>
+argument, or both. If more than one of the arguments sets a rank for the
+same interface, the rank set by the B<-server> argument takes
+precedence. It can also be combined with the B<-vlservers> argument, but
+does not interact with it.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command sets the Cache Manager's preference ranks for the
+file server machines named C<fs3.abc.com> and C<fs4.abc.com>, the latter
+of which is specified by its IP address, 192.12.105.100. The machines
+reside in another subnetwork of the local machine's network, so their
+default base rank is 30,000. To increase the Cache Manager's preference
+for these machines, the issuer assigns a rank of C<25000>, to which the
+Cache Manager adds an integer in the range from 0 to 15.
+
+ # fs setserverprefs -servers fs3.abc.com 25000 192.12.105.100 25000
+
+The following command uses the B<-servers> argument to set the Cache
+Manager's preference ranks for the same two file server machines, but it
+also uses the B<-file> argument to read a collection of preference ranks
+from a file that resides in the local file F</etc/fs.prefs>:
+
+ # fs setserverprefs -servers fs3.abc.com 25000 192.12.105.100 25000 \
+ -file /etc/fs.prefs
+
+The /etc/fs.prefs file has the following contents and format:
+
+ 192.12.108.214 7500
+ 192.12.108.212 7500
+ 138.255.33.41 39000
+ 138.255.33.34 39000
+ 128.0.45.36 41000
+ 128.0.45.37 41000
+
+The following command uses the B<-stdin> flag to read preference ranks
+from the standard input stream. The ranks are piped to the command from a
+program, B<calc_prefs>, which was written by the issuer to calculate
+preferences based on values significant to the local cell.
+
+ # calc_prefs | fs setserverprefs -stdin
+
+The following command uses the B<-vlservers> argument to set the Cache
+Manager's preferences for the VL server machines named C<fs1.abc.com>,
+C<fs3.abc.com>, and C<fs4.abc.com> to base ranks of 1, 11000, and 65521,
+respectively:
+
+ # fs setserverprefs -vlservers fs1.abc.com 1 fs3.abc.com 11000 \
+ fs4.abc.com 65521
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be logged in as the local superuser root.
+
+=head1 SEE ALSO
+
+L<fs_getserverprefs(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
+
+fs setvol - Set quota and messages for a volume containing a file or directory
+
+=head1 SYNOPSIS
+
+B<fs setvol> [B<-path> <I<dir/file path>>+]
+ [B<-max> <I<disk space quota in 1K units>>]
+ [B<-offlinemsg> <I<offline message>>] [B<-help>]
+
+B<fs setv> [B<-p> <I<dir/file path>>+]
+ [B<-ma> <I<disk space quota in 1K units>>]
+ [B<-o> <I<offline message>>] [B<-h>]
+
+B<fs sv> [B<-p> <I<dir/file path>>+]
+ [B<-ma> <I<disk space quota in 1K units>>]
+ [B<-o> <I<offline message>>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<fs setvol> command sets the quota (maximum possible size) of the
+read/write volume that contains each directory or file named by the
+B<-path> argument. To associate a message with the volume which then
+appears in the output of the B<fs examine> command, include the
+B<-offlinemsg> argument.
+
+To display all of the settings made with this command, use the B<fs
+examine> command. The B<fs listquota> command reports a fileset's quota,
+and the B<fs quota> command the percent of quota used.
+
+To set quota on one volume at a time, use the B<fs setquota> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-path> <I<dir/file path>>+
+
+Names each file or directory for which to set the host volume's quota and
+offline message. Partial pathnames are interpreted relative to the current
+working directory, which is also the default value if this argument is
+omitted.
+
+Specify the read/write path to the file or directory, to avoid the failure
+that results from attempting to change 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, 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 B<-max> <I<disk space quota in 1K units>>
+
+Sets the maximum amount of file server disk space the volume can
+occupy. Provide a positive integer to indicate the number of one-kilobyte
+blocks (C<1024> is one megabyte). A value of C<0> sets an unlimited quota,
+but the size of the disk partition that houses the volume places an
+absolute limit on the volume's size.
+
+If the B<-path> argument is omitted (so that the command sets the quota of
+the volume housing the current working directory), the B<-max> switch must
+be provided.
+
+=item B<-offlinemsg>
+
+Associates a message with the volume which then appears in the output of
+the B<fs examine> command. Its intended use is to explain why the volume
+is currently offline.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command imposes a 6500 kilobyte quota on the volumes mounted
+at the home directories F</afs/abc.com/usr/smith> and
+F</afs/abc.com/usr/pat>:
+
+ % cd /afs/abc.com/usr
+ % fs setvol -path smith pat -max 6500B<>
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must belong to the system:administrators group.
+
+=head1 SEE ALSO
+
+L<fs_examine(1)>,
+L<fs_listquota(1)>,
+L<fs_mkmount(1)>,
+L<fs_quota(1)>,
+L<fs_setquota(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
+
+fs storebehind - Enables asynchronous writes to the file server
+
+=head1 SYNOPSIS
+
+B<fs storebehind> [B<-kbytes> <I<asynchrony for specified names>>]
+ [B<-files> <I<specific pathnames>>+]
+ [B<-allfiles> <I<new default (KB)>>] [B<-verbose>] [B<-help>]
+
+B<fs st> [B<-k> <I<asynchrony for specified names>>]
+ [B<-f> <I<specific pathnames>>+]
+ [B<-a> <I<new default (KB)>>] [B<-v>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<fs storebehind> command enables the Cache Manager to perform a
+delayed asynchronous write to the File Server when an application closes a
+file. By default, the Cache Manager writes all data to the File Server
+immediately and synchronously when an application program closes a file --
+that is, the close() system call does not return until the Cache Manager
+has actually transferred the final chunk of the file to the File
+Server. This command specifies the number of kilobytes of a file that can
+still remain to be written to the File Server when the Cache Manager
+returns control to the application. It is useful if users working on the
+machine commonly work with very large files, but also introduces the
+complications discussed in the L<CAUTIONS>.
+
+Set either or both of the following in a single command:
+
+=over 4
+
+=item *
+
+To set a value that applies to all AFS files manipulated by applications
+running on the machine, use the B<-allfiles> argument. This value is
+termed the I<default store asynchrony> for the machine, and persists until
+the machine reboots. If it is not set, the default value is zero,
+indicating that the Cache Manager performs synchronous writes.
+
+As an example, the following setting means that when an application closes
+a file, the Cache Manager can return control to the application as soon as
+no more than 10 kilobytes of the file remain to be written to the File
+Server.
+
+ -allfiles 10
+
+=item *
+
+To set a value that applies to one or more individual files, and overrides
+the value of the B<-allfiles> argument for them, combine the B<-kbytes>
+and B<-files> arguments. The setting persists as long as there is an entry
+for the file in the kernel table that the Cache Manager uses to track
+certain information about files. In general, such an entry persists at
+least until an application closes the file or exits, but the Cache Manager
+is free to recycle the entry if the file is inactive and it needs to free
+up slots in the table. To increase the certainty that there is an entry
+for the file in the table, issue the B<fs storebehind> command shortly
+before closing the file.
+
+As an example, the following setting means that when an application closes
+either of the files B<bigfile> and B<biggerfile>, the Cache Manager can
+return control to the application as soon as no more than a megabyte of
+the file remains to be written to the File Server.
+
+ -kbytes 1024 -files bigfile biggerfile
+
+Note that once an explicit value has been set for a file, the only way to
+make it subject to the default store asynchrony once again is to set
+B<-kbytes> to that value. In other words, there is no combination of
+arguments that automatically makes a file subject to the default store
+asynchrony once another value has been set for the file.
+
+=back
+
+To display the settings that currently apply to individual files or to all
+files, provide the command's arguments in certain combinations as
+specified in L<OUTPUT>.
+
+=head1 CAUTIONS
+
+For the following reasons, use of this command is not recommended in most
+cases.
+
+In normal circumstances, an asynchronous setting results in the Cache
+Manager returning control to applications earlier than it otherwise does,
+but this is not guaranteed.
+
+If a delayed write fails, there is no way to notify the application, since
+the close() system call has already returned with a code indicating
+success.
+
+Writing asynchronously increases the possibility that the user will not
+notice if a write operation makes the volume that houses the file exceed
+its quota. As always, the portion of the file that exceeds the volume's
+quota is lost, which prompts a message such as the following:
+
+ No space left on device
+
+To avoid losing data, it is advisable to verify that the volume housing
+the file has space available for the amount of data anticipated to be
+written.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-kbytes> <I<asynchrony for specified names>>
+
+Specifies the number of kilobytes of data from each file named by the
+B<-files> argument that can remain to be written to the file server when
+the Cache Manager returns control to an application program that closed
+the file. The B<-files> argument is required along with this
+argument. Provide an integer from the range C<0> (which reinstates the
+Cache Manager's default behavior or writing synchronously) to the maximum
+AFS file size.
+
+=item B<-files> <I<specific pathnames>>+
+
+Names each file to which the value set with the B<-kbytes> argument
+applies. The setting persists as long as there is an entry for the file in
+the kernel table that the Cache Manager uses to track certain information
+about files. Because closing a file generally erases the entry, when
+reopening a file the only way to guarantee that the setting still applies
+is to reissue the command. If this argument is provided without the
+B<-kbytes> argument, the command reports the current setting for the
+specified files, and the default store asynchrony.
+
+=item B<-allfiles> <I<new default (KB)>>
+
+Sets the default store asynchrony for the local machine, which is the
+number of kilobytes of data that can remain to be written to the file
+server when the Cache Manager returns control to the application program
+that closed a file. The value applies to all AFS files manipulated by
+applications running on the machine, except those for which settings have
+been made with the B<-kbytes> and B<-files> arguments. Provide an integer
+from the range C<0> (which indicates the default of synchronous writes) to
+the maximum AFS file size.
+
+=item B<-verbose>
+
+Produces output confirming the settings made with the accompanying
+B<-kbytes> and B<-files> arguments, the B<-allfiles> argument, or all
+three. If provided by itself, reports the current default store
+asynchrony.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+If none of the command's options are included, or if only the B<-verbose>
+flag is included, the following message reports the default store
+asynchrony (the setting that applies to all files manipulated by
+applications running on the local machine and for which not more specific
+asynchrony is set).
+
+ Default store asynchrony is <x> kbytes.
+
+A value of C<0> (zero) indicates synchronous writes and is the default if
+no one has included the B<-allfiles> argument on this command since the
+machine last rebooted.
+
+If the B<-files> argument is provided without the B<-kbytes> argument, the
+output reports the value that applies to each specified file along with
+the default store asynchrony. If a particular value has previously been
+set for a file, the following message reports it:
+
+ Will store up to <y> kbytes of <file> asynchronously.
+ Default store asynchrony is <x> kbytes.
+
+If the default store asynchrony applies to a file because no explicit
+B<-kbytes> value has been set for it, the message is instead as follows:
+
+ Will store <file> according to default.
+ Default store asynchrony is <x> kbytes.
+
+If the B<-verbose> flag is combined with arguments that set values
+(B<-files> and B<-kbytes>, or B<-allfiles>, or all three), there is a
+message that confirms immediately that the setting has taken effect. When
+included without other arguments or flags, the B<-verbose> flag reports
+the default store asynchrony only.
+
+=head1 EXAMPLES
+
+The following command enables the Cache Manager to return control to the
+application program that closed the file F<test.data> when 100 kilobytes
+still remain to be written to the File Server. The B<-verbose> flag
+produces output that confirms the new setting, and that the default store
+asynchrony is zero.
+
+ % fs storebehind -kbytes 100 -files test.data -verbose
+ Will store up to 100 kbytes of test.data asynchronously.
+ Default store asynchrony is 0 kbytes.
+
+=head1 PRIVILEGE REQUIRED
+
+To include the B<-allfiles> argument, the issuer must be logged in as the
+local superuser C<root>.
+
+To include the B<-kbytes> and B<-files> arguments, the issuer must either
+be logged in as the local superuser C<root> or have the C<w> (write)
+permission on the ACL of each file's directory.
+
+To view the current settings (by including no arguments, the B<-file>
+argument alone, or the B<-verbose> argument alone), no privilege is
+required.
+
+=head1 SEE ALSO
+
+L<afsd(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+fs sysname - Reports or sets the CPU/operating system type
+
+=head1 SYNOPSIS
+
+B<fs sysname> [B<-newsys> <I<new sysname>>] [B<-help>]
+
+B<fs sy> [B<-n> <I<new sysname>>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<fs sysname> command sets or displays the local machine's
+CPU/operating system type as recorded in kernel memory. The Cache Manager
+substitutes the string for the I<@sys> variable which can occur in AFS
+pathnames; the I<IBM AFS Quick Beginnings> and I<IBM AFS Administration
+Guide> explain how using I<@sys> can simplify cell configuration. It is
+best to use it sparingly, however, because it can make the effect of
+changing directories unpredictable.
+
+The command always applies to the local machine only. If issued on an NFS
+client machine accessing AFS via the NFS/AFS Translator, the string is set
+or reported for the NFS client machine. The Cache Manager on the AFS
+client machine serving as the NFS client's NFS/AFS translator machine
+stores the value in its kernel memory, and so can provide the NFS client
+with the proper version of program binaries when the user issues commands
+for which the pathname to the binaries includes I<@sys>. There is a
+separate record for each user logged into the NFS client, which implies
+that if a user adopts a new identity (UNIX UID) during a login session on
+the NFS client -- perhaps by using the UNIX B<su> command -- he or she
+must verify that the correct string is set for the new identity also.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-newsys> <I<new sysname>>
+
+Sets the CPU/operating system indicator string for the local machine. If
+this argument is omitted, the output displays the current setting
+instead. AFS uses a standardized set of strings; consult the I<IBM AFS
+Quick Beginnings> or I<AFS Release Notes>.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+When the B<-newsys> argument is omitted, the output reports the machine's
+system type in the following format:
+
+ Current sysname is '<system_type>'
+
+=head1 EXAMPLES
+
+The following example shows the output produced on a Sun SPARCStation
+running Solaris 5.7:
+
+ % fs sysname
+ Current sysname is 'sun4x_57'
+
+The following command defines a machine to be a IBM RS/6000 running AIX
+4.2:
+
+ % fs sysname -newsys rs_aix42
+
+=head1 PRIVILEGE REQUIRED
+
+To display the current setting, no privilege is required. To include the
+B<-newsys> argument on an AFS client machine, the issuer must be logged in
+as the local superuser C<root>.
+
+=head1 SEE ALSO
+
+L<fs_exportafs(1)>,
+L<sys(1)>
+
+I<IBM AFS Quick Beginnings>
+
+I<IBM AFS Administration Guide>
+
+=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
+
+fs whereis - Reports each file server housing a file or directory
+
+=head1 SYNOPSIS
+
+B<fs whereis> [B<-path> <I<dir/file path>>+] [B<-help>]
+
+B<fs whe> [B<-p> <I<dir/file path>>+] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<fs whereis> command returns the name of each file server machine
+that houses the volume containing each directory or file named by the
+B<-path> argument.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-path> <I<dir/file path>>+
+
+Names each AFS file or directory for which to return the host file server
+machine. Partial pathnames are interpreted relative to the current working
+directory, which is also the default value if this argument is omitted.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+The output includes a line for each specified directory or file. It names
+the file server machine on which the volume that houses the specified
+directory or file resides. A list of multiple machines indicates that the
+directory or file is in a replicated volume.
+
+Machine names usually have a suffix indicating their cell membership. If
+the cell is not clear, use the B<fs whichcell> command to display the cell
+in which the directory or file resides. To display the cell membership of
+the local machine, use the B<fs wscell> command.
+
+=head1 EXAMPLES
+
+The following example indicates that volume housing the directory
+F</afs/abc.com> resides is replicated on both C<fs1.abc.com> and
+C<fs3.abc.com>:
+
+ % fs whereis -path /afs/abc.com
+ File /afs/abc.com is on hosts fs1.abc.com fs3.abc.com
+
+=head1 PRIVILEGE REQUIRED
+
+None
+
+=head1 SEE ALSO
+
+L<fs_whichcell(1)>,
+L<fs_wscell(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
+
+fs whichcell - Returns the cell to which a file or directory belongs
+
+=head1 SYNOPSIS
+
+B<fs whichcell> [B<-path> <I<dir/file path>>+] [B<-help>]
+
+B<fs whi > [B<-p> <I<dir/file path>>+] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<fs whichcell> command returns the name of the cell in which the
+volume that houses each indicated directory or file resides.
+
+To display the file server machine on which the volume housing a directory
+or file resides, use the B<fs whichcell> command. To display the cell
+membership of the local machine, use the B<fs wscell> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-path> I<Idir/file path>>+
+
+Names each AFS file or directory for which to return the cell
+membership. Partial pathnames are interpreted relative to the current
+working directory, which is also the default value if this argument is
+omitted.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+The output includes a line for each directory or file, naming the cell to
+which the volume that houses the directory or file resides.
+
+=head1 EXAMPLES
+
+The following example shows that the current working directory resides in
+a volume in the ABC Corporation cell:
+
+ % fs whichcell
+ File . lives in cell 'abc.com'
+
+=head1 PRIVILEGE REQUIRED
+
+None
+
+=head1 SEE ALSO
+
+L<fs_wscell(1)>,
+L<fs_whereis(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
+
+fs wscell - Returns the name of the cell to which a machine belongs
+
+=head1 SYNOPSIS
+
+B<fs wscell> [B<-help>]
+
+B<fs ws> [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<fs wscell> command returns the name of the local machine's home
+cell.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+The output displays the contents of the local F</usr/vice/etc/ThisCell>
+file, in the format
+
+ This workstation belongs to cell '<cellname>'
+
+=head1 EXAMPLES
+
+The following example results when the fs wscell is issued on a machine in
+the State University cell:
+
+ % fs wscell
+ This workstation belongs to cell 'stateu.edu'
+
+=head1 PRIVILEGE REQUIRED
+
+None
+
+=head1 SEE ALSO
+
+L<fs_whereis(1)>,
+L<fs_whichcell(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
+
+klog - Authenticates with the Authentication Server
+
+=head1 SYNOPSIS
+
+B<klog> [B<-x>] [B<-principal> <I<user name>>]
+ [-password <I<user's password>>] [B<-cell> <I<cell name>>]
+ [B<-servers> <I<explicit list of servers>>+]
+ [B<-pipe>] [B<-silent>]
+ [B<-lifetime> <I<ticket lifetime in hh[:mm[:ss]]>>]
+ [B<-setpag>] [B<-tmp>] [B<-help>]
+
+B<klog> [B<-x>] [B<-pr> <I<user name>>] [B<-pa> <I<user's password>>]
+ [B<-c> <I<cell name>>] [B<-s> <I<explicit list of servers>>+]
+ [B<-pi>] [B<-si>] [B<-l> <I<ticket lifetime in hh[:mm[:ss]]>>]
+ [B<-se>] [B<-t>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<klog> command obtains an AFS token from the Authentication
+Server. The Cache Manager on the local machine stores the token in a
+credential structure in kernel memory and uses it when obtaining
+authenticated access to the AFS filespace. This command does not affect
+the issuer's identity (UNIX UID) in the local file system.
+
+By default, the command interpreter obtains a token for the AFS user name
+that matches the issuer's identity in the local file system. To specify an
+alternate user, include the B<-principal> argument. The user named by the
+B<-principal> argument does not have to appear in the local password file
+(the F</etc/passwd> file or equivalent).
+
+By default, the command interpreter obtains a token for the local cell, as
+defined by the AFSCELL environment variable set in the command shell or by
+the F</usr/vice/etc/ThisCell> file on the local machine. To specify an
+alternate cell, include the B<-cell> argument. The command interpreter
+contacts an Authentication Server chosen at random from the cell's entry
+in the local F</usr/afs/etc/CellServDB> file, unless the B<-servers>
+argument is used to name one or more database server machines.
+
+A user can have tokens in multiple cells simultaneously, but only one
+token per cell per connection to the client machine. If the user's
+credential structure already contains a token for the requested cell, the
+token resulting from this command replaces it.
+
+Sites that employ standard Kerberos authentication instead of the AFS
+Authentication Server must use the Kerberos version of this command,
+B<klog.krb>, on all client machines. It automatically places the issuer's
+Kerberos tickets in the file named by the KRBTKFILE environment variable,
+which the B<pagsh.krb> command defines automatically as F</tmp/tktpI<X>>
+where I<X> is the number of the user's PAG.
+
+The lifetime of the token resulting from this command is the smallest of
+the following.
+
+=over 4
+
+=item *
+
+The lifetime specified by the issuer with the B<-lifetime> argument. If
+the issuer does not include this argument, the value defaults to 720 hours
+(30 days).
+
+=item *
+
+The maximum ticket lifetime recorded for the afs entry in the
+Authentication Database. The default is 100 hours.
+
+=item *
+
+The maximum ticket lifetime recorded in the specified user's
+Authentication Database entry. The default is 25 hours for user entries
+created by an Authentication Server running AFS 3.1 or later.
+
+=item *
+
+The maximum ticket lifetime recorded in the krbtgt.I<CELLNAME> entry in
+the Authentication Database; this entry corresponds to the ticket-granting
+ticket used internally in generating the token. The default is 720 hours
+(30 days).
+
+=back
+
+The output from the kas examine command displays an Authentication
+Database entry's maximum ticket lifetime as C<Max ticket
+lifetime>. Administrators can display any entry, and users can display
+their own entries.
+
+If none of the defaults have been changed, the token lifetime is 25 hours
+for user accounts created by an Authentication Server running AFS 3.1 or
+higher. The maximum lifetime for any token is 720 hours (30 days), and the
+minimum is 5 minutes.
+
+Between the minimum and maximum values, the Authentication Server uses a
+defined set of values, according to the following rules. Requested
+lifetimes between 5 minutes and 10 hours 40 minutes are granted at 5
+minute intervals, rounding up. For example, if the issuer requests a
+lifetime of 12 minutes, the token's actual lifetime is 15 minutes.
+
+For token lifetimes greater than 10 hours 40 minutes, consult the
+following table, which presents all the possible times in units of
+I<hours>B<:>I<minutes>B<:>I<seconds>. The number in parentheses is an
+approximation of the corresponding time in days and hours (as indicated by
+the C<d> and C<h> letters). For example, C<282:22:17> means 282 hours, 22
+minutes, and 17 seconds, which translates to approximately 11 days and 18
+hours (C<11d 18h>). The Authentication Server rounds up a requested
+lifetime to the next highest possible lifetime.
+
+ 11:24:15 (0d 11h) 46:26:01 (1d 22h) 189:03:38 (7d 21h)
+ 12:11:34 (0d 12h) 49:38:40 (2d 01h) 202:08:00 (8d 10h)
+ 13:02:09 (0d 13h) 53:04:37 (2d 05h) 216:06:35 (9d 00h)
+ 13:56:14 (0d 13h) 56:44:49 (2d 08h) 231:03:09 (9d 15h)
+ 14:54:03 (0d 14h) 60:40:15 (2d 12h) 247:01:43 (10d 07h)
+ 15:55:52 (0d 15h) 64:51:57 (2d 16h) 264:06:34 (11d 00h)
+ 17:01:58 (0d 17h) 69:21:04 (2d 21h) 282:22:17 (11d 18h)
+ 18:12:38 (0d 18h) 74:08:46 (3d 02h) 301:53:45 (12d 13h)
+ 19:28:11 (0d 19h) 79:16:23 (3d 07h) 322:46:13 (13d 10h)
+ 20:48:57 (0d 20h) 84:45:16 (3d 12h) 345:05:18 (14d 09h)
+ 22:15:19 (0d 22h) 90:36:53 (3d 18h) 368:56:58 (15d 08h)
+ 23:47:38 (0d 23h) 96:52:49 (4d 00h) 394:27:37 (16d 10h)
+ 25:26:21 (1d 01h) 103:34:45 (4d 07h) 421:44:07 (17d 13h)
+ 27:11:54 (1d 03h) 110:44:28 (4d 14h) 450:53:46 (18d 18h)
+ 29:04:44 (1d 05h) 118:23:54 (4d 22h) 482:04:24 (20d 02h)
+ 31:05:22 (1d 07h) 126:35:05 (5d 06h) 515:24:22 (21d 11h)
+ 33:14:21 (1d 09h) 135:20:15 (5d 15h) 551:02:38 (22d 23h)
+ 35:32:15 (1d 11h) 144:41:44 (6d 00h) 589:08:45 (24d 13h)
+ 37:59:41 (1d 13h) 154:42:01 (6d 10h) 629:52:56 (26d 05h)
+ 40:37:19 (1d 16h) 165:23:50 (6d 21h) 673:26:07 (28d 01h)
+ 43:25:50 (1d 19h) 176:50:01 (7d 08h)
+
+=head1 CAUTIONS
+
+By default, this command does not create a new process authentication
+group (PAG); see the description of the B<pagsh> command to learn about
+PAGs. If a cell does not use an AFS-modified login utility, users must
+include B<-setpag> option to this command, or issue the B<pagsh> command
+before this one, to have their tokens stored in a credential structure
+that is identified by PAG rather than by local UID.
+
+When a credential structure is identified by local UID, the potential
+security exposure is that the local superuser C<root> can use the UNIX
+B<su> command to assume any other identity and automatically inherit the
+tokens associated with that UID. Identifying the credential structure by
+PAG eliminates this exposure.
+
+If the B<-password> argument is used, the specified password cannot begin
+with a hyphen, because it is interpreted as another option name. Use of
+the B<-password> argument is not recommended in any case.
+
+By default, it is possible to issue this command on a properly configured
+NFS client machine that is accessing AFS via the NFS/AFS Translator,
+assuming that the NFS client machine is a supported system type. However,
+if the translator machine's administrator has enabled UID checking by
+including the B<-uidcheck on> argument to the B<fs exportafs> command, the
+command fails with an error message similar to the following:
+
+ Warning: Remote pioctl to <translator_machine> has failed (err=8). . .
+ Unable to authenticate to AFS because a pioctl failed.
+
+Enabling UID checking means that the credential structure in which tokens
+are stored on the translator machine must be identified by a UID that
+matches the local UID of the process that is placing the tokens in the
+credential structure. After the B<klog> command interpreter obtains the
+token on the NFS client, it passes it to the remote executor daemon on the
+translator machine, which makes the system call that stores the token in a
+credential structure on the translator machine. The remote executor
+generally runs as the local superuser C<root>, so in most cases its local
+UID (normally zero) does not match the local UID of the user who issued
+the B<klog> command on the NFS client machine.
+
+Issuing the B<klog> command on an NFS client machine creates a security
+exposure: the command interpreter passes the token across the network to
+the remote executor daemon in clear text mode.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-x>
+
+Appears only for backwards compatibility. Its former function is now the
+default behavior of this command.
+
+=item B<-principal> <I<user name>>
+
+Specifies the user name to authenticate. If this argument is omitted, the
+Authentication Server attempts to authenticate the user logged into the
+local system.
+
+=item B<-password> <I<user's password>>
+
+Specifies the issuer's password (or that of the alternate user identified
+by the B<-principal> argument). Omit this argument to have the command
+interpreter prompt for the password, in which case it does not echo
+visibly in the command shell.
+
+=item B<-cell> <I<cell name>>
+
+Specifies the cell for which to obtain a token. The command is directed to
+that cell's Authentication Servers. During a single login session on a
+given machine, a user can be authenticated in multiple cells
+simultaneously, but can have only one token at a time for each of them
+(that is, can only authenticate under one identity per cell per session on
+a machine). It is acceptable to abbreviate the cell name to the shortest
+form that distinguishes it from the other cells listed in the
+F</usr/vice/etc/CellServDB> file on the client machine on which the
+command is issued.
+
+If this argument is omitted, the command is executed in the local cell, as
+defined
+
+=over 4
+
+=item *
+
+First, by the value of the environment variable AFSCELL.
+
+=item *
+
+Second, in the F</usr/vice/etc/ThisCell> file on the client machine on
+which the command is issued.
+
+=back
+
+=item B<-servers> <I<explicit list of servers>>+
+
+Establishes a connection with the Authentication Server running on each
+specified database server machine. The command interpreter then chooses
+one of these at random to execute the command. It is best to provide
+fully-qualified hostnames, but abbreviated forms are possibly acceptable
+depending on the state of the cell's name server at the time the command
+is issued. This option is useful for testing specific servers if problems
+are encountered.
+
+If this argument is omitted, the command interpreter establishes a
+connection with each machine listed for the indicated cell in the local
+copy of the F</usr/vice/etc/CellServDB> file, and then chooses one of them
+at random for command execution.
+
+=item B<-pipe>
+
+Suppresses all output to the standard output stream, including prompts and
+error messages. The B<klog> command interpreter expects to receive the
+password from the standard input stream. Do not use this argument; it is
+designed for use by application programs rather than human users.
+
+=item B<-silent>
+
+Suppresses some of the trace messages that the klog command produces on
+the standard output stream by default. It still reports on major problems
+encountered.
+
+=item B<-lifetime> <I<ticket lifetime>
+
+Requests a specific lifetime for the token. Provide a number of hours and
+optionally minutes and seconds in the format I<hh>[B<:>I<mm>[B<:>I<ss>]].
+The value is used in calculating the token lifetime as described in
+L<DESCRIPTION>.
+
+=item B<-setpag>
+
+Creates a process authentication group (PAG) prior to requesting
+authentication. The token is associated with the newly created PAG.
+
+=item B<-tmp>
+
+Creates a Kerberos-style ticket file in the F</tmp> directory of the local
+machine. The file is called F<tkt.I<AFS_UID>> where I<AFS_UID> is the AFS
+UID of the issuer.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+The following message indicates that the limit on consecutive
+authentication failures has been exceeded. An administrator can use the
+B<kas unlock> command to unlock the account, or the issuer can wait until
+the lockout time for the account has passed. (The time is set with the
+B<-locktime> argument to the B<kas setfields> command and displayed in the
+output from the B<kas examine> command).
+
+ Unable to authenticate to AFS because ID is locked - see your system admin
+
+If the B<-tmp> flag is included, the following message confirms that a
+Kerberos-style ticket file was created:
+
+ Wrote ticket file to /tmp
+
+=head1 EXAMPLES
+
+Most often, this command is issued without arguments. The appropriate
+password is for the person currently logged into the local system. The
+ticket's lifetime is calculated as described in L<DESCRIPTION> (if no
+defaults have been changed, it is 25 hours for a user whose Authentication
+Database entry was created in AFS 3.1 or later).
+
+ % klog
+ Password:
+
+The following example authenticates the user as admin in the ABC
+Corporation's test cell:
+
+ % klog -principal admin -cell test.abc.com
+ Password:
+
+In the following, the issuer requests a ticket lifetime of 104 hours 30
+minutes (4 days 8 hours 30 minutes). Presuming that this lifetime is
+allowed by the maximum ticket lifetimes and other factors described in
+L<DESCRIPTION>, the token's lifetime is 110:44:28, which is the next
+largest possible value.
+
+ % klog -lifetime 104:30
+ Password:
+
+=head1 PRIVILEGE REQUIRED
+
+None
+
+=head1 SEE ALSO
+
+L<fs_exportafs(1)>,
+L<kas_examine(8)>,
+L<kas_setfields(8)>,
+L<kas_unlock(8)>,
+L<kaserver(8)>,
+L<pagsh(1)>,
+L<tokens(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
+
+kpasswd - Changes the issuer's password in the Authentication Database
+
+=head1 SYNOPSIS
+
+B<kpasswd> [B<-x>] [B<-principal> <I<user name>>]
+ [B<-password> <I<user's password>>]
+ [B<-newpassword> <I<user's new password>>] [B<-cell> <I<cell name>>]
+ [B<-servers> <I<explicit list of servers>>+] [B<-pipe>] [B<-help>]
+
+B<kpasswd> [B<-x>] [B<-pr> <I<user name>>] [B<-pa> <I<user's password>>]
+ [B<-n> <I<user's new password>>] [B<-c> <I<cell name>>]
+ [B<-s> <I<explicit list of servers>>+] [B<-pi>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<kpasswd> command changes the password recorded in an Authentication
+Database entry. By default, the command interpreter changes the password
+for the AFS user name that matches the issuer's local identity (UNIX
+UID). To specify an alternate user, include the B<-principal>
+argument. The user named by the B<-principal> argument does not have to
+appear in the local password file (the F</etc/passwd> file or equivalent).
+
+By default, the command interpreter sends the password change request to
+the Authentication Server running on one of the database server machines
+listed for the local cell in the F</usr/afs/etc/CellServDB> file on the
+local disk; it chooses the machine at random. It consults the
+F</usr/vice/etc/ThisCell> file on the local disk to learn the local cell
+name. To specify an alternate cell, include the B<-cell> argument.
+
+Unlike the UNIX B<passwd> command, the B<kpasswd> command does not
+restrict passwords to eight characters or less; it accepts passwords of
+virtually any length. All AFS commands that require passwords (including
+the B<klog>, B<kpasswd>, and AFS-modified login utilities, and the
+commands in the B<kas> suite) accept passwords longer than eight
+characters, but some other applications and operating system utilities do
+not. Selecting an AFS password of eight characters or less enables the
+user to maintain matching AFS and UNIX passwords.
+
+The command interpreter makes the following checks:
+
+=over 4
+
+=item *
+
+If the program B<kpwvalid> exists in the same directory as the B<kpasswd>
+command, the command interpreter pass the new password to it for
+verification. 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:
+
+ 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:
+
+ Password was not changed because you changed it too
+ recently; see your systems administrator
+
+=back
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-x>
+
+Appears only for backwards compatibility.
+
+=item B<-principal> <I<user name>>
+
+Names the Authentication Database entry for which to change the
+password. If this argument is omitted, the database entry with the same
+name as the issuer's local identity (UNIX UID) is changed.
+
+=item B<-password> <I<user's password>>
+
+Specifies the current password. Omit this argument to have the command
+interpreter prompt for the password, which does not echo visibly:
+
+ Old password: current_password
+
+=item B<-newpassword> <I<user's new password>>
+
+Specifies the new password, which the B<kpasswd> command interpreter
+converts into an encryption key (string of octal numbers) before sending
+it to the Authentication Server for storage in the user's Authentication
+Database entry.
+
+Omit this argument to have the command interpreter prompt for the
+password, which does not echo visibly:
+
+ New password (RETURN to abort): <new_password>
+ Retype new password: <new_password>
+
+=item B<-cell> <I<cell name>>
+
+Specifies the cell in which to change the password, by directing the
+command to that cell's Authentication Servers. The issuer can abbreviate
+the cell name to the shortest form that distinguishes it from the other
+cells listed in the local F</usr/vice/etc/CellServDB> file.
+
+By default, the command is executed in the local cell, as defined
+
+=over 4
+
+=item *
+
+First, by the value of the environment variable AFSCELL.
+
+=item *
+
+Second, in the F</usr/vice/etc/ThisCell> file on the client machine on
+which the command is issued.
+
+=back
+
+=item B<-servers> <I<explicit list of servers>>
+
+Establishes a connection with the Authentication Server running on each
+specified machine, rather than with all of the database server machines
+listed for the relevant cell in the local copy of the
+F</usr/vice/etc/CellServDB> file. The B<kpasswd> command interpreter then
+sends the password-changing request to one machine chosen at random from
+the set.
+
+=item B<-pipe>
+
+Suppresses all output to the standard output stream or standard error
+stream. The B<kpasswd> command interpreter expects to receive all
+necessary arguments, each on a separate line, from the standard input
+stream. Do not use this argument, which is provided for use by application
+programs rather than human users.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following example shows user pat changing her password in the ABC
+Corporation cell.
+
+ % kpasswd
+ Changing password for 'pat' in cell 'abc.com'.
+ Old password:
+ New password (RETURN to abort):
+ Verifying, please re-enter new_password:
+
+=head1 PRIVILEGE REQUIRED
+
+None
+
+=head1 SEE ALSO
+
+L<kas_setfields(8)>,
+L<kas_setpassword(8)>,
+L<klog(1)>,
+L<kpwvalid(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+livesys - Reports the configured CPU/operating system type
+
+=head1 SYNOPSIS
+
+B<livesys>
+
+=head1 DESCRIPTION
+
+The B<livesys> command displays the string stored in kernel memory that
+indicates the local machine's CPU/operating system (OS) type,
+conventionally called the I<sysname>. The Cache Manager substitutes this
+string for the I<@sys> variable which can occur in AFS pathnames; the
+I<IBM AFS Quick Beginnings> and I<IBM AFS Administration Guide> explain
+how using I<@sys> can simplify cell configuration.
+
+To set a new value in kernel memory, use the B<fs sysname> command, which
+can also be used to view the current value. If a sysname list was set
+using B<fs sysname>, only the first value in the list will be reported by
+B<livesys>.
+
+=head1 CAUTIONS
+
+To see the full sysname list, use B<fs sysname> rather than this command.
+B<livesys> is mostly useful for scripts that need to know the primary
+sysname for the local system (to create directories that will later be
+addressed using I<@sys>, for example).
+
+B<livesys> first appeared in OpenAFS 1.2.2. Scripts that need to support
+older versions of AFS should parse the output of B<fs sysname> or use
+B<sys>.
+
+=head1 OUTPUT
+
+The machine's system type appears as a text string:
+
+ I<system_type>
+
+=head1 EXAMPLES
+
+The following example shows the output produced on a Linux system with a
+2.6 kernel:
+
+ % livesys
+ i386_linux26
+
+=head1 PRIVILEGE REQUIRED
+
+None
+
+=head1 SEE ALSO
+
+L<fs_sysname(1)>,
+L<sys(1)>
+
+I<IBM AFS Quick Beginnings>
+
+I<IBM AFS Administration Guide>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Copyright 2005 Russ Allbery <rra@stanford.edu>
+
+This documentation is covered by the IBM Public License Version 1.0. It
+was written by Russ Allbery based on the B<sys> man page.
--- /dev/null
+=head1 NAME
+
+pagsh - Creates a new PAG
+
+=head1 SYNOPSIS
+
+B<pagsh>
+
+=head1 DESCRIPTION
+
+The B<pagsh> command creates a new command shell (owned by the issuer of
+the command) and associates a new I<process authentication group> (PAG)
+with the shell and the user. A PAG is a number guaranteed to identify the
+issuer of commands in the new shell uniquely to the local Cache
+Manager. The PAG is used, instead of the issuer's UNIX UID, to identify
+the issuer in the credential structure that the Cache Manager creates to
+track each user.
+
+Any tokens acquired subsequently (presumably for other cells) become
+associated with the PAG, rather than with the user's UNIX UID. This
+method for distinguishing users has two advantages.
+
+=over 4
+
+=item *
+
+It means that processes spawned by the user inherit the PAG and so share
+the token; thus they gain access to AFS as the authenticated user. In
+many environments, for example, printer and other daemons run under
+identities (such as the local superuser C<root>) that the AFS server
+processes recognize only as C<anonymous>. Unless PAGs are used, such
+daemons cannot access files in directories whose access control lists
+(ACLs) do not extend permissions to the system:anyuser group.
+
+=item *
+
+It closes a potential security loophole: UNIX allows anyone already logged
+in as the local superuser C<root> on a machine to assume any other
+identity by issuing the UNIX B<su> command. If the credential structure is
+identified by a UNIX UID rather than a PAG, then the local superuser
+C<root> can assume a UNIX UID and use any tokens associated with that
+UID. Use of a PAG as an identifier eliminates that possibility.
+
+=back
+
+=head1 CAUTIONS
+
+Each PAG created uses two of the memory slots that the kernel uses to
+record the UNIX groups associated with a user. If none of these slots are
+available, the B<pagsh> command fails. This is not a problem with most
+operating systems, which make at least 16 slots available per user.
+
+In cells that do not use an AFS-modified login utility, use this command
+to obtain a PAG before issuing the B<klog> command (or include the
+B<-setpag> argument to the B<klog> command). If a PAG is not acquired, the
+Cache Manager stores the token in a credential structure identified by
+local UID rather than PAG. This creates the potential security exposure
+described in L<DESCRIPTION>.
+
+If users of NFS client machines for which AFS is supported are to issue
+this command as part of authenticating with AFS, do not use the B<fs
+exportafs> command's B<-uidcheck on> argument to enable UID checking on
+NFS/AFS Translator machines. Enabling UID checking prevents this command
+from succeeding. See L<klog(1)>.
+
+If UID checking is not enabled on Translator machines, then by default it
+is possible to issue this command on a properly configured NFS client
+machine that is accessing AFS via the NFS/AFS Translator, assuming that
+the NFS client machine is a supported system type. The B<pagsh> binary
+accessed by the NFS client must be owned by, and grant setuid privilege
+to, the local superuser C<root>. The complete set of mode bits must be
+C<-rwsr-xr-x>. This is not a requirement when the command is issued on AFS
+client machines.
+
+However, if the translator machine's administrator has enabled UID
+checking by including the B<-uidcheck on> argument to the B<fs exportafs>
+command, the command fails with an error message similar to the following:
+
+ Warning: Remote setpag to <translator_machine> has failed (err=8). . .
+ setpag: Exec format error
+
+=head1 EXAMPLES
+
+In the following example, the issuer invokes the C shell instead of the
+default Bourne shell:
+
+ # pagsh -c /bin/csh
+
+=head1 PRIVILEGE REQUIRED
+
+None
+
+=head1 SEE ALSO
+
+L<fs_exportafs(1)>,
+L<klog(1)>,
+L<tokens(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
+
+pts - Introduction to the pts command suite
+
+=head1 DESCRIPTION
+
+The commands in the B<pts> command suite are the administrative interface
+to the Protection Server, which runs on each database server machine in a
+cell and maintains the Protection Database. The database stores the
+information that AFS uses to augment and refine the standard UNIX scheme
+for controlling access to files and directories.
+
+Instead of relying only on the mode bits that define access rights for
+individual files, AFS associates an access control list (ACL) with each
+directory. The ACL lists users and groups and specifies which of seven
+possible access permissions they have for the directory and the files it
+contains. (It is still possible to set a directory or file's mode bits,
+but AFS interprets them in its own way; see the chapter on protection in
+the I<IBM AFS Administration Guide> for details.)
+
+AFS enables users to define groups in the Protection Database and place
+them on ACLs to extend a set of rights to multiple users simultaneously.
+Groups simplify administration by making it possible to add someone to
+many ACLs by adding them to a group that already exists on those
+ACLs. Machines can also be members of a group, so that users logged into
+the machine automatically inherit the permissions granted to the group.
+
+There are several categories of commands in the pts command suite:
+
+=over 4
+
+=item *
+
+Commands to create and remove Protection Database entries: B<pts
+creategroup>, B<pts createuser>, and B<pts delete>.
+
+=item *
+
+Commands to administer and display group membership: B<pts adduser>, B<pts
+listowned>, B<pts membership>, and B<pts removeuser>.
+
+=item *
+
+Commands to administer and display properties of user and group entries
+other than membership: B<pts chown>, B<pts examine>, B<pts listentries>,
+B<pts rename>, and B<pts setfields>.
+
+=item *
+
+Commands to set and examine the counters used when assigning IDs to users
+and groups: B<pts listmax> and B<pts setmax>.
+
+=item *
+
+Commands to obtain help: B<pts apropos> and B<pts help>.
+
+=back
+
+=head1 OPTIONS
+
+The following arguments and flags are available on many commands in the
+B<pts> suite. The reference page for each command also lists them, but
+they are described here in greater detail.
+
+=over 4
+
+=item B<-cell> <I<cell name>>
+
+Names the cell in which to run the command. It is acceptable to abbreviate
+the cell name to the shortest form that distinguishes it from the other
+entries in the F</usr/vice/etc/CellServDB> file on the local machine. If
+the B<-cell> argument is omitted, the command interpreter determines the
+name of the local cell by reading the following in order:
+
+=over 4
+
+=item *
+
+The value of the AFSCELL environment variable.
+
+=item *
+
+The local F</usr/vice/etc/ThisCell> file.
+
+=back
+
+=item B<-force>
+
+Enables the command to continue executing as far as possible when errors
+or other problems occur, rather than halting execution immediately.
+Without it, the command halts as soon as the first error is
+encountered. In either case, the B<pts> command interpreter reports errors
+at the command shell. This flag is especially useful if the issuer
+provides many values for a command line argument; if one of them is
+invalid, the command interpreter continues on to process the remaining
+arguments.
+
+=item B<-help>
+
+Prints a command's online help message on the standard output stream. Do
+not combine this flag with any of the command's other options; when it is
+provided, the command interpreter ignores all other options, and only
+prints the help message.
+
+=item B<-noauth>
+
+Establishes an unauthenticated connection to the Protection Server, in
+which the 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 Protection Server allows only
+privileged users to issue commands that change the Protection Database,
+and refuses to perform such an action even if the B<-noauth> flag is
+provided.
+
+=back
+
+=head1 PRIVILEGE REQUIRED
+
+Members of the system:administrators group can issue all B<pts> commands
+on any entry in the Protection Database.
+
+Users who do not belong to the system:administrators group can list
+information about their own entry and any group entries they own. The
+privacy flags set with the B<pts setfields> command control access to
+entries owned by other users.
+
+=head1 SEE ALSO
+
+L<pts_adduser(1)>,
+L<pts_apropos(1)>,
+L<pts_chown(1)>,
+L<pts_creategroup(1)>,
+L<pts_createuser(1)>,
+L<pts_delete(1)>,
+L<pts_examine(1)>,
+L<pts_help(1)>,
+L<pts_listentries(1)>,
+L<pts_listmax(1)>,
+L<pts_listowned(1)>,
+L<pts_membership(1)>,
+L<pts_removeuser(1)>,
+L<pts_rename(1)>,
+L<pts_setfields(1)>,
+L<pts_setmax(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
+
+pts adduser - Adds a user or machine to a Protection Database group
+
+=head1 SYNOPSIS
+
+B<pts adduser> B<-user> <I<user name>>+ B<-group> <I<group name>>+
+ [B<-cell> <I<cell name>>] [B<-noauth>] [B<-force>] [B<-help>]
+
+B<pts ad> B<-u> <I<user name>>+ B<-g> <I<group name>>+
+ [B<-c> <I<cell name>>] [B<-n>] [B<-f>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<pts adduser> command adds each user or machine entry named by the
+B<-user> argument as a member of each group named by the B<-group>
+argument.
+
+To remove members of a group, use the B<pts removeuser> command. To list
+the groups to which a user or machine belongs, or the members of a
+specified group, use the B<pts membership> command.
+
+=head1 CAUTIONS
+
+After being added as a group member, a currently authenticated user must
+reauthenticate (for example, by issuing the B<klog> command) to obtain
+permissions granted to the group on an access control list (ACL).
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-user> <I<user name>>+
+
+Specifies the name of each user or machine entry to add to each group
+named by the B<-group> argument. The name of a machine entry resembles an
+IP address and can use the wildcard notation described on the B<pts
+createuser> reference page. The user or machine entry must already exist
+in the Protection Database.
+
+=item B<-group> <I<group name>>+
+
+Specifies the complete name (including the owner prefix if applicable) of
+each group to which to add members. The group entry must already exist in
+the Protection Database.
+
+=item B<-cell> <I<cell name>>
+
+Names the cell in which to run the command. For more details, see
+L<pts(1)>.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity anonymous to the issuer. For more
+details, see L<pts(1)>.
+
+=item B<-force>
+
+Enables the command to continue executing as far as possible when errors
+or other problems occur, rather than halting execution at the first error.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following example adds user smith to the group system:administrators.
+
+ % pts adduser -user smith -group system:administrators
+
+The following example adds users C<jones>, C<terry>, and B<pat> to the
+smith:colleagues group.
+
+ % pts adduser -user jones terry pat -group smith:colleagues
+
+The following example adds the machine entries in the ABC Corporation
+subnet to the group C<bin-prot>. Because of the IP address range of the
+ABC Corporation subnet, the system administrator was able to group the
+machines into three machine entries (using the wildcard notation discussed
+on the B<pts createuser> reference page).
+
+ % pts adduser -user 138.255.0.0 192.12.105.0 192.12.106.0 -group bin-prot
+
+=head1 PRIVILEGE REQUIRED
+
+The required privilege depends on the setting of the fourth privacy flag
+in the Protection Database entry for each group named by the B<-group>
+argument (use the B<pts examine> command to display the flags):
+
+=over 4
+
+=item *
+
+If it is the hyphen, only the group's owner and members of the
+system:administrators group can add members.
+
+=item *
+
+If it is lowercase C<a>, current members of the group can add new members.
+
+=item *
+
+If it is uppercase C<A>, anyone who can access the cell's database server
+machines can add new members.
+
+=back
+
+=head1 SEE ALSO
+
+L<pts(1)>,
+L<pts_createuser(1)>,
+L<pts_examine(1)>,
+L<pts_membership(1)>,
+L<pts_removeuser(1)>,
+L<pts_setfields(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
+
+pts apropos - Displays each help entry containing a keyword string
+
+=head1 SYNOPSIS
+
+B<pts apropos> B<-topic> <I<help string>> [B<-help>]
+
+B<pts ap> B<-t> <I<help string>> [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<pts apropos> command displays the first line of the online help
+entry for any B<pts> 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 B<pts help> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=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 ("") or
+other delimiters.
+
+=item B<-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<pts> command in which the string specified by the B<-topic> argument is
+part of the command name or first line.
+
+=head1 EXAMPLES
+
+The following command lists all pts commands that include the word
+C<create> in their names or short descriptions:
+
+ % pts apropos create
+ creategroup: create a new group
+ createuser: create a new user
+
+=head1 PRIVILEGE REQUIRED
+
+None
+
+=head1 SEE ALSO
+
+L<pts(1)>,
+L<pts_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
+
+pts chown - Changes the owner of a Protection Database entry
+
+=head1 SYNOPSIS
+
+B<pts chown> B<-name> <I<group name>> B<-owner> <I<new owner>>
+ [B<-cell> <I<cell name>>] [B<-noauth>] [B<-force>] [B<-help>]
+
+B<pts cho> B<-na> <I<group name>> B<-o> <I<new owner>>
+ [B<-c> <I<cell name>>] [B<-no>] [B<-f>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<pts chown> command designates the user or group named by the
+B<-owner> argument as the owner of the group named by the B<-name>
+argument, and records the new owner in the owner field of the group's
+Protection Database entry.
+
+In the case of regular groups, this command automatically changes the
+group name's owner prefix (the part of the group name before the colon) to
+match the new owner. If the new owner is itself a group, then only its
+owner prefix, not its complete name, becomes the owner prefix in the new
+name. The change to the owner prefix does not propagate to any groups
+owned by the group, however. To make the owner prefix of such group-owned
+groups reflect the new owning group, use the B<pts rename> command.
+
+It is not possible to change a user or machine entry's owner from the
+default set at creation time, the system:administrators group.
+
+=head1 CAUTIONS
+
+While designating a machine as a group's owner does not cause an error, it
+is not recommended. The Protection Server does not extend the usual
+privileges of group ownership to users logged onto the machine.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-name> <I<group name>>
+
+Specifies the current name of the group to which to assign a new owner.
+
+=item B<-owner> <I<new owner>>
+
+Names the user or group to become the group's owner.
+
+=item B<-cell> <I<cell name>>
+
+Names the cell in which to run the command. For more details, see
+L<pts(1)>.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity anonymous to the issuer. For more
+details, see L<pts(1)>.
+
+=item B<-force>
+
+Enables the command to continue executing as far as possible when errors
+or other problems occur, rather than halting execution at the first error.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following example changes the owner of the group C<terry:friends> from
+the user C<terry> to the user C<pat>. A side effect is that the group name
+changes to C<pat:friends>.
+
+ % pts chown -name terry:friends -owner pat
+
+The following example changes the owner of the group C<terry:friends> from
+the user C<terry> to the group C<pat:buddies>. A side effect is that the
+group name changes to C<pat:friends>.
+
+ % pts chown -name terry:friends -owner pat:buddies
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must belong to the system:administrators group or currently own
+the group.
+
+=head1 SEE ALSO
+
+L<pts(1)>,
+L<pts_rename(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
+
+pts creategroup - Creates an (empty) Protection Database group entry
+
+=head1 SYNOPSIS
+
+B<pts creategroup> B<-name> <I<group name>>+
+ [B<-owner> <I<owner of the group>>]
+ [B<-id> <I<id (negated) for the group>>+] [B<-cell> <I<cell name>>]
+ [B<-noauth>] [B<-force>] [B<-help>]
+
+B<pts createg> B<-na> <I<group name>>+ [B<-o> <I<owner of the group>>]
+ [B<-i> <I<id (negated) for the group>>+] [B<-c> <I<cell name>>]
+ [B<-no>] [B<-f>] [B<-h>]
+
+B<pts cg> B<-na> <I<group name>>+ [B<-o> <I<owner of the group>>]
+ [B<-i> <I<id (negated) for the group>>+] [B<-c> <I<cell name>>]
+ [B<-no>] [B<-f>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<pts creategroup> command creates an entry in the Protection Database
+for each group specified by the B<-name> argument. The entry records the
+issuer of the command as the group's creator, and as the group's owner
+unless the B<-owner> argument names an alternate user or group as the
+owner.
+
+There are two types of groups:
+
+=over 4
+
+=item *
+
+I<regular>, the names of which have two parts separated by a colon. The
+part before the colon names the group's owner. Any user can create such
+groups.
+
+=item *
+
+I<prefix-less>, which do not have an owner prefix. Only members of the
+system:administrators group can create prefix-less groups.
+
+=back
+
+Creating a group lowers the issuer's group-creation quota by one. This is
+true even if the B<-owner> argument is used to assign ownership to an
+alternate user or group. To display a user's group-creation quota, use the
+B<pts examine> command; to set it, use the B<pts setfields> command.
+
+AFS group ID (AFS GID) numbers are negative integers and by default the
+Protection Server assigns a GID that is one less (more negative) than the
+current value of the C<max group id> counter in the Protection Database,
+decrementing the counter by one for each group. Members of the
+system:administrators group can use the B<-id> argument to assign specific
+AFS GID numbers. If any of the specified GIDs is lower (more negative)
+than the current value of the C<max group id> counter, the counter is
+reset to that value. It is acceptable to specify a GID greater (less
+negative) than the current value of the counter, but the creation
+operation fails if an existing group already has it. To display or set the
+value of the C<max group id> counter, use the B<pts listmax> or B<pts
+setmax> command, respectively.
+
+=head1 OUTPUT
+
+The command generates the following string to confirm creation of each
+group:
+
+ group <name> has id <AFS GID>
+
+=head1 CAUTIONS
+
+Although using the B<-owner> argument to designate a machine entry as a
+group's owner does not generate an error, it is not recommended. The
+Protection Server does not extend the usual privileges of group ownership
+to users logged onto the machine.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-name> <I<group name>>
+
+Specifies the name of each group to create. Provide a string of up to 63
+characters, which can include lowercase (but not uppercase) letters,
+numbers, and punctuation marks. A regular name includes a single colon
+(C<:>) to separate the two parts of the name; the colon cannot appear in a
+prefix-less group name.
+
+A regular group's name must have the following format:
+
+ <owner_name>:<group_name>
+
+and the <owner_name> field must reflect the actual owner of the group, as
+follows:
+
+=over 4
+
+=item *
+
+If the optional B<-owner> argument is not included, the field must match
+the AFS username under which the issuer is currently authenticated.
+
+=item *
+
+If the B<-owner> argument names an alternate AFS user, the field must
+match that AFS username.
+
+=item *
+
+If the B<-owner> argument names another regular group, the field must
+match the owning group's owner field (the part of its name before the
+colon). If the B<-owner> argument names a prefix-less group, the field
+must match the owning group's complete name.
+
+=back
+
+=item B<-owner> <I<owner of the group>>
+
+Specifies a user or group as the owner for each group, rather than the
+issuer of the command. Provide either an AFS username or the name of a
+regular or prefix-less group. An owning group must already have at least
+one member. This requirement prevents assignment of self-ownership to a
+group during its creation; use the B<pts chown> command after issuing this
+command, if desired.
+
+=item B<-id> <I<id for the group>>
+
+Specifies a negative integer AFS GID number for each group, rather than
+allowing the Protection Server to assign it. Precede the integer with a
+hyphen (C<->) to indicate that it is negative.
+
+If this argument is used and the B<-name> argument names multiple new
+groups, it is best to provide an equivalent number of AFS GIDs. The first
+GID is assigned to the first group, the second to the second group, and so
+on. If there are fewer GIDs than groups, the Protection Server assigns
+GIDs to the unmatched groups based on the C<max group id> counter. If
+there are more GIDs than groups, the excess GIDs are ignored. If any of
+the GIDs is lower (more negative) than the current value of the C<max
+group id> counter, the counter is reset to that value.
+
+=item B<-cell> <I<cell name>>
+
+Names the cell in which to run the command. For more details, see
+L<pts(1)>.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity anonymous to the issuer. For more
+details, see L<pts(1)>.
+
+=item B<-force>
+
+Enables the command to continue executing as far as possible when errors
+or other problems occur, rather than halting execution at the first error.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+In the following example, the user pat creates groups called
+C<pat:friends> and C<pat:colleagues>.
+
+ % pts creategroup -name pat:friends pat:colleagues
+
+The following example shows a member of the system:administrators group
+creating the prefix-less group C<staff> and assigning its ownership to the
+system:administrators group rather than to herself.
+
+ % pts creategroup -name staff -owner system:administrators
+
+In the following example, the user pat creates a group called
+C<smith:team-members>, which is allowed because the B<-owner> argument
+specifies the required value (C<smith>).
+
+ % pts creategroup -name smith:team-members -owner smith
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must belong to the system:administrators group to create
+prefix-less groups or include the B<-id> argument.
+
+To create a regular group, the issuer must
+
+=over 4
+
+=item *
+
+Be authenticated. The command fails if the B<-noauth> flag is provided.
+
+=item *
+
+Have a group-creation quota greater than zero. The B<pts examine> command
+displays this quota.
+
+=back
+
+=head1 SEE ALSO
+
+L<pts(1)>,
+L<pts_examine(1)>,
+L<pts_listmax(1)>,
+L<pts_setfields(1)>,
+L<pts_setmax(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
+
+pts createuser - Creates a user or machine entry in the Protection Database
+
+=head1 SYNOPSIS
+
+B<pts createuser> B<-name> <I<user name>>+ [B<-id> <I<user id>>+]
+ [B<-cell> <I<cell name>>] [B<-noauth>] [B<-force>] [B<-help>]
+
+B<pts createu> B<-na> <I<user name>>+ [B<-i> <I<user id>>+]
+ [B<-c> <I<cell name>>] [B<-no>] [B<-f>] [B<-h>]
+
+B<pts cu> B<-na> <I<user name>>+ [B<-i> <I<user id>>+]
+ [B<-c> <I<cell name>>] [B<-no>] [B<-f>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<pts createuser> command creates an entry in the Protection Database
+for each user or machine specified by the B<-name> argument. A user entry
+name becomes the user's AFS username (the one to provide when
+authenticating with the AFS Authentication Server). A machine entry's
+name is the machine's IP address or a wildcard notation that represents a
+range of consecutive IP addresses (a group of machines on the same
+network). It is not possible to authenticate as a machine, but a group to
+which a machine entry belongs can appear on a directory's access control
+list (ACL), thereby granting the indicated permissions to any user logged
+on to the machine.
+
+AFS user IDs (AFS UIDs) are positive integers and by default the
+Protection Server assigns an AFS UID that is one greater than the current
+value of the C<max user id> counter in the Protection Database,
+incrementing the counter by one for each user. To assign a specific AFS
+UID, use the B<-id> argument. If any of the specified AFS UIDs is greater
+than the current value of the C<max user id> counter, the counter is reset
+to that value. It is acceptable to specify an AFS UID smaller than the
+current value of the counter, but the creation operation fails if an
+existing user or machine entry already has it. To display or set the value
+of the C<max user id> counter, use the B<pts listmax> or B<pts setmax>
+command, respectively.
+
+The issuer of the B<pts createuser> command is recorded as the entry's
+creator and the group system:administrators as its owner.
+
+=head1 CAUTIONS
+
+The Protection Server reserves AFS UID 0 (zero) and returns an error if
+the B<-id> argument has that value.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-name> <I<user name>>+
+
+Specifies either a username for a user entry, or an IP address (complete
+or wildcarded) for a machine entry:
+
+=over 4
+
+=item *
+
+A username can include up to 63 numbers and lowercase letters, but it is
+best to make it shorter than eight characters, because many application
+programs cannot handle longer names. Also, it is best not to include shell
+metacharacters or other punctuation marks. In particular, the colon (C<:>)
+and at-sign (C<@>) characters are not acceptable. The period is generally
+used only in special administrative names, to separate the username and an
+I<instance>, as in the example C<pat.admin>.
+
+=item *
+
+A machine identifier is its IP address in dotted decimal notation (for
+example, 192.12.108.240), or a wildcard notation that represents a set of
+IP addresses (a group of machines on the same network). The following are
+acceptable wildcard formats. The letters C<W>, C<X>, C<Y> and C<Z> each
+represent an actual number from the range 1 through 255.
+
+=over 4
+
+=item *
+
+W.X.Y.Z represents a single machine, for example C<192.12.108.240>.
+
+=item *
+
+W.X.Y.0 matches all machines whose IP addresses start with the first three
+numbers. For example, C<192.12.108.0> matches both C<192.12.108.119> and
+C<192.12.108.120>, but does not match C<192.12.105.144>.
+
+=item *
+
+W.X.0.0 matches all machines whose IP addresses start with the first two
+numbers. For example, the address C<192.12.0.0> matches both
+C<192.12.106.23> and C<192.12.108.120>, but does not match C<192.5.30.95>.
+
+=item *
+
+W.0.0.0 matches all machines whose IP addresses start with the first
+number in the specified address. For example, the address C<192.0.0.0>
+matches both C<192.5.30.95> and C<192.12.108.120>, but does not match
+C<138.255.63.52>.
+
+=back
+
+Do not define a machine entry with the name C<0.0.0.0> to match every
+machine. The system:anyuser group is equivalent.
+
+=back
+
+=item B<-id> <I<user id>>+
+
+Specifies an AFS UID for each user or machine entry, rather than allowing
+the Protection Server to assign it. Provide a positive integer.
+
+If this argument is used and the B<-name> argument names multiple new
+entries, it is best to provide an equivalent number of AFS UIDs. The
+first UID is assigned to the first entry, the second to the second entry,
+and so on. If there are fewer UIDs than entries, the Protection Server
+assigns UIDs to the unmatched entries based on the C<max user id>
+counter. If there are more UIDs than entries, the excess UIDs are
+ignored. If any of the UIDs is greater than the current value of the C<max
+user id> counter, the counter is reset to that value.
+
+=item B<-cell> <I<cell name>>
+
+Names the cell in which to run the command. For more details, see
+L<pts(1)>.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity anonymous to the issuer. For more
+details, see L<pts(1)>.
+
+=item B<-force>
+
+Enables the command to continue executing as far as possible when errors
+or other problems occur, rather than halting execution at the first error.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+The command generates the following string to confirm creation of each
+user:
+
+ User <name> has id <id>
+
+=head1 EXAMPLES
+
+The following example creates a Protection Database entry for the user
+C<johnson>.
+
+ % pts createuser -name johnson
+
+The following example creates three wildcarded machine entries in the ABC
+Corporation cell. The three entries encompass all of the machines on the
+company's networks without including machines on other networks:
+
+ % pts createuser -name 138.255.0.0 192.12.105.0 192.12.106.0
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must belong to the system:administrators group.
+
+=head1 SEE ALSO
+
+L<pts(1)>,
+L<pts_listmax(1)>,
+L<pts_setmax(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
+
+pts delete - Deletes a Protection Database entry
+
+=head1 SYNOPSIS
+
+B<pts delete> B<-nameorid> <I<user or group name or id>>+
+ [B<-cell> <I<cell name>>] [B<-noauth>] [B<-force>] [B<-help>]
+
+B<pts d> B<-na> <I<user or group name or id>>+
+ [B<-c> <I<cell name>>] [B<-no>] [B<-f>] [-h]
+
+=head1 DESCRIPTION
+
+The B<pts delete> command removes each entry specified by the B<-nameorid>
+argument from the Protection Database. Deleting entries affects other
+parts of the system in various ways:
+
+=over 4
+
+=item *
+
+Deleted users and groups still appear on access control lists (ACLs), but
+are listed by AFS UID or GID rather than by name, because there is no
+longer an associated name to which to translate the ID. To remove these
+obsolete entries from ACLs, use the B<fs cleanacl> command.
+
+=item *
+
+Deleting a user or machine's entry removes it from the membership list of
+any group to which it belonged.
+
+=item *
+
+Deleting a group entry removes it from the membership list of any user or
+machine entry that belonged to the group, and also increments the
+group-creation quota of the group's creator by one, even if the creator no
+longer owns the group.
+
+=back
+
+To remove a user or machine from a group without actually deleting the
+entry, use the B<pts removeuser> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-nameorid> <I<user or group name or ID>>+
+
+Specifies the name or AFS UID of each user, the name or AFS GID of each
+group, or the IP address (complete or wildcard-style) or AFS UID of each
+machine entry to delete. It is acceptable to mix users, machines, and
+groups on the same command line, as well as names (IP addresses for
+machines) and IDs. Precede the GID of each group with a hyphen to indicate
+that it is negative.
+
+=item B<-cell> <I<cell name>>
+
+Names the cell in which to run the command. For more details, see
+L<pts(1)>.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity anonymous to the issuer. For more
+details, see L<pts(1)>.
+
+=item B<-force>
+
+Enables the command to continue executing as far as possible when errors
+or other problems occur, rather than halting execution at the first error.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following example deletes the user entries C<pat> and C<terry>:
+
+ % pts delete pat terry
+
+The following example deletes the Protection Database entry of the group
+with AFS GID -215.
+
+ % pts delete -215
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must belong to the system:administrators group to delete user
+and machine entries. To delete group entries, the issuer must either own
+the group or belong to the system:administrators group.
+
+=head1 SEE ALSO
+
+L<fs_cleanacl(1)>,
+L<pts(1)>,
+L<pts_removeuser(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
+
+pts examine - Displays a Protection Database entry
+
+=head1 SYNOPSIS
+
+B<pts examine> B<-nameorid> <I<user or group name or id>>+
+ [B<-cell> <I<cell name>>] [B<-noauth>] [B<-force>] [B<-help>]
+
+B<pts e> B<-na> <I<user or group name or id>>+ [B<-c> <I<cell name>>]
+ [B<-no>] [B<-f>] [B<-h>]
+
+B<pts check> B<-na> <I<user or group name or id>>+ [B<-c> <I<cell name>>]
+ [B<-no>] [B<-f>] [B<-h>]
+
+B<pts che> B<-na> <I<user or group name or id>>+ [B<-c> <I<cell name>>]
+ [B<-no>] [B<-f>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<pts examine> command displays information from the Protection
+Database entry of each user, machine or group specified by the
+B<-nameorid> argument.
+
+=head1 OPTIONS
+
+=over 4
+
+=item -nameorid <I<user or group name or id>>+
+
+Specifies the name or AFS UID of each user, the name or AFS GID of each
+group, or the IP address (complete or wildcard-style) or AFS UID of each
+machine for which to display the Protection Database entry. It is
+acceptable to mix users, machines, and groups on the same command line, as
+well as names (IP addresses for machines) and IDs. Precede the GID of each
+group with a hyphen to indicate that it is negative.
+
+=item B<-cell> <I<cell name>>
+
+Names the cell in which to run the command. For more details, see
+L<pts(1)>.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity anonymous to the issuer. For more
+details, see L<pts(1)>.
+
+=item B<-force>
+
+Enables the command to continue executing as far as possible when errors
+or other problems occur, rather than halting execution at the first error.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+The output for each entry consists of two lines that include the following
+fields:
+
+=over 4
+
+=item Name
+
+The contents of this field depend on the type of entry:
+
+=over 4
+
+=item *
+
+For a user entry, it is the username that the user types when
+authenticating with AFS.
+
+=item *
+
+For a machine entry, it is either the IP address of a single machine in
+dotted decimal format, or a wildcard notation that represents a group of
+machines on the same network. See the B<pts createuser> reference page for
+an explanation of the wildcard notation.
+
+=item *
+
+For a group entry, it is one of two types of group name. If the name has a
+colon between the two parts, it represents a regular group and the part
+before the prefix reflects the group's owner. A prefix-less group does not
+have the owner field or the colon. For more details on group names, see
+the B<pts creategroup> reference page.
+
+=back
+
+=item id
+
+A unique number that the AFS server processes use to identify AFS users,
+machines and groups. AFS UIDs for user and machine entries are positive
+integers, and AFS GIDs for group entries are negative integers. AFS UIDs
+and GIDs are similar in function to the UIDs and GIDs used in local file
+systems such as UFS, but apply only to AFS operations.
+
+=item owner
+
+The user or group that owns the entry and thus can administer it (change
+the values in most of the fields displayed in the output of this command),
+or delete it entirely. The Protection Server automatically records the
+system:administrators group in this field for user and machine entries at
+creation time.
+
+=item creator
+
+The user who issued the B<pts createuser> or B<pts creategroup> command to
+create the entry. This field serves as an audit trail, and cannot be
+changed.
+
+=item membership
+
+An integer that for users and machines represents the number of groups to
+which the user or machine belongs. For groups, it represents the number of
+group members.
+
+=item flags
+
+A string of five characters, referred to as I<privacy flags>, which
+indicate who can display or administer certain aspects of the entry.
+
+=over 4
+
+=item s
+
+Controls who can issue the B<pts examine> command to display the entry.
+
+=item o
+
+Controls who can issue the B<pts listowned> command to display the groups
+that a user or group owns.
+
+=item m
+
+Controls who can issue the B<pts membership> command to display the groups
+a user or machine belongs to, or which users or machines belong to a
+group.
+
+=item a
+
+Controls who can issue the B<pts adduser> command to add a user or machine
+to a group. It is meaningful only for groups, but a value must always be
+set for it even on user and machine entries.
+
+=item r
+
+Controls who can issue the B<pts removeuser> command to remove a user or
+machine from a group. It is meaningful only for groups, but a value must
+always be set for it even on user and machine entries.
+
+=back
+
+Each flag can take three possible types of values to enable a different
+set of users to issue the corresponding command:
+
+=over 4
+
+=item *
+
+A hyphen (-) designates the members of the system:administrators group and
+the entry's owner. For user entries, it designates the user in addition.
+
+=item *
+
+The lowercase version of the letter applies meaningfully to groups only,
+and designates members of the group in addition to the individuals
+designated by the hyphen.
+
+=item *
+
+The uppercase version of the letter designates everyone.
+
+=back
+
+For example, the flags C<SOmar> on a group entry indicate that anyone can
+examine the group's entry and display the groups that it owns, and that
+only the group's members can display, add, or remove its members.
+
+The default privacy flags for user and machine entries are C<S---->,
+meaning that anyone can display the entry. The ability to perform any
+other functions is restricted to members of the system:administrators
+group and the entry's owner (as well as the user for a user entry).
+
+The default privacy flags for group entries are C<S-M-->, meaning that all
+users can display the entry and the members of the group, but only the
+entry owner and members of the system:administrators group can perform
+other functions.
+
+=item group quota
+
+The number of additional groups the user is allowed to create. The B<pts
+createuser> command sets it to 20 for both users and machines, but it has
+no meaningful interpretation for a machine, because it is not possible to
+authenticate as a machine. Similarly, it has no meaning in group entries
+and the B<pts creategroup> command sets it to 0 (zero); do not change this
+value.
+
+=back
+
+=head1 EXAMPLES
+
+The following example displays the user entry for C<terry> and the machine
+entry C<158.12.105.44>.
+
+ % pts examine terry 158.12.105.44
+ Name: terry, id: 1045, owner: system:administrators, creator: admin,
+ membership: 9, flags: S----, group quota: 15.
+ Name: 158.12.105.44, id: 5151, owner: system:administrators,
+ creator: byu, membership: 1, flags: S----, group quota: 20.
+
+The following example displays the entries for the AFS groups with GIDs
+-673 and -674.
+
+ % pts examine -673 -674
+ Name: terry:friends, id: -673, owner: terry, creator: terry,
+ membership: 5, flags: S-M--, group quota: 0.
+ Name: smith:colleagues, id: -674, owner: smith, creator: smith,
+ membership: 14, flags: SOM--, group quota: 0.
+
+=head1 PRIVILEGE REQUIRED
+
+The required privilege depends on the setting of the first privacy flag in
+the Protection Database entry of each entry specified by the B<-nameorid>
+argument:
+
+=over 4
+
+=item *
+
+If it is lowercase C<s>, members of the system:administrators group and
+the user associated with a user entry can examine it, and only members of
+the system:administrators group can examine a machine or group entry.
+
+=item *
+
+If it is uppercase C<S>, anyone who can access the cell's database server
+machines can examine the entry.
+
+=back
+
+=head1 SEE ALSO
+
+L<pts(1)>,
+L<pts_adduser(1)>,
+L<pts_chown(1)>,
+L<pts_creategroup(1)>,
+L<pts_createuser(1)>,
+L<pts_listowned(1)>,
+L<pts_membership(1)>,
+L<pts_removeuser(1)>,
+L<pts_rename(1)>,
+L<pts_setfields(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
+
+pts help - Displays help for pts commands
+
+=head1 SYNOPSIS
+
+B<pts help> [B<-topic> <I<help string>>+] [B<-help>]
+
+B<pts h> [B<-t> <I<help string>>+] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<pts 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<pts> command.
+
+To list every pts command whose name or short description includes a
+specified keyword, use the B<pts apropos> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-topic> <I<help string>>+
+
+Indicates each command for which to display the complete online help
+entry. Omit the B<pts> part of the command name, providing only the
+operation code (for example, specify C<membership>, not C<pts
+membership>). If this argument is omitted, the output briefly describes
+every B<pts> command.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+The online help entry for each B<pts> 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 B<pts
+membership> command:
+
+ % pts help membership
+ pts membership: list membership of a user or group
+ aliases: groups
+ Usage: pts membership -nameorid <user or group name or id>+
+ [-cell <cell name>] [-noauth] [-force] [-help]
+
+=head1 PRIVILEGE REQUIRED
+
+None
+
+=head1 SEE ALSO
+
+L<pts(1)>,
+L<pts_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
+
+pts listentries - Displays all users or groups in the Protection Database
+
+=head1 SYNOPSIS
+
+B<pts listentries> [B<-users>] [B<-groups>] [B<-cell> <I<cell name>>]
+ [B<-noauth>] [B<-force>] [B<-help>]
+
+B<pts liste> [B<-u>] [B<-g>] [B<-c> <I<cell name>>] [B<-n>] [B<-f>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<pts listentries> command displays the name and AFS ID of all
+Protection Database entries of the indicated type. It also displays the
+AFS ID of each entry's owner and creator.
+
+To display all user and machine entries, either include the B<-users> flag
+or omit both it and the B<-groups> flag. To display all group entries,
+include the B<-groups> flag. To display all entries, provide both flags.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-users>
+
+Displays user and machine entries.
+
+=item B<-groups>
+
+Displays group entries.
+
+=item B<-cell> <I<cell name>>
+
+Names the cell in which to run the command. For more details, see
+L<pts(1)>.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity anonymous to the issuer. For more
+details, see L<pts(1)>.
+
+=item B<-force>
+
+Enables the command to continue executing as far as possible when errors
+or other problems occur, rather than halting execution at the first error.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+The output includes a line for each entry, with information in four
+columns that have the following headers:
+
+=over 4
+
+=item Name
+
+The entry's name.
+
+=item ID
+
+The entry's AFS ID (AFS UID for a user or machine, negative AFS GID for a
+group).
+
+=item Owner
+
+The AFS ID of the user or group that owns the entry.
+
+=item Creator
+
+The AFS ID of the user who created the entry (the system:administrators
+group is listed as the creator of the entry for C<anonymous> and the
+system groups, but it is not otherwise possible for a group to create
+groups).
+
+=back
+
+In general, the entries appear in the order in which they were created.
+
+=head1 EXAMPLES
+
+The following example displays both user and group entries.
+
+ % pts listentries -users -groups
+ Name ID Owner Creator
+ system:administrators -204 -204 -204
+ system:anyuser -101 -204 -204
+ system:authuser -102 -204 -204
+ anonymous 32766 -204 -204
+ admin 1 -204 32766
+ pat 100 -204 1
+ smith 101 -204 1
+ pat:friends -206 100 100
+ staff -207 -204 1
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must belong to the system:administrators group.
+
+=head1 SEE ALSO
+
+L<pts(1)>,
+L<pts_creategroup(1)>,
+L<pts_createuser(1)>,
+L<pts_examine(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
+
+pts listmax - Displays the max user id and max group id counters
+
+=head1 SYNOPSIS
+
+B<pts listmax> [B<-cell> <I<cell name>>] [B<-noauth>] [B<-force>] [B<-help>]
+
+B<pts listm> [B<-c> <I<cell name>>] [B<-n>] [B<-f>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<pts listmax> command displays the values of the C<max user id> and
+C<max group id> counters, which the Protection Server uses to track the
+AFS user IDs (AFS UIDs) it allocates to new users or machines, and the AFS
+group IDs (AFS GIDs) it allocates to new groups, respectively. When an
+administrator next issues the B<pts createuser> command and does not
+include the B<-id> argument, the new user or machine receives an AFS UID
+one greater than the C<max user id> counter, and when a user issues the
+B<pts creategroup> command and does not include the B<-id> argument, the
+new group receives an AFS UID one less (more negative) than the C<max
+group id> counter.
+
+To reset one or both counters, members of the system:administrators group
+can issue the B<pts setmax> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-cell> <I<cell name>>
+
+Names the cell in which to run the command. For more details, see
+L<pts(1)>.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity anonymous to the issuer. For more
+details, see L<pts(1)>.
+
+=item B<-force>
+
+Enables the command to continue executing as far as possible when errors
+or other problems occur, rather than halting execution at the first error.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+The command displays the counters in the following format:
+
+ Max user id is <user_counter> and max group id is <group_counter>.
+
+=head1 EXAMPLES
+
+The following example displays the output of this command:
+
+ % pts listmax
+ Max user name is 1271 and max group id is -382.
+
+=head1 PRIVILEGE REQUIRED
+
+None
+
+=head1 SEE ALSO
+
+L<pts(1)>,
+L<pts_setmax(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
+
+pts listowned - Show the Protection Database groups owned by a user or group
+
+=head1 SYNOPSIS
+
+B<pts listowned> B<-nameorid> <I<user or group name or id>>+
+ [-cell <I<cell name>>] [B<-noauth>] [B<-force>] [B<-help>]
+
+B<pts listo> B<-na> <I<user or group name or id>>+
+ [-c <I<cell name>>] [B<-no>] [B<-f>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<pts listowned> command lists the groups owned by each user or group
+specified by the B<-nameorid> argument.
+
+To list any I<orphaned group>s, whose owners have themselves been deleted
+from the Protection Database, provide a value of C<0> (zero) for the
+B<-nameorid> argument. To change the owner to a user or group that still
+exists, use the B<pts chown> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-nameorid> <I<user or group name or id>>+
+
+Specifies the name or AFS UID of each user, or the name or AFS GID of each
+group, for which to display the list of owned groups. It is acceptable to
+mix users and groups on the same command line, as well as names and
+IDs. Precede the GID of each group with a hyphen to indicate that it is
+negative.
+
+A value of 0 (zero) lists group entries for groups whose owners no longer
+have entries in the Protection Database.
+
+=item B<-cell> <I<cell name>>
+
+Names the cell in which to run the command. For more details, see
+L<pts(1)>.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity anonymous to the issuer. For more
+details, see L<pts(1)>.
+
+=item B<-force>
+
+Enables the command to continue executing as far as possible when errors
+or other problems occur, rather than halting execution at the first error.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+The first line of the output indicates the name and AFS UID or AFS GID of
+each user or group for which ownership information is requested, in the
+following format:
+
+ Groups owned by <name> (id: <ID>) are:
+
+A list of groups follows. The list does not include groups owned by groups
+that the user or group owns, or to which the user or group belongs. If the
+user or group does not own any groups, only the header line appears.
+
+The following error message appears if the issuer is not privileged to
+view ownership information. By default, for both user and group entries
+the second privacy flag is the hyphen, which denies permission to anyone
+other than the user (for a user entry) and the members of the
+system:administrators group.
+
+ pts: Permission denied so failed to get owner list for <name> (id: <ID>)
+
+=head1 EXAMPLES
+
+The following example lists the groups owned by user terry and shows that
+the group C<terry:friends> does not own any groups:
+
+ % pts listowned terry terry:friends
+ Groups owned by terry (id: 1045) are:
+ terry:friends
+ terry:project1
+ terry:project2
+ Groups owned by terry:friends (id: -673) are:
+
+=head1 PRIVILEGE REQUIRED
+
+The required privilege depends on the setting of the second privacy flag
+in the Protection Database entry of each user or group indicated by the
+B<-nameorid> argument (use the B<pts examine> command to display the
+flags):
+
+=over 4
+
+=item *
+
+If it is the hyphen and the B<-nameorid> argument specifies a group, only
+the members of the system:administrators group and the owner of a group
+can list the groups it owns.
+
+=item *
+
+If it is the hyphen and the B<-nameorid> argument specifies a user, only
+the members of the system:administrators group and the associated user can
+list the groups he or she owns.
+
+=item *
+
+If it is uppercase letter C<O>, anyone who can access the cell's database
+server machines can list the groups owned by this user or group.
+
+=back
+
+=head1 SEE ALSO
+
+L<pts(1)>,
+L<pts_chown(1)>,
+L<pts_examine(1)>,
+L<pts_setfields(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
+
+pts membership - Displays the membership list for a user or group
+
+=head1 SYNOPSIS
+
+B<pts membership> B<-nameorid> <I<user or group name or id>>+
+ [B<-cell> <I<cell name>>] [B<-noauth>] [B<-force>] [B<-help>]
+
+B<pts m> B<-na> <I<user or group name or id>>+ [B<-c> <I<cell name>>]
+ [B<-no>] [B<-f>] [B<-h>]
+
+B<pts groups> B<-na> <I<user or group name or id>>+ [-c <I<cell name>>]
+ [B<-no>] [B<-f>] [B<-h>]
+
+B<pts g> B<-na> <I<user or group name or id>>+ [B<-c> <I<cell name>>]
+ [B<-no>] [B<-f>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<pts membership> command lists the groups to which each user or
+machine specified by the B<-nameorid> argument belongs, or lists the users
+and machines that belong to each group specified by the B<-nameorid>
+argument.
+
+It is not possible to list the members of the system:anyuser or
+system:authuser groups, and they do not appear in the list of groups to
+which a user belongs.
+
+To add users or machine to groups, use the pts adduser command; to remove
+them, use the B<pts removeuser> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-nameorid> <I<user or group name or id>>+
+
+Specifies the name or AFS UID of each user entry, the IP address (complete
+or wildcard-style) or AFS UID of each machine entry, or the name or AFS
+GID of each group, for which to list group membership. It is acceptable to
+mix users, machines, and groups on the same command line, as well as names
+and IDs. Precede the GID of each group with a hyphen to indicate that it
+is negative.
+
+=item B<-cell> <I<cell name>>
+
+Names the cell in which to run the command. For more details, see
+L<pts(1)>.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity anonymous to the issuer. For more
+details, see L<pts(1)>.
+
+=item B<-force>
+
+Enables the command to continue executing as far as possible when errors
+or other problems occur, rather than halting execution at the first error.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+For each user and machine, the output begins with the following header
+line, followed by a list of the groups to which the user or machine
+belongs:
+
+ Groups <name> (id: <AFS UID>) is a member of:
+
+For each group, the output begins with the following header line, followed
+by a list of the users and machines who belong to the group:
+
+ Members of <group_name> (id: <AFS GID>) are:
+
+=head1 EXAMPLES
+
+The following example lists the groups to which the user C<pat> belongs
+and the members of the group C<smith:friends>. Note that third privacy
+flag for the C<pat> entry was changed from the default hyphen to enable a
+non-administrative user to obtain this listing.
+
+ % pts membership pat smith:friends
+ Groups pat (id: 1144) is a member of:
+ smith:friends
+ staff
+ johnson:project-team
+ Members of smith:friends (id: -562) are:
+ pat
+ terry
+ jones
+ richard
+ thompson
+
+=head1 PRIVILEGE REQUIRED
+
+The required privilege depends on the setting of the third privacy flag in
+the Protection Database entry of each user or group indicated by the
+B<-nameorid> argument (use the B<pts examine> command to display the
+flags):
+
+=over 4
+
+=item *
+
+If it is the hyphen and the B<-nameorid> argument specifies a user, only
+the associated user and members of the system:administrators group can
+list the groups to which the user belongs.
+
+=item *
+
+If it is the hyphen and the B<-nameorid> argument specifies a machine,
+only the members of the system:administrators group can list the groups to
+which the machine belongs.
+
+=item *
+
+If it is the hyphen and the B<-nameorid> argument specifies a group, only
+the owner of the group and members of the system:administrators group can
+list the members of the group.
+
+=item *
+
+If it is lowercase C<m> and the B<-nameorid> argument specifies a user or
+machine entry, the meaning is equivalent to the hyphen.
+
+=item *
+
+If it is lowercase C<m> and the B<-nameorid> argument specifies a group,
+members of the group can also list the other members.
+
+=item *
+
+If it is uppercase C<M>, anyone who can access the cell's database server
+machines can list group memberships.
+
+=back
+
+=head1 SEE ALSO
+
+L<pts(1)>,
+L<pts_adduser(1)>,
+L<pts_examine(1)>,
+L<pts_removeuser(1)>,
+L<pts_setfields(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
+
+pts removeuser - Removes a user from a Protection Database group
+
+=head1 SYNOPSIS
+
+B<pts removeuser> B<-user> <I<user name>>+ B<-group> <I<group name>>+
+ [B<-cell> <I<cell name>>] [B<-noauth>] [B<-force>] [B<-help>]
+
+B<pts rem> B<-u> <I<user name>>+ B<-g> <I<group name>>+
+ [B<-c> <I<cell name>>] [B<-n>] [B<-f>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<pts removeuser> command removes each user or machine named by the
+B<-user> argument from each group named by the B<-group> argument.
+
+To add users to a group, use the B<pts adduser> command. To list group
+membership, use the B<pts membership> command. To remove users from a
+group and delete the group's entry completely in a single step, use the
+B<pts delete> command.
+
+=head1 CAUTIONS
+
+AFS compiles each user's group membership as he or she authenticates. Any
+users who have valid tokens when they are removed from a group retain the
+privileges extended to that group's members until they discard their
+tokens or reauthenticate.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-name> <I<user name>>+
+
+Specifies the name of each user entry or the IP address (complete or
+wildcard-style) of each machine entry to remove.
+
+=item B<-group> <I<group name>>+
+
+Names each group from which to remove members.
+
+=item B<-cell> <I<cell name>>
+
+Names the cell in which to run the command. For more details, see
+L<pts(1)>.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity anonymous to the issuer. For more
+details, see L<pts(1)>.
+
+=item B<-force>
+
+Enables the command to continue executing as far as possible when errors
+or other problems occur, rather than halting execution at the first error.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following example removes user smith from the groups C<staff> and
+C<staff:finance>. Note that no switch names are necessary because only a
+single instance is provided for the first argument (the username).
+
+ % pts removeuser smith staff staff:finance
+
+The following example removes three machine entries, which represent all
+machines in the ABC Corporation network, from the group C<bin-prot>:
+
+ % pts removeuser -user 138.255.0.0 192.12.105.0 192.12.106.0 -group bin-prot
+
+=head1 PRIVILEGE REQUIRED
+
+The required privilege depends on the setting of the fifth privacy flag in
+the Protection Database for the group named by the B<-group> argument (use
+the B<pts examine> command to display the flags):
+
+=over 4
+
+=item *
+
+If it is the hyphen, only the group's owner and members of the
+system:administrators group can remove members.
+
+=item *
+
+If it is lowercase C<r>, members of the group can also remove other
+members.
+
+=back
+
+(It is not possible to set the fifth flag to uppercase C<R>.)
+
+=head1 SEE ALSO
+
+L<pts(1)>,
+L<pts_adduser(1)>,
+L<pts_examine(1)>,
+L<pts_membership(1)>,
+L<pts_setfields(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
+
+pts rename - Changes the name of a Protection Database entry
+
+=head1 SYNOPSIS
+
+B<pts rename> B<-oldname> <I<old name>> B<-newname> <I<new name>>
+ [B<-cell> <I<cell name>>] [B<-noauth>] [B<-force>] [B<-help>]
+
+B<pts ren> B<-o> <I<old name>> B<-ne> <I<new name>> [B<-c> <I<cell name>>]
+ [B<-no>] [B<-f>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<pts rename> command changes the name of the user, machine, or group
+entry specified by the B<-oldname> argument to the name specified by the
+B<-newname> argument. It is not possible to change a user or machine
+entry's name to look like a regular group entry's name (have a colon in
+it).
+
+Members of the system:administrators group can change a regular group name
+into a prefix-less name and vice versa. When changing a prefix-less group
+name into a regular group name or a regular group name to another regular
+group name, the owner field of the new name (the part before the colon)
+must correctly reflect the group's owner.
+
+Changing a regular group's owner with the B<pts chown> command
+automatically changes the owner field (the part before the colon) of the
+group's name, but does not change the owner field of any groups owned by
+the group. Use this command to rename those groups to a form that
+accurately reflects their ownership.
+
+=head1 CAUTIONS
+
+By convention, many aspects of an AFS user account have the same name as
+the user's Protection Database entry, including the Authentication
+Database entry, volume, and mount point. When using this command to change
+a user name, also change the names of all related entities to maintain
+consistency. For instructions, see the chapter on user accounts in the
+I<IBM AFS Administration Guide>.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-oldname> <I<old name>>
+
+Specifies the current full name of the entry.
+
+=item B<-newname> <I<new name>>
+
+Specifies the new full name for the entry. For regular groups, the owner
+field (the part before the colon) of the new name must reflect the actual
+ownership of the group.
+
+=item B<-cell> <I<cell name>>
+
+Names the cell in which to run the command. For more details, see
+L<pts(1)>.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity anonymous to the issuer. For more
+details, see L<pts(1)>.
+
+=item B<-force>
+
+Enables the command to continue executing as far as possible when errors
+or other problems occur, rather than halting execution at the first error.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following example changes the name of the group staff, owned by the
+privileged user C<admin>, to C<admin:staff>:
+
+ % pts rename -oldname staff -newname admin:staff
+
+The following example changes the name of the group C<admin:finance> to
+the group C<finance>. The issuer must belong to the system:administrators
+group.
+
+ % pts rename -oldname admin:finance -newname finance
+
+=head1 PRIVILEGE REQUIRED
+
+To change a regular group name to a prefix-less name or vice versa, or to
+change a user or machine entry's name, the issuer must belong to the
+system:administrators group.
+
+To change a group name to a new name of the same type (regular or
+prefix-less), the issuer must own the group or belong to the
+system:administrators group.
+
+=head1 SEE ALSO
+
+L<pts(1)>,
+L<pts_chown(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
+
+pts setfields - Sets privacy flags or quota for a Protection Database entry
+
+=head1 SYNOPSIS
+
+B<pts setfields> B<-nameorid> <I<user or group name or id>>+
+ [B<-access> <I<set privacy flags>>]
+ [B<-groupquota> <I<set limit on group creation>>]
+ [B<-cell> <I<cell name>>] [B<-noauth>] [B<-force>] [B<-help>]
+
+B<pts setf> B<-na> <I<user or group name or id>>+
+ [B<-a> <I<set privacy flags>>]
+ [B<-g> <I<set limit on group creation>>] [B<-c> <I<cell name>>]
+ [B<-no>] [B<-f>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<pts setfields> command sets the group-creation quota, the privacy
+flags, or both, associated with each user, machine, or group entry
+specified by the B<-nameorid> argument.
+
+To examine the current quota and privacy flags, use the B<pts examine>
+command.
+
+=head1 CAUTIONS
+
+Changing a machine or group's group-creation quota is allowed, but not
+recommended. The concept is meaningless for machines and groups, because
+it is impossible to authenticate as a group or machine.
+
+Similarly, some privacy flag settings do not have a sensible
+interpretation. L<OPTIONS> specifies the appropriate settings.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-nameorid> <I<user or group name or id>>+
+
+Specifies the name or AFS UID of each user, the IP address (complete or
+wildcard-style) of each machine, or the name or AFS GID of each machine
+for which to set privacy flags or group-creation quota. It is acceptable
+to mix users, machines, and groups on the same command line, as well as
+names (IP addresses for machines) and IDs. Precede the GID of each group
+with a hyphen to indicate that it is negative.
+
+=item B<-access> <I<privacy flags>>
+
+Specifies the privacy flags to apply to each entry. Provide a string of
+five characters, one for each of the permissions. If this option is
+omitted, the current setting remains unchanged.
+
+Set each flag to achieve the desired combination of permissions. If the
+following list does not mention a certain setting, it is not
+acceptable. For further discussion of the privacy flags, see
+L<pts_examine(1)>.
+
+=over 4
+
+=item *
+
+The first flag determines who can use the B<pts examine> command to
+display information from a user, machine or group's Protection Database
+entry.
+
+=over 4
+
+=item *
+
+Set it to lowercase C<s> to permit the members of the
+system:administrators group to display a user, machine, or group entry,
+and the associated user to display a user entry.
+
+=item *
+
+Set it to uppercase C<S> to permit anyone who can access the cell's
+database server machines to display a user, machine, or group entry.
+
+=back
+
+=item *
+
+The second flag determines who can use the B<pts listowned> command to
+list the groups that a user or group owns.
+
+=over 4
+
+=item *
+
+Set it to the hyphen (C<->) to permit the members of the
+system:administrators group and a user to list the groups he or she owns,
+or to permit the members of the system:administrators group and a group's
+owner to list the groups that a group owns.
+
+=item *
+
+Set it to uppercase letter C<O> to permit anyone who can access the cell's
+database server machines to list the groups owned by a machine or group
+entry.
+
+=back
+
+=item *
+
+The third flag determines who can use the B<pts membership> command to
+list the groups to which a user or machine belongs, or the users and
+machines that belong to a group.
+
+=over 4
+
+=item *
+
+Set it to the hyphen (C<->) to permit the members of the
+system:administrators group and a user to list the groups he or she
+belongs to, to permit the members of the B<system:administrators> group to
+list the groups a machine belongs to, or to permit the members of the
+system:administrators group and a group's owner to list the users and
+machines that belong to it.
+
+=item *
+
+Set it to lowercase C<m> to permit members of a group to list the other
+members. (For user and machine entries, this setting is equivalent to the
+hyphen.)
+
+=item *
+
+Set it to uppercase C<M> to permit anyone who can access the cell's
+database server machines to list membership information for a user,
+machine or group.
+
+=back
+
+=item *
+
+The fourth flag determines who can use the B<pts adduser> command to add
+users and machines as members of a group. This flag has no sensible
+interpretation for user and machine entries, but must be set nonetheless,
+preferably to the hyphen.
+
+=over 4
+
+=item *
+
+Set it to the hyphen (C<->) to permit the members of the
+system:administrators group and the owner of the group to add members.
+
+=item *
+
+Set it to lowercase C<a> to permit members of a group to add other
+members.
+
+=item *
+
+Set it to uppercase C<A> to permit anyone who can access the cell's
+database server machines to add members to a group.
+
+=back
+
+=item *
+
+The fifth flag determines who can use the B<pts removeuser> command to
+remove users and machines from membership in a group. This flag has no
+sensible interpretation for user and machine entries, but must be set
+nonetheless, preferably to the hyphen.
+
+=over 4
+
+=item *
+
+Set it to the hyphen (C<->) to permit the members of the
+system:administrators group and the owner of the group to remove members.
+
+=item *
+
+Set it to lowercase C<r> to permit members of a group to remove other
+members.
+
+=back
+
+=back
+
+=item B<-groupquota> <I<group creation quota>>
+
+Specifies the number of additional groups a user can create (it does not
+matter how many he or she has created already). Do not include this
+argument for a group or machine entry.
+
+=item B<-cell> <I<cell name>>
+
+Names the cell in which to run the command. For more details, see
+L<pts(1)>.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity anonymous to the issuer. For more
+details, see L<pts(1)>.
+
+=item B<-force>
+
+Enables the command to continue executing as far as possible when errors
+or other problems occur, rather than halting execution at the first error.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following example changes the privacy flags on the group C<operators>,
+retaining the default values of the first, second and third flags, but
+setting the fourth and fifth flags to enable the group's members to add
+and remove other members.
+
+ % pts setfields -nameorid operators -access S-Mar
+
+The following example changes the privacy flags and sets group quota on
+the user entry C<admin>. It retains the default values of the first,
+fourth, and fifth flags, but sets the second and third flags, to enable
+anyone to list the groups that C<admin> owns and belongs to. Users
+authenticated as C<admin> can create an additional 50 groups.
+
+ % pts setfields -nameorid admin -access SOM-- -groupquota 50
+
+=head1 PRIVILEGE REQUIRED
+
+To edit group entries or set the privacy flags on any type of entry, the
+issuer must own the entry or belong to the system:administrators group. To
+set group-creation quota on a user entry, the issuer must belong to the
+system:administrators group.
+
+=head1 SEE ALSO
+
+L<pts(1)>,
+L<pts_adduser(1)>,
+L<pts_examine(1)>,
+L<pts_listowned(1)>,
+L<pts_membership(1)>,
+L<pts_removeuser(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
+
+pts setmax - Sets the value of the max group id or max user id counter
+
+=head1 SYNOPSIS
+
+B<pts setmax> [B<-group> <I<group max>>] [B<-user> <I<user max>>]
+ [B<-cell> <I<cell name>>] [B<-noauth>] [B<-force>] [B<-help>]
+
+B<pts setm> [B<-g> I<group max>>] [B<-u> <I<user max>>]
+ [B<-c> <I<cell name>>] [B<-n>] [B<-f>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<pts setmax> command sets the value of one or both counters that
+track the IDs the Protection Server allocates to new users, machines, or
+groups: the C<max user id> counter for the AFS user IDs (AFS UIDs)
+assigned to users and machines, and the C<max group id> counter for the
+AFS group IDs (AFS GIDs) assigned to groups.
+
+Use the B<pts listmax> command to display the current value of both
+counters.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-group> <I<group max>>
+
+Sets the C<max group id> counter. Precede the value with a hyphen to
+indicate that it is negative. When an administrator next uses the B<pts
+creategroup> command to create a group entry and does not include that
+command's B<-id> argument, the Protection Server assigns the group an AFS
+GID one less (more negative) than this value.
+
+=item B<-user> <I<user max>>
+
+Sets the C<max user id> counter. When an administrator next uses the B<pts
+createuser> command to create a user or machine entry and does not include
+that command's B<-id> argument, the Protection Server assigns the group an
+AFS UID one greater than this value.
+
+=item B<-cell> <I<cell name>>
+
+Names the cell in which to run the command. For more details, see
+L<pts(1)>.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity anonymous to the issuer. For more
+details, see L<pts(1)>.
+
+=item B<-force>
+
+Enables the command to continue executing as far as possible when errors
+or other problems occur, rather than halting execution at the first error.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command sets the C<max group id> counter to -500 and the
+C<max user id> counter to 1000.
+
+ % pts setmax -group -500 -user 1000
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must belong to the system:administrators group.
+
+=head1 SEE ALSO
+
+L<pts(1)>,
+L<pts_creategroup(1)>,
+L<pts_createuser(1)>,
+L<pts_listmax(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
+
+rxdebug - Provides debugging trace of Rx activity
+
+=head1 SYNOPSIS
+
+B<rxdebug> B<-servers> <I<server machine>> [B<-port> <I<IP port>>]
+ [B<-nodally>] [B<-allconnections>] [B<-rxstats>] [B<-onlyserver>]
+ [B<-onlyclient>] [B<-onlyport> <I<show only port>>]
+ [B<-onlyhost> <I<show only host>>]
+ [B<-onlyauth> <I<show only auth level>>] [B<-version>]
+ [B<-noconns>] [B<-peers>] [B<-help>]
+
+B<rxdebug> B<-s> <I<server machine>> [B<-po> <I<IP port>>] [B<-nod>]
+ [B<-a>] [B<-r>] [B<-onlys>] [B<-onlyc>] [B<-onlyp> <I<show only port>>]
+ [B<-onlyh> <I<show only host>>] [-onlya <I<show only auth level>>]
+ [B<-v>] [B<-noc>] [B<-pe>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<rxdebug> command provides a trace of Rx activity for the server or
+client machine named by the B<-servers> argument. Rx is AFS's proprietary
+remote procedure call (RPC) protocol, so this command enables the issuer
+to check the status of communication between the Cache Manager or an AFS
+server process (as specified with the B<-port> argument) on the machine
+and one or more processes on other machines.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-servers> <I<server machine>>
+
+Specifies the machine that is running the Cache Manager or server process
+for which to trace Rx activity. Provide the machine's IP address in dotted
+decimal format, its fully qualified host name (for example,
+C<fs1.abc.com>), or the shortest 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 resolution service (such as the
+Domain Name Service or a local host table) at the time the command is
+issued.
+
+=item B<-port> <I<IP port>>
+
+Specifies the process for which to trace Rx activity. Omit this argument
+to specify the File Server (B<fileserver> process), or provide one of the
+following values:
+
+=over 4
+
+=item C<7000> for the File Server (B<fileserver> process)
+
+=item C<7001> for the Cache Manager (specifically, its callback interface)
+
+=item C<7002> for the Protection Server (B<ptserver> process)
+
+=item C<7003> for the Volume Location (VL) Server (B<vlserver> process)
+
+=item C<7004> for the Authentication Server (B<kaserver> process)
+
+=item C<7005> for the Volume Server (B<volserver> process)
+
+=item C<7007> for the BOS Server (B<bosserver> process)
+
+=item C<7008> for the Update Server (B<upserver> process)
+
+=item C<7009> for the NFS/AFS Translator's B<rmtsysd> daemon
+
+=item C<7021> for the Backup Server (B<buserver> process)
+
+=back
+
+Finally, specify C<7025> through C<65535> for the Backup Tape Coordinator
+(B<butc> process) that has the port offset number derived by subtracting
+7025 from this value.
+
+=item B<-nodally>
+
+Produces output only for connections that are not in dally mode.
+
+=item B<-allconnections>
+
+Produces output for all connections, even inactive ones. By default, the
+output includes information only for connections that are active or in
+dally mode when the B<rxdebug> command is issued.
+
+=item B<-rxstats>
+
+Produces detailed statistics about Rx history and performance (for
+example, counts of the number of packets of various types the process has
+read and sent, calculations of average and minimum roundtrip time, and so
+on).
+
+=item B<-onlyserver>
+
+Produces output only for connections in which the process designated by
+the B<-port> argument is acting as the server.
+
+=item B<-onlyclient>
+
+Produces output only for connections in which the process designated by
+the B<-port> argument is acting as the client.
+
+=item B<-onlyport> <I<port>>
+
+Produces output only for connections between the process designated by the
+B<-port> argument and the specified port on any another machine. Use the
+same port identifiers as for the B<-port> argument.
+
+=item B<-onlyhost> <I<host>>
+
+Produces output only for connections between the process designated by the
+B<-port> argument and any process on the specified machine. To identify
+the machine, use the same notation as for the B<-servers> argument.
+
+=item B<-onlyauth>
+
+Produces output only for connections that are using the specified
+authentication level. Provide one of the following values:
+
+=over 4
+
+=item auth
+
+Cconnections at authentication level rxkad_auth
+
+=item clear
+
+Connections at authentication level rxkad_clear
+
+=item crypt
+
+Connections at authentication level rxkad_crypt
+
+=item none
+
+Unauthenticated connections (equivalents are C<null>, C<noauth>, and
+C<unauth>)
+
+=back
+
+=item B<-version>
+
+Reports the AFS build level of the binary file for the process designated
+by the B<-port> argument (or of the kernel extensions file for port 7001,
+the Cache Manager's callback interface). Any other options combined with
+this one are ignored.
+
+=item B<-noconns>
+
+Produces only the standard statistics that begin the output produced by
+every option (other than B<-version>), without reporting on any
+connections. Any other options combined with this one are ignored.
+
+=item B<-peers>
+
+Outputs information from the I<peer structure> maintained for each port on
+another machine to which the process designated by the B<-port> argument
+has a connection. There is information about roundtrip time and numbers of
+packets sent and received, for example.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+If any options other than B<-version> or B<-help> are provided, the output
+written to the standard output stream begins with basic statistics about
+packet usage and availability, how many calls are waiting for a thread,
+how many threads are free, and so on (this is the only information
+provided by the B<-noconns> flag). Adding other options produces
+additional information as described in L<OPTIONS>. The output is intended
+for debugging purposes and is meaningful to someone familiar with the
+implementation of Rx.
+
+=head1 PRIVILEGE REQUIRED
+
+None.
+
+=head1 SEE ALSO
+
+L<afsd(8)>,
+L<bosserver(8)>,
+L<buserver(8)>,
+L<butc(8)>,
+L<fileserver(8)>,
+L<kaserver(8)>,
+L<ptserver(8)>,
+L<upclient(8)>,
+L<upserver(8)>,
+L<vlserver(8)>,
+L<volserver(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+rxgen - Stub generator for the Rx remote procedure call package
+
+=head1 SYNOPSIS
+
+B<rxgen> [B<-h> | B<-c> | B<-C> | B<-S> | B<-r>] [B<-dkpR>]
+ [B<-I> I<dir>] [B<-P> I<prefix>] [B<-o> I<outfile>] [I<infile>]
+
+B<rxgen> B<-s> I<transport> [B<-o> I<outfile>] [I<infile>]
+
+B<rxgen> B<-l> [B<-o> I<outfile>] [I<infile>]
+
+B<rxgen> B<-m> [B<-o> I<outfile>] [I<infile>]
+
+=head1 DESCRIPTION
+
+B<rxgen> is a tool that generates C code to implement the Rx RPC protocol;
+it takes as input a description of an application interface similar to C
+and produces a number of server and/or client stub routines to be linked
+with RPC-based programs. These stubs allow programs to invoke remote
+procedures through local procedure calls. B<rxgen> is an extension of
+Sun's B<rpcgen> (version 3.9) and retains full B<rpcgen> functionality (at
+least as of that version). Please refer to rpcgen(1) for more details on
+the Sun's RPC specific flags, and to the RPC programming guide regarding
+the RPC language along with useful examples.
+
+=head1 OPTIONS
+
+B<rxgen> operates in several different modes. The generated output files
+can be produced individually (using one of B<-h>, B<-c>, B<-C>, or B<-S>)
+or collectively. All output files are created when the default is used
+(i.e., no options), or the output is limited to the server stubs (B<-C>
+and B<-S>) when the B<-r> flag is used. The following describes the types
+of generated output files (for simplicity, I<filename> refers to the main
+output filename):
+
+=over 4
+
+=item B<-h>
+
+Generate C data definitions (a header file) from standard RPCL definitions
+(default extension: I<filename>.h).
+
+=item B<-c>
+
+Compile the XDR routines required to serialize the protocol described by
+RPCL. Generate XDR routines for all declarations (default extension:
+I<filename>.xdr.c).
+
+=item B<-C>
+
+Generate all the client-side stub routines (default extension:
+I<filename>.cs.c). Calling a routine in this file will cause the
+arguments to be packed up and sent via Rx (or R).
+
+=item B<-S>
+
+Generate all the server-side stub routines (default extension:
+I<filename>.ss.c). Arguments are unpacked, and the corresponding server
+routine is called.
+
+=item B<-r>
+
+Generate the two default extension files produced by the B<-C> and B<-S>
+options.
+
+=back
+
+The following options can be used on any combination of B<rxgen> calls:
+
+=over 4
+
+=item B<-R>
+
+Generate code for the older \R protocol, as opposed to Rx, which is the
+default.
+
+=item B<-k>
+
+Must be specified when the generated code is intended to be used by the
+kernel; special "includes" and other specifics are produced when the
+target output is for the kernel.
+
+=item B<-p>
+
+Package combination flag: when multiple packages are included within a
+single specification file, a single Execute Request routine will be used
+for all of them as a result of this flag. The default is to generate
+individual Execute Request stubs for each package.
+
+=item B<-I> I<dir>
+
+Similar to the B<-I> flag in the C compiler (B<cc>). This flag is passed
+to the pre-processor (B<cpp>) so that directory I<dir> is searched before
+the standard lookup list for #include files. As expected, multiple B<-I>
+flags can be used simultaneously.
+
+=item B<-P> I<prefix>
+
+The I<prefix> string following this switch is prepended to all generated
+output files; useful when multiple runs want to produce different versions
+of the same interface (say, kernel and non-kernel versions).
+
+=item B<-d>
+
+Debugging mode; only needed when B<rxgen> is to be debugged (say, via
+B<dbx>).
+
+=item B<-o> I<outfile>
+
+Specify the name of the output file. If none is specified, the standard
+output is used (B<-c>, B<-h>, B<-C>, and B<-S> modes only). Note that if
+an output file is specified in a multi-output file option (such as the
+default, or with option B<-r>), then the I<outfile> replaces the name
+generated by default (which is based on the configuration's main file
+name).
+
+=back
+
+The B<-s>, B<-l>, and B<-m> options are present only for B<rpcgen>
+support. See rpcgen(1) for information on their use.
+
+=head1 B<rxgen> SYNTAX SUMMARY
+
+ Specification file:
+
+ <Package description option> |
+ <Prefix description option> |
+ <StartingOpcode description option> |
+ <SplitPrefix description option> |
+ <Procedure description option> |
+ <RPCL language description option>
+
+ <Package description option>:
+
+ "package" <Package_ident>
+
+ <Prefix description option>:
+
+ "prefix" <Prefix_ident>
+
+ <StartingOpcode description option>:
+
+ "startingopcode" <constant>
+
+ <SplitPrefix description option>:
+
+ "splitprefix" <split options> ";"
+
+ <Split options>:
+
+ "IN =" <Start_prefix_ident> "|"
+ "OUT =" <End_prefix_ident> "|"
+ <Split options>
+
+ <Procedure description option>:
+
+ ["proc"] [<Procedure_ident>] [<ServerStub_ident>]
+ <Argument list> ["split" | "multi"]
+ ["=" <Opcode_ident>] ";"
+
+ <Argument list>:
+
+ "(" <Argument definition> <Comma_joined argument> ")"
+
+ <Argument definition>:
+
+ <Direction option> <Standard RPCL type decl> <Arg_ident>
+ ["<" <Max_size> ">" | "[" <Max_size> "]"] | NULL
+
+ <Comma_joined argument>:
+
+ "," <Argument definition> | NULL
+
+ <Direction option>:
+
+ "IN" | "OUT" | "INOUT" | NULL
+
+ <Max_size>:
+
+ <constant> | NULL
+
+ <Package_ident>:
+ <Prefix_ident>:
+ <String_ident>:
+ <Start_prefix_ident>:
+ <End_prefix_ident>:
+ <Procedure_ident>:
+ <ServerStub_ident>:
+ <Arg_ident>:
+ <Opcode_ident>:
+
+ <identifier>
+
+ <RPCL language description option>:
+ <Standard RPCL type decl>:
+
+ Sun's RPCL language syntax (see rpcgen(1))
+
+=head1 B<rxgen> COMMANDS
+
+=head2 Comments and Preprocessing
+
+The input interface may contain preprocessor directives which are passed
+through the C preprocessor (i.e. C<cpp>). Since the preprocessor runs on
+all input files before they are actually interpreted by B<rxgen>, all
+B<cpp> directives (#include, #ifdefs, #defines, etc.) are legal and
+welcomed within an B<rxgen> input file. Of course, none of these
+preprocessor directives will be included in any of the generated files.
+To facilitate distinctions between the different types of output files,
+B<rxgen> defines certain special B<cpp> symbols for use by the B<rxgen>
+programmer. These are RPC_HDR (defined when compiling into header,
+I<filename>.h, files), RPC_XDR (defined when compiling into xdr,
+I<filename>.xdr.c, files), RPC_CLIENT (defined when compiling into client
+stubs, I<filename>.cs.c, files), and RPC_SERVER (defined when compiling
+into server stubs, I<filename>.ss.c, files).
+
+In addition, B<rxgen> does a little preprocessing of its own. Any line
+beginning with C<%> is passed directly into the output file, uninterpreted
+by B<rxgen>. For a more heavy en masse dumping of uninterpreted code, it
+would be adviced to include all such code in an C<#include> file and pass
+it in preceded by C<%>. The input interface may also contain any C-style
+comments which are, of course, ignored. Interpretation is token-based,
+thus special line-orientation of separate statements is not necessary.
+B<rxgen> also provides a quite rich and helpful set of error reports,
+identifying them by exact line location and error type. Also, B<rxgen>
+will automatically generate #include lines for standard include files,
+such as F<rx/xdr.h> and F<rx/rx.h>, along with the generated header file
+from this interface.
+
+=head2 Prefixing stub procedures
+
+The I<package> statement tells B<rxgen> the name of the interface package.
+It is used for prefixing the naming of all generated stub routines and the
+execute request procedure. For example:
+
+ package AFS_
+
+causes the execute request procedure to be named AFS_ExecuteRequest
+(Warning: in the older version an additional C<_> was appended after the
+package name to the ExecuteRequest name; thus make sure you don't have an
+ExecuteRequest interface routine) and a given stub routine, say Fetch, to
+be actually named AFS_Fetch. Multiple package statements (current maximum
+size is 10) per configuration are permitted and are useful when multiple
+sets of interfaces are implemented (see the example at the end). Note
+that in such cases, use of the B<-p> flag results in the generation of
+just one ExecuteRequest procedure which recognizes the multiple interfaces
+and whose name is prefixed by the first package statement. In the default
+case, independent ExecuteRequest procedures will be created for each
+packaged group of remote procedure calls.
+
+The I<prefix> statement supplies a name to prepend to all calls to remote
+procedure names in the ExecuteRequest stub routine. It is useful when the
+server makes RPC calls to other servers (say, for debugging purposes).
+For example:
+
+ prefix S
+
+causes the name C<S> to be prepended to the name of all routines called
+from the server stubs. The server can then call the original name and get
+the client stubs.
+
+=head2 B<rxgen> procedure declaration
+
+The I<proc> statement is the most common (and meaningful) in the B<rxgen>
+interface. Its syntax description is:
+
+ [proc] [<proc_name>] [<server_stub>] (<arg>, ..., <arg>)
+ [split | multi] [= <opcode>] ;
+
+where:
+
+=over 2
+
+=item *
+
+C<proc> is an optional prefix of the procedure statement. This is just a
+stylistic item and not a required procedure delimiter.
+
+=item *
+
+<proc_name> is the name of the procedure. Note that even the name of the
+procedure is optional. This only makes sense when the name of the given
+procedure is identical to the name of the last I<package> statement (i.e.,
+C<package RCallBack> and the declaration of the C<RCallBack> procedure).
+
+=item *
+
+<server_stub>, if present, causes the ExecuteRequest procedure to call
+that stub instead of the automatically generated stub when a call with
+that opcode is decoded.
+
+=item *
+
+<opcode> is a constant or symbol that is the opcode for that procedure.
+One might use the preprocessor features (i.e., #define), the I<const>
+RPC-language feature, or the old good constants as opcodes. Some further
+evaluation/processing of opcodes is done. Particularly, checks for
+duplicate and non-existent opcodes are performed, along with checks for
+"holes" (i.e., gaps in consecutive opcodes) in the opcode sequences. For
+example, we use the fact that when "holes" in opcodes exist, the
+ExecuteRequest procedure uses the I<case> statement rather than the faster
+(and smaller, codewise) indexed array method.
+
+Also, B<rxgen> defines (i.e., appends to the header file) three valuable
+macros for each package group: <package-name>LOWEST_OPCODE,
+<package-name>HIGHEST_OPCODE, and <package-name>NUMBER_OPCODES. These may
+be useful to the B<rxgen> programmer. Also, notice that the I<opcode>
+statement is an optional feature, and can be omitted. In such cases,
+automatic opcode numbers are generated sequentially, starting from 0.
+
+One can change the initial opcode number by using the I<startingopcode>
+(for lack of a better name) B<rxgen> command. Its syntax is:
+
+ startingopcode <constant>
+
+where <constant> must be reasonable! Note that one can not mix
+procedures, some with opcodes and some without, nor allow opcodes after
+the specification of the I<startingopcode> statement. B<rxgen> will
+complain in all such cases.
+
+=item *
+
+The I<argument> entry represents a given parameter of the procedure. Its
+syntax is:
+
+ [IN | INOUT | OUT | <null>] <type_decl> <arg_name>
+ [<max>|<>|[max]|[]]
+
+If the type is an indirect type (i.e., is followed by *), it is assumed
+that the pointer should be followed one level and the data pointed to is
+to be transmitted. This should normally be used for all structures/arrays
+and out parameters. A noticeable exception is when explicit
+array/structure maximum size is given; since no array-of-pointer
+declarations are allowed one should use typedefs to achieve the similar
+effect. The parameters could be input parameters (preceded by IN), output
+parameters (preceded by OUT), or input/output parameters (preceded by
+INOUT). If not specified, then the direction of the previous parameter in
+the procedure is used. (Note: the first parameter must be preceded by the
+directional primitive!)
+
+=item *
+
+C<split> is a hack to handle stub routines that do things such as file
+transfers or any other operation that has to exchange information (e.g.,
+length of a file) before the call returns its output parameters. Because
+of the particular handshake that is involved when doing remote file
+transfer, we currently break all such calls into two client-side stub
+routines. The first (with the default prefix of C<Begin>) is used to pass
+all IN and INOUT parameters to the server side. The second (with the
+default prefix of C<End>) is used to get back the INOUT and OUT parameters
+from the server. Between the two calls, the user is supposed to do the
+appropriate calls for the file transfer. For example, the following
+procedure declaration in package AFS_
+
+ Fetch (IN a, b,INOUT c, OUT d) split = FETCHOPCODE;
+
+will roughly generate the two independent client stub routines:
+
+ BeginAFS_Fetch (IN a, b, c)
+
+and
+
+ EndAFS_Fetch(OUT c, d)
+
+The I<splitprefix> statement is used to change the default prefix names
+used by the two client-side stub generated routines when dealing with file
+transfer-related procedure calls. For example:
+
+ splitprefix IN=Before_ OUT=After_
+
+will cause the naming of the two client stubs for a file transfer-related
+routine, say Fetch(), to be Before_AFS_Fetch() and After_AFS_Fetch(),
+respectively.
+
+=item *
+
+The C<multi> option is nearly identical to the C<split> feature described
+above. The only significant visible difference is that along with the two
+client stubs, the standard client stub is also generated. Since the
+intention is to handle the multi-Rx calls, we need the whole standard
+procedure stub in the cases where no multi-Rx call of the procedure is
+performed. A side effect of the C<multi> option is the generation of a
+special macro (i.e., C<< multi_<Procedure-name> >> which passes back as
+arguments the C<Begin> and C<End> stubs in the header output file. This
+macro is used directly by the Rx code when a multi-Rx call of this
+procedure is performed.
+
+=back
+
+=head2 OBSOLETE B<rxgen> FEATURES
+
+Although the following rxgen commands are still in effect, they will soon
+be removed since there are better alternatives. DO NOT USE THEM!
+
+The I<special> statement is a temporary hack used to handle certain
+inefficiencies of standard xdr routines to handle some user-customized
+declarations. In particular, this applies to a string pointer specified
+as part of a declaration. For example,
+
+ special struct BBS SeqBody;
+
+tells B<rxgen> that the entry C<SeqBody> in the user-defined BBS xdr
+routine is a string (note that more than one string can be "special" per
+structure -- multiple ones are separated by commas); it will thus allocate
+and de-allocate space properly in the server-generated stubs that contain
+this structure as an IN or INOUT parameter.
+
+A better alternative to I<special> is the I<customized> statement, which
+is simply the C<customized> token followed by the regular declaration of a
+struct based on the RPCL rules. In this case, the declaration will be
+included in the generated header file (B<-h> option) but no xdr routine
+will be generated for this structure -- the user will supply this. All
+pointer entries in this structure will be remembered so when the structure
+is used as an IN or INOUT in the server stub, no core leaks will occur.
+For example, consider
+
+ customized struct CBS {
+ long Seqlen;
+ char *SeqBody;
+ }
+
+The C<xdr_CBS> routine would be provided by the user where during the
+DECODE xdr opcode, appropriate space for the C<SeqBody> string is
+allocated. Similarly, that space is freed during the FREE xdr opcode.
+
+Note: Old style "Array parameter specifications" are not supported any
+more.
+
+=head1 EXAMPLES
+
+In case there are some requirements not available by the current RPC
+language, one can customize some XDR routines by leaving those data types
+undefined. For every data type that is undefined, it will be assumed that
+a routine exists with the name C<xdr_> prepended to it. A selected set of
+B<rxgen> features is presented below, but for a more comprehensive one
+(unions, complex examples, etc) please refer to the I<rpcgen Programming
+Guide> and I<eXternal Data Representation: Sun Technical Notes>.
+
+=head2 Typedefs
+
+The RPC typedef statement is identical to the C typedef (i.e. C<< typedef
+<declaration> >>). By default, most user declarations (i.e. structs,
+unions, etc) are automatically typedef'ed by B<rxgen>. Since it makes
+parsing simpler, its usage is recommended by B<rxgen> scripts.
+
+=head2 Strings
+
+The C C<char *> string convention is kind of ambiguous, since it is
+usually intended to mean a null-terminated string of characters, but it
+could also represent a pointer to a single character, a pointer to an
+array of characters, etc. In the RPC language, a null-terminated string
+is unambiguously called a "string". Examples,
+
+ string bigname<>;
+ string name<MAXNAMELEN>;
+ typedef string volname<MAXVOLNAME>;
+
+Notice that the maximum size of string can be arbitrary (like C<bigname>
+above) or, preferably, or specified in angle brackets (i.e. C<name> and
+C<volname> above). In practice, one should always use only bounded
+strings in interfaces. A sample calling proc using the declarations above
+would be:
+
+ GetEntryByName (IN volname name,
+ OUT struct vldbentry *entry) = VL_GETENTRYBYNAME;
+
+or, of course,
+
+ GetEntryByName (IN string volname<MAXVOLNAME>,
+ OUT struct vldbentry *entry) = VL_GETENTRYBYNAME;
+
+It is very important for the user to understand when the string parameters
+should be allocated and/or freed by the his/her client and/or server
+programs. A short analysis on string parameters handling follows (note
+that a similar method is used for the handling of variable length arrays
+as it will be shown later on):
+
+=over 2
+
+=item *
+
+In the client side: IN and INOUT string parameters are the programmer's
+responsibility and should be allocated (static or via malloc) before
+calling the rpc and freed (if malloc was used) after the rpc's return in
+the user's client program; of course, for INOUT parameters, the returned
+string can't be bigger than the malloced input string.
+
+OUT string parameters are automatically malloced (based on the length of
+the returned string and not the maxsize) by the B<rxgen> client stubs (in
+I<filename>.cs.c) and must be freed by the client program; admittedly,
+this could be somewhat confusing since the user needs to free something
+that he/she didn't allocate.}
+
+=item *
+
+In the server side: IN and INOUT string parameters are automatically
+malloced (based on the size of incoming strings) by the rxgen server stubs
+(in I<filename>.ss.c) before they are passed to the user's server
+procedure; that space is automatically freed just before the rxgen server
+stub returns; therefore the user need not do anything special for IN and
+INOUT string parameters.
+
+OUT string parameters must be malloced by the user's server procedure
+(i.e. null pointer is passed to it by the rxgen server stub) and it is
+automatically freed at the end of the B<rxgen> server stub. Like in the
+client side, the OUT parameters are somewhat unorthodox (i.e. the server
+routine must malloc a string without ever freeing it itself; this is done
+by the B<rxgen> server stub).
+
+Note that for INOUT and OUT string parameters, in both the client and
+server sides their arguments must be char of pointers (i.e. char **).
+
+=head2 Pointers
+
+Pointer declarations in RPC are also exactly as they are in C
+(i.e. C<struct single_vldbentry *vldblist;>). Of course, one can't send
+pointers over the network, but one can use XDR pointers for sending
+recursive data types such as lists and trees (an example of a linked list
+will be demonstrated shortly).
+
+=head2 Arrays
+
+Fixed arrays are just like standard C array declarations (i.e. C<struct
+UpdateEntry entries[20]>) without any side effect problems in
+B<rxgen>. Since variable-length arrays have no explicit syntax in C, the
+angle-brackets are used for it and the array declarations are actually
+compiled into "struct"s. For example, declarations such as:
+
+ const MAXBULKSIZE = 10000;
+ const MAXENTRIES = 100;
+ opaque bulk<MAXBULKSIZE>; /* At most 10000 items */
+ int hosts<>; /* any number of items */
+ typedef vldbentry blkentries<100>; /* Preferable array decl */
+
+are compiled into the following structs:
+
+ struct {
+ u_int bulk_len; /* no of items */
+ char *bulk_val; /* pointer to array */
+ } bulk;
+
+for the C<bulk> array, and similarly for the C<< blkentries<100> >> array,
+
+ struct {
+ u_int blkentries_len; /* no of items in array */
+ vldbentry *blkentries_val; /* pointer to array */
+ } blkentries;
+
+Therefore the user should be aware of the "magically" generated structure
+entries such as the number of items in the array (<array_name>_len) and
+the pointer to the array (<array_name>_val) since some of the entries will
+have to be filled in from the client/server programs. A sample proc would
+be:
+
+ typedef vldbentry blkentries<MAXENTRIES>;
+ proc GetBlk (OUT blkentries *vlentries) = VL_GETBLK;
+
+or, more directly,
+
+ GetBlk(OUT vldbentry vlentries<MAXENTRIES>) = VL_GETBLK;
+
+Note that although the latest method is preferable since one does not have
+to first use the typedef statement (and admittedly, programmers prefer
+avoiding typedefs), one should realize that B<rxgen> does the structure
+expansion and the xdr creation implicitly; therefore the user should be
+aware of the C<vldbentries_val> and C<vldbentries_len> fields as before
+(see following examples).
+
+=head3 Array example I (least desirable)
+
+Procedure declaration in the interface configuration:
+
+ proc ListAttributes (IN vldblistbyattributes *attributes,
+ INOUT blkentries *vldbentries) = VL_LISTATTRIBUTES;
+
+Sample CLIENT code:
+
+ blkentries entries, *pnt;
+ entries.blkentries_len = 10; /* max # returned entries */
+ entries.blkentries_val = (vldbentry *)malloc(LEN);
+ /* It must be set */
+
+ code = VL_ListAttributes(&attributes, &entries);
+ if (!code) {
+ pnt = entries.blkentries_val;
+ for (i=0; i < entries.blkentries_len; i++, pnt++)
+ display_vldbentry(pnt);
+ /* Make sure you free the allocated space */
+ free((char *)entries.blkentries_val);
+ }
+
+Sample SERVER code:
+
+ VL_ListAttributes(attributes, entries)
+ {
+ vldbentry *singleentry = entries->blkentries_val;
+ entries->blkentries_len = 0;
+
+ while (copy_to_vldbentry(&vlentry, singleentry))
+ singleentry++, vldbentries->entries_len++;
+ }
+
+Although this method for variable-size arrays works fine, there are some
+major drawbacks. The array parameter (i.e. vldbentries above) must be
+declared as INOUT since we need to pass the max length of the expected
+returned array; more importantly, a big (depending on the value of
+C<_len>) chunk of junk code is going to be transferred to the server as
+result of the IN(out) side-effect of the array. It's an easy and
+convenient method if the returned array size can be predicted from the
+start and when the size is quite high. This method is included as an
+example of erroneous use (and abuse) of B<rxgen> and should not be used.
+
+=head3 Array example II (Desirable method)
+
+Procedure declaration in the interface configuration (using Example I
+above):
+
+ proc ListAttributes (IN vldblistbyattributes *attributes,
+ OUT blkentries *vldbentries) = VL_LISTATTRIBUTES;
+
+Sample CLIENT code:
+
+ blkentries entries, *pnt;
+
+ code = VL_ListAttributes(&attributes, &entries);
+ if (!code) {
+ pnt = entries.blkentries_val;
+ for (i=0; i < entries.blkentries_len; i++, pnt++)
+ display_vldbentry(pnt);
+ /* Make sure you free the allocated space (by rxgen) */
+ free((char *)entries.blkentries_val);
+ }
+
+Sample SERVER code:
+
+ VL_ListAttributes(attributes, entries)
+ {
+ vldbentry *singleentry;
+ entries->blkentries_len = 0;
+ singleentry = entries->blkentries_val
+ = (vldbentry *)malloc(MAXENTRIES * sizeof(vldbentry));
+
+ while (copy_to_vldbentry(&vlentry, singleentry))
+ singleentry++, vldbentries->entries_len++;
+ }
+
+This is the best (and simplest) way of using variable-size arrays as an
+output parameter. It is the responsibility of the server-side stub to
+malloc() the adequate space which is automatically freed by the B<rxgen>
+stub; the client side should free the space allocated by the
+B<rxgen>-calling stub.
+
+=head3 Array example III (Linked Lists)
+
+Considering the following 3 declarations (could have applied some
+optimizations) in the configuration file:
+
+ typedef struct single_vldbentry *vldblist;
+ struct single_vldbentry {
+ vldbentry vlentry;
+ vldblist next_vldb;
+ };
+
+ struct vldb_list {
+ vldblist node;
+ };
+
+and the rxgen procedure declaration:
+
+ LinkedList (IN vldblistbyattributes *attributes,
+ OUT vldb_list *linkedentries) = VL_LINKEDLIST;
+
+Sample CLIENT code:
+
+ vldb_list linkedvldbs;
+ vldblist vllist, vllist1;
+
+ bzero(&linkedvldbs, sizeof(vldb_list));
+ code = VL_LinkedList(&attributes, &nentries, &linkedvldbs);
+ if (!code) {
+ printf("We got %d vldb entries\n", nentries);
+ for (vllist = linkedvldbs.node; vllist; vllist = vllist1) {
+ vllist1 = vllist->next_vldb;
+ display_entry(&vllist->vlentry);
+ free((char *)vllist);
+ }
+ }
+
+Sample SERVER code:
+
+ VL_LinkedList(rxcall, attributes, nentries, linkedvldbs);
+ {
+ vldblist vllist, *vllistptr = &linkedvldbs->node;
+ while (...) {
+ vllist = *vllistptr
+ = (single_vldbentry *)malloc (sizeof (single_vldbentry));
+ copy_to_vldbentry(&tentry, &vllist->vlentry);
+ nentries++;
+ vllistptr = &vllist->next_vldb;
+ };
+ *vllistptr = NULL;
+ }
+
+Using a linked list offers many advantages: Nothing is passed to the
+server (the parameter is OUT), no additional overhead is involved, and the
+caller doesn't have to explicitly prepare for an arbitrary return size. A
+drawback is that the caller has the responsibility of malloc() (on the
+server) and free (on the client) of each entry (to avoid unwanted
+core-leaks). Another drawback is that since it's a recursive call, the C
+stack will grow linearly with respect to the number of nodes in the list
+(so it's wise to increase the Rx LWP stack if huge amounts of data are
+expected back -- default stack size is 4K). The advantages should
+outweight the disadvantages here.
+
+It's important to pay attention to the comments of the three array
+examples above particularly when they're references to when the user
+should allocate/free space for the variable length arrays. The mechanism
+is very similar to the handling of strings thus you might need to review
+the strings section above; note that the linked lists are handled somewhat
+differently...
+
+=head2 Miscellaneous examples
+
+Below is an abbreviated version of a random interface file which shows
+some of the common cases.
+
+ /* Declaration of all structures used by the R.xg script interface */
+
+ struct AFSFid {
+ unsigned long Volume;
+ unsigned long Vnode;
+ unsigned long Unique;
+ };
+
+ typedef long ViceDataType;
+
+ /* Note that TEST would be equivalent to "HEADER" only during the
+ processing of the header, *.h, file */
+
+ #ifdef RPC_HDR
+ #define TEST "HEADER"
+ #else
+ #define TEST "REST"
+ #endif
+
+ /* This is the standard *.xg specification file */
+
+ package AFS_
+ splitprefix IN=BEFORE_ OUT=AFTER_;
+ Prefix Test
+
+ proc Remove(IN struct AFSFid *Did, IN string volname<64>,
+ OUT struct AFSStatus *Status) = AFS_REMOVE;
+
+ DisconnectFS AUX_disconnectFS() = AFS_DISCONNECTFS;
+
+ proc GetVolumeInfo(IN string Vid,
+ OUT struct VolumeInfo *Info) = AFS_GETVOLUMEINFO;
+
+ /* You could have more than an interface per configuration */
+
+ package VOTE_
+
+ /* Using the "multi" feature; thus VOTE_Beacon can be called as an
+ multi-Rx call or as a regular call */
+
+ Beacon (IN long state, long voteStart,
+ net_version *version, net_tid *tid)
+ multi = VOTE_BEACON;
+
+ package DISK_
+
+ /* Using the "split" feature */
+
+ SendFile (IN long file, long offset,
+ long length, net_version *version)
+ split = DISK_SENDFILE;
+
+=head2 Output of an actual interface configuration
+
+We'll demonstrate some of the actual output generated by B<rxgen> by
+following an abbreviated actual interface configuration.
+
+=head3 Configuration file
+
+Contents of the interface configuration file (F<vldbint.xg>):
+
+ package VL_
+ #include "vl_opcodes.h" /* The opcodes are included here */
+ %#include "vl_opcodes.h" /* directly to other places */
+
+ /* Current limitations on parameters that affect other packages
+ (i.e. volume) */
+
+ const MAXNAMELEN = 65;
+ const MAXNSERVERS = 8;
+ const MAXTYPES = 3;
+
+ /* External (visible) representation of an individual vldb entry */
+
+ struct vldbentry {
+ char name[MAXNAMELEN];
+ long volumeType;
+ long nServers;
+ long serverNumber[MAXNSERVERS];
+ long serverPartition[MAXNSERVERS];
+ long serverFlags[MAXNSERVERS];
+ u_long volumeId[MAXTYPES];
+ long flags;
+ };
+
+ typedef struct single_vldbentry *vldblist;
+ struct single_vldbentry {
+ vldbentry VldbEntry;
+ vldblist next_vldb;
+ };
+
+ struct vldb_list {
+ vldblist node;
+ };
+
+ /* vldb interface calls */
+
+ CreateEntry (IN long Volid,
+ vldbentry *newentry) = VLCREATEENTRY;
+
+ GetEntryByName (IN string volumename<MAXNAMELEN>,
+ OUT vldbentry *entry) = VLGETENTRYBYNAME;
+
+ GetNewVolumeId (IN long bumpcount,
+ OUT long *newvolumid) = VLGETNEWVOLUMEID;
+
+ ReplaceEntry (IN long Volid,
+ long voltype,
+ vldbentry *newentry,
+ long ReleaseType) multi = VLREPLACEENTRY;
+
+ ListAttributes (IN VldbListByAttributes *attributes,
+ OUT long *nentries,
+ OUT vldbentry bulkentries<MAXVLDBLEN>)
+ = VLLISTATTRIBUTES;
+
+ LinkedList (IN VldbListByAttributes *attributes,
+ OUT long *nentries,
+ OUT vldb_list *linkedentries) = VLLINKEDLIST;
+
+We'll concentrate only on the Rx generated code since the R generated code
+(B<-R> option) will soon be obsolete. For a detailed description on the
+Rx-related calls inside the generated stubs (i.e., rx_NewCall(),
+rx_EndCall()), along with details on what happens inside certain calls
+(like xdrrx_create()) please refer to the Rx documentation. Typing C<rxgen
+vldbint.xg> will result in the creation of four files: F<vldbint.h>,
+F<vldbint.xdr.c>, F<vldbint.cs.c> and F<vldbint.ss.c>. A closer look at
+these files follows.
+
+=head3 Header file (F<vldbint.h>)
+
+ /* Machine generated file -- Do NOT edit */
+
+ #include "vl_opcodes.h" /* directly to other places */
+ #define MAXNAMELEN 65
+ #define MAXNSERVERS 8
+ #define MAXTYPES 3
+
+ struct vldbentry {
+ char name[MAXNAMELEN];
+ long volumeType;
+ long nServers;
+ long serverNumber[MAXNSERVERS];
+ long serverPartition[MAXNSERVERS];
+ long serverFlags[MAXNSERVERS];
+ u_long volumeId[MAXTYPES];
+ long flags;
+ };
+ typedef struct vldbentry vldbentry;
+ bool_t xdr_vldbentry();
+
+ typedef struct single_vldbentry *vldblist;
+ bool_t xdr_vldblist();
+
+ struct single_vldbentry {
+ vldbentry VldbEntry;
+ vldblist next_vldb;
+ };
+ typedef struct single_vldbentry single_vldbentry;
+ bool_t xdr_single_vldbentry();
+
+ struct vldb_list {
+ vldblist node;
+ };
+ typedef struct vldb_list vldb_list;
+ bool_t xdr_vldb_list();
+
+ #include <rx/rx_multi.h>
+ #define multi_VL_ReplaceEntry(Volid, voltype, newentry, ReleaseType) \
+ multi_Body(StartVL_ReplaceEntry(multi_call, Volid, voltype,
+ newentry, ReleaseType), EndVL_ReplaceEntry(multi_call))
+
+ typedef struct bulkentries {
+ u_int bulkentries_len;
+ vldbentry *bulkentries_val;
+ } bulkentries;
+ bool_t xdr_bulkentries();
+
+ /* Opcode-related useful stats for package: VL_ */
+ #define VL_LOWEST_OPCODE 501
+ #define VL_HIGHEST_OPCODE 506
+ #define VL_NUMBER_OPCODES 6
+
+Notice that all structures are automatically typedef'ed and all C<const>s
+are converted to C<#define>s. Some data structures, such as bulkentries,
+are taken from procedure params (from ListAttributes proc). Thus, this
+should be kept in mind when creating stubs piecemeal with B<rxgen> (i.e.,
+using the B<-c>, B<-h>, B<-C>, or B<-S> flags). Also, one of the side
+effects of the C<multi> option (in C<ReplaceEntry> proc) is the generation
+of the C<multi_VL_ReplaceEntry> above.
+
+=head3 XDR routines for structures (vldbint.xdr.c)
+
+ /* Machine generated file -- Do NOT edit */
+
+ #include <rx/xdr.h>
+ #include "vldbint.h"
+
+ #include "vl_opcodes.h" /* directly to other places */
+
+ bool_t
+ xdr_vldbentry(xdrs, objp)
+ XDR *xdrs;
+ vldbentry *objp;
+ {
+ if (!xdr_vector(xdrs, (char *)objp->name, MAXNAMELEN,
+ sizeof(char), xdr_char))
+ return (FALSE);
+ if (!xdr_long(xdrs, &objp->volumeType))
+ return (FALSE);
+ if (!xdr_long(xdrs, &objp->nServers))
+ return (FALSE);
+ if (!xdr_vector(xdrs, (char *)objp->serverNumber, MAXNSERVERS,
+ sizeof(long), xdr_long))
+ return (FALSE);
+ if (!xdr_vector(xdrs, (char *)objp->serverPartition,
+ MAXNSERVERS, sizeof(long), xdr_long))
+ return (FALSE);
+ if (!xdr_vector(xdrs, (char *)objp->serverFlags, MAXNSERVERS,
+ sizeof(long), xdr_long))
+ return (FALSE);
+ if (!xdr_vector(xdrs, (char *)objp->volumeId, MAXTYPES,
+ sizeof(u_long), xdr_u_long))
+ return (FALSE);
+ if (!xdr_long(xdrs, &objp->flags))
+ return (FALSE);
+ return (TRUE);
+ }
+
+ bool_t
+ xdr_vldblist(xdrs, objp)
+ XDR *xdrs;
+ vldblist *objp;
+ {
+ if (!xdr_pointer(xdrs, (char **)objp,
+ sizeof(struct single_vldbentry),
+ xdr_single_vldbentry))
+ return (FALSE);
+ return (TRUE);
+ }
+
+ bool_t
+ xdr_single_vldbentry(xdrs, objp)
+ XDR *xdrs;
+ single_vldbentry *objp;
+ {
+ if (!xdr_vldbentry(xdrs, &objp->VldbEntry))
+ return (FALSE);
+ if (!xdr_vldblist(xdrs, &objp->next_vldb))
+ return (FALSE);
+ return (TRUE);
+ }
+
+ bool_t
+ xdr_vldb_list(xdrs, objp)
+ XDR *xdrs;
+ vldb_list *objp;
+ {
+ if (!xdr_vldblist(xdrs, &objp->node))
+ return (FALSE);
+ return (TRUE);
+ }
+
+ bool_t
+ xdr_bulkentries(xdrs, objp)
+ XDR *xdrs;
+ bulkentries *objp;
+ {
+ if (!xdr_array(xdrs, (char **)&objp->bulkentries_val,
+ (u_int *)&objp->bulkentries_len, MAXVLDBLEN,
+ sizeof(vldbentry), xdr_vldbentry))
+ return (FALSE);
+ return (TRUE);
+ }
+
+Note that the xdr_bulkentries() is automatically generated as a side
+effect of a procedure parameter declaration. Thus, if identical multiple
+type parameter declarations are used, then multiply-defined xdr_* stubs
+will be created! We felt this was a better alternative to having the
+B<rxgen> programmer deal with types such as bulkentries_1,
+bulkentries_2...
+
+=head3 Client-Side stub routines (vldbint.cs.c)
+
+ /* Machine generated file -- Do NOT edit */
+
+ #include <rx/xdr.h>
+ #include <rx/rx.h>
+ #include <afs/rxgen_consts.h>
+ #include "vldbint.h"
+
+ #include "vl_opcodes.h" /* directly to other places */
+
+ int VL_CreateEntry(z_conn, Volid, newentry)
+ register struct rx_connection *z_conn;
+ long Volid;
+ vldbentry * newentry;
+ {
+ struct rx_call *z_call = rx_NewCall(z_conn);
+ static int z_op = 501;
+ int z_result;
+ XDR z_xdrs;
+
+ xdrrx_create(&z_xdrs, z_call, XDR_ENCODE);
+
+ /* Marshal the arguments */
+ if ((!xdr_int(&z_xdrs, &z_op))
+ || (!xdr_long(&z_xdrs, &Volid))
+ || (!xdr_vldbentry(&z_xdrs, newentry))) {
+ z_result = RXGEN_CC_MARSHAL;
+ goto fail;
+ }
+
+ z_result = RXGEN_SUCCESS;
+ fail:
+ return rx_EndCall(z_call, z_result);
+ }
+
+ int VL_GetEntryByName(z_conn, volumename, entry)
+ register struct rx_connection *z_conn;
+ char * volumename;
+ vldbentry * entry;
+ {
+ struct rx_call *z_call = rx_NewCall(z_conn);
+ static int z_op = 504;
+ int z_result;
+ XDR z_xdrs;
+
+ xdrrx_create(&z_xdrs, z_call, XDR_ENCODE);
+
+ /* Marshal the arguments */
+ if ((!xdr_int(&z_xdrs, &z_op))
+ || (!xdr_string(&z_xdrs, &volumename, 65))) {
+ z_result = RXGEN_CC_MARSHAL;
+ goto fail;
+ }
+
+ /* Un-marshal the reply arguments */
+ z_xdrs.x_op = XDR_DECODE;
+ if ((!xdr_vldbentry(&z_xdrs, entry))) {
+ z_result = RXGEN_CC_UNMARSHAL;
+ goto fail;
+ }
+
+ z_result = RXGEN_SUCCESS;
+ fail:
+ return rx_EndCall(z_call, z_result);
+ }
+
+ int VL_GetNewVolumeId(z_conn, bumpcount, newvolumid)
+ register struct rx_connection *z_conn;
+ long bumpcount;
+ long * newvolumid;
+ {
+ struct rx_call *z_call = rx_NewCall(z_conn);
+ static int z_op = 505;
+ int z_result;
+ XDR z_xdrs;
+
+ xdrrx_create(&z_xdrs, z_call, XDR_ENCODE);
+
+ /* Marshal the arguments */
+ if ((!xdr_int(&z_xdrs, &z_op))
+ || (!xdr_long(&z_xdrs, &bumpcount))) {
+ z_result = RXGEN_CC_MARSHAL;
+ goto fail;
+ }
+
+ /* Un-marshal the reply arguments */
+ z_xdrs.x_op = XDR_DECODE;
+ if ((!xdr_long(&z_xdrs, newvolumid))) {
+ z_result = RXGEN_CC_UNMARSHAL;
+ goto fail;
+ }
+
+ z_result = RXGEN_SUCCESS;
+ fail:
+ return rx_EndCall(z_call, z_result);
+ }
+
+ int VL_ReplaceEntry(z_conn, Volid, voltype, newentry, ReleaseType)
+ register struct rx_connection *z_conn;
+ long Volid, voltype, ReleaseType;
+ vldbentry * newentry;
+ {
+ struct rx_call *z_call = rx_NewCall(z_conn);
+ static int z_op = 506;
+ int z_result;
+ XDR z_xdrs;
+
+ xdrrx_create(&z_xdrs, z_call, XDR_ENCODE);
+
+ /* Marshal the arguments */
+ if ((!xdr_int(&z_xdrs, &z_op))
+ || (!xdr_long(&z_xdrs, &Volid))
+ || (!xdr_long(&z_xdrs, &voltype))
+ || (!xdr_vldbentry(&z_xdrs, newentry))
+ || (!xdr_long(&z_xdrs, &ReleaseType))) {
+ z_result = RXGEN_CC_MARSHAL;
+ goto fail;
+ }
+
+ z_result = RXGEN_SUCCESS;
+ fail:
+ return rx_EndCall(z_call, z_result);
+ }
+
+ int StartVL_ReplaceEntry(z_call, Volid, voltype, newentry, ReleaseType)
+ register struct rx_call *z_call;
+ long Volid, voltype, ReleaseType;
+ vldbentry * newentry;
+ {
+ static int z_op = 506;
+ int z_result;
+ XDR z_xdrs;
+
+ xdrrx_create(&z_xdrs, z_call, XDR_ENCODE);
+
+ /* Marshal the arguments */
+ if ((!xdr_int(&z_xdrs, &z_op))
+ || (!xdr_long(&z_xdrs, &Volid))
+ || (!xdr_long(&z_xdrs, &voltype))
+ || (!xdr_vldbentry(&z_xdrs, newentry))
+ || (!xdr_long(&z_xdrs, &ReleaseType))) {
+ z_result = RXGEN_CC_MARSHAL;
+ goto fail;
+ }
+
+ z_result = RXGEN_SUCCESS;
+ fail:
+ return z_result;
+ }
+
+ int EndVL_ReplaceEntry(z_call)
+ register struct rx_call *z_call;
+ {
+ int z_result;
+ XDR z_xdrs;
+
+ z_result = RXGEN_SUCCESS;
+ fail:
+ return z_result;
+ }
+
+ int VL_ListAttributes(z_conn, attributes, nentries, bulkentries_1)
+ register struct rx_connection *z_conn;
+ VldbListByAttributes * attributes;
+ long * nentries;
+ bulkentries * bulkentries_1;
+ {
+ struct rx_call *z_call = rx_NewCall(z_conn);
+ static int z_op = 511;
+ int z_result;
+ XDR z_xdrs;
+
+ xdrrx_create(&z_xdrs, z_call, XDR_ENCODE);
+
+ /* Marshal the arguments */
+ if ((!xdr_int(&z_xdrs, &z_op))
+ || (!xdr_VldbListByAttributes(&z_xdrs, attributes))) {
+ z_result = RXGEN_CC_MARSHAL;
+ goto fail;
+ }
+
+ /* Un-marshal the reply arguments */
+ z_xdrs.x_op = XDR_DECODE;
+ if ((!xdr_long(&z_xdrs, nentries))
+ || (!xdr_bulkentries(&z_xdrs, bulkentries_1))) {
+ z_result = RXGEN_CC_UNMARSHAL;
+ goto fail;
+ }
+
+ z_result = RXGEN_SUCCESS;
+ fail:
+ return rx_EndCall(z_call, z_result);
+ }
+
+ int VL_LinkedList(z_conn, attributes, nentries, linkedentries)
+ register struct rx_connection *z_conn;
+ VldbListByAttributes * attributes;
+ long * nentries;
+ vldb_list * linkedentries;
+ {
+ struct rx_call *z_call = rx_NewCall(z_conn);
+ static int z_op = 512;
+ int z_result;
+ XDR z_xdrs;
+
+ xdrrx_create(&z_xdrs, z_call, XDR_ENCODE);
+
+ /* Marshal the arguments */
+ if ((!xdr_int(&z_xdrs, &z_op))
+ || (!xdr_VldbListByAttributes(&z_xdrs, attributes))) {
+ z_result = RXGEN_CC_MARSHAL;
+ goto fail;
+ }
+
+ /* Un-marshal the reply arguments */
+ z_xdrs.x_op = XDR_DECODE;
+ if ((!xdr_long(&z_xdrs, nentries))
+ || (!xdr_vldb_list(&z_xdrs, linkedentries))) {
+ z_result = RXGEN_CC_UNMARSHAL;
+ goto fail;
+ }
+
+ z_result = RXGEN_SUCCESS;
+ fail:
+ return rx_EndCall(z_call, z_result);
+ }
+
+Notice the side effect of the C<multi> feature (three different modules
+for C<ReplaceEntry> proc).
+
+=head3 Server-Side stub routines (vldbint.ss.c)
+
+ /* Machine generated file -- Do NOT edit */
+
+ #include <rx/xdr.h>
+ #include <rx/rx.h>
+ #include <afs/rxgen_consts.h>
+ #include "vldbint.h"
+
+ #include "vl_opcodes.h" /* directly to other places */
+
+ long _VL_CreateEntry(z_call, z_xdrs)
+ struct rx_call *z_call;
+ XDR *z_xdrs;
+ {
+ long z_result;
+ long Volid;
+ vldbentry newentry;
+
+ if ((!xdr_long(z_xdrs, &Volid))
+ || (!xdr_vldbentry(z_xdrs, &newentry))) {
+ z_result = RXGEN_SS_UNMARSHAL;
+ goto fail;
+ }
+
+ z_result = VL_CreateEntry(z_call, Volid, &newentry);
+ fail:
+ return z_result;
+ }
+
+ long _VL_GetEntryByName(z_call, z_xdrs)
+ struct rx_call *z_call;
+ XDR *z_xdrs;
+ {
+ long z_result;
+ char *volumename = (char *)0;
+ vldbentry entry;
+
+ if ((!xdr_string(z_xdrs, &volumename, 65))) {
+ z_result = RXGEN_SS_UNMARSHAL;
+ goto fail;
+ }
+
+ z_result = VL_GetEntryByName(z_call, &volumename, &entry);
+ z_xdrs->x_op = XDR_ENCODE;
+ if ((!xdr_vldbentry(z_xdrs, &entry)))
+ z_result = RXGEN_SS_MARSHAL;
+ fail:
+ z_xdrs->x_op = XDR_FREE;
+ if (!xdr_string(z_xdrs, &volumename, 65)) goto fail1;
+ return z_result;
+ fail1:
+ return RXGEN_SS_XDRFREE;
+ }
+
+ long _VL_GetNewVolumeId(z_call, z_xdrs)
+ struct rx_call *z_call;
+ XDR *z_xdrs;
+ {
+ long z_result;
+ long bumpcount;
+ long newvolumid;
+
+ if ((!xdr_long(z_xdrs, &bumpcount))) {
+ z_result = RXGEN_SS_UNMARSHAL;
+ goto fail;
+ }
+
+ z_result = VL_GetNewVolumeId(z_call, bumpcount, &newvolumid);
+ z_xdrs->x_op = XDR_ENCODE;
+ if ((!xdr_long(z_xdrs, &newvolumid)))
+ z_result = RXGEN_SS_MARSHAL;
+ fail:
+ return z_result;
+ }
+
+ long _VL_ReplaceEntry(z_call, z_xdrs)
+ struct rx_call *z_call;
+ XDR *z_xdrs;
+ {
+ long z_result;
+ long Volid, voltype, ReleaseType;
+ vldbentry newentry;
+
+ if ((!xdr_long(z_xdrs, &Volid))
+ || (!xdr_long(z_xdrs, &voltype))
+ || (!xdr_vldbentry(z_xdrs, &newentry))
+ || (!xdr_long(z_xdrs, &ReleaseType))) {
+ z_result = RXGEN_SS_UNMARSHAL;
+ goto fail;
+ }
+
+ z_result = VL_ReplaceEntry(z_call, Volid, voltype, &newentry,
+ ReleaseType);
+ fail:
+ return z_result;
+ }
+
+ long _VL_ListAttributes(z_call, z_xdrs)
+ struct rx_call *z_call;
+ XDR *z_xdrs;
+ {
+ long z_result;
+ VldbListByAttributes attributes;
+ long nentries;
+ bulkentries bulkentries_1;
+
+ if ((!xdr_VldbListByAttributes(z_xdrs, &attributes))) {
+ z_result = RXGEN_SS_UNMARSHAL;
+ goto fail;
+ }
+
+ z_result = VL_ListAttributes(z_call, &attributes, &nentries,
+ &bulkentries_1);
+ z_xdrs->x_op = XDR_ENCODE;
+ if ((!xdr_long(z_xdrs, &nentries))
+ || (!xdr_bulkentries(z_xdrs, &bulkentries_1)))
+ z_result = RXGEN_SS_MARSHAL;
+ fail:
+ z_xdrs->x_op = XDR_FREE;
+ if (!xdr_bulkentries(z_xdrs, &bulkentries_1)) goto fail1;
+ return z_result;
+ fail1:
+ return RXGEN_SS_XDRFREE;
+ }
+
+ long _VL_LinkedList(z_call, z_xdrs)
+ struct rx_call *z_call;
+ XDR *z_xdrs;
+ {
+ long z_result;
+ VldbListByAttributes attributes;
+ long nentries;
+ vldb_list linkedentries;
+
+ if ((!xdr_VldbListByAttributes(z_xdrs, &attributes))) {
+ z_result = RXGEN_SS_UNMARSHAL;
+ goto fail;
+ }
+
+ z_result = VL_LinkedList(z_call, &attributes, &nentries,
+ &linkedentries);
+ z_xdrs->x_op = XDR_ENCODE;
+ if ((!xdr_long(z_xdrs, &nentries))
+ || (!xdr_vldb_list(z_xdrs, &linkedentries)))
+ z_result = RXGEN_SS_MARSHAL;
+ fail:
+ return z_result;
+ }
+
+ long _VL_CreateEntry();
+ long _VL_GetEntryByName();
+ long _VL_GetNewVolumeId();
+ long _VL_ReplaceEntry();
+ long _VL_ListAttributes();
+ long _VL_LinkedList();
+
+ static long (*StubProcsArray0[])() = {_VL_CreateEntry,
+ _VL_GetEntryByName, _VL_GetNewVolumeId, _VL_ReplaceEntry,
+ _VL_ListAttributes, _VL_LinkedList};
+
+ VL_ExecuteRequest(z_call)
+ register struct rx_call *z_call;
+ {
+ int op;
+ XDR z_xdrs;
+ long z_result;
+
+ xdrrx_create(&z_xdrs, z_call, XDR_DECODE);
+ if (!xdr_int(&z_xdrs, &op))
+ z_result = RXGEN_DECODE;
+ else if (op < VL_LOWEST_OPCODE || op > VL_HIGHEST_OPCODE)
+ z_result = RXGEN_OPCODE;
+ else
+ z_result = (*StubProcsArray0[op - VL_LOWEST_OPCODE])
+ (z_call, &z_xdrs);
+ return z_result;
+ }
+
+If there were gaps in the procedures' opcode sequence the code for
+VL_ExecuteRequest() routine would be have been drastically different (it
+would have been a case statement for each procedure).
+
+=head1 NOTES
+
+B<rxgen> is implemented from Sun's B<rpcgen> utility. All of the standard
+B<rpcgen>'s functionality is fully maintained. Note that some active
+B<rpcgen> options that don't apply to B<rxgen>'s purpose aren't referenced
+here (i.e., B<-s>, B<-l>, B<-m> options) and the interested reader should
+refer to rpcgen(1) for details.
+
+When the C<%#include <include file>> feature is used make sure that you
+don't have any B<rxgen> language features (i.e. %#defines) since you'll
+get syntax errors during compilations..
+
+Since this is an ongoing project many of the above may change/disappear
+without a major warning.
+
+=head1 SEE ALSO
+
+I<Rxgen Syntax Summary>: Summary description of rxgen's grammar.
+
+I<Rpcgen Programming Guide>: Sun's RPC protocol compiler. B<rxgen> was
+implemented as an extension to that compiler.
+
+I<External Data Representation: Sun Technical Notes>: Detailed examples in
+using XDR.
+
+I<RPCL Syntax Summary>: Summary of Sun's Remote Procedure Call Language.
+
+I<Rx>: An extended Remote Procedure Call Protocol.
+
+I<rgen>: An earlier version of a similar stub generator used for the R RPC
+protocol.
+
+=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 the original TeX B<rxgen> manual to POD by Russ
+Allbery.
--- /dev/null
+=head1 NAME
+
+scout - Monitors the File Server process
+
+=head1 SYNOPSIS
+
+B<scout> [B<initcmd>] B<-server> <I<servers to monitor>>+
+ [B<-basename> <I<base server name>>]
+ [B<-frequency> <I<poll frequency, in seconds>>] [B<-host>]
+ [B<-attention> <I<specify attention (highlighting) level>>+]
+ [B<-debug> <I<turn debugging output on to the named file>>]
+ [B<-help>]
+
+B<scout> [B<i>] B<-s> <I<servers to monitor>>+
+ [B<-b> <I<base server name>>] [B<-f> <I<poll frequency, in seconds>>]
+ [B<-ho>] [B<-a> <I<specify attention (highlighting) level>>+]
+ [B<-d> <I<turn debugging output on to the named file>>] [B<-he>]
+
+=head1 DESCRIPTION
+
+The scout command displays statistics gathered from the File Server
+process running on each machine specified with the B<-server>
+argument. L<OUTPUT> explains the meaning of the statistics and describes
+how they appear in the command shell, which is preferably a window managed
+by a window manager program.
+
+=head1 CAUTIONS
+
+The B<scout> program must be able to access the curses graphics package,
+which it uses to display statistics. Most UNIX distributions include
+curses as a standard utility.
+
+Both dumb terminals and windowing systems that emulate terminals can
+display the B<scout> program's statistics. The display makes use of
+reverse video and cursor addressing, so the display environment must
+support those features for it to look its best (most windowing systems do,
+most dumb terminals do not). Also, set the TERM environment variable to
+the correct terminal type, or one with characteristics similar to the
+actual ones. For machines running the AIX operating system, the
+recommended setting for TERM is C<vt100>, as long as the terminal is
+similar to that. For other operating systems, the wider range of
+acceptable values includes C<xterm>, C<xterms>, C<vt100>, C<vt200>, and
+C<wyse85>.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<initcmd>
+
+Accommodates the command's use of the AFS command parser, and is optional.
+
+=item B<-server> <I<servers to monitor>>+
+
+Specifies each file server machine running a File Server process to
+monitor. Provide each machine's fully qualified hostname unless the
+B<-basename> argument is used. In that case, specify only the unique
+initial part of each machine name, omitting the domain name suffix (the
+basename) common to all the names. It is also acceptable to use the
+shortest abbreviated form of a host name that distinguishes it from other
+machines, but successful resolution depends on the availability of a name
+resolution service (such as the Domain Name Service or a local host table)
+at the time the command is issued.
+
+=item B<-basename> <I<base server name>>
+
+Specifies the basename (domain name) suffix common to all of the file
+server machine names specified with the B<-server> argument, and is
+automatically appended to them. This argument is normally the name of the
+cell to which the machines belong. Do not include the period that
+separates this suffix from the distinguishing part of each file server
+machine name, but do include any periods that occur within the suffix
+itself. For example, in the ABC Corporation cell, the proper value is
+C<abc.com> rather than C<.abc.com>.
+
+=item B<-frequency> <I<poll frequency>>
+
+Indicates how often to probe the File Server processes. Specify a number
+of seconds greater than C<0> (zero). The default is 60 seconds.
+
+=item B<-host>
+
+Displays the name of the machine that is running the scout program, in the
+banner line of the display screen.
+
+=item B<-attention> <I<attention level>>+
+
+Defines a list of entries, each of which pairs a statistic and a threshold
+value. When the value of the statistic exceeds the indicated threshold
+value, it is highlighted (in reverse video) in the display. List the pairs
+in any order. The acceptable values are the following:
+
+=over 4
+
+=item conn <I<connections>>
+
+Indicates the number of open connections to client processes at which to
+highlight the statistic. The statistic returns to regular display when
+the value goes back below the threshold. There is no default threshold.
+
+An example of an acceptable value is conn 300.
+
+=item disk <I<blocks_free>>
+
+Indicates the number of remaining free kilobyte blocks at which to
+highlight the statistic. The statistic returns to regular display when the
+value again exceeds the threshold. There is no default threshold.
+
+An example of an acceptable value is disk 5000.
+
+=item disk <I<percent_full>>%
+
+Indicates the percentage of disk usage at which to highlight the
+statistic. The statistic returns to regular display when the value goes
+back below the threshold. The default threshold is 95%. Acceptable values
+are the integers in the range from C<0> to C<99>, followed by the percent
+sign (C<%>) to distinguish this type of value from the one described just
+previously.
+
+An example is disk 90%.
+
+=item fetch <I<fetch RPCs>>
+
+Indicates the cumulative number of fetch RPCs from client processes at
+which to highlight the statistic. The statistic does not return to regular
+display until the File Server process restarts, at which time the value
+returns to zero. There is no default threshold.
+
+Example of a legal value: fetch 6000000
+
+=item store <I<store RPCs>>
+
+Indicates the cumulative number of store RPCs from client processes at
+which to highlight the statistic. The statistic does not return to regular
+display until the File Server process restarts, at which time the value
+returns to zero. There is no default threshold.
+
+Example of an acceptable value: store 200000
+
+=item ws <I<active client machines>>
+
+Indicates the number of client machines with active open connections at
+which to highlight the statistic. An active connection is defined as one
+over which the File Server and client have communicated in the last 15
+minutes. The statistic returns to regular display when the value goes back
+below the threshold. There is no default threshold.
+
+Example of an acceptable value: ws 65
+
+=back
+
+=item B<-debug> <I<debugging trace file>>
+
+Specifies the pathname of the file into which to write a debugging
+trace. Partial pathnames are interpreted relative to the current working
+directory.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+The B<scout> program can display statistics either in a dedicated window
+or on a plain screen if a windowing environment is not available. For best
+results, the window or screen needs the ability to print in reverse video.
+
+The B<scout> screen has three main parts: the banner line, the statistics
+display region and the message/probe line.
+
+=head2 The Banner Line
+
+By default, the string C<Scout> appears in the banner line at the top of
+the window or screen. Two optional arguments place additional information
+in the banner line:
+
+=over 4
+
+=item *
+
+The B<-host> flag displays the name of the machine where the B<scout>
+program is running. As mentioned previously, this is useful when running
+the B<scout> program on several machines but displaying the results on a
+single machine.
+
+For example, when the B<-host> flag is included and the B<scout> program
+is running on the machine C<client1.abc.com>, the banner line reads as
+follows:
+
+ [client1.abc.com] Scout
+
+=item *
+
+The B<-basename> argument displays the indicated basename on the banner
+line. For example, including the argument C<-basename abc.com> argument
+results in the following banner line:
+
+ Scout for abc.com
+
+=back
+
+=head2 The Statistics Display Region
+
+In this region, which occupies the majority of the window, the B<scout>
+process displays the statistics gathered for each File Server
+process. Each process appears on its own line.
+
+The region is divided into six columns, labeled as indicated and
+displaying the following information:
+
+=over 4
+
+=item Conn
+
+The first column displays the number of RPC connections open between the
+File Server process and client machines. This number equals or exceeds
+the number in the C<Ws> column (see the fourth entry below), because each
+user on the machine can have several separate connections open at once,
+and one client machine can handle several users.
+
+=item Fetch
+
+The second column displays the number of fetch-type RPCs (fetch data,
+fetch access list, and fetch status) that client machines have made to the
+File Server process since the latter started. This number is reset to
+zero each time the File Server process restarts.
+
+=item Store
+
+The third column displays the number of store-type RPCs (store data, store
+access list, and store status) that client machines have made to the File
+Server process since the latter started. This number is reset to zero each
+time the File Server process restarts.
+
+=item Ws
+
+The fourth column displays the number of client machines (C<Ws> stands for
+workstations) that have communicated with the File Server process within
+the last 15 minutes. Such machines are termed I<active>). This number is
+likely to be smaller than the number in the first (C<Conn>) column because
+a single client machine can have several connections open to one File
+Server.
+
+=item server name
+
+The fifth, unlabeled, column displays the name of the file server machine
+on which the File Server process is running. Names of 12 characters or
+less are displayed in full; longer names are truncated and an asterisk
+(C<*>) appears as the last character in the name. Using the B<-basename>
+argument is a good way to avoid truncation, but only if all machine names
+end in a common string.
+
+=item Disk attn
+
+The sixth column displays the number of available kilobyte blocks on each
+AFS disk partition on the file server machine.
+
+The display for each partition has the following form:
+
+ x:<free_blocks>
+
+where C<x> indicates the partition name. For example, C<a:8949> specifies
+that the F</vicepa> partition has 8,949 1-KB blocks free. Available space
+can be displayed for up to 26 partitions. If the window is not wide enough
+for all partition entries to appear on a single line, the B<scout> process
+automatically creates multiple lines, stacking the partition entries into
+sub-columns within the sixth column.
+
+The label on the C<Disk attn> column indicates the threshold value at
+which entries in the column become highlighted. By default, the label is
+
+ Disk attn: > 95% used
+
+because by default the scout program highlights the entry for any
+partition that is over 95% full.
+
+=back
+
+For all columns except the fifth (file server machine name), the optional
+B<-attention> argument sets the value at which entries in the column are
+highlighted to indicate that a certain value has been exceeded. Only
+values in the fifth and C<Disk attn> columns ever become highlighted by
+default.
+
+If the scout program is unable to access or otherwise obtain information
+about a partition, it generates a message similar to the following
+example:
+
+ Could not get information on server fs1.abc.com partition /vicepa
+
+=head2 The Message/Probe Line
+
+The bottom line of the scout screen indicates how many times the B<scout>
+program has probed the File Server processes for statistics. The
+statistics gathered in the latest probe appear in the statistics display
+region. The B<-frequency> argument overrides the default probe frequency
+of 60 seconds.
+
+=head1 EXAMPLES
+
+See the chapter on monitoring tools in the I<IBM AFS Administration
+Guide>, which illustrates the displays that result from different
+combinations of options.
+
+=head1 PRIVILEGE REQUIRED
+
+None
+
+=head1 SEE ALSO
+
+L<afsmonitor(1)>,
+L<fstrace(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+sys - Reports the compile-time CPU/operating system type
+
+=head1 SYNOPSIS
+
+B<sys>
+
+=head1 DESCRIPTION
+
+The B<sys> command displays the string set at compile time that indicates
+the local machine's CPU/operating system (OS) type, conventionally called
+the I<sysname>. This string is the default for the value stored in kernel
+memory. The Cache Manager substitutes this string for the I<@sys>
+variable which can occur in AFS pathnames; the I<IBM AFS Quick Beginnings>
+and I<IBM AFS Administration Guide> explain how using I<@sys> can simplify
+cell configuration.
+
+To set a new value in kernel memory, use the B<fs sysname> command. To
+view the current value set in the kernel, use either B<fs sysname> or
+B<livesys>.
+
+=head1 CAUTIONS
+
+You almost always want to use B<livesys> rather than this command. The
+B<sys> command displays a single value hard-coded at compile time. It
+does not query the Cache Manager for the current value and it does not
+report sysname lists. If you have changed the local system type with B<fs
+sysname>, or if you run a version of B<sys> compiled differently than the
+Cache Manager running on the system, the value retured will not match the
+behavior of the Cache Manager. The only reason to use B<sys> is that
+B<livesys> wasn't available in older versions of AFS.
+
+=head1 OUTPUT
+
+The machine's system type appears as a text string:
+
+ I<system_type>
+
+=head1 EXAMPLES
+
+The following example shows the output produced on a Sun SPARCStation
+running Solaris 5.7:
+
+ % sys
+ sun4x_57
+
+=head1 PRIVILEGE REQUIRED
+
+None
+
+=head1 SEE ALSO
+
+L<fs_sysname(1)>,
+L<livesys(1)>
+
+I<IBM AFS Quick Beginnings>
+
+I<IBM AFS Administration Guide>
+
+=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
+
+tokens - Displays the issuer's tokens
+
+=head1 SYNOPSIS
+
+B<tokens> [B<-help>]
+
+B<tokens> [B<-h>]
+
+=head1 DESCRIPTION
+
+The tokens command displays all tokens (tickets) cached on the local
+machine for the issuer. AFS server processes require that their clients
+present a token as evidence that they have authenticated in the server's
+local cell.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+The output lists one token for each cell in which the user is
+authenticated. The output indicates the
+
+=over 4
+
+=item *
+
+User's AFS UID, if it is available for display.
+
+=item *
+
+Server for which the token is valid (normally, afs). This includes a cell
+specification.
+
+=item *
+
+Day and time the token expires.
+
+=back
+
+The output of the Kerberos version of this command, B<tokens.krb>, also
+reports the following about the Kerberos ticket-granting ticket: the
+ticket owner, which Kerberos ticket-granting service that issued the
+ticket (for example, C<krbtgt.ABC.COM>), and ticket's expiration date.
+
+The string C<--End of list--> appears at the end of the output. If the
+user is not authenticated in any cell, this line is all that appears.
+
+=head1 EXAMPLES
+
+The following example shows the output when the issuer is not
+authenticated in any cell.
+
+ % tokens
+ Tokens held by the Cache Manager:
+
+ --End of list--
+
+The following example shows the output when the issuer is authenticated in
+ABC Corporation cell, where he or she has AFS UID 1000.
+
+ % tokens
+ Tokens held by the Cache Manager:
+
+ User's (AFS ID 1000) tokens for afs@abc.com [Expires Jan 2 10:00]
+ --End of list--
+
+The following example shows the output when the issuer is authenticated in
+the ABC Corporation cell, the State University cell, and the XYZ Company
+cell. The user has different AFS UIDs in the three cells. Tokens for last
+cell are expired:
+
+ % tokens
+ Tokens held by the Cache Manager:
+
+ User's (AFS ID 1000) tokens for afs@abc.com [Expires Jan 3 10:00]
+ User's (AFS ID 4286) tokens for afs@stateu.edu [Expires Jan 3 1:34]
+ User's (AFS ID 22) tokens for afs@xyz.com [>>Expired<]
+ --End of list--
+
+The following example shows the output when the issuer uses the
+B<tokens.krb> version of the command after authenticating in the ABC
+Corporation cell using the B<klog.krb> command.
+
+ % tokens.krb
+ Tokens held by the Cache Manager:
+
+ User's (AFS ID 1000) tokens for afs@abc.com [Expires Jan 31 00:09]
+ User smiths tokens for krbtgt.ABC.COM@abc.com [Expires Jan 31 00:09]
+ --End of list--
+
+=head1 PRIVILEGE REQUIRED
+
+None
+
+=head1 SEE ALSO
+
+L<klog(1)>,
+L<unlog(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
+
+translate_et - Translates numbered error codes into text messages
+
+=head1 SYNOPSIS
+
+B<translate_et> <I<error number>>+
+
+=head1 DESCRIPTION
+
+The B<translate_et> command translates each specified error number into a
+text message.
+
+This command does not use the syntax conventions of the AFS command
+suites. Provide the command name in full.
+
+=head1 OPTIONS
+
+=over 4
+
+=item <I<error number>>+
+
+Specifies each error number to translate.
+
+=back
+
+=head1 EXAMPLES
+
+The following command translates the error numbers 1 and 4:
+
+ % translate_et 1 4
+ 1 ().1 = Not owner
+ 4 ().4 = Interrupted system call
+
+=head1 PRIVILEGE REQUIRED
+
+None
+
+=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
+
+udebug - Reports Ubik process status for a database server process
+
+=head1 SYNOPSIS
+
+B<udebug> B<-servers> <I<server machine>> [B<-port> <I<IP port>>]
+ [B<-long>] [B<-help>]
+
+B<udebug> B<-s> <I<server machine>> [B<-p> <I<IP port>>] [B<-l>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<udebug> command displays the status of the lightweight Ubik process
+for the database server process identified by the B<-port> argument that
+is running on the database server machine named by the B<-servers>
+argument. The output identifies the machines where peer database server
+processes are running, which of them is the synchronization site (Ubik
+coordinator), and the status of the connections between them.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-servers> <I<server machine>>
+
+Names the database server machine that is running the process for which to
+display status information. Provide the machine's IP address in dotted
+decimal format, its fully qualified host name (for example,
+B<fs1.abc.com>), or the shortest 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 resolution service (such as the
+Domain Name Service or a local host table) at the time the command is
+issued.
+
+=item B<-port> <I<IP port>>
+
+Identifies the database server process for which to display status
+information, either by its process name or port number. Provide one of the
+following values.
+
+=over 4
+
+=item B<buserver> or 7021 for the Backup Server
+
+=item B<kaserver> or 7004 for the Authentication Server
+
+=item B<ptserver> or 7002 for the Protection Server
+
+=item B<vlserver> or 7003 for the Volume Location Server
+
+=back
+
+=item B<-long>
+
+Reports additional information about each peer of the machine named by the
+B<-servers> argument. The information appears by default if that machine
+is the synchronization site.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+Several of the messages in the output provide basic status information
+about the Ubik process on the machine specified by the B<-servers>
+argument, and the remaining messages are useful mostly for debugging
+purposes.
+
+To check basic Ubik status, issue the command for each database server
+machine in turn. In the output for each, one of the following messages
+appears in the top third of the output.
+
+ I am sync site . . . (<#_sites> servers)
+
+ I am not sync site
+
+For the synchronization site, the following message indicates that all
+sites have the same version of the database, which implies that Ubik is
+functioning correctly. See the following for a description of values other
+than C<1f>.
+
+ Recovery state 1f
+
+For correct Ubik operation, the database server machine clocks must agree
+on the time. The following messages, which are the second and third lines
+in the output, report the current date and time according to the database
+server machine's clock and the clock on the machine where the B<udebug>
+command is issued.
+
+ Host's <IP_addr> time is <dbserver_date/time>
+ Local time is <local_date/time> (time differential <skew> secs)
+
+The <skew> is the difference between the database server machine clock and
+the local clock. Its absolute value is not vital for Ubik functioning, but
+a difference of more than a few seconds between the I<skew> values for the
+database server machines indicates that their clocks are not synchronized
+and Ubik performance is possibly hampered.
+
+Following is a description of all messages in the output. As noted, it is
+useful mostly for debugging and most meaningful to someone who understands
+Ubik's implementation.
+
+The output begins with the following messages. The first message reports
+the IP addresses that are configured with the operating system on the
+machine specified by the B<-servers> argument. As previously noted, the
+second and third messages report the current date and time according to
+the clocks on the database server machine and the machine where the
+B<udebug> command is issued, respectively. All subsequent timestamps in
+the output are expressed in terms of the local clock rather than the
+database server machine clock.
+
+ Host's addresses are: <list_of_IP_addrs>
+ Host's <IP_addr> time is <dbserver_date/time>
+ Local time is <local_date/time> (time differential <skew> secs)
+
+If the <skew> is more than about 10 seconds, the following message
+appears. As noted, it does not necessarily indicate Ubik malfunction: it
+denotes clock skew between the database server machine and the local
+machine, rather than among the database server machines.
+
+ ****clock may be bad
+
+If the udebug command is issued during the coordinator election process
+and voting has not yet begun, the following message appears next.
+
+ Last yes vote not cast yet
+
+Otherwise, the output continues with the following messages.
+
+ Last yes vote for <sync_IP_addr> was <last_vote> secs ago (sync site);
+ Last vote started <vote_start> secs ago (at <date/time>)
+ Local db version is <db_version>
+
+The first indicates which peer this Ubik process last voted for as
+coordinator (it can vote for itself) and how long ago it sent the vote.
+The second message indicates how long ago the Ubik coordinator requested
+confirming votes from the secondary sites. Usually, the <last_vote> and
+<vote_start> values are the same; a difference between them can indicate
+clock skew or a slow network connection between the two database server
+machines. A small difference is not harmful. The third message reports the
+current version number <db_version> of the database maintained by this
+Ubik process. It has two fields separated by a period. The field before
+the period is based on a timestamp that reflects when the database first
+changed after the most recent coordinator election, and the field after
+the period indicates the number of changes since the election.
+
+The output continues with messages that differ depending on whether the
+Ubik process is the coordinator or not.
+
+=over 4
+
+=item *
+
+If there is only one database server machine, it is always the coordinator
+(synchronization site), as indicated by the following message.
+
+ I am sync site forever (1 server)
+
+=item *
+
+If there are multiple database sites, and the B<-servers> argument names
+the coordinator (synchronization site), the output continues with the
+following two messages.
+
+ I am sync site until <expiration> secs from now (at <date/time>)
+ (<#_sites> servers)
+ Recovery state <flags>
+
+The first message (which is reported on one line) reports how much longer
+the site remains coordinator even if the next attempt to maintain quorum
+fails, and how many sites are participating in the quorum. The I<flags>
+field in the second message is a hexadecimal number that indicates the
+current state of the quorum. A value of C<1f> indicates complete database
+synchronization, whereas a value of C<f> means that the coordinator has
+the correct database but cannot contact all secondary sites to determine
+if they also have it. Lesser values are acceptable if the B<udebug>
+command is issued during coordinator election, but they denote a problem
+if they persist. The individual flags have the following meanings:
+
+=over 4
+
+=item 0x1
+
+This machine is the coordinator.
+
+=item 0x2
+
+The coordinator has determined which site has the database with the
+highest version number.
+
+=item 0x4
+
+The coordinator has a copy of the database with the highest version
+number.
+
+=item 0x8
+
+The database's version number has been updated correctly.
+
+=item 0x10
+
+All sites have the database with the highest version number.
+
+=back
+
+If the udebug command is issued while the coordinator is writing a change
+into the database, the following additional message appears.
+
+ I am currently managing write transaction I<identifier>
+
+=item *
+
+If the B<-servers> argument names a secondary site, the output continues
+with the following messages.
+
+ I am not sync site
+ Lowest host <lowest_IP_addr> was set <low_time> secs ago
+ Sync host <sync_IP_addr> was set <sync_time> secs ago
+
+The <lowest_IP_addr> is the lowest IP address of any peer from which the
+Ubik process has received a message recently, whereas the <sync_IP_addr>
+is the IP address of the current coordinator. If they differ, the machine
+with the lowest IP address is not currently the coordinator. The Ubik
+process continues voting for the current coordinator as long as they
+remain in contact, which provides for maximum stability. However, in the
+event of another coordinator election, this Ubik process votes for the
+<lowest_IP_addr> site instead (assuming they are in contact), because it
+has a bias to vote in elections for the site with the lowest IP address.
+
+=back
+
+For both the synchronization and secondary sites, the output continues
+with the following messages. The first message reports the version number
+of the database at the synchronization site, which needs to match the
+<db_version> reported by the preceding C<Local db version> message. The
+second message indicates how many VLDB records are currently locked for
+any operation or for writing in particular. The values are nonzero if the
+B<udebug> command is issued while an operation is in progress.
+
+ Sync site's db version is <db_version>
+ <locked> locked pages, <writes> of them for write
+
+The following messages appear next only if there are any read or write
+locks on database records:
+
+ There are read locks held
+ There are write locks held
+
+Similarly, one or more of the following messages appear next only if there
+are any read or write transactions in progress when the B<udebug> command
+is issued:
+
+ There is an active write transaction
+ There is at least one active read transaction
+ Transaction tid is <tid>
+
+If the machine named by the B<-servers> argument is the coordinator, the
+next message reports when the current coordinator last updated the
+database.
+
+ Last time a new db version was labelled was:
+ <last_restart> secs ago (at <date/time>)
+
+If the machine named by the B<-servers> argument is the coordinator, the
+output concludes with an entry for each secondary site that is
+participating in the quorum, in the following format.
+
+ Server (<IP_address>): (db <db_version>)
+ last vote rcvd <last_vote> secs ago (at <date/time>),
+ last beacon sent <last_beacon> secs ago (at <date/time>),
+ last vote was { yes | no }
+ dbcurrent={ 0 | 1 }, up={ 0 | 1 } beaconSince={ 0 | 1 }
+
+The first line reports the site's IP address and the version number of the
+database it is maintaining. The <last_vote> field reports how long ago the
+coordinator received a vote message from the Ubik process at the site, and
+the <last_beacon> field how long ago the coordinator last requested a vote
+message. If the B<udebug> command is issued during the coordinator
+election process and voting has not yet begun, the following messages
+appear instead.
+
+ Last vote never rcvd
+ Last beacon never sent
+
+On the final line of each entry, the fields have the following meaning:
+
+=over 4
+
+=item *
+
+C<dbcurrent> is C<1> if the site has the database with the highest version
+number, C<0> if it does not.
+
+=item *
+
+C<up> is C<1> if the Ubik process at the site is functioning correctly,
+C<0> if it is not.
+
+=item *
+
+C<beaconSince> is C<1> if the site has responded to the coordinator's last
+request for votes, C<0> if it has not.
+
+=back
+
+Including the B<-long> flag produces peer entries even when the
+B<-servers> argument names a secondary site, but in that case only the
+I<IP_address> field is guaranteed to be accurate. For example, the value
+in the <db_version> field is usually C<0.0>, because secondary sites do
+not poll their peers for this information. The values in the I<last_vote>
+and I<last_beacon> fields indicate when this site last received or
+requested a vote as coordinator; they generally indicate the time of the
+last coordinator election.
+
+=head1 EXAMPLES
+
+This example checks the status of the Ubik process for the Volume Location
+Server on the machine C<afs1>, which is the synchronization site.
+
+ % udebug afs1 vlserver
+ Host's addresses are: 192.12.107.33
+ Host's 192.12.107.33 time is Wed Oct 27 09:49:50 1999
+ Local time is Wed Oct 27 09:49:52 1999 (time differential 2 secs)
+ Last yes vote for 192.12.107.33 was 1 secs ago (sync site);
+ Last vote started 1 secs ago (at Wed Oct 27 09:49:51 1999)
+ Local db version is 940902602.674
+ I am sync site until 58 secs from now (at Wed Oct 27 09:50:50 1999) (3 servers)
+ Recovery state 1f
+ Sync site's db version is 940902602.674
+ 0 locked pages, 0 of them for write
+ Last time a new db version was labelled was:
+ 129588 secs ago (at Mon Oct 25 21:50:04 1999)
+
+ Server( 192.12.107.35 ): (db 940902602.674)
+ last vote rcvd 2 secs ago (at Wed Oct 27 09:49:50 1999),
+ last beacon sent 1 secs ago (at Wed Oct 27 09:49:51 1999), last vote was yes
+ dbcurrent=1, up=1 beaconSince=1
+
+ Server( 192.12.107.34 ): (db 940902602.674)
+ last vote rcvd 2 secs ago (at Wed Oct 27 09:49:50 1999),
+ last beacon sent 1 secs ago (at Wed Oct 27 09:49:51 1999), last vote was yes
+ dbcurrent=1, up=1 beaconSince=1
+
+This example checks the status of the Authentication Server on the machine
+with IP address 192.12.107.34, which is a secondary site. The local clock
+is about 4 minutes behind the database server machine's clock.
+
+ % udebug 192.12.107.34 7004
+ Host's addresses are: 192.12.107.34
+ Host's 192.12.107.34 time is Wed Oct 27 09:54:15 1999
+ Local time is Wed Oct 27 09:50:08 1999 (time differential -247 secs)
+ ****clock may be bad
+ Last yes vote for 192.12.107.33 was 6 secs ago (sync site);
+ Last vote started 6 secs ago (at Wed Oct 27 09:50:02 1999)
+ Local db version is 940906574.25
+ I am not sync site
+ Lowest host 192.12.107.33 was set 6 secs ago
+ Sync host 192.12.107.33 was set 6 secs ago
+ Sync site's db version is 940906574.25
+ 0 locked pages, 0 of them for write
+
+=head1 PRIVILEGE REQUIRED
+
+None
+
+=head1 SEE ALSO
+
+L<buserver(8)>,
+L<kaserver(8)>,
+L<ptserver(8)>,
+L<vlserver(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+unlog - Discards all of the issuer's tokens
+
+=head1 SYNOPSIS
+
+B<unlog> [B<-cell> <I<cell name>>+] [B<-help>]
+
+B<unlog> [B<-c ><I<cell name>>+] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<unlog> command by default discards all tokens that the issuer
+currently holds. To discard tokens for certain cells only, name them with
+the B<-cell> argument.
+
+Since a token pertains to one client machine only, destroying tokens on
+one machine has no effect on tokens on another machine.
+
+=head1 CAUTIONS
+
+Specifying one or more cell names can cause a brief authentication outage
+during which the issuer has no valid tokens in any cell. This is because
+the command actually discards all tokens and then restores the ones for
+cells not named by the B<-cell> argument. The outage can sometimes
+interrupt the operation of jobs that require authentication.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-cell> <I<cell name>>+
+
+Specifies each cell for to discard the token. If this argument is omitted,
+the Cache Manager discards all tokens. Provide the fully qualified domain
+name, or a shortened form, in which case successful resolution depends on
+the availability of a name resolution service (such as the Domain Name
+Service or a local host table) at the time the command is issued.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command discards all tokens.
+
+ % unlog
+
+The following command discards only the tokens for the C<abc.com> and
+C<stateu.edu> cells.
+
+ % unlog -cell abc.com stateu
+
+=head1 PRIVILEGE REQUIRED
+
+None
+
+=head1 SEE ALSO
+
+L<klog(1)>,
+L<tokens(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
+
+up - Recursively copy directories, preserving AFS metadata
+
+=head1 SYNOPSIS
+
+B<up> [B<-v>] [B<-1>] [B<-f>] [B<-r>] [B<-x>]
+ <I<source directory>> <I<destination directory>>
+
+=head1 DESCRIPTION
+
+The B<up> command recursively copies the files and subdirectories in a
+specified source directory to a specified destination directory. The
+command interpreter changes the destination directory and the files and
+subdirectories in it in the following ways:
+
+=over 4
+
+=item *
+
+It copies the source directory's access control list (ACL) to the
+destination directory and its subdirectories, overwriting any existing
+ACLs.
+
+=item *
+
+If the issuer is logged on as the local superuser root and has AFS tokens
+as a member of the group system:administrators, then the source
+directory's owner (as reported by the C<ls -ld> command) becomes the owner
+of the destination directory and all files and subdirectories in
+it. Otherwise, the issuer's user name is recorded as the owner.
+
+=item *
+
+If a file or directory exists in both the source and destination
+directories, the source version overwrites the destination version. The
+overwrite operation fails if the first (user) C<w> (write) mode bit is
+turned off on the version in the destination directory, unless the B<-f>
+flag is provided.
+
+=item *
+
+The modification timestamp on a file (as displayed by the C<ls -l>
+command) in the source directory overwrites the timestamp on a file of the
+same name in the destination directory, but the timestamp on an existing
+subdirectory in the destination directory remains unchanged. If the
+command creates a new subdirectory in the destination directory, the new
+subdirectory's timestamp is set to the time of the copy operation, rather
+than to the timestamp that the subdirectory has in the source directory.
+
+=back
+
+The up command is idempotent, meaning that if its execution is interrupted
+by a network, server machine, or process outage, then a subsequent reissue
+of the same command continues from the interruption point, rather than
+starting over at the beginning. This saves time and reduces network
+traffic in comparison to the UNIX commands that provide similar
+functionality.
+
+The B<up> command returns a status code of C<0> (zero) only if it
+succeeds. Otherwise, it returns a status code of C<1> (one).
+
+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 B<-v>
+
+Prints a detailed trace to the standard output stream as the command runs.
+
+=item B<-1>
+
+Copies only the files in the top level source directory to the destination
+directory, rather than copying recursively through subdirectories. The
+source directory's ACL still overwrites the destination directory's. (This
+is the number one, not the letter C<l>.)
+
+=item B<-f>
+
+Overwrites existing directories, subdirectories, and files even if the
+first (user) C<w> (write) mode bit is turned off on the version in the
+destination directory.
+
+=item B<-r>
+
+Creates a backup copy of all files overwritten in the destination
+directory and its subdirectories, by adding a C<.old> extension to each
+filename.
+
+=item B<-x>
+
+Sets the modification timestamp on each file to the time of the copying
+operation.
+
+=item I<source directory>
+
+Names the directory to copy recursively.
+
+=item I<destination directory>
+
+Names the directory to which to copy. It does not have to exist already.
+
+=back
+
+=head1 EXAMPLES
+
+The following command copies the contents of the directory F<dir1> to
+directory F<dir2>:
+
+ % up dir1 dir2
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must have the C<a> (administer) permission on the ACL of both
+the source and destination directories.
+
+=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
+
+vos - Introduction to the vos command suite
+
+=head1 DESCRIPTION
+
+The commands in the B<vos> command suite are the administrative interface
+to the Volume Server and Volume Location (VL) Server. System
+administrators use B<vos> commands to create, move, delete, replicate,
+back up and examine volumes, among other operations. The VL Server
+automatically records in the Volume Location Database (VLDB) changes in
+volume status and location that result from B<vos> commands.
+
+The operations invoked by most B<vos> commands are idempotent, meaning
+that if an operation is interrupted by a network, server machine, or
+process outage, then a subsequent attempt at the same operation continues
+from the interruption point, rather than starting over at the beginning of
+the operation. Before executing a command, the Volume and VL Servers check
+the current state of the volumes and VLDB records to be altered by the
+command. If they are already in the desired end state (or a consistent
+intermediate state), there is no need to repeat the internal steps that
+brought them there. Idempotency does not apply if the command issuer
+explicitly interrupts the operation with the Ctrl-C command or another
+interrupt signal. In that case, the volume is left locked and the
+administrator must use the B<vos unlock> command to unlock it before
+proceeding.
+
+It is important that the VLDB accurately indicate the status of the
+volumes on file server machines at all times. L<vldb.DB0(5)> and
+L<afs_volume_header(5)> describe the information recorded in the VLDB and
+volume headers, respectively. If a B<vos> command changes volume status,
+it automatically records the change in the corresponding VLDB entry. The
+most common cause of discrepancies between the VLDB and volume status on
+file server machines is interrupted operations; to restore consistency,
+use the B<vos syncserv> and B<vos syncvldb> commands.
+
+There are several categories of commands in the vos command suite:
+
+=over 4
+
+=item *
+
+Commands to create, move, and rename volumes: B<vos backup>, B<vos
+backupsys>, B<vos create>, B<vos move>, and B<vos rename>.
+
+=item *
+
+Commands to remove VLDB volume records or volumes or both: B<vos
+delentry>, B<vos remove>, and B<vos zap>.
+
+=item *
+
+Commands to edit or display VLDB server entries: B<vos changeaddr> and
+B<vos listaddrs>.
+
+=item *
+
+Commands to create and restore dump files: B<vos dump> and B<vos restore>.
+
+=item *
+
+Commands to administer replicated volumes: B<vos addsite>, B<vos release>,
+and B<vos remsite>.
+
+=item *
+
+Commands to display VLDB records, volume headers, or both: B<vos examine>,
+B<vos listvldb>, and B<vos listvol>.
+
+=item *
+
+Commands to display information about partitions that house volumes: B<vos
+listpart> and B<vos partinfo>.
+
+=item *
+
+Commands to restore consistency between the VLDB and volume headers: B<vos
+syncserv> and B<vos syncvldb>.
+
+=item *
+
+Commands to lock and unlock VLDB entries: B<vos lock>, B<vos unlock>, and
+B<vos unlockvldb>.
+
+=item *
+
+A command to report Volume Server status: B<vos status>.
+
+=item *
+
+Commands to obtain help: B<vos apropos> and B<vos help>.
+
+=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.
+
+=over 4
+
+=item B<-cell> <I<cell name>>
+
+Names the cell in which to run the command. It is acceptable to abbreviate
+the cell name to the shortest form that distinguishes it from the other
+entries in the F</usr/vice/etc/CellServDB> file on the local machine. If
+the B<-cell> argument is omitted, the command interpreter determines the
+name of the local cell by reading the following in order:
+
+=over 4
+
+=item *
+
+The value of the AFSCELL environment variable.
+
+=item *
+
+The local F</usr/vice/etc/ThisCell> file.
+
+=back
+
+Do not combine the B<-cell> and B<-localauth> options. A command on which
+the B<-localauth> flag is included always runs in the local cell (as
+defined in the server machine's local F</usr/afs/etc/ThisCell> file),
+whereas a command on which the B<-cell> argument is included runs in the
+specified foreign cell.
+
+=item B<-help>
+
+Prints a command's online help message on the standard output stream. Do
+not combine this flag with any of the command's other options; when it is
+provided, the command interpreter ignores all other options, and only
+prints the help message.
+
+=item B<-localauth>
+
+Constructs a server ticket using the server encryption key with the
+highest key version number in the local F</usr/afs/etc/KeyFile> file. The
+B<vos> command interpreter presents the ticket, which never expires, to
+the Volume Server and VL Server during mutual authentication.
+
+Use this flag only when issuing a command on a server machine; client
+machines do not usually have a F</usr/afs/etc/KeyFile> file. The issuer
+of a command that includes this flag must be logged on to the server
+machine as the local superuser C<root>. The flag is useful for commands
+invoked by an unattended application program, such as a process controlled
+by the UNIX B<cron> utility or by a cron entry in the machine's
+F</usr/afs/local/BosConfig> file. It is also useful if an administrator is
+unable to authenticate to AFS but is logged in as the local superuser
+B<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 B<-noauth>
+
+Establishes an unauthenticated connection to the Volume Server and VL
+Server, in which the servers treat 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 servers allow only privileged
+users to issue commands that change the status of a volume or VLDB record,
+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<-partition> <I<partition name>>
+
+Identifies the AFS server partition on a file server machine that houses,
+or is to house, the volumes of interest, or about which to list
+information. The B<vos> command interpreter accepts any of the following
+four name formats:
+
+ /vicepa = vicepa = a = 0
+ /vicepb = vicepb = b = 1
+
+After /vicepz (for which the index is 25) comes
+
+ /vicepaa = vicepaa = aa = 26
+ /vicepab = vicepab = ab = 27
+
+and so on through
+
+ /vicepiv = vicepiv = iv = 255
+
+The B<-frompartition> and B<-topartition> arguments to the B<vos move>
+command also accept this notation.
+
+=item B<-server> <I<machine name>>
+
+Identifies the file server machine that houses, or is to house, the
+volumes or AFS server partitions of interest. Provide the machine's IP
+address in dotted decimal format, its fully qualified host name (for
+example, C<fs1.abc.com>), or the shortest 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 resolution service
+(such as the Domain Name Service or a local host table) at the time the
+command is issued.
+
+The B<-fromserver> and B<-toserver> arguments to the B<vos move> command
+also accept these name formats.
+
+=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.
+
+=back
+
+=head1 PRIVILEGE REQUIRED
+
+To issue most vos commands, the issuer must be listed in the
+F</usr/afs/etc/UserList> file on each server machine that houses or is to
+house an affected volume, and on each database server machine. The most
+predictable performance results if all database server and file server
+machines in the cell share a common F<UserList> file. Alternatively, if
+the B<-localauth> flag is included, the issuer must be logged on to a
+server machine as the local superuser C<root>.
+
+To issue a vos command that only displays information, no privilege is
+required.
+
+=head1 SEE ALSO
+
+L<CellServDB(5)>,
+L<UserList(5)>,
+L<vos_addsite(1)>,
+L<vos_apropos(1)>,
+L<vos_backup(1)>,
+L<vos_backupsys(1)>,
+L<vos_changeaddr(1)>,
+L<vos_create(1)>,
+L<vos_delentry(1)>,
+L<vos_dump(1)>,
+L<vos_examine(1)>,
+L<vos_help(1)>,
+L<vos_listaddrs(1)>,
+L<vos_listpart(1)>,
+L<vos_listvldb(1)>,
+L<vos_listvol(1)>,
+L<vos_lock(1)>,
+L<vos_move(1)>,
+L<vos_partinfo(1)>,
+L<vos_release(1)>,
+L<vos_remove(1)>,
+L<vos_remsite(1)>,
+L<vos_rename(1)>,
+L<vos_restore(1)>,
+L<vos_status(1)>,
+L<vos_syncserv(1)>,
+L<vos_syncvldb(1)>,
+L<vos_unlock(1)>,
+L<vos_unlockvldb(1)>,
+L<vos_zap(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
+
+vos addsite - Adds a read-only site definition to a volume's VLDB entry
+
+=head1 SYNOPSIS
+
+B<vos addsite> B<-server> <I<machine name for new site>>
+ B<-partition> <I<partition name for new site>>
+ B<-id> <I<volume name or ID>> [B<-cell> <I<cell name>>]
+ [B<-noauth>] [B<-localauth>] [B<-verbose>] [B<-help>]
+
+B<vos ad> B<-s> <I<machine name for new site>>
+ B<-p> <I<partition name for new site>>
+ B<-i> <I<volume name or ID>> [B<-c> <I<cell name>>]
+ [B<-n>] [B<-l>] [B<-v>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<vos addsite> command defines a new read-only site (partition on a
+file server machine, specified by the B<-server> and B<-partition>
+arguments) in the Volume Location Database (VLDB) entry of the read/write
+volume named by the B<-id> argument. When the B<vos release> command is
+next issued against the read/write volume, a read-only copy of it is
+distributed to all of the read-only sites, including the newly defined
+one.
+
+=head1 CAUTIONS
+
+A volume's VLDB entry accommodates a maximum number of site definitions,
+as defined in the I<IBM AFS Release Notes>. The site housing the
+read/write and backup versions of the volume counts as one site, and each
+read-only site counts as an additional site (even the read-only site
+defined on the same file server machine and partition as the read/write
+site counts as a separate site). The limit in the VLDB entry effectively
+determines the maximum number of copies of the volume that are available
+to AFS clients.
+
+Attempts to create additional sites by using this command fail with an
+error.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-server> <I<machine name>>
+
+Identifies the file server machine where the read-only volume is to
+reside. Provide the machine's IP address or its host name (either fully
+qualified or using an unambiguous abbreviation). For details, see
+L<vos(1)>.
+
+=item B<-partition> <I<partition name>>
+
+Identifies the partition where the read-only volume is to reside, on the
+file server machine named by the B<-server> argument. Provide the
+partition's complete name with preceding slash (for example, C</vicepa>)
+or use one of the three acceptable abbreviated forms. For details, see
+L<vos(1)>.
+
+=item B<-id> <I<volume name or ID>>
+
+Specifies either the complete name or volume ID number of the read/write
+source volume.
+
+=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<vos(1)>.
+
+=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 L<vos(1)>.
+
+=item -localauth
+
+Constructs a server ticket using a key from the local
+F</usr/afs/etc/KeyFile> file. The B<vos> command interpreter presents it
+to the Volume Server and Volume Location Server during mutual
+authentication. Do not combine this flag with the B<-cell> argument or
+B<-noauth> flag. For more details, see L<vos(1)>.
+
+=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.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following example, appropriate in the State University cell, defines a
+read-only site for the cell's C<root.afs> volume.
+
+ % vos addsite -server sv7.stateu.edu -partition /vicepb -id root.afs
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the F</usr/afs/etc/UserList> file on the
+machine specified with the B<-server> argument and on each database server
+machine. 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<vos(1)>,
+L<vos_examine(1)>,
+L<vos_release(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
+
+vos apropos - Displays each help entry containing a keyword string
+
+=head1 SYNOPSIS
+
+B<vos apropos> B<-topic> <I<help string>> [B<-help>]
+
+B<vos ap> B<-t> <I<help string>> [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<vos apropos> command displays the first line of the online help
+entry for any B<vos> 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 B<vos help> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-topic> <I<help string>>
+
+Specifies the keyword string to match. Use lowercase letters only, except
+for the acronym C<VLDB>. If the string is more than a single word,
+surround it with double quotes ("") or other delimiters.
+
+=item B<-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<vos> command where the string specified with the B<-topic> argument is
+part of the command name or first line.
+
+=head1 EXAMPLES
+
+The following command displays all vos commands that include the word
+B<lock> in their names or short descriptions:
+
+ % vos apropos lock
+ lock: lock VLDB entry for a volume
+ unlock: release lock on VLDB entry for a volume
+ unlockvldb: unlock all the locked entries in the VLDB
+
+=head1 PRIVILEGE REQUIRED
+
+None
+
+=head1 SEE ALSO
+
+L<vos(1)>,
+L<vos_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
+
+vos backup - Creates a backup volume for a single read/write volume
+
+=head1 SYNOPSIS
+
+B<vos backup> B<-id> <I<volume name or ID>> [B<-cell> <I<cell name>>]
+ [B<-noauth>] [B<-localauth>] [B<-verbose>] [B<-help>]
+
+B<vos backup> B<-i> <I<volume name or ID>> [B<-c><I<cell name>>]
+ [B<-n>] [B<-l>] [B<-v>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<vos backup> command clones the indicated read/write volume to create
+a backup version, placing it at the same site as the read/write
+version. The backup volume's name is the same as the read/write source's
+with the addition of the C<.backup> extension. Its volume ID number is the
+one allocated for it in the Volume Location Database (VLDB) when the
+read/write source was created with the B<vos create> command. If a backup
+version already exists, the new clone replaces it.
+
+To create a backup version of multiple volumes, use the B<vos backupsys>
+command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-id> <I<volume name or ID>>
+
+Specifies either the complete name or volume ID number of the read/write
+source volume.
+
+=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<vos(1)>.
+
+=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 L<vos(1)>.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+F</usr/afs/etc/KeyFile> file. The B<vos> command interpreter presents it
+to the Volume Server and Volume Location Server during mutual
+authentication. Do not combine this flag with the B<-cell> argument or
+B<-noauth> flag. For more details, see L<vos(1)>.
+
+=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.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+The following message confirms that the command succeeded:
+
+ Created backup volume for I<volume name>
+
+=head1 EXAMPLES
+
+The following example creates a backup version of the volume
+C<user.smith>.
+
+ % vos backup user.smith
+ Created backup volume for user.smith
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the F</usr/afs/etc/UserList> file on the
+machine specified with the B<-server> argument and on each database server
+machine. 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<vos(1)>,
+L<vos_backupsys(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
+
+vos backupsys - Creates a backup volume for several read/write volumes
+
+=head1 SYNOPSIS
+
+B<vos backupsys> [B<-prefix> <I<common prefix on volume(s)>>+]
+ [B<-server> <I<machine name>>] [B<-partition> <I<partition name>>]
+ [B<-exclude>] [B<-xprefix> <I<negative prefix on volume(s)>>+]
+ [B<-dryrun>] [B<-cell> <I<cell name>>] [B<-noauth>] [B<-localauth>]
+ [B<-verbose>] [B<-help>]
+
+B<vos backups> [B<-pr> <I<common prefix on volume(s)>>+]
+ [B<-s> <I<machine name>>] [B<-pa> <I<partition name>>] [B<-e>]
+ [B<-x> <I<negative prefix on volume(s)>>+] [B<-d>]
+ [B<-c> <I<cell name>>] [B<-n>] [B<-l>] [B<-v>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<vos backupsys> command clones each indicated read/write volume to
+create a backup version, placing each clone at the same site as its
+read/write source version. It assigns each clone the same name as the
+read/write source, adding a C<.backup> extension. It assigns the volume ID
+number already allocated for the backup version in the Volume Location
+Database (VLDB). If a backup version already exists for a given volume,
+the new clone replaces it.
+
+To clone every read/write volume listed in the VLDB, omit all of the
+command's options. Otherwise, combine the command's options to clone
+various groups of volumes. The options use one of two basic criteria to
+select volumes: location (the B<-server> and B<-partition> arguments) or
+presence in the volume name of one of a set of specified character strings
+(the B<-prefix>, B<-exclude>, and B<-xprefix> options).
+
+To clone only volumes that reside on one file server machine, include the
+B<-server> argument. To clone only volumes that reside on one partition,
+combine the B<-server> and B<-partition> arguments. The B<-partition>
+argument can also be used alone to clone volumes that reside on the
+indicated partition on every file server machine. These arguments can be
+combined with those that select volumes based on their names.
+
+Combine the B<-prefix>, -exclude, and B<-xprefix> options (with or without
+the B<-server> and B<-partition> arguments) in the indicated ways to
+select volumes based on character strings contained in their names:
+
+=over 4
+
+=item *
+
+To clone every read/write volume at the specified location whose name
+includes one of a set of specified character strings (for example, begins
+with C<user.> or includes the string C<afs>), use the B<-prefix> argument
+or combine the B<-xprefix> and B<-exclude> options.
+
+=item *
+
+To clone every read/write volume at the specified location except those
+whose name includes one of a set of specified character strings, use the
+B<-xprefix> argument or combine the B<-prefix> and B<-exclude> options.
+
+=item *
+
+To clone every read/write volume at the specified location whose name
+includes one of one of a set of specified character strings, except those
+whose names include one of a different set of specified character strings,
+combine the B<-prefix> and B<-xprefix> arguments. The command creates a
+list of all volumes that match the B<-prefix> argument and then removes
+from the list the volumes that match the B<-xprefix> argument. For
+effective results, the strings specified by the B<-xprefix> argument must
+designate a subset of the volumes specified by the B<-prefix> argument.
+
+If the B<-exclude> flag is combined with the B<-prefix> and B<-xprefix>
+arguments, the command creates a list of all volumes that do not match the
+B<-prefix> argument and then adds to the list any volumes that match the
+B<-xprefix> argument. As when the B<-exclude> flag is not used, the result
+is effective only if the strings specified by the B<-xprefix> argument
+designate a subset of the volumes specified by the B<-prefix> argument.
+
+=back
+
+The B<-prefix> and B<-xprefix> arguments both accept multiple values,
+which can be used to define disjoint groups of volumes. Each value can be
+one of two types:
+
+=item *
+
+A simple character string, which matches volumes whose name begin with the
+string. All characters are interpreted literally (that is, characters that
+potentially have special meaning to the command shell, such as the period,
+have only their literal meaning).
+
+=item *
+
+A regular expression, which matches volumes whose names contain the
+expressions. Place a caret (C<^>) at the beginning of the expression, and
+enclose the entire string in single quotes (C<''>). Explaining regular
+expressions is outside the scope of this reference page; see the UNIX
+manual page for regexp(5) or (for a brief introduction)
+L<backup_addvolentry(8)>. As an example, the following expression matches
+volumes that have the string C<aix> anywhere in their names:
+
+ -prefix '^.*aix'
+
+To display a list of the volumes to be cloned, without actually cloning
+them, include the B<-dryrun> flag. To display a statement that summarizes
+the criteria being used to select volume, include the B<-verbose> flag.
+
+This command can be used to clone a single read/write volume; specify its
+complete name as the B<-prefix> argument. However, it is more efficient to
+use the B<vos backup> command, which employs a more streamlined technique
+for finding a single volume.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-prefix> <I<common prefix>>
+
+Specifies one or more simple character strings or regular expressions of
+any length; a volume whose name includes the string is placed on the set
+of volumes to be cloned. Include field separators (such as periods) if
+appropriate. This argument can be combined with any combination of the
+B<-server>, B<-partition>, B<-exclude>, and B<-xprefix> options.
+
+=item B<-server> <I<machine name>>
+
+Identifies the file server machine where each read/write source volume
+resides. Provide the machine's IP address or its host name (either fully
+qualified or using an unambiguous abbreviation). For details, see
+L<vos(1)>.
+
+This argument can be combined with any combination of the B<-prefix>,
+B<-partition>, B<-exclude>, and B<-xprefix> options.
+
+=item B<-partition> <I<partition name>>
+
+Identifies the partition where each read/write source volume
+resides. Provide the partition's complete name with preceding slash (for
+example, C</vicepa>) or use one of the three acceptable abbreviated
+forms. For details, see L<vos(1)>.
+
+This argument can be combined with any combination of the B<-prefix>,
+B<-server>, B<-exclude>, and B<-xprefix> options.
+
+=item B<-exclude>
+
+Reverses the meaning of the B<-prefix> or B<-xprefix> argument. This flag
+can be combined with any combination of the B<-prefix>, B<-server>,
+B<-partition>, and B<-xprefix> options.
+
+=item B<-xprefix> <I<negative prefix>>
+
+Specifies a simple character string or regular expression of any length; a
+volume whose name includes the string is removed from the set of volumes
+to be cloned. Include field separators (such as periods) if
+appropriate. This argument can be combined with any combination of the
+B<-prefix>, B<-server>, B<-partition>, and B<-exclude> options.
+
+=item B<-dryrun>
+
+Displays on the standard output stream a list of the volumes to be cloned,
+without actually cloning them.
+
+=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<vos(1)>.
+
+=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<vos(1)>.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+F</usr/afs/etc/KeyFile> file. The B<vos> command interpreter presents it
+to the Volume Server and Volume Location Server during mutual
+authentication. Do not combine this flag with the B<-cell> argument or
+B<-noauth> flag. For more details, see L<vos(1)>.
+
+=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.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+The command generates the following messages on the standard output stream
+to confirm that the operation was successful:
+
+ done
+ Total volumes backed up: <number_cloned>; failed to backup: <failures>
+
+If the B<-dryrun> flag is included, a list of the volumes to be backed up
+precedes the standard confirmation messages.
+
+If the B<-verbose> flag is included but not the B<-dryrun> flag, the
+following messages appear for each volume. The output concludes with the
+standard confirmation messages.
+
+ Creating backup volume for <volume_name> on <date/time>
+ {Recloning backup volume | Creating a new backup clone} <backup_volumeID> . . .done
+
+If both the B<-dryrun> and B<-verbose> flags are included, the output
+begins with a statement summarizing the criteria being used to select the
+volumes, followed by a list of the volumes and the standard confirmation
+messages. The format of the criteria summary statement depends on which
+other options are provided:
+
+=over 4
+
+=item *
+
+If only the B<-prefix> argument is provided, or the B<-xprefix> and
+B<-exclude> options are combined:
+
+ Would have backed up volumes which are prefixed with <string> [or <string>] . .
+
+=item *
+
+If only the B<-xprefix> argument is provided, or the B<-prefix> and
+B<-exclude> options are combined:
+
+ Would have backed up volumes which are not prefixed with <string> [nor <string>] . .
+
+=item *
+
+If the B<-prefix> and B<-xprefix> arguments are combined:
+
+ Would have backed up volumes which are prefixed with <string> [or <string>] \
+ removing those which are prefixed with <x_string> [or <x_string>] . .
+
+=item *
+
+If the B<-prefix>, B<-xprefix>, and B<-exclude> options are provided:
+
+ Would have backed up volumes which are not prefixed with <string> [nor <string>] \
+ adding those which are prefixed with <x_string> [or <x_string>] . .
+
+=back
+
+=head1 EXAMPLES
+
+The following example creates a backup version of every read/write volume
+listed in the cell's VLDB whose name begins with the string B<user>.
+
+ % vos backupsys -prefix user
+
+The following example, appropriate in the ABC Corporation cell, creates a
+backup version of every read/write volume on the file server machine
+C<fs3.abc.com>.
+
+ % vos backupsys -server fs3.abc.com
+
+The following example, appropriate in the State University cell, creates a
+backup version of every read/write volume on the file server machine
+C<db1.stateu.edu> except those whose name includes the string C<temp>.
+
+ % vos backupsys -server db1.stateu.edu -prefix '^.*temp'
+
+The following example creates a backup version of every volume listed in
+the cell's VLDB, excluding those whose names contain the string C<source>,
+but including those whose names contain the string C<source.current>.
+
+ % vos backupsys -prefix '^.*source' -exclude -xprefix '^.*source\.current'
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the F</usr/afs/etc/UserList> file on the
+machine specified with the B<-server> argument and on each database server
+machine. 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_addvolentry(8)>,
+L<vos(1)>,
+L<vos_backup(1)>
+
+UNIX manual page for regexp(5)
+
+=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
+
+vos changeaddr - Changes or removes a file server machine's entry in the VLDB
+
+=head1 SYNOPSIS
+
+B<vos changeaddr> B<-oldaddr> <I<original IP address>>
+ [B<-newaddr> <I<new IP address>>] [B<-remove>]
+ [B<-cell> <I<cell name>>] [B<-noauth>] [B<-localauth>]
+ [B<-verbose>] [B<-help>]
+
+B<vos ch> B<-o> <I<original IP address>> [B<-ne> <I<new IP address>>]
+ [B<-r>] [B<-c> <I<cell name>>] [B<-no>] [B<-l>] [B<-v>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<vos changeaddr> command removes a server entry from the Volume
+Location Database (VLDB) when the B<-remove> flag is combined with the
+B<-oldaddr> argument. There must be no VLDB entries that list the machine
+as a site for any version of a volume (if necessary, use the B<vos move>
+or B<vos remove> command to more or remove volumes). It is appropriate to
+remove a VLDB server entry when removing the corresponding file server
+machine from service; this is the only recommended use of the command.
+
+To display all VLDB server entries, use the B<vos listaddrs> command.
+
+=head1 CAUTIONS
+
+Combining the command's B<-oldaddr> and B<-newaddr> arguments is no longer
+the appropriate way to change the IP address registered for a file server
+machine. Furthermore, if a machine is multihomed and its server entry
+includes several addresses, then the address specified with the
+B<-newaddr> argument replaces all of the addresses currently listed in the
+server entry that includes the address specified by the B<-oldaddr>
+argument. This effectively makes the machine single-homed with respect to
+AFS operations, which is probably not the desired result.
+
+The recommended method for changing the IP addresses in a server entry is
+instead to restart the C<fs> process group (which includes the File
+Server) after using the utilities provided by the operating system to
+reconfigure the machine's network interfaces. For a description of how the
+File Server constructs and registers a list of its network interfaces in
+the VLDB, see L<sysid(5)>.
+
+If, counter to recommended usage, the command is used to change the IP
+address in a server entry, it does not also change the names of machine
+entries in the Protection Database. Operations fail when they refer to a
+protection group that has an obsolete IP address in it. Use the B<pts
+rename> command to change the names of machine entries that correspond to
+the addresses changed with this command. Changing the address of a
+database server machine also requires updating the client and server
+versions of the F<CellServDB> file on every machine.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-oldaddr> <I<original IP address>>
+
+Specifies the IP address currently registered for the file server machine
+in the VLDB server entry. If there are multiple addresses registered for a
+multihomed machine, use any of them to identify the server entry.
+
+=item B<-newaddr> <I<new IP address>>
+
+Specifies the new IP address that replaces all currently registered
+addresses.
+
+=item B<-remove>
+
+Removes from the VLDB the server entry that includes the address specified
+by the B<-oldaddr> argument.
+
+=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<vos(1)>.
+
+=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<vos(1)>.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+F</usr/afs/etc/KeyFile> file. The B<vos> command interpreter presents it
+to the Volume Server and Volume Location Server during mutual
+authentication. Do not combine this flag with the B<-cell> argument or
+B<-noauth> flag. For more details, see L<vos(1)>.
+
+=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.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command removes the VLDB server entry that includes the IP
+address C<192.12.107.214>.
+
+ % vos changeaddr -oldaddr 192.12.107.214 -remove
+
+=head1 PRIVILEGE REQUIRED
+
+Issuer must be listed in the F</usr/afs/etc/UserList> file on the machine
+specified with the B<-oldaddr> argument and on each database server
+machine.
+
+=head1 SEE ALSO
+
+L<CellServDB(5)>,
+L<UserList(5)>,
+L<sysid(5)>,
+L<fileserver(8)>,
+L<pts_rename(1)>,
+L<vos(1)>,
+L<vos_listaddrs(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
+
+vos create - Creates a read/write volume and associated VLDB entry
+
+=head1 SYNOPSIS
+
+B<vos create> B<-server> <I<machine name>> B<-partition> <I<partition name>>
+ B<-name> <I<volume name>> [B<-maxquota> <I<initial quota (KB)>>]
+ [B<-cell> <I<cell name>>] [B<-noauth>] [B<-localauth>] [B<-verbose>]
+ [B<-help>]
+
+B<vos cr> B<-s> <I<machine name>> B<-p> <I<partition name>>
+ B<-na> <I<volume name>> [B<-m> <I<initial quota (KB)>>]
+ [B<-c> <I<cell name>>] [B<-no>] [B<-l>] [B<-v>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<vos create> command creates a read/write volume with the name
+specified by the B<-name> argument at the site specified by the B<-server>
+and B<-partition> arguments. In addition, the command allocates or sets
+the following:
+
+=over 4
+
+=item *
+
+Volume ID numbers for the read/write volume and its associated read-only
+and backup volumes (this command does not actually create the latter two
+types of volume). A volume ID number is an identification number
+guaranteed to be unique within a cell.
+
+=item *
+
+An access control list (ACL) associated with the volume's root directory,
+which takes the same name as volume's mount point when the volume is
+mounted with the B<fs mkmount> command. An entry that grants all seven
+permissions to the members of the system:administrators group is
+automatically placed on the ACL. (In addition, the File Server by default
+always implicitly grants the C<l> (lookup) and C<a> (administer)
+permissions on every ACL to members of the system:administrators group,
+even when the group does not appear on an ACL; use the B<-implicit>
+argument to the B<fileserver> initialization command to alter the set of
+rights on a server-by-server basis if desired.)
+
+=item *
+
+The volume's space quota, set to 5000 kilobyte blocks by default. Use the
+B<-maxquota> argument to specify a different quota, or use the B<fs
+setquota> command to change the volume's quota after mounting the volume
+with the B<fs mkmount> command.
+
+=back
+
+The volume is empty when created. To access it via the Cache Manager,
+mount it in the file space by using the B<fs mkmount> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-server> <I<server name>>
+
+Identifies the file server machine on which to create the read/write
+volume. Provide the machine's IP address or its host name (either fully
+qualified or using an unambiguous abbreviation). For details, see
+L<vos(1)>.
+
+=item B<-partition> <I<partition name>>
+
+Identifies the partition on which to create the read/write volume, on the
+file server machine specified by the B<-server> argument. Provide the
+partition's complete name with preceding slash (for example, C</vicepa>)
+or use one of the three acceptable abbreviated forms. For details, see
+L<vos(1)>.
+
+=item B<-name> <I<volume name>>
+
+Specifies a name for the read/write volume. The maximum length is 22
+characters, which can include any alphanumeric or punctuation
+character. By convention, periods separate the fields in a name. Do not
+apply the C<.backup> or C<.readonly> extension to a read/write volume
+name; they are reserved for the Volume Server to add to the read/write
+name when creating those backup and read-only volumes respectively.
+
+=item B<-maxquota> <I<volume quota>>
+
+Specifies the maximum amount of disk space the volume can use, as a number
+of kilobyte blocks (a value of C<1024> is one megabyte). The value C<0>
+(zero) grants an unlimited quota, but the size of the disk partition that
+houses the volume places an absolute limit on its size. If this argument
+is omitted, the default value is C<5000>.
+
+=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<vos(1)>.
+
+=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<vos(1)>.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+F</usr/afs/etc/KeyFile> file. The B<vos> command interpreter presents it
+to the Volume Server and Volume Location Server during mutual
+authentication. Do not combine this flag with the B<-cell> argument or
+B<-noauth> flag. For more details, see L<vos(1)>.
+
+=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.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+The Volume Server produces the following message to confirm that it
+created the volume:
+
+ Volume <volume_ID> created on partition <partition_name> of <machine_name>
+
+=head1 EXAMPLES
+
+The following command creates the read/write volume C<user.pat> on the
+F</vicepf> partition of the file server machine C<fs4.abc.com>.
+
+ % vos create -server fs4.abc.com -partition /vicepf -name user.pat
+ Volume user.pat created on partition /vicepf of fs4.abc.com
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the F</usr/afs/etc/UserList> file on the
+machine specified with the B<-server> argument and on each database server
+machine. 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<vos(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
+
+vos delentry - Removes a volume entry from the VLDB.
+
+=head1 SYNOPSIS
+
+B<vos delentry> [B<-id> <I<volume name or ID>>+]
+ [B<-prefix> <I<prefix of volume whose VLDB entry is to be deleted>>]
+ [B<-server> <I<machine name>>] [B<-partition> <I<partition name>>]
+ [B<-cell> <I<cell name>>] [B<-noauth>] [B<-localauth>] [B<-verbose>]
+ [B<-help>]
+
+B<vos de> [B<-i> <I<volume name or ID>>+]
+ [B<-pr> <I<prefix of volume whose VLDB entry is to be deleted>>]
+ [B<-s> <I<machine name>>] [B<-pa> <I<partition name>>]
+ [B<-c> <I<cell name>>] [B<-n>] [B<-l>] [B<-v>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<vos delentry> command removes the Volume Location Database (VLDB)
+entry for each specified volume. A specified volume can be any of the
+three types (read/write, read-only, or backup), but the entire entry is
+removed no matter which type is provided. The command has no effect on the
+actual volumes on file server machines, if they exist.
+
+This command is useful if a volume removal operation did not update the
+VLDB (perhaps because the B<vos zap> command was used), but the system
+administrator does not feel it is necessary to use the B<vos syncserv> and
+B<vos syncvldb> commands to synchronize an entire file server machine.
+
+To remove the VLDB entry for a single volume, use the B<-id> argument. To
+remove groups of volumes, combine the B<-prefix>, B<-server>, and
+B<-partition> arguments. The following list describes how to remove the
+VLDB entry for the indicated group of volumes:
+
+=over 4
+
+=item *
+
+For every volume whose name begins with a certain character string (for
+example, C<sys.> or C<user.>): use the B<-prefix> argument.
+
+=item *
+
+Every volume for which the VLDB lists a site on a certain file server
+machine: specify the file server name with the B<-server> argument.
+
+=item *
+
+Every volume for which the VLDB lists a site on a partition of the same
+name (for instance, on the F</vicepa> partition on any file server
+machine): specify the partition name with the B<-partition> argument.
+
+=item *
+
+Every volume for which the VLDB lists a site one a specific partition of a
+file server machine: specify both the B<-server> and B<-partition>
+arguments.
+
+=item *
+
+Every volume whose name begins with a certain prefix and for which the
+VLDB lists a site on a file server machine: combine the B<-prefix> and
+B<-server> arguments. Combine the B<-prefix> argument with the
+B<-partition> argument, or both the B<-server> and B<-partition>
+arguments, to remove a more specific group of volumes.
+
+=back
+
+=head1 CAUTIONS
+
+Do not use this command to remove a volume in normal circumstances; it
+does not remove a volume from the file server machine, and so is likely to
+make the VLDB inconsistent with state of the volumes on server
+machines. Use the B<vos remove> command to remove both the volume and its
+VLDB entry.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-id> <I<volume name or ID>>+
+
+Specifies the complete name or the volume ID number of each volume for
+which to remove the VLDB entry. The entire entry is removed, regardless of
+whether the read/write, read-only, or backup version is indicated.
+Provide this argument or some combination of the B<-prefix>, B<-server>,
+and B<-partition> arguments.
+
+=item B<-prefix> <I<prefix of volume entry>
+
+Specifies a character string of any length; the VLDB entry for a volume
+whose name begins with the string is removed. Include field separators
+(such as periods) if appropriate. Combine this argument with the
+B<-server> argument, B<-partition> argument, or both.
+
+=item B<-server> <I<server name>>
+
+Identifies a file server machine; if a volume's VLDB entry lists a site on
+the machine, the entry is removed. Provide the machine's IP address or its
+host name (either fully qualified or using an unambiguous
+abbreviation). For details, see L<vos(1)>.
+
+Combine this argument with the B<-prefix> argument, the B<-partition>
+argument, or both.
+
+=item B<-partition> <I<partition name>>
+
+Identifies a partition; if a volume's VLDB entry lists a site on the
+partition, the entry is removed. Provide the partition's complete name
+with preceding slash (for example, F</vicepa>) or use one of the three
+acceptable abbreviated forms. For details, see L<vos(1)>.
+
+Combine this argument with the B<-prefix> argument, the B<-server>
+argument, or both.
+
+=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<vos(1)>.
+
+=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<vos(1)>.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+F</usr/afs/etc/KeyFile> file. The B<vos> command interpreter presents it
+to the Volume Server and Volume Location Server during mutual
+authentication. Do not combine this flag with the B<-cell> argument or
+B<-noauth> flag. For more details, see L<vos(1)>.
+
+=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.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+The following message confirms the success of the command by indicating
+how many VLDB entries were removed.
+
+ Deleted <number> VLDB entries
+
+=head1 EXAMPLES
+
+The following command removes the VLDB entry for the volume C<user.temp>.
+
+ % vos delentry user.temp
+
+The following command removes the VLDB entry for every volume whose name
+begins with the string C<test> and for which the VLDB lists a site on the
+file server machine C<fs3.abc.com>.
+
+ % vos delentry -prefix test -server fs3.abc.com
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the F</usr/afs/etc/UserList> file on the
+machine specified with the B<-server> argument and on each database server
+machine. 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<vos(1)>,
+L<vos_remove(1)>,
+L<vos_syncserv(1)>,
+L<vos_syncvldb(1)>,
+L<vos_zap(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
+
+vos dump - Converts a volume into ASCII format and writes it to a file
+
+=head1 SYNOPSIS
+
+B<vos dump> B<-id> <I<volume name or ID>> [B<-time> <I<dump from time>>]
+ [B<-file> <I<dump file>>] [B<-server> <I<server>>]
+ [B<-partition> <I<partition>>] [B<-cell> <I<cell name>>]
+ [B<-noauth>] [B<-localauth>] [B<-verbose>] [B<-help>]
+
+B<vos du> B<-i> <I<volume name or ID>> [B<-t> <I<dump from time>>]
+ [B<-f> <I<dump file>>] [B<-s> <I<server>>] [B<-p> <I<partition>>]
+ [B<-c> <I<cell name>>] [B<-n>] [B<-l>] [B<-v>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<vos dump> command converts the contents of the indicated volume,
+which can be read/write, read-only or backup, into ASCII format. The
+Volume Server writes the converted contents to the file named by the
+B<-file> argument, or to the standard output stream. In the latter case,
+the output can be directed to a named pipe, which enables interoperation
+with third-party backup utilities.
+
+To dump the complete contents of a volume (create a I<full dump>), omit
+the B<-time> argument or specify the value C<0> (zero) for it. To create
+an I<incremental dump>, which includes only the files and directories in
+the volume that have modification timestamps later than a certain time,
+specify a date and time as the value for the B<-time> argument.
+
+By default, the vos command interpreter consults the Volume Location
+Database (VLDB) to learn the volume's location, so the B<-server> and
+B<-partition> arguments are not required. If the B<-id> argument
+identifies a read-only volume that resides at multiple sites, the command
+dumps the version from just one of them (normally, the one listed first in
+the volume's VLDB entry as reported by the B<vos examine> or B<vos
+listvldb> command). To dump the read-only volume from a particular site,
+use the B<-server> and B<-partition> arguments to specify the site. To
+bypass the VLDB lookup entirely, provide a volume ID number (rather than a
+volume name) as the value for the B<-id> argument, together with the
+B<-server> and B<-partition> arguments. This makes it possible to dump a
+volume for which there is no VLDB entry.
+
+During the dump operation, the volume is inaccessible both to Cache
+Managers and to other volume operations. Dumping a volume does not
+otherwise affect its status on the partition or its VLDB entry.
+
+To restore a dumped volume back into AFS, use the B<vos restore> command.
+
+=head1 CAUTIONS
+
+Support for incremental dumps is provided to facilitate interoperation
+with third-party backup utilities. The B<vos dump> command does not
+provide any of the administrative facilities of an actual backup system,
+so the administrator must keep manual records of dump times and the
+relationship between full and incremental dumps of a volume. For a
+volume's contents to be consistent after restoration of incremental dumps,
+there must be no gap between the time at which a prior dump of the volume
+was created and the value of the B<-time> argument to the B<vos dump>
+command that creates the incremental dump. More specifically, for a
+read/write volume, the B<-time> argument must specify the time that the
+prior dump was performed, and for a read-only or backup volume it must
+specify the time that the volume was last released (using the B<vos
+release> command) or cloned (using the B<vos backup> or B<vos backupsys>
+command) prior to dumping it. The parent dump can be either a full dump or
+another incremental dump.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-id> <I<volume name or ID>>
+
+Specifies either the complete name or volume ID number of the read/write,
+read-only, or backup volume to dump.
+
+=item B<-time> <I<dump from time>>
+
+Specifies whether the dump is full or incremental. Omit this argument to
+create a full dump, or provide one of three acceptable values:
+
+=over 4
+
+=item *
+
+The value C<0> (zero) to create a full dump.
+
+=item *
+
+A date in the format I<mm>B</>I<dd>B</>I<yyyy> (month, day and year) to
+create an incremental dump that includes only files and directories with
+modification timestamps later than midnight (12:00 a.m.) on the indicated
+date. 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 2038. The command interpreter automatically reduces
+later dates to the maximum value. An example is C<01/13/1999>.
+
+=item *
+
+A date and time in the format B<">I<mm>B</>I<dd>B</>I<yyyy>
+I<hh>B<:>I<MM>B<"> to create an incremental dump that includes only files
+and directories with modification timestamps later than the specified date
+and time. The date format is the same as for a date alone. Express the
+time as hours and minutes (I<hh>:I<MM>) in 24-hour format (for example,
+B<20:30> is 8:30 p.m.). Surround the entire expression with double quotes
+(C<"">) because it contains a space. An example is C<"01/13/1999 22:30">.
+
+=back
+
+=item B<-file> <I<dump file>>
+
+Specifies the pathname of the file to which to write the dump. The file
+can be in AFS, but not in the volume being dumped. A partial pathname is
+interpreted relative to the current working directory. If this argument is
+omitted, the dump is directed to the standard output stream.
+
+=item B<-server> <I<server name>>
+
+Specifies the file server machine on which the volume resides. Provide
+the B<-partition> argument along with this one.
+
+=item B<-partition> <I<partition name>>
+
+Specifies the partition on which the volume resides. Provide the
+B<-server> argument along with this one.
+
+=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<vos(1)>.
+
+=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 L<vos(1)>.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+F</usr/afs/etc/KeyFile> file. The B<vos> command interpreter presents it
+to the Volume Server and Volume Location Server during mutual
+authentication. Do not combine this flag with the B<-cell> argument or
+B<-noauth> flag. For more details, see L<vos(1)>.
+
+=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.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command writes a full dump of the volume C<user.terry> to
+the file F</afs/abc.com/common/dumps/terry.dump>.
+
+ % vos dump -id user.terry -time 0 -file /afs/abc.com/common/dumps/terry.dump
+
+The following command writes an incremental dump of the volume
+C<user.smith> to the file C<smith.990131.dump> in the current working
+directory. Only those files in the volume with modification time stamps
+later than 6:00 p.m. on 31 January 1999 are included in the dump.
+
+ % vos dump -id user.smith -time "01/31/1999 18:00" -file smith.990131.dump
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the F</usr/afs/etc/UserList> file on the
+machine specified with the B<-server> argument and on each database server
+machine. If the B<-localauth> flag is included, the issuer must instead be
+logged on to a server machine as the local superuser C<root>.
+
+If the B<-file> argument is included, the issuer must also have permission
+to insert and write in the directory that houses the file.
+
+=head1 SEE ALSO
+
+L<vos(1)>,
+L<vos_examine(1)>,
+L<vos_listvldb(1)>,
+L<vos_restore(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
+
+vos examine - Shows volume header and VLDB entry information for a volume
+
+=head1 SYNOPSIS
+
+B<vos examine> B<-id> <I<volume name or ID>> [B<-extended>]
+ [B<-cell> <I<cell name>>] [B<-noauth>] [B<-localauth>] [B<-verbose>]
+ [B<-help>]
+
+B<vos e> B<-i> <I<volume name or ID>> [B<-e>] [B<-c> <I<cell name>>]
+ [B<-n>] [B<-l>] [B<-v>] [B<-h>]
+
+B<vos volinfo> B<-i> <I<volume name or ID>> [B<-e>] [-c <I<cell name>>]
+ [B<-n>] [B<-l>] [B<-v>] [B<-h>]
+
+B<vos v> B<-i> <I<volume name or ID>> [B<-e>] [B<-c> <I<cell name>>]
+ [B<-n>] [B<-l>] [B<-v>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<vos examine> command formats and displays information from the
+Volume Location Database (VLDB) entry and the volume header of the volume
+specified by the B<-id> argument.
+
+To display the volume header only, use the B<vos listvol> command. To
+display information from the VLDB only, use the B<vos listvldb> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-id> <I<volume name or ID>>
+
+Specifies either the complete name or volume ID number of the volume,
+which can be read/write, read-only, or backup.
+
+=item B<-extended>
+
+Display statistics about read and write operations on files and
+directories in the volume.
+
+=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<vos(1)>.
+
+=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<vos(1)>.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+F</usr/afs/etc/KeyFile> file. The B<vos> command interpreter presents it
+to the Volume Server and Volume Location Server during mutual
+authentication. Do not combine this flag with the B<-cell> argument or
+B<-noauth> flag. For more details, see L<vos(1)>.
+
+=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.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+The first seven lines of the output show information from the volume
+header and the remaining lines come from the VLDB. Each item in the
+following list corresponds to a line of output derived from the volume
+header.
+
+=over 4
+
+=item *
+
+Basic information about the specified volume (displayed on a single
+line):
+
+=over 4
+
+=item *
+
+Name
+
+=item *
+
+Volume ID number
+
+=item *
+
+Type (the flag is C<RW> for read/write, C<RO> for read-only, C<BK> for
+backup)
+
+=item *
+
+Size in kilobytes (C<1024> equals a megabyte)
+
+=item *
+
+Number of files in the volume, if the B<-extended> flag is provided
+
+=item *
+
+Status on the file server machine, which is one of the following:
+
+=over 4
+
+=item On-line
+
+The volume is completely accessible to Cache Managers.
+
+=item Off-line
+
+The volume is not accessible to Cache Managers, but does not seem to be
+corrupted. This status appears while a volume is being dumped, for
+example.
+
+=item Off-line**needs salvage**
+
+The volume is not accessible to Cache Managers, because it seems to be
+corrupted. Use the B<bos salvage> or B<salvager> command to repair the
+corruption.
+
+=back
+
+=back
+
+=item *
+
+The file server machine and partition that house the volume, as determined
+by the command interpreter as the command runs, rather than derived from
+the VLDB or the volume header.
+
+=item *
+
+The volume ID numbers associated with the various versions of the volume:
+read/write (C<RWrite>), read-only (C<ROnly>), backup (C<Backup>), and
+ReleaseClone (C<RClone>). One of them matches the volume ID number that
+appears on the first line of the volume's output. If the value in the
+C<RWrite>, C<ROnly>, or C<Backup> field is C<0> (zero), there is no volume
+of that type. If there is currently no ReleaseClone, the C<RClone> field
+does not appear at all.
+
+=item *
+
+The maximum space quota allotted to the read/write copy of the volume,
+expressed in kilobyte blocks in the C<MaxQuota> field.
+
+=item *
+
+The date and time the volume was created, in the C<Creation> field. If the
+volume has been restored with the B<backup diskrestore>, B<backup
+volrestore>, or B<vos restore> command, this is the restore time.
+
+=item *
+
+The date and time when the contents of the volume last changed, in the
+C<Last Update> field. For read-only and backup volumes, it matches the
+timestamp in the C<Creation> field.
+
+=item *
+
+The number of times the volume has been accessed for a fetch or store
+operation since the later of the two following times:
+
+=over 4
+
+=item *
+
+12:00 a.m. on the day the command is issued
+
+=item *
+
+The last time the volume changed location
+
+=back
+
+=back
+
+When the B<-extended> flag is included, two tables appear next:
+
+=over 4
+
+=item *
+
+The table labeled C<Raw Read/Write Stats> contains information on the
+number of reads (fetches) and writes (stores) made on the specified
+volume.
+
+=item *
+
+The table labeled C<Writes Affecting Authorship> contains information on
+writes made to files and directories in the specified volume.
+
+=back
+
+If the following message appears instead of the previously listed
+information, it indicates that a volume is not accessible to Cache
+Managers or the B<vos> command interpreter, for example because a clone is
+being created.
+
+ **** Volume <volume_ID> is busy ****
+
+If the following message appears instead of the previously listed
+information, it indicates that the File Server is unable to attach the
+volume, perhaps because it is seriously corrupted. The F<FileLog> and
+F<VolserLog> log files in the F</usr/afs/logs> directory on the file
+server machine possibly provide additional information; use the B<bos
+getlog> command to display them.
+
+ **** Could not attach volume <volume_ID> ****
+
+Following a blank line, information from the VLDB entry appears. Each
+item in this list corresponds to a separate line in the output:
+
+=over 4
+
+=item *
+
+The base (read/write) volume name. The read-only and backup versions have
+the same name with a C<.readonly> and C<.backup> extension, respectively.
+
+=item *
+
+The volume ID numbers allocated to the versions of the volume that
+actually exist, in fields labeled C<RWrite> for the read/write, C<ROnly>
+for the read-only, C<Backup> for the backup, and C<RClone> for the
+ReleaseClone. (If a field does not appear, the corresponding version of
+the volume does not exist.) The appearance of the C<RClone> field normally
+indicates that a release operation did not complete successfully; the
+C<Old release> and C<New release> flags often also appear on one or more
+of the site definition lines described just following.
+
+=item *
+
+The number of sites that house a read/write or read-only copy of the
+volume, following the string C<< number of sites -> >>.
+
+=item *
+
+A line for each site that houses a read/write or read-only copy of the
+volume, specifying the file server machine, partition, and type of volume
+(C<RW> for read/write or C<RO> for read-only). If a backup version exists,
+it is understood to share the read/write site. Several flags can appear
+with a site definition:
+
+=over 4
+
+=item Not released
+
+Indicates that the vos release command has not been issued since the B<vos
+addsite> command was used to define the read-only site.
+
+=item Old release
+
+Indicates that a vos release command did not complete successfully,
+leaving the previous, obsolete version of the volume at this site.
+
+=item New release
+
+Indicates that a vos release command did not complete successfully, but
+that this site did receive the correct new version of the volume.
+
+=back
+
+=item *
+
+If the VLDB entry is locked, the string C<Volume is currently LOCKED>.
+
+=back
+
+For further discussion of the C<New release> and C<Old release> flags, see
+L<vos_release(1)>.
+
+=head1 EXAMPLES
+
+The following example shows output for the ABC Corporation volume called
+C<usr> with two read-only replication sites (this volume is mounted at the
+F</afs/abc.com/usr> directory). For the sake of illustration, the output
+shows the volume as locked.
+
+ % vos examine usr
+ usr 536870981 RW 3459 K On-line
+ fs2.abc.com /vicepb
+ RWrite 5360870981 ROnly 536870982 Backup 536870983
+ MaxQuota 40000 K
+ Creation Mon Jun 12 15:22:06 1989
+ Last Update Fri Jun 16 09:34:35 1989
+ 5719 accesses in the past day (i.e., vnode references)
+ RWrite: 5360870981 ROnly: 536870982 Backup: 536870983
+ number of sites -> 3
+ server fs1.abc.com partition /vicepa RO Site
+ server fs3.abc.com partition /vicepa RO Site
+ server fs2.abc.com partition /vicepb RW Site
+ Volume is currently LOCKED
+
+The following example shows the output for the volume C<user.terry> using
+the B<-extended> flag. The volume has no read-only replication sites.
+
+ % vos examine -id user.terry -extended
+ user.terry 354287190 RW 2302 K used 119 files On-line
+ fs4.abc.com /vicepc
+ RWrite 354287190 ROnly 0 Backup 354287192
+ MaxQuota 5000 K
+ Creation Wed Nov 25 17:38:57 1992
+ Last Update Tue Dec 15 10:46:20 1992
+ 598 accesses in the past day (i.e., vnode references)
+ Raw Read/Write Stats
+ |-------------------------------------------|
+ | Same Network | Diff Network |
+ |----------|----------|----------|----------|
+ | Total | Auth | Total | Auth |
+ |----------|----------|----------|----------|
+ Reads | 55 | 55 | 38 | 38 |
+ Writes | 95 | 95 | 0 | 0 |
+ |-------------------------------------------|
+ Writes Affecting Authorship
+ |-------------------------------------------|
+ | File Authorship | Directory Authorship|
+ |----------|----------|----------|----------|
+ | Same | Diff | Same | Diff |
+ |----------|----------|----------|----------|
+ 0-60 sec | 38 | 0 | 21 | 1 |
+ 1-10 min | 2 | 0 | 7 | 0 |
+ 10min-1hr | 0 | 0 | 1 | 0 |
+ 1hr-1day | 1 | 0 | 5 | 1 |
+ 1day-1wk | 0 | 0 | 0 | 0 |
+ > 1wk | 0 | 0 | 0 | 0 |
+ |-------------------------------------------|
+ RWrite: 354287190 Backup: 354287192
+ number of sites -> 1
+ server fs4.abc.com partition /vicepc RW Site
+
+=head1 PRIVILEGE REQUIRED
+
+None
+
+=head1 SEE ALSO
+
+L<backup_diskrestore(8)>,
+L<backup_volrestore(8)>,
+L<bos_getlog(1)>,
+L<bos_salvage(1)>,
+L<salvager(8)>,
+L<vos(1)>,
+L<vos_listvol(1)>,
+L<vos_listvldb(1)>,
+L<vos_release(1)>,
+L<vos_restore(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
+
+vos help - Displays help for vos commands
+
+=head1 SYNOPSIS
+
+B<vos help> [B<-topic> <I<help string>>+] [B<-help>]
+
+B<vos h> [B<-t> <I<help string>>+] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<vos 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<vos> command.
+
+To list every B<vos> command whose name or short description includes a
+specified keyword, use the B<vos apropos> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-topic> <I<help string>>+
+
+Identifies each command for which to display the complete online help
+entry. Omit the B<vos> part of the command name, providing only the
+operation code (for example, specify B<create>, not B<vos create>). If
+this argument is omitted, the output briefly describes every B<vos>
+command.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+The online help entry for each B<vos> 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 B<vos create>
+command:
+
+ % vos help create
+ vos create: create a new volume
+ Usage: vos create -server <machine name> -partition <partition name>
+ -name <volume name> [-cell <cell name>] [-noauth] [-localauth]
+ [-verbose] [-help]
+
+=head1 PRIVILEGE REQUIRED
+
+None
+
+=head1 SEE ALSO
+
+L<vos(1)>,
+L<vos_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
+
+vos listaddrs - Displays all VLDB server entries
+
+=head1 SYNOPSIS
+
+B<vos listaddrs> [B<-cell> <I<cell name>>] [B<-noauth>]
+ [B<-localauth>] [B<-verbose>] [B<-help>]
+
+B<vos lista> [B<-c> <I<cell name>>] [B<-n>] [B<-l>] [B<-v>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<vos listaddrs> command displays all of the server entries from the
+Volume Location Database (VLDB). An entry is created as the File Server
+initializes and registers the contents of its F</usr/afs/local/sysid> file
+in the VLDB.
+
+=head1 OPTIONS
+
+=over 4
+
+=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<vos(1)>.
+
+=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 L<vos(1)>.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+F</usr/afs/etc/KeyFile> file. The B<vos> command interpreter presents it
+to the Volume Server and Volume Location Server during mutual
+authentication. Do not combine this flag with the B<-cell> argument or
+B<-noauth> flag. For more details, see L<vos(1)>.
+
+=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.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+The output displays all server entries from the VLDB, each on its own
+line. If a file server machine is multihomed, all of its registered
+addresses appear on the line. The first one is the one reported as a
+volume's site in the output from the B<vos examine> and B<vos listvldb>
+commands.
+
+The VLDB records IP addresses, and the command interpreter has the local
+name service (either a process like the Domain Name Service or a local
+host table) translate them to hostnames before displaying them. If an IP
+address appears in the output, it is not possible to translate it.
+
+The existence of an entry does not necessarily indicate that the machine
+that is still an active file server machine. To remove obsolete server
+entries, use the B<vos changeaddr> command with the B<-remove> argument.
+
+=head1 EXAMPLES
+
+The following command displays the VLDB server entries in the ABC
+Corporation cell:
+
+ % vos listaddrs
+ sv5.abc.com
+ sv1.abc.com
+ sv2.abc.com afs2.abc.com
+ sv6.abc.com
+
+=head1 PRIVILEGE REQUIRED
+
+None
+
+=head1 SEE ALSO
+
+L<sysid(5)>,
+L<vos(1)>,
+L<vos_changeaddr(1)>,
+L<vos_examine(1)>,
+L<vos_listvldb(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
+
+vos listpart - Displays all AFS partitions on a file server machine
+
+=head1 SYNOPSIS
+
+B<vos listpart> B<-server> <I<machine name>> [B<-cell> <I<cell name>>]
+ [B<-noauth>] [B<-localauth>] [B<-verbose>] [B<-help>]
+
+B<vos listp> B<-s> <I<machine name>> [B<-c> <I<cell name>>] [B<-n>]
+ [B<-l>] [B<-v>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<vos listpart> command displays all of the valid AFS partitions on
+the indicated file server machine, without consulting the Volume Location
+Database (VLDB). The B<vos partinfo> command reports the size of a
+partition and the available space on that partition.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-server> <I<server name>>
+
+Identifies the file server machine for which to list the partitions.
+Provide the machine's IP address or its host name (either fully qualified
+or using an unambiguous abbreviation). For details, see L<vos(1)>.
+
+=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<vos(1)>.
+
+=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 L<vos(1)>.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+B</usr/afs/etc/KeyFile> file. The B<vos> command interpreter presents it
+to the Volume Server and Volume Location Server during mutual
+authentication. Do not combine this flag with the B<-cell> argument or
+B<-noauth> flag. For more details, see L<vos(1)>.
+
+=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.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+The output consists of a list of partition names of the form
+F</vicepI<xx>>, following the header:
+
+ The partitions on the server are:
+
+The last line of the output reports the total number of partitions.
+
+=head1 EXAMPLES
+
+The following command displays the partitions on C<fs1.abc.com>:
+
+ % vos listpart fs1.abc.com
+ The partitions on the server are:
+ /vicepa /vicepb /vicepc /vicepd
+ Total: 4
+
+=head1 PRIVILEGE REQUIRED
+
+None
+
+=head1 SEE ALSO
+
+L<vos(1)>,
+L<vos_partinfo(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
+
+vos listvldb - Displays a volume's VLDB entry
+
+=head1 SYNOPSIS
+
+B<vos listvldb> [B<-name> <I<volume name or ID>>]
+ [B<-server> <I<machine name>>] [B<-partition> <I<partition name>>]
+ [B<-locked>] [B<-quiet>] [B<-nosort>] [B<-cell> <I<cell name>>]
+ [B<-noauth>] [B<-localauth>] [B<-verbose>] [B<-help>]
+
+B<vos listvl> [B<-na> <I<volume name or ID>>] [B<-s> <I<machine name>>]
+ [B<-p> <I<partition name>>] [B<-lock>] [B<-q>] [B<-nos>]
+ [B<-c> <I<cell name>>] [B<-noa>] [B<-loca>] [B<-v>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<vos listvldb> command formats and displays information from the
+Volume Location Database (VLDB) entry for each volume specified. The
+output depends on the combination of options supplied on the command
+line. Combine options as indicated to display the desired type of VLDB
+entries:
+
+=over 4
+
+=item *
+
+Every entry in the VLDB: provide no options.
+
+=item *
+
+Every VLDB entry that mentions a certain file server machine as the site
+for a volume: specify the machine's name as the B<-server> argument.
+
+=item *
+
+Every VLDB entry that mentions a certain partition on any file server
+machine as the site for a volume: specify the partition name as the
+B<-partition> argument.
+
+=item *
+
+Every VLDB entry that mentions a certain partition on a certain file
+server machine as the site for a volume: combine the B<-server> and
+B<-partition> arguments.
+
+=item *
+
+A single VLDB entry: specify a volume name or ID number with the B<-name>
+argument.
+
+=item *
+
+The VLDB entry only for the volumes with locked VLDB entries found at a
+certain site: combine the B<-locked> flag with any of arguments that
+define sites.
+
+=back
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-name> <I<volume name or ID>>
+
+Specifies either the complete name or volume ID number of a volume of any
+of the three types.
+
+=item B<-server> <I<server name>>
+
+Identifies the file server machine listed as a site in each VLDB entry to
+display. Provide the machine's IP address or its host name (either fully
+qualified or using an unambiguous abbreviation). For details, see
+L<vos(1)>.
+
+This argument can be combined with the B<-partition> argument, the
+B<-locked> flag, or both.
+
+=item B<-partition> <I<partition name>>
+
+Identifies the partition (on the file server machine specified by the
+B<-server> argument) listed as a site in each VLDB entry to
+display. Provide the partition's complete name with preceding slash (for
+example, C</vicepa>) or use one of the three acceptable abbreviated
+forms. For details, see L<vos(1)>.
+
+This argument can be combined with the B<-server> argument, the B<-locked>
+flag, or both.
+
+=item B<-locked>
+
+Displays only locked VLDB entries. This flag can be combined with the
+B<-server> argument, the B<-partition> argument, or both.
+
+=item B<-quiet>
+
+Suppresses the lines that summarize the number of volumes listed and their
+status, which otherwise appear at the beginning and end of the output when
+the output includes more than one volume.
+
+=item B<-nosort>
+
+Suppresses the default sorting of volume entries alphabetically by volume
+name.
+
+=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<vos(1)>.
+
+=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<vos(1)>.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+F</usr/afs/etc/KeyFile> file. The B<vos> command interpreter presents it
+to the Volume Server and Volume Location Server during mutual
+authentication. Do not combine this flag with the B<-cell> argument or
+B<-noauth> flag. For more details, see L<vos(1)>.
+
+=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.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+If the output includes more than one VLDB entry, by default the first line
+reports which file server machine, partition, or both, houses the
+volumes. The final line of output reports the total number of entries
+displayed. Including the B<-quiet> flag suppresses these lines.
+
+By default, volumes are sorted alphabetically by volume name. Including
+the B<-nosort> flag skips the sorting step, which can speed up the
+production of output if there are a large number of entries.
+
+The VLDB entry for each volume includes the following information:
+
+=over 4
+
+=item *
+
+The base (read/write) volume name. The read-only and backup versions have
+the same name with a C<.readonly> and C<.backup> extension, respectively.
+
+=item *
+
+The volume ID numbers allocated to the versions of the volume that
+actually exist, in fields labeled C<RWrite> for the read/write, C<ROnly>
+for the read-only, C<Backup> for the backup, and C<RClone> for the
+ReleaseClone. (If a field does not appear, the corresponding version of
+the volume does not exist.) The appearance of the C<RClone> field normally
+indicates that a release operation did not complete successfully; the
+C<Old release> and C<New release> flags often also appear on one or more
+of the site definition lines described just following.
+
+=item *
+
+The number of sites that house a read/write or read-only copy of the
+volume, following the string C<< number of sites -> >>.
+
+=item *
+
+A line for each site that houses a read/write or read-only copy of the
+volume, specifying the file server machine, partition, and type of volume
+(C<RW> for read/write or C<RO> for read-only). If a backup version exists,
+it is understood to share the read/write site. Several flags can appear
+with a site definition:
+
+=over 4
+
+=item Not released
+
+Indicates that the vos release command has not been issued since the B<vos
+addsite> command was used to define the read-only site.
+
+=item Old release
+
+Indicates that a vos release command did not complete successfully,
+leaving the previous, obsolete version of the volume at this site.
+
+=item New release
+
+Indicates that a vos release command did not complete successfully, but
+that this site did receive the correct new version of the volume.
+
+=back
+
+=item *
+
+If the VLDB entry is locked, the string C<Volume is currently LOCKED>.
+
+=back
+
+For further discussion of the C<New release> and C<Old release> flags, see
+L<vos_release(1)>.
+
+=head1 EXAMPLES
+
+The following command displays VLDB information for the ABC Corporation
+volume called C<usr>, which has two read-only replication sites:
+
+ % vos listvldb -name usr
+ usr
+ RWrite: 5360870981 ROnly: 536870982 Backup: 536870983
+ number of sites -> 3
+ server fs1.abc.com partition /vicepa RO Site
+ server fs3.abc.com partition /vicepa RO Site
+ server fs2.abc.com partition /vicepb RW Site
+
+The following example shows entries for two of the volumes that reside on
+the file server machine C<fs4.abc.com>. The first VLDB entry is currently
+locked. There are 508 entries that mention the machine as a volume site.
+
+ % vos listvldb -server fs4.abc.com
+ VLDB entries for server fs4.abc.com
+ . . . .
+ . . . .
+ user.smith
+ RWrite: 278541326 ROnly: 278541327 Backup: 278542328
+ number of sites -> 1
+ server fs4.abc.com partition /vicepg RW Site
+ Volume is currently LOCKED
+ user.terry
+ RWrite 354287190 ROnly 354287191 Backup 354287192
+ number of sites -> 1
+ server fs4.abc.com partition /vicepc RW Site
+ . . . .
+ . . . .
+ Total entries: 508
+
+=head1 PRIVILEGE REQUIRED
+
+None
+
+=head1 SEE ALSO
+
+L<vos(1)>,
+L<vos_examine(1)>,
+L<vos_listvol(1)>,
+L<vos_lock(1)>,
+L<vos_unlock(1)>,
+L<vos_unlockvldb(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
+
+vos listvol - Displays information from a volume header
+
+=head1 SYNOPSIS
+
+B<vos listvol> B<-server> <I<machine name>>
+ [B<-partition> <I<partition name>>] [B<-fast>] [B<-long>] [B<-quiet>]
+ [B<-extended>] [B<-cell> <I<cell name>>] [B<-noauth>] [B<-localauth>]
+ [B<-verbose>] [B<-help>]
+
+B<vos listvo> B<-s> <I<machine name>> [B<-p> <I<partition name>>] [B<-f>]
+ [-lon] [B<-q>] [B<-e>] [B<-c> <I<cell name>>] [B<-n>] [B<-loc>]
+ [B<-v>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<vos listvol> command formats and displays the following information
+from the volume header of each specified volume: volume name, volume ID,
+volume type, size, and status at the server. The actual information
+displayed depends on the combination of arguments supplied when the
+command is issued. To display volume header information for various
+numbers of volumes, combine the command's arguments as indicated:
+
+=over 4
+
+=item *
+
+For every volume on a file server machine, specify the machine's name with
+the B<-server> argument.
+
+=item *
+
+For every volume at a particular site, combine the B<-server> argument
+with the B<-partition> argument.
+
+=back
+
+To display the Volume Location Database (VLDB) entry for one or more
+volumes, use the B<vos listvldb> command. To display both the VLDB entry
+and the volume header for a single volume, use the B<vos examine> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-server> <I<server name>>
+
+Identifies the file server machine that houses volumes for which to
+display the header. Provide the machine's IP address or its host name
+(either fully qualified or using an unambiguous abbreviation). For
+details, see L<vos(1)>.
+
+This argument can be combined with the B<-partition> argument, as well as
+the B<-fast>, B<-long>, or B<-extended> flag.
+
+=item B<-partition> <I<partition name>>
+
+Identifies the partition (on the file server machine specified by the
+B<-server> argument) that houses volumes for which to display the
+header. Provide the partition's complete name with preceding slash (for
+example, F</vicepa>) or use one of the three acceptable abbreviated
+forms. For details, see L<vos(1)>.
+
+=item B<-fast>
+
+Displays only the volume ID numbers of volumes stored at the site
+specified by the B<-server>, and optionally B<-partition>, argument. Do
+not combine this flag with the B<-extended> flag.
+
+=item B<-long>
+
+Displays more detailed information about each volume stored at the site
+specified by the B<-server>, and optionally B<-partition>, argument. The
+information includes the volume IDs of all three volume types associated
+with the volume, and the read/write volume's quota, creation date and
+update date.
+
+=item B<-quiet>
+
+Suppresses the lines that summarize the number of volumes listed and their
+status, which otherwise appear at the beginning and end of the output when
+the output includes more than one volume.
+
+=item B<-extended>
+
+Displays extensive statistics about access patterns for each volume stored
+at the site specified by the B<-server>, and optionally B<-partition>,
+argument. The statistics include the number of reads and writes to files
+in the volume, and how recently files and directories have been updated by
+their owners or other users. Do not combine this flag with the B<-fast>
+flag.
+
+=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<vos(1)>.
+
+=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<vos(1)>.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+F</usr/afs/etc/KeyFile> file. The B<vos> command interpreter presents it
+to the Volume Server and Volume Location Server during mutual
+authentication. Do not combine this flag with the B<-cell> argument or
+B<-noauth> flag. For more details, see L<vos(1)>.
+
+=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.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+The output is ordered alphabetically by volume name and by default
+provides the following information on a single line for each volume:
+
+=over 4
+
+=item *
+
+Name
+
+=item *
+
+Volume ID number
+
+=item *
+
+Type (the flag is C<RW> for read/write, C<RO> for read-only, C<BK> for
+backup)
+
+=item *
+
+Size in kilobytes (C<1024> equals a megabyte)
+
+=item *
+
+Number of files in the volume, if the B<-extended> flag is provided
+
+=item *
+
+Status on the file server machine, which is one of the following:
+
+=over 4
+
+=item On-line
+
+The volume is completely accessible to Cache Managers.
+
+=item Off-line
+
+The volume is not accessible to Cache Managers, but does not seem to be
+corrupted. This status appears while a volume is being dumped, for
+example.
+
+=item Off-line**needs salvage**
+
+The volume is not accessible to Cache Managers, because it seems to be
+corrupted. Use the B<bos salvage> or B<salvager> command to repair the
+corruption.
+
+=back
+
+=back
+
+If the following message appears instead of the previously listed
+information, it indicates that a volume is not accessible to Cache
+Managers or the B<vos> command interpreter, for example because a clone is
+being created.
+
+ **** Volume <volume_ID> is busy ****
+
+If the following message appears instead of the previously listed
+information, it indicates that the File Server is unable to attach the
+volume, perhaps because it is seriously corrupted. The F<FileLog> and
+F<VolserLog> log files in the F</usr/afs/logs> directory on the file
+server machine possibly provide additional information; use the B<bos
+getlog> command to display them.
+
+ **** Could not attach volume <volume_ID> ****
+
+The information about individual volumes is bracketed by summary
+lines. The first line of output specifies the number of volumes in the
+listing. The last line of output summarizes the number of volumes that are
+online, offline, and busy. These lines do not appear if the B<-quiet> flag
+is used.
+
+If the B<-fast> flag is added, the output displays only the volume ID
+number of each volume, arranged in increasing numerical order. The final
+line (which summarizes the number of online, offline, and busy volumes) is
+omitted.
+
+If the B<-long> flag is included, the output for each volume includes all
+of the information in the default listing plus the following. Each item in
+this list corresponds to a separate line of output:
+
+=over 4
+
+=item *
+
+The file server machine and partition that house the volume, as determined
+by the command interpreter as the command runs, rather than derived from the
+VLDB or the volume header.
+
+=item *
+
+The volume ID numbers associated with the various versions of the volume:
+read/write (C<RWrite>), read-only (C<ROnly>), backup (C<Backup>), and
+ReleaseClone (C<RClone>). One of them matches the volume ID number that
+appears on the first line of the volume's output. If the value in the
+C<RWrite>, C<ROnly>, or C<Backup> field is C<0> (zero), there is no volume
+of that type. If there is currently no ReleaseClone, the C<RClone> field
+does not appear at all.
+
+=item *
+
+The maximum space quota allotted to the read/write copy of the volume,
+expressed in kilobyte blocks in the C<MaxQuota> field.
+
+=item *
+
+The date and time the volume was created, in the C<Creation> field. If the
+volume has been restored with the B<backup diskrestore>, B<backup
+volrestore>, or B<vos restore> command, this is the restore time.
+
+=item *
+
+The date and time when the contents of the volume last changed, in the
+C<Last Update> field. For read-only and backup volumes, it matches the
+timestamp in the C<Creation> field.
+
+=item *
+
+The number of times the volume has been accessed for a fetch or store
+operation since the later of the two following times:
+
+=over 4
+
+=item *
+
+12:00 a.m. on the day the command is issued
+
+=item *
+
+The last time the volume changed location
+
+=back
+
+=back
+
+If the B<-extended> flag is included, the output for each volume includes
+all of the information reported with the B<-long> flag, plus two tables of
+statistics:
+
+=over 4
+
+=item *
+
+The table labeled C<Raw Read/Write Stats> table summarizes the number of
+times the volume has been accessed for reading or writing.
+
+=item *
+
+The table labeled C<Writes Affecting Authorship> table contains
+information on writes made to files and directories in the specified
+volume.
+
+=back
+
+=head1 EXAMPLES
+
+The following example shows the output for the F</vicepb> partition on the
+file server machine C<fs2.abc.com> when no flags are provided:
+
+ % vos listvol -server fs2.abc.com -partition b
+ Total number of volumes on server fs2.abc.com partition /vicepb : 66
+ sys 1969534847 RW 1582 K On-line
+ sys.backup 1969535105 BK 1582 K On-line
+ . . . . . .
+ . . . . . .
+ user.pat 1969534536 RW 17518 K On-line
+ user.pat.backup 1969534538 BK 17537 K On-line
+ Total volumes onLine 66 ; Total volumes offLine 0 ; Total busy 0
+
+The following example shows the output when the B<-fast> flag is added:
+
+ % vos listvol -server fs2.abc.com -partition b -fast
+ Total number of volumes on server fs2.abc.com partition /vicepb : 66
+ 1969516782
+ 1969516784
+ .
+ .
+ 1969535796
+
+The following example shows two volumes from the output that appears when
+the B<-long> flag is added:
+
+ % vos listvol -server fs2.abc.com -partition b -long
+ Total number of volumes on server fs2.abc.com partition /vicepb: 66
+ . . . . . .
+ . . . . . .
+ user.pat 1969534536 RW 17518 K On-line
+ fs2.abc.com /vicepb
+ RWrite 1969534536 ROnly 0 Backup 1969534538
+ MaxQuota 20000 K
+ Creation Mon Jun 12 09:02:25 1989
+ Last Update Thu May 20 17:39:34 1999
+ 1573 accesses in the past day (i.e., vnode references)
+ user.pat.backup 1969534538 BK 17537 K On-line
+ fs2.abc.com /vicepb
+ RWrite 1969534536 ROnly 0 Backup 1969534538
+ MaxQuota 20000 K
+ Creation Tue Jun 13 04:37:59 1989
+ Last Update Wed May 19 06:37:59 1999
+ 0 accesses in the past day (i.e., vnode references)
+ . . . . . .
+ . . . . . .
+ Total volumes onLine 66 ; Total volumes offLine 0 ; Total busy 0
+
+=head1 PRIVILEGE REQUIRED
+
+None
+
+=head1 SEE ALSO
+
+L<backup_diskrestore(1)>,
+L<backup_volrestore(1)>,
+L<bos_getlog(1)>,
+L<bos_salvage(1)>,
+L<salvager(1)>,
+L<vos(1)>,
+L<vos_examine(1)>,
+L<vos_listvldb(1)>,
+L<vos_restore(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
+
+vos lock - Locks a VLDB volume entry
+
+=head1 SYNOPSIS
+
+B<vos lock> B<-id> <I<volume name or ID>> [B<-cell> <I<cell name>>]
+ [B<-noauth>] [B<-localauth>] [B<-verbose>] [B<-help>]
+
+B<vos lo> B<-i> <I<volume name or ID>> [B<-c> <I<cell name>>] [B<-n>]
+ [B<-l>] [B<-v>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<vos lock> command locks the Volume Location Database (VLDB) entry
+for the indicated volume, blocking any operation that requires a write to
+that entry. The lock applies to all of the volume versions associated with
+the entry, not just the one specified with the B<-id> argument.
+
+To unlock a single VLDB entry, use the B<vos unlock> command. To unlock
+several entries, or all locked entries in the VLDB, use the B<vos
+unlockvldb> command.
+
+=head1 CAUTIONS
+
+Do not use this command in normal circumstances. It is useful for
+guaranteeing that the volume stays unchanged when there is reason to
+believe that volume operations cannot properly lock VLDB volume entries as
+they normally do to synchronize with one another.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-id> <I<volume name or ID>>
+
+Specifies either the complete name or volume ID number of a volume of the
+any of the three types.
+
+=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<vos(1)>.
+
+=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<vos(1)>.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+F</usr/afs/etc/KeyFile> file. The B<vos> command interpreter presents it
+to the Volume Server and Volume Location Server during mutual
+authentication. Do not combine this flag with the B<-cell> argument or
+B<-noauth> flag. For more details, see L<vos(1)>.
+
+=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.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command locks the VLDB entry for C<user.terry>.
+
+ % vos lock user.terry
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the F</usr/afs/etc/UserList> file on the
+machine specified with the B<-server> argument and on each database server
+machine. 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<vos(1)>,
+L<vos_unlock(1)>,
+L<vos_unlockvldb(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
+
+vos move - Moves a read/write volume to another site
+
+=head1 SYNOPSIS
+
+B<vos move> B<-id> <I<volume name or ID>>
+ B<-fromserver> <I<machine name on source>>
+ B<-frompartition> <I<partition name on source>>
+ B<-toserver> <I<machine name on destination>>
+ B<-topartition> <I<partition name on destination>>
+ [B<-cell> <I<cell name>>] [B<-noauth>] [B<-localauth>] [B<-verbose>]
+ [B<-help>]
+
+B<vos m -i> <I<volume name or ID>>
+ B<-froms> <I<machine name on source>>
+ B<-fromp> <I<partition name on source>>
+ B<-tos> <I<machine name on destination>>
+ B<-top> <I<partition name on destination>>
+ [-c <I<cell name>>] [B<-n>] [B<-l>] [B<-v>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<vos move> command moves the indicated read/write volume from its
+current site (specified with the B<-fromserver> and B<-frompartition>
+arguments) to the destination site (specified with the B<-toserver> and
+B<-topartition> arguments). This command automatically removes the backup
+copy from the current site, if it exists. To create a new backup volume at
+the destination site, use the B<vos backup> command.
+
+This command works on read/write volumes only. To move a read-only volume,
+use the B<vos addsite> and B<vos release> commands to define a new
+read-only site and release the volume contents to it, and then use the
+B<vos remove> command to remove the previous read-only volume's definition
+from the Volume Location Database (VLDB) and data from the partition. To
+move a backup volume, use this command to move its read/write source and
+then issue the B<vos backup> command.
+
+Before executing this command, the B<vos> command interpreter initiates a
+check that the destination partition contains enough space to house the
+volume being moved. If there is not enough space, the move operation is
+not attempted and the following message appears:
+
+ vos: no space on target partition <dest_part> to move volume <volume>
+
+=head1 CAUTIONS
+
+Unless there is a compelling reason, do not interrupt a B<vos move>
+command in progress. Interrupting a move can result in one or more of the
+following inconsistent states:
+
+=over 4
+
+=item *
+
+There are two versions of the volume, one at the source site and one at
+the destination site. (If this happens, retain the version identified by
+the VLDB and use the B<vos zap> command to remove the other version.)
+
+=item *
+
+The backup version of the volume is stranded at the old site. (If this
+happens, use the B<vos zap> command to remove it.)
+
+=item *
+
+The volume is off-line. (If this happens, run the B<bos salvage> command
+to bring it back on line.)
+
+=back
+
+If the Ctrl-C interrupt signal is pressed while a vos move operation is
+executing, the following message warns of the consequences and requests
+confirmation of the kill signal:
+
+ SIGINT handler: vos move operation in progress
+ WARNING: may leave AFS storage and metadata in indeterminate state
+ enter second control-c to exit
+
+To confirm termination of the operation, press Ctrl-C a second time; press
+any other key to continue the operation.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-id> <I<volume name or ID>>
+
+Specifies either the complete name or volume ID number of a read/write
+volume.
+
+=item B<-fromserver> <I<server name>>
+
+Identifies the file server machine where the volume currently
+resides. Provide the machine's IP address or its host name (either fully
+qualified or using an unambiguous abbreviation). For details, see
+L<vos(1)>.
+
+=item B<-frompartition> <I<partition name>>
+
+Names the partition where the volume currently resides. Provide the full
+partition name (for, example, B</vicepa>) or one of the abbreviated forms
+described in L<vos(1)>.
+
+=item B<-toserver> <I<server name>>
+
+Identifies the file server machine to which to move the volume. Provide
+the machine's IP address or its host name (either fully qualified or using
+an unambiguous abbreviation). For details, see L<vos(1)>.
+
+=item B<-topartition> <I<partition name>>
+
+Names the partition to which to move the volume. Provide the full
+partition name (for, example, B</vicepa>) or one of the abbreviated forms
+described in L<vos(1)>.
+
+=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<vos(1)>.
+
+=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<vos(1)>.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+F</usr/afs/etc/KeyFile> file. The B<vos> command interpreter presents it
+to the Volume Server and Volume Location Server during mutual
+authentication. Do not combine this flag with the B<-cell> argument or
+B<-noauth> flag. For more details, see L<vos(1)>.
+
+=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.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following example moves the volume C<user.smith> from the F</vicepb>
+partition on the file server machine C<fs3.abc.com> to the F</vicepg>
+partition on the file server machine C<fs7.abc.com>.
+
+ % vos move -id user.smith -fromserver fs3.abc.com -frompartition b \
+ -toserver fs7.abc.com -topartition g
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the F</usr/afs/etc/UserList> file on the
+machines specified with the B<-toserver> and B<-fromserver> arguments and
+on each database server machine. 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<vos(1)>,
+L<vos_addsite(1)>,
+L<vos_backup(1)>,
+L<vos_release(1)>,
+L<vos_listvol(1)>,
+L<vos_remove(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
+
+vos partinfo - Reports the available and total space on a partition
+
+=head1 SYNOPSIS
+
+B<vos partinfo> B<-server> <I<machine name>>
+ [B<-partition> <I<partition name>>] [B<-cell> <I<cell name>>]
+ [B<-noauth>] [B<-localauth>] [B<-verbose>] [B<-help>]
+
+B<vos p> B<-s> <I<machine name>> [B<-p> <I<partition name>>]
+ [B<-c> <I<cell name>>] [B<-n>] [B<-l>] [B<-v>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The vos partinfo command reports the amount of space available and total
+size on either all of the partitions on the indicated file server machine
+(if the B<-partition> argument is omitted) or the specified partition on
+that file server machine. The Volume Location Database (VLDB) is not
+consulted.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-server> <I<server name>>
+
+Identifies the file server machine for which to display partition
+information. Provide the machine's IP address or its host name (either
+fully qualified or using an unambiguous abbreviation). For details, see
+L<vos(1)>.
+
+=item B<-partition> <I<partition name>>
+
+Identifies which partition on the file server machine specified by the
+B<-server> argument for which to display information. Provide the
+partition's complete name with preceding slash (for example, C</vicepa>)
+or use one of the three acceptable abbreviated forms. For details, see
+L<vos(1)>.
+
+=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<vos(1)>.
+
+=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<vos(1)>.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+F</usr/afs/etc/KeyFile> file. The B<vos> command interpreter presents it
+to the Volume Server and Volume Location Server during mutual
+authentication. Do not combine this flag with the B<-cell> argument or
+B<-noauth> flag. For more details, see L<vos(1)>.
+
+=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.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 CAUTIONS
+
+The partition-related statistics in this command's output do not always
+agree with the corresponding values in the output of the standard UNIX
+B<df> command. The statistics reported by this command can be up to five
+minutes old, because the Cache Manager polls the File Server for partition
+information at that frequency. Also, on some operating systems, the B<df>
+command's report of partition size includes reserved space not included in
+this command's calculation, and so is likely to be about 10% larger.
+
+=head1 OUTPUT
+
+The output reports the amount of space available and total space for each
+specified partition.
+
+=head1 EXAMPLES
+
+The following command displays all partitions on the file server machine
+C<fs2.abc.com>.
+
+ % vos partinfo fs2.abc.com
+ Free space on partition /vicepa: 27301 K blocks out of total 549197
+ Free space on partition /vicepb: 13646 K blocks out of total 69194
+ Free space on partition /vicepc: 31798 K blocks out of total 320315
+ Free space on partition /vicepd: 33302 K blocks out of total 494954
+
+=head1 PRIVILEGE REQUIRED
+
+None
+
+=head1 SEE ALSO
+
+L<vos(1)>,
+L<vos_listpart(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
+
+vos release - Updates read-only volumes to match the read/write source volume
+
+=head1 SYNOPSIS
+
+B<vos release> B<-id> <I<volume name or ID>> [B<-f>]
+ [B<-cell> <I<cell name>>] [B<-noauth>] [B<-localauth>] [B<-verbose>]
+ [B<-help>]
+
+B<vos rel> B<-i> <I<volume name or ID>> [B<-f>] [B<-c> <I<cell name>>]
+ [B<-n>] [B<-l>] [B<-v>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<vos release> command copies the contents of the indicated read/write
+source volume to each read-only site defined in the source volume's Volume
+Location Database (VLDB) entry. (Use the B<vos addsite> command to define
+sites as necessary before issuing this command). Each read-only copy has
+the same name as read/write source with the addition of a C<.readonly>
+extension.
+
+For users to have a consistent view of the file system, the release of the
+new volume version must be atomic: either all read-only sites receive the
+new version, or all sites keep the version they currently have. The B<vos
+release> command is designed to ensure that all copies of the volume's
+read-only version match both the read/write source and each other. In
+cases where problems such as machine or server process outages prevent
+successful completion of the release operation, AFS uses two mechanisms to
+alert the administrator.
+
+First, the command interpreter generates an error message on the standard
+error stream naming each read-only site that did not receive the new
+volume version. Second, during the release operation the Volume Location
+(VL) Server marks site definitions in the VLDB entry with flags (C<New
+release> and C<Old release>) that indicate whether or not the site has the
+new volume version. If any flags remain after the operation completes, it
+was not successful. The Cache Manager refuses to access a read-only site
+marked with the C<Old release> flag, which potentially imposes a greater
+load on the sites marked with the C<New release> flag. It is important to
+investigate and eliminate the cause of the failure and then to issue the
+B<vos release> command as many times as necessary to complete the release
+without errors.
+
+The pattern of site flags remaining in the volume's VLDB entry after a
+failed release operation can help determine the point at which the
+operation failed. Use the B<vos examine> or B<vos listvldb> command to
+display the VLDB entry. The VL Server sets the flags in concert with the
+Volume Server's operations, as follows:
+
+=over 4
+
+=item *
+
+Before the operation begins, the VL Server sets the C<New release> flag on
+the read/write site definition in the VLDB entry and the C<Old release>
+flag on read-only site definitions (unless the read-only site has been
+defined since the last release operation and has no actual volume, in
+which case its site flag remains C<Not released>).
+
+=item *
+
+If necessary, the Volume Server creates a temporary copy (a I<clone>) of
+the read/write source called the ReleaseClone (see the following
+discussion of when the Volume Server does or does not create a new
+ReleaseClone.) It assigns the ReleaseClone its own volume ID number, which
+the VL Server records in the C<RClone> field of the source volume's VLDB
+entry.
+
+=item *
+
+The Volume Server distributes a copy of the ReleaseClone to each read-only
+site defined in the VLDB entry. As the site successfully receives the new
+clone, the VL Server sets the site's flag in the VLDB entry to C<New
+release>.
+
+=item *
+
+When all the read-only copies are successfully released, the VL Server
+clears all the C<New release> site flags. The ReleaseClone is no longer
+needed, so the Volume Server deletes it and the VL Server erases its ID
+from the VLDB entry.
+
+=back
+
+By default, the Volume Server determines automatically whether or not it
+needs to create a new ReleaseClone:
+
+=over 4
+
+=item *
+
+If there are no flags (C<New release>, C<Old release>, or C<Not released>)
+on site definitions in the VLDB entry, the previous B<vos release> command
+completed successfully and all read-only sites currently have the same
+volume. The Volume Server infers that the current B<vos release> command
+was issued because the read/write volume has changed. The Volume Server
+creates a new ReleaseClone and distributes it to all of the read-only
+sites.
+
+=item *
+
+If any site definition in the VLDB entry is marked with a flag, either the
+previous release operation did not complete successfully or a new
+read-only site was defined since the last release. The Volume Server does
+not create a new ReleaseClone, instead distributing the existing
+ReleaseClone to sites marked with the C<Old release> or C<Not released>
+flag. As previously noted, the VL Server marks each VLDB site definition
+with the C<New release> flag as the site receives the ReleaseClone, and
+clears all flags after all sites successfully receive it.
+
+=back
+
+To override the default behavior, forcing the Volume Server to create and
+release a new ReleaseClone to the read-only sites, include the B<-f>
+flag. This is appropriate if, for example, the data at the read/write site
+has changed since the existing ReleaseClone was created during the
+previous release operation.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-id> <I<volume name or id>>
+
+Specifies either the complete name or volume ID number of a read/write
+volume.
+
+=item B<-f>
+
+Creates a new ReleaseClone and distributes it all read-only sites
+regardless of whether or not any site definitions in the VLDB entry are
+marked with a flag.
+
+=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<vos(1)>.
+
+=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<vos(1)>.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+F</usr/afs/etc/KeyFile> file. The B<vos> command interpreter presents it
+to the Volume Server and Volume Location Server during mutual
+authentication. Do not combine this flag with the B<-cell> argument or
+B<-noauth> flag. For more details, see L<vos(1)>.
+
+=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.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command clones the read/write volume usr and releases it to
+the read-only sites defined in its VLDB entry.
+
+ % vos release usr
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the F</usr/afs/etc/UserList> file on the
+machine specified with the B<-server> argument and on each database server
+machine. 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<vos(1)>,
+L<vos_addsite(1)>,
+L<vos_examine(1)>,
+L<vos_listvldb(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
+
+vos remove - Removes a volume from a site
+
+=head1 SYNOPSIS
+
+B<vos remove> [B<-server> <I<machine name>>]
+ [B<-partition> <I<partition name>>]
+ B<-id> <I<volume name or ID>> [B<-cell> <I<cell name>>]
+ [B<-noauth>] [B<-localauth>] [B<-verbose>] [B<-help>]
+
+B<vos remo> [B<-s> <I<machine name>>] [B<-p> <I<partition name>>]
+ B<-i> <I<volume name or ID>> [B<-c> <I<cell name>>] [B<-n>] [B<-l>]
+ [B<-v>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<vos remove> command removes the indicated volume from the partition
+on which it resides. The Volume Location Database (VLDB) record is altered
+appropriately, as described in the following paragraphs. Use this command
+to remove any of the three types of volumes; the effect depends on the
+type.
+
+=over 4
+
+=item *
+
+If the B<-id> argument names the read/write volume (that is, specifies the
+volume's base name), both it and the associated backup volume are removed
+from the partition that houses them. The B<-server> and B<-partition>
+arguments are optional, because there can be only one read/write
+site. When the volume is removed, the site information is also removed
+from the VLDB entry. The read/write and backup volume ID numbers no longer
+appear in the output from the B<vos listvldb> or B<vos examine> commands,
+but they are preserved internally. Read-only sites, if any, are not
+affected, but cannot be changed unless a read/write site is again
+defined. The site count reported by the B<vos examine> and B<vos listvldb>
+commands as C<number of sites> decrements by one. The entire VLDB entry is
+removed if there are no read-only sites.
+
+=item *
+
+If the B<-id> argument names a read-only volume, it is removed from the
+partition that houses it, and the corresponding site information is
+removed from the VLDB entry. The site count reported by the B<vos examine>
+and B<vos listvldb> commands as C<number of sites> decrements by one for
+each volume you remove. If there is more than one read-only site, the
+B<-server> argument (and optionally B<-partition> argument) must be used
+to specify the site from which to remove the volume. If there is only one
+read-only site, the B<-id> argument is sufficient; if there is also no
+read/write volume in this case, the entire VLDB entry is removed.
+
+=item *
+
+If the B<-id> argument names a backup volume, it is removed from the
+partition that houses it. The B<-server> and B<-partition> arguments are
+optional, because there can be only one backup site. The backup volume ID
+number no longer appears in the output from the B<vos listvldb> command or
+in the corresponding portion of the output from the B<vos examine>
+command, but is preserved internally.
+
+=back
+
+This command is the most appropriate one for removing volumes in almost
+all cases. Other commands that remove only volumes or only VLDB entries
+(such as the B<vos delentry>, B<vos remsite> and B<vos zap> commands) by
+definition can put the volumes and VLDB out of sync. Use them only in the
+special circumstances mentioned on their reference pages. Like the B<vos
+delentry> command, this command can remove a VLDB entry when no
+corresponding volumes exist on the file server machine. Like the B<vos
+zap> command, this command can remove a volume that does not have a VLDB
+entry, as long as the volume is online, B<-server> and B<-partition>
+arguments are provided, and the B<-id> argument specifies the volume's ID
+number.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-server> <I<server name>>
+
+Identifies the file server machine that houses the volume to remove. It is
+necessary only when the B<-id> argument names a read-only volume that
+exists at multiple sites. Provide the machine's IP address or its host
+name (either fully qualified or using an unambiguous abbreviation). For
+details, see L<vos(1)>.
+
+=item B<-partition> <I<partition name>>
+
+Identifies the partition (on the file server machine specified by the
+B<-server> argument) that houses the volume to remove. Provide the
+partition's complete name with preceding slash (for example, C</vicepa>)
+or use one of the three acceptable abbreviated forms. For details, see
+L<vos(1)>.
+
+Including this argument is necessary only when the B<-id> argument names a
+read-only volume that exists at multiple sites. Provide the B<-server>
+argument along with this one.
+
+=item B<-id> <I<volume name or id>>
+
+Identifies the volume to remove, either by its complete name or volume ID
+number. If identifying a read-only or backup volume by name, include the
+appropriate extension (C<.readonly> or C<.backup>).
+
+=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<vos(1)>.
+
+=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<vos(1)>.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+F</usr/afs/etc/KeyFile> file. The B<vos> command interpreter presents it
+to the Volume Server and Volume Location Server during mutual
+authentication. Do not combine this flag with the B<-cell> argument or
+B<-noauth> flag. For more details, see L<vos(1)>.
+
+=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.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following example removes the read/write volume C<user.terry> and its
+backup version, if any.
+
+ % vos remove -id user.terry
+
+The following example removes the read-only volume C<root.afs.readonly>
+from one of its sites, the F</vicepa> partition on the file server machine
+C<fs1.abc.com>.
+
+ % vos remove fs1.abc.com a root.afs.readonly
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the F</usr/afs/etc/UserList> file on the
+machine specified with the B<-server> argument and on each database server
+machine. 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<vos(1)>,
+L<vos_delentry(1)>,
+L<vos_remsite(1)>,
+L<vos_zap(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
+
+vos remsite - Removes a read-only site definition from a VLDB entry
+
+=head1 SYNOPSIS
+
+B<vos remsite> B<-server> <I<machine name>>
+ B<-partition> <I<partition name>> B<-id> <I<volume name or ID>>
+ [B<-cell> <I<cell name>>] [B<-noauth>] [B<-localauth>] [B<-verbose>]
+ [B<-help>]
+
+B<vos rems> B<-s> <I<machine name>> B<-p> <I<partition name>>
+ B<-i> <I<volume name or ID>> [B<-c> <I<cell name>>] [B<-n>] [B<-l>]
+ [B<-v>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<vos remsite> command removes the read-only replication site
+specified by the B<-machine> and B<-partition> arguments from the Volume
+Location Database (VLDB) entry for the indicated volume, which is
+read/write.
+
+This command is useful for removing read-only sites that were mistakenly
+created with the B<vos addsite> command, before the B<vos release> command
+actually releases them. If a read-only copy already exists at the site, it
+is not affected. However, if this read-only site was the last site housing
+any version of the volume, then the entire VLDB entry is removed, even if
+a copy of the read-only version still actually exists at the site. The VL
+Server does not correct the discrepancy until the B<vos syncserv> and
+B<vos syncvldb> commands are run.
+
+=head1 CAUTIONS
+
+Do not use this command as the standard way to remove a read-only volume,
+because it can create a discrepancy between the VLDB and the volumes on
+file server machines. Use the B<vos remove> command instead.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-server> <I<server name>>
+
+Specifies the file server machine portion of the site definition to
+remove. Provide the machine's IP address or its host name (either fully
+qualified or using an unambiguous abbreviation). For details, see
+L<vos(1)>.
+
+=item B<-partition> <I<partition name>>
+
+Specifies the partition name portion of the site definition to
+remove. Provide the partition's complete name with preceding slash (for
+example, C</vicepa>) or use one of the three acceptable abbreviated
+forms. For details, see L<vos(1)>.
+
+=item B<-id> <I<volume name or id>>
+
+Specifies either the complete name or volume ID number of the read/write
+volume to remove.
+
+=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<vos(1)>.
+
+=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<vos(1)>.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+F</usr/afs/etc/KeyFile> file. The B<vos> command interpreter presents it
+to the Volume Server and Volume Location Server during mutual
+authentication. Do not combine this flag with the B<-cell> argument or
+B<-noauth> flag. For more details, see L<vos(1)>.
+
+=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.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command removes the mistakenly defined read-only site
+F</viceph> on the file server machine C<fs5.abc.com> from the VLDB entry
+for the volume C<root.cell>.
+
+ % vos remsite -server fs5.abc.com -partition h -id root.cell
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the F</usr/afs/etc/UserList> file on the
+machine specified with the B<-server> argument and on each database server
+machine. 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<vos(1)>,
+L<vos_delentry(1)>,
+L<vos_remove(1)>,
+L<vos_zap(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
+
+vos rename - Renames a volume
+
+=head1 SYNOPSIS
+
+B<vos rename> B<-oldname> <I<old volume name>>
+ B<-newname> <I<new volume name>> [B<-cell> <I<cell name>>]
+ [B<-noauth>] [B<-localauth>] [B<-verbose>] [B<-help>]
+
+B<vos ren> B<-o> <I<old volume name>> B<-ne> <I<new volume name>>
+ [-c <I<cell name>>] [B<-no>] [B<-l>] [B<-v>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<vos rename> command changes the name of the read/write volume
+specified with the B<-oldname> argument to the name specified with the
+B<-newname> argument. The names of the read/write's read-only copies and
+backup copy, if any, change automatically to match.
+
+After issuing this command, remember to correct any mount points that
+refer to the old volume name, by removing the old mount point with the
+B<fs rmmount> command and creating a new one with the B<fs mkmount>
+command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-oldname> <I<old volume name>>
+
+Is the current name of the read/write volume.
+
+=item B<-newname> <I<new volume name>>
+
+Is the desired new name for the volume.
+
+=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<vos(1)>.
+
+=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<vos(1)>.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+F</usr/afs/etc/KeyFile> file. The B<vos> command interpreter presents it
+to the Volume Server and Volume Location Server during mutual
+authentication. Do not combine this flag with the B<-cell> argument or
+B<-noauth> flag. For more details, see L<vos(1)>.
+
+=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.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+The B<vos rename> command produces no output if the command succeeds.
+
+If the volume named by the B<-oldname> argument does not exist, the
+following message appears:
+
+ vos: Could not find entry for volume <old volume name>.
+
+=head1 EXAMPLES
+
+The following example changes the mistaken volume name C<sun4x_56.afsws>
+to the correct alternative C<sun4x_56.usr.afsws>.
+
+ % vos rename -oldname sun4x_56.afsws -newname sun4x_56.usr.afsws
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the F</usr/afs/etc/UserList> file on the
+machine specified with the B<-server> argument and on each database server
+machine. 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<vos(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
+
+vos restore - Converts an ASCII dump file into an AFS volume
+
+=head1 SYNOPSIS
+
+B<vos restore> B<-server> <I<machine name>> B<-partition> <I<partition name>>
+ B<-name> <I<name of volume to be restored>> [B<-file> <I<dump file>>]
+ [B<-id> <I<volume ID>>] [B<-overwrite> (abort | full | incremental)]
+ [B<-cell> <I<cell name>>] [B<-noauth>] [B<-localauth>] [-verbose]
+ [B<-help>]
+
+B<vos res> B<-s> <I<machine name>> B<-p> <I<partition name>>
+ B<-na> <I<name of volume to be restored>> [B<-f> <I<dump file>>]
+ [B<-i> <I<volume ID>>] [B<-o> (a | f | i)] [B<-c> <I<cell name>>]
+ [B<-no>] [B<-l>] [B<-v>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<vos restore> command converts a volume dump file previously created
+with the B<vos dump> command from ASCII into the volume format appropriate
+for the machine type indicated by the B<-server> argument, and restores it
+as a read/write volume to the partition named by the B<-partition>
+argument on that machine. The Volume Server assigns the volume name
+indicated with the B<-name> argument, and resets the volume's creation
+timestamp to the time at which the restore operation begins (the creation
+timestamp is stored in the volume header and reported in the C<Creation>
+field in the output from the B<vos examine> and B<vos listvol> commands.)
+
+Use the B<-file> argument to name the dump file, or omit the argument to
+provide the file via the standard input stream, presumably through a
+pipe. The pipe can be named, which enables interoperation with third-party
+backup utilities.
+
+As described in the following list, the command can create a completely
+new volume or overwrite an existing volume. In all cases, the full dump of
+the volume must be restored before any incremental dumps. If there are
+multiple incremental dump files, they must be restored in the order they
+were created.
+
+=over 4
+
+=item *
+
+To create a new read/write volume, use the B<-name> argument to specify a
+volume name that does not already exist in the Volume Location Database
+(VLDB), and the B<-server> and B<-partition> arguments to specify the new
+volume's site. It is best to omit the B<-id> argument so that the Volume
+Location (VL) Server allocates a volume ID automatically. Do not include
+the B<-overwrite> argument, because there is no existing volume to
+overwrite.
+
+=item *
+
+To overwrite an existing volume at its current site, specify its name and
+site with the B<-name>, B<-server>, and B<-partition> arguments. The
+volume retains its current volume ID number unless the B<-id> argument is
+provided. Specify the value C<f> or C<i> for the B<-overwrite> argument to
+indicate whether the dump file is full or incremental, respectively.
+
+=item *
+
+To overwrite an existing volume and move it to a new site, specify its
+name and the new site with the B<-name>, B<-server>, and B<-partition>
+arguments. The volume retains its current volume ID number unless the
+B<-id> argument is provided. The volume is removed from its original
+site. Specify the value C<f> for the B<-overwrite> argument to indicate
+that the dump file is a full dump (it is not possible to restore an
+incremental dump and move the volume at the same time).
+
+=back
+
+If the volume named by the B<-name> argument already exists and the
+B<-overwrite> argument is omitted, the command interpreter produces the
+following prompt:
+
+ Do you want to do a full/incremental restore or abort? [fia](a):
+
+Respond by entering one of the following values:
+
+=over 4
+
+=item *
+
+C<f> if restoring a full dump file
+
+=item *
+
+C<i> if restoring an incremental dump file
+
+=item *
+
+C<a> or Return to cancel the restore operation
+
+=back
+
+=head1 CAUTIONS
+
+If the B<-file> argument is omitted, the issuer must provide all other
+necessary arguments, because the standard input stream is unavailable for
+responding to the command interpreter's prompts for missing
+information. In particular, the issuer must provide the B<-overwrite>
+argument if overwriting an existing volume.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-server> <I<server name>>
+
+Identifies the file server machine onto which to restore the
+volume. Provide the machine's IP address or its host name (either fully
+qualified or using an unambiguous abbreviation). For details, see
+L<vos(1)>.
+
+=item B<-partition> <I<partition name>>
+
+Identifies the partition (on the file server machine specified by the
+B<-server> argument) onto which to restore the volume. Provide the
+partition's complete name with preceding slash (for example, F</vicepa>)
+or use one of the three acceptable abbreviated forms. For details, see
+L<vos(1)>.
+
+=item B<-name> <I<name of volume>>
+
+Specifies the name under which to restore the volume. It can be up to 22
+characters long, but cannot end with a C<.readonly> or C<.backup>
+extension. If the volume already exists, it is overwritten subject to the
+value of the B<-overwrite> argument.
+
+=item B<-file> <I<dump file>>
+
+Names the dump file to restore. Incomplete pathnames are interpreted
+relative to the current working directory. Omit this argument to provide
+the dump file via the standard input stream.
+
+=item B<-id> <I<volume ID>>
+
+Specifies the volume ID number to assign to the restored volume.
+
+=item B<-overwrite> (a | f | i)
+
+Specifies which type of dump file is being restored when overwriting an
+existing volume. Provide one of the following values:
+
+=over 4
+
+=item *
+
+C<a> to terminate the restore operation.
+
+=item *
+
+C<f> if restoring a full dump file.
+
+=item *
+
+C<i> if restoring an incremental dump file. This value is not acceptable
+if the B<-server> and B<-partition> arguments do not indicate the volume's
+current site.
+
+=back
+
+This argument is mandatory if the B<-file> argument is not provided.
+
+=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<vos(1)>.
+
+=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<vos(1)>.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+F</usr/afs/etc/KeyFile> file. The B<vos> command interpreter presents it
+to the Volume Server and Volume Location Server during mutual
+authentication. Do not combine this flag with the B<-cell> argument or
+B<-noauth> flag. For more details, see L<vos(1)>.
+
+=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.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command restores the contents of the dump file
+F</afs/abc.com/common/dumps/terry.dump> to the F</vicepc> partition on the
+file server machine C<fs3.abc.com>. The restored volume is named
+C<user.terry>.
+
+ % cd /afs/abc.com/common/dumps
+ % vos restore -file terry.dump -server fs3.abc.com -partition c \
+ -name user.terry
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the F</usr/afs/etc/UserList> file on the
+machine specified with the B<-server> argument and on each database server
+machine. 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<vos(1)>,
+L<vos_dump(1)>,
+L<vos_examine(1)>,
+L<vos_listvol(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
+
+vos status - Reports a Volume Server's status
+
+=head1 SYNOPSIS
+
+B<vos status> B<-server> <I<machine name>> [B<-cell> <I<cell name>>]
+ [B<-noauth>] [B<-localauth>] [B<-verbose>] [B<-help>]
+
+B<vos st> B<-s> <I<machine name>> [B<-c> <I<cell name>>] [B<-n>] [B<-l>]
+ [B<-v>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<vos status> command reports on what the Volume Server on a certain
+file server machine is doing at the moment the command is issued. If there
+is no activity, the following message appears:
+
+ No active transactions on <machine_name>
+
+This command is useful mainly if there is concern that the Volume Server
+is not performing requested actions.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-server> <I<server name>>
+
+Identifies the file server machine running the Volume Server for which to
+display status information. Provide the machine's IP address or its host
+name (either fully qualified or using an unambiguous abbreviation). For
+details, see L<vos(1)>.
+
+=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<vos(1)>.
+
+=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<vos(1)>.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+F</usr/afs/etc/KeyFile> file. The B<vos> command interpreter presents it
+to the Volume Server and Volume Location Server during mutual
+authentication. Do not combine this flag with the B<-cell> argument or
+B<-noauth> flag. For more details, see L<vos(1)>.
+
+=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.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+There are two possible types of output.
+
+The following message indicates that the Volume Server is not currently
+performing any actions.
+
+ No active transactions on I<machine name>
+
+The other possible output is a set of information which is probably more
+useful to programmers than to system administrators. A full understanding
+of all the fields requires familiarity with the code for the Volume
+Server, as many of the fields report ID numbers and flag values that the
+Volume Server sets for internal use.
+
+Among the fields of possible interest to an administrator are:
+
+=over 4
+
+=item *
+
+C<created> on the first line, which indicates the time at which this
+transaction started
+
+=item *
+
+C<attachFlags> on the second line, where a value of C<offline> indicates
+that the volume is not available for other read or write operations during
+this transaction
+
+=item *
+
+C<volume> on the third line, which specifies the affected volume's ID
+number
+
+=item *
+
+C<partition> on the third line, which indicates where the affected volume
+resides (at the beginning of the transaction if this is a move)
+
+=item *
+
+C<procedure> on the third line, which indicates the internal subprocedure
+being executed
+
+=back
+
+A fourth line can appear during certain transactions, and includes the
+following fields:
+
+=over 4
+
+=item *
+
+C<packetRead> tracks whether information is being read into the
+volume. Its absolute value is not informative, but the way it changes
+shows whether the B<vos restore> command is executing properly. As the
+B<vos status> command is issued repeatedly during a restore, C<readNext>
+increases monotonically to indicate that information is being read into
+the volume.
+
+=item *
+
+C<packetSend> tracks whether information is being sent out of the
+volume. Its absolute value is not informative, but the way it changes
+shows whether the B<vos dump> command is executing properly. As the B<vos
+status> command is issued repeatedly during a dump, C<transmitNext>
+increases monotonically to indicate that information is being transferred
+from the volume into the dump file.
+
+=back
+
+The C<lastReceiveTime> and C<lastSendTime> are for internal use.
+
+=head1 EXAMPLES
+
+The following example illustrates the kind of output that sometimes
+appears when the Volume Server on C<fs1.abc.com> is executing a dump at
+the time this command is issued.
+
+ % vos status fs1.abc.com
+ --------------------------------------------
+ transaction: 575 created: Tue Jan 2 8:34:56 1990
+ attachFlags: offline
+ volume: 536871080 partition: /vicepb procedure: Dump
+ packetRead: 2 lastReceiveTime: 113313 packetSend: 24588
+ lastSendTime: 113317
+ --------------------------------------------
+
+=head1 PRIVILEGE REQUIRED
+
+None
+
+=head1 SEE ALSO
+
+L<vos(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
+
+vos syncserv - Verifies VLDB entries that mention a specified site
+
+=head1 SYNOPSIS
+
+B<vos syncserv> B<-server> <I<machine name>>
+ [B<-partition> <I<partition name>>] [B<-cell> <I<cell name>>]
+ [B<-noauth>] [B<-localauth>] [B<-verbose>] [B<-help>]
+
+B<vos syncs> B<-s> <I<machine name>> [B<-p> <I<partition name>>]
+ [B<-c> <I<cell name>>] [B<-n>] [B<-l>] [B<-v>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<vos syncserv> command verifies that each volume mentioned in a VLDB
+entry actually exists at the site indicated in the entry. It checks all
+VLDB entries that mention a read/write, read-only, or backup site either
+on any partition on the file server machine specified by the B<-server>
+argument, or on the one partition specified by the B<-server> and
+B<-partition> arguments. Note that the command can end up inspecting sites
+other than those specified by the B<-server> and B<-partition> arguments,
+if there are versions of the volume at sites other than the one specified.
+
+The command alters any incorrect information in the VLDB, unless there is
+an irreconcilable conflict with other VLDB entries. In that case, it
+writes a message to the standard error stream instead. The command never
+removes volumes from file server machines.
+
+To achieve complete VLDB consistency, first run the B<vos syncvldb>
+command on all file server machines in the cell, then run this command on
+all file server machines in the cell.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-server> <I<server name>>
+
+Identifies the file server machine mentioned in each VLDB entry to
+check. Provide the machine's IP address or its host name (either fully
+qualified or using an unambiguous abbreviation). For details, see
+L<vos(1)>.
+
+=item B<-partition> <I<partition name>>
+
+Identifies the partition mentioned in each VLDB entry to check. Provide
+the partition's complete name with preceding slash (for example,
+C</vicepa>) or use one of the three acceptable abbreviated forms. For
+details, see L<vos(1)>.
+
+=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<vos(1)>.
+
+=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<vos(1)>.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+F</usr/afs/etc/KeyFile> file. The B<vos> command interpreter presents it
+to the Volume Server and Volume Location Server during mutual
+authentication. Do not combine this flag with the B<-cell> argument or
+B<-noauth> flag. For more details, see L<vos(1)>.
+
+=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.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following example verifies the VLDB entries in which a site definition
+mentions the file server machine C<fs3.abc.com>.
+
+ % vos syncserv -server fs3.abc.com
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the F</usr/afs/etc/UserList> file on the
+machine specified with the B<-server> argument and on each database server
+machine. 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<vos(1)>,
+L<vos_syncvldb(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
+
+vos syncvldb - Verifies VLDB entries for volumes residing at specified site
+
+=head1 SYNOPSIS
+
+B<vos syncvldb> [B<-server> <I<machine name>>]
+ [B<-partition> <I<partition name>>] [B<-volume> <I<volume name or ID>>]
+ [B<-cell> <I<cell name>>] [B<-noauth>] [B<-localauth>] [B<-verbose>]
+ [B<-help>]
+
+B<vos syncv> [B<-s> <I<machine name>>] [B<-p> <I<partition name>>]
+ [B<-vo> <I<volume name or ID>>] [B<-c> <I<cell name>>] [B<-n>] [B<-l>]
+ [B<-ve>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<vos syncvldb> command verifies that the status of the volumes housed
+either on all partitions on the file server machine specified by the
+B<-server> argument, or on the single partition specified by the
+B<-server> and B<-partition> arguments, is recorded correctly in the
+VLDB. If the B<-volume> argument is included to indicate a single volume,
+the command compares only its status on the file server machine with its
+VLDB entry.
+
+If the B<-volume> argument is not included, the command interpreter
+obtains from the Volume Server a list of the volumes that reside on each
+partition, then changes information in the VLDB as necessary to reflect
+their state on the partition. For example, it creates or updates a VLDB
+entry when it finds a volume for which the VLDB entry is missing or
+incomplete. However, if there is already a VLDB entry that defines a
+different location for the volume, or there are irreconcilable conflicts
+with other VLDB entries, it instead writes a message about the conflict to
+the standard error stream. The command never removes volumes from the file
+server machine.
+
+To achieve complete VLDB consistency, run this command on all file server
+machines in the cell, and then run the B<vos syncserv> command on all file
+server machines in the cell.
+
+Using the B<-volume> argument basically combines the effects of this
+command with those of the B<vos syncserv> command, for a single
+volume. The command not only verifies that the VLDB entry is correct for
+the specified volume type (read/write, backup, or read-only), but also
+checks that any related volume types mentioned in the VLDB entry actually
+exist at the site listed in the entry. It is not necessary to provide the
+B<-server> argument (and optionally, B<-partition> argument); if one or
+both is provided, the results are reliable only if they specify the actual
+location of the volume indicated by the B<-volume> argument.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-server> <I<server name>>
+
+Identifies the file server machine housing the volumes for which to verify
+VLDB entries. Provide the machine's IP address or its host name (either
+fully qualified or using an unambiguous abbreviation). For details, see
+L<vos(1)>.
+
+=item B<-partition> <I<partition name>>
+
+Identifies the partition housing the volumes for which to verify VLDB
+entries. Provide the B<-server> argument along with this one. Provide the
+partition's complete name with preceding slash (for example, C</vicepa>)
+or use one of the three acceptable abbreviated forms. For details, see
+L<vos(1)>.
+
+=item B<-volume> <I<volume name or ID>>
+
+Specifies the name or volume ID number of a single volume for which to
+verify the VLDB entry. This argument can be combined with the B<-server>
+(and optionally, the B<-partition>) argument.
+
+=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<vos(1)>.
+
+=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<vos(1)>.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+F</usr/afs/etc/KeyFile> file. The B<vos> command interpreter presents it
+to the Volume Server and Volume Location Server during mutual
+authentication. Do not combine this flag with the B<-cell> argument or
+B<-noauth> flag. For more details, see L<vos(1)>.
+
+=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.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following example command verifies the VLDB entry for each volume
+stored on the file server machine C<fs4.abc.com>.
+
+ % vos syncvldb fs4.abc.com
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the F</usr/afs/etc/UserList> file on the
+machine specified with the B<-server> argument and on each database server
+machine. 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<vos(1)>,
+L<vos_syncserv(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
+
+vos unlock - Unlocks a single VLDB entry
+
+=head1 SYNOPSIS
+
+B<vos unlock> B<-id> <I<volume name or ID>> [B<-cell> <I<cell name>>]
+ [B<-noauth>] [B<-localauth>] [B<-verbose>] [B<-help>]
+
+B<vos unlock> B<-i> <I<volume name or ID>> [B<-c> <I<cell name>>] [B<-n>]
+ [B<-l>] [B<-v>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<vos unlock> command releases the lock on the Volume Location
+Database (VLDB) entry for the indicated volume.
+
+=head1 CAUTIONS
+
+Do not user this command under normal circumstances.
+
+It is useful if the VLDB entry is locked but there is no reason to suspect
+inconsistency within the volume or between it and the VLDB. Note that it
+is possible to list information from locked VLDB entries, even though they
+cannot be manipulated in other ways.
+
+The B<vos unlockvldb> command unlocks several VLDB entries at once, or
+even the entire VLDB. The B<vos lock> command locks a VLDB entry so that
+no one else can perform an action that requires writing the VLDB.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-id> <I<volume name or ID>>
+
+Specifies either the complete name or volume ID number of a volume of any
+of the three types.
+
+=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<vos(1)>.
+
+=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<vos(1)>.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+F</usr/afs/etc/KeyFile> file. The B<vos> command interpreter presents it
+to the Volume Server and Volume Location Server during mutual
+authentication. Do not combine this flag with the B<-cell> argument or
+B<-noauth> flag. For more details, see L<vos(1)>.
+
+=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.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following example unlocks the VLDB entry for the volume C<user.terry>.
+
+ % vos unlock user.terry
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the F</usr/afs/etc/UserList> file on the
+machine specified with the B<-server> argument and on each database server
+machine. 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<vos(1)>,
+L<vos_lock(1)>,
+L<vos_unlockvldb(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
+
+vos unlockvldb - Unlocks several locked VLDB entries
+
+=head1 SYNOPSIS
+
+B<vos unlockvldb> [B<-server> <I<machine name>>]
+ [B<-partition> <I<partition name>>] [B<-cell> <I<cell name>>]
+ [B<-noauth>] [B<-localauth>] [B<-verbose>] [B<-help>]
+
+B<vos unlockv> [B<-s> <I<machine name>>] [B<-p> <I<partition name>>]
+ [B<-c> <I<cell name>>] [B<-n>] [B<-l>] [B<-v>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<vos unlockvldb> command releases the lock on the Volume Location
+Database (VLDB) entries indicated by the combination of arguments
+provided:
+
+=over 4
+
+=item *
+
+To unlock all entries in the VLDB, provide no arguments.
+
+=item *
+
+To unlock all entries that mention a file server machine in a site
+definition, provide its name with the B<-server> argument.
+
+=item *
+
+To unlock all entries that mention a partition on any file server machine
+in a site definition, provide the partition name with the B<-partition>
+argument.
+
+=item *
+
+To unlock all entries that mention a specific site, provide both the
+B<-server> and B<-partition> arguments.
+
+=back
+
+To unlock a single volume, use the B<vos unlock> command instead.
+
+=head1 CAUTIONS
+
+Do not use this command under normal circumstances.
+
+It is useful if VLDB entries for volumes at a certain site are locked but
+there is no reason to suspect inconsistency within the volume or between
+it and the VLDB. Note that it is possible to list information from locked
+VLDB entries, even though they cannot be manipulated in other ways.
+
+The B<vos lock> command locks a VLDB entry so that no one else can perform
+an action that requires writing the VLDB.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-server> <I<server name>>
+
+Identifies the file server machine for which to unlock VLDB
+entries. Provide the machine's IP address or its host name (either fully
+qualified or using an unambiguous abbreviation). For details, see
+L<vos(1)>.
+
+=item B<-partition> <I<partition name>>
+
+Identifies the partition (on the file server machine specified by the
+B<-server> argument) for which to unlock VLDB entries. Provide the
+partition's complete name with preceding slash (for example, C</vicepa>)
+or use one of the three acceptable abbreviated forms. For details, see
+L<vos(1)>.
+
+=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<vos(1)>.
+
+=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<vos(1)>.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+F</usr/afs/etc/KeyFile> file. The B<vos> command interpreter presents it
+to the Volume Server and Volume Location Server during mutual
+authentication. Do not combine this flag with the B<-cell> argument or
+B<-noauth> flag. For more details, see L<vos(1)>.
+
+=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.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command unlocks all locked entries in the VLDB.
+
+ % vos unlockvldb
+
+The following command unlocks all locked VLDB entries that mention the
+F</vicepa> partition in a site definition.
+
+ % vos unlockvldb -partition a
+
+The following command unlocks all locked VLDB entries that refer to
+volumes on the F</vicepc> partition of the file server machine
+C<fs3.abc.com>.
+
+ % vos unlockvldb -server fs3.abc.com -partition c
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the F</usr/afs/etc/UserList> file on the
+machine specified with the B<-server> argument and on each database server
+machine. 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<vos(1)>,
+L<vos_lock(1)>,
+L<vos_unlock(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
+
+vos zap - Removes a volume from its site without writing to the VLDB
+
+=head1 SYNOPSIS
+
+B<vos zap> B<-server> <I<machine name>> B<-partition> <I<partition name>>
+ B<-id> <I<volume ID>> [B<-force>] [B<-backup>]
+ [B<-cell> <I<cell name>>] [B<-noauth>] [B<-localauth>] [B<-verbose>]
+ [B<-help>]
+
+B<vos z> B<-s> <I<machine name>> B<-p> <I<partition name>>
+ B<-i> <I<volume ID>> [B<-f>] [B<-b>] [B<-c> <I<cell name>>] [B<-n>]
+ [B<-l>] [B<-v>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<vos zap> command removes the volume with the specified I<volume ID>
+from the site defined by the B<-server> and B<-partition> arguments,
+without attempting to change the corresponding Volume Location Database
+(VLDB) entry. If removing the volume can possibly result in incorrect data
+in the VLDB, a warning message is displayed.
+
+The B<-force> flag removes a volume even if it cannot be "attached"
+(brought online), which can happen either because the volume is extremely
+damaged or because the Salvager functioned abnormally. Without this flag,
+this command cannot remove volumes that are not attachable. See also
+L<CAUTIONS>.
+
+To remove the specified read/write volume's backup version at the same
+time, include the B<-backup> flag.
+
+=head1 CAUTIONS
+
+Do not use this command as the standard way to remove a volume, as it is
+likely to put the VLDB out of sync with the volumes on servers. Use the
+B<vos remove> command instead.
+
+This command is useful in situations where it is important to delete the
+volume, but for some reason the VLDB is unreachable -- for example,
+because s the Volume Location Server is unavailable. The issuer can remove
+the VLDB entry later with the B<vos remove> or B<vos delentry> command, or
+it is removed automatically when the B<vos syncserv> and B<vos syncvldb>
+commands run.
+
+To remove a read-only site defined in the VLDB by mistake, before a copy
+actually exists at the site, use the B<vos remsite> command. To remove an
+entire VLDB entry without affecting volumes at their sites, use the B<vos
+delentry> command.
+
+Do not use the B<-force> flag if the volume is online, but only when
+attempts to remove the volume with the B<vos remove> or the B<vos zap>
+command have failed, or the volume definitely cannot be attached. After
+using the B<-force> flag, make sure that the volume's VLDB entry is also
+removed (issue the B<vos delentry> command if necessary).
+
+Adding the B<-force> flag makes the command take considerably longer --
+about as long as a salvage of the relevant partition -- since the Volume
+Server examines all inodes on the partition for traces of the volume.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-server> <I<server name>>
+
+Identifies the file server machine from which to remove the volume.
+Provide the machine's IP address or its host name (either fully qualified
+or using an unambiguous abbreviation). For details, see L<vos(1)>.
+
+=item B<-partition> <I<partition name>>
+
+Identifies the partition (on the file server machine specified by the
+B<-server> argument) from which to remove the volume. Provide the
+partition's complete name with preceding slash (for example, C</vicepa>)
+or use one of the three acceptable abbreviated forms. For details, see
+L<vos(1)>.
+
+=item B<-id> <I<volume ID>>
+
+Specifies the volume ID number of the volume to remove, which can be of
+any of the three types. The volume name is not acceptable.
+
+=item B<-force>
+
+Removes the volume even though it cannot be attached (brought online). Use
+only after the failure of previous attempts to remove the volume by using
+the B<vos remove> command or the B<vos zap> command without this flag.
+
+=item B<-backup>
+
+Removes the backup version of the read/write volume specified by the
+B<-id> argument. Do not use this flag if the B<-id> argument identifies a
+read-only or backup volume.
+
+=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<vos(1)>.
+
+=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<vos(1)>.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+F</usr/afs/etc/KeyFile> file. The B<vos> command interpreter presents it
+to the Volume Server and Volume Location Server during mutual
+authentication. Do not combine this flag with the B<-cell> argument or
+B<-noauth> flag. For more details, see L<vos(1)>.
+
+=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.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following example removes the volume with volume ID 536870988 from the
+F</vicepf> partition of the file server machine C<fs6.abc.com>, without
+noting the change in the VLDB.
+
+ % vos zap -server fs6.abc.com -partition f -id 536870988
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the F</usr/afs/etc/UserList> file on the
+machine specified with the B<-server> argument and on each database server
+machine. 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<vos(1)>,
+L<vos_delentry(1)>,
+L<vos_remove(1)>,
+L<vos_remsite(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
+
+AuthLog.dir, AuthLog.pag - Log of Authentication Server privileged operations
+
+=head1 DESCRIPTION
+
+The F<AuthLog.dir> and F<AuthLog.pag> files record a trace of privileged
+operations performed by the Authentication Server (B<kaserver> process) on
+the local machine. If the files do not exist when the Authentication
+Server starts, it creates them in the F</usr/afs/logs> directory as
+necessary.
+
+The files are in binary format. To display their contents, use the B<kdb>
+command, which requires being logged in to the local machine as the local
+superuser C<root>.
+
+=head1 CAUTIONS
+
+The Authentication Server is possibly unable to create these files on some
+operating systems that AFS otherwise supports, making the B<kdb> command
+inoperative. See the I<IBM AFS Release Notes> for details.
+
+=head1 SEE ALSO
+
+L<kaserver(8)>,
+L<kdb(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+AuthLog - Traces Authentication Server operations
+
+=head1 DESCRIPTION
+
+The F<AuthLog> file records a trace of Authentication Server (B<kaserver>
+process) operations on the local machine and describes any error
+conditions it encounters.
+
+If the F<AuthLog> file does not exist in the F</usr/afs/logs> directory
+when the Authentication Server starts, the server process creates it and
+writes initial start-up messages to it. If there is an existing file, the
+Authentication Server renames it to F<AuthLog.old>, overwriting the
+existing F<AuthLog.old> file if it exists.
+
+The file is in ASCII format. Administrators listed in the
+F</usr/afs/etc/UserList> file can use the B<bos getlog> command to display
+its contents. Alternatively, log onto the server machine and use a text
+editor or a file display command such as the UNIX B<cat> command. By
+default, the mode bits on the F<AuthLog> file grant the required C<r>
+(read) permission to all users.
+
+The Authentication Server records operations only as it completes them,
+and cannot recover from failures by reviewing the file. The log contents
+are useful for administrative evaluation of process failures and other
+problems.
+
+=head1 SEE ALSO
+
+L<UserList(5)>,
+L<bos_getlog(1)>,
+L<kaserver(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+BackupLog - Traces Backup Server operations
+
+=head1 DESCRIPTION
+
+The F<BackupLog> file records a trace of Backup Server (B<buserver>
+process) operations on the local machine and describes any error
+conditions it encounters.
+
+If the F<BackupLog> file does not already exist in the F</usr/afs/logs>
+directory when the Backup Server starts, the server process creates it and
+writes initial start-up messages to it. If there is an existing file, the
+Backup Server renames it to F<BackupLog.old>, overwriting the existing
+F<BackupLog.old> file if it exists.
+
+The file is in ASCII format. Administrators listed in the
+F</usr/afs/etc/UserList> file can use the B<bos getlog> command to display
+its contents. Alternatively, log on to the machine and use a text editor
+or a file display command such as the UNIX B<cat> command. By default, the
+mode bits on the F<BackupLog> file grant the required C<r> (read)
+permission to all users.
+
+The Backup Server records operations only as it completes them, and so
+cannot recover from failures by reviewing the file. The log contents are
+useful for administrative evaluation of process failures and other
+problems.
+
+=head1 SEE ALSO
+
+L<UserList(5)>,
+L<bos_getlog(1)>,
+L<buserver(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+BosConfig - Defines server processes for the BOS Server to monitor
+
+=head1 DESCRIPTION
+
+The F<BosConfig> file lists the processes that the Basic OverSeer (BOS)
+Server monitors on its server machine, and thus defines which AFS server
+processes run on the machine. It specifies how the BOS Server reacts when
+a process fails, and also defines the times at which the BOS Server
+automatically restarts processes as part of performance maintenance. The
+file must reside in the F</usr/afs/local> directory on each AFS server
+machine.
+
+A server process entry in the F<BosConfig> file records the following
+information:
+
+=over 4
+
+=item *
+
+The I<entry type>, which is one of the following:
+
+=over 4
+
+=item cron
+
+Designates a server process that runs periodically instead of
+continuously. The BOS Server starts a cron process only at specified
+times, not whenever it fails. All standard AFS process entries except
+C<fs> are simple (there are no standard cron processes).
+
+=item fs
+
+Designates a group of interdependent server processes. If one of the
+processes fails, the BOS Server must coordinate its restart with the
+restart of the other processes in the group, possibly by stopping them
+first.
+
+There is only one standard entry of this type, for which the conventional
+name is C<fs>. It combines three server processes: the File Server
+(B<fileserver> process), the Volume Server (B<volserver> process), and the
+Salvager (B<salvager> process). These processes all operate on the same
+data--the AFS data stored on an AFS server machine's F</vicep> partitions
+and mounted in the AFS filespace--but in different ways. Grouping the
+processes prevents them from attempting to access the same data
+simultaneously, which can cause corruption.
+
+During normal operation, the Salvager process is not active. If the File
+Server process fails, however, the BOS Server stops the Volume Server
+process and runs the Salvager process to correct any corruption that
+resulted from the failure. (The administrator can also issue the B<bos
+salvage> command to invoke the Salvager process.) If the Volume Server
+fails, the BOS Server can restart it without stopping the File Server or
+running the Salvager.
+
+=item simple
+
+Designates a server process that runs independently of any other on the
+server machine. If a simple process fails, the BOS Server does not have to
+coordinate its restart with any other process.
+
+=back
+
+=item *
+
+The I<entry name>. The conventional name for an entry in the F<BosConfig>
+file and the associated process matches the binary filename. When issuing
+any B<bos> command that takes the B<-instance> argument, identify each
+process by the name used in the F<BosConfig> file. For a list of the
+names, see the B<bos create> reference page.
+
+=item *
+
+The process's I<status flag>, which determines whether the BOS Server
+attempts to start the process in two cases: each time the BOS Server
+itself restarts, and when the process fails. The F<BosConfig> file
+currently uses a binary notation to indicate whether the BOS Server
+attempts to restart the process as necessary or does not monitor it at
+all. For the sake of clarity, the AFS documentation refers to the flags as
+C<Run> and C<NotRun> instead. Only a system administrator, not the BOS
+Server, can change the flag.
+
+=item *
+
+One or more I<command parameters> which the BOS Server invokes to start
+the process or processes associated with the entry:
+
+=over 4
+
+=item *
+
+A C<cron> entry has two command parameters, the first the complete
+pathname to the program, and the second the time at which the BOS Server
+invokes the program.
+
+=item *
+
+The C<fs> entry has three command parameters, each the complete pathname
+to the B<fileserver>, B<volserver>, and B<salvager> programs, in that
+order.
+
+=item *
+
+A C<simple> entry has only one command parameter, the complete pathname to
+the program.
+
+=back
+
+=back
+
+In addition to server process entries, the F<BosConfig> file specifies the
+times at which the BOS Server performs two types of automatic process
+restarts:
+
+=over 4
+
+=item *
+
+The I<general restart> time at which the BOS Server restarts itself and
+then each process for which the entry in the F<BosConfig> file has status
+flag C<Run>. The default setting is Sunday at 4:00 a.m.
+
+=item *
+
+The I<binary restart> time at which the BOS Server restarts any server
+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.
+
+=back
+
+Although the F<BosConfig> file is in ASCII format, do not use a text
+editor to alter it. Its format is subject to change and incorrectly
+formatted entries can prevent server startup in ways that are difficult to
+diagnose. Instead always use the appropriate commands from the B<bos>
+command suite:
+
+=over 4
+
+=item *
+
+The B<bos create> command to create an entry in the file and start the
+associated process.
+
+=item *
+
+The B<bos delete> command to remove an entry from the file after the B<bos
+stop> command is used to stop the associated process.
+
+=item *
+
+The B<bos getrestart> command to display the times at which the BOS Server
+performs automatic restarts.
+
+=item *
+
+The B<bos setrestart> command to set the times at which the BOS Server
+performs automatic process restarts.
+
+=item *
+
+The B<bos start> command to change an entry's status flag to C<Run> and
+start the associated process.
+
+=item *
+
+The B<bos status> command to display all processes listed in the file.
+
+=item *
+
+The B<bos stop> command to change an entry's status flag to C<NotRun> and
+stop the associated process.
+
+=back
+
+There are also bos commands that start and stop processes without changing
+entries in the F<BosConfig> file. The BOS Server reads the F<BosConfig>
+file only when it starts, transferring the information into its
+memory. Thus a process's status as represented in the BOS Server's memory
+can diverge from its status in the F<BosConfig> file. The following
+commands change a process's status in the BOS Server's memory only:
+
+=over 4
+
+=item *
+
+The B<bos restart> command restarts a specified set of processes, all
+processes, or all processes other than the BOS Server.
+
+=item *
+
+The B<bos shutdown> command stops a process.
+
+=item *
+
+The B<bos startup> command starts a process.
+
+=back
+
+=head1 SEE ALSO
+
+L<bos_create(1)>,
+L<bos_delete(1)>,
+L<bos_getrestart(1)>,
+L<bos_restart(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_salvage(1)>,
+L<fileserver(8)>,
+L<salvager(8)>,
+L<volserver(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+BosLog - Traces BOS Server operations
+
+=head1 DESCRIPTION
+
+The F<BosLog> file records a trace of Basic OverSeer (BOS) Server
+(B<bosserver> process) operations on the local machine and describes any
+error conditions it encounters.
+
+If the F<BosLog> file does not already exist in the F</usr/afs/logs>
+directory when the BOS Server starts, the server process creates it and
+writes initial start-up messages to it. If there is an existing file, the
+BOS server renames it to F<BosLog.old>, overwriting the existing
+F<BosLog.old> file if it exists.
+
+The file is in ASCII format. Administrators listed in the
+F</usr/afs/etc/UserList> file can use the B<bos getlog> command to display
+its contents. Alternatively, log onto the server machine and use a text
+editor or a file display command such as the UNIX B<cat> command. By
+default, the mode bits on the F<BosLog> file grant the required C<r>
+(read) permission to all users.
+
+The BOS Server records operations only as it completes them, and cannot
+recover from failures by reviewing the file. The log contents are useful
+for administrative evaluation of process failures and other problems.
+
+=head1 SEE ALSO
+
+L<UserList(5)>,
+L<bos_getlog(1)>,
+L<bosserver(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+CellServDB - Lists the database server machines in AFS cells
+
+=head1 DESCRIPTION
+
+There are two versions of the F<CellServDB> file, both of which have the
+same format. One version is used by an AFS client and lists all of the
+database server machines in the local cell and any foreign cell that is to
+be accessible from the local client machine. The other version is used on
+servers and lists only the database servers in the local cell.
+
+=head2 Client CellServDB
+
+The client version of the CellServDB file lists the database server
+machines in the local cell and any foreign cell that is to be accessible
+from the local client machine. Database server machines run the
+Authentication Server, Backup Server, Protection Server, and Volume
+Location (VL) Server (the B<kaserver>, B<buserver>, B<ptserver>, and
+B<vlserver>) processes, which maintain the cell's administrative AFS
+databases.
+
+The Cache Manager and other processes running on a client machine use the
+list of a cell's database server machines when performing several common
+functions, including:
+
+=over 4
+
+=item *
+
+Fetching files. The Cache Manager contacts the VL Server to learn
+the location of the volume containing a requested file or directory.
+
+=item *
+
+Authenticating users. Client-side authentication programs (such as an
+AFS-modified login utility or the B<klog> command interpreter) contact the
+Authentication Server to obtain a server ticket, which the AFS server
+processes accept as proof that the user is authenticated.
+
+=item *
+
+Creating protection groups. The B<pts> command interpreter contacts the
+Protection Server when users create protection groups or request
+information from the Protection Database.
+
+=back
+
+The Cache Manager reads the CellServDB file into kernel memory as it
+initializes, and not again until the machine next reboots. To enable users
+on the local machine to continue accessing the cell correctly, update the
+file whenever a database server machine is added to or removed from a
+cell. To update the kernel-resident list of database server machines
+without rebooting, use the B<fs newcell> command.
+
+The F<CellServDB> file is in ASCII format and must reside in the
+F</usr/vice/etc> directory on each AFS client machine. Use a text editor
+to create and maintain it.
+
+The client version of the F<CellServDB> file is distinct from the server
+version, which resides in the F</usr/afs/etc> directory on each AFS server
+machine. The client version lists the database server machines in every
+AFS cell that the cell administrator wants the machine's users to be able
+to access, whereas the server version lists only the local cell's database
+server machines.
+
+=head2 Server CellServDB
+
+The server version of the F<CellServDB> file lists the local cell's
+database server machines. These machines run the Authentication Server,
+Backup Server, Protection Server, and Volume Location (VL) Server (the
+B<kaserver>, B<buserver>, B<ptserver>, and B<vlserver>) processes, which
+maintain the cell's administrative AFS databases. The initial version of
+the file is created with the B<bos setcellname> command during the
+installation of the cell's server machine, which is automatically recorded
+as the cell's first database server machine. When adding or removing
+database server machines, be sure to update this file appropriately. It
+must reside in the F</usr/afs/etc> directory on each AFS server machine.
+
+The database server processes consult the F<CellServDB> file to learn
+about their peers, with which they must maintain constant connections in
+order to coordinate replication of changes across the multiple copies of
+each database. The other AFS server processes consult the file to learn
+which machines to contact for information from the databases when they
+need it.
+
+Although the server F<CellServDB> file is in ASCII format, do not use a
+text editor to alter it. Instead always use the appropriate commands from
+the B<bos> command suite:
+
+=over 4
+
+=item *
+
+The B<bos addhost> command to add a machine to the file.
+
+=item *
+
+The B<bos listhosts> command to display the list of machines from the
+file.
+
+=item *
+
+The B<bos removehost> command to remove a machine from the file.
+
+=back
+
+In cells that use the Update Server to distribute the contents of the
+F</usr/afs/etc> directory, it is customary to edit only the copy of the
+file stored on the system control machine. Otherwise, edit the file on
+each server machine individually. For instructions on adding and removing
+database server machine, see the I<IBM AFS Quick Beginnings> chapter on
+installing additional server machines.
+
+=head2 CellServDB Format
+
+Both F<CellServDB> files have the same format:
+
+=over 4
+
+=item *
+
+The first line begins at the left margin with the greater-than character
+(C<< > >>), followed immediately by the cell's name without an intervening
+space. Optionally, a comment can follow any number of spaces and a number
+sign (C<#>), perhaps to identify the organization associated with the
+cell.
+
+=item *
+
+Each subsequent line in the entry identifies one of the cell's database
+server machines, with the indicated information in order:
+
+=over 4
+
+=item *
+
+The database server machine's IP address in dotted-decimal format.
+
+=item *
+
+One or more spaces.
+
+=item *
+
+A number sign (#), followed by the machine's fully qualified hostname
+without an intervening space. This number sign does not indicate that the
+hostname is a comment. It is a required field.
+
+=back
+
+=back
+
+No extra blank lines or newline characters are allowed in the file, even
+after the last entry. Their presence can prevent the Cache Manager from
+reading the file into kernel memory, resulting in an error message.
+
+grand.central.org maintains a list of the database server machines in all
+cells that have registered themselves as receptive to access from foreign
+cells. When a cell's administrators change its database server machines,
+it is customary to register the change with grand.central.org for
+inclusion in this file. The file conforms to the required F<CellServDB>
+format, and so is a suitable basis for the F<CellServDB> file on a client
+machine. You can download this file from L<http://grand.central.org/>.
+
+=head1 EXAMPLES
+
+The following example shows entries for two cells in a client
+F<CellServDB> file and illustrates the required format.
+
+ >abc.com # ABC Corporation
+ 192.12.105.2 #db1.abc.com
+ 192.12.105.3 #db2.abc.com
+ 192.12.107.3 #db3.abc.com
+ >test.abc.com # ABC Corporation Test Cell
+ 192.12.108.57 #testdb1.abc.com
+ 192.12.108.55 #testdb2.abc.com
+
+=head1 SEE ALSO
+
+L<bos_addhost(1)>,
+L<bos_listhosts(1)>,
+L<bos_removehost(1)>,
+L<bos_setcellname(1)>,
+L<buserver(8)>,
+L<fs_newcell(1)>,
+L<kaserver(8)>,
+L<klog(1)>,
+L<ptserver(8)>,
+L<vlserver(8)>,
+L<upclient(8)>,
+L<upserver(8)>
+
+I<IBM AFS Quick Beginnings>
+
+=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
+
+FORCESALVAGE - Forces salvage of entire partition
+
+=head1 DESCRIPTION
+
+The F<FORCESALVAGE> file, if present on an AFS server partition (that is,
+in a F</vicep> directory), signals that the Salvager must salvage the
+entire partition. The AFS-modified version of the B<fsck> program creates
+the empty (zero-length) file when it discovers corruption on the
+partition. The Salvager removes the file when it completes the salvage
+operation.
+
+When the File Server detects the presence of the file on a partition on
+which it is attaching volumes, it stops, detaches any volumes that are
+already attached, and exits after recording a message in the
+F</usr/afs/logs/FileLog> file. The Bos Server then invokes the Salvager to
+salvage the partition.
+
+=head1 SEE ALSO
+
+L<FileLog(5)>,
+L<bosserver(8)>,
+L<fileserver(8)>,
+L<salvager(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+FileLog - Traces File Server operations
+
+=head1 DESCRIPTION
+
+The F<FileLog> file records a trace of File Server (B<fileserver> process)
+operations on the local machine and describes any error conditions it
+encounters.
+
+If the F<FileLog> file does not already exist in the
+F</usr/afs/logs> directory when the File Server starts, the server
+process creates it and writes initial start-up messages to it. If there
+is an existing file, the File Server renames it to
+F<FileLog.old>, overwriting the existing
+F<FileLog.old> file if it exists.
+
+The file is in ASCII format. Administrators listed in the
+F</usr/afs/etc/UserList> file can use the B<bos getlog> command to display
+its contents. Alternatively, log onto the file server machine and use a
+text editor or a file display command such as the UNIX B<cat> command. By
+default, the mode bits on the F<FileLog> file grant the required C<r>
+(read) permission to all users.
+
+The File Server records operations only as it completes them, and cannot
+recover from failures by reviewing the file. The log contents are useful
+for administrative evaluation of process failures and other problems.
+
+=head1 SEE ALSO
+
+L<UserList(5)>,
+L<bos_getlog(1)>,
+L<fileserver(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+KeyFile - Defines AFS server encryption keys
+
+=head1 DESCRIPTION
+
+The F<KeyFile> file defines the server encryption keys that the AFS server
+processes running on the machine use to decrypt the tickets presented by
+clients during the mutual authentication process. AFS server processes
+perform privileged actions only for clients that possess a ticket
+encrypted with one of the keys from the file. The file must reside in the
+F</usr/afs/etc> directory on every server machine. For more detailed
+information on mutual authentication and server encryption keys, see the
+I<IBM AFS Administration Guide>.
+
+Each key has a corresponding a key version number that distinguishes it
+from the other keys. The tickets that clients present are also marked with
+a key version number to tell the server process which key to use to
+decrypt it. The F<KeyFile> file must always include a key with the same
+key version number and contents as the key currently listed for the C<afs>
+entry in the Authentication Database.
+
+The F<KeyFile> file is in binary format, so always use the appropriate
+commands from the B<bos> command suite to administer it:
+
+=over 4
+
+=item *
+
+The B<bos addkey> command to define a new key.
+
+=item *
+
+The B<bos listkeys> command to display the keys.
+
+=item *
+
+The B<bos removekey> command to remove a key from the file.
+
+=back
+
+In cells that use the Update Server to distribute the contents of the
+F</usr/afs/etc> directory, it is customary to edit only the copy of the
+file stored on the system control machine. Otherwise, edit the file on
+each server machine individually.
+
+=head1 SEE ALSO
+
+L<bos_addkey(1)>,
+L<bos_listkeys(1)>,
+L<bos_removekey(1)>,
+L<kas_setpassword(8)>,
+L<upclient(8)>,
+L<upserver(8)>
+
+I<IBM AFS Administration Guide>
+
+=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
+
+NetInfo - Defines machine interfaces to register with AFS servers
+
+=head1 DESCRIPTION
+
+There are two F<NetInfo> files, one for an AFS client and one for an AFS
+File Server or database server. The AFS client F<NetInfo> file specifies
+the IP addresses that the client should register with the File Servers it
+connects to. The server F<NetInfo> file specifies what interfaces should
+be registered with AFS Database Servers or used to talk to other database
+servers.
+
+=head2 Client NetInfo
+
+The client F<NetInfo> file lists the IP addresses of one or more of the
+local machine's network interfaces. If it exists in the F</usr/vice/etc>
+directory when the Cache Manager initializes, the Cache Manager uses its
+contents as the basis for a list of local interfaces. Otherwise, the Cache
+Manager uses the list of interfaces configured with the operating
+system. It then removes from the list any addresses that appear in the
+F</usr/vice/etc/NetRestrict> file, if it exists. The Cache Manager records
+the resulting list in kernel memory. The first time it establishes a
+connection to a File Server, it registers the list with the File Server.
+
+The File Server uses the addresses when it initiates a remote procedure
+call (RPC) to the Cache Manager (as opposed to responding to an RPC sent
+by the Cache Manager). There are two common circumstances in which the
+File Server initiates RPCs: when it breaks callbacks and when it pings the
+client machine to verify that the Cache Manager is still accessible.
+
+The F<NetInfo> file is in ASCII format. One of the machine's IP addresses
+appears on each line, in dotted decimal format. The File Server initially
+uses the address that appears first in the list. The order of the
+remaining addresses is not significant: if an RPC to the first interface
+fails, the File Server simultaneously sends RPCs to all of the other
+interfaces in the list. Whichever interface replies first is the one to
+which the File Server then sends pings and RPCs to break callbacks.
+
+To prohibit the Cache Manager absolutely from using one or more addresses,
+list them in the F<NetRestrict> file. To display the addresses the Cache
+Manager is currently registering with File Servers, use the B<fs
+getclientaddrs> command. To replace the current list of interfaces with a
+new one between reboots of the client machine, use the B<fs
+setclientaddrs> command.
+
+=head2 Server NetInfo
+
+The server F<NetInfo> file, if present in the F</usr/afs/local> directory,
+defines the following:
+
+=over 4
+
+=item *
+
+On a file server machine, the local interfaces that the File Server
+(B<fileserver> process) can register in the Volume Location Database
+(VLDB) at initialization time.
+
+=item *
+
+On a database server machine, the local interfaces that the Ubik database
+synchronization library uses when communicating with the database server
+processes running on other database server machines.
+
+=back
+
+If the F<NetInfo> file exists when the File Server initializes, the File
+Server uses its contents as the basis for a list of interfaces to register
+in the VLDB. Otherwise, it uses the list of network interfaces configured
+with the operating system. It then removes from the list any addresses
+that appear in the F</usr/afs/local/NetRestrict> file, if it exists. The
+File Server records the resulting list in the F</usr/afs/local/sysid> file
+and registers the interfaces in the VLDB. The database server processes
+use a similar procedure when initializing, to determine which interfaces
+to use for communication with the peer processes on other database
+machines in the cell.
+
+The F<NetInfo> file is in ASCII format. One of the machine's IP addresses
+appears on each line, in dotted decimal format. The order of the addresses
+is not significant.
+
+To display the File Server interface addresses registered in the VLDB, use
+the B<vos listaddrs> command.
+
+=head1 SEE ALSO
+
+L<sysid(5)>,
+L<vldb.DB0(5)>,
+L<fileserver(8)>,
+L<fs_getclientaddrs(1)>,
+L<fs_setclientaddrs(1)>,
+L<vos_listaddrs(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
+
+NetRestrict - Defines interfaces not to register with AFS servers
+
+=head1 DESCRIPTION
+
+There are two F<NetRestrict> files, one for an AFS client and one for an
+AFS File Server or database server. The AFS client F<NetRestrict> file
+specifies the IP addresses that the client should not register with the
+File Servers it connects to. The server F<NetInfo> file specifies what
+interfaces should not be registered with AFS Database Servers or used to
+talk to other database servers.
+
+=head2 Client NetRestrict
+
+The F<NetRestrict> file, if present in a client machine's F</usr/vice/etc>
+directory, defines the IP addresses of the interfaces that the local Cache
+Manager does not register with a File Server when first establishing a
+connection to it. For an explanation of how the File Server uses the
+registered interfaces, see L<NetInfo(5)>.
+
+As it initializes, the Cache Manager constructs a list of interfaces to
+register, from the F</usr/vice/etc/NetInfo> file if it exists, or from the
+list of interfaces configured with the operating system otherwise. The
+Cache Manager then removes from the list any addresses that appear in the
+F<NetRestrict> file, if it exists. The Cache Manager records the resulting
+list in kernel memory.
+
+The F<NetRestrict> file is in ASCII format. One IP address appears on each
+line, in dotted decimal format. The order of the addresses is not
+significant. The value C<255> is a wildcard that represents all possible
+addresses in that field. For example, the value C<192.12.105.255>
+indicates that the Cache Manager does not register any of the addresses in
+the C<192.12.105> subnet.
+
+To display the addresses the Cache Manager is currently registering with
+File Servers, use the B<fs getclientaddrs> command.
+
+=head2 Server NetRestrict
+
+The F<NetRestrict> file, if present in the F</usr/afs/local> directory,
+defines the following:
+
+=over 4
+
+=item *
+
+On a file server machine, the local interfaces that the File Server
+(B<fileserver> process) does not register in the Volume Location Database
+(VLDB) at initialization time.
+
+=item *
+
+On a database server machine, the local interfaces that the Ubik
+synchronization library does not use when communicating with the database
+server processes running on other database server machines.
+
+=back
+
+As it initializes, the File Server constructs a list of interfaces to
+register, from the F</usr/afs/local/NetInfo> file if it exists, or from
+the list of interfaces configured with the operating system otherwise. The
+File Server then removes from the list any addresses that appear in the
+F<NetRestrict> file, if it exists. The File Server records the resulting
+list in the F</usr/afs/local/sysid> file and registers the interfaces in
+the VLDB. The database server processes use a similar procedure when
+initializing, to determine which interfaces to use for communication with
+the peer processes on other database machines in the cell.
+
+The F<NetRestrict> file is in ASCII format. One IP address appears on each
+line, in dotted decimal format. The order of the addresses is not
+significant. The value C<255> is a wildcard that represents all possible
+addresses in that field. For example, the value C<192.12.105.255>
+indicates that the File Server or database server processes do not
+register or use any of the addresses in the C<192.12.105> subnet.
+
+To display the File Server interface addresses registered in the VLDB, use
+the B<vos listaddrs> command.
+
+=head1 SEE ALSO
+
+L<sysid(5)>,
+L<vldb.DB0(5)>,
+L<fileserver(8)>,
+L<fs_getclientaddrs(1)>
+L<vos_listaddrs(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
+
+NoAuth - Disables authorization checking
+
+=head1 DESCRIPTION
+
+The F<NoAuth> file, if present in a server machine's F</usr/afs/local>
+directory, indicates to the AFS server processes running on the machine
+that it is not necessary to perform authorization checking. They perform
+any action for any user who logs into the machine's local file system or
+issues a remote command that affects the machine's AFS server functioning,
+such as commands from the AFS command suites. Because failure to check
+authorization exposes the machine's AFS server functionality to attack,
+there are normally only two circumstances in which the file is present:
+
+=over 4
+
+=item *
+
+During installation of the machine, as instructed in the I<IBM AFS Quick
+Beginnings>.
+
+=item *
+
+During correction of a server encryption key emergency, as discussed in
+the I<IBM AFS Administration Guide>.
+
+=back
+
+In all other circumstances, the absence of the file means that the AFS
+server processes perform authorization checking, verifying that the issuer
+of a command has the required privilege.
+
+Create the file in one of the following ways:
+
+=over 4
+
+=item *
+
+By issuing the bosserver initialization command with the B<-noauth> flag,
+if the Basic OverSeer (BOS) Server is not already running.
+
+=item *
+
+By issuing the B<bos setauth> command with off as the value for the
+B<-authrequired> argument, if the BOS Server is already running.
+
+=back
+
+To remove the file, issue the B<bos setauth> command with C<on> as the
+value for the B<-authrequired> argument.
+
+The file's contents, if any, are ignored; an empty (zero-length) file is
+effective.
+
+=head1 SEE ALSO
+
+L<bos_setauth(1)>,
+L<bosserver(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+SALVAGE.fs - Triggers salvaging of AFS server partitions
+
+=head1 DESCRIPTION
+
+The F<SALVAGE.fs> file, if present in a file server machine's
+F</usr/afs/local> directory, indicates to the Basic OverSeer (BOS) Server
+(B<bosserver> process) that it must invoke the Salvager (B<salvager>
+process) during recovery from a failure of the File Server (B<fileserver>
+process).
+
+The BOS Server creates the zero-length file each time it starts or
+restarts the C<fs> process. When the File Server exits normally (for
+example, in response to the B<bos shutdown> or B<bos stop> command), the
+BOS Server removes the file. However, if the File Server exits
+unexpectedly, the file remains in the F</usr/afs/local> directory as a
+signal that the BOS Server must invoke the Salvager process to repair any
+file system inconsistencies possibly introduced during the failure, before
+restarting the File Server and Volume Server processes.
+
+Do not create or remove this file. To invoke the Salvager process
+directly, use the B<bos salvage> command or log onto the file server
+machine as the local superuser C<root> and issue the B<salvager> command.
+
+=head1 SEE ALSO
+
+L<bos_salvage(1)>,
+L<bosserver(8)>,
+L<fileserver(8)>,
+L<salvager(8)>,
+L<volserver(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+SalvageLog - Traces Salvager operations
+
+=head1 DESCRIPTION
+
+The F<SalvageLog> file records a trace of Salvager (B<salvager> process)
+operations on the local machine and describes any error conditions it
+encounters.
+
+If the F<SalvageLog> file does not already exist in the F</usr/afs/logs>
+directory when the Salvager starts, the process creates it and writes
+initial start-up messages to it. If there is an existing file, the
+Salvager renames is to F<SalvageLog.old>, overwriting the existing
+F<SalvageLog.old> file if it exists.
+
+The file is in ASCII format. Administrators listed in the
+F</usr/afs/etc/UserList> file can use the B<bos getlog> command to display
+its contents. Alternatively, log onto the file server machine and use a
+text editor or a file display command such as the UNIX B<cat> command. By
+default, the mode bits on the F<SalvageLog> file grant the required C<r>
+(read) permission to all users.
+
+The Salvager records operations only as it completes them, and cannot
+recover from failures by reviewing the file. The log contents are useful
+for administrative evaluation of process failures and other problems.
+
+=head1 SEE ALSO
+
+L<UserList(5)>,
+L<bos_getlog(1)>,
+L<salvager(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+ThisCell - Defines the local cell name
+
+=head1 DESCRIPTION
+
+The F<ThisCell> file defines the local cell name. There are two versions
+of this file, one for a AFS client and one for an AFS server.
+
+=head2 Client ThisCell
+
+The client version of the F<ThisCell> file defines the complete Internet
+domain-style name (for example, C<abc.com>) of the cell to which the local
+client machine belongs. It must reside in the F</usr/vice/etc> directory
+on every AFS client machine. To change a client machine's cell membership,
+edit the file and reboot the machine.
+
+The file is in ASCII format and contains a character string on a single
+line. The I<IBM AFS Quick Beginnings> instructs the administrator to
+create it during the installation of each client machine.
+
+The client machine's cell membership determines three defaults important
+to its functioning:
+
+=over 4
+
+=item *
+
+The cell in which the machine's users authenticate by default. The effect
+is two-fold:
+
+=over 4
+
+=item *
+
+The AFS-modified login utilities and the klog command interpreter contact
+an Authentication Server in the cell named in the F<ThisCell> file (unless
+B<-cell> argument to the B<klog> command specifies an alternate cell).
+
+=item *
+
+The command interpreters combine the cell name with the password that the
+user provides, generating an encryption key from the combination. For
+authentication to succeed, both the cell name and password must match the
+ones used to generate the user's encryption key stored in the
+Authentication Database.
+
+=back
+
+=item *
+
+The cell the Cache Manager considers its local, or home, cell. By default,
+the Cache Manager allows programs that reside in its home cell to run with
+setuid permission, but not programs from foreign cells. For more details,
+see the B<fs getcellstatus> and B<fs setcell> reference pages.
+
+=item *
+
+Which AFS server processes the local AFS command interpreters contact by
+default as they execute commands issued on the machine.
+
+=back
+
+The client version of the F<ThisCell> file is distinct from the server
+version, which resides in the F</usr/afs/etc> directory on each AFS server
+machine. If a server machine also runs as a client, it is acceptable for
+the server and client versions of the file on the same machine to name
+different cells. However, the behavior that results from this
+configuration can be more confusing than useful.
+
+=head2 Server ThisCell
+
+The server version of the F<ThisCell> file defines the complete Internet
+domain-style name (for example, C<abc.com>) of the cell to which the
+server machine belongs. It must reside in the F</usr/afs/etc> directory on
+every AFS server machine.
+
+The file is in ASCII format and contains a character string on a single
+line. The initial version of the file is created with the B<bos
+setcellname> command during the installation of the cell's first file
+server machine, and the I<IBM AFS Quick Beginnings> includes instructions
+for copying it over to additional server machine during their
+installation.
+
+The only reason to edit the file is as part of changing the cell's name,
+which is strongly discouraged because of the large number of configuration
+changes involved. In particular, changing the cell name requires
+rebuilding the entire Authentication Database, because the Authentication
+Server combines the cell name it finds in this file with each user and
+server password and converts the combination into an encryption key before
+recording it in the Database.
+
+=head1 SEE ALSO
+
+L<bos_setcellname(1)>,
+L<fs_getcellstatus(1)>,
+L<fs_setcell(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
+
+UserList - Defines privileged administrators
+
+=head1 DESCRIPTION
+
+The F<UserList> file lists the AFS usernames of the system administrators
+authorized to issue privileged B<bos>, B<vos>, and B<backup> commands that
+affect the local server machine or the volumes housed on it. It must
+reside in the F</usr/afs/etc> directory on every server machine.
+
+Although the F<UserList> file is in ASCII format, do not use a text editor
+to alter it. Instead always use the appropriate commands from the B<bos>
+command suite:
+
+=over 4
+
+=item *
+
+The B<bos adduser> command to add a user to the file.
+
+=item *
+
+The B<bos listusers> command to display the contents of the file.
+
+=item *
+
+The B<bos removeuser> command to remove a user from the file.
+
+=back
+
+Although it is theoretically possible to list different administrators in
+the F<UserList> files on different server machines, doing so can cause
+unanticipated authorization failures and is not recommended. In cells that
+use the Update Server to distribute the contents of the F</usr/afs/etc>
+directory, it is customary to edit only the copy of the file stored on the
+system control machine. Otherwise, edit the file on each server machine
+individually.
+
+=head1 SEE ALSO
+
+L<bos_adduser(1)>,
+L<bos_listusers(1)>,
+L<bos_removeuser(1)>,
+L<upclient(8)>,
+L<upserver(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+VLLog - Traces Volume Location Server operations
+
+=head1 DESCRIPTION
+
+The F<VLLog> file records a trace of Volume Location (VL) Server
+(B<vlserver> process) operations on the local machine and describes any
+error conditions it encounters.
+
+If the F<VLLog> file does not already exist in the
+F</usr/afs/logs> directory when the VL Server starts, the server
+process creates it and writes initial start-up messages to it. If there
+is an existing file, the VL Server renames it to F<VLLog.old>,
+overwriting the existing F<VLLog.old> file if it exists.
+
+The file is in ASCII format. Administrators listed in the
+F</usr/afs/etc/UserList> file can use the B<bos getlog> command to display
+its contents. Alternatively, log onto the server machine and use a text
+editor or a file display command such as the UNIX B<cat> command. By
+default, the mode bits on the F<VLLog> file grant the required C<r> (read)
+permission to all users.
+
+The VL Server records operations only as it completes them, and cannot
+recover from failures by reviewing the file. The log contents are useful
+for administrative evaluation of process failures and other problems.
+
+The VL Server can record messages at three levels of detail. By default,
+it records only very rudimentary messages. To increase logging to the
+first level of detail, issue the following command while logged onto the
+database server machine as the local superuser C<root>.
+
+ # kill -TSTP <vlserver_pid>
+
+where <vlserver_pid> is the process ID of the vlserver process, as
+reported in the output from the standard UNIX B<ps> command. To increase
+to the second and third levels of detail, repeat the command.
+
+To disable logging, issue the following command.
+
+ # kill -HUP <vlserver_pid>
+
+To decrease the level of logging, first completely disable it and then
+issue the C<kill -TSTP> command as many times as necessary to reach the
+desired level.
+
+=head1 SEE ALSO
+
+L<UserList(5)>,
+L<bos_getlog(1)>,
+L<vlserver(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+VolserLog - Traces Volume Server operations
+
+=head1 DESCRIPTION
+
+The F<VolserLog> file records a trace of Volume Server (B<volserver>
+process) operations on the local machine and describes any error
+conditions it encounters.
+
+If the VolserLog file does not already exist in the F</usr/afs/logs>
+directory when the Volume Server starts, the server process creates it and
+writes initial start-up messages to it. If there is an existing file, the
+Volume Server renames it to F<VolserLog.old>, overwriting the existing
+F<VolserLog.old> file if it exists.
+
+The file is in ASCII format. Administrators listed in the
+F</usr/afs/etc/UserList> file can use the B<bos getlog> command to display
+its contents. Alternatively, log onto the file server machine and use a
+text editor or a file display command such as the UNIX B<cat> command. By
+default, the mode bits on the F<VolserLog> file grant the required C<r>
+(read) permission to all users.
+
+The Volume Server records operations only as it completes them, and so
+cannot recover from failures by reviewing the file. The log contents are
+useful for administrative evaluation of process failures and other
+problems.
+
+=head1 SEE ALSO
+
+L<UserList(5)>,
+L<bos_getlog(1)>,
+L<volserver(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+afs - Introduction to AFS files
+
+=head1 DESCRIPTION
+
+A number of files must reside on the local disk of AFS server and client
+machines. They belong to the following general categories:
+
+=over 4
+
+=item *
+
+I<Configuration files> define configuration parameters for specific server
+and kernel processes such as the Backup System Tape Coordinator or the
+Cache Manager.
+
+=item *
+
+I<Administrative files> list information used in administration of server
+machines, such as a list of privileged users or server encryption keys.
+
+=item *
+
+I<Cache-related files> contain cached data or information about cached
+data, on client machines.
+
+=item *
+
+I<Log files> contain tracing messages about the operation of a specific
+process.
+
+=item *
+
+I<Database files> contain database records used to administer the AFS
+cell.
+
+=item *
+
+I<Controller files> control the behavior of a process.
+
+=item *
+
+I<Volume header files> represent AFS volumes on server partitions.
+
+=back
+
+For a description of the format and contents of each file, see its
+reference page.
+
+Note for Windows users: Some files described in this document possibly do
+not exist on machines that run a Windows operating system. Also, Windows
+uses a backslash (C<\>) rather than a forward slash (C</>) to separate the
+elements in a pathname.
+
+=head1 SEE ALSO
+
+Configuration files:
+
+=over 4
+
+=item L<BosConfig(5)>
+
+=item L<CellServDB(5)>
+
+=item L<NetInfo(5)>
+
+=item L<NetRestrict(5)>
+
+=item L<ThisCell(5)>
+
+=item L<butc(5)>
+
+=item L<cacheinfo(5)>
+
+=item L<package(5)>
+
+=item L<sysid(5)>
+
+=item L<tapeconfig(5)>
+
+=item L<uss(5)>
+
+=item L<uss_bulk(5)>
+
+=back
+
+Administrative files:
+
+=over 4
+
+=item L<KeyFile(5)>
+
+=item L<UserList(5)>
+
+=back
+
+Cache-related files:
+
+=over 4
+
+=item L<afs_cache(5)>
+
+=back
+
+Log files:
+
+=over 4
+
+=item L<AuthLog(5)>
+
+=item L<BackupLog(5)>
+
+=item L<BosLog(5)>
+
+=item L<FileLog(5)>
+
+=item L<SalvageLog(5)>
+
+=item L<VLLog(5)>
+
+=item L<VolserLog(5)>
+
+=item L<butc(5)>
+
+=item L<fms.log(5)>
+
+=back
+
+Database files:
+
+=over 4
+
+=item L<bdb.DB0(5)>
+
+=item L<kaserver.DB0(5)>
+
+=item L<kaserverauxdb(5)>
+
+=item L<prdb.DB0(5)>
+
+=item L<vldb.DB0(5)>
+
+=back
+
+Controller files:
+
+=over 4
+
+=item L<FORCESALVAGE(5)>
+
+=item L<NoAuth(5)>
+
+=item L<SALVAGE.fs(5)>
+
+=item L<salvage.lock(5)>
+
+=back
+
+Volume header files:
+
+=over 4
+
+=item L<afs_volume_header(5)>
+
+=back
+
+=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
+
+afs_cache - Format of data stored in an AFS client disk cache
+
+=head1 DESCRIPTION
+
+The disk cache on a client machine is composed of multiple F<VI<n>> files
+that contain the data, a F<CacheItems> file that records index information
+for all of the F<VI<n>> files, and a F<VolumeItems> file that records the
+mapping between volume name and mount point for volumes.
+
+When it initializes, the Cache Manager creates the cache files in the
+configured cache location. The standard directory name is
+F</usr/vice/cache>, but it is acceptable to use a directory on a partition
+with more available space. To designate a different directory, change the
+value in the second field of the F</usr/vice/etc/cacheinfo> file before
+issuing the B<afsd> command, or include the B<-cachedir> argument to the
+B<afsd> command.
+
+=head2 F<CacheItems>
+
+The CacheItems file records information about each file in the disk cache
+on a client machine (each F<VI<n>> file). The information includes the
+file ID number and associated volume version number of the AFS file
+currently stored in the B<V>I<n> file, which enables the Cache Manager to
+determine which F<VI<n>> file contains the AFS data it needs to present to
+an application.
+
+As it initializes, the Cache Manager creates the binary-format
+F<CacheItems> file in the same local disk cache directory as the F<VI<n>>
+files that the F<CacheItems> file describes, and it must always remain
+there.
+
+=head2 F<VolumeItems>
+
+The F<VolumeItems> file records the mapping between volume name and mount
+point for each volume that the Cache Manager has accessed since it
+initialized on a client machine using a disk cache. The Cache Manager uses
+the mappings to respond correctly to queries about the current working
+directory, which can come from the operating system or commands such as
+the UNIX B<pwd> command.
+
+As it initializes, the Cache Manager creates the binary-format
+F<VolumeItems> file in the local disk cache directory, and it must always
+remain there.
+
+=head2 F<VI<n>>
+
+A F<VI<n>> file can store a chunk of cached AFS data on a client machine
+that is using a disk cache. As the Cache Manager initializes, it verifies
+that the local disk cache directory houses a number of F<VI<n>> files
+equal to the largest of the following:
+
+=over 4
+
+=item *
+
+100
+
+=item *
+
+One and a half times the result of dividing the cache size by the chunk
+size (cachesize/chunksize * 1.5).
+
+=item *
+
+The result of dividing the cache size by 10 MB (10,240).
+
+=back
+
+The Cache Manager determines the cache size from the B<-blocks> argument
+to the B<afsd> command, or if the argument is not included, from the third
+field of the F</usr/vice/etc/cacheinfo> file. The default chunk size is
+64 KB; use the B<-chunksize> argument to the B<afsd> command to override
+it. To override the default number of chunks resulting from the
+calculation, include the B<-files> argument to the B<afsd>
+command. L<afsd(8)> describes the restrictions on acceptable values for
+each of the arguments.
+
+If the disk cache directory houses fewer F<VI<n>> files than necessary,
+the Cache Manager creates new ones, assigning each a unique integer I<n>
+that distinguishes it from the other files; the integers start with 1 and
+increment by one for each F<VI<n>> file created. The Cache Manager removes
+files if there are more than necessary. The Cache Manager also adds and
+removes F<VI<n>> files in response to the B<fs setcachesize> command,
+which can be used to alter the cache size between reboots.
+
+F<VI<n>> files expand and contract to accommodate the size of the AFS
+directory listing or file they temporarily house. As mentioned, by default
+each F<VI<n>> file holds up to 64 KB (65,536 bytes) of a cached AFS
+element. AFS elements larger than 64 KB are divided among multiple
+B<V>I<n> files. If an element is smaller than 64 KB, the F<VI<n>> file
+expands only to the required size. A F<VI<n>> file accommodates only a
+single element, so if there many small cached elements, it is possible to
+exhaust the available F<VI<n>> files without reaching the maximum cache
+size.
+
+=head1 CAUTIONS
+
+Editing or removing the F<CacheItems> or F<VolumeItems> files or a
+F<VI<n>> file can cause a kernel panic. If the contents of F<VI<n>> files
+seem out of date, clear the files by using the B<fs flush> or B<fs
+flushvolume> command. If any of the cache files are accidentally modified
+or deleted, rebooting the machine usually restores normal performance.
+
+To alter cache size (and thus the number of F<VI<n>> files) between
+reboots, use the B<fs setcachesize> command. Alternatively, alter the
+value of the B<-blocks>, B<-files> or B<-chunksize> arguments to the
+B<afsd> command invoked in the machine's AFS initialization file, and
+reboot. To refresh the contents of one or more F<VI<n>> files, use the
+B<fs flush> or B<fs flushvolume> command.
+
+=head1 SEE ALSO
+
+L<cacheinfo(5)>,
+L<afsd(8)>,
+L<fs_checkvolumes(1)>,
+L<fs_flush(1)>,
+L<fs_flushvolume(1)>,
+L<fs_setcachesize(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
+
+afs_volume_header - Represents an AFS volume
+
+=head1 DESCRIPTION
+
+The F<VI<vol_ID>.vol> file is the header file for the AFS volume with
+volume ID I<vol_ID>. There is one such file for each volume stored on an
+AFS server (F</vicep>) partition. The header file stores information that
+includes the volume's name, ID number, type (read/write, read-only, or
+backup), size and status (online, offline, or busy). To display
+information from the header file, use the B<vos listvol> or B<vos examine>
+command.
+
+The header file points to, but does not contain, the actual data in the
+volume. It is not possible to access the AFS data except by mounting the
+volume in the AFS filespace and reading its contents through the Cache
+Manager.
+
+=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
+
+afsmonitor - Provides instructions for the afsmonitor command
+
+=head1 DESCRIPTION
+
+The afsmonitor configuration file determines which machines the
+B<afsmonitor> command probes for File Server or Cache Manager statistics
+and which statistics it gathers. Use the B<-config> argument to the
+B<afsmonitor> command to identify the configuration file to use.
+
+The instructions that can appear in the configuration file are as follows:
+
+=over 4
+
+=item cm <I<host name>>
+
+Names a client machine for which to display Cache Manager statistics. The
+order of C<cm> lines in the file determines the order in which client
+machines appear from top to bottom on the C<System Overview> and C<Cache
+Managers> output screens.
+
+=item fs <I<host name>>
+
+Names a file server machine for which to display File Server
+statistics. The order of C<fs> lines in the file determines the order in
+which file server machines appear from top to bottom on the C<System
+Overview> and C<File Servers> output screens.
+
+=item thresh (fs | cm) <I<field>> <I<thresh>> [<I<cmd>>] [<I<arg>> ...]
+
+Assigns the threshold value I<thresh> to the statistic I<field>, for
+either a File Server statistic (C<fs>) or a Cache Manager statistic
+(C<cm>). The optional I<cmd> field names a binary or script to execute
+each time the value of the statistic changes from being below I<thresh> to
+being at or above I<thresh>. A change between two values that both exceed
+I<thresh> does not retrigger the binary or script. The optional I<arg>
+fields are additional values that the B<afsmonitor> program passes as
+arguments to the I<cmd> command. If any of them include one or more
+spaces, enclose the entire field in double quotes.
+
+The B<afsmonitor> program passes the following parameters to the I<cmd>:
+
+ <hostname> (fs|cm) <field> <thresh> <actual> [<arg> ...]
+
+The parameters C<fs>, C<cm>, <field>, <thresh>, and <arg> correspond to
+the values with the same name on the thresh line. The <hostname> parameter
+identifies the file server or client machine where the statistic has
+crossed the threshold, and the <actual> parameter is the actual value of
+<field> that exceeds the threshold value.
+
+Use the C<thresh> line to set either a global threshold, which applies to
+all file server machines listed on C<fs> lines or client machines listed
+on C<cm> lines in the configuration file, or a machine-specific threshold,
+which applies to only one file server or client machine.
+
+=over 4
+
+=item *
+
+To set a global threshold, place the thresh line before any of the C<fs>
+or C<cm> lines in the file.
+
+=item *
+
+To set a machine-specific threshold, place the thresh line below the
+corresponding C<fs> or C<cm> line, and above any other C<fs> or C<cm>
+lines. A machine-specific threshold value always overrides the
+corresponding global threshold, if set. Do not place a C<thresh fs> line
+directly after a C<cm> line or a C<thresh cm> line directly after a C<fs>
+line.
+
+=back
+
+=item show (fs | cm) I<field/group/section>
+
+Specifies which individual statistic, group of statistics, or section of
+statistics to display on the C<File Servers> screen (C<fs>) or C<Cache
+Managers> screen (C<cm>) and the order in which to display them. The
+appendix of B<afsmonitor> statistics in the I<IBM AFS Administration
+Guide> specifies the group and section to which each statistic
+belongs. Include as many C<show> lines as necessary to customize the
+screen display as desired, and place them anywhere in the file. The
+top-to-bottom order of the C<show> lines in the configuration file
+determines the left-to-right order in which the statistics appear on the
+corresponding screen.
+
+If there are no C<show> lines in the configuration file, then the screens
+display all statistics for both Cache Managers and File
+Servers. Similarly, if there are no C<show fs> lines, the C<File Servers>
+screen displays all file server statistics, and if there are no C<show cm>
+lines, the C<Cache Managers> screen displays all client statistics.
+
+=item # I<comments>
+
+Precedes a line of text that the afsmonitor program ignores because of the
+initial number (C<#>) sign, which must appear in the very first column of
+the line.
+
+=back
+
+For a list of the values that can appear in the I<field/group/section>
+field of a C<show> instruction, see the B<afsmonitor> statistics appendix
+to the I<IBM AFS Administration Guide>.
+
+=head1 SEE ALSO
+
+L<afsmonitor(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
+
+afszcm.cat - Error message catalog for debugging the Cache Manager
+
+=head1 DESCRIPTION
+
+The F<afszcm.cat> file is a message catalog for the Cache Manager. The
+B<fstrace dump> command interpreter uses it in conjunction with the
+standard UNIX catalog utilities to translate Cache Manager operation codes
+into character strings as it writes traces in the B<fstrace> trace log,
+which makes the log more readable.
+
+The conventional location for the file is the F</usr/vice/etc/C/>
+directory. It can be placed in another directory if the NLSPATH and LANG
+environment variables are set appropriately.
+
+=head1 SEE ALSO
+
+L<afsd(8)>,
+L<fstrace_dump(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+bdb.DB0, bdb.DBSYS1 - Contain the Backup Database and associated log
+
+=head1 DESCRIPTION
+
+The F<bdb.DB0> file contains the Backup Database, which records
+configuration information used by the AFS Backup System along with
+cross-indexed records of the tapes created and volumes dumped using the
+Backup System commands.
+
+The F<bdb.DBSYS1> file is a log file in which the Backup Server
+(B<buserver> process) logs each database operation before performing
+it. When an operation is interrupted, the Backup Server replays the log to
+complete the operation.
+
+Both files are in binary format and reside in the F</usr/afs/db> directory
+on each database server machine that runs the Backup Server. When the
+Backup Server starts or restarts on a given machine, it establishes a
+connection with its peers and verifies that its copy of the F<bdb.DB0>
+file matches the copy on the other database server machines. If not, the
+Backup Servers use AFS's distributed database technology, Ubik, to
+distribute to all of the machines the copy of the database with the
+highest version number.
+
+Use the commands in the backup suite to administer the Backup Database. It
+is advisable to create a backup copy of the F<bdb.DB0> file on tape on a
+regular basis, using the UNIX B<tar> command or another local disk backup
+utility.
+
+=head1 SEE ALSO
+
+L<backup(8)>,
+L<backup_savedb(8)>,
+L<buserver(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+butc - Defines Tape Coordinator instructions for automated tape devices
+
+=head1 DESCRIPTION
+
+The F<CFG_I<device_name>> file includes instructions that configure a Tape
+Coordinator (B<butc>) for use with automated backup devices such as tape
+stackers and jukeboxes, enable the Tape Coordinator to dump and restore
+data to a I<backup data file> on a local disk device, and enable greater
+automation of other aspects of the backup process.
+
+There is a separate configuration file for each tape device or backup data
+file. Creating the file is optional, and unnecessary if none of the
+instructions it can include pertain to a given tape device. The
+ASCII-format file must reside in the F</usr/afs/backup> directory on the
+Tape Coordinator machine if it exists.
+
+The F<CFG_I<device_name>> file does not replace the
+F</usr/afs/backup/tapeconfig> file, a single copy of which still must
+exist on every Tape Coordinator machine.
+
+To enable the Tape Coordinator to locate the configuration file, construct
+the variable part of the filename, I<device_name>, as follows:
+
+=over 4
+
+=item *
+
+For a tape device, strip off the initial C</dev/> string from the device
+name, and replace any other slashes in the name with underscores. For
+example, F<CFG_rmt_4m> is the appropriate filename for a device called
+F</dev/rmt/4m>.
+
+=item *
+
+For a backup data file, strip off the initial slash (C</>) and replace any
+other slashes in the name with underscores. For example,
+F<CFG_var_tmp_FILE> is the appropriate filename for a backup data file
+called F</var/tmp/FILE>.
+
+=back
+
+The F<CFG_I<device_name>> file lists one or more of the following
+instructions, each on its own line. All are optional, and they can appear
+in any order. A more detailed description of each instruction follows the
+list:
+
+=over 4
+
+=item ASK
+
+Controls whether the Tape Coordinator prompts for guidance when it
+encounters error conditions.
+
+=item AUTOQUERY
+
+Controls whether the Tape Coordinator prompts for the first tape.
+
+=item BUFFERSIZE
+
+Sets the size of the memory buffer the Tape Coordinator uses when
+transferring data.
+
+=item FILE
+
+Controls whether the dump is written to a tape device or a file.
+
+=item MOUNT
+
+Identifies the file that contains routines for inserting tapes into the
+device's drive.
+
+=item NAME_CHECK
+
+Controls whether the Tape Coordinator verifies that a tape's AFS tape
+name matches the dump being written.
+
+=item UNMOUNT
+
+Identifies the file that contains routines for removing tapes from the
+device's drive.
+
+=back
+
+=head2 The ASK Instruction
+
+The C<ASK> instruction takes a boolean value as its argument, in the
+following format:
+
+ ASK (YES | NO)
+
+When the value is C<YES>, the Tape Coordinator generates a prompt in its
+window, requesting a response to the error cases described in the
+following list. This is the default behavior if the C<ASK> instruction
+does not appear in the F<CFG_I<device_name>> file.
+
+When the value is C<NO>, the Tape Coordinator does not prompt in error
+cases, but instead uses the automatic default responses described in the
+following list. The Tape Coordinator also logs the error in the
+F<TE_I<device_name>> file. Suppressing the prompts enables the Tape
+Coordinator to run unattended, though it still prompts for insertion of
+tapes unless the C<MOUNT> instruction is used.
+
+The error cases controlled by this instruction are the following:
+
+=over 4
+
+=item *
+
+The Backup System is unable to dump a volume while running the backup dump
+command. With a C<YES> value, the Tape Coordinator prompts to offer three
+choices: try to dump the volume again immediately, omit the volume from
+the dump but continue the operation, or terminate the operation. With a
+C<NO> value, the Tape Coordinator omits the volume from the dump and
+continues the operation.
+
+=item *
+
+The Backup System is unable to restore a volume while running the B<backup
+diskrestore>, B<backup volrestore>, or B<backup volsetrestore>
+command. With a C<YES> value, the Tape Coordinator prompts to offer two
+choices: omit the volume and continue restoring the other volumes, or
+terminate the operation. With a C<NO> value, it continues the operation
+without prompting, omitting the problematic volume but restoring the
+remaining ones.
+
+=item *
+
+The Backup System cannot determine if the dump set includes any more
+tapes, while running the B<backup scantape> command (the reference page
+for that command discusses possible reasons for this problem). With a
+C<YES> value, the Tape Coordinator prompts to ask if there are more tapes
+to scan. With a C<NO> value, it proceeds as though there are more tapes
+and invokes the routine named by the C<MOUNT> instruction in the
+configuration file, or prompts the operator to insert the next tape.
+
+=item *
+
+The Backup System determines that the tape contains an unexpired dump
+while running the B<backup labeltape> command. With a C<YES> value, the
+Tape Coordinator prompts to offer two choices: continue or terminate the
+labeling operation. With a C<NO> value, it terminates the operation
+without relabeling the tape.
+
+=back
+
+=head2 The AUTOQUERY Instruction
+
+The C<AUTOQUERY> instruction takes a boolean value as its argument,
+in the following format:
+
+ AUTOQUERY (YES | NO)
+
+When the value is C<YES>, the Tape Coordinator checks for the C<MOUNT>
+instruction in the configuration file when it needs to read the first tape
+involved in an operation. As described for that instruction, it then
+either prompts for the tape or invokes the specified routine to mount the
+tape. This is the default behavior if the C<AUTOQUERY> instruction does
+not appear in the configuration file.
+
+When the value is C<NO>, the Tape Coordinator assumes that the first tape
+required for an operation is already in the drive. It does not prompt the
+operator or invoke the C<MOUNT> routine unless there is an error in
+accessing the first tape. This setting is equivalent in effect to
+including the B<-noautoquery> flag to the B<butc> command.
+
+Note that the setting of the C<AUTOQUERY> instruction controls the Tape
+Coordinator's behavior only with respect to the first tape required for an
+operation. For subsequent tapes, the Tape Coordinator always checks for
+the C<MOUNT> instruction. It also refers to the C<MOUNT> instruction if it
+encounters an error while attempting to access the first tape.
+
+=head2 The BUFFERSIZE Instruction
+
+The C<BUFFERSIZE> instruction takes an integer value, and optionally
+units, in the following format:
+
+ BUFFERSIZE <size>[(k | K | m | M | g | G)]
+
+where <size> specifies the amount of memory the Tape Coordinator allocates
+to use as a buffer during both dump and restore operations. The default
+unit is bytes, but use C<k> or C<K> to specify kilobytes, C<m> or C<M> for
+megabytes, and C<g> or C<G> for gigabytes. There is no space between the
+<size> value and the units letter.
+
+By default, the Tape Coordinator uses a 16 KB buffer during dump
+operations. As it receives volume data from the Volume Server, the Tape
+Coordinator gathers 16 KB of data in the buffer before transferring the
+entire 16 KB to the tape device or backup data file. Similarly, during a
+restore operation the Tape Coordinator by default buffers 32 KB of data
+from the tape device or backup data file before transferring the entire 32
+KB to the Volume Server for restoration into the file system. Buffering
+makes the volume of data flowing to and from a tape device more even and
+so promotes tape streaming, which is the most efficient way for a tape
+device to operate.
+
+In a normal network configuration, the default buffer sizes are usually
+large enough to promote tape streaming. If the network between the Tape
+Coordinator machine and file server machines is slow, it can help to
+increase the buffer size.
+
+=head2 The FILE Instruction
+
+The C<FILE> instruction takes a boolean value as its argument, in the
+following format:
+
+ FILE (NO | YES)
+
+When the value is C<NO>, the Tape Coordinator writes to a tape device
+during a dump operation and reads from one during a restore
+operation. This is the default behavior if the C<FILE> instruction does
+not appear in the configuration file.
+
+When the value is C<YES>, the Tape Coordinator writes volume data to a
+backup data file on the local disk during a dump operation and reads
+volume data from a file during a restore operation. If the file does not
+exist when the Tape Coordinator attempts to access it to write a dump, the
+Tape Coordinator creates it. For a restore operation to succeed, the file
+must exist and contain volume data previously written to it by a B<backup
+dump> operation.
+
+When the value is C<YES>, the backup data file's complete pathname must
+appear (instead of a tape drive device name) in the third field of the
+corresponding port offset entry in the local F</usr/afs/backup/tapeconfig>
+file. If the field instead refers to a tape device, dump operations appear
+to succeed but are inoperative. It is not possible to restore data that
+was accidently dumped to a tape device while the C<FILE> instruction was
+set to C<YES>. (In the same way, if the C<FILE> instruction is set to
+C<NO>, the F<tapeconfig> entry must refer to an actual tape device.)
+
+Rather than put an actual file pathname in the third field of the
+F<tapeconfig> file, however, the recommended configuration is to create a
+symbolic link in the F</dev> directory that points to the actual file
+pathname, and record the symbolic link in this field. This configuration
+has a couple of advantages:
+
+=over 4
+
+=item *
+
+It makes the I<device_name> portion of the F<CFG_I<device_name>>,
+F<TE_I<device_name>>, and F<TL_I<device_name>> names as short as
+possible. Because the symbolic link is in the F</dev> directory as though
+it were a tape device, the device configuration file's name is constructed
+by stripping off the entire F</dev/> prefix, instead of just the initial
+slash. If, for example, the symbolic link is called F</dev/FILE>, the
+device configuration file name is F<CFG_FILE>, whereas if the actual
+pathname F</var/tmp/FILE> appears in the B<tapeconfig> file, the file's
+name must be F<CFG_var_tmp_FILE>.
+
+=item *
+
+It provides for a more graceful, and potentially automated, recovery if
+the Tape Coordinator cannot write a complete dump into the backup data
+file (because the partition housing the backup data file becomes full, for
+example). The Tape Coordinator's reaction to this problem is to invoke the
+C<MOUNT> script, or to prompt the operator if the C<MOUNT> instruction
+does not appear in the configuration file.
+
+=over 4
+
+=item *
+
+If there is a C<MOUNT> routine, the operator can prepare for this
+situation by adding a subroutine that changes the symbolic link to point
+to another backup data file on a partition where there is space available.
+
+=item *
+
+If there is no C<MOUNT> instruction, the prompt enables the operator
+manually to change the symbolic link to point to another backup data file,
+then press Return to signal that the Tape Coordinator can continue the
+operation.
+
+=back
+
+=back
+
+If the third field in the F<tapeconfig> file names the actual file, there
+is no way to recover from exhausting the space on the partition that
+houses the backup data file. It is not possible to change the
+F<tapeconfig> file in the middle of an operation.
+
+When writing to a backup data file, the Tape Coordinator writes data at 16
+KB offsets. If a given block of data (such as the marker that signals the
+beginning or end of a volume) does not fill the entire 16 KB, the Tape
+Coordinator still skips to the next offset before writing the next
+block. In the output of a B<backup dumpinfo> command issued with the
+B<-id> option, the value in the C<Pos> column is the ordinal of the 16-KB
+offset at which the volume data begins, and so is not generally only one
+higher than the position number on the previous line, as it is for dumps
+to tape.
+
+=head2 The MOUNT Instruction
+
+The C<MOUNT> instruction takes a pathname as its argument, in the
+following format:
+
+ MOUNT <filename>
+
+The referenced executable file must reside on the local disk and contain a
+shell script or program that directs an automated tape device, such as a
+jukebox or stacker, to mount a tape (insert it into the tape reader). The
+operator must write the routine to invoke the mount command specified by
+the device's manufacturer; AFS does not include any scripts, although an
+example appears in L<EXAMPLES>. The script or program inherits the Tape
+Coordinator's AFS authentication status.
+
+When the Tape Coordinator needs to mount a tape, it checks the
+configuration file for a C<MOUNT> instruction. If there is no C<MOUNT>
+instruction, the Tape Coordinator prompts the operator to insert a tape
+before it attempts to open the tape device. If there is a C<MOUNT>
+instruction, the Tape Coordinator executes the routine in the referenced
+file. The routine invoked by the C<MOUNT> instruction inherits the local
+identity (UNIX UID) and AFS tokens of the B<butc> command's issuer.
+
+There is an exception to this sequence: if the C<AUTOQUERY NO> instruction
+appears in the configuration file, or the B<-noautoquery> flag was
+included on the B<butc> command, then the Tape Coordinator assumes that
+the operator has already inserted the first tape needed for a given
+operation. It attempts to read the tape immediately, and only checks for
+the C<MOUNT> instruction or prompts the operator if the tape is missing or
+is not the required one.
+
+When the Tape Coordinator invokes the routine indicated by the C<MOUNT>
+instruction, it passes the following parameters to the routine in the
+indicated order:
+
+=over 4
+
+=item *
+
+The tape device or backup data file's pathname, as recorded in the
+F</usr/afs/backup/tapeconfig> file.
+
+=item *
+
+The tape operation, which (except for the exceptions noted in the
+following list) matches the B<backup> command operation code used to
+initiate the operation:
+
+=over 4
+
+=item *
+
+C<appenddump> (when a backup dump command includes the B<-append> flag).
+
+=item *
+
+C<dump> (when a backup dump command does not include the B<-append> flag).
+
+=item *
+
+C<labeltape>
+
+=item *
+
+C<readlabel>
+
+=item *
+
+C<restore> (for a B<backup diskrestore>, backup volrestore, or B<backup
+volsetrestore> command).
+
+=item *
+
+C<restoredb>
+
+=item *
+
+C<savedb>
+
+=item *
+
+C<scantape>
+
+=back
+
+=item *
+
+The number of times the Tape Coordinator has attempted to open the tape
+device or backup data file. If the open attempt returns an error, the Tape
+Coordinator increments this value by one and again invokes the C<MOUNT>
+instruction.
+
+=item *
+
+The tape name. For some operations, the Tape Coordinator passes the string
+C<none>, because it does not know the tape name (when running the B<backup
+scantape> or B<backup readlabel>, for example), or because the tape does
+not necessarily have a name (when running the B<backup labeltape> command,
+for example).
+
+=item *
+
+The tape ID recorded in the Backup Database. As with the tape name, the
+Backup System passes the string C<none> for operations where it does not
+know the tape ID or the tape does not necessarily have an ID.
+
+=back
+
+The routine invoked by the C<MOUNT> instruction must return an exit code
+to the Tape Coordinator:
+
+=over 4
+
+=item *
+
+Code 0 (zero) indicates that the routine successfully mounted the
+tape. The Tape Coordinator continues the backup operation. If the routine
+invoked by the C<MOUNT> instruction does not return this exit code, the
+Tape Coordinator never calls the C<UNMOUNT> instruction.
+
+=item *
+
+Code 1 (one) indicates that the routine failed to mount the tape. The Tape
+Coordinator terminates the operation.
+
+=item *
+
+Any other code indicates that the routine was not able to access the
+correct tape. The Tape Coordinator prompts the operator to insert the
+correct tape.
+
+=back
+
+If the backup command was issued in interactive mode and the operator
+issues the B<backup kill> command while the C<MOUNT> routine is running,
+the Tape Coordinator passes the termination signal to the routine; the
+entire operation terminates.
+
+=head2 The NAME_CHECK Instruction
+
+The C<NAME_CHECK> instruction takes a boolean value as its argument, in
+the following format:
+
+ NAME_CHECK (YES | NO)
+
+When the value is C<YES> and the tape does not have a permanent name, the
+Tape Coordinator checks the AFS tape name when dumping a volume in
+response to the B<backup dump> command. The AFS tape name must be C<<
+<NULL> >> or match the tape name that the B<backup dump> operation assigns
+based on the volume set and dump level names. This is the default behavior
+if the C<NAME_CHECK> instruction does not appear in the configuration
+file.
+
+When the value is C<NO>, the Tape Coordinator does not check the AFS tape
+name before writing to the tape.
+
+The Tape Coordinator always checks that all dumps on the tape are expired,
+and refuses to write to a tape that contains unexpired dumps.
+
+=head2 The UNMOUNT Instruction
+
+The C<UNMOUNT> instruction takes a pathname as its argument, in the
+following format:
+
+ UNMOUNT <filename>
+
+The referenced executable file must reside on the local disk and contain a
+shell script or program that directs an automated tape device, such as a
+jukebox or stacker, to unmount a tape (remove it from the tape reader).
+The operator must write the routine to invoke the unmount command
+specified by the device's manufacturer; AFS does not include any scripts,
+although an example appears in L<EXAMPLES>. The script or program
+inherits the Tape Coordinator's AFS authentication status.
+
+After closing a tape device, the Tape Coordinator checks the configuration
+file for an C<UNMOUNT> instruction, whether or not the B<close> operation
+succeeds. If there is no C<UNMOUNT> instruction, the Tape Coordinator
+takes no action, in which case the operator must take the action necessary
+to remove the current tape from the drive before another can be
+inserted. If there is an C<UNMOUNT> instruction, the Tape Coordinator
+executes the referenced file. It invokes the routine only once, passing in
+the following parameters:
+
+=over 4
+
+=item *
+
+The tape device pathname (as specified in the
+F</usr/afs/backup/tapeconfig> file).
+
+=item *
+
+The tape operation (always unmount).
+
+=back
+
+=head1 PRIVILEGE REQUIRED
+
+The file is protected by UNIX mode bits. Creating the file requires the
+C<w> (write) and C<x> (execute) permissions on the F</usr/afs/backup>
+directory. Editing the file requires the C<w> (write) permission on the
+file.
+
+=head1 EXAMPLES
+
+The following example configuration files demonstrate one way to structure
+a configuration file for a stacker or backup dump file. The examples are
+not necessarily appropriate for a specific cell; if using them as models,
+be sure to adapt them to the cell's needs and equipment.
+
+=head2 Example F<CFG_I<device_name>> File for Stackers
+
+In this example, the administrator creates the following entry for a tape
+stacker called C<stacker0.1> in the F</usr/afs/backup/tapeconfig> file. It
+has port offset 0.
+
+ 2G 5K /dev/stacker0.1 0
+
+The administrator includes the following five lines in the
+F</usr/afs/backup/CFG_stacker0.1> file. To review the meaning of each
+instruction, see L<DESCRIPTION>.
+
+ MOUNT /usr/afs/backup/stacker0.1
+ UNMOUNT /usr/afs/backup/stacker0.1
+ AUTOQUERY NO
+ ASK NO
+ NAME_CHECK NO
+
+Finally, the administrator writes the following executable routine in the
+F</usr/afs/backup/stacker0.1> file referenced by the C<MOUNT> and
+C<UNMOUNT> instructions in the F<CFG_stacker0.1> file.
+
+ #! /bin/csh -f
+
+ set devicefile = $1
+ set operation = $2
+ set tries = $3
+ set tapename = $4
+ set tapeid = $5
+
+ set exit_continue = 0
+ set exit_abort = 1
+ set exit_interactive = 2
+
+ #--------------------------------------------
+
+ if (${tries} > 1) then
+ echo "Too many tries"
+ exit ${exit_interactive}
+ endif
+
+ if (${operation} == "unmount") then
+ echo "UnMount: Will leave tape in drive"
+ exit ${exit_continue}
+ endif
+
+ if ((${operation} == "dump") |\
+ (${operation} == "appenddump") |\
+ (${operation} == "savedb")) then
+
+ stackerCmd_NextTape ${devicefile}
+ if (${status} != 0)exit${exit_interactive}
+ echo "Will continue"
+ exit ${exit_continue}
+ endif
+
+ if ((${operation} == "labeltape") |\
+ (${operation} == "readlabel")) then
+ echo "Will continue"
+ exit ${exit_continue}
+ endif
+
+ echo "Prompt for tape"
+ exit ${exit_interactive}
+
+This routine uses two of the parameters passed to it by the Backup System:
+C<tries> and C<operation>. It follows the recommended practice of
+prompting for a tape if the value of the C<tries> parameter exceeds one,
+because that implies that the stacker is out of tapes.
+
+For a B<backup dump> or backup savedb operation, the routine calls the
+example C<stackerCmd_NextTape> function provided by the stacker's
+manufacturer. Note that the final lines in the file return the exit code
+that prompts the operator to insert a tape; these lines are invoked when
+either the stacker cannot load a tape or a the operation being performed
+is not one of those explicitly mentioned in the file (such as a restore
+operation).
+
+=head2 Example F<CFG_I<device_name>> File for Dumping to a Data File
+
+In this example, the administrator creates the following entry for a
+backup data file called F<HSM_device> in the F</usr/afs/backup/tapeconfig>
+file. It has port offset 20.
+
+ 1G 0K /dev/HSM_device 20
+
+The administrator includes the following lines in the
+F</usr/afs/backup/CFG_HSM_device> file. To review the meaning of each
+instruction, see L<DESCRIPTION>.
+
+ MOUNT /usr/afs/backup/file
+ FILE YES
+ ASK NO
+
+Finally, the administrator writes the following executable routine in the
+F</usr/afs/backup/file> file referenced by the C<MOUNT> instruction in the
+F<CFG_HSM_device> file, to control how the Tape Coordinator handles the
+file.
+
+ #! /bin/csh -f
+ set devicefile = $1
+ set operation = $2
+ set tries = $3
+ set tapename = $4
+ set tapeid = $5
+
+ set exit_continue = 0
+ set exit_abort = 1
+ set exit_interactive = 2
+
+ #--------------------------------------------
+
+ if (${tries} > 1) then
+ echo "Too many tries"
+ exit ${exit_interactive}
+ endif
+
+ if (${operation} == "labeltape") then
+ echo "Won't label a tape/file"
+ exit ${exit_abort}
+ endif
+
+ if ((${operation} == "dump") |\
+ (${operation} == "appenddump") |\
+ (${operation} == "restore") |\
+ (${operation} == "savedb") |\
+ (${operation} == "restoredb")) then
+
+ /bin/rm -f ${devicefile}
+ /bin/ln -s /hsm/${tapename}_${tapeid} ${devicefile}
+ if (${status} != 0) exit ${exit_abort}
+ endif
+
+ exit ${exit_continue}
+
+Like the example routine for a tape stacker, this routine uses the
+C<tries> and C<operation> parameters passed to it by the Backup
+System. The C<tries> parameter tracks how many times the Tape Coordinator
+has attempted to access the file. A value greater than one indicates that
+the Tape Coordinator cannot access it, and the routine returns exit code 2
+(C<exit_interactive>), which results in a prompt for the operator to load
+a tape. The operator can use this opportunity to change the name of the
+backup data file specified in the B<tapeconfig> file.
+
+The primary function of this routine is to establish a link between the
+device file and the file to be dumped or restored. When the Tape
+Coordinator is executing a B<backup dump>, B<backup restore>, B<backup
+savedb>, or B<backup restoredb> operation, the routine invokes the UNIX
+C<ln -s> command to create a symbolic link from the backup data file named
+in the F<tapeconfig> file to the actual file to use (this is the
+recommended method). It uses the value of the C<tapename> and C<tapeid>
+parameters to construct the file name.
+
+=head1 SEE ALSO
+
+L<tapeconfig(5)>,
+L<backup_diskrestore(8)>,
+L<backup_dump(8)>,
+L<backup_restoredb(8)>,
+L<backup_savedb(8)>,
+L<backup_volrestore(8)>,
+L<backup_volsetrestore(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+butc_logs - Message logs from the Tape Coordinator process
+
+=head1 DESCRIPTION
+
+The Backup System Tape Coordinator (B<butc>) process generates two log
+files per device, one for error messages and one for actions.
+
+=head2 Error Message Log
+
+The F<TE_I<device_name>> file logs error messages generated by the Backup
+System Tape Coordinator that controls the tape device or backup data file
+indicated by I<device_name>.
+
+As the Tape Coordinator initializes, it creates the file in ASCII format
+in the F</usr/afs/backup> directory. If there is an existing file, the
+Tape Coordinator renames it to F<TE_I<device_name>.old>>, overwriting the
+existing F<TE_I<device_name>.old>> file if it exists.
+
+For a tape device, the Tape Coordinator derives the variable
+I<device_name> portion of the filename from the device pathname listed in
+the local F</usr/afs/backup/tapeconfig> file, by stripping off the initial
+C</dev/> string and replacing any other slashes in the name with
+underscores. For example, the filename for a device called F</dev/rmt/4m>
+is F<TE_rmt_4m>. Similarly, for a backup data file the Tape Coordinator
+strips off the initial slash (C</>) and replaces any other slashes in the
+name with underscores. For example, the filename for a backup data file
+called F</var/tmp/FILE> is F<TE_var_tmp_FILE>.
+
+The messages in the file describe the error and warning conditions the
+Tape Coordinator encounters as it operates. For instance, a message can
+list the volumes that are inaccessible during a dump operation, or warn
+that the Tape Coordinator is overwriting a tape or backup data file. The
+messages also appear in the F</usr/afs/backup/TL_I<device_name>> file,
+which traces most of the Tape Coordinator's actions.
+
+=head2 Action Log
+
+The F<TL_I<device_name>> file logs the actions performed by the Backup
+System Tape Coordinator that controls the tape device or backup data file
+indicated by I<device_name>. It also records the same error and warning
+messages written to the F<TE_I<device_name>> file.
+
+As the Tape Coordinator initializes, it creates the file in ASCII format
+in the F</usr/afs/backup> directory. If there is an existing file, the
+Tape Coordinator renames it to F<TL_I<device_name>.old>, overwriting the
+existing F<TL_I<device_name>.old> file if it exists.
+
+For a tape device, the Tape Coordinator derives the variable
+I<device_name> portion of the filename from the device pathname listed in
+the local F</usr/afs/backup/tapeconfig> file, by stripping off the initial
+C</dev/> string and replacing any other slashes in the name with
+underscores. For example, the filename for a device called F</dev/rmt/4m>
+is F<TL_rmt_4m>. Similarly, for a backup data file the Tape Coordinator
+strips off the initial slash (C</>) and replaces any other slashes in the
+name with underscores. For example, the filename for a backup data file
+called F</var/tmp/FILE> is F<TL_var_tmp_FILE>.
+
+=head1 SEE ALSO
+
+L<tapeconfig(5)>,
+L<butc(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+cacheinfo - Defines configuration parameters for the Cache Manager
+
+=head1 DESCRIPTION
+
+The F<cacheinfo> file defines configuration parameters for the Cache
+Manager, which reads the file as it initializes.
+
+The file contains a single line of ASCII text and must reside in the
+F</usr/vice/etc> directory. Use a text editor to create it during initial
+configuration of the client machine; the required format is as follows:
+
+ <mount>:<cache>:<size>
+
+where
+
+=over 4
+
+=item <mount>
+
+Names the local disk directory at which the Cache Manager mounts the AFS
+namespace. It must exist before the B<afsd> program runs. The conventional
+value is F</afs>. Using any other value prevents traversal of pathnames
+that begin with F</afs> (such as pathnames to files in foreign cells that
+do use the conventional name). The B<-mountdir> argument to the B<afsd>
+command overrides this value.
+
+=item <cache>
+
+Names the local disk directory to use as a cache. It must exist before the
+B<afsd> program runs. The standard value is F</usr/vice/cache>, but it is
+acceptable to substitute a directory on a partition with more available
+space. Although the Cache Manager ignores this field when configuring a
+memory cache, a value must always appear in it. The B<-cachedir> argument
+to the B<afsd> command overrides this value.
+
+=item <size>
+
+Specifies the cache size as a number of 1-kilobyte blocks. Larger caches
+generally yield better performance, but a disk cache must not exceed 90%
+of the space available on the cache partition (85% for AIX systems), and a
+memory cache must use no more than 25% of available machine memory.
+
+The B<-blocks> argument to the afsd command overrides this value. To reset
+cache size without rebooting on a machine that uses disk caching, use the
+B<fs setcachesize> command. To display the current size of a disk or
+memory cache between reboots, use the B<fs getcacheparms> command.
+
+=back
+
+=head1 EXAMPLES
+
+The following example cacheinfo file mounts the AFS namespace at F</afs>,
+establishes a disk cache in the F</usr/vice/cache> directory, and defines
+cache size as 50,000 1-kilobyte blocks.
+
+ /afs:/usr/vice/cache:50000
+
+=head1 SEE ALSO
+
+L<afsd(8)>,
+L<fs_getcacheparms(8)>,
+L<fs_setcachesize(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+fms.log - Records output from the fms command
+
+=head1 DESCRIPTION
+
+The F<fms.log> file records the output generated by the B<fms>
+command. The output includes two numbers that can appear in a tape
+device's entry in the F</usr/afs/backup/tapeconfig> file on the Tape
+Coordinator machine to which the tape device is attached:
+
+=over 4
+
+=item *
+
+The capacity in bytes of the tape in the device.
+
+=item *
+
+The size in bytes of the end-of-file (EOF) marks (often referred to simply
+as I<filemarks>) that the tape device writes.
+
+=back
+
+When transferring the numbers recorded in this file to the F<tapeconfig>
+file, adjust them as specified in L<tapeconfig(5)>, to improve Tape
+Coordinator performance during dump operations.
+
+If the F<fms.log> file does not already exist in the current working
+directory, the B<fms> command interpreter creates it. In this case, the
+directory's mode bits must grant the C<rwx> (read, write, and execute)
+permissions to the issuer of the command. If there is an existing file,
+the command interpreter overwrites it, so the file's mode bits need to
+grant only the B<w> permission to the issuer of the B<fms> command. The
+B<fms> command interpreter also writes similar information to the standard
+output stream as it runs.
+
+The file is in ASCII format. To display its contents, log onto the client
+machine and use a text editor or a file display command such as the UNIX
+B<cat> command. By default, the mode bits on the F<fms.log> file grant the
+required C<r> permission only to the owner (which is the local superuser
+C<root> by default).
+
+=head1 OUTPUT
+
+The first few lines of the file provide a simple trace of the B<fms>
+command interpreter's actions, specifying (for example) how many blocks it
+wrote on the tape. The final two lines in the file specify tape capacity
+and filemark size in bytes, using the following format:
+
+ Tape capacity is <tape_size> bytes
+ File marks are <filemark_size> bytes
+
+=head1 EXAMPLES
+
+The following example of the fms.log file specifies that the tape used
+during the execution of the B<fms> command had a capacity of 2,136,604,672
+bytes, and that the tape device writes filemarks of size 1,910,220 bytes.
+
+ fms test started
+ wrote 130408 blocks
+ Tape capacity is 2136604672 bytes
+ File marks are 1910220 bytes
+
+=head1 SEE ALSO
+
+L<tapeconfig(5)>,
+L<fms(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+prdb.DB0, prdb.DBSYS1 - Contain the Protection Database and associated log
+
+=head1 DESCRIPTION
+
+The F<prdb.DB0> file contains the Protection Database, which maps AFS
+user, machine, and group names to their respective IDs (AFS UIDs and GIDs)
+and tracks group memberships. The Protection Server (B<ptserver> process)
+uses the information in the database to help the File Server grant data
+access to authorized users.
+
+The F<prdb.DBSYS1> file is a log file in which the Protection Server logs
+each database operation before performing it. When an operation is
+interrupted, the Protection Server replays the log to complete the
+operation.
+
+Both files are in binary format and reside in the F</usr/afs/db> directory
+on each of the cell's database server machines. When the Protection Server
+starts or restarts on a given machine, it establishes a connection with
+its peers and verifies that its copy of the database matches the copy on
+the other database server machines. If not, the Protection Servers call on
+AFS's distributed database technology, Ubik, to distribute to all of the
+machines the copy of the database with the highest version number.
+
+Always use the commands in the B<pts> suite to administer the Protection
+Database. It is advisable to create an archive copy of the database on a
+regular basis, using a tool such as the UNIX B<tar> command.
+
+=head1 SEE ALSO
+
+L<prdb_check(8)>,
+L<pts(8)>,
+L<ptserver(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+salvage.lock - Prevents multiple simultaneous salvage operations on a partition
+
+=head1 DESCRIPTION
+
+The F<salvage.lock> file guarantees that only one Salvager (B<salvager>
+process) runs at a time on a file server machine (the single process can
+fork multiple subprocesses to salvage multiple partitions in parallel). As
+the Salvager initializes, it creates the empty (zero-length) file in the
+F</usr/afs/local> directory and invokes the B<flock> system call on it. It
+removes the file when it completes the salvage operation. Because the
+Salvager must lock the file to run, only one Salvager can run at a time.
+
+=head1 SEE ALSO
+
+L<salvager(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+sysid - Lists file server machine interface addresses registered in VLDB
+
+=head1 DESCRIPTION
+
+The F<sysid> file records the network interface addresses that the File
+Server (B<fileserver> process) registers in the Volume Location Database
+(VLDB) for the local file server machine.
+
+Each time the File Server restarts, it builds a list of interfaces on the
+local machine by reading the F</usr/afs/local/NetInfo> file, if it
+exists. If the file does not exist, the File Server uses the list of
+network interfaces configured with the operating system. It then removes
+from the list any addresses that appear in the
+F</usr/afs/local/NetRestrict> file, if it exists. The File Server records
+the resulting list in the binary-format F<sysid> file and registers the
+interfaces in the VLDB.
+
+When the Cache Manager requests volume location information, the Volume
+Location (VL) Server provides all of the interfaces registered for each
+server machine that houses the volume. This enables the Cache Manager to
+make use of multiple addresses when accessing AFS data stored on a
+multihomed file server machine.
+
+=head1 CAUTIONS
+
+The F<sysid> file is unique to each file server machine, and must not be
+copied from one machine to another. If it is a common practice in the cell
+to copy the contents of the F</usr/afs/local> directory from an existing
+file server machine to a newly installed one, be sure to remove the
+F<sysid> file from the new machine before starting the C<fs> trio of
+processes, which includes the B<fileserver> process.
+
+Some versions of AFS limit how many of a file server machine's interface
+addresses that can be registered. Consult the I<IBM AFS Release Notes>.
+
+=head1 SEE ALSO
+
+L<NetInfo(5)>,
+L<NetRestrict(5)>,
+L<vldb.DB0(5)>,
+L<fileserver(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+tapeconfig - Defines parameters for tape devices and backup data files
+
+=head1 DESCRIPTION
+
+The F<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:
+
+ [<capacity> <filemark_size>] <device_name> <port_offset>
+
+where
+
+=over 4
+
+=item <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 B<-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 *
+
+C<k> or C<K> for kilobytes (KB).
+
+=item *
+
+C<m> or C<M> for megabytes (MB).
+
+=item *
+
+C<g> or C<G> for gigabytes (GB).
+
+=item *
+
+C<t> or C<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
+<filemark_size> field empty, or provide a value in both of them.
+
+=item <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 <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 <capacity> field empty, or
+provide a value in both of them.
+
+=item <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
+C<FILE> instruction in L<butc(5)>.
+
+=item <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 C<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 F<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 C<w> (write) and C<x> (execute)
+permissions on the F</usr/afs/backup> directory. Editing the file requires
+UNIX C<w> (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(8)>,
+L<fms(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+vldb.DB0, vldb.DBSYS1 - Contain the Volume Location Database and associated log
+
+=head1 DESCRIPTION
+
+The file F<vldb.DB0> contains the Volume Location Database (VLDB), which
+tracks the location of all AFS volumes stored on file server machines in
+the cell. The Volume Location (VL) Server (B<vlserver> process) provides
+information from the database to Cache Managers when they need to access
+AFS data.
+
+The file F<vldb.DBSYS1> is a log file in which the VL Server logs each
+database operation before performing it. When an operation is interrupted,
+the VL Server replays the log to complete the operation.
+
+Both files are in binary format and reside in the F</usr/afs/db> directory
+on each of the cell's database server machines. When the VL Server starts
+or restarts on a given machine, it establishes a connection with its peers
+and verifies that its copy of the database matches the copy on the other
+database server machines. If not, the VL Servers call on AFS's distributed
+database technology, Ubik, to distribute to all of the machines the copy
+of the database with the highest version number.
+
+Always use the commands in the B<vos> suite to administer the VLDB. It is
+advisable to create an archive copy of the database on a regular basis,
+using a tool such as the UNIX B<tar> command.
+
+=head1 SEE ALSO
+
+L<vldb_check(8)>,
+L<vlserver(8)>,
+L<vos(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
+
+afsd - Initializes the Cache Manager and starts related daemons
+
+=head1 SYNOPSIS
+
+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 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
+
+=item *
+
+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 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
+machines, prevents the Cache Manager from accessing files in it.
+
+The list of database server machines is transferred into the kernel from
+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
+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 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.
+
+=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.
+
+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 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:
+
+=over 4
+
+=item *
+
+The B<-blocks> argument, to specify a different number of kilobyte blocks.
+
+=item *
+
+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 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
+available, the B<afsd> program exits without initializing the Cache
+Manager and produces the following message on the standard output stream:
+
+ afsd: memCache allocation failure at <number> KB
+
+where <number> is how many kilobytes were allocated just before the
+failure.
+
+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.
+
+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.
+
+=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
+much data per fetch RPC, since AFS uses partial file transfer).
+
+For a disk cache, a chunk is a F<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.
+
+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 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 (F<VI<n>> files) is set to the largest
+of the following unless the B<-files> argument is used to set the value
+explicitly:
+
+=over 4
+
+=item *
+
+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<VI<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.
+
+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.
+
+=item *
+
+Randomly selects a file server machine in the local cell as the source for
+the correct time. Every five minutes thereafter, the local clock is
+adjusted (if necessary) to match the file server machine's clock.
+
+Use the B<-nosettime> flag to prevent the afsd command from selecting a
+time standard. This is recommended only on file server machines that are
+also acting as clients. File server machines maintain the correct time
+using the Network Time Protocol Daemon instead.
+
+=back
+
+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.
+
+=item *
+
+One I<maintenance> daemon, which performs the following tasks:
+
+=over 4
+
+=item *
+
+Garbage collects obsolete data (for example, expired tokens) from kernel
+memory.
+
+=item *
+
+Synchronizes files.
+
+=item *
+
+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.
+
+=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
+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
+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.
+
+=item *
+
+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
+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.
+
+=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:
+
+=over 4
+
+=item *
+
+If the B<-biods> argument is used, it sets the number of VM daemons.
+
+=item *
+
+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 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 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
+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 B<-files> <I<files in cache>>
+
+Specifies the number of F<VI<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<VI<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 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 F</afs> directory). This value
+overrides the default of the C<root.afs> volume.
+
+=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 C<300>.
+
+=item B<-memcache>
+
+Initializes a memory cache rather than a disk cache. Do not combine this
+flag with the B<-files> argument.
+
+=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
+F</usr/vice/etc/cacheinfo> file.
+
+=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 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 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 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.
+
+=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
+machine every five minutes. Use this flag only on a machine that is
+already using another time synchronization protocol (for example, a server
+machine that is running the B<runntp> process).
+
+=item B<-verbose>
+
+Generates a detailed trace of the B<afsd> program's actions on the
+standard output stream.
+
+=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.
+
+=item B<-debug>
+
+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 B<-chunksize> <I<chunk size>>
+
+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 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 F<VI<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.
+
+=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 C<50>.
+
+=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.
+
+=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 C<400>, but the Cache
+Manager dynamically allocates more memory as it needs it.
+
+=item B<-confdir> <I<configuration directory>>
+
+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 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 F</usr/vice/etc/AFSLog>.
+
+=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
+writes to the File Server, is now the default behavior. To perform
+asynchronous writes in certain cases, use the B<fs storebehind> command.
+
+=item B<-shutdown>
+
+Shuts down the Cache Manager, but not in the most effective possible
+way. Do not use this flag.
+
+=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.
+
+=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,
+GetStatus, and so on) sent or received, aggregated over all connections to
+other machines. To display or otherwise access the records, use the Rx
+Monitoring API.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+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
+
+The following command is appropriate when enabling a machine to act as an
+NFS/AFS Translator machine serving more than five users.
+
+ /usr/vice/etc/afsd -daemons 4 -rmtsys
+
+The following command initializes a memory cache and sets chunk size to 16
+KB (2^14).
+
+ /usr/vice/etc/afsd -memcache -chunksize 14
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be logged in as the local superuser root.
+
+=head1 SEE ALSO
+
+L<afs_cache(5)>,
+L<CellServDB(5)>,
+L<cacheinfo(5)>
+
+=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
+
+backup - Introduction to the backup command suite
+
+=head1 DESCRIPTION
+
+The commands in the B<backup> command suite are the administrative
+interface to the AFS Backup System. There are several categories of
+commands in the suite:
+
+=over 4
+
+=item *
+
+Commands to copy data from AFS volumes to tape or a backup data file, and
+to restore it to the file system: 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>.
+
+=item *
+
+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>.
+
+=item *
+
+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>.
+
+=item *
+
+Commands to obtain help: B<backup apropos> and B<backup help>.
+
+=back
+
+The backup command interpreter interacts with two other processes:
+
+=over 4
+
+=item *
+
+The Backup Server (B<buserver>) process. It maintains the Backup Database,
+which stores most of the administrative information used by the Backup
+System. In the standard configuration, the Backup Server runs on each
+database server machine in the cell, and uses AFS's distributed database
+technology, Ubik, to synchronize its copy of the database with the copies
+on the other database server machines.
+
+=item *
+
+The Backup Tape Coordinator (B<butc>) process. A separate instance of the
+process controls each tape device or backup data file used to dump or
+restore data. The Tape Coordinator runs on a Tape Coordinator machine,
+which is an AFS server or client machine that has one or more tape devices
+attached, or has sufficient disk space to accommodate one or more backup
+data files on its local disk.
+
+Each Tape Coordinator must be registered in the Backup Database and in the
+F</usr/afs/backup/tapeconfig> configuration file on the Tape Coordinator
+machine's local disk, and information in the two places must be consistent
+for proper Backup System performance. The optional
+F</usr/afs/backup/CFG_I<device_name>> for each Tape Coordinator records
+information used to automate its operation.
+
+=back
+
+In addition to the standard command line interface, the B<backup> command
+suite provides an I<interactive> interface, which has several useful
+features described in L<backup_interactive(8)>. Three of the commands in
+the suite are available only in interactive mode: 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.
+
+=over 4
+
+=item B<-cell> <I<cell name>>
+
+Names the cell in which to run the command. It is acceptable to abbreviate
+the cell name to the shortest form that distinguishes it from the other
+entries in the F</usr/vice/etc/CellServDB> file on the local machine. If
+the B<-cell> argument is omitted, the command interpreter determines the
+name of the local cell by reading the following in order:
+
+=over 4
+
+=item *
+
+The value of the AFSCELL environment variable.
+
+=item *
+
+The local F</usr/vice/etc/ThisCell> file.
+
+=back
+
+Do not combine the B<-cell> and B<-localauth> options. A command on which
+the B<-localauth> flag is included always runs in the local cell (as
+defined in the server machine's local F</usr/afs/etc/ThisCell> file),
+whereas a command on which the B<-cell> argument is included runs in the
+specified foreign cell.
+
+The B<-cell> argument is not available on commands issued in interactive
+mode. The cell defined when the B<backup> command interpreter enters
+interactive mode applies to all commands issued during the interactive
+session.
+
+=item B<-help>
+
+Prints a command's online help message on the standard output stream. Do
+not combine this flag with any of the command's other options; when it is
+provided, the command interpreter ignores all other options, and only
+prints the help message.
+
+=item B<-localauth>
+
+Constructs a server ticket using the server encryption key with the
+highest key version number in the local F</usr/afs/etc/KeyFile> file. The
+B<backup> command interpreter presents the ticket, which never expires, to
+the Backup Server, Volume Server and Volume Location (VL) Server during
+mutual authentication.
+
+Use this flag only when issuing a command on a server machine; client
+machines do not usually have a F</usr/afs/etc/KeyFile> file. The issuer
+of a command that includes this flag must be logged on to the server
+machine as the local superuser C<root>. The flag is useful for commands
+invoked by an unattended application program, such as a process controlled
+by the UNIX B<cron> utility or by a cron entry in the machine's
+F</usr/afs/local/BosConfig> file. It is also useful if an administrator is
+unable to authenticate to AFS but is logged in as the local superuser
+C<root>.
+
+Do not combine the B<-cell> and B<-localauth> options. A command on which
+the B<-localauth> flag is included always runs in the local cell (as
+defined in the server machine's local F</usr/afs/etc/ThisCell> file),
+whereas a command on which the B<-cell> argument is included runs in the
+specified foreign cell.
+
+The B<-localauth> argument is not available on commands issued in
+interactive mode. The local identity and AFS tokens with which the
+B<backup> command interpreter enters interactive mode apply to all
+commands issued during the interactive session.
+
+=item B<-portoffset> <I<TC port offset>>
+
+Specifies the port offset number of the Tape Coordinator that is to
+execute the B<backup> command. The port offset number uniquely identifies
+a pairing of a Tape Coordinator (B<butc>) process and tape device or
+backup data file.
+
+The backup command interpreter and Tape Coordinator process communicate
+via a UDP socket, or port. Before issuing a B<backup> command that
+involves reading or writing a tape, the backup operator must start a
+B<butc> process that controls the appropriate tape device and listens for
+requests sent to its port number. If a Backup System machine has multiple
+tape devices attached, they can perform backup operations simultaneously
+because each device has its own associated B<butc> process and port offset
+number.
+
+The Backup System associates a tape capacity and file mark size with each
+port offset (as defined in the F<tapeconfig> file). For a compressing tape
+device, the capacity and file mark values differ for compression and
+non-compression modes, so the two modes have distinct port offset numbers.
+
+The Backup Database can store up to 58,511 port offsets, so the legal
+values for this argument are the integers C<0> through C<58510>. If the
+issuer omits the argument, it defaults to C<0>. (The limit of 58,511 port
+offsets results from the fact that UDP socket numbers are identified by a
+16-bit integer, and the lowest socket number used by the Backup System is
+7025. The largest number that a 16-bit integer can represent is
+65,535. Subtracting 7,025 yields 58,510. The addition of port offset 0
+(zero) increases the maximum to 58,511.)
+
+Although it is possible to define up to 58,511 port offset numbers for a
+cell, it is not possible to run 58,511 tape devices simultaneously, due to
+the following limits:
+
+=over 4
+
+=item *
+
+The maximum number of dump or restore operations that can run
+simultaneously is 64.
+
+=item *
+
+The maximum number of tape devices that can work together on a restore
+operation is 128 (that is the maximum number of values that can be
+provided for the B<-portoffset> argument to the 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:
+
+ bind: Address already in use
+ rxi_GetUDPSocket: bind failed
+
+=back
+
+=head1 PRIVILEGE REQUIRED
+
+To issue any backup command that accesses the Backup Database only, the
+issuer must be listed in the F</usr/afs/etc/UserList> file on every
+machine where the Backup Server is running. To issue any B<backup> command
+that accesses volume data, the issuer must appear in the F<UserList> file
+on every Backup Server machine, every Volume Location (VL) Server machine,
+and every file server machine that houses affected volumes. By convention,
+a common F<UserList> file is distributed to all database server and file
+server machines in the cell. See the chapter on privileged users in the
+I<IBM AFS Administration Guide> for more information on this type of
+privilege.
+
+If the B<-localauth> flag is included, the user must instead be logged on
+as the local superuser C<root> on the server machine where the B<backup>
+command is issued.
+
+=head1 SEE ALSO
+
+L<BosConfig(5)>,
+L<CellServDB(5)>,
+L<KeyFile(5)>,
+L<ThisCell(5)>,
+L<UserList(5)>,
+L<butc(5)>,
+L<tapeconfig(5)>,
+L<backup_adddump(8)>,
+L<backup_addhost(8)>,
+L<backup_addvolentry(8)>,
+L<backup_addvolset(8)>,
+L<backup_dbverify(8)>,
+L<backup_deldump(8)>,
+L<backup_deletedump(8)>,
+L<backup_delhost(8)>,
+L<backup_delvolentry(8)>,
+L<backup_delvolset(8)>,
+L<backup_diskrestore(8)>,
+L<backup_dump(8)>,
+L<backup_dumpinfo(8)>,
+L<backup_help(8)>,
+L<backup_interactive(8)>,
+L<backup_jobs(8)>,
+L<backup_kill(8)>,
+L<backup_labeltape(8)>,
+L<backup_listdumps(8)>,
+L<backup_listhosts(8)>,
+L<backup_listvolsets(8)>,
+L<backup_quit(8)>,
+L<backup_readlabel(8)>,
+L<backup_restoredb(8)>,
+L<backup_savedb(8)>,
+L<backup_scantape(8)>,
+L<backup_setexp(8)>,
+L<backup_status(8)>,
+L<backup_volinfo(8)>,
+L<backup_volrestore(8)>,
+L<backup_volsetrestore(8)>,
+L<buserver(8)>,
+L<butc(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+backup adddump - Defines a dump level in the dump hierarchy
+
+=head1 SYNOPSIS
+
+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> B<-d> <I<dump level name>>+ [B<-e> <I<expiration date>>+]
+ [B<-l>] [B<-c> <I<cell name>>] [B<-h>]
+
+=head1 DESCRIPTION
+
+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.)
+
+Define either an absolute or relative expiration date:
+
+=over 4
+
+=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.
+
+=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.
+
+=back
+
+=head1 OPTIONS
+
+=over 4
+
+=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, 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.
+
+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 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:
+
+ [at] {NEVER | <mm>/<dd>/<yyyy> [<hh>:<MM>] }
+
+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: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:
+
+ [in] [<years>y] [<months>m] [<days>d]
+
+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 B<-localauth>
+
+Constructs a server ticket using a key from the local
+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 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<backup(8)>.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+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
+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,
+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 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(8)>,
+L<backup_deldump(8)>,
+L<backup_deletedump(8)>,
+L<backup_listdumps(8)>,
+L<backup_setexp(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+backup addhost - Adds a Tape Coordinator entry to the Backup Database
+
+=head1 SYNOPSIS
+
+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> B<-t> <I<tape machine name>> [B<-p> <I<TC port offset>>]
+ [B<-l>] [B<-c> <I<cell name>>] [B<-h>]
+
+=head1 DESCRIPTION
+
+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.
+
+=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 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
+B<backup listhosts> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=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 (F</etc/hosts> or equivalent) on the machine
+where the command is issued.
+
+=item B<-portoffset> <I<TC port offset>>
+
+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 B<-localauth>
+
+Constructs a server ticket using a key from the local
+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 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<backup(8)>.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command creates an entry in the Backup Database that assigns
+port offset number 4 to a Tape Coordinator running on the machine
+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 C<backup3.abc.com>:
+
+ % backup addhost backup3.abc.com
+
+=head1 PRIVILEGE REQUIRED
+
+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(8)>,
+L<backup_delhost(8)>,
+L<backup_listhosts(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+backup addvolentry - Defines a volume entry in a volume set
+
+=head1 SYNOPSIS
+
+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> 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 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 B<-partition> arguments, provide either
+
+=over 4
+
+=item *
+
+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).
+
+=back
+
+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. 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
+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
+set was created.
+
+=head1 OPTIONS
+
+=over 4
+
+=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).
+
+=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
+C<fs1.abc.com>) or the metacharacter expression C<.*> (period and
+asterisk), which matches all machine names in the VLDB.
+
+=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
+C</vicepa>) or the metacharacter expression C<.*> (period and asterisk),
+which matches all partition names.
+
+=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:
+
+=over 4
+
+=item .
+
+The period matches any single character.
+
+=item *
+
+The asterisk matches zero or more instances of the preceding character.
+Combine it with any other alphanumeric character or metacharacter.
+
+=item [ ]
+
+Square brackets around a list of characters match a single instance of any
+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, 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 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 (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 B<-localauth>
+
+Constructs a server ticket using a key from the local
+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 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<backup(8)>.
+
+=item B<-help>
+
+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
+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 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.
+
+=head1 PRIVILEGE REQUIRED
+
+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(8)>,
+L<backup_addvolset(8)>,
+L<backup_delvolentry(8)>,
+L<backup_delvolset(8)>,
+L<backup_listvolsets(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+backup addvolset - Creates a new (empty) volume set
+
+=head1 SYNOPSIS
+
+B<backup addvolset> B<-name> <I<volume set name>> [B<-temporary>]
+ [B<-localauth>] [B<-cell> <I<cell name>>] [B<-help>]
+
+B<backup addvols> B<-n> <I<volume set name>> [B<-t>] [B<-l>]
+ [B<-c> <I<cell name>>] [B<-h>]
+
+=head1 DESCRIPTION
+
+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 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 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 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.
+
+=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 B<-localauth>
+
+Constructs a server ticket using a key from the local
+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 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<backup(8)>.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command creates a volume set called C<sys>:
+
+ % backup addvolset sys
+
+=head1 PRIVILEGE REQUIRED
+
+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(8)>,
+L<backup_addvolentry(8)>,
+L<backup_delvolentry(8)>,
+L<backup_delvolset(8)>,
+L<backup_listvolsets(8)>,
+L<backup_volsetrestore(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+backup apropos - Displays each help entry containing a keyword string
+
+=head1 SYNOPSIS
+
+B<backup apropos> B<-topic> <I<help string>> [B<-help>]
+
+B<backup ap> B<-t> <I<help string>> [B<-h>]
+
+=head1 DESCRIPTION
+
+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 B<backup help> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=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 (C<" ">)
+or other delimiters.
+
+=item B<-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<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
+C<tape> in their names or short descriptions:
+
+ % backup apropos tape
+ labeltape: label a tape
+ readlabel: read the label on tape
+ scantape: dump information recovery from tape
+ status: get tape coordinator status
+
+=head1 PRIVILEGE REQUIRED
+
+None
+
+=head1 SEE ALSO
+
+L<backup(8)>,
+L<backup_help(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+backup dbverify - Checks the integrity of the Backup Database
+
+=head1 SYNOPSIS
+
+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>>] [B<-h>]
+
+=head1 DESCRIPTION
+
+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.
+
+=head1 OPTIONS
+
+=over 4
+
+=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.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+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 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<backup(8)>.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+The command displays one of the following two messages:
+
+=over 4
+
+=item Database OK
+
+The database is undamaged and can be used.
+
+=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.
+
+=back
+
+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.
+
+=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 F</usr/afs/logs/BackupLog> file on the
+indicated machine. You can use the B<bos getlog> command to display it.
+
+=back
+
+=head1 EXAMPLES
+
+The following command confirms that the Backup Database is undamaged:
+
+ % backup dbverify
+ Database OK
+
+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 C<db1.abc.com> checked its copy of
+the Database.
+
+ % backup dbverify -detail
+ Database OK
+ Orphan blocks 0
+ Database checker was db1.abc.com
+
+=head1 PRIVILEGE REQUIRED
+
+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(5)>,
+L<backup(8)>,
+L<backup_restoredb(8)>,
+L<backup_savedb(8)>,
+L<bos_getlog(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
+
+backup deldump - Deletes a dump level from the Backup Database
+
+=head1 SYNOPSIS
+
+B<backup deldump> B<-dump> <I<dump level name>> [B<-localauth>]
+ [B<-cell> <I<cell name>>] [B<-help>]
+
+B<backup deld> B<-d> <I<dump level name>> [B<-l>] [B<-c> <I<cell name>>]
+ [B<-h>]
+
+=head1 DESCRIPTION
+
+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 B<-dump> <I<dump level name>>
+
+Specifies the complete pathname of the dump level to delete.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+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 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<backup(8)>.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+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 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(8)>,
+L<backup_adddump(8)>,
+L<backup_listdumps(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+backup deletedump - Deletes one or more dump records from the Backup Database
+
+=head1 SYNOPSIS
+
+B<backup deletedump> [B<-dumpid> <I<dump id>>+] [B<-from> <I<date time>>+]
+ [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>]
+
+=head1 DESCRIPTION
+
+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
+dumps that are expired or otherwise no longer needed.
+
+=head1 CAUTIONS
+
+The only way to remove the dump record for an appended dump is to remove
+the record for its initial dump, and doing so removes the records for all
+of the initial dump's associated appended dumps.
+
+The 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.
+
+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
+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.
+
+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.
+
+=head1 OPTIONS
+
+=over 4
+
+=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).
+
+Provide either this argument or the B<-to> (and optionally B<-from>)
+argument.
+
+=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: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 B<-to> argument must be provided along with this one.
+
+=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 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
+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 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<backup(8)>.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+At the conclusion of processing, the output lists the dump IDs of all dump
+records deleted in the following format:
+
+ The following dumps were deleted:
+ dump ID 1
+ dump ID 2
+ etc.
+
+=head1 EXAMPLES
+
+The following command deletes the dump record with dump ID 653777462, and
+for any appended dumps associated with it:
+
+ % backup deletedump -dumpid 653777462
+ The following dumps were deleted:
+ 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:
+
+ % backup deletedump -from 01/01/1997 -to 12/31/1997
+ The following dumps were deleted:
+ 598324045
+ 598346873
+ ...
+ ...
+ 653777523
+ 653779648
+
+=head1 PRIVILEGE REQUIRED
+
+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(8)>,
+L<backup_dumpinfo(8)>,
+L<backup_scantape(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+backup delhost - Deletes a Tape Coordinator entry from the Backup Database
+
+=head1 SYNOPSIS
+
+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> B<-t> <I<tape machine name>> [B<-p> <I<TC port offset>>]
+ [B<-l>] [B<-c> <I<cell name>>] [B<-h>]
+
+=head1 DESCRIPTION
+
+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.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-tapehost> <I<tape machine name>>
+
+Specifies the hostname of the machine housing the Tape Coordinator to
+delete.
+
+=item B<-portoffset> <I<TC port offset>>
+
+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 B<-localauth>
+
+Constructs a server ticket using a key from the local
+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 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<backup(8)>.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command deletes the Backup Database entry for the Tape
+Coordinator with port offset 2 on the Tape Coordinator machine
+C<backup3.abc.com>:
+
+ % backup delhost -tapehost backup3.abc.com -portoffset 2
+
+=head1 PRIVILEGE REQUIRED
+
+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(8)>,
+L<backup_addhost(8)>,
+L<backup_listhosts(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+backup delvolentry - Deletes a volume entry from a volume set
+
+=head1 SYNOPSIS
+
+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> B<-n> <I<volume set name>> B<-e> <I<volume set index>>
+ [B<-l>] [B<-c> <I<cell name>>] [B<-h>]
+
+=head1 DESCRIPTION
+
+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.
+
+=head1 CAUTIONS
+
+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 B<-name> <I<volume set name>>
+
+Names the volume set from which to delete a volume 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.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+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 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<backup(8)>.
+
+=item B<-help>
+
+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 C<sys>:
+
+ % backup delvolentry -name sys -entry 4
+
+=head1 PRIVILEGE REQUIRED
+
+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(8)>,
+L<backup_addvolentry(8)>,
+L<backup_addvolset(8)>,
+L<backup_delvolset(8)>,
+L<backup_listvolsets(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+backup delvolset - Deletes one or more volume sets from the Backup Database
+
+=head1 SYNOPSIS
+
+B<backup delvolset> B<-name> <I<volume set name>>+ [B<-localauth>]
+ [B<-cell> <I<cell name>>] [B<-help>]
+
+B<backup delvols> B<-n> <I<volume set name>>+ [B<-l>]
+ [B<-c> <I<cell name>>] [B<-h>]
+
+=head1 DESCRIPTION
+
+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
+
+Deleting a temporary volume set is possible only within the interactive
+session in which it was created. Exiting the interactive session also
+destroys the temporary volume set automatically.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-name> <I<volume set name>>+
+
+Names each volume set to delete.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+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 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<backup(8)>.
+
+=item B<-help>
+
+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:
+
+ % backup delvolset user
+
+=head1 PRIVILEGE REQUIRED
+
+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(8)>,
+L<backup_addvolentry(8)>,
+L<backup_addvolset(8)>,
+L<backup_delvolentry(8)>,
+L<backup_listvolsets(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+backup diskrestore - Restores the entire contents of a partition
+
+=head1 SYNOPSIS
+
+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 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 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
+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).
+
+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>.
+
+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
+records the change of site in the VLDB.
+
+=over 4
+
+=item *
+
+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.
+
+=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.
+
+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 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.
+
+=head1 OPTIONS
+
+=over 4
+
+=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 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 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
+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
+and at all lower levels.
+
+Provide this argument unless the default value of 0 (zero) is appropriate
+for all dumps. If C<0> is just one of the values in the list, provide it
+explicitly in the appropriate order.
+
+=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.
+
+=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.
+
+=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
+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 B<-localauth>
+
+Constructs a server ticket using a key from the local
+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 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<backup(8)>.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+If a tape error occurs during the restore operation, the Tape Coordinator
+displays the following messages:
+
+ Restore operation on volume I<name> failed due to tape error
+ Do you want to continue (y/n)?
+
+where I<name> is the name of the volume that was being restored when the
+tape error occurred. Enter the value B<y> to continue the operation
+without restoring the indicated volume or the value 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 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 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 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 F</vicepm> partition of the
+machine C<fs4.abc.com>:
+
+ % backup diskrestore -server fs4.abc.com -partition /vicepm -n
+ Tapes needed:
+ user.sunday1.1
+ user.sunday1.2
+ user.monday1.1
+ user.tuesday1.1
+ user.wednesday1.1
+
+=head1 PRIVILEGE REQUIRED
+
+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<butc(5)>,
+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)>,
+L<vos_release(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
+
+backup dump - Creates a dump (dumps a volume set at a particular dump level)
+
+=head1 SYNOPSIS
+
+B<backup dump> [B<-volumeset> <I<volume set name>>]
+ [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>>] [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 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 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.
+
+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.
+
+=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
+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 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.
+
+=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.
+
+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
+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.
+
+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
+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
+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
+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 C<MOUNT> instruction in the
+F<CFG_I<device_name>> file or prompting the operator.
+
+=over 4
+
+=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.
+
+=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.
+
+=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 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.
+
+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
+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.
+
+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.
+
+=item *
+
+If the tape to be recycled does not have a permanent name and name
+checking is enabled, then the AFS tape name derived from the new initial
+dump's volume set name and dump level name must match the AFS tape name
+already recorded on the label.
+
+=item *
+
+The tape cannot already have data on it that belongs to the dump currently
+being performed, because that implies that the operator or automated tape
+device has not removed the previous tape from the drive, or has mistakenly
+reinserted it. The Tape Coordinator generates the following message and
+attempts to obtain another tape:
+
+ 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:
+
+ 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 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.
+
+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
+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.
+
+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
+mode, especially when including the B<-at> argument to schedule dump
+operations.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-volumeset> <I<volume set name>>
+
+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 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.
+
+=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.
+
+=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 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 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.
+
+=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.
+
+=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 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 B<-volumeset>, B<-dump>,
+B<-portoffset>, B<-append>, or B<-n> options.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+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 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<backup(8)>.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+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:
+
+ Preparing to dump the following volumes:
+
+The following message then indicates that the command interpreter has
+passed the dump request to the appropriate Tape Coordinator for
+processing:
+
+ Starting dump.
+
+If the issuer includes the B<-n> flag, the output is of the following
+form:
+
+ Starting dump of volume set '<volume set>' (dump set '<dump level>')
+ Total number of volumes : <number dumped>
+ Would have dumped the following volumes:
+ <list_of_volumes>
+
+where I<list_of_volumes> identifies each volume by name and volume ID
+number.
+
+If the Tape Coordinator is unable to access a volume, it prints an error
+message in its window and records the error in its log and error files.
+
+=head1 EXAMPLES
+
+The following command dumps the volumes in the volume set called 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:
+ user.jones.backup 387623900
+ user.pat.backup 486219245
+ user.smith.backup 597315841
+ . .
+ . .
+ Starting dump.
+
+The following command displays the list of volumes to be dumped when the
+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')
+ Total number of volumes: 24
+ Would have dumped the following volumes:
+ sun4x_56 124857238
+ sun4x_56.bin 124857241
+ . .
+ . .
+ sun4x_55 124857997
+ . .
+ . .
+
+The following command schedules a dump of the volumes in the volume set
+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 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<butc(5)>,
+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
+
+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
+
+backup dumpinfo - Displays a dump record from the Backup Database
+
+=head1 SYNOPSIS
+
+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>]
+
+=head1 DESCRIPTION
+
+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 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 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.
+
+=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.
+
+=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.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+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 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<backup(8)>.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+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 dumpid
+
+The dump ID number.
+
+=item parentid
+
+The dump ID number of the dump's parent dump. A value of C<0> (zero)
+identifies a full dump.
+
+=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.
+
+=item created
+
+The date and time at which the Backup System started the dump operation
+that created the dump.
+
+=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.
+
+=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.
+
+=item dump name
+
+The dump name in the form
+
+ <volume_set_name>.<dump_level_name> (<initial_dump_ID>)
+
+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 <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 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 id
+
+The dump ID number.
+
+=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.
+
+=item volumes
+
+The number of volumes for which the dump includes data.
+
+=item created
+
+The date and time at which the dump operation began.
+
+=back
+
+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: <XBSA_program>: Server: <hostname>
+
+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:
+
+=over 4
+
+=item name
+
+The tape's permanent name if it has one, or its AFS tape name otherwise,
+and its tape ID number in parentheses.
+
+=item nVolumes
+
+The number of volumes for which this tape includes dump data.
+
+=item created
+
+The date and time at which the Tape Coordinator began writing data to this
+tape.
+
+=back
+
+Following another blank line, the tape-specific information concludes with
+a table that includes a line for each volume dump on the tape. The
+information appears in columns with the following headings:
+
+=over 4
+
+=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
+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.
+
+=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 Nbytes
+
+The number of bytes of data in the dump of the volume.
+
+=item Volume
+
+The volume name, complete with C<.backup> or C<.readonly> extension if
+appropriate.
+
+=back
+
+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:
+
+=over 4
+
+=item Group id
+
+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 maxTapes
+
+The number of tapes that contain the dump set to which this dump belongs.
+
+=item Start Tape Seq
+
+The ordinal of the tape on which this dump begins in the set of tapes that
+contain the dump set.
+
+=back
+
+=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:
+
+=over 4
+
+=item expires
+
+The date and time when this tape can be recycled, because all dumps it
+contains have expired.
+
+=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 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.
+
+=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:
+
+=over 4
+
+=item id
+
+The volume ID.
+
+=item tape
+
+The name of the tape containing this volume data.
+
+=back
+
+=back
+
+=head1 EXAMPLES
+
+The following example displays information about the last five dumps:
+
+ % backup dumpinfo -ndumps 5
+ dumpid parentid lv created nt nvols dump name
+ 924424000 0 0 04/18/1999 04:26 1 22 usr.sun (924424000)
+ 924685000 924424000 1 04/21/1999 04:56 1 62 usr.wed (924424000)
+ 924773000 924424000 1 04/22/1999 05:23 1 46 usr.thu (924424000)
+ 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.
+
+ % backup dumpinfo -id 922097346
+ Dump: id 922097346, level 0, volumes 1, created Mon Mar 22 05:09:06 1999
+ Tape: name monday.user.backup (922097346)
+ nVolumes 1, created 03/22/1999 05:09
+ Pos Clone time Nbytes Volume
+ 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>):
+
+ % backup dumpinfo -id 922097346 -verbose
+ Dump
+ ----
+ id = 922097346
+ Initial id = 0
+ Appended id = 922099568
+ parent = 0
+ level = 0
+ flags = 0x0
+ volumeSet = user
+ dump path = /monday1
+ name = user.monday1
+ created = Mon Mar 22 05:09:06 1999
+ nVolumes = 1
+ id = 0
+ tapeServer =
+ format= user.monday1.%d
+ maxTapes = 1
+ Start Tape Seq = 1
+ name = pat
+ instance =
+ cell =
+ Tape
+ ----
+ tape name = monday.user.backup
+ AFS tape name = user.monday1.1
+ flags = 0x20
+ written = Mon Mar 22 05:09:06 1999
+ expires = NEVER
+ kBytes Tape Used = 121
+ nMBytes Data = 0
+ nBytes Data = 19092
+ nFiles = 0
+ nVolumes = 1
+ seq = 1
+ tapeid = 0
+ useCount = 1
+ dump = 922097346
+ Volume
+ ------
+ name = user.pat.backup
+ flags = 0x18
+ id = 536871640
+ server =
+ partition = 0
+ nFrags = 1
+ position = 2
+ clone = Mon Mar 22 04:43:06 1999
+ startByte = 0
+ nBytes = 19092
+ seq = 0
+ dump = 922097346
+ tape = user.monday1.1
+
+=head1 PRIVILEGE REQUIRED
+
+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<butc(5)>,
+L<backup(8)>,
+L<backup_deletedump(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+backup help - Displays help for backup commands
+
+=head1 SYNOPSIS
+
+B<backup help> [B<-topic> <I<help string>>+] [B<-help>]
+
+B<backup h> [B<-t> <I<help string>>+] [B<-h>]
+
+=head1 DESCRIPTION
+
+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.
+
+=head1 OPTIONS
+
+=over 4
+
+=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.
+
+=item B<-help>
+
+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:
+
+=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 example displays the online help entry for the B<backup
+dump> command:
+
+ % backup help dump
+ backup dump: start dump
+ Usage: backup dump -volumeset <volume set name> -dump <dump level name>
+ [-portoffset <TC port offset>] [-at <Date/time to start dump>+]
+ [-append] [-n] [-file <load file>] [-help]
+
+=head1 PRIVILEGE REQUIRED
+
+None
+
+=head1 SEE ALSO
+
+L<backup(8)>,
+L<backup_apropos(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+backup interactive - Enters interactive mode
+
+=head1 SYNOPSIS
+
+B<backup> [B<interactive>] [B<-localauth>] [B<-cell> <I<cell name>>]
+ [B<-help>]
+
+B<backup> [B<i>] [B<-l>] [B<-c> <I<cell name>>] [B<-h>]
+
+=head1 DESCRIPTION
+
+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:
+
+=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>).
+
+=item *
+
+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 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.
+
+=back
+
+To exit an interactive session, issue the B<backup quit> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+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 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<backup(8)>.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+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
+ dump: start dump
+ Usage: dump [-volumeset <volume set name>] [-dump <dump level name>]
+ [-portoffset <TC port offset>] [-at <Date/time to start dump>+]
+ [-append ] [-n ] [-file <load file>] [-help ]
+
+=head1 PRIVILEGE REQUIRED
+
+None. However, B<backup> commands that require privilege in regular mode
+still require it in interactive mode.
+
+=head1 SEE ALSO
+
+L<backup(8)>,
+L<backup_jobs(8)>,
+L<backup_kill(8)>,
+L<backup_quit(8)>,
+L<butc(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+backup jobs - Lists pending and running operations in interactive mode
+
+=head1 SYNOPSIS
+
+B<jobs> [B<-help>]
+
+B<j> [B<-h>]
+
+=head1 DESCRIPTION
+
+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.
+
+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
+operation, use the B<backup status> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-help>
+
+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:
+
+ <date> <time>: TOKEN EXPIRATION
+
+If the execution date and time specified for a scheduled dump operation is
+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:
+
+ : TOKEN NEVER EXPIRES
+
+The entry for a scheduled dump operation has the following format:
+
+ Job <job_ID>: <timestamp>: dump <volume_set> <dump_level>
+
+where
+
+=over 4
+
+=item <job_ID>
+
+Is a job identification number assigned by the Backup System.
+
+=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)
+
+=item <volume_set>
+
+Indicates the volume set to dump.
+
+=item <dump_level>
+
+Indicates the dump level at which to perform the dump operation.
+
+=back
+
+The line for a pending or running operation of any other type has the
+following format:
+
+ Job <job_ID>: <operation> <status>
+
+where
+
+=over 4
+
+=item <job_ID>
+
+Is a job identification number assigned by the Backup System.
+
+=item <operation>
+
+Identifies the operation the Tape Coordinator is performing, which is
+initiated by the indicated command:
+
+=over 4
+
+=item Dump (I<dump name>)
+
+Initiated by the backup dump command. The I<dump name> has the following
+format:
+
+ <volume_set_name>.<dump_level_name>
+
+=item Restore
+
+Initiated by the B<backup diskrestore>, B<backup volrestore>, or B<backup
+volsetrestore> command.
+
+=item Labeltape (I<tape_label>)
+
+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 Scantape
+
+Initiated by the B<backup scantape> command.
+
+=item SaveDb
+
+Initiated by the B<backup savedb> command.
+
+=item RestoreDb
+
+Initiated by the B<backup restoredb> command.
+
+=back
+
+=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.
+
+=over 4
+
+=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.
+
+=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 [abort requested]
+
+The B<backup kill> command was issued, but the termination signal has yet
+to reach the Tape Coordinator.
+
+=item [abort sent]
+
+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 [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.
+
+=item [done]
+
+The Tape Coordinator has finished the operation.
+
+=item [drive wait]
+
+The operation is waiting for the specified tape drive to become free.
+
+=item [operator wait]
+
+The Tape Coordinator is waiting for the backup operator to insert a tape
+in the drive.
+
+=back
+
+=back
+
+=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
+10:45 am:
+
+ backup> jobs
+ Job 1: Restore, 1306 Kbytes, restore.volume
+ Job 2: Dump (user.sunday1), 34 Kbytes, volume user.pat.backup
+ Job 3: Restore, 2498 Kbytes, restore.volume
+ 04/22/1999 10:45: TOKEN EXPIRATION
+
+=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.
+
+=head1 SEE ALSO
+
+L<backup(8)>,
+L<backup_interactive(8)>,
+L<backup_kill(8)>,
+L<backup_quit(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+backup kill - Terminates a pending or running operation
+
+=head1 SYNOPSIS
+
+B<kill> B<-id> <I<job ID or dump set name>> [B<-help>]
+
+B<k -i> <I<job ID or dump set name>> [B<-h>]
+
+=head1 DESCRIPTION
+
+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.
+
+The effect of terminating an operation depends on the type and current
+state of the operation:
+
+=over 4
+
+=item *
+
+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.
+
+=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.
+
+=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.
+
+=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.
+
+=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
+L<CAUTIONS>.
+
+=back
+
+=head1 CAUTIONS
+
+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 B<-id> <I<job ID or dump set name>>
+
+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.
+
+=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.
+
+=back
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command terminates the operation with job ID 5:
+
+ backup> kill 5
+
+The following command terminates the dump operation called
+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
+interactive session during which the operation was initiated, the required
+privilege is essentially guaranteed.
+
+=head1 SEE ALSO
+
+L<backup(8)>,
+L<backup_interactive(8)>,
+L<backup_jobs(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+backup labeltape - Creates the magnetic label on a tape
+
+=head1 SYNOPSIS
+
+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> [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 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 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
+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 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 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:
+
+ <volume_set_name>.<dump_level_name>.<tape_index>
+
+for the tape to be acceptable for use in a future backup dump
+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:
+
+ Ubik_db_dump.<tape_index>
+
+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 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 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 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.
+
+=item B<-portoffset> <I<TC port offset>>
+
+Specifies the port offset number of the Tape Coordinator handling the tape
+for this operation.
+
+=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
+to mark them as literal in commands issued at the shell prompt.
+
+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 B<-localauth>
+
+Constructs a server ticket using a key from the local
+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 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<backup(8)>.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+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.
+
+ % backup labeltape -size 2g -portoffset 4
+ % backup labeltape -size 2048M -portoffset 4
+ % backup labeltape -size 2097152 -portoffset 4
+
+=head1 PRIVILEGE REQUIRED
+
+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<butc(5)>,
+L<backup(8)>,
+L<backup_readlabel(8)>,
+L<butc(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
+
+backup listdumps - Displays the dump hierarchy from the Backup Database
+
+=head1 SYNOPSIS
+
+B<backup listdumps> [B<-localauth>] [B<-cell> <I<cell name>>] [B<-help>]
+
+B<backup listd> [B<-l>] [B<-c> <I<cell name>>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<backup listdumps> command displays the dump hierarchy from the
+Backup Database.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+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 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<backup(8)>.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+The output displays the complete dump hierarchy and indicates the
+relationship between full and incremental dump levels. Full dump levels
+appear at the left margin. The hierarchy can include more than one full
+dump level; each one defines a subhierarchy of dump levels that can be
+used for dumping different volume sets.
+
+Incremental dump levels appear below and indented to the right of their
+parent dump levels, which can be either full or incremental. Since
+multiple incremental dump levels can share the same parent, an incremental
+dump level is not always directly below its parent; the amount of
+indentation indicates the parent/child relationship.
+
+If a dump level has an associated expiration date, it appears along with
+the level name. Absolute expiration dates appear in the format
+
+ <dump_level> expires at <day month date time year>
+
+and relative expiration dates in the format
+
+ <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.
+
+ % backup listdumps
+ /week1 expires in 27d
+ /tuesday expires in 13d
+ /thursday expires in 13d
+ /sunday expires in 13d
+ /tuesday expires in 13d
+ /thursday expires in 13d
+ /week3 expires in 27d
+ /tuesday expires in 13d
+ /thursday expires in 13d
+ /sunday expires in 13d
+ /tuesday expires in 13d
+ /thursday expires in 13d
+ /sunday1 expires in 27d
+ /monday1 expires in 13d
+ /tuesday1 expires in 13d
+ /wednesday1 expires in 13d
+ /thursday1 expires in 13d
+ /friday1 expires in 13d
+ /sunday2 expires in 27d
+ /monday2 expires in 13d
+ /tuesday2 expires in 13d
+ /wednesday2 expires in 13d
+ /thursday2 expires in 13d
+ /friday2 expires in 13d
+ /sunday3 expires in 27d
+ /monday1 expires in 13d
+ /tuesday1 expires in 13d
+ /wednesday1 expires in 13d
+ /thursday1 expires in 13d
+ /friday1 expires in 13d
+ /sunday4 expires in 27d
+ /monday2 expires in 13d
+ /tuesday2 expires in 13d
+ /wednesday2 expires in 13d
+ /thursday2 expires in 13d
+ /friday2 expires in 13d
+
+=head1 PRIVILEGE REQUIRED
+
+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(8)>,
+L<backup_adddump(8)>,
+L<backup_deldump(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+backup listhosts - Lists Tape Coordinators registered in the Backup Database
+
+=head1 SYNOPSIS
+
+B<backup listhosts> [B<-localauth>] [B<-cell> <I<cell name>>] [B<-help>]
+
+B<backup listh> [B<-l>] [B<-c> <I<cell name>>] [B<-h>]
+
+=head1 DESCRIPTION
+
+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.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+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 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<backup(8)>.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+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.
+
+=item *
+
+The Tape Coordinator's port offset number.
+
+=back
+
+The Tape Coordinators appear in the order in which they were added to the
+Backup Database.
+
+=head1 EXAMPLES
+
+The following example shows the result of the command in the ABC
+Corporation cell:
+
+ % backup listhosts
+ Tape hosts:
+ Host backup1.abc.com, port offset 0
+ Host backup1.abc.com, port offset 1
+ Host backup3.abc.com, port offset 4
+ Host backup2.abc.com, port offset 3
+
+=head1 PRIVILEGE REQUIRED
+
+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(8)>,
+L<backup_addhost(8)>,
+L<backup_delhost(8)>,
+L<backup_status(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+backup listvolsets - Lists volume set entries from the Backup Database
+
+=head1 SYNOPSIS
+
+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>>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<backup listvolsets> command displays the Backup Database records for
+either
+
+=over 4
+
+=item *
+
+All volume sets and their volume entries, if the B<-name> argument is
+omitted.
+
+=item *
+
+The volume set specified by the B<-name> argument, along with its volume
+entries.
+
+=back
+
+=head1 OPTIONS
+
+=over 4
+
+=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.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+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 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<backup(8)>.
+
+=item B<-help>
+
+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.
+
+=head1 EXAMPLES
+
+The following example shows the volume entries in the three volume sets
+currently defined in the Backup Database:
+
+ % backup listvolsets
+ Volume set user:
+ Entry 1: server .*, partition .*, volumes: user.*\.backup
+ Volume set sun
+ Entry 1: server .*, partition .*, volumes: sun4x_55\..*
+ Entry 2: server .*, partition .*, volumes: sun4x_56\..*
+ Volume set rs
+ Entry 1: server .*, partition .*, volumes: rs_aix42\..*
+
+=head1 PRIVILEGE REQUIRED
+
+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(8)>,
+L<backup_addvolentry(8)>,
+L<backup_addvolset(8)>,
+L<backup_delvolentry(8)>,
+L<backup_delvolset(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+backup quit - Leaves interactive mode
+
+=head1 SYNOPSIS
+
+B<quit> [B<-help>]
+
+B<q> [B<-h>]
+
+=head1 DESCRIPTION
+
+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.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command exits interactive mode:
+
+ backup> quit
+ %
+
+=head1 PRIVILEGE REQUIRED
+
+None
+
+=head1 SEE ALSO
+
+L<backup(8)>,
+L<backup_interactive(8)>,
+L<backup_jobs(8)>,
+L<backup_kill(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+backup readlabel - Reads and displays a tape's label
+
+=head1 SYNOPSIS
+
+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>>]
+ [B<-h>]
+
+=head1 DESCRIPTION
+
+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 B<-portoffset> <I<TC port offset>>
+
+Specifies the port offset number of the Tape Coordinator handling the
+tapes for this operation.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+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 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<backup(8)>.
+
+=item B<-help>
+
+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.
+
+If the tape is unlabeled or if the specified tape device is empty, the
+output reads
+
+ Failed to read tape label.
+
+Otherwise, the output in the shell window has the following format:
+
+ Tape read was labelled: <tape name> (<dump id>)
+ size: <size> Kbytes
+
+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 label> header at the top, and the following string at the bottom:
+
+ -- End of tape label --
+
+In between are lines reporting the following information:
+
+=over 4
+
+=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.
+
+=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.
+
+=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.
+
+=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.
+
+=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.
+
+=back
+
+=item creationTime
+
+The date and time at which the Backup System started performing the dump
+operation that created the initial dump.
+
+=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.
+
+=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
+F</usr/afs/backup/tapeconfig> file on the Tape Coordinator machine, not
+from a measurement of the tape.
+
+=item dump path
+
+The dump level of the initial dump in the dump set.
+
+=item dump id
+
+The dump ID number of the initial dump in the dump set, as recorded in the
+Backup Database.
+
+=item useCount
+
+The number of times a dump has been written to the tape, or it has been
+relabeled.
+
+=back
+
+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
+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)
+ size: 2097152 Kbytes
+
+The output in the Tape Coordinator window reads:
+
+ Tape label
+ ----------
+ tape name = oct.guest.dump
+ AFS tape name = guests.monthly.3
+ creationTime = Thu Oct 1 00:10:00 1998
+ cell = abc.com
+ size = 2097152 Kbytes
+ dump path = /monthly
+ dump id = 907215000
+ useCount = 5
+ ---- End of tape label ----
+
+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)
+ size: 2097152 Kbytes
+
+The output in the Tape Coordinator window reads:
+
+ Tape label
+ ----------
+ tape name = <NULL>
+ AFS tape name = guests.monthly.2
+ creationTime = Sun Nov 1 00:58:20 1998
+ cell = abc.com
+ size = 2097152 Kbytes
+ dump path = /monthly
+ dump id = 909899900
+ useCount = 1
+ ---- End of tape label ----
+
+=head1 PRIVILEGE REQUIRED
+
+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<butc(5)>,
+L<backup(8)>,
+L<backup_labeltape(8)>,
+L<butc(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+backup restoredb - Restores a saved copy of the Backup Database
+
+=head1 SYNOPSIS
+
+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>>]
+ [B<-h>]
+
+=head1 DESCRIPTION
+
+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 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.
+
+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
+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 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 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.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-portoffset> <I<TC port offset>>
+
+Specifies the port offset number of the Tape Coordinator handling the
+tapes for this operation.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+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 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<backup(8)>.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following example shows the Backup Database being restored from the
+Tape Coordinator with port offset 0:
+
+ % backup restoredb
+
+=head1 PRIVILEGE REQUIRED
+
+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<butc(5)>,
+L<backup(8)>,
+L<backup_dbverify(8)>,
+L<backup_savedb(8)>,
+L<butc(8)>
+
+I<IBM AFS Administration Guide>
+
+=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
+
+backup savedb - Creates a saved copy of the Backup Database
+
+=head1 SYNOPSIS
+
+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>>] [B<-a> <I<date time>>+]
+ [B<-l>] [B<-c> <I<cell name>>] [B<-h>]
+
+=head1 DESCRIPTION
+
+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 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 B<-portoffset> <I<TC port offset>>
+
+Specifies the port offset number of the Tape Coordinator handling the
+tapes for this operation.
+
+=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.
+
+Provide one of two values:
+
+=over 4
+
+=item *
+
+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 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 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.
+
+=back
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+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 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<backup(8)>.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following example writes a copy of the Backup Database to the tape
+device controlled by the Tape Coordinator with port offset 1:
+
+ % backup savedb -portoffset 1
+
+=head1 PRIVILEGE REQUIRED
+
+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<butc(5)>,
+L<backup(8)>,
+L<backup_dbverify(8)>,
+L<backup_restoredb(8)>,
+L<butc(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+backup scantape - Extracts dump information from a tape
+
+=head1 SYNOPSIS
+
+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>>] [B<-h>]
+
+=head1 DESCRIPTION
+
+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 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 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
+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
+Database.
+
+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 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.
+
+=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
+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.
+
+=back
+
+=head1 OPTIONS
+
+=over 4
+
+=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).
+
+=item B<-portoffset> <I<TC port offset>>
+
+Specifies the port offset number of the Tape Coordinator handling the
+tapes for this operation.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+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 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<backup(8)>.
+
+=item B<-help>
+
+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.
+
+A dump label contains the following fields, which are the same as in the
+output from the B<backup readlabel> command:
+
+=over 4
+
+=item tape name
+
+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 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.
+
+=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.
+
+=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.
+
+=back
+
+=item creationTime
+
+The date and time at which the Backup System started performing the dump
+operation that created the initial dump.
+
+=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.
+
+=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
+F</usr/afs/backup/tapeconfig> file on the Tape Coordinator machine, not
+from a measurement of the tape.
+
+=item dump path
+
+The dump level of the initial dump in the dump set.
+
+=item dump id
+
+The dump ID number of the initial dump in the dump set, as recorded in the
+Backup Database.
+
+=item useCount
+
+The number of times a dump has been written to the tape, or it has been
+relabeled.
+
+=back
+
+The volume header contains the following fields:
+
+=over 4
+
+=item volume name
+
+The volume name, complete with a C<.backup> or C<.readonly> extension, if
+appropriate.
+
+=item volume ID
+
+The volume's volume ID.
+
+=item dumpSetName
+
+The dump to which the volume belongs. The dump name is of the form
+I<volume_set_name>.I<dump_level_name> and matches the name displayed in
+the dump label.
+
+=item dumpID
+
+The dump ID of the dump named in the C<dumpSetName> field.
+
+=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.
+
+=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>.
+
+=item endTime
+
+Is always C<0>; it is reserved for internal use.
+
+=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
+dump named in the C<dumpSetName> field.
+
+=back
+
+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 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 EXAMPLES
+
+The following example shows the output for the first two volumes on a tape
+in the device with port offset 0:
+
+ % backup scantape
+ Dump label
+ ----------
+ tape name = monthly_guest
+ AFS tape name = guests.monthly.3
+ creationTime = Mon Feb 1 04:06:40 1999
+ cell = abc.com
+ size = 2150000 Kbytes
+ dump path = /monthly
+ dump id = 917860000
+ useCount = 44
+ -- End of dump label --
+ -- volume --
+ volume name: user.guest10.backup
+ volume ID 1937573829
+ dumpSetName: guests.monthly
+ dumpID 917860000
+ level 0
+ parentID 0
+ endTime 0
+ clonedate Mon Feb 1 03:03:23 1999
+ -- volume --
+ volume name: user.guest11.backup
+ volume ID 1938519386
+ dumpSetName: guests.monthly
+ dumpID 917860000
+ level 0
+ parentID 0
+ endTime 0
+ clonedate Mon Feb 1 03:05:15 1999
+
+=head1 PRIVILEGE REQUIRED
+
+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<butc(5)>,
+L<backup(8)>,
+L<backup_dump(8)>,
+L<backup_dumpinfo(8)>,
+L<butc(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
+
+backup setexp - Sets the expiration date for existing dump levels.
+
+=head1 SYNOPSIS
+
+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> B<-d> <I<dump level name>>+ [B<-e> <I<expiration date>>+]
+ [B<-l>] [B<-c> <I<cell name>>] [B<-h>]
+
+=head1 DESCRIPTION
+
+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 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.)
+
+Define either an absolute or relative expiration date:
+
+=over 4
+
+=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.
+
+=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.
+
+=back
+
+If the command is used to change an existing expiration date associated
+with a dump level, the new date applies only to dumps created after the
+change. Existing dumps retain the expiration date assigned at the time
+they were created.
+
+=head1 OPTIONS
+
+=over 4
+
+=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 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:
+
+ [at] {NEVER | <mm>/<dd>/<yyyy> [<hh>:<MM>] }
+
+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 <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:
+
+ [in] [<years>y] [<months>m] [<days>d]
+
+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 B<-localauth>
+
+Constructs a server ticket using a key from the local
+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 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<backup(8)>.
+
+=item B<-help>
+
+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 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 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 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(8)>,
+L<backup_adddump(8)>,
+L<backup_deldump(8)>,
+L<backup_listdumps(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+backup status - Reports a Tape Coordinator's status
+
+=head1 SYNOPSIS
+
+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>>]
+ [B<-h>]
+
+=head1 DESCRIPTION
+
+The B<backup status> command displays which operation, if any, the
+indicated Tape Coordinator is currently executing.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-portoffset> <I<TC port offset>>
+
+Specifies the port offset number of the Tape Coordinator for which to
+report the status.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+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 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<backup(8)>.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+The following message indicates that the Tape Coordinator is not currently
+performing an operation:
+
+ Tape coordinator is idle
+
+Otherwise, the output includes a message of the following format for each
+running or pending operation:
+
+ Task <task_ID>: <operation>: <status>
+
+where
+
+=over 4
+
+=item <task_ID>
+
+Is a task identification number assigned by the Tape Coordinator. It
+begins with the Tape Coordinator's port offset number.
+
+=item <operation>
+
+Identifies the operation the Tape Coordinator is performing, which is
+initiated by the indicated command:
+
+=over 4
+
+=item Dump
+
+The B<backup dump> command.
+
+=item Restore
+
+The B<backup diskrestore>, B<backup volrestore>, or B<backup
+volsetrestore> commands.
+
+=item Labeltape
+
+The B<backup labeltape> command.
+
+=item Scantape
+
+The B<backup scantape> command.
+
+=item SaveDb
+
+The B<backup savedb> command.
+
+=item RestoreDb
+
+The B<backup restoredb> command.
+
+=back
+
+=item <status>
+
+Indicates the job's current status in one of the following messages.
+
+=over 4
+
+=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.
+
+=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 [abort requested]
+
+The B<backup kill> command was issued, but the termination signal has yet
+to reach the Tape Coordinator.
+
+=item [abort sent]
+
+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 [butc contact lost]
+
+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 [done]
+
+The Tape Coordinator has finished the operation.
+
+=item [drive wait]
+
+The operation is waiting for the specified tape drive to become free.
+
+=item [operator wait]
+
+The Tape Coordinator is waiting for the backup operator to insert a tape
+in the drive.
+
+=back
+
+=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:
+
+ <XBSA_program> Tape coordinator
+
+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 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 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(8)>,
+L<butc(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+backup volinfo - Displays a volume's dump history from the Backup Database
+
+=head1 SYNOPSIS
+
+B<backup volinfo> B<-volume> <I<volume name>> [B<-localauth>]
+ [B<-cell> <I<cell name>>] [B<-help>]
+
+B<backup voli> B<-v> <I<volume name>> [B<-l>] [B<-c> <I<cell name>>] [B<-h>]
+
+=head1 DESCRIPTION
+
+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 B<-volume> <I<volume name>>
+
+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 B<-localauth>
+
+Constructs a server ticket using a key from the local
+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 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<backup(8)>.
+
+=item B<-help>
+
+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:
+
+=over 4
+
+=item dumpID
+
+The dump ID of the dump that includes the volume.
+
+=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.
+
+=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>.
+
+=item creation date
+
+The date and time at which the Backup System started the dump operation
+that created the dump.
+
+=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 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
+C<user.smith.backup>:
+
+ % backup volinfo -volume user.smith.backup
+ DumpID lvl parentID creation date clone date tape name
+ 924600000 1 924427600 04/20/1999 05:20 04/20/1999 05:01 user_incr_2 (924514392)
+ 924514392 1 924427600 04/19/1999 05:33 04/19/1999 05:08 user_incr_2
+ 924427600 0 0 04/18/1999 05:26 04/18/1999 04:58 user_full_6
+ . . . . . . . .
+ . . . . . . . .
+
+=head1 PRIVILEGE REQUIRED
+
+None
+
+=head1 SEE ALSO
+
+L<backup(8)>,
+L<backup_dumpinfo(8)>,
+L<backup_volrestore(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+backup volrestore - Restores one or more volumes
+
+=head1 SYNOPSIS
+
+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 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:
+
+=over 4
+
+=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.
+
+=item *
+
+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 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.
+
+=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.
+
+=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.
+
+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 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.
+
+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
+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
+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 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 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
+changes the site information in the volume's VLDB entry.
+
+=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.
+
+=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
+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 C<.backup> or C<.readonly> extension, the Backup System
+restores dumps of the corresponding volume version only.
+
+=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 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 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
+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
+and all dumps at lower levels.
+
+Provide this argument unless the default value of 0 (zero) is appropriate
+for all dumps. If C<0> is just one of the values in the list, provide it
+explicitly in the appropriate order.
+
+=item B<-n>
+
+Displays the list of tapes that contain the dumps required by the restore
+operation, without actually performing the operation.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+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 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<backup(8)>.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+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 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 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 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 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<butc(5)>,
+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 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
+
+backup volsetrestore - Restores all volumes in a volume set
+
+=head1 SYNOPSIS
+
+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>>] [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 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
+to use the B<backup diskrestore> command.
+
+Indicate the volumes to restore by providing either the B<-name> argument
+or the B<-file> argument:
+
+=over 4
+
+=item *
+
+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.
+
+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.
+
+=item *
+
+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
+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
+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
+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 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 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 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 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.
+
+=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.
+
+Each volume's entry must appear on its own (unbroken) line in the file,
+and have the following format:
+
+ <machine> <partition> <volume> [<comments> ...]
+
+where
+
+=over 4
+
+=item <machine>
+
+Names the file server machine to which to restore the volume.
+
+=item <partition>
+
+Names the partition to which to restore the 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 C<.backup> or
+C<.readonly> extension, the Backup System restores dumps of that volume
+version only.
+
+=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.
+
+=back
+
+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 B<-extension> <I<new volume name extension>>
+
+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 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
+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
+and all dumps at lower levels.
+
+Provide this argument unless the default value of 0 (zero) is appropriate
+for all dumps. If C<0> is just one of the values in the list, provide it
+explicitly in the appropriate order.
+
+=item B<-n>
+
+Displays a list of the volumes to be restored if the flag were not
+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 B<-localauth>
+
+Constructs a server ticket using a key from the local
+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 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<backup(8)>.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+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.
+
+=item *
+
+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 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):
+
+ <machine> <partition> <volume_dumped> # as <volume_restored>; \
+ <tape_name> (<tape_ID>); pos <position_number>; <date>
+
+where
+
+=over 4
+
+=item <machine>
+
+Names the file server machine that currently houses the volume, as listed
+in the VLDB.
+
+=item <partition>
+
+Names the partition that currently houses the volume, as listed in the
+VLDB.
+
+=item <volume_dumped>
+
+Specifies the version (read/write or backup) of the volume that was
+dumped, as listed in the Backup Database.
+
+=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>).
+
+=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.
+
+=item <tape_ID>
+
+The tape ID of the tape containing the dump of the volume, from the Backup
+Database.
+
+=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.
+
+=item <date>
+
+The date and time when the volume was dumped.
+
+=back
+
+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.
+
+=head1 EXAMPLES
+
+The following command restores all volumes included in entries in the
+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: task ID of restore operation: 112
+ backup: Finished doing restore
+
+The following command restores all volumes that have entries in the file
+named F</tmp/restore>:
+
+ % backup volsetrestore -file /tmp/restore
+ Starting restore
+ backup: task ID of restore operation: 113
+ backup: Finished doing restore
+
+The F</tmp/restore> file has the following contents:
+
+ fs1.abc.com b user.pat
+ fs1.abc.com b user.terry
+ fs1.abc.com b user.smith
+ fs2.abc.com c user.jones
+ . . .
+ . . .
+
+=head1 PRIVILEGE REQUIRED
+
+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<butc(5)>,
+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
+
+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
+
+bosserver - Initializes the BOS Server
+
+=head1 SYNOPSIS
+
+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 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:
+
+=over 4
+
+=item *
+
+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.
+
+=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.
+
+=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.
+
+=back
+
+The BOS Server logs a default set of important events in the file
+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 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.
+
+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).
+
+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 B<-noauth>
+
+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 B<-log>
+
+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 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.
+
+=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,
+GetStatus, and so on) sent or received, aggregated over all connections to
+other machines. To display or otherwise access the records, use the Rx
+Monitoring API.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command initializes the BOS Server and logs the names of
+users who issue privileged B<bos> commands.
+
+ % bosserver -log &
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer most be logged onto a file server machine as the local
+superuser C<root>.
+
+=head1 SEE ALSO
+
+L<BosConfig(5)>,
+L<BosLog(5)>,
+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)>
+
+=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
+
+buserver - Initializes the Backup Server
+
+=head1 SYNOPSIS
+
+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 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
+F</usr/afs/bin> directory on a file server machine.
+
+The B<buserver> 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>.
+
+As it initializes, the Backup Server process creates the two files that
+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
+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.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-database> <I<database directory>>
+
+Specifies the pathname of an alternate directory for the Backup Database
+files, ending in a final slash (C</>). If this argument is not provided,
+the default is the F</usr/afs/db> directory.
+
+=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 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 B<-resetdb>
+
+Removes all of the information in the Backup Database files in the
+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 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 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 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.
+
+=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 F</usr/afs/etc/CellServDB> file.
+
+=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.
+
+=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,
+GetStatus, and so on) sent or received, aggregated over all connections to
+other machines. To display or otherwise access the records, use the Rx
+Monitoring API.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+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 \
+ -type simple -cmd /usr/afs/bin/buserver
+
+=head1 PRIVILEGE REQUIRED
+
+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(5)>,
+L<BosConfig(5)>,
+L<CellServDB(5)>,
+L<bdb.DB0(5)>,
+L<backup(8)>,
+L<bos_create(1)>,
+L<bos_getlog(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
+
+butc - Initializes the Tape Coordinator process
+
+=head1 SYNOPSIS
+
+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> (0 | 1 | 2)]
+ [B<-c> <I<cell name>>] [B<-n>] [B<-l>] [B<-h>]
+
+=head1 DESCRIPTION
+
+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
+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 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 F<TE_I<device_name>> file records problems that the Tape Coordinator
+encounters as it executes backup operations.
+
+=item *
+
+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 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
+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 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:
+
+=over 4
+
+=item *
+
+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 F<tapeconfig> file. Create the
+Backup Database entry by using the B<backup addhost> command.
+
+=item *
+
+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.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-port> <I<port offset>>
+
+Specifies the port offset number of the Tape Coordinator to initialize.
+
+=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:
+
+=over 4
+
+=item *
+
+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 *
+
+C<1> to display the names of the volumes being dumped or restored as well
+as the information displayed at level C<0>.
+
+=item *
+
+C<2> to display all messages also being written to the
+F<TL_I<device_name>> log file.
+
+=back
+
+=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 F</usr/vice/etc/ThisCell> file. Do not combine this
+flag with the B<-localauth> argument.
+
+=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.
+
+=item B<-localauth>
+
+Constructs a server ticket using the server encryption key with the
+highest key version number in the local F</usr/afs/etc/KeyFile>. 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 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 B<-help>
+
+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 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 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<KeyFile(5)>,
+L<ThisCell(5)>,
+L<UserList(5)>,
+L<butc(5)>,
+L<butc_logs(5)>,
+L<tapeconfig(5)>,
+L<backup_addhost(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+fileserver - Initializes the File Server component of the fs process
+
+=head1 SYNOPSIS
+
+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 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 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 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 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 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.
+
+=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.
+
+=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.
+
+=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.
+
+=item *
+
+The maximum volume cache size, which determines how many volumes the File
+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.
+
+=item *
+
+The maximum number of Rx packets the File Server uses; corresponds to the
+B<-rxpck> argument. Each packet consumes 1544 bytes of memory.
+
+=back
+
+The default values are:
+
+ 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
+
+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:
+
+=over 4
+
+=item *
+
+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 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 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 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.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-d> <I<debug level>>
+
+Sets the detail level for the debugging trace written to the
+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 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).
+
+The maximum number of threads can differ in each release of AFS. Consult
+the I<IBM AFS Release Notes> for the current release.
+
+=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
+C<0> prevents the volume from ever exceeding its quota. Do not combine
+this argument with the B<-pctspare> argument.
+
+=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 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<-b> <I<buffers>>
+
+Sets the number of directory buffers. Provide a positive integer.
+
+=item B<-l> <I<large vnodes>>
+
+Sets the number of large vnodes available in memory for caching directory
+elements. Provide a positive integer.
+
+=item B<-s> <I<small nodes>>
+
+Sets the number of small vnodes available in memory for caching file
+elements. Provide a positive integer.
+
+=item B<-vc> <I<volume cachesize>>
+
+Sets the number of volumes the File Server can cache in memory. Provide a
+positive integer.
+
+=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.
+
+=item B<-cb> <I<number of callbacks>>
+
+Sets the number of callbacks the File Server can track. Provide a positive
+integer.
+
+=item B<-banner>
+
+Prints the following banner to F</dev/console> about every 10 minutes.
+
+ File Server is running at I<time>.
+
+=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.
+
+=item B<-implicit> <I<admin mode bits>>
+
+Defines the set of permissions granted by default to the
+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 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
+machines). The File Server must update this information to enable users
+from machines recently added to protection groups to access data for which
+those machines now have the necessary ACL permissions.
+
+=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
+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 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
+integer.
+
+=item B<-rxdbg>
+
+Writes a trace of the File Server's operations on Rx packets to the file
+F</usr/afs/logs/rx_dbg>.
+
+=item F<-rxdbge>
+
+Writes a trace of the File Server's operations on Rx events (such as
+retransmissions) to the file F</usr/afs/logs/rx_dbg>.
+
+=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
+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 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.
+
+=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.
+
+=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.
+
+=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 C<24>.
+
+=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 F</usr/afs/etc/ThisCell> file.
+
+=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.
+
+=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.
+
+=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,
+GetStatus, and so on) sent or received, aggregated over all connections to
+other machines. To display or otherwise access the records, use the Rx
+Monitoring API.
+
+=item B<-help>
+
+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 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 \
+ -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 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(5)>,
+L<FileLog(5)>,
+L<bos_create(1)>,
+L<bos_getlog(1)>,
+L<fs_setacl(1)>,
+L<salvager(8)>,
+L<volserver(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+fms - Determine a tape's capacity and a tape device's filemark size
+
+=head1 SYNOPSIS
+
+B<fms> B<-tape> <I<tape special file>> [B<-help>]
+
+B<fms> B<-t> <I<tape special file>> [B<-h>]
+
+=head1 DESCRIPTION
+
+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
+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.
+
+=head1 CAUTIONS
+
+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.
+
+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.
+
+=head1 OPTIONS
+
+=over 4
+
+=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 F</dev>;
+an example is F</dev/sd0a>.
+
+=item B<-help>
+
+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
+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:
+
+=over 4
+
+=item *
+
+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> 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.
+
+ Can't open tape drive I<device>
+
+The following message indicates that the command interpreter cannot create
+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
+F</dev/rmt1h>:
+
+ % fms /dev/rmt1h
+ wrote block: 130408
+ Finished data capacity test - rewinding
+ wrote 1109 blocks, 1109 file marks
+ Finished file mark test
+ Tape capacity is 2136604672 bytes
+ File marks are 1910205 bytes
+
+The following appears in the F<fms.log> file:
+
+ fms test started
+ wrote 9230 blocks
+ Finished file mark test
+ Tape capacity is 151224320 bytes
+ File marks are 2375680 bytes
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be able to insert and write to files in the currently
+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(5)>,
+L<tapeconfig(5)>
+
+=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
+
+fstrace - Introduction to the fstrace command suite
+
+=head1 DESCRIPTION
+
+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>, B<fstrace setlog>.
+
+=item *
+
+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: B<fstrace dump>.
+
+=item *
+
+Commands to obtain help: B<fstrace apropos> and B<fstrace help>.
+
+=back
+
+=head1 OPTIONS
+
+All B<fstrace> commands accept the following optional flag. It is listed
+in the command descriptions and described in detail here:
+
+=over 4
+
+=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.
+
+=back
+
+=head1 PRIVILEGE REQUIRED
+
+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(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
+
+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
+
+fstrace apropos - Displays each help entry containing a keyword string
+
+=head1 SYNOPSIS
+
+B<fstrace apropos> B<-topic> <I<help string>> [B<-help>]
+
+B<fstrace ap> B<-t> <I<help string>> [B<-h>]
+
+=head1 DESCRIPTION
+
+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 B<fstrace help> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=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 (C<"">)
+or other delimiters.
+
+=item B<-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<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 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
+ lsset: list available event sets
+ setlog: set the size of a log
+ setset: set state of event sets
+
+=head1 PRIVILEGE REQUIRED
+
+None
+
+=head1 SEE ALSO
+
+L<fstrace(8)>,
+L<fstrace_help(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+fstrace clear - Clears the trace log
+
+=head1 SYNOPSIS
+
+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>>+] [B<-h>]
+
+=head1 DESCRIPTION
+
+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 B<-set> <I<set name>>+
+
+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 B<-log> <I<log name>>+
+
+Names the trace log to clear. The only acceptable value is
+C<cmfx>. Provide either this argument or the B<-set> argument, or omit
+both to clear the C<cmfx> log by default.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+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 C<root>.
+
+=head1 SEE ALSO
+
+L<fstrace(8)>,
+L<fstrace_lslog(8)>,
+L<fstrace_lsset(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+fstrace dump - Dumps a trace log
+
+=head1 SYNOPSIS
+
+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>>]
+ [B<-fi> <I<output filename>>] [B<-sl> <I<seconds between reads>>]
+ [B<-h>]
+
+=head1 DESCRIPTION
+
+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.
+
+=head1 CAUTIONS
+
+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 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 B<-set> <I<set name>>+
+
+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 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.
+
+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 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.
+
+=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.
+
+=item B<-help>
+
+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 C<cmfx> trace log. The format of the header is as
+follows:
+
+ AFS Trace Dump -
+ Date: I<starting_timestamp>
+ Found 1 logs.
+ Contents of log cmfx:
+
+Each subsequent message describes a Cache Manager operation in the
+following format:
+
+ time <timestamp>, pid <pid>:<event_message>
+
+where
+
+=over 4
+
+=item <timestamp>
+
+Specifies the time at which the Cache Manager performed the operation, as
+the number of seconds since the dump began.
+
+=item <pid>
+
+Specifies the process ID of the process or thread associated with the
+message.
+
+=item <event_message>
+
+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:
+
+ time <timestamp>, pid <pid>: Current time: <unix_time>
+
+where
+
+=over 4
+
+=item <timestamp>
+
+Is the number of seconds from the start of trace logging.
+
+=item <pid>
+
+Is the process ID number.
+
+=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.
+
+=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 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 <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:
+
+ Log wrapped; data missing.
+
+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:
+
+ AFS Trace Dump - Completed
+
+=head1 EXAMPLES
+
+The following command dumps the log associated with the cm event set to
+the standard output stream.
+
+ # fstrace dump -set cm
+ AFS Trace Dump -
+ Date: Tue Apr 7 10:54:57 1998
+ Found 1 logs.
+ time 32.965783, pid 0: Tue Apr 7 10:45:52 1998
+ time 32.965783, pid 33657: Close 0x5c39ed8 flags 0x20
+ time 32.965897, pid 33657: Gn_close vp 0x5c39ed8 flags 0x20 (returns 0x0)
+ time 35.159854, pid 10891: Breaking callback for 5bd95e4 states 1024 (volume 0)
+ time 35.407081, pid 10891: Breaking callback for 5c0fadc states 1024 (volume 0)
+ .
+ .
+ .
+ time 71.440456, pid 33658: Lookup adp 0x5bbdcf0 name g3oCKs \
+ fid (756 4fb7e:588d240.2ff978a8.6)
+ time 71.440569, pid 33658: Returning code 2 from 19
+ time 71.440619, pid 33658: Gn_lookup vp 0x5bbdcf0 name g3oCKs (returns 0x2)
+ 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 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 C<root>.
+
+=head1 SEE ALSO
+
+L<afszcm.cat(5)>,
+L<fstrace(8)>,
+L<fstrace_lslog(8)>,
+L<fstrace_setlog(8)>,
+L<fstrace_lsset(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+fstrace help - Displays help for fstrace commands
+
+=head1 SYNOPSIS
+
+B<fstrace help> [B<-topic> <I<help string>>+] [B<-help>]
+
+B<fstrace h> [B<-t> <I<help string>>+] [B<-h>]
+
+=head1 DESCRIPTION
+
+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.
+
+=head1 OPTIONS
+
+=over 4
+
+=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.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+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.
+
+=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 B<fstrace
+setset> command:
+
+ % fstrace help -topic setset
+ fstrace setset: set state of event sets
+ Usage: fstrace setset [-set <set_name>+] [-active] [-inactive]
+ [-dormant] [-help]
+
+=head1 PRIVILEGE REQUIRED
+
+None
+
+=head1 SEE ALSO
+
+L<fstrace(8)>,
+L<fstrace_apropos(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+fstrace lslog - Displays information about a log
+
+=head1 SYNOPSIS
+
+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>]
+ [B<-h>]
+
+=head1 DESCRIPTION
+
+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 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 B<-set> <I<set name>>+
+
+Names the event set for which to display information about the
+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 B<-log> <I<log name>>
+
+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 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 B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+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 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 : <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 C<cmfx> log:
+
+ # fstrace lslog -log cmfx -long
+ Available logs:
+ cmfx : 60 kbytes (allocated)
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be logged in as the local superuser C<root>.
+
+=head1 SEE ALSO
+
+L<fstrace(8)>,
+L<fstrace_lsset(8)>,
+L<fstrace_setlog(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+fstrace lsset - Reports the status of an event set
+
+=head1 SYNOPSIS
+
+B<fstrace lsset> [B<-set> <I<set name>>+] [B<-help>]
+
+B<fstrace lss> [B<-s> <I<set name>>+] [B<-h>]
+
+=head1 DESCRIPTION
+
+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 B<fstrace setset> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-set> <I<set name>>+
+
+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 B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+The output lists the available event sets and the status of each, in the
+following format:
+
+ Available sets:
+ cm (active | inactive | dormant)
+
+where
+
+=over 4
+
+=item active
+
+Indicates that tracing is enabled for the event set, and kernel memory
+allocated for the corresponding trace log.
+
+=item inactive
+
+Indicates that tracing is temporarily disabled for the event set, but
+kernel memory still allocated for the corresponding trace log.
+
+=item dormant
+
+Indicates that tracing is disabled for the event set, and no kernel memory
+allocated for the corresponding trace log.
+
+=back
+
+=head1 EXAMPLES
+
+The following example displays the available event set and its status:
+
+ # fstrace lsset
+ Available sets:
+ cm active
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be logged in as the local superuser C<root>.
+
+=head1 SEE ALSO
+
+L<fstrace(8)>,
+L<fstrace_setset(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+fstrace setlog - Sets the size of a trace log
+
+=head1 SYNOPSIS
+
+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>> [B<-h>]
+
+B<fstrace sl> [B<-l> <I<log name>>+] B<-b> <I<1-kilobyte units>> [B<-h>]
+
+=head1 DESCRIPTION
+
+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 C<cm> event set; to display the event
+set's status, use the B<fstrace lsset> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-log> <I<log name>>+
+
+Names trace log for which to set the size. The only acceptable
+value is C<cmfx>, which is also the default if this argument is
+omitted.
+
+=item B<-buffersize> <I<1-kilobyte units>>
+
+Specifies the number of 1-kilobyte blocks of kernel memory to allocate for
+the trace log.
+
+=item B<-help>
+
+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 C<cmfx>
+trace log:
+
+ # fstrace setlog -log cmfx -buffersize 80
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be logged in as the local superuser C<root>.
+
+=head1 SEE ALSO
+
+L<fstrace(8)>,
+L<fstrace_lslog(8)>,
+L<fstrace_lsset(8)>,
+L<fstrace_setset(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+fstrace setset - Sets the status of an event set
+
+=head1 SYNOPSIS
+
+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>] [B<-h>]
+
+=head1 DESCRIPTION
+
+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 B<-set> <I<set name>>+
+
+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 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.
+
+=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.
+
+=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.
+
+=item B<-help>
+
+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 inactive:
+
+ # fstrace setset -set cm -inactive
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be logged in as the local superuser C<root>.
+
+=head1 SEE ALSO
+
+L<fstrace(8)>,
+L<fstrace_lsset(8)>,
+L<fstrace_setlog(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+kas - Introduction to the kas command suite
+
+=head1 DESCRIPTION
+
+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 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>.
+
+=item *
+
+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: B<kas interactive>.
+
+=item *
+
+A command to trace Authentication Server operations: B<kas statistics>.
+
+=item *
+
+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.
+
+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 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:
+
+=over 4
+
+=item *
+
+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 (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.
+
+=over 4
+
+=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.
+
+=item B<-cell> <I<cell name>>
+
+Names the cell in which to run the command. It is acceptable to abbreviate
+the cell name to the shortest form that distinguishes it from the other
+entries in the F</usr/vice/etc/CellServDB> file on the local machine. If
+the B<-cell> argument is omitted, the command interpreter determines the
+name of the local cell by reading the following in order:
+
+=over 4
+
+=item *
+
+The value of the AFSCELL environment variable.
+
+=item *
+
+The local F</usr/vice/etc/ThisCell> file.
+
+=back
+
+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 B<-help>
+
+Prints a command's online help message on the standard output stream. Do
+not combine this flag with any of the command's other options; when it is
+provided, the command interpreter ignores all other options, and only
+prints the help message.
+
+=item B<-noauth>
+
+Establishes an unauthenticated connection to the Authentication Server, in
+which the Authentication 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 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 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).
+
+=head1 SEE ALSO
+
+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
+
+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
+
+kas apropos - Displays each help entry containing a keyword string
+
+=head1 SYNOPSIS
+
+B<kas apropos> B<-topic> <I<help string>> [B<-help>]
+
+B<kas a> B<-t> <I<help string>> [B<-h>]
+
+=head1 DESCRIPTION
+
+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 B<kas help> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=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 (C<"">)
+or other delimiters.
+
+=item B<-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<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 B<kas> commands that include the word
+C<key> in their names or short descriptions:
+
+ % kas apropos key
+ setkey: set a user's key
+ stringtokey: convert a string to a key
+
+=head1 PRIVILEGE REQUIRED
+
+None, and no password is required.
+
+=head1 SEE ALSO
+
+L<kas(8)>,
+L<kas_help(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+kas create - Creates an entry in the Authentication Database
+
+=head1 SYNOPSIS
+
+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 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 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 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
+lowercase letters).
+
+=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
+field. If this argument is omitted, the command interpreter prompts for
+the string and does not echo it visibly.
+
+=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 L<kas(8)>.
+
+=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 L<kas(8)>.
+
+=item B<-cell> <I<cell name>>
+
+Names the cell in which to run the command. For more details, see
+L<kas(8)>.
+
+=item B<-servers> <I<authentication servers>>
+
+Names each machine running an Authentication Server with which to
+establish a connection. For more details, see L<kas(8)>.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity C<anonymous> to the issuer. For more
+details, see L<kas(8)>.
+
+=item B<-help>
+
+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 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:
+ initial_password:
+ Verifying, please re-enter initial_password:
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must have the C<ADMIN> flag set on his or her Authentication
+Database entry.
+
+=head1 SEE ALSO
+
+L<kas(8)>,
+L<kas_examine(8)>,
+L<kas_list(8)>,
+L<kas_setfields(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+kas delete - Deletes an entry from the Authentication Database
+
+=head1 SYNOPSIS
+
+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> 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 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 B<-name> <I<name of user>>
+
+Names the Authentication Database entry to delete.
+
+=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
+L<kas(8)>.
+
+=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 L<kas(8)>.
+
+=item B<-cell> <I<cell name>>
+
+Names the cell in which to run the command. For more details, see
+L<kas(8)>.
+
+=item B<-servers> <I<authentication servers>>+
+
+Names each machine running an Authentication Server with which to
+establish a connection. For more details, see L<kas(8)>.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity C<anonymous> to the issuer. For more
+details, see L<kas(8)>.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following example shows the administrative user C<admin> entering
+interactive mode to delete three accounts.
+
+ % kas
+ Password for admin:
+ ka> delete smith
+ ka> delete pat
+ ka> delete terry
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must have the C<ADMIN> flag set on his or her Authentication
+Database entry.
+
+=head1 SEE ALSO
+
+L<kas(8)>,
+L<kas_create(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+kas examine - Displays information from an Authentication Database entry
+
+=head1 SYNOPSIS
+
+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> 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 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 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.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-name> <I<name of user>>
+
+Names the Authentication Database entry from which to display information.
+
+=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.
+
+=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
+L<kas(8)>.
+
+=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 L<kas(8)>.
+
+=item B<-cell> <I<cell name>>
+
+Names the cell in which to run the command. For more details, see
+L<kas(8)>.
+
+=item B<-servers> <I<authentication servers>>+
+
+Names each machine running an Authentication Server with which to
+establish a connection. For more details, see L<kas(8)>.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity C<anonymous> to the issuer. For more
+details, see L<kas(8)>.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+The output includes:
+
+=over 4
+
+=item *
+
+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:
+
+=over 4
+
+=item ADMIN
+
+Enables the user to issue privileged B<kas> commands (default is
+C<NOADMIN>).
+
+=item NOTGS
+
+Prevents the user from obtaining tickets from the Authentication Server's
+Ticket Granting Service (default is C<TGS>).
+
+=item NOSEAL
+
+Prevents the Ticket Granting Service from using the entry's key field as
+an encryption key (default is C<SEAL>).
+
+=item NOCPW
+
+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.
+
+=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 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 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").
+
+=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.
+
+=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.
+
+=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.
+
+=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.
+
+=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.
+
+=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 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.
+
+=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.
+
+=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
+C<smith> is privileged.
+
+ % kas examine smith
+ Password for smith:
+ User data for smith (ADMIN)
+ key (0) cksum is 3414844392, last cpw: Thu Mar 25 16:05:44 1999
+ password will expire: Fri Apr 30 20:44:36 1999
+ 5 consecutive unsuccessful authentications are permitted.
+ The lock time for this user is 25.5 minutes.
+ User is not locked.
+ entry never expires. Max ticket lifetime 100.00 hours.
+ last mod on Tue Jan 5 08:22:29 1999 by admin
+ permit password reuse
+
+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:
+ User data for pat
+ key (0) cksum is 73829292912, last cpw: Wed Apr 7 11:23:01 1999
+ password will expire: Fri Jun 11 11:23:01 1999
+ 5 consecutive unsuccessful authentications are permitted.
+ The lock time for this user is 25.5 minutes.
+ User is locked until Tue Sep 21 12:25:07 1999
+ entry expires on never. Max ticket lifetime 100.00 hours.
+ last mod on Thu Feb 4 08:22:29 1999 by admin
+ permit password reuse
+
+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
+the C<afs> entry.
+
+ % kas examine -name afs -showkey
+ Password for admin: I<admin_password>
+ User data for afs
+ key (12): \357\253\304\352\234\236\253\352, last cpw: no date
+ entry never expires. Max ticket lifetime 100.00 hours.
+ last mod on Thu Mar 25 14:53:29 1999 by admin
+ permit password reuse
+
+=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.
+
+=head1 SEE ALSO
+
+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 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
+
+kas forgetticket - Discards all tickets for the issuer
+
+=head1 SYNOPSIS
+
+B<kas forgetticket> [B<-all>] [B<-help>]
+
+B<kas f> [B<-a>] [B<-h>]
+
+=head1 DESCRIPTION
+
+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 B<-all>
+
+Discards all tickets. This argument explicitly invokes the command's
+default behavior.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command discards all of the issuer's tickets.
+
+ % kas forgetticket
+
+=head1 PRIVILEGE REQUIRED
+
+None, and no password is required.
+
+=head1 SEE ALSO
+
+L<kas(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+kas help - Displays help for kas commands
+
+=head1 SYNOPSIS
+
+B<kas help> [B<-topic> <I<help string>>+] [B<-help>]
+
+B<kas h> [B<-t> <I<help string>>+] [B<-h>]
+
+=head1 DESCRIPTION
+
+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.
+
+=head1 OPTIONS
+
+=over 4
+
+=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.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+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.
+
+=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 B<kas
+setpassword> command:
+
+ % kas help setpassword
+ kas setpassword: set a user's password
+ aliases: sp
+ Usage: kas setpassword -name <name of user>
+ [-new_password <new password>] [-kvno <key version number>]
+ [-admin_username <admin principal to use for authentication>]
+ [-password_for_admin <password>] [-cell <cell name>]
+ [-servers <explicit list of authentication servers>+] [-help]
+
+=head1 PRIVILEGE REQUIRED
+
+None, and no password is required.
+
+=head1 SEE ALSO
+
+L<kas(8)>,
+L<kas_apropos(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+kas interactive - Enters interactive mode
+
+=head1 SYNOPSIS
+
+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> [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 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:
+
+=over 4
+
+=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 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:
+
+=over 4
+
+=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>).
+
+=item *
+
+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.
+
+=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.
+
+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.
+
+=head1 OPTIONS
+
+=over 4
+
+=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
+L<kas(8)>.
+
+=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 L<kas(8)>.
+
+=item B<-cell> <I<cell name>>
+
+Names the cell in which to run the command. For more details, see
+L<kas(8)>.
+
+=item B<-servers> <I<authentication servers>>+
+
+Names each machine running an Authentication Server with which to
+establish a connection. For more details, see L<kas(8)>.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity C<anonymous> to the issuer. For more
+details, see L<kas(8)>.
+
+=item B<-help>
+
+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 C<admin>.
+
+ % kas interactive admin
+ Password for admin: I<admin_password>
+ ka>
+
+=head1 PRIVILEGE REQUIRED
+
+None
+
+=head1 SEE ALSO
+
+L<kas(8)>,
+L<kas_noauthentication(8)>,
+L<kas_quit(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+kas list - Displays all entries in the Authentication Database
+
+=head1 SYNOPSIS
+
+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>] [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 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:
+
+=over 4
+
+=item *
+
+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.
+
+=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.
+
+=head1 OPTIONS
+
+=over 4
+
+=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.
+
+=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.
+
+=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.
+
+=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
+L<kas(8)>.
+
+=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 L<kas(8)>.
+
+=item B<-cell> <I<cell name>>
+
+Names the cell in which to run the command. For more details, see
+L<kas(8)>.
+
+=item B<-servers> <I<authentication servers>>+
+
+Names each machine running an Authentication Server with which to
+establish a connection. For more details, see L<kas(8)>.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity C<anonymous> to the issuer. For more
+details, see L<kas(8)>.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+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 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.
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must have the C<ADMIN> flag set on his or her Authentication
+Database entry.
+
+=head1 SEE ALSO
+
+L<kas(8)>,
+L<kas_examine(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+kas listtickets - Displays all of the issuer's tickets (tokens)
+
+=head1 SYNOPSIS
+
+B<kas listtickets> [B<-name> <I<name of server>>] [B<-long>] [B<-help>]
+
+B<kas listt> [B<-n> <I<name of server>>] [B<-l>] [B<-h>]
+
+=head1 DESCRIPTION
+
+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 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 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 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 B<-long>
+
+Displays the octal numbers that constitute the session key and ticket.
+
+=item B<-help>
+
+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.
+
+ User's (AFS ID <AFS UID>) tokens for <service>[@<cellname>] \
+ [Expires <date>]
+
+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.)
+
+=head1 EXAMPLES
+
+The following two examples are for a user with AFS UID 1020 in the
+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 \
+ [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...
+
+=head1 PRIVILEGE REQUIRED
+
+None, and no password is required.
+
+=head1 SEE ALSO
+
+L<kas(8)>,
+L<tokens(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
+
+kas noauthentication - Discards an authenticated identity in interactive mode
+
+=head1 SYNOPSIS
+
+B<noauthentication> [B<-help>]
+
+B<n> [B<-h>]
+
+=head1 DESCRIPTION
+
+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.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following example command discards the authentication information with
+which the user entered interactive mode.
+
+ ka> noauthentication
+
+=head1 PRIVILEGE REQUIRED
+
+None, and no password is required.
+
+=head1 SEE ALSO
+
+L<kas(8)>,
+L<kas_forgetticket(8)>,
+L<kas_interactive(8)>,
+L<unlog(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
+
+kas quit - Leaves interactive mode
+
+=head1 SYNOPSIS
+
+B<quit> [B<-help>]
+
+B<q> [B<-h>]
+
+=head1 DESCRIPTION
+
+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.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following example demonstrates how the normal command shell prompt
+returns when the issuer leaves interactive mode.
+
+ ka> quit
+ %
+
+=head1 PRIVILEGE REQUIRED
+
+None, and no password is required.
+
+=head1 SEE ALSO
+
+L<kas(8)>,
+L<kas_interactive(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+kas setfields - Sets fields in an Authentication Database entry
+
+=head1 SYNOPSIS
+
+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> 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 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.
+
+=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. 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.
+
+=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 F<syslog> file or equivalent, for
+which the standard location varies depending on the operating system).
+
+=item *
+
+To set how long the Authentication Server refuses to process
+authentication attempts for a locked-out user, set the B<-locktime>
+argument.
+
+=back
+
+The B<kas examine> command displays the settings made with this command.
+
+=head1 CAUTIONS
+
+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.
+
+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 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
+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.
+
+To avoid the undesirable consequences of setting a limit on failed
+authentication attempts, note the following recommendations:
+
+=over 4
+
+=item *
+
+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 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 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
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-name> <I<name of user>>
+
+Names the Authentication Database account for which to change settings.
+
+=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 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 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 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 C<0x020>, default is
+C<SEAL>).
+
+=item NOCPW
+
+The user cannot change his or her own password or key (hexadecimal
+equivalent is C<0x040>, default is C<CPW>).
+
+=back
+
+=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 C<afs> expires,
+all server processes that use the associated key become inaccessible.
+Provide one of the three acceptable values:
+
+=over 4
+
+=item never
+
+The account never expires (the default).
+
+=item I<mm/dd/yyyy>
+
+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>"
+
+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 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 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 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 (C<10:00> equals 10 hours). If this argument is omitted, the
+default setting is 100:00 hours (360000 seconds).
+
+=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 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.
+
+=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 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 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 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 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: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 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
+L<kas(8)>.
+
+=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 L<kas(8)>.
+
+=item B<-cell> <I<cell name>>
+
+Names the cell in which to run the command. For more details, see
+L<kas(8)>.
+
+=item B<-servers> <I<authentication servers>>+
+
+Names each machine running an Authentication Server with which to
+establish a connection. For more details, see L<kas(8)>.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity C<anonymous> to the issuer. For more
+details, see L<kas(8)>.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+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 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.
+
+=head1 SEE ALSO
+
+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 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
+
+kas setpassword - Changes the key field in an Authentication Database entry
+
+=head1 SYNOPSIS
+
+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> 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> 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 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.
+
+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:
+
+=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 L<kpwvalid(8)>.
+
+=item *
+
+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:
+
+ Password was not changed because you changed it too
+ recently; see your systems administrator
+
+=back
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-name> <I<name of user>>
+
+Names the entry in which to record the new key.
+
+=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.
+
+=item B<-kvno> <I<key version number>>
+
+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 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
+L<kas(8)>.
+
+=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 L<kas(8)>.
+
+=item B<-cell> <I<cell name>>
+
+Names the cell in which to run the command. For more details, see
+L<kas(8)>.
+
+=item B<-servers> <I<authentication servers>>+
+
+Names each machine running an Authentication Server with which to
+establish a connection. For more details, see L<kas(8)>.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity C<anonymous> to the issuer. For more
+details, see L<kas(8)>.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+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:
+ new_password:
+ Verifying, please re-enter new_password:
+
+=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 C<afs>, the issuer must have the C<ADMIN> flag set in his or her
+Authentication Database entry.
+
+=head1 SEE ALSO
+
+L<bos_addkey(8)>,
+L<kas(8)>,
+L<kaserver(1)>,
+L<kpwvalid(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
+
+kas statistics - Displays statistics from an Authentication Server process
+
+=head1 SYNOPSIS
+
+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> [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 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 B<-servers> argument is not available in interactive mode, making it
+impossible to specify a certain machine.
+
+=head1 OPTIONS
+
+=over 4
+
+=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
+L<kas(8)>.
+
+=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 L<kas(8)>.
+
+=item B<-cell> <I<cell name>>
+
+Names the cell in which to run the command. For more details, see
+L<kas(8)>.
+
+=item B<-servers> <I<authentication servers>>+
+
+Names each machine running an Authentication Server with which to
+establish a connection. For more details, see L<kas(8)>.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity C<anonymous> to the issuer. For more
+details, see L<kas(8)>.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+The information in the output includes:
+
+=over 4
+
+=item *
+
+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.
+
+=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
+C<fs1.abc.com>.
+
+ % kas statistics -servers fs1.abc.com
+ 56 allocs, 46 frees, 0 password changes
+ Hash table utilization = 0.100000%
+ From host bfff21a7 started at Tue Mar 23 12:42:02 1999:
+ of 88 requests for Authenticate, 18 were aborted.
+ of 14 requests for GetTicket, 0 were aborted.
+ of 4 requests for CreateUser, 1 were aborted.
+ of 12 requests for SetFields, 4 were aborted.
+ of 3 requests for DeleteUser, 0 were aborted.
+ of 23 requests for GetEntry, 4 were aborted.
+ of 18 requests for ListEntry, 0 were aborted.
+ of 2 requests for GetStats, 1 were aborted.
+ of 2 requests for GetRandomKey, 0 were aborted.
+ Used 6.015 seconds of CPU time.
+ 3 admin accounts
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must have the C<ADMIN> flag set on his or her Authentication
+Database entry.
+
+=head1 SEE ALSO
+
+L<kas(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+kas stringtokey - Converts a character string into an octal key
+
+=head1 SYNOPSIS
+
+B<kas stringtokey> B<-string> <I<password string>>
+ [B<-cell> <I<cell name>>] [B<-help>]
+
+B<kas str> B<-s> <I<password string>> [B<-c> <I<cell name>>] [B<-h>]
+
+=head1 DESCRIPTION
+
+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 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.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-string> <I<password string>>
+
+Specifies the character string to convert into an octal key.
+
+=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:
+
+=over 4
+
+=item *
+
+First, the value of the environment variable AFSCELL.
+
+=item *
+
+Second, the cellname in the F</usr/vice/etc/ThisCell> file on the local
+machine.
+
+=back
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+The output is of the following form:
+
+ Converting I<password string> in realm 'I<cell_name>' yields key='I<key>'.
+
+=head1 EXAMPLES
+
+The following example shows the octal key equivalent of the string
+C<new_pswd> in the ABC Corporation cell.
+
+ % kas stringtokey new_pswd
+ Converting new_pswd in realm 'ABC.COM' yields
+ key='\346\307\364\320\263\233\342\354'.
+
+=head1 PRIVILEGE REQUIRED
+
+None, and no password is required.
+
+=head1 SEE ALSO
+
+L<ThisCell(5)>,
+L<kas(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+kas unlock - Unlocks a locked user account
+
+=head1 SYNOPSIS
+
+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>]
+
+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 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
+F</usr/afs/local/kaauxdb> file from each one. The B<kaserver> process
+recreates the file as it restarts.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-name> <I<authentication ID>>
+
+Names the Authentication Database entry to unlock.
+
+=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
+L<kas(8)>.
+
+=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 L<kas(8)>.
+
+=item B<-cell> <I<cell name>>
+
+Names the cell in which to run the command. For more details, see
+L<kas(8)>.
+
+=item B<-servers> <I<authentication servers>>+
+
+Names each machine running an Authentication Server with which to
+establish a connection. For more details, see L<kas(8)>.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity C<anonymous> to the issuer. For more
+details, see L<kas(8)>.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+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.
+
+=head1 SEE ALSO
+
+L<kas(8)>,
+L<kas_examine(8)>,
+L<kas_setfields(8)>,
+L<klog(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
+
+prdb_check - Checks the integrity of the Protection Database
+
+=head1 SYNOPSIS
+
+B<prdb_check> B<-database> <I<ptdb file>> [B<-uheader>] [B<-pheader>]
+ [B<-entries>] [B<-verbose>] [B<-help>]
+
+B<prdb_check> B<-d> <I<ptdb file>> [B<-u>] [B<-p>] [B<-e>] [B<-v>] [B<-h>]
+
+=head1 DESCRIPTION
+
+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 F<prdb.DB0> file
+(with a different name) on which to run the command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-database> <I<ptdb file>>
+
+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 B<-uheader>
+
+Displays information which Ubik maintains in the database's header.
+
+=item B<-pheader>
+
+Displays information which the Protection Server maintains in the
+database's header.
+
+=item B<-entries>
+
+Outputs every entry in the database. Some of the information is similar to
+that returned by the B<pts examine> command.
+
+=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.
+
+=item B<-help>
+
+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 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 C<root>.
+
+=head1 SEE ALSO
+
+L<prdb.DB0(5)>,
+L<bos_shutdown(1)>,
+L<pts_examine(1)>,
+L<ptserver(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+ptserver - Initializes the Protection Server
+
+=head1 SYNOPSIS
+
+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 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
+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:
+
+=over 4
+
+=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.
+
+=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.
+
+=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 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 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 B<-p> <I<number of processes>>
+
+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 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 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.
+
+=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,
+GetStatus, and so on) sent or received, aggregated over all connections to
+other machines. To display or otherwise access the records, use the Rx
+Monitoring API.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+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 \
+ -type simple -cmd /usr/afs/bin/ptserver
+
+=head1 PRIVILEGE REQUIRED
+
+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(5)>,
+L<prdb.DB0(5)>,
+L<bos_create(1)>,
+L<bos_getlog(1)>,
+L<pts(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
+
+salvager - Initializes the Salvager component of the fs process
+
+=head1 SYNOPSIS
+
+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 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:
+
+=over 4
+
+=item *
+
+If the volume header is corrupted, the Salvager removes the volume
+completely and records the removal in its log file,
+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.
+
+=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 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:
+
+=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.
+
+=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.
+
+=item *
+
+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.
+
+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 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.
+
+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 [I<initcmd>]
+
+Accommodates the command's use of the AFS command parser, and is optional.
+
+=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 F</vicepI<x>> or F</vicepI<xx>>. Omit this argument to
+salvage every partition on the file server machine.
+
+=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.
+
+=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.
+
+=item B<-nowrite>
+
+Brings all undamaged volumes online without attempting to salvage any
+damaged volumes.
+
+=item B<-inodes>
+
+Records in the F</usr/afs/logs/SalvageLog> file a list of all AFS inodes
+that the Salvager modified.
+
+=item B<-force>
+
+Inspects all volumes for corruption, not just those that are marked as
+having been active when a crash occurred.
+
+=item B<-oktozap>
+
+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 B<-rootinodes>
+
+Records in the F</usr/afs/logs/SalvageLog> file a list of all AFS inodes
+owned by the local superuser C<root>.
+
+=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 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.
+
+=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:
+
+=over 4
+
+=item *
+
+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 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 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.
+
+=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
+salvaged.
+
+=item B<-showlog>
+
+Displays on the standard output stream all log data that is being written
+to the F</usr/afs/logs/SalvageLog> file.
+
+=item B<-showsuid>
+
+Displays a list of the pathnames for all files that have the setuid or
+setgid mode bit set.
+
+=item B<-showmounts>
+
+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 B<-orphans> (ignore | remove | attach)
+
+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
+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
+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:
+
+=over 4
+
+=item C<__ORPHANFILE__.I<index>> for files.
+
+=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.
+
+=back
+
+=item B<-help>
+
+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 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 C<root>.
+
+=head1 SEE ALSO
+
+L<BosConfig(5)>,
+L<SalvageLog(5)>,
+L<bos_create(1)>,
+L<bos_getlog(1)>,
+L<bos_salvage(1)>,
+L<vos_move(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
+
+upclient - Initializes the client portion of the Update Server
+
+=head1 SYNOPSIS
+
+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 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
+F</usr/afs/etc> directory using the B<-clear> option. The contents of
+this directory are sensitive.
+
+=head1 OPTIONS
+
+=over 4
+
+=item <I<hostname>>
+
+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 B<-crypt>
+
+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 B<-clear>
+
+Requests transfer of data from the B<upserver> process in unencrypted
+form. Provide this flag or the B<-crypt> flag, but not both.
+
+=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 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 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.
+
+=item <I<dir>>+
+
+Names each directory to check for modified files. The conventional choices
+are the following:
+
+=over 4
+
+=item *
+
+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 *
+
+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 B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+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 \
+ -t 120 /usr/afs/bin"
+
+=head1 PRIVILEGE REQUIRED
+
+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(5)>,
+L<bos_create(1)>,
+L<upserver(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+upserver - Initializes the server portion of the Update Server
+
+=head1 SYNOPSIS
+
+B<upserver> [<I<directory>>+] [B<-crypt> <I<directory>>+]
+ [B<-clear> <I<directory>>+] [B<-auth> <I<directory>>+] [B<-help>]
+
+=head1 DESCRIPTION
+
+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
+F</usr/afs/etc> directory without the B<-crypt> flag. The contents of
+this directory are sensitive.
+
+=head1 OPTIONS
+
+=over 4
+
+=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.
+
+=item B<-crypt> <I<directory>>+
+
+Precedes a list of one or more directories that the B<upserver> process
+distributes only in encrypted form.
+
+=item B<-clear> <I<directory>>+
+
+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 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.
+
+=item B<-help>
+
+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 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"
+
+=head1 PRIVILEGE REQUIRED
+
+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(5)>,
+L<bos_create(1)>,
+L<upclient(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+vldb_check - Checks the integrity of the VLDB
+
+=head1 SYNOPSIS
+
+B<vldb_check> B<-database> <I<vldb file>> [B<-uheader>] [B<-vheader>]
+ [B<-servers>] [B<-entries>] [B<-verbose>] [B<-help>]
+
+B<vldb_check> B<-d> <I<vldb file>> [B<-u>] [B<-vh>] [B<-s>] [B<-e>]
+ [B<-ve>] [B<-h>]
+
+=head1 DESCRIPTION
+
+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 F<vldb.DB0> file (with a
+different name) on which to run the command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-database> <I<vldb file>>
+
+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 B<-uheader>
+
+Displays information which Ubik maintains in the database's header.
+
+=item B<-pheader>
+
+Displays information which the VL Server maintains in the database's
+header.
+
+=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 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.
+
+=item B<-verbose>
+
+Reports additional information about the database, including the number of
+entries for each type of volume.
+
+=item B<-help>
+
+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 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 C<root>.
+
+=head1 SEE ALSO
+
+L<vldb.DB0(5)>,
+L<bos_shutdown(1)>,
+L<vlserver(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+vlserver - Initializes the Volume Location Server
+
+=head1 SYNOPSIS
+
+B<vlserver> [B<-p> <I<lwp processes>>] [B<-nojumbo>]
+ [B<-enable_peer_stats>] [B<-enable_process_stats>] [B<-help>]
+
+=head1 DESCRIPTION
+
+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 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), 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
+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 VL Server records a trace of its activity in the
+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 B<-p> <I<lwp processes>>
+
+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 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.
+
+=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.
+
+=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,
+GetStatus, and so on) sent or received, aggregated over all connections to
+other machines. To display or otherwise access the records, use the Rx
+Monitoring API.
+
+=item B<-help>
+
+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 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 \
+ -cmd "/usr/afs/bin/vlserver -p 6"
+
+=head1 PRIVILEGE REQUIRED
+
+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(5)>,
+L<VLLog(5)>,
+L<vldb.DB0(5)>,
+L<bos_create(1)>,
+L<bos_getlog(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
+
+voldump - Dump an AFS volume without using the Volume Server
+
+=head1 SYNOPSIS
+
+B<voldump> B<-part> <I<partition>> B<-volumeid> <I<volume id>>
+ [B<-file> <I<dump file>>] [B<-verbose>] [B<-help>]
+
+B<voldump> B<-p> <I<partition>> B<-vo> <I<volume id>>
+ [B<-f> <I<dump file>>] [B<-ve>] [B<-h>]
+
+=head1 DESCRIPTION
+
+B<voldump> dumps an AFS volume in the format used by B<vos dump> without
+using the Volume Server. It must be run on the file server machine and
+usually must be run as the superuser C<root> to have permissions to read
+the file server data. It's primary use is to recover data from a file
+server machine where the Volume Server cannot be started for some reason.
+
+The dump output will go to standard output, or to a file if B<-file> is
+specified. B<vos restore> can be used to load the resulting dump into a
+new AFS volume. B<voldump> always does a full dump.
+
+=head1 CAUTIONS
+
+Normally, use B<vos dump> instead of this command. B<voldump> is a tool
+of last resort to try to extract data from the raw data structures stored
+on the file server machine and is not as regularly tested or used as the
+normal B<vos dump> implementation.
+
+If the AFS volume being dumped changes while B<voldump> is running, the
+results may be inconsistent. If the File Server and Volume Server are
+running, stop them with B<bos shutdown> or a similar method before running
+this command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-part> <I<partition>>
+
+Names the partition on which the volume to be dumped is located.
+B<voldump> does not take the normal full range of ways of specifying a
+partition. Instead, I<partition> must be either a single letter between
+C<a> and C<z>, corresponding to F</vicepa> through F</vicepz>, or the full
+path to the file server partition. C<aa> is not recognized; use
+F</vicepaa> instead.
+
+=item B<-volumeid> <I<volume id>>
+
+Specifies the ID of the volume to dump. The volume must be specified by
+numeric ID, not by name.
+
+=item B<-file> <I<dump file>>
+
+Specifies the output file for the dump. If this option is not given, the
+volume will be dumped to standard output.
+
+=item B<-verbose>
+
+Asks for a verbose trace of the dump process. This trace information will
+be sent to standard error.
+
+=back
+
+=head1 EXAMPLES
+
+The following command dumps the volume 1936964939 on the F</vicepb>
+partition to the file F</tmp/volume.dump>:
+
+ % voldump -part /vicepb -volumeid 1936964939 -file /tmp/volume.dump
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must have read access to the file server data stored in the
+specified partition. Usually, this means that the issuer must be the
+local superuser C<root> on the file server machine.
+
+=head1 SEE ALSO
+
+L<bos_shutdown(1)>,
+L<volserver(8)>,
+L<vos_dump(1)>,
+L<vos_restore(1)>
+
+=head1 COPYRIGHT
+
+Copyright 2005 Russ Allbery <rra@stanford.edu>
+
+This documentation is covered by the IBM Public License Version 1.0. This
+man page was written by Russ Allbery for OpenAFS.
--- /dev/null
+=head1 NAME
+
+volinfo - Produces detailed statistics about AFS volume headers
+
+=head1 SYNOPSIS
+
+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 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 B<-online>
+
+Is nonoperational.
+
+=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 B<-date>
+
+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 B<-inode>
+
+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 B<-itime>
+
+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 B<-part> <I<partition name>>+
+
+Specifies the partition that houses each volume for which to produce
+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 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.
+
+=item B<-header>
+
+Displays statistics about the volume header of each volume, in addition to
+the default output.
+
+=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 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.
+
+=item B<-saveinodes>
+
+Creates a file in the current working directory for each inode in each
+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 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).
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+By default, the command produces several line of statistics for each
+volume. Adding other options produces or substitutes additional
+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 C<root>.
+
+=head1 SEE ALSO
+
+L<vldb.DB0(5)>,
+L<volserver(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+volserver - Initializes the Volume Server component of the fs process
+
+=head1 SYNOPSIS
+
+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 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 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
+F</usr/afs/logs/VolserLog> file. Use the B<bos getlog> command to display
+the contents of the file.
+
+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 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.
+
+=item B<-p> <I<number of processes>>
+
+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 B<-udpsize> <I<size of socket buffer>>
+
+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 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.
+
+=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,
+GetStatus, and so on) sent or received, aggregated over all connections to
+other machines. To display or otherwise access the records, use the Rx
+Monitoring API.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+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 \
+ -cmd /usr/afs/bin/volserver
+
+=head1 PRIVILEGE REQUIRED
+
+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(5)>,
+L<VolserLog(5)>,
+L<bos_create(1)>,
+L<bos_getlog(1)>,
+L<vos(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.
debian/tmp/usr/bin/rxgen usr/bin
+
debian/tmp/usr/include usr
+
debian/tmp/usr/lib/*.a usr/lib
debian/tmp/usr/lib/afs usr/lib
+
+debian/doc/man1/rxgen.1 usr/share/man/man1
src/afs/afszcm.cat usr/share/openafs
debian/CellServDB usr/share/openafs
+
+debian/doc/man1/afs.1 usr/share/man/man1
+debian/doc/man1/afsmonitor.1 usr/share/man/man1
+debian/doc/man1/bos.1 usr/share/man/man1
+debian/doc/man1/bos_addhost.1 usr/share/man/man1
+debian/doc/man1/bos_addkey.1 usr/share/man/man1
+debian/doc/man1/bos_adduser.1 usr/share/man/man1
+debian/doc/man1/bos_apropos.1 usr/share/man/man1
+debian/doc/man1/bos_create.1 usr/share/man/man1
+debian/doc/man1/bos_delete.1 usr/share/man/man1
+debian/doc/man1/bos_exec.1 usr/share/man/man1
+debian/doc/man1/bos_getdate.1 usr/share/man/man1
+debian/doc/man1/bos_getlog.1 usr/share/man/man1
+debian/doc/man1/bos_getrestart.1 usr/share/man/man1
+debian/doc/man1/bos_help.1 usr/share/man/man1
+debian/doc/man1/bos_install.1 usr/share/man/man1
+debian/doc/man1/bos_listhosts.1 usr/share/man/man1
+debian/doc/man1/bos_listkeys.1 usr/share/man/man1
+debian/doc/man1/bos_listusers.1 usr/share/man/man1
+debian/doc/man1/bos_prune.1 usr/share/man/man1
+debian/doc/man1/bos_removehost.1 usr/share/man/man1
+debian/doc/man1/bos_removekey.1 usr/share/man/man1
+debian/doc/man1/bos_removeuser.1 usr/share/man/man1
+debian/doc/man1/bos_restart.1 usr/share/man/man1
+debian/doc/man1/bos_salvage.1 usr/share/man/man1
+debian/doc/man1/bos_setauth.1 usr/share/man/man1
+debian/doc/man1/bos_setcellname.1 usr/share/man/man1
+debian/doc/man1/bos_setrestart.1 usr/share/man/man1
+debian/doc/man1/bos_shutdown.1 usr/share/man/man1
+debian/doc/man1/bos_start.1 usr/share/man/man1
+debian/doc/man1/bos_startup.1 usr/share/man/man1
+debian/doc/man1/bos_status.1 usr/share/man/man1
+debian/doc/man1/bos_stop.1 usr/share/man/man1
+debian/doc/man1/bos_uninstall.1 usr/share/man/man1
+debian/doc/man1/cmdebug.1 usr/share/man/man1
+debian/doc/man1/fs.1 usr/share/man/man1
+debian/doc/man1/fs_apropos.1 usr/share/man/man1
+debian/doc/man1/fs_checkservers.1 usr/share/man/man1
+debian/doc/man1/fs_checkvolumes.1 usr/share/man/man1
+debian/doc/man1/fs_cleanacl.1 usr/share/man/man1
+debian/doc/man1/fs_copyacl.1 usr/share/man/man1
+debian/doc/man1/fs_diskfree.1 usr/share/man/man1
+debian/doc/man1/fs_examine.1 usr/share/man/man1
+debian/doc/man1/fs_exportafs.1 usr/share/man/man1
+debian/doc/man1/fs_flush.1 usr/share/man/man1
+debian/doc/man1/fs_flushmount.1 usr/share/man/man1
+debian/doc/man1/fs_flushvolume.1 usr/share/man/man1
+debian/doc/man1/fs_getcacheparms.1 usr/share/man/man1
+debian/doc/man1/fs_getcellstatus.1 usr/share/man/man1
+debian/doc/man1/fs_getclientaddrs.1 usr/share/man/man1
+debian/doc/man1/fs_getserverprefs.1 usr/share/man/man1
+debian/doc/man1/fs_help.1 usr/share/man/man1
+debian/doc/man1/fs_listacl.1 usr/share/man/man1
+debian/doc/man1/fs_listcells.1 usr/share/man/man1
+debian/doc/man1/fs_listquota.1 usr/share/man/man1
+debian/doc/man1/fs_lsmount.1 usr/share/man/man1
+debian/doc/man1/fs_messages.1 usr/share/man/man1
+debian/doc/man1/fs_mkmount.1 usr/share/man/man1
+debian/doc/man1/fs_newcell.1 usr/share/man/man1
+debian/doc/man1/fs_quota.1 usr/share/man/man1
+debian/doc/man1/fs_rmmount.1 usr/share/man/man1
+debian/doc/man1/fs_setacl.1 usr/share/man/man1
+debian/doc/man1/fs_setcachesize.1 usr/share/man/man1
+debian/doc/man1/fs_setcell.1 usr/share/man/man1
+debian/doc/man1/fs_setclientaddrs.1 usr/share/man/man1
+debian/doc/man1/fs_setquota.1 usr/share/man/man1
+debian/doc/man1/fs_setserverprefs.1 usr/share/man/man1
+debian/doc/man1/fs_setvol.1 usr/share/man/man1
+debian/doc/man1/fs_storebehind.1 usr/share/man/man1
+debian/doc/man1/fs_sysname.1 usr/share/man/man1
+debian/doc/man1/fs_whereis.1 usr/share/man/man1
+debian/doc/man1/fs_whichcell.1 usr/share/man/man1
+debian/doc/man1/fs_wscell.1 usr/share/man/man1
+debian/doc/man1/klog.1 usr/share/man/man1
+debian/doc/man1/livesys.1 usr/share/man/man1
+debian/doc/man1/pagsh.1 usr/share/man/man1
+debian/doc/man1/pts.1 usr/share/man/man1
+debian/doc/man1/pts_adduser.1 usr/share/man/man1
+debian/doc/man1/pts_apropos.1 usr/share/man/man1
+debian/doc/man1/pts_chown.1 usr/share/man/man1
+debian/doc/man1/pts_creategroup.1 usr/share/man/man1
+debian/doc/man1/pts_createuser.1 usr/share/man/man1
+debian/doc/man1/pts_delete.1 usr/share/man/man1
+debian/doc/man1/pts_examine.1 usr/share/man/man1
+debian/doc/man1/pts_help.1 usr/share/man/man1
+debian/doc/man1/pts_listentries.1 usr/share/man/man1
+debian/doc/man1/pts_listmax.1 usr/share/man/man1
+debian/doc/man1/pts_listowned.1 usr/share/man/man1
+debian/doc/man1/pts_membership.1 usr/share/man/man1
+debian/doc/man1/pts_removeuser.1 usr/share/man/man1
+debian/doc/man1/pts_rename.1 usr/share/man/man1
+debian/doc/man1/pts_setfields.1 usr/share/man/man1
+debian/doc/man1/pts_setmax.1 usr/share/man/man1
+debian/doc/man1/rxdebug.1 usr/share/man/man1
+debian/doc/man1/scout.1 usr/share/man/man1
+debian/doc/man1/sys.1 usr/share/man/man1
+debian/doc/man1/tokens.1 usr/share/man/man1
+debian/doc/man1/translate_et.1 usr/share/man/man1
+debian/doc/man1/udebug.1 usr/share/man/man1
+debian/doc/man1/unlog.1 usr/share/man/man1
+debian/doc/man1/up.1 usr/share/man/man1
+debian/doc/man1/vos.1 usr/share/man/man1
+debian/doc/man1/vos_addsite.1 usr/share/man/man1
+debian/doc/man1/vos_apropos.1 usr/share/man/man1
+debian/doc/man1/vos_backup.1 usr/share/man/man1
+debian/doc/man1/vos_backupsys.1 usr/share/man/man1
+debian/doc/man1/vos_changeaddr.1 usr/share/man/man1
+debian/doc/man1/vos_create.1 usr/share/man/man1
+debian/doc/man1/vos_delentry.1 usr/share/man/man1
+debian/doc/man1/vos_dump.1 usr/share/man/man1
+debian/doc/man1/vos_examine.1 usr/share/man/man1
+debian/doc/man1/vos_help.1 usr/share/man/man1
+debian/doc/man1/vos_listaddrs.1 usr/share/man/man1
+debian/doc/man1/vos_listpart.1 usr/share/man/man1
+debian/doc/man1/vos_listvldb.1 usr/share/man/man1
+debian/doc/man1/vos_listvol.1 usr/share/man/man1
+debian/doc/man1/vos_lock.1 usr/share/man/man1
+debian/doc/man1/vos_move.1 usr/share/man/man1
+debian/doc/man1/vos_partinfo.1 usr/share/man/man1
+debian/doc/man1/vos_release.1 usr/share/man/man1
+debian/doc/man1/vos_remove.1 usr/share/man/man1
+debian/doc/man1/vos_remsite.1 usr/share/man/man1
+debian/doc/man1/vos_rename.1 usr/share/man/man1
+debian/doc/man1/vos_restore.1 usr/share/man/man1
+debian/doc/man1/vos_status.1 usr/share/man/man1
+debian/doc/man1/vos_syncserv.1 usr/share/man/man1
+debian/doc/man1/vos_syncvldb.1 usr/share/man/man1
+debian/doc/man1/vos_unlock.1 usr/share/man/man1
+debian/doc/man1/vos_unlockvldb.1 usr/share/man/man1
+debian/doc/man1/vos_zap.1 usr/share/man/man1
+
+debian/doc/man5/CellServDB.5 usr/share/man/man5
+debian/doc/man5/NetInfo.5 usr/share/man/man5
+debian/doc/man5/NetRestrict.5 usr/share/man/man5
+debian/doc/man5/ThisCell.5 usr/share/man/man5
+debian/doc/man5/afs.5 usr/share/man/man5
+debian/doc/man5/afs_cache.5 usr/share/man/man5
+debian/doc/man5/afsmonitor.5 usr/share/man/man5
+debian/doc/man5/afszcm.cat.5 usr/share/man/man5
+debian/doc/man5/butc.5 usr/share/man/man5
+debian/doc/man5/butc_logs.5 usr/share/man/man5
+debian/doc/man5/cacheinfo.5 usr/share/man/man5
+debian/doc/man5/tapeconfig.5 usr/share/man/man5
+
+debian/doc/man8/afsd.8 usr/share/man/man8
+debian/doc/man8/backup.8 usr/share/man/man8
+debian/doc/man8/backup_adddump.8 usr/share/man/man8
+debian/doc/man8/backup_addhost.8 usr/share/man/man8
+debian/doc/man8/backup_addvolentry.8 usr/share/man/man8
+debian/doc/man8/backup_addvolset.8 usr/share/man/man8
+debian/doc/man8/backup_apropos.8 usr/share/man/man8
+debian/doc/man8/backup_dbverify.8 usr/share/man/man8
+debian/doc/man8/backup_deldump.8 usr/share/man/man8
+debian/doc/man8/backup_deletedump.8 usr/share/man/man8
+debian/doc/man8/backup_delhost.8 usr/share/man/man8
+debian/doc/man8/backup_delvolentry.8 usr/share/man/man8
+debian/doc/man8/backup_delvolset.8 usr/share/man/man8
+debian/doc/man8/backup_diskrestore.8 usr/share/man/man8
+debian/doc/man8/backup_dump.8 usr/share/man/man8
+debian/doc/man8/backup_dumpinfo.8 usr/share/man/man8
+debian/doc/man8/backup_help.8 usr/share/man/man8
+debian/doc/man8/backup_interactive.8 usr/share/man/man8
+debian/doc/man8/backup_jobs.8 usr/share/man/man8
+debian/doc/man8/backup_kill.8 usr/share/man/man8
+debian/doc/man8/backup_labeltape.8 usr/share/man/man8
+debian/doc/man8/backup_listdumps.8 usr/share/man/man8
+debian/doc/man8/backup_listhosts.8 usr/share/man/man8
+debian/doc/man8/backup_listvolsets.8 usr/share/man/man8
+debian/doc/man8/backup_quit.8 usr/share/man/man8
+debian/doc/man8/backup_readlabel.8 usr/share/man/man8
+debian/doc/man8/backup_restoredb.8 usr/share/man/man8
+debian/doc/man8/backup_savedb.8 usr/share/man/man8
+debian/doc/man8/backup_scantape.8 usr/share/man/man8
+debian/doc/man8/backup_setexp.8 usr/share/man/man8
+debian/doc/man8/backup_status.8 usr/share/man/man8
+debian/doc/man8/backup_volinfo.8 usr/share/man/man8
+debian/doc/man8/backup_volrestore.8 usr/share/man/man8
+debian/doc/man8/backup_volsetrestore.8 usr/share/man/man8
+debian/doc/man8/butc.8 usr/share/man/man8
+debian/doc/man8/fms.8 usr/share/man/man8
+debian/doc/man8/fstrace.8 usr/share/man/man8
+debian/doc/man8/fstrace_apropos.8 usr/share/man/man8
+debian/doc/man8/fstrace_clear.8 usr/share/man/man8
+debian/doc/man8/fstrace_dump.8 usr/share/man/man8
+debian/doc/man8/fstrace_help.8 usr/share/man/man8
+debian/doc/man8/fstrace_lslog.8 usr/share/man/man8
+debian/doc/man8/fstrace_lsset.8 usr/share/man/man8
+debian/doc/man8/fstrace_setlog.8 usr/share/man/man8
+debian/doc/man8/fstrace_setset.8 usr/share/man/man8
case "$1" in
configure)
update-alternatives --install /usr/bin/pagsh pagsh \
- /usr/bin/pagsh.openafs 100
+ /usr/bin/pagsh.openafs 100 \
+ --slave /usr/share/man/man1/pagsh.1.gz pagsh.1.gz \
+ /usr/share/man/man1/pagsh.openafs.1.gz
test -d /afs || mkdir /afs
debian/tmp/usr/lib/openafs/vlserver usr/lib/openafs
debian/ConfigUtils.pm usr/share/perl5/Debian/OpenAFS
+
+debian/doc/man5/BackupLog.5 usr/share/man/man5
+debian/doc/man5/VLLog.5 usr/share/man/man5
+debian/doc/man5/bdb.DB0.5 usr/share/man/man5
+debian/doc/man5/prdb.DB0.5 usr/share/man/man5
+debian/doc/man5/vldb.DB0.5 usr/share/man/man5
+
+debian/doc/man8/buserver.8 usr/share/man/man8
+debian/doc/man8/prdb_check.8 usr/share/man/man8
+debian/doc/man8/ptserver.8 usr/share/man/man8
+debian/doc/man8/vldb_check.8 usr/share/man/man8
+debian/doc/man8/vlserver.8 usr/share/man/man8
debian/tmp/usr/lib/openafs/fileserver usr/lib/openafs
debian/tmp/usr/lib/openafs/salvager usr/lib/openafs
debian/tmp/usr/lib/openafs/volserver usr/lib/openafs
+
+debian/doc/man5/BosConfig.5 usr/share/man/man5
+debian/doc/man5/BosLog.5 usr/share/man/man5
+debian/doc/man5/FORCESALVAGE.5 usr/share/man/man5
+debian/doc/man5/FileLog.5 usr/share/man/man5
+debian/doc/man5/KeyFile.5 usr/share/man/man5
+debian/doc/man5/NoAuth.5 usr/share/man/man5
+debian/doc/man5/SALVAGE.fs.5 usr/share/man/man5
+debian/doc/man5/SalvageLog.5 usr/share/man/man5
+debian/doc/man5/VolserLog.5 usr/share/man/man5
+debian/doc/man5/afs_volume_header.5 usr/share/man/man5
+debian/doc/man5/salvage.lock.5 usr/share/man/man5
+debian/doc/man5/sysid.5 usr/share/man/man5
+
+debian/doc/man8/bosserver.8 usr/share/man/man8
+debian/doc/man8/fileserver.8 usr/share/man/man8
+debian/doc/man8/salvager.8 usr/share/man/man8
+debian/doc/man8/upclient.8 usr/share/man/man8
+debian/doc/man8/upserver.8 usr/share/man/man8
+debian/doc/man8/voldump.8 usr/share/man/man8
+debian/doc/man8/volinfo.8 usr/share/man/man8
+debian/doc/man8/volserver.8 usr/share/man/man8
debian/tmp/usr/bin/kpasswd usr/bin
debian/tmp/usr/sbin/kas usr/bin
+
+debian/doc/man1/kpasswd.1 usr/share/man/man1
+
+debian/doc/man8/kas.8 usr/share/man/man8
+debian/doc/man8/kas_apropos.8 usr/share/man/man8
+debian/doc/man8/kas_create.8 usr/share/man/man8
+debian/doc/man8/kas_delete.8 usr/share/man/man8
+debian/doc/man8/kas_examine.8 usr/share/man/man8
+debian/doc/man8/kas_forgetticket.8 usr/share/man/man8
+debian/doc/man8/kas_help.8 usr/share/man/man8
+debian/doc/man8/kas_interactive.8 usr/share/man/man8
+debian/doc/man8/kas_list.8 usr/share/man/man8
+debian/doc/man8/kas_listtickets.8 usr/share/man/man8
+debian/doc/man8/kas_noauthentication.8 usr/share/man/man8
+debian/doc/man8/kas_quit.8 usr/share/man/man8
+debian/doc/man8/kas_setfields.8 usr/share/man/man8
+debian/doc/man8/kas_setpassword.8 usr/share/man/man8
+debian/doc/man8/kas_statistics.8 usr/share/man/man8
+debian/doc/man8/kas_stringtokey.8 usr/share/man/man8
+debian/doc/man8/kas_unlock.8 usr/share/man/man8
mkdir -p $(CURDIR)/debian/tmp
$(MAKE) install_nolibafs DESTDIR=$(CURDIR)/debian/tmp
chmod +x debian/afs-rootvol debian/afs-newcell
+ cd debian/doc && ./build-man
touch build-stamp
clean:
ifeq (Makefile,$(wildcard Makefile))
$(MAKE) distclean
endif
+ rm -rf debian/doc/man1 debian/doc/man5 debian/doc/man8
dh_clean
install: DH_OPTIONS=
mv debian/openafs-client/usr/bin/pagsh \
debian/openafs-client/usr/bin/pagsh.openafs
+ mv debian/openafs-client/usr/share/man/man1/pagsh.1 \
+ debian/openafs-client/usr/share/man/man1/pagsh.openafs.1
mv debian/openafs-client/usr/bin/up \
debian/openafs-client/usr/bin/afs-up
+ mv debian/openafs-client/usr/share/man/man1/up.1 \
+ debian/openafs-client/usr/share/man/man1/afs-up.1
+
install -m 644 -c debian/tmp/usr/lib/pam_afs.so.1 \
debian/libpam-openafs-kaserver/lib/security/pam_afs.so
install -m 644 -c debian/tmp/usr/lib/pam_afs.krb.so.1 \
projects / packages / o / openafs.git / commitdiff