* New upstream release (1.4.1-rc10).
- Supports Linux 2.6.16. (Closes: #358203)
- Suspend should work with newer kernels. (Closes: #341588)
+ - Upstream now includes man pages, so remove our backport.
+ * Always pass the system type into Autoconf, following autotools-dev
+ best practices.
- -- Russ Allbery <rra@debian.org> Tue, 28 Mar 2006 13:32:16 -0800
+ -- Russ Allbery <rra@debian.org> Tue, 28 Mar 2006 14:09:37 -0800
openafs (1.4.0-4) 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
-
-xstat_cm_test - Displays data collections from the Cache Manager
-
-=head1 SYNOPSIS
-
-=for html
-<div class="synopsis">
-
-B<xstat_cm_test> [I<initcmd>]
- S<<< B<-cmname> <I<cache manager name(s) to monitor>>+ >>>
- S<<< B<-collID> <I<collection(s) to fetch>>+ >>> [B<-onceonly>]
- S<<< [B<-frequency> <I<poll frequency, in seconds>>] >>>
- S<<< [B<-period> <I<data collection time, in minutes>>] >>> [B<-debug>]
- [B<-help>]
-
-B<xstat_cm_test> [I<i>] S<<< B<-cm> <I<cache manager name(s) to monitor>>+ >>>
- S<<< B<-co> <I<collection(s) to fetch>>+ >>> [B<-o>]
- S<<< [B<-f> <I<poll frequency, in seconds>>] >>>
- S<<< [B<-p> <I<data collection time, in minutes>>] >>> [B<-d>] [B<-h>]
-
-=for html
-</div>
-
-=head1 DESCRIPTION
-
-The B<xstat_cm_test> command tests the routines in the F<libxstat_cm.a>
-library and displays the data collections associated with the Cache
-Manager. The command executes in the foreground.
-
-The command produces a large volume of output; to save it for later
-analysis, direct it to a file.
-
-=head1 OPTIONS
-
-=over 4
-
-=item I<initcmd>
-
-Accommodates the command's use of the AFS command parser, and is optional.
-
-=item B<-cmname> <I<cache manager name to monitor>>+
-
-Specifies the fully qualified hostname of each client machine for which to
-monitor the Cache Manager.
-
-=item B<-collID> <I<collection to fetch>>+
-
-Specifies each data collection to return, which defines the type and
-amount of data the command interpreter gathers about the Cache Manager.
-Data is returned in a predefined data structure.
-
-There are three acceptable values:
-
-=over 4
-
-=item 0
-
-Provides profiling information about the numbers of times different
-internal Cache Manager routines were called since the Cache Manager
-started.
-
-=item 1
-
-Reports various internal performance statistics related to the Cache
-Manager (for example, statistics about how effectively the cache is being
-used and the quantity of intracell and intercell data access).
-
-=item 2
-
-Reports all of the internal performance statistics provided by the C<1>
-setting, plus some additional, detailed performance figures (for example,
-statistics about the number of RPCs sent by the Cache Manager and how long
-they take to complete, and statistics regarding authentication, access,
-and PAG information associated with data access).
-
-=back
-
-=item B<-onceonly>
-
-Gathers statistics just one time. Omit this flag to have the command
-continue to probe the Cache Manager for statistics at the frequency
-specified by the B<-frequency> argument; in this case press Ctrl-C to stop
-the probes.
-
-=item B<-frequency> <I<poll frequency>>
-
-Sets the frequency in seconds at which the program initiates probes to the
-Cache Manager. The default is 30 seconds.
-
-=item B<-period> <I<data collection time>>
-
-Sets the number of minutes the program runs; at the end of this period of
-time, the program exits. The default is 10 minutes.
-
-=item B<-debug>
-
-Displays a trace on the standard output stream as the command runs.
-
-=item B<-help>
-
-Prints the online help for this command. All other valid options are
-ignored.
-
-=back
-
-=head1 SEE ALSO
-
-L<xstat_fs_test(1)>
-
-=head1 COPYRIGHT
-
-IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
-
-This documentation is covered by the IBM Public License Version 1.0. It was
-converted from HTML to POD by software written by Chas Williams and Russ
-Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
+++ /dev/null
-=head1 NAME
-
-xstat_fs_test - Displays data collections from the File Server process
-
-=head1 SYNOPSIS
-
-=for html
-<div class="synopsis">
-
-B<xstat_fs_test> [I<initcmd>] S<<< B<-fsname> <I<file server name(s) to monitor>>+ >>>
- S<<< B<-collID> <I<collection(s) to fetch>>+ >>> [B<-onceonly>]
- S<<< [B<-frequency> <I<poll frequency, in seconds>>] >>>
- S<<< [B<-period> <I<data collection time, in minutes>>] >>> [B<-debug>] [B<-help>]
-
-B<xstat_fs_test> [B<initcmd>] S<<< B<-fs> <I<File Server name(s) to monitor>>+ >>>
- S<<< B<-c> <I<Collection(s) to fetch>>+ >>> [B<-o>]
- S<<< [B<-fr> <I<poll frequency, in seconds>>] >>>
- S<<< [B<-p> <I<data collection time, in minutes>>] >>> [B<-d>] [B<-h>]
-
-=for html
-</div>
-
-=head1 DESCRIPTION
-
-The B<xstat_fs_test> command tests the routines in the F<libxstat_fs.a>
-library and displays the data collections associated with the File Server
-(the C<fs> process). The command executes in the foreground.
-
-The command produces a large volume of output; to save it for later
-analysis, direct it to a file.
-
-=head1 OPTIONS
-
-=over 4
-
-=item I<initcmd>
-
-Accommodates the command's use of the AFS command parser, and is optional.
-
-=item B<-fsname> <I<file server name to monitor>>+
-
-Specifies the fully qualified hostname of each file server machine for
-which to monitor the File Server process.
-
-=item B<-collID> <I<collection to fetch>>+
-
-Specifies each data collection to return, which defines the type and
-amount of data the command interpreter gathers about the File Server.
-Data is returned in a predefined data structure.
-
-There are three acceptable values:
-
-=over 4
-
-=item 0
-
-Provides profiling information about the numbers of times different
-internal File Server routines were called since the File Server
-started. This value is not currently implemented; it returns no data.
-
-=item 1
-
-Reports various internal performance statistics related to the File Server
-(for example, vnode cache entries and Rx protocol activity).
-
-=item 2
-
-Reports all of the internal performance statistics provided by the C<1>
-setting, plus some additional, detailed performance figures about the File
-Server (for example, minimum, maximum, and cumulative statistics regarding
-File Server RPCs, how long they take to complete, and how many succeed).
-
-=back
-
-=item B<-onceonly>
-
-Gathers statistics just one time. Omit this flag to have the command
-continue to probe the Cache Manager for statistics at the frequency
-specified by the B<-frequency> argument; in this case press Ctrl-C to stop
-the probes.
-
-=item B<-frequency> <I<poll frequency>>
-
-Sets the frequency in seconds at which the program initiates probes to the
-Cache Manager. The default is 30 seconds.
-
-=item B<-period> <I<data collection time>>
-
-Sets the number of minutes the program runs; at the end of this period of
-time, the program exits. The default is 10 minutes.
-
-=item B<-debug>
-
-Displays a trace on the standard output stream as the command runs.
-
-=item B<-help>
-
-Prints the online help for this command. All other valid options are
-ignored.
-
-=back
-
-=head1 SEE ALSO
-
-L<xstat_cm_test(1)>
-
-=head1 COPYRIGHT
-
-IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
-
-This documentation is covered by the IBM Public License Version 1.0. It was
-converted from HTML to POD by software written by Chas Williams and Russ
-Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
+++ /dev/null
-=head1 NAME
-
-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/lib/*.a usr/lib
debian/tmp/usr/lib/afs usr/lib
-debian/doc/man1/rxgen.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/rxgen.1 usr/share/man/man1
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/man1/xstat_cm_test.1 usr/share/man/man1
-debian/doc/man1/xstat_fs_test.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/afs.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/afsmonitor.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/cmdebug.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/fs.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/fs_apropos.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/fs_checkservers.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/fs_checkvolumes.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/fs_cleanacl.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/fs_copyacl.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/fs_diskfree.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/fs_examine.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/fs_exportafs.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/fs_flush.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/fs_flushmount.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/fs_flushvolume.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/fs_getcacheparms.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/fs_getcellstatus.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/fs_getclientaddrs.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/fs_getserverprefs.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/fs_help.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/fs_listacl.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/fs_listcells.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/fs_listquota.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/fs_lsmount.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/fs_messages.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/fs_mkmount.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/fs_newcell.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/fs_quota.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/fs_rmmount.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/fs_setacl.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/fs_setcachesize.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/fs_setcell.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/fs_setclientaddrs.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/fs_setquota.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/fs_setserverprefs.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/fs_setvol.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/fs_storebehind.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/fs_sysname.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/fs_whereis.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/fs_whichcell.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/fs_wscell.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/klog.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/livesys.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/pagsh.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/pts.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/pts_adduser.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/pts_apropos.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/pts_chown.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/pts_creategroup.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/pts_createuser.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/pts_delete.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/pts_examine.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/pts_help.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/pts_listentries.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/pts_listmax.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/pts_listowned.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/pts_membership.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/pts_removeuser.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/pts_rename.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/pts_setfields.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/pts_setmax.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/rxdebug.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/scout.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/sys.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/tokens.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/translate_et.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/udebug.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/unlog.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/up.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/vos.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/vos_addsite.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/vos_apropos.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/vos_backup.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/vos_backupsys.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/vos_changeaddr.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/vos_create.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/vos_delentry.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/vos_dump.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/vos_examine.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/vos_help.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/vos_listaddrs.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/vos_listpart.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/vos_listvldb.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/vos_listvol.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/vos_lock.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/vos_move.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/vos_partinfo.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/vos_release.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/vos_remove.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/vos_remsite.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/vos_rename.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/vos_restore.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/vos_status.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/vos_syncserv.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/vos_syncvldb.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/vos_unlock.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/vos_unlockvldb.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/vos_zap.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/xstat_cm_test.1 usr/share/man/man1
+debian/tmp/usr/share/man/man1/xstat_fs_test.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/tmp/usr/share/man/man5/CellServDB.5 usr/share/man/man5
+debian/tmp/usr/share/man/man5/NetInfo.5 usr/share/man/man5
+debian/tmp/usr/share/man/man5/NetRestrict.5 usr/share/man/man5
+debian/tmp/usr/share/man/man5/ThisCell.5 usr/share/man/man5
+debian/tmp/usr/share/man/man5/afs.5 usr/share/man/man5
+debian/tmp/usr/share/man/man5/afs_cache.5 usr/share/man/man5
+debian/tmp/usr/share/man/man5/afsmonitor.5 usr/share/man/man5
+debian/tmp/usr/share/man/man5/afszcm.cat.5 usr/share/man/man5
+debian/tmp/usr/share/man/man5/butc.5 usr/share/man/man5
+debian/tmp/usr/share/man/man5/butc_logs.5 usr/share/man/man5
+debian/tmp/usr/share/man/man5/cacheinfo.5 usr/share/man/man5
+debian/tmp/usr/share/man/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
+debian/tmp/usr/share/man/man8/afsd.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/backup.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/backup_adddump.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/backup_addhost.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/backup_addvolentry.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/backup_addvolset.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/backup_apropos.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/backup_dbverify.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/backup_deldump.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/backup_deletedump.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/backup_delhost.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/backup_delvolentry.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/backup_delvolset.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/backup_diskrestore.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/backup_dump.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/backup_dumpinfo.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/backup_help.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/backup_interactive.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/backup_jobs.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/backup_kill.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/backup_labeltape.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/backup_listdumps.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/backup_listhosts.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/backup_listvolsets.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/backup_quit.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/backup_readlabel.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/backup_restoredb.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/backup_savedb.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/backup_scantape.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/backup_setexp.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/backup_status.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/backup_volinfo.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/backup_volrestore.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/backup_volsetrestore.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/bos.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/bos_addhost.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/bos_addkey.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/bos_adduser.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/bos_apropos.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/bos_create.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/bos_delete.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/bos_exec.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/bos_getdate.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/bos_getlog.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/bos_getrestart.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/bos_help.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/bos_install.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/bos_listhosts.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/bos_listkeys.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/bos_listusers.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/bos_prune.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/bos_removehost.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/bos_removekey.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/bos_removeuser.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/bos_restart.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/bos_salvage.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/bos_setauth.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/bos_setcellname.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/bos_setrestart.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/bos_shutdown.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/bos_start.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/bos_startup.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/bos_status.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/bos_stop.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/bos_uninstall.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/butc.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/fms.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/fstrace.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/fstrace_apropos.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/fstrace_clear.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/fstrace_dump.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/fstrace_help.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/fstrace_lslog.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/fstrace_lsset.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/fstrace_setlog.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/fstrace_setset.8 usr/share/man/man8
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/tmp/usr/share/man/man5/BackupLog.5 usr/share/man/man5
+debian/tmp/usr/share/man/man5/VLLog.5 usr/share/man/man5
+debian/tmp/usr/share/man/man5/bdb.DB0.5 usr/share/man/man5
+debian/tmp/usr/share/man/man5/prdb.DB0.5 usr/share/man/man5
+debian/tmp/usr/share/man/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/share/man/man8/buserver.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/prdb_check.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/ptserver.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/vldb_check.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/vlserver.8 usr/share/man/man8
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/tmp/usr/share/man/man5/BosConfig.5 usr/share/man/man5
+debian/tmp/usr/share/man/man5/BosLog.5 usr/share/man/man5
+debian/tmp/usr/share/man/man5/FORCESALVAGE.5 usr/share/man/man5
+debian/tmp/usr/share/man/man5/FileLog.5 usr/share/man/man5
+debian/tmp/usr/share/man/man5/KeyFile.5 usr/share/man/man5
+debian/tmp/usr/share/man/man5/NoAuth.5 usr/share/man/man5
+debian/tmp/usr/share/man/man5/SALVAGE.fs.5 usr/share/man/man5
+debian/tmp/usr/share/man/man5/SalvageLog.5 usr/share/man/man5
+debian/tmp/usr/share/man/man5/VolserLog.5 usr/share/man/man5
+debian/tmp/usr/share/man/man5/afs_volume_header.5 usr/share/man/man5
+debian/tmp/usr/share/man/man5/salvage.lock.5 usr/share/man/man5
+debian/tmp/usr/share/man/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/share/man/man8/bosserver.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/fileserver.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/salvager.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/upclient.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/upserver.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/voldump.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/volinfo.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/volserver.8 usr/share/man/man8
debian/tmp/usr/sbin/kas usr/bin
-debian/doc/man1/kpasswd.1 usr/share/man/man1
+debian/tmp/usr/share/man/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
+debian/tmp/usr/share/man/man8/kas.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/kas_apropos.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/kas_create.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/kas_delete.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/kas_examine.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/kas_forgetticket.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/kas_help.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/kas_interactive.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/kas_list.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/kas_listtickets.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/kas_noauthentication.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/kas_quit.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/kas_setfields.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/kas_setpassword.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/kas_statistics.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/kas_stringtokey.8 usr/share/man/man8
+debian/tmp/usr/share/man/man8/kas_unlock.8 usr/share/man/man8
# This has to be exported to make some magic below work.
export DH_OPTIONS
+# Tell Autoconf the correct system types.
+DEB_HOST_GNU_TYPE ?= $(shell dpkg-architecture -qDEB_HOST_GNU_TYPE)
+DEB_BUILD_GNU_TYPE ?= $(shell dpkg-architecture -qDEB_BUILD_GNU_TYPE)
+ifeq ($(DEB_BUILD_GNU_TYPE),$(DEB_HOST_GNU_TYPE))
+ SYSTEM = --build $(DEB_HOST_GNU_TYPE)
+else
+ SYSTEM = --build $(DEB_BUILD_GNU_TYPE) --host $(DEB_HOST_GNU_TYPE)
+endif
+
+# Determine whether we're building with optimization. This doesn't really
+# work at the moment due to upstream problems.
ifneq (,$(findstring noopt,$(DEB_BUILD_OPTIONS)))
DEBIAN_OPT_FLAGS = --disable-optimize --disable-lwp-optimize
DEBIAN_KERN_FLAGS = --disable-kernel-optimize
DEBIAN_KERN_FLAGS =
endif
+# Find kernel build information.
ifndef KSRC
KSRC = /usr/src/linux
endif
afslogsdir=/var/log/openafs afslocaldir=/etc/openafs/server-local \
sh configure \
--with-afs-sysname=$(SYS_NAME) --disable-kernel-module \
- --prefix=/usr --sysconfdir=/etc --libexecdir=/usr/lib \
+ --prefix=/usr --mandir=\$${prefix}/share/man \
+ --sysconfdir=/etc --libexecdir=/usr/lib \
--localstatedir=/var/lib --enable-supergroups \
--enable-largefile-fileserver --enable-debug --enable-lwp-debug \
- $(DEBIAN_OPT_FLAGS)
+ $(DEBIAN_OPT_FLAGS) $(SYSTEM)
chmod a+x src/libafs/make_kbuild_makefile.pl
touch configure-stamp
dh_testdir
mkdir -p $(CURDIR)/debian/tmp
$(MAKE) install_nolibafs DESTDIR=$(CURDIR)/debian/tmp
- chmod +x debian/afs-rootvol debian/afs-newcell debian/doc/build-man
- cd debian/doc && ./build-man
+ chmod +x debian/afs-rootvol debian/afs-newcell
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=
projects / packages / o / openafs.git / commitdiff