$command =~ s/^L<//;
$command =~ s/\(1\)>$//;
} elsif ($lasttag eq "strong") {
- if ($buffer eq 'Cautions') {
- $buffer = 'CAVEATS';
- } elsif ($buffer eq 'Related Information') {
+ if ($buffer eq 'Related Information') {
$buffer = 'SEE ALSO';
} else {
$buffer = uc $buffer;
# Fix up a few last things.
$result =~ s/L<(\S+) (\S+\(1\))>/L<${1}_${2}>/g;
-$result =~ s/^(L<\S+>)\n\n(?=L<)/$1,\n/mg;
-$result =~ s/^(\S+[^\n]+)\n +/$1\n/mg;
+$result =~ s/^(L<[^>]+>)\n\n(?=L<)/$1,\n/mg;
$result =~ s/^(\s+.*)B<([^>]+)>/$1$2/mg;
# Append a stock copyright statement.
=head1 NAME
-afs_intro - Introduction to AFS commands
+afs - Introduction to AFS commands
=head1 DESCRIPTION
=item backup
-Interface for configuring and operating the AFS Backup System
+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
+processes and configuration files.
=item fs
Interface for administering access control lists (ACLs), the Cache
-Manager, and other miscellaneous file system functions
+Manager, and other miscellaneous file system functions.
=item fstrace
-Interface for tracing Cache Manager operations when debugging problems
+Interface for tracing Cache Manager operations when debugging problems.
=item kas
Interface to the Authentication Server for administering security and
-authentication information
+authentication information.
=item pts
Interface to the Protection Server for administering AFS ID and group
-membership information
+membership information.
=item uss
-Interface for automated administration of user accounts
+Interface for automated administration of user accounts.
=item vos
Interface to the Volume Server and Volume Location (VL) Server for
-administering volumes
+administering volumes.
=back
In addition, there are several commands that do not belong to
suites.
-=head2
+=head2 AFS Command Syntax
-AFS commands that belong to suites have the following
-structure:
+AFS commands that belong to suites have the following structure:
- B<command_suite operation_code> B<-switch> <I<value>>[+] [-flag]
+I<command_suite> I<operation_code> B<-switch> <I<value>>[+] [B<-flag>]
-=head3
+=head3 Command Names
-Together, the B<command_suite> and operation_code
-make up the I<command name>.
+Together, the I<command_suite> and I<operation_code> make up the I<command
+name>.
-The 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<scout>, B<uss> and B<vos>.
-Some of these suites have an interactive mode in which the issuer omits the
-B<command_suite> portion of the 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 operation_code tells the command interpreter and server
-process which action to perform. Most command suites include several
-operation codes. The I<IBM AFS Administration Reference>
-describes each operation code in detail, and the I<IBM AFS Administration
-Guide> describes how to use them in the context of performing
-administrative tasks.
+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 B<command_suite> portion. Their structure is otherwise
-similar to the commands in the suites.
+have a I<command_suite> portion. Their structure is otherwise similar to
+the commands in the suites.
-=head3
+=head3 Options
-The term I<option> refers to both arguments and flags, which
-are described in the following sections.
+The term I<option> refers to both arguments and flags, which are described
+in the following sections.
-=head3
+=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.
+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:
=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(1)>.
-
+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
-B<fs3.abc.com>. Unlike switches (which have a
+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 (B<<
->>) in command descriptions and the online help to show that they are
+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 (
-B<+> ) 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(1)>.
+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 ([
-]).
+descriptions and online help show optional arguments in square brackets
+(C<[]>).
-=head3
+=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
+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
+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
+=head3 An Example Command
-The following example illustrates the different parts
-of a command that belongs to an AFS command suite.
+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
=item *
-bos is the command suite. The BOS Server executes most
-of the commands in this suite.
-
+B<bos> is the command suite. The BOS Server executes most of the commands
+in this suite.
=item *
-getdate is the operation code. It tells the BOS Server
-on the specified server machine (in this case
-B<fs1.abc.com>) to report the modification dates of
-binary files in the local B</usr/afs/bin> directory.
-
+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 *
--server fs1.abc.com is one argument, with
-B<-server> as the switch and B<fs1.abc.com> as
-the value. This argument specifies the server machine on which BOS
-Server is to collect and report binary dates.
-
+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 *
--file ptserver kaserver is an argument that takes multiple
-values. The switch is B<-file> and the values are
-B<ptserver> and B<kaserver>. This argument tells the
-BOS Server to report the modification dates on the files
-B</usr/afs/bin/kaserver> and B</usr/afs/bin/ptserver>.
-
+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
+=head3 Rules for Entering AFS Commands
-Enter each AFS command on a single line (press
-B<<Return>> only at the end of the command). Some commands
-in this document appear broken across multiple lines, but that is for
-legibility only.
+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.
+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:
=item *
-Omitting switches
-
+Omitting switches.
=item *
Using accepted abbreviations for operation codes, switches (if they are
-included at all), and some types of values
-
+included at all), and some types of values.
=back
parts of the command line. It is always acceptable to type a command in
full, with all of its switches and no abbreviations.
-I<L<Conditions for Omitting Switches(1): >>
-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.
+=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
-
+All of the command's required arguments appear in the order prescribed by
+the syntax statement.
=item *
-No switch is provided for any argument
-
+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)
-
+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.
+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.
+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
-
+The command's arguments do not appear in the prescribed order.
=item *
An optional argument is omitted but a subsequent optional argument is
-provided
-
+provided.
=item *
-A switch is provided for a preceding argument
-
+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
-
+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
-I<L<An Example of Omitting Switches(1): >>
-Consider again the example command from L<An Example Command(1)>.
+=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
+ % 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:
+(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, B<fs1.abc.com>, is the
-server machine name, and that the next argument, B<ptserver>, is a
-binary file name. Then, because the command's second (and last)
-argument accepts multiple values, the command interpreter correctly interprets
-B<kaserver> as an additional value for it.
+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(1)>: 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.
+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
-
-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.
-
-I<L<Abbreviating Operation Codes(1): >>
-It is acceptable to abbreviate an operation code to the shortest form
-that still distinguishes it from the other operation codes in its
-suite.
+=head3 Rules for Using Abbreviations and Aliases
-For example, it is acceptable to shorten B<bos install> to bos
-i because there are no other operation codes in the B<bos>
-command suite that begin with the letter B<i>. In contrast,
-there are several B<bos> operation codes that start with the letter
-B<s>, so the abbreviations must be longer to remain unambiguous:
+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.
-=over 4
-
-
-B<bos sa> for bos salvage
-
-
-B<bos seta> for bos setauth
+=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.
-B<bos setc> for bos setcellname
-
-
-B<bos setr> for bos setrestart
+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
-B<bos sh> for bos shutdown
+=item B<bos sa> for bos salvage
+=item B<bos seta> for bos setauth
-B<bos start> for bos start
+=item B<bos setc> for bos setcellname
+=item B<bos setr> for bos setrestart
-B<bos startu> for bos startup
+=item B<bos sh> for bos shutdown
+=item B<bos start> for bos start
-B<bos stat> for bos status
+=item B<bos startu> for bos startup
+=item B<bos stat> for bos status
-B<bos sto> for bos stop
+=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>.
+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:
=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.
-
+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>).
-
+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).
+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
-I<L<Abbreviating Switches and Flags(1): >>
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(1)>.
+conditions listed in L<"Conditions for Omitting Switches">.
+
+=head4 Abbreviating Server Machine Names
-I<L<Abbreviating Server Machine Names(1): >>
-AFS server machines must have fully-qualified
-Internet-style host names (for example, B<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.
+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.
-I<L<Abbreviating Partition Names(1): >>
-Partitions that house AFS volumes must have names of
-the form B</vicep>I<x> or B</vicep>I<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 B</vicepa>, the second B</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.
+=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:
+When issuing AFS commands, you can abbreviate a partition name using any
+of the following forms:
- B</vicepa> = B<vicepa> = B<a> = 0
- B</vicepb> = B<vicepb> = B<b> = 1
+ /vicepa = vicepa = a = 0
+ /vicepb = vicepb = b = 1
After /vicepz (for which the index is 25) comes
- B</vicepaa> = B<vicepaa> = B<aa> = 26
- B</vicepab> = B<vicepab> = B<ab> = 27
+ /vicepaa = vicepaa = aa = 26
+ /vicepab = vicepab = ab = 27
and so on through
- B</vicepiv> = B<vicepiv> = B<iv> = 255
+ /vicepiv = vicepiv = iv = 255
-I<L<Abbreviating Cell Names(1): >>
-A cell's full name usually matches its Internet
-domain name (such as B<stateu.edu> for the State University or
-B<abc.com> for ABC Corporation). Some AFS commands
-accept unambiguous shortened forms, usually with respect to the local
-B</usr/vice/etc/CellServDB file> but sometimes depending on the
-ability of the local name service to resolve the corresponding domain
-name.
+=head4 Abbreviating Cell Names
-=head3
+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.
-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.
+=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:
=item *
-The first line names the command and briefly describes what it does
-
+The first line names the command and briefly describes what it does.
=item *
-If the command has aliases, they appear on the next line
-
+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.
-
+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 help operation code
-displays the first line (short description) for every operation code in the
-suite:
+If no operation code is specified, the B<help> operation code displays the
+first line (short description) for every operation code in the suite:
-
- % I<command_suite> help
+ % <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):
-If the issuer specifies one or more operation codes, the 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:
- % I<command_suite> help I<operation_code>+
-
+ % <command_name> -help
-The -help flag displays a command's syntax but not the
-short description or alias:
-
- % I<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
+The apropos operation code displays the short description of any command
+in a suite whose operation code or short description includes the
specified keyword:
- % I<command_suite> apropos I<"<help string>">
+ % <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 -help flag:
+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:
-
+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:
+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
=over 4
-
-L<afsd(1)>
-
-
-L<afsmonitor(1)>
-
-
-L<backup(1)>
-
-
-L<bos(1)>
-
-
-L<bosserver(1)>
-
-
-L<buserver(1)>
-
-
-L<butc(1)>
-
-
-L<dlog(1)>
-
-
-L<dpass(1)>
-
-
-L<fileserver(1)>
-
-
-L<fms(1)>
-
-
-L<fs(1)>
-
-
-L<fstrace(1)>
-
-
-L<ftpd (AFS version)(1)>
-
-
-L<inetd (AFS version)(1)>
-
-
-L<kadb_check(1)>
-
-
-L<kas(1)>
-
-
-L<kaserver(1)>
-
-
-L<kdb(1)>
-
-
-L<klog(1)>
-
-
-L<knfs(1)>
-
-
-L<kpasswd(1)>
-
-
-L<kpwvalid(1)>
-
-
-L<package(1)>
-
-
-L<package(1)>
-
-
-L<package_test(1)>
-
-
-L<pagsh(1)>
-
-
-L<prdb_check(1)>
-
-
-L<pts(1)>
-
-
-L<ptserver(1)>
-
-
-L<rcp (AFS version)(1)>
-
-
-L<rsh (AFS version)(1)>
-
-
-L<runntp(1)>
-
-
-L<rxdebug(1)>
-
-
-L<salvager(1)>
-
-
-L<scout(1)>
-
-
-L<sys(1)>
-
-
-L<tokens(1)>
-
-
-L<translate_et(1)>
-
-
-L<unlog(1)>
-
-
-L<up(1)>
-
-
-L<upclient(1)>
-
-
-L<upserver(1)>
-
-
-L<uss(1)>
-
-
-L<vldb_check(1)>
-
-
-L<vlserver(1)>
-
-
-L<volinfo(1)>
-
-
-L<volserver(1)>
-
-
-L<vos(1)>
-
-
-L<xfs_size_check(1)>
-
-
-L<xstat_cm_test(1)>
-
-
-L<xstat_fs_test(1)>
+L<afsd(8)>,
+L<afsmonitor(1)>,
+L<backup(8)>,
+L<bos(8)>,
+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 DESCRIPTION
-B<afsmonitor> [B<initcmd>] [-config <I<configuration file>>]
-[B<-frequency> <I<poll frequency, in seconds>>]
- [B<-output> <I<storage file name>>] [-detailed]
- [-debug <I<turn debugging output on to the named file>>]
- [-fshosts <I<list of file servers to monitor>>+]
- [-cmhosts <I<list of cache managers to monitor>>+]
- [B<-buffers> <I<number of buffer slots>>] [-help]
+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>>] [-det]
- [-deb <I<turn debugging output on to the named file>>]
- [-fs <I<list of file servers to monitor>>+]
- [-cm <I<list of cache managers to monitor>>+]
- [B<-b> <I<number of buffer slots>>] [-h]
+
[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.
+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:
+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.
-
+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.
-
+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 the afsmonitor
-Configuration File reference page
+For a description of the configuration file, see L<afsmonitor(5)>.
-=head1 CAVEATS
+=head1 CAUTIONS
The following software must be accessible to a machine where the
B<afsmonitor> program is running:
=item *
-The AFS B<xstat> libraries, which the afsmonitor
-program uses to gather data
-
+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
-
+The curses graphics package, which most UNIX distributions provide as a
+standard utility.
=back
-The 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.
-L<(1)>
-L<(1)>
-L<(1)>
-
-The 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.
+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 initcmd
+=item B<initcmd>
-Accommodates the command's use of the AFS command parser, and is
-optional.
+Accommodates the command's use of the AFS command parser, and is optional.
-=item -config
+=item B<-config> <I<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>.
+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 -frequency
+=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
-B<1> to B<86400> (which is 24 hours); the default value
-is B<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.
+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 -output
+=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.
+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 -detailed
+=item B<-detailed>
-Formats the information in the output file named by -output
-argument in a maximally readable format. Provide the B<-output>
-argument along with this one.
+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 -fshosts
+=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.
+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 -cmhosts
+=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.
+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 -buffers
+=item B<-buffers> <I<slots>>
Is nonoperational and provided to accommodate potential future
enhancements to the program.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=over 4
-=item *
-
-C<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 *
+=item System Overview
-C<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.
+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
-=item *
+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.
-C<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.
+=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:
+Fields at the corners of every screen display the following information:
=over 4
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.)
-
+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.
-
+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.
-
+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
-Navigating the afsmonitor Display Screens
+=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.
+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
->
+=item C<cm>
-Switches to the C<Cache Managers> screen. Available only on
-the C<System Overview> and C<File Servers> screens.
+Switches to the C<Cache Managers> screen. Available only on the C<System
+Overview> and C<File Servers> screens.
-=item C<fs
->
+=item C<fs>
-Switches to the C<File Servers> screen. Available only on
-the C<System Overview> and the C<Cache Managers>
-screens.
+Switches to the C<File Servers> screen. Available only on the C<System
+Overview> and the C<Cache Managers> screens.
-=item C<left
->
+=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
-B<L> to scroll horizontally all the way to the left (to display the
-first set of data columns).
+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
->
+=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 B<N> to scroll to the
-final page.
+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
->
+=item C<oview>
-Switches to the C<System Overview> screen. Available only
-on the C<Cache Managers> and C<File Servers> screens.
+Switches to the C<System Overview> screen. Available only on the C<Cache
+Managers> and C<File Servers> screens.
-=item C<prev
->
+=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 B<N> to scroll to the
-first page.
+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
->
+=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 B<R> to scroll horizontally all the way to the right (to
-display the final set of data columns).
+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
-The System Overview Screen
+=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 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
+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
-
+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)
-
+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.
+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.
-The File Servers Screen
+=head2 The File Servers Screen
-The C<File Servers> screen displays the values collected at the
-most recent probe for File Server statistics.
+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
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.
+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.
-The Cache Managers Screen
+=head2 The Cache Managers Screen
-The C<Cache Managers> screen displays the values collected at the
-most recent probe for Cache Manager statistics.
+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
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.
-
-Writing to an Output File
-
-Include the -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
+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.
+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.
- I<time> I<host_name> CM|FS I<statistic>
+ <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.
+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
+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
=head1 SEE ALSO
-L<afsmonitor Configuration File(1)>
-
-L<fstrace(1)>,
+L<afsmonitor(5)>
+L<fstrace(8)>,
L<scout(1)>
=head1 COPYRIGHT
=head1 SYNOPSIS
-B<dlog> [B<-principal> <I<user name>>] [-cell <I<cell name>>]
-[B<-password> <I<user's password>>] [B<-servers> <I<explicit list of servers>>+]
- [-lifetime <I<ticket lifetime in hh[:mm[:ss]]>>]
- [B<-setpag>] [B<-pipe>] [-help]
-
-B<dlog> [B<-pr> <I<user name>>] [B<-c> <I<cell name>>] [-pw <I<user's password>>]
-[B<-ser> <I<explicit list of servers>>+]
- [B<-l> <I<ticket lifetime in hh[:mm[:ss]]>>] [B<-set>] [B<-pi>] [-h]
+B<dlog> [B<-principal> <I<user name>>] [B<-cell> <I<cell name>>]
+ [B<-password> <I<user's password>>]
+ [B<-servers> <I<explicit list of servers>>+]
+ [B<-lifetime> <I<ticket lifetime in hh[:mm[:ss]]>>]
+ [B<-setpag>] [B<-pipe>] [B<-help>]
+
+B<dlog> [B<-pr> <I<user name>>] [B<-c> <I<cell name>>]
+ [B<-pw> <I<user's password>>]
+ [B<-ser> <I<explicit list of servers>>+]
+ [B<-l> <I<ticket lifetime in hh[:mm[:ss]]>>]
+ [B<-set>] [B<-pi>] [B<-h>]
=head1 DESCRIPTION
-The dlog command obtains DCE credentials for the issuer from the
-DCE Security Service in the cell named by the B<-cell> argument, and
-stores them on the AFS client machine on which the user issues the
-command. The AFS/DFS Migration Toolkit Protocol Translator processes
-running on machines in the DCE cell accept the credentials, which enables the
-user to access the DCE cell's filespace from the AFS client. The
-user's identity in the local file system is unchanged.
-
-If the issuer does not provide the -principal argument, the
-B<dlog> command interpreter uses the user name under which the issuer
-is logged into the local file system. Provide the DCE password for the
-appropriate user name. As with the B<klog> command, the
-password does not cross the network in clear text (unless the issuer is logged
-into the AFS client from a remote machine).
+The B<dlog> command obtains DCE credentials for the issuer from the DCE
+Security Service in the cell named by the B<-cell> argument, and stores
+them on the AFS client machine on which the user issues the command. The
+AFS/DFS Migration Toolkit Protocol Translator processes running on
+machines in the DCE cell accept the credentials, which enables the user to
+access the DCE cell's filespace from the AFS client. The user's identity
+in the local file system is unchanged.
+
+If the issuer does not provide the B<-principal> argument, the B<dlog>
+command interpreter uses the user name under which the issuer is logged
+into the local file system. Provide the DCE password for the appropriate
+user name. As with the B<klog> command, the password does not cross the
+network in clear text (unless the issuer is logged into the AFS client
+from a remote machine).
The credentials are valid for a lifetime equivalent to the smallest of the
-following, all but the last of which is defined by the DCE cell's
-Security Server:
+following, all but the last of which is defined by the DCE cell's Security
+Server:
=over 4
=item *
-The maximum certificate lifetime for the issuer's DCE account
-
+The maximum certificate lifetime for the issuer's DCE account.
=item *
-The maximum certificate lifetime for the afs principal's
-DCE account
-
+The maximum certificate lifetime for the AFS principal's DCE account.
=item *
-The registry-wide maximum certificate lifetime
-
+The registry-wide maximum certificate lifetime.
=item *
-The registry-wide default certificate lifetime
-
+The registry-wide default certificate lifetime.
=item *
-The lifetime requested using the -lifetime argument
-
+The lifetime requested using the B<-lifetime> argument.
=back
If the previous maximum certificate lifetime values are set to
-B<default-policy>, the maximum possible ticket lifetime is defined by
-the default certificate lifetime. Refer to the DCE vendor's
-administration guide for more information before setting any of these
-values.
+C<default-policy>, the maximum possible ticket lifetime is defined by the
+default certificate lifetime. Refer to the DCE vendor's administration
+guide for more information before setting any of these values.
The AFS Cache Manager stores the ticket in a credential structure
associated with the name of the issuer (or the user named by the
-B<-principal> argument. If the user already has a ticket for
-the DCE cell, the ticket resulting from this command replaces it in the
-credential structure.
+B<-principal> argument. If the user already has a ticket for the DCE cell,
+the ticket resulting from this command replaces it in the credential
+structure.
-The AFS tokens command displays the ticket obtained by the
-B<dlog> command for the server principal B<afs>, regardless of
-the principal to which it is actually granted. Note that the
-B<tokens> command does not distinguish tickets for a DFSTM
-File Server from tickets for an AFS File Server.
+The AFS tokens command displays the ticket obtained by the B<dlog> command
+for the server principal C<afs>, regardless of the principal to which it
+is actually granted. Note that the B<tokens> command does not distinguish
+tickets for a DFSTM File Server from tickets for an AFS File Server.
=head1 OPTIONS
=over 4
-=item -principal
+=item B<-principal> <I<user name>>
-Specifies the DCE user name for which to obtain DCE credentials. If
-this option is omitted, the B<dlog> command interpreter uses the name
-under which the issuer is logged into the local file system.
+Specifies the DCE user name for which to obtain DCE credentials. If this
+option is omitted, the B<dlog> command interpreter uses the name under
+which the issuer is logged into the local file system.
-=item -cell
+=item B<-cell> <I<cell name>>
-Specifies the DCE cell in which to authenticate. During a single
-login session on a given machine, a user can authenticate in multiple cells
-simultaneously, but can have only one ticket at a time for each cell (that is,
-it is possible to authenticate under only one identity per cell per
+Specifies the DCE cell in which to authenticate. During a single login
+session on a given machine, a user can authenticate in multiple cells
+simultaneously, but can have only one ticket at a time for each cell (that
+is, it is possible to authenticate under only one identity per cell per
machine). It is legal to abbreviate the cell name to the shortest form
that distinguishes it from the other cells listed in the
-B</usr/vice/etc/CellServDB> file on the local client machine.
+F</usr/vice/etc/CellServDB> file on the local client machine.
-If the issuer does not provide the -cell argument, the
-B<dlog> command attempts to authenticate with the DCE Security Server
-for the cell defined by
+If the issuer does not provide the B<-cell> argument, the B<dlog> command
+attempts to authenticate with the DCE Security Server for the cell defined
+by
+
+=over 4
=item *
The value of the environment variable AFSCELL on the local AFS client
-machine, if defined. The issuer can set the AFSCELL environment
-variable to name the desired DCE cell.
-
+machine, if defined. The issuer can set the AFSCELL environment variable
+to name the desired DCE cell.
=item *
-The cell name in the /usr/vice/etc/ThisCell file on the local
-AFS client machine. The machine's administrator can place the
-desired DCE cell's name in the file.
+The cell name in the F</usr/vice/etc/ThisCell> file on the local AFS
+client machine. The machine's administrator can place the desired DCE
+cell's name in the file.
+=back
-=item -password
+=item B<-password> <I<user's password>>
Specifies the password for the issuer (or for the user named by the
-B<-principal> argument). Using this argument is not
-recommended, because it makes the password visible on the command line.
-If this argument is omitted, the command prompts for the password and does not
-echo it visibly.
+B<-principal> argument). Using this argument is not recommended, because
+it makes the password visible on the command line. If this argument is
+omitted, the command prompts for the password and does not echo it
+visibly.
-=item -servers
+=item B<-servers> <I<list of servers>>+
Specifies a list of DFS database server machines running the Translator
Server through which the AFS client machine can attempt to
-authenticate. Specify each server by hostname, shortened machine name,
-or IP address. If this argument is omitted, the B<dlog> command
-interpreter randomly selects a machine from the list of DFS Fileset Location
-(FL) Servers in the B</usr/vice/etc/CellServDB> file for the DCE cell
-specified by the B<-cell> argument. This argument is useful for
-testing when authentication seems to be failing on certain server
-machines.
-
-=item -lifetime
-
-Requests a ticket lifetime using the format
-I<hh>B<:>I<mm>[B<:>I<ss>]
-(hours, minutes, and optionally a number seconds between 00 and 59).
-For example, the value B<168:30> requests a ticket lifetime of 7
-days and 30 minutes, and B<96:00> requests a lifetime of 4
-days. Acceptable values range from B<00:05> (5 minutes)
-to B<720:00> (30 days). If this argument is not provided
-and no other determinants of ticket lifetime have been changed from their
-defaults, ticket lifetime is 10 hours.
+authenticate. Specify each server by hostname, shortened machine name, or
+IP address. If this argument is omitted, the B<dlog> command interpreter
+randomly selects a machine from the list of DFS Fileset Location (FL)
+Servers in the F</usr/vice/etc/CellServDB> file for the DCE cell specified
+by the B<-cell> argument. This argument is useful for testing when
+authentication seems to be failing on certain server machines.
+
+=item B<-lifetime> <I<ticket lifetime>>
+
+Requests a ticket lifetime using the format I<hh>B<:>I<mm>[B<:>I<ss>]
+(hours, minutes, and optionally a number seconds between 00 and 59). For
+example, the value C<168:30> requests a ticket lifetime of 7 days and 30
+minutes, and C<96:00> requests a lifetime of 4 days. Acceptable values
+range from C<00:05> (5 minutes) to C<720:00> (30 days). If this argument
+is not provided and no other determinants of ticket lifetime have been
+changed from their defaults, ticket lifetime is 10 hours.
The requested lifetime must be smaller than any of the DCE cell's
determinants for ticket lifetime; see the discussion in the preceding
B<Description> section.
-=item -setpag
+=item B<-setpag>
Creates a process authentication group (PAG) in which the newly created
ticket is placed. If this flag is omitted, the ticket is instead
associated with the issuers' local user ID (UID).
-=item -pipe
+=item B<-pipe>
Suppresses any prompts that the command interpreter otherwise produces,
-including the prompt for the issuer's password. Instead, the
-command interpreter accepts the password via the standard input stream.
+including the prompt for the issuer's password. Instead, the command
+interpreter accepts the password via the standard input stream.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=head1 EXAMPLES
-The following command authenticates the issuer as cell_admin in
-the B<dce.abc.com> cell.
+The following command authenticates the issuer as cell_admin in the
+C<dce.abc.com> cell.
% dlog -principal cell_admin -cell dce.abc.com
- Password: I<cell_admin's password>
+ Password: <cell_admin's password>
-In the following example, the issuer authenticates as cell_admin
-to the B<dce.abc.com> cell and request a ticket lifetime
-of 100 hours. The B<tokens> command confirms that the user
-obtained DCE credentials as the user B<cell_admin>: the AFS ID
-is equivalent to the UNIX ID of B<1> assigned to B<cell_admin>
-in B<dce.abc.com> cell's DCE registry.
+In the following example, the issuer authenticates as cell_admin to the
+C<dce.abc.com> cell and request a ticket lifetime of 100 hours. The
+B<tokens> command confirms that the user obtained DCE credentials as the
+user C<cell_admin>: the AFS ID is equivalent to the UNIX ID of C<1>
+assigned to C<cell_admin> in C<dce.abc.com> cell's DCE registry.
% dlog -principal cell_admin -cell dce.abc.com -lifetime 100
- Password: I<cell_admin's password>
+ Password: <cell_admin's password>
% tokens
Tokens held by the Cache Manager:
User's (AFS ID 4758) tokens for afs@abc.com [Expires Jul 2 13:14]
--End of list--
-
=head1 PRIVILEGE REQUIRED
=head1 SYNOPSIS
-B<dpass> [B<-cell> <I<original AFS cell name>>] [-help]
+B<dpass> [B<-cell> <I<original AFS cell name>>] [B<-help>]
-B<dpass> [B<-c> <I<original AFS cell name>>] [-h]
+B<dpass> [B<-c> <I<original AFS cell name>>] [B<-h>]
=head1 DESCRIPTION
-The dpass command returns the DCE password that an administrator
-assigned to the issuer when using the B<dm pass> command to migrate
-AFS user accounts into a DCE cell.
+The B<dpass> command returns the DCE password that an administrator
+assigned to the issuer when using the B<dm pass> command to migrate AFS
+user accounts into a DCE cell.
-The dpass command, issued on an AFS client, requests the
-issuer's new DCE password from the AFS cell specified with the
-B<-cell> argument.
+The B<dpass> command, issued on an AFS client, requests the issuer's new
+DCE password from the AFS cell specified with the B<-cell> argument.
The issuer must be authenticated as the AFS user whose AFS account was
moved into DCE, and be able to provide the user's AFS password when
=over 4
-=item -cell
+=item B<-cell> <I<cell name>>
Specifies the name of the AFS cell from which the AFS account was moved
into DCE and from which to fetch the new DCE password.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=head1 OUTPUT
-By default, the dpass command writes a message similar to the
-following to the standard output stream.
+By default, the dpass command writes a message similar to the following to
+the standard output stream.
Please read the following message before entering your password.
This program will display your new, temporary DCE password on your
- terminal, and you should change the assigned password as soon as
- possible (from a DCE client). The program assumes that the AFS cell
- uses the AFS Authentication Server and that an administrator used the
- utilities in the AFS/DFS Migration Toolkit to migrate the account from
- AFS to DCE. The password you enter should be the AFS password that was
- in effect when your DCE account was created; this is not necessarily
- the same password you have at the moment. The cell name (which you
- may override with a command line option), must be the name of the AFS
- cell from which the authentication information was taken.
-
+ terminal, and you should change the assigned password as soon as
+ possible (from a DCE client). The program assumes that the AFS cell
+ uses the AFS Authentication Server and that an administrator used the
+ utilities in the AFS/DFS Migration Toolkit to migrate the account from
+ AFS to DCE. The password you enter should be the AFS password that was
+ in effect when your DCE account was created; this is not necessarily
+ the same password you have at the moment. The cell name (which you may
+ override with a command line option), must be the name of the AFS cell
+ from which the authentication information was taken.
To suppress this message, set the DPASS_NO_MESSAGE environment
variable. It is then possible to substitute a customized message if
setenv DPASS_NO_MESSAGE
dpass $*
-After the standard or customized message, if any, the dpass
-command generates the following prompt for the original AFS password:
+After the standard or customized message, if any, the dpass command
+generates the following prompt for the original AFS password:
- Original password for AFS cell I<cell>:
+ Original password for AFS cell <cell>:
Re-enter password to verify:
If the AFS passwords match and are correct, the command reports the
temporary DCE password in the following message.
- The new DCE password is: I<Issuer's_temporary_DCE_password>
+ The new DCE password is: <Issuer's_temporary_DCE_password
=head1 EXAMPLES
The following example returns the DCE password of the issuer, whose AFS
-account is in the B<abc.com> cell. The DPASS_NO_MESSAGE
-variable has been set to suppress the standard message.
+account is in the C<abc.com> cell. The DPASS_NO_MESSAGE variable has been
+set to suppress the standard message.
% dpass
- Original password for AFS cell abc.com: I<Issuer's_AFS_password>
- Re-enter password to verify: I<Issuer's_AFS_password>
+ Original password for AFS cell abc.com: <Issuer's_AFS_password>
+ Re-enter password to verify: <Issuer's_AFS_password>
The new DCE password is: 8655--eg8e-dcdc-8157
=head1 PRIVILEGE REQUIRED
L<dlog(1)>
-dm pass reference page in I<IBM AFS/DFS Migration Toolkit
+B<dm pass> reference page in I<IBM AFS/DFS Migration Toolkit
Administration Guide and Reference>
=head1 COPYRIGHT
=head1 DESCRIPTION
-The commands in the 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
+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 fs command
-suite:
+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 fs
-wscell
+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): fs
-cleanacl, B<fs copyacl>, B<fs listacl>, and B<fs
-setacl>
-
+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 fs whichcell
+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>
-
+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: fs lsmount,
-B<fs mkmount>, and B<fs rmmount>
-
+Commands to administer volume mount points: B<fs lsmount>, B<fs mkmount>,
+and B<fs rmmount>.
=item *
-Commands to control monitoring and tracing: fs debug, and
-B<fs messages>
-
+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>
-
+file systems: B<fs exportafs>.
=item *
-Commands to obtain help: B<fs apropos> and fs
-help
-
+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:
+The Cache Manager and the fs commands use and maintain the following
+configuration files:
=over 4
-=item *
-
-The /usr/vice/etc/CellServDB file 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
-B<root.cell> volume must also be mounted in the local
-cell's AFS file tree.
-
-
-=item *
+=item F</usr/vice/etc/CellServDB>
-The /usr/vice/etc/ThisCell file defines the machine's cell
-membership with respect to the AFS command suites and Cache Manager access to
-AFS data.
+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>
-=item *
+Defines the machine's cell membership with respect to the AFS command
+suites and Cache Manager access to AFS data.
-The /usr/vice/etc/cacheinfo file defines configuration
-parameters for the cache, including its size and whether it is in memory or on
-disk.
+=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, B</usr/vice/cache> for caching and tracking
-files fetched from file server machines.
+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.
-L<(1)>
-L<(1)>
-L<(1)>
+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 -help
+=item B<-help>
-Prints a command's online help message on the standard output
-stream. Do not combine this flag with any of the command's other
-options; when it is provided, the command interpreter ignores all other
-options, and only prints the help message.
+Prints a command's online help message on the standard output stream. Do
+not combine this flag with any of the command's other options; when it is
+provided, the command interpreter ignores all other options, and only
+prints the help message.
=back
=head1 PRIVILEGE REQUIRED
-The privileges required for fs commands vary more than for other
-command suites. Pay special attention to the B<Privilege
-Required> section of each command description.
+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:
=item *
-Having permissions on a directory's ACL. For example, creating
-and removing mount points requires B<a> (B<administer>),
-B<i> (B<insert>), and B<d> (B<delete>)
-permissions on the ACL of the directory in which the mount point
+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
-B<root>. This is necessary when issuing commands that affect
-Cache Manager configuration.
-
+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.
-
+Belonging to the system:administrators group in the Protection Database.
=item *
-No privilege. Many fs commands simply list
-information.
-
+No privilege. Many B<fs> commands simply list information.
=back
=head1 SEE ALSO
-L<CacheItems(1)>,
-L<CellServDB (client version)(1)>
-
-L<ThisCell (client version)(1)>
-
-L<VI<n>(1)>,
-L<VolumeItems(1)>,
-L<cacheinfo(1)>,
+L<CacheItems(5)>,
+L<CellServDB(5)>,
+L<ThisCell(5)>
+L<VolumeItems(5)>,
+L<cacheinfo(5)>,
L<fs_apropos(1)>,
L<fs_checkservers(1)>,
L<fs_checkvolumes(1)>,
=head1 SYNOPSIS
-B<fs apropos -topic> <I<help string>> [-help]
+B<fs apropos> B<-topic> <I<help string>> [B<-help>]
-B<fs ap -t> <I<help string>> [-h]
+B<fs ap> B<-t> <I<help string>> [B<-h>]
=head1 DESCRIPTION
-The 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.
+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 fs help
-command.
+To display the syntax for a command, use the B<fs help> command.
=head1 OPTIONS
=over 4
-=item -topic
+=item B<-topic> <I<help string>>
-Specifies the keyword string to match, in lowercase letters only.
-If the string is more than a single word, surround it with double quotes ("")
-or other delimiters.
+Specifies the keyword string to match, in lowercase letters only. If the
+string is more than a single word, surround it with double quotes ("") or
+other delimiters.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=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.
+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 B<cache> in their names or short online descriptions:
+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
=head1 SYNOPSIS
-B<fs checkservers> [B<-cell> <I<cell to check>>] [B<-all>] [-fast]
-[B<-interval> <I<seconds between probes>>] [B<-help>]
+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>] [-f]
-[B<-i> <I<seconds between probes>>] [B<-h>]
+B<fs checks> [B<-c> <I<cell to check>>] [B<-a>] [B<-f>]
+ [B<-i> <I<seconds between probes>>] [B<-h>]
=head1 DESCRIPTION
-The 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:
+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
-B</usr/vice/etc/CellServDB file>, plus any machines added to the
-memory list by the B<fs newcell> command since the last reboot.
-
+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 *
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.
+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 fs checkservers command updates the list of inaccessible
-machines by having the Cache Manager probe a specified set of them:
+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 B</usr/vice/etc/ThisCell>
-file)
-
+local cell (the cell listed in the local F</usr/vice/etc/ThisCell>
+file).
=item *
-If the -cell argument is included, only machines that are
-marked inaccessible and belong to the specified cell
-
+If the B<-cell> argument is included, only machines that are marked
+inaccessible and belong to the specified cell.
=item *
-If the -all flag is included, all machines marked inaccessible
-
+If the B<-all> flag is included, all machines marked inaccessible.
=back
-If the -fast flag is included, the Cache Manager does not probe
-any machines, but instead reports the results of the most recent previous
+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.
+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 CAVEATS
+=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
+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
-B<Ctrl-c> or another interrupt signal.
+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.
+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.
+Unlike most B<fs> commands, the fs checkservers command does not refer to
+the AFSCELL environment variable.
=head1 OPTIONS
=over 4
-=item -cell
+=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
-B</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.
+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 -all
+=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.
+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 -fast
+=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
+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 -interval
+=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:
+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 B<600> (10 minutes); the default is B<180> (three
-minutes). The issuer must be logged in as the local superuser
-B<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.
-
+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 0 (zero) to display the current interval
-setting. No privilege is required. Do not combine this argument
-with any other.
-
+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 -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
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.
+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).
+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 -interval argument is provided with a value between
-B<1> and B<600>, there is no output. If the value is
-B<0>, the output reports the probe interval as follows:
+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 I<interval> secs
+ The current down server probe interval is <interval> secs
=head1 EXAMPLES
% fs checkservers -fast
All servers are running.
-The following example probes machines in the Cache Manager's memory
-list that belong to the B<stateu.edu> cell:
+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.
+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:
=head1 PRIVILEGE REQUIRED
To set the probe interval, the issuer must be logged in as the local
-superuser B<root>. Otherwise, no privilege is required.
+superuser C<root>. Otherwise, no privilege is required.
=head1 SEE ALSO
-L<CellServDB (client version)(1)>
-
-L<ThisCell (client version)(1)>
-
+L<CellServDB(5)>,
+L<ThisCell(5)>,
L<fs_newcell(1)>
=head1 COPYRIGHT
=head1 NAME
-fs checkvolumes - Forces the Cache Manager to update volume-related information
+fs checkvolumes - Forces the Cache Manager to update volume information
=head1 SYNOPSIS
-B<fs checkvolumes> [-help]
+B<fs checkvolumes> [B<-help>]
-B<fs checkv> [-h]
+B<fs checkv> [B<-h>]
=head1 DESCRIPTION
-The 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 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.
+released, because issuing it forces the Cache Manager to reference the
+changed volume.
=head1 OPTIONS
=over 4
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=head1 SYNOPSIS
-B<fs cleanacl >[B<-path> <I<dir/file path>>+] [-help]
+B<fs cleanacl> [B<-path> <I<dir/file path>>+] [B<-help>]
-B<fs cl> [B<-p> <I<dir/file path>>+] [-h]
+B<fs cl> [B<-p> <I<dir/file path>>+] [B<-h>]
=head1 DESCRIPTION
-The 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.
+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.)
+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 -path
+=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.
+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,
-B</afs/.abc.com>). For further discussion of the
-concept of read/write and read-only paths through the filespace, see the
-B<fs mkmount> reference page.
+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 -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
If there are no obsolete entries on the ACL, the following message
appears:
- Access list for I<dir/file path> is fine.
+ Access list for <path> is fine.
Otherwise, the output reports the resulting state of the ACL, following the
header
- Access list for I<dir/file path> is now
+ Access list for <path> is now
At the same time, the following error message appears for each file in the
cleaned directories:
- fs: 'I<filename>': Not a directory
+ fs: '<filename>': Not a directory
=head1 EXAMPLES
=head1 PRIVILEGE REQUIRED
-The issuer must have the B<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
-B<system:administrators> group have the right implicitly, even
-if it does not appear on the ACL.
+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
=head1 NAME
-fs copyacl - Copies an ACL from one directory to one or more other directories
+fs copyacl - Copies an ACL from a directory to one or more other directories
=head1 SYNOPSIS
-fs copyacl -fromdir <I<source directory (or DFS file)>>
-B<-todir> <I<destination directory (or DFS file)>>+
- [B<-clear>] [B<-id>] [B<-if>] [-help]
+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]
-fs co -f <I<source directory (or DFS file)>>
-B<-t> <I<destination directory (or DFS file)>>+
- [B<-c>] [B<-id>] [B<-if>] [-h]
+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:
+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
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.
-
+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.
-
+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>.
+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 CAVEATS
+=head1 CAUTIONS
-Do not copy ACLs between AFS and DFS files or directories. The ACL
-formats are incompatible.
+Do not copy ACLs between AFS and DFS files or directories. The ACL formats
+are incompatible.
=head1 OPTIONS
=over 4
-=item -fromdir
+=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.
+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 -todir
+=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.
+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,
-B</afs/.abc.com>). For further discussion of the
-concept of read/write and read-only paths through the filespace, see the
-B<fs mkmount> reference page.
+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 -clear
+=item B<-clear>
Replaces the ACL of each destination directory with the source ACL.
-=item -id
+=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
+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 -if
+=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
+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 -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=head1 EXAMPLES
-The following example command copies the current working directory's
-ACL to its subdirectory called B<reports>. Note that the source
-directory's ACL is unaffected. Entries on the B<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.
+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
smith rlidwk
Negative rights
jones rlidwka
-
=head1 PRIVILEGE REQUIRED
-To copy an ACL between AFS objects, the issuer must have the l
-(B<lookup)>) permission on the source directory's ACL and the
-B<a> (B<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 B<l> and
-B<r> (B<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 B<c>
-(B<control>) permission on each destination directory or file's
-ACL.
+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
=head1 NAME
-fs diskfree - Displays information about the partition housing a directory or file
+fs diskfree - Shows data about the partition housing a directory or file
=head1 SYNOPSIS
-B<fs diskfree> [B<-path> <I<dir/file path>>+] [-help]
+B<fs diskfree> [B<-path> <I<dir/file path>>+] [B<-help>]
-B<fs df> [B<-p> <I<dir/file path>>+] [-h]
+B<fs df> [B<-p> <I<dir/file path>>+] [B<-h>]
-B<fs di> [B<-p> <I<dir/file path>>+] [-h]
+B<fs di> [B<-p> <I<dir/file path>>+] [B<-h>]
=head1 DESCRIPTION
-The fs diskfree command formats and displays information about
-the partition that houses the volume containing the specified directory or
+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 fs
-examine command. The B<fs examine> and B<fs
-quota> commands also display information about a volume.
+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 CAVEATS
+=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.
+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 -path
+=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
+produce output. Partial pathnames are interpreted relative to the current
+working directory, which is also the default value if this argument is
omitted.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=head1 OUTPUT
-The output reports the following information about the volume and partition
-that houses each file or directory:
+The output reports the following information about the volume and
+partition that houses each file or directory:
=over 4
-=item C<Volume Name
->
+=item Volume Name
-The name of the volume
+The name of the volume.
-=item C<kbytes
->
+=item kbytes
-The partition's total size in kilobytes
+The partition's total size in kilobytes.
-=item C<used
->
+=item used
-The number of kilobytes used on the partition
+The number of kilobytes used on the partition.
-=item C<avail
->
+=item avail
-The number of kilobytes available on the partition
+The number of kilobytes available on the partition.
-=item C<%used
->
+=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)
+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 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.
+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 B<user.smith> and B<sun4x_56.bin>:
+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
=head1 PRIVILEGE REQUIRED
-The issuer must have the B<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.
+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
=head1 NAME
-fs examine - Displays information about the volume containing a directory or file
+fs examine - Shows data about the volume containing a directory or file
=head1 SYNOPSIS
-B<fs examine> [B<-path> <I<dir/file path>>+] [-help]
+B<fs examine> [B<-path> <I<dir/file path>>+] [B<-help>]
-B<fs exa> [B<-p> <I<dir/file path>>+] [-h]
+B<fs exa> [B<-p> <I<dir/file path>>+] [B<-h>]
-B<fs listvol> [B<-p> <I<dir/file path>>+] [-h]
+B<fs listvol> [B<-p> <I<dir/file path>>+] [B<-h>]
-B<fs listv> [B<-p> <I<dir/file path>>+] [-h]
+B<fs listv> [B<-p> <I<dir/file path>>+] [B<-h>]
-B<fs lv> [B<-p> <I<dir/file path>>+] [-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.
+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 fs
-listquota command displays similar information in tabular format, and
-the B<fs quota> command reports only the percentage of quota
-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 fs setvol
-command.
+To set volume quota, use the B<fs setquota> or B<fs setvol> command.
-=head1 CAVEATS
+=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.
+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 -path
+=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
+produce output. Partial pathnames are interpreted relative to the current
+working directory, which is also the default value if this argument is
omitted.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=head1 OUTPUT
-The output displays information about the volume that houses each specified
-directory or file, in the following format
+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>
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> C<offline> C<message> line appears only
-if an administrator has included the B<-offlinemsg> argument to the
-B<fs setvol> command. The remaining lines report, respectively,
+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
-
+The volume's quota in kilobytes, or the string C<unlimited> to indicate an
+unlimited quota.
=item *
-the volume's current size in kilobytes
-
+The volume's current size in kilobytes.
=item *
-the number of blocks available and total size of the host partition, both
+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
-B<user.smith> and the partition housing it:
+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
=head1 PRIVILEGE REQUIRED
-The issuer must have the B<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.
+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
=head1 NAME
-fs exportafs - Reports or sets whether the machine can export AFS to clients of other file
-systems
+fs exportafs - Configures export of AFS to clients of other file systems
=head1 SYNOPSIS
-fs exportafs -type <I<exporter name>>
-[B<-start> <I<start/stop translator (on | off)>>]
- [-convert <I<convert from afs to unix mode (on | off)>>]
- [-uidcheck <I<run on strict 'uid check' mode (on | off)>>]
-
[-submounts <I<allow nfs mounts to subdirs of /afs/.. (on | off)>>]
- [-help]
+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>]
-fs exp -t <I<exporter name>>
-[B<-st> <I<start/stop translator (on | off)>>]
- [-c <I<convert from afs to unix mode (on | off)>>]
- [-u <I<run on strict 'uid check' mode (on | off)>>]
-
[-su <I<allow nfs mounts to subdirs of /afs/.. (on | off)>>]
- [-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 -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:
+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 B<group> and other mode
-bits on an AFS file or directory are set to match the B<owner> mode
-bits when it is exported to the non-AFS file system, use the
-B<-convert> argument.
-
+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.
-
+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 B</afs>, use the B<-submounts>
-argument.
-
+AFS directory other than F</afs>, use the B<-submounts> argument.
=back
=over 4
-=item -type
+=item B<-type> <I<exporter name>>
Names the alternate file system to which to reexport the AFS
-filespace. The only acceptable value is B<nfs>, in lowercase
-letters only.
+filespace. The only acceptable value is C<nfs>, in lowercase letters only.
-=item -start
+=item B<-start> on
+=item B<-start> off
Enables the local machine to reexport the AFS filespace if the value is
-B<on>, or disables it if the value is B<off>. Omit this
-argument to report the current setting for all of the configurable
-parameters.
+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 -convert
+=item B<-convert> on
+=item B<-convert> off
-Controls the setting of the UNIX B<group> and other
-mode bits on AFS files and directories exported to the non-AFS file
-system. If the value is B<on>, they are set to match the
-B<owner> mode bits. If the value is B<off>, the bits
-are not changed. If this argument is omitted, the default value is
-B<on>.
+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 -uidcheck
+=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.
+tokens in the structure.
=over 4
=item *
-If the value is on, the UID that identifies the credential
-structure must match the local UID.
+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.
-With respect to the 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 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 the reference page for the B<klog> command.
+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.
-
+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 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 B<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.
+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 -submounts
+=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 B</afs>
-directory. If the value is B<on>, such submounts are
-allowed. If the value is off, only mounts of the B</afs>
-directory are allowed. If this argument is omitted, the default value
-is B<off>.
+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 -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
If the machine is not even configured as a server of the non-AFS file
system, the following message appears:
- Sorry, the I<file_system>-exporter type is currently not supported on
+ 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 B<on>), the message is as
-follows:
+argument to this command is not set to C<on>), the message is as follows:
- 'I<file_system>' translator is disabled
+ '<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.
- 'I<file_system>' translator is enabled with the following options:
+ '<file_system>' translator is enabled with the following options:
-The following messages indicate that the -convert argument is
-set to B<on> or B<off> respectively:
+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 -uidcheck argument is
-set to B<on> or B<off> respectively:
+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 -submounts argument is
-set to B<on> or B<off> respectively:
+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
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 B<group> and B<other> mode bits on exported AFS
-directories and files to match the UNIX B<owner> mode bits.
+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
=head1 SYNOPSIS
-B<fs flush> [B<-path> <I<dir/file path>>+] [-help]
+B<fs flush> [B<-path> <I<dir/file path>>+] [B<-help>]
-B<fs flush> [B<-p> <I<dir/file path>>+] [-h]
+B<fs flush> [B<-p> <I<dir/file path>>+] [B<-h>]
=head1 DESCRIPTION
-The fs flush command removes from the cache all data and status
+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
+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:
-=item *
+=over 4
-Data in application program buffers
+=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
+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.
+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 -path
+=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
+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 -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=head1 EXAMPLES
-The following command flushes from the cache the file
-B<projectnotes> in the current working directory and all data from the
-subdirectory B<plans>:
+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 B<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.
+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
=head1 SYNOPSIS
-B<fs flushmount> [B<-path> <I<dir/file path>>+] [-help]
+B<fs flushmount> [B<-path> <I<dir/file path>>+] [B<-help>]
-B<fs flushm> [B<-p> <I<dir/file path>>+] [-h]
+B<fs flushm> [B<-p> <I<dir/file path>>+] [B<-h>]
=head1 DESCRIPTION
-The 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 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.
+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 fs flush
-or B<fs flushvolume> command.
+To flush cached data rather than a mount point, use the B<fs flush> or
+B<fs flushvolume> command.
=head1 OPTIONS
=over 4
-=item -path
+=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
+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 -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=head1 EXAMPLES
The following command flushes from the cache the mount point for user
-
B<pat>'s home directory:
+
C<pat>'s home directory:
% fs flushm /afs/abc.com/usr/pat
=head1 PRIVILEGE REQUIRED
-The issuer must have the B<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.
+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
=head1 NAME
-fs flushvolume - Forces the Cache Manager to discard all cached data from the volume
-containing a file or directory
+fs flushvolume - Forces the Cache Manager to discard cached data from a volume
=head1 SYNOPSIS
-B<fs flushvolume> [B<-path> <I<dir/file path>>+] [-help]
+B<fs flushvolume> [B<-path> <I<dir/file path>>+] [B<-help>]
-B<fs flushv> [B<-p> <I<dir/file path>>+] [-h]
+B<fs flushv> [B<-p> <I<dir/file path>>+] [B<-h>]
=head1 DESCRIPTION
-The 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:
+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:
-=item *
+=over 4
-Data in application program buffers
+=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
+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.
+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 -path
+=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 -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=head1 PRIVILEGE REQUIRED
-The issuer must have the B<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.
+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
=head1 NAME
-fs getcacheparms - Displays the current size of the cache and the amount being used
+fs getcacheparms - Displays the current size and usage of the cache
=head1 SYNOPSIS
-B<fs getcacheparms> [-help]
+B<fs getcacheparms> [B<-help>]
-B<fs getca> [-h]
+B<fs getca> [B<-h>]
=head1 DESCRIPTION
-The 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 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 B</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.
+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 -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
The output reports
- AFS using I<amount used> of the cache's available I<size> 1K byte blocks.
+ AFS using <amount> of the cache's available <size> 1K byte blocks.
-where I<amount used> is the number of kilobyte blocks currently used
-to cache data and status information, and I<size> is the total current
-cache size.
+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
=head1 NAME
-fs getcellstatus - Reports whether the machine can run setuid programs from a specified cell
+fs getcellstatus - Reports whether setuid programs are honored in a cell
=head1 SYNOPSIS
-B<fs getcellstatus -cell> <I<cell name>>+ [-help]
+B<fs getcellstatus> B<-cell> <I<cell name>>+ [B<-help>]
-B<fs getce -c> <I<cell name>>+ [-h]
+B<fs getce> B<-c> <I<cell name>>+ [B<-h>]
=head1 DESCRIPTION
-The 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; its reference page fully describes how AFS treats
-setuid programs.
+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 -cell
+=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 B</usr/vice/etc/CellServDB>
-file.
+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 -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
The output reports one of the following two values as appropriate:
- Cell I<cell> status: setuid allowed
- Cell I<cell> status: no setuid allowed
+ Cell <cell> status: setuid allowed
+ Cell <cell> status: no setuid allowed
=head1 EXAMPLES
-The following example indicates that programs from the cell
-B<abc.com> are not allowed to run with setuid
-permission.
+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 SEE ALSO
-L<CellServDB (client version)(1)>
-
+L<CellServDB(5)>,
L<fs_setcell(1)>
=head1 COPYRIGHT
=head1 NAME
-fs getclientaddrs - Displays the client interfaces to register with the File Server
+fs getclientaddrs - Displays the client interfaces to register
=head1 SYNOPSIS
-B<fs getclientaddrs> [-help]
+B<fs getclientaddrs> [B<-help>]
-B<fs gc> [-h]
+B<fs gc> [B<-h>]
-B<fs getcl >[-h]
+B<fs getcl> [B<-h>]
=head1 DESCRIPTION
-The fs getclientaddrs command displays the IP addresses of the
+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.
+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
+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.
-The fs setclientaddrs reference page 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.
+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 CAVEATS
+=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.
+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.
+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.
+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.
+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 -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=head1 OUTPUT
-The output 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.
+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.
+The following example displays the two interfaces that the Cache Manager
+is registering with File Servers.
% fs getclientaddrs
192.12.105.68
=head1 NAME
-fs getserverprefs - Displays the Cache Manager's preference ranks for file server or VL
-Server machines
+fs getserverprefs - Displays preference ranks for file servers or VL servers
=head1 SYNOPSIS
-B<fs getserverprefs> [-file <I<output to named file>>]
-[B<-numeric>] [B<-vlservers>] [B<-help>]
+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>] [-h]
+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>] [-h]
+B<fs gp> [B<-f> <I<output to named file>>] [B<-n>] [B<-v>] [B<-h>]
=head1 DESCRIPTION
-The 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.
+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
-B</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
+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.
+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.
+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.
+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 -file
+=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
+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 -numeric
+=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 B<fs1.abc.com>.
+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 -vlservers
+=item B<-vlservers>
Displays preference ranks for VL Server machines rather than file server
machine interfaces.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
The output consists of 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
+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.
+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.
+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, B<def.com>. It is not
-possible to translate the IP addresses of two machines on the 138.255
-network.
+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
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.
+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
138.255.33.36 40012
138.255.33.37 40005
-The example shows how the -vlservers flag displays preference
-ranks for VL Server machines:
+The example shows how the B<-vlservers> flag displays preference ranks for
+VL Server machines:
% fs getserverprefs -vlservers
fs2.abc.com 10052
=head1 NAME
-fs help - Displays the syntax of specified fs commands or lists functional
-descriptions of all B<fs> commands
+fs help - Displays help for fs commands
=head1 SYNOPSIS
-B<fs help> [B<-topic> <I<help string>>+] [-help]
+B<fs help> [B<-topic> <I<help string>>+] [B<-help>]
-B<fs h> [B<-t> <I<help string>>+] [-h]
+B<fs h> [B<-t> <I<help string>>+] [B<-h>]
=head1 DESCRIPTION
-The 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.
+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 fs command whose name or short description
-includes a specified keyword, use the B<fs apropos> 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 -topic
+=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 B<setacl>, not B<fs
-setacl>). If this argument is omitted, the output briefly
-describes every B<fs> command.
+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 -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=head1 OUTPUT
-The online help entry for each fs command consists of the
-following two or three lines:
+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.
-
+The first line names the command and briefly describes its function.
=item *
The second line lists aliases for the command, if any.
-
=item *
-The final line, which begins with the string C<Usage>, lists the
-command's options in the prescribed order. Online help entries use
-the same symbols (for example, brackets) as the reference pages in this
-document.
-
+The final line, which begins with the string C<Usage>, lists the command's
+options in the prescribed order. Online help entries use the same symbols
+(for example, brackets) as the reference pages in this document.
=back
=head1 EXAMPLES
-The following command displays the online help entry for the fs
-setacl command:
+The following command displays the online help entry for the B<fs setacl>
+command:
% fs help setacl
fs setacl: set access control list
=head1 SYNOPSIS
-B<fs listacl> [B<-path> <I<dir/file path>>+] [B<-id>] [B<-if>] [-help]
+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>] [-h]
+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>] [-h]
+B<fs lista> [B<-p> <I<dir/file path>>+] [B<-id>] [B<-if>] [B<-h>]
=head1 DESCRIPTION
-The fs listacl command displays the access control list (ACL)
+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.
+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.
+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 CAVEATS
+=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
-B<system:anyuser> group. In that case, the user needs
-only to issue the B<unlog> command to obtain the permissions granted
-to the B<system:anyuser> group.
+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 -path
+=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.
+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 -id
+=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.
+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 -if
+=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.
+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 -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
The first line of the output for each file, directory, or symbolic link
reads as follows:
- Access list for I<directory> is
+ Access list for <directory> is
If the issuer used shorthand notation in the pathname, such as the period
-(B<.>) 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.
+(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
+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
=over 4
-=item C<a
->
+=item a (administer)
-(administer): change the entries on the ACL
+Change the entries on the ACL.
-=item C<d
->
+=item d (delete)
-(delete): remove files and subdirectories from the
-directory or move them to other directories
+Remove files and subdirectories from the directory or move them to other
+directories.
-=item C<i
->
+=item i (insert)
-(insert): add files or subdirectories to the directory by
-copying, moving or creating
+Add files or subdirectories to the directory by copying, moving or
+creating.
-=item C<k
->
+=item k (lock)
-(lock): set read locks or write locks on the files in the
-directory
+Set read locks or write locks on the files in the directory.
-=item C<l
->
+=item l (lookup)
-(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
+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 C<r
->
+=item r (read)
-(read): read the contents of files in the directory;
-issue the B<ls -l> command to stat the elements in the directory
+Read the contents of files in the directory; issue the C<ls -l> command to
+stat the elements in the directory.
-=item C<w
->
+=item w (write)
-(write): modify the contents of files in the directory,
-and issue the UNIX B<chmod> command to change their mode bits
+Modify the contents of files in the directory, and issue the UNIX B<chmod>
+command to change their mode bits
-=item C<A, C<B>, C<C>, C<D>, C<E>,
-C<F>, C<G>, C<H>:
->
+=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.
+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 B<x> (B<execute>) permission replaces the AFS B<l>
-(B<lookup>) permission, DFS B<c> (B<control>) replaces
-AFS B<a> (B<administer>), and there is no DFS equivalent to
-the AFS B<k> (B<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>.
+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
-
B<pat> (the current working directory), and on its B<private>
+
C<pat> (the current working directory), and on its C<private>
subdirectory.
% fs listacl -path . private
=head1 PRIVILEGE REQUIRED
-If the -path argument names an AFS directory, the issuer must
-have the B<l> (B<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 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 -path argument names an AFS file, the issuer must have
-the B<l> (B<lookup>) and B<r> (B<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 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 -path argument names a DFS directory or file, the issuer
-must have the B<x> (B<execute>) permission on its ACL and 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
=head1 NAME
-fs listcells - Displays the database server machines in each cell known to the Cache
-Manager
+fs listcells - Displays the database server machines known to the Cache Manager
=head1 SYNOPSIS
-B<fs listcells> [B<-numeric>] [-help]
+B<fs listcells> [B<-numeric>] [B<-help>]
-B<fs listc> [B<-n>] [-h]
+B<fs listc> [B<-n>] [B<-h>]
=head1 DESCRIPTION
-The 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.
+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 B</usr/vice/etc/CellServDB> into kernel memory. To modify
-the list between reboots, use the B<fs newcell> command.
+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 -numeric
+=item B<-numeric>
-Displays each database server machine's IP address rather than
-hostname.
+Displays each database server machine's IP address rather than hostname.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=head1 OUTPUT
-The output includes a line for each cell included in the Cache
-Manager's kernel memory list, in the following format:
+The output includes a line for each cell included in the Cache Manager's
+kernel memory list, in the following format:
- Cell I<cell> on hosts I<database server machines>
+ 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.
+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 -numeric flag bypasses the translation to hostnames,
-which can result in significantly faster production of output. The
-output includes IP addresses only.
+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
=head1 SEE ALSO
-L<CellServDB (client version)(1)>
-
+L<CellServDB(5)>,
L<fs_newcell(1)>
=head1 COPYRIGHT
=head1 NAME
-fs listquota - Displays quota information for the volume containing a file or
-directory.
+fs listquota - Displays quota information for a volume
=head1 SYNOPSIS
-B<fs listquota> [B<-path> <I<dir/file path>>+] [-help]
+B<fs listquota> [B<-path> <I<dir/file path>>+] [B<-help>]
-B<fs listq> [B<-p> <I<dir/file path>>+] [-h]
+B<fs listq> [B<-p> <I<dir/file path>>+] [B<-h>]
-B<fs lq> [B<-p> <I<dir/file path>>+] [-h]
+B<fs lq> [B<-p> <I<dir/file path>>+] [B<-h>]
=head1 DESCRIPTION
-The 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.
+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 fs
-examine command.
+To display more information about the host partition, use the B<fs
+examine> command.
-To set volume quota, use the B<fs setquota> or fs setvol
-command.
+To set volume quota, use the B<fs setquota> or B<fs setvol> command.
=head1 OPTIONS
=over 4
-=item -path
+=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
+produce output. Partial pathnames are interpreted relative to the current
+working directory, which is also the default value if this argument is
omitted.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=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:
+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 C<Volume Name
->
+=item Volume Name
The name of the volume.
-=item C<Quota
->
+=item Quota
-The volume's quota in kilobytes, or the string C<no limit> to
-indicate an unlimited quota.
+The volume's quota in kilobytes, or the string C<no limit> to indicate an
+unlimited quota.
-=item C<Used
->
+=item Used
The number of kilobytes of quota used.
-=item C<% 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).
+The percentage of the volume's quota that is used (the C<Used> statistic
+divided by the C<Quota> statistic, times 100).
-=item C<Partition
->
+=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.
+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
-B<user.smith>:
+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
=head1 PRIVILEGE REQUIRED
-The issuer must have the B<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.
+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
=head1 SYNOPSIS
-B<fs lsmount -dir> <I<directory>>+ [-help]
+B<fs lsmount> B<-dir> <I<directory>>+ [B<-help>]
-B<fs ls -d> <I<directory>>+ [-h]
+B<fs ls -d> <I<directory>>+ [B<-h>]
=head1 DESCRIPTION
-The 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.
+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 fs mkmount command. To
-remove one, use the B<fs rmmount> command.
+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 -dir
+=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 (B<.> or
-B<..>).
+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 -help
+=item B<-help>
Prints the online help for this command. All other valid options
are ignored.
=head1 OUTPUT
-If the specified directory is a mount point, the output is of the following
-form:
+If the specified directory is a mount point, the output is of the
+following form:
- 'I<directory>' is a mount point for volume 'I<volume name>'
+ '<directory>' is a mount point for volume '<volume name>'
where
=item *
-A number sign (C<#>) precedes the I<volume name> string for
-a regular mount point.
-
+A number sign (C<#>) precedes the <volume name> string for a regular mount
+point.
=item *
-A percent sign (C<%>) precedes the I<volume name> string for
-a read/write mount point.
-
+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 I<volume name> string for a cellular mount
-point.
-
+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 fs mkmount reference page explains how the Cache Manager
-interprets each of the three types of mount points.
+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:
- 'I<directory>' is a symbolic link, leading to a mount point for volume 'I<volume name>'
+ '<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:
+If the directory is not a mount point or is not in AFS, the output reads:
- 'I<directory>' is not a mount point.
+ '<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.
+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
-B<smith>:
+C<smith>:
% fs lsmount /afs/abc.com/usr/smith
'/afs/abc.com/usr/smith' is a mount point for volume '#user.smith'
% 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.
+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 B<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.
+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
=head1 SYNOPSIS
-B<fs messages> [B<-show> <[B<user>|B<console>|B<all>|B<none>]>] [-help]
+B<fs messages> [B<-show> (user|console|all|none)] [B<-help>]
-B<fs me> [B<-s> <[B<user>|B<console>|B<all>|B<none>]>] [-h]
+B<fs me> [B<-s> (user|console|all|none)] [B<-h>]
=head1 DESCRIPTION
-The 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.
+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:
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.
-
+the Cache Manager directs them to the client machine's designated console.
=back
=over 4
-=item -show
+=item B<-show> (user|console|all|none)
-Specifies the types of messages to display. Choose one of the
-following values:
+Specifies the types of messages to display. Choose one of the following
+values:
=over 4
=item user
-Send user messages to user screens
+Send user messages to user screens.
=item console
-Send console messages to the 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)
+(the default if the B<-show> argument is omitted).
=item none
-Do not send any messages to user screens or the console
+Do not send any messages to user screens or the console.
=back
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=head1 SEE ALSO
-L<afsd(1)>
+L<afsd(8)>
=head1 COPYRIGHT
=head1 SYNOPSIS
-B<fs mkmount -dir> <I<directory>> B<-vol> <I<volume name>> [-cell <I<cell name>>]
-[B<-rw>] [B<-fast>] [B<-help>]
+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 -d> <I<directory>> B<-v> <I<volume name>> [B<-c> <I<cell name>>] [B<-r>] [B<-f>] [-h]
+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 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.
+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
=over 4
-=item *
-
-Rule 1: Access Backup and Read-only Volumes When
-Specified
-
+=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 B<.readonly> or a B<.backup>
-extension, it accesses that type of volume only. If a mount point does
-not have either a B<.backup> or B<.readonly>
-extension, the Cache Manager uses Rules 2 and 3.
+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
-
+=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
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 B</afs> by convention). That is, if the
-B<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
-B<root.afs> and B<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 B</afs> and B</afs/>I<cellname> directories,
-respectively.
-
-=item *
-
-Rule 3: Once on a Read/write Path, Stay There
-
+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 B<.readonly> or a B<.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 B<.readonly> extension. (Cellular
-mount points are an important exception to this rule, as explained in the
-following discussion.
+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.
+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.
-L<(1)>
-L<(1)>
-
+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
-B<.readonly> or B<.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.
-L<(1)>
-L<(1)>
-
-
-To create a read/write mount point, include the -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 B<root.cell> volume just below the AFS filespace
-root (by convention, B</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.
+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 B<.readonly> or
-B<.backup> extension.
+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.
-L<(1)>
-L<(1)>
-L<(1)>
-
-
-To create a regular cellular mount point, include the -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
-B</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 B</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.
+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
=over 4
-=item -dir
+=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.
+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,
-B</afs/.abc.com>). For further discussion of the
-concept of read/write and read-only paths through the filespace, see the
-B<Description> section of this reference page.
+F</afs/.abc.com>). For further discussion of the concept of read/write and
+read-only paths through the filespace, see L<DESCRIPTION>.
-=item -vol
+=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.
+appropriate, add the C<.readonly> or C<.backup> extension to the name, or
+specify the appropriate volume ID number.
-=item -cell
+=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
-B</usr/vice/etc/CellServDB> file.
+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.
+named in the mount point resides in the same cell as the volume that
+houses the mount point.
-=item -rw
+=item B<-rw>
-Creates a read/write mount point. Omit this flag to create a
-regular mount point.
+Creates a read/write mount point. Omit this flag to create a regular mount
+point.
-=item -fast
+=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
+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 -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=head1 EXAMPLES
The following command creates a regular mount point, mounting the volume
-B<user.smith> at
-B</afs/abc.com/usr/smith>:
+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.
+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
-B</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.
+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 B<i> (B<insert>) and a
-(B<administer>) permissions on the ACL of the directory that is to
-house the mount point.
+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 (client version)(1)>
-
+L<CellServDB(5)>,
L<fs_lsmount(1)>,
L<fs_rmmount(1)>
=head1 NAME
-fs newcell - Changes the kernel-resident list of a cell's database server machines
+fs newcell - Changes the kernel-resident list of a cell's database servers
=head1 SYNOPSIS
-B<fs newcell
-name> <I<cell name>> -servers <I<primary servers>>+
-[B<-linkedcell> <I<linked cell name>>] [B<-help>]
+B<fs newcell
> B<-name> <I<cell name>> -servers <I<primary servers>>+
+ [B<-linkedcell> <I<linked cell name>>] [B<-help>]
-B<fs n -n> <I<cell name>> B<-s> <I<primary servers>>+ [B<-l> <I<linked cell name>>] [-h]
+B<fs n> B<-n> <I<cell name>> B<-s> <I<primary servers>>+
+ [B<-l> <I<linked cell name>>] [B<-h>]
=head1 DESCRIPTION
-The 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
-B</usr/vice/etc/CellServDB> file. This command does not change
-the B<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
-B<CellServDB> file.
+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 B<CellServDB> file and reboot the machine.
-
-If the -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 B</usr/vice/etc/CellServDB>
-file.
+B<-server> argument). To make a cell inaccessible, remove its entry from
+the F<CellServDB> file and reboot the machine.
-=head1 CAVEATS
+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.
-Some commands, such as the klog command, work correctly only
-when the information is accurate for a cell in both the B<CellServDB>
-file and the kernel-resident list.
+=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 -name
+=item B<-name> <I<cell name>>
Specifies the fully-qualified cell name of the AFS or DCE cell.
-=item -servers
+=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.
+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 -linkedcell
+=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 -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=head1 EXAMPLES
The following example changes the machine's kernel-resident list of
-database server machines for the ABC Corporation cell to include the machines
-B<db1.abc.com> and
-B<db2.abc.com>:
+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
-B<dce.abc.com> to the AFS cell
-B<abc.com>. The AFS client contacts the Fileset Location
-(FL) servers B<db1.dce.abc.com> and
-B<db2.dce.abc.com> for fileset location
-information as it interprets a DFS pathname.
+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
+ % fs newcell -name dce.abc.com \
+ -servers db1.dce.abc.com db2.dce.abc.com \
+ -linkedcell abc.com
=head1 PRIVILEGE REQUIRED
=head1 SEE ALSO
-L<CellServDB (client version)(1)>
-
+L<CellServDB(5)>,
L<fs_listcells(1)>
I<IBM AFS/DFS Migration Toolkit Administration Guide and Reference>
=head1 NAME
-fs quota - Displays the percentage of quota used in the volume containing a directory
-or file
+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>>+] [-help]
+B<fs quota> [B<-path> <I<dir/file path>>+] [B<-help>]
-B<fs q> [B<-p> <I<dir/file path>>+] [-h]
+B<fs q> [B<-p> <I<dir/file path>>+] [B<-h>]
=head1 DESCRIPTION
-The fs quota command displays the percent of quota consumed in
-the volume that contains each specified directory or file.
+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.
+resides on, use the B<fs examine> and B<fs listquota> commands.
-To set volume quota, use the B<fs setquota> or fs setvol
-command.
+To set volume quota, use the B<fs setquota> or B<fs setvol> command.
=head1 OPTIONS
=over 4
-=item -path
+=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.
+current working directory, which is also the default value if this
+argument is omitted.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
The output reports the percent of volume quota used, in the following
format:
-
I<percent>% of quota used.
+ <percent>% of quota used.
=head1 EXAMPLES
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 B</afs/abc.com/usr/smith>:
+housing the directory F</afs/abc.com/usr/smith>:
- % fs quota -path .. /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 B<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.
+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
=head1 SYNOPSIS
-B<fs rmmount -dir> <I<directory>>+ [-help]
+B<fs rmmount> B<-dir> <I<directory>>+ [B<-help>]
-B<fs rm -d> <I<directory>>+ [-h]
+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.
+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 -dir
+=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" (.) or "dot dot" (. .).
+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,
-B</afs/.abc.com>). For further discussion of the
-concept of read/write and read-only paths through the filespace, see the
-B<fs mkmount> reference page.
+F</afs/.abc.com>). For further discussion of the concept of read/write and
+read-only paths through the filespace, see the B<fs mkmount> reference
+page.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=head1 EXAMPLES
-The following command removes the mount points jones and
-B<terry> from the current working directory (the
-B</afs/abc.com/usr> directory).
+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 B<d> (delete) permission on the
-ACL of the directory that houses each mount point.
+The issuer must have the C<d> (delete) permission on the ACL of the
+directory that houses each mount point.
=head1 SEE ALSO
=head1 SYNOPSIS
-B<fs setacl
-dir> <I<directory>>+ -acl <I<access list entries>>+
-[B<-clear>] [B<-negative>] [B<-id>] [B<-if>] [B<-help>]
+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
-d> <I<directory>>+ -a <I<access list entries>>+
-[B<-c>] [B<-n>] [B<-id>] [B<-if>] [B<-h>]
+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
-d> <I<directory>>+ -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 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.
+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 -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
-B<mask_obj>, however. For more details, refer to the I<IBM
-AFS/DFS Migration Toolkit Administration Guide and Reference>.
+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 -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.
+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> C<rights> section of the ACL (deny rights to
-specified users or groups), provide the B<-negative> flag.
+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.
+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 CAVEATS
+=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.
+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>
-C<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 B<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 -clear option, be sure to reinstate an entry
-for each directory's owner that includes at least the B<l>
-(B<lookup>) permission. Without that permission, it is
-impossible to resolve the "dot" ( . ) and "dot dot" ( . .
-) shorthand from within the directory. (The directory's owner does
-implicitly have the B<a> [B<administer>] permission even on a
-cleared ACL, but must know to use it to add other permissions.)
+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 -dir
+=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
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,
-B</afs/.abc.com>). For further discussion of the
-concept of read/write and read-only paths through the filespace, see the
-B<fs mkmount> reference page.
+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 -acl
+=item B<-acl> <I<access list entries>>+
-Defines a list of one or more ACL entries, each a pair that names
+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
-
+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
-
+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:
+the meaning of each, are as follows:
=over 4
-=item a
+=item a (administer)
-(administer): change the entries on the ACL
+Change the entries on the ACL.
-=item d
+=item d (delete)
-(delete): remove files and subdirectories from the
-directory or move them to other directories
+Remove files and subdirectories from the directory or move them to other
+directories.
-=item i
+=item i (insert)
-(insert): add files or subdirectories to the directory by
-copying, moving or creating
+Add files or subdirectories to the directory by copying, moving or
+creating.
-=item k
+=item k (lock)
-(lock): set read locks or write locks on the files in the
-directory
+Set read locks or write locks on the files in the directory.
-=item l
+=item l (lookup)
-(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
+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
+=item r (read)
-(read): read the contents of files in the directory;
-issue the B<ls -l> command to stat the elements in the directory
+Read the contents of files in the directory; issue the C<ls -l> command to
+stat the elements in the directory.
-=item w
+=item w (write)
-(write): modify the contents of files in the directory,
-and issue the UNIX B<chmod> command to change their mode bits
+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.
+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 (rlidwka).
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
+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.
-L<(1)>
-L<(1)>
+guarantee they have no permissions if they belong to groups that remain on
+the ACL.
=item read
-Equals the B<r> (B<read>) and l
-(B<lookup>) permissions.
-L<(1)>
-L<(1)>
+Equals the C<r> (read) and C<l> (lookup) permissions.
=item write
-Equals all permissions except B<a> (administer), that
-is, B<rlidwk>.
-L<(1)>
-L<(1)>
+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.
+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>.
+the I<IBM AFS/DFS Migration Toolkit Administration Guide and Reference>.
-=item -clear
+=item B<-clear>
Removes all existing entries on each ACL before adding the entries
specified with the B<-acl> argument.
-=item -negative
+=item B<-negative>
-Places the specified ACL entries in the C<Negative>
-C<rights> section of each ACL, explicitly denying the rights to the
-user or group, even if entries on the accompanying C<Normal>
-C<rights> section of the ACL grant them permissions.
+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 -id
+=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.
+which are the only file system objects for which this flag is supported.
-=item -if
+=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.
+which are the only file system objects for which this flag is supported.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=head1 EXAMPLES
-The following example adds two entries to the C<Normal rights>
-section of the current working directory's ACL: the first entry
-grants B<r> (B<read>) and B<l> (B<lookup>)
-permissions to the group B<pat:friends>, while the other (using
-the B<write> shorthand) gives all permissions except B<a>
-(B<administer>) to the user B<smith>.
+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
Normal rights:
pat:friends rl
smith rlidwk
-
-The following example includes the -clear flag, which removes
-the existing permissions (as displayed with the B<fs listacl> command)
-from the current working directory's B<reports> subdirectory and
-replaces them with a new set.
+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
system:anyuser rl
smith rlidwk
pat rlidwka
-
-The following example use the B<-dir> and -acl switches
-because it sets the ACL for more than one directory (both the current working
-
directory and its B<public> subdirectory).
+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
Normal rights:
pat rlidwka
pat:friends rli
-
=head1 PRIVILEGE REQUIRED
-The issuer must have the B<a> (administer) permission on
-the directory's ACL; the directory's owner and the members of
-the B<system:administrators> group have the right implicitly,
-even if it does not appear on the ACL.
+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
=head1 SYNOPSIS
-B<fs setcachesize> [-blocks <I<size in 1K byte blocks (0 => reset)>>]
-[B<-reset>] [B<-help>]
+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>] [-h]
+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>] [-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>] [-h]
+B<fs ca> [B<-b> <I<size in 1K byte blocks (0 => reset)>>]
+ [B<-r>] [B<-h>]
=head1 DESCRIPTION
-The 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.
+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 B</usr/vice/etc/cacheinfo> file, provide a value of
-B<0> to the B<-blocks> argument.
+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
-B<cacheinfo> file, unless the B<-blocks> argument was included
-on the B<afsd> command to override the B<cacheinfo>
-value.
+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.
+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 CAVEATS
+=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.
+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.
+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 -blocks
+=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
-B<0> to set cache size to the default specified in the
-B<cacheinfo> file.
+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 -reset
+=item B<-reset>
Returns the cache size to the value set when the machine was last
-booted. This agrees with the value in the B<cacheinfo> file
-unless the B<-blocks> argument was used on the B<afsd>
-command.
+booted. This agrees with the value in the F<cacheinfo> file unless the
+B<-blocks> argument was used on the B<afsd> command.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=head1 EXAMPLES
-The following command sets the disk cache size to 25000 kilobyte
-blocks.
+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 B<cacheinfo> file, assuming that the B<-blocks> argument
-
to the B<afsd> command was not used.
+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
=head1 NAME
-fs setcell - Allows or disallows running of setuid programs from specified cells
+fs setcell - Configures permissions for setuid programs from specified cells
=head1 SYNOPSIS
-B<fs setcell -cell> <I<cell name>>+ [B<-suid>] [B<-nosuid>] [-help]
+B<fs setcell> B<-cell> <I<cell name>>+ [B<-suid>] [B<-nosuid>] [B<-help>]
-B<fs setce -c> <I<cell name>>+ [B<-s>] [B<-n>] [-h]
+B<fs setce> B<-c> <I<cell name>>+ [B<-s>] [B<-n>] [B<-h>]
=head1 DESCRIPTION
-The 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 B</usr/afs/etc/ThisCell> file. The Cache Manager
-determines its own home cell by reading the B</usr/vice/etc/ThisCell>
-file at initialization.
+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.
+include the B<-suid> flag. To prohibit programs from running with setuid
+permission, include the B<-nosuid> flag, or omit both flags.
-The 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.
+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 fs
-getcellstatus command.
+To display a cell's setuid status, issue the B<fs getcellstatus> command.
-=head1 CAVEATS
+=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.
+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.
+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 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.
+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 -cell
+=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 B</usr/vice/etc/CellServDB>
-file.
+other cells listed in the local F</usr/vice/etc/CellServDB> file.
-=item -suid
+=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.
+privilege. Provide it or the B<-nosuid> flag, or omit both flags to
+disallow programs from running with setuid privilege.
-=item -nosuid
+=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.
+privilege. Provide it or the B<-suid> flag, or omit both flags to disallow
+programs form running with setuid privilege.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=head1 SYNOPSIS
-B<fs setclientaddrs> [B<-address> <I<client network interfaces>>+] [-help]
+B<fs setclientaddrs> [B<-address> <I<client network interfaces>>+] [B<-help>]
-B<fs setcl> [B<-a> <I<client network interfaces>>+] [-h]
+B<fs setcl> [B<-a> <I<client network interfaces>>+] [B<-h>]
-B<fs sc> [B<-a> <I<client network interfaces>>+] [-h]
+B<fs sc> [B<-a> <I<client network interfaces>>+] [B<-h>]
=head1 DESCRIPTION
-The fs setclientaddrs command defines the IP addresses of the
+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.
+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 B</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 B</usr/vice/etc/NetRestrict>
-file. It records the final list in kernel memory. (An
-administrator must create the B<NetInfo> and B<NetRestrict>
-files; there are no default versions of them.)
+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
+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.
+To list the interfaces that the Cache Manager is currently registering
+with File Servers, use the B<fs getclientaddrs> command.
-=head1 CAVEATS
+=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 B</usr/vice/etc/NetInfo> file, or place
-the appropriate B<fs setclientaddrs> command in the machine's AFS
+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 B<NetInfo> file and
-reboot the client machine.
+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> C<interface>.
+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 -address
+=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.
+decimal format. Hostnames are not acceptable. Separate each address with
+one or more spaces.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
The message
- Adding I<interface>
+ 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, B</usr/afs/logs/FileLog>.
+list. The address appears in hexadecimal format to match the notation used
+in the File Server log, F</usr/afs/logs/FileLog>.
=head1 EXAMPLES
=head1 SEE ALSO
-L<NetInfo (client version)(1)>
-
-L<NetRestrict (client version)(1)>
-
-L<fileserver(1)>,
+L<NetInfo(5)>,
+L<NetRestrict(5)>,
+L<fileserver(8)>,
L<fs_getclientaddrs(1)>
=head1 COPYRIGHT
=head1 NAME
-fs setquota - Sets the maximum quota for the volume containing a file or directory
+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>> [-help]
+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>> [-h]
+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>> [-h]
+B<fs sq> [B<-p> <I<dir/file path>>] B<-m> <I<max quota in kbytes>> [B<-h>]
=head1 DESCRIPTION
-The fs setquota command sets the quota (maximum possible size)
-of the read/write volume that contains the directory or file named by the
+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 fs
-setvol command.
+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>, fs
-listquota or B<fs quota> 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 -path
+=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.
+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,
-B</afs/.abc.com>). For further discussion of the
-concept of read/write and read-only paths through the filespace, see the
-B<fs mkmount> reference page.
+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 -max
+=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
-(B<1024> is one megabyte). A value of B<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.
+(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 -path argument is omitted (to set the quota of the volume
+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 -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=head1 EXAMPLES
The following command imposes a maximum quota of 3000 kilobytes on the
-volume that houses the B</afs/abc.com/usr/smith>
-directory:
+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.
+The issuer must belong to the system:administrators group.
=head1 SEE ALSO
=head1 NAME
-fs setserverprefs - Sets the Cache Manager's preference ranks for file server or VL Server
-machines
+fs setserverprefs - Sets the preference ranks for file servers or VL servers
=head1 SYNOPSIS
-B<fs setserverprefs> [-servers <I<fileserver names and ranks>>+]
-[B<-vlservers> <I<VL server names and ranks>>+]
- [B<-file> <I<input from named file>>] [B<-stdin>] [-help]
+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>>+] [-vl <I<VL server names and ranks>>+]
-[B<-f> <I<input from named file>>] [B<-st>] [B<-h>]
+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>>+] [-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 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 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
+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.
-Calculation of Default Preference Ranks
+=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
+(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 B</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.
+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
+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.
+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
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.
-
+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.
-
+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.
-
-Setting Non-default Preference Ranks
-
-Use the 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.
+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:
=item *
The first member of the pair is the fully-qualified hostname (for example,
-B<fs1.abc.com>), or the IP address in dotted decimal
-format, of a file server machine interface or VL Server machine
-
+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 B<1> through B<65535>.
-
+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
+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
=item *
-On the command line, following the -servers argument.
-
+On the command line, following the B<-servers> argument.
=item *
-In a file named by the -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.
-
+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 -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.
-
+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 -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.
+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 -servers
+=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
+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 B<1> through
-B<65521>; a lower value indicates a greater preference.
-Providing ranks outside this range can have unpredictable results.
-Providing a value no larger than B<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 -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 -vlservers
-
-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 B<1> through B<65521>; a lower value
-indicates a greater preference. Providing ranks outside this range can
-have unpredictable results. Providing a value no larger than
-B<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 -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 -file
+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
+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 -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.
+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 -stdin
+=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 B<<Ctrl-d>> after the final newline to
-complete the input.
+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 -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.
+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 -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=head1 EXAMPLES
-The following command sets the Cache Manager's preference ranks for
-the file server machines named B<fs3.abc.com> and
-B<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 B<25000>, to which the
+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 -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
-B</etc/fs.prefs>:
+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
+ # 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:
+The /etc/fs.prefs file has the following contents and format:
192.12.108.214 7500
192.12.108.212 7500
128.0.45.36 41000
128.0.45.37 41000
-The following command uses the -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.
+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 -vlservers argument to set the
-Cache Manager's preferences for the VL server machines named
-B<fs1.abc.com>, B<fs3.abc.com>,
-and B<fs4.abc.com> to base ranks of 1, 11000, and 65521,
+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
+ # fs setserverprefs -vlservers fs1.abc.com 1 fs3.abc.com 11000 \
+ fs4.abc.com 65521
=head1 PRIVILEGE REQUIRED
=head1 NAME
-fs setvol - Set maximum quota and messages for the volume containing a file or
-directory
+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>>+] [-max <I<disk space quota in 1K units>>]
-[B<-offlinemsg> <I<offline message>>] [B<-help>]
+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>>+] [-ma <I<disk space quota in 1K units>>]
-[B<-o> <I<offline message>>] [B<-h>]
+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>>+] [-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 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
+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 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 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 fs setquota
-command.
+To set quota on one volume at a time, use the B<fs setquota> command.
=head1 OPTIONS
=over 4
-=item -path
+=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
+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,
-B</afs/.abc.com>). For further discussion of the
-concept of read/write and read-only paths through the filespace, see the
-B<fs mkmount> reference page.
+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 -max
+=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 (B<1024> is one megabyte). A value of
-B<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.
+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 -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.
+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 -offlinemsg
->
+=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.
+the B<fs examine> command. Its intended use is to explain why the volume
+is currently offline.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=head1 EXAMPLES
The following command imposes a 6500 kilobyte quota on the volumes mounted
-at the home directories B</afs/abc.com/usr/smith> and
-B</afs/abc.com/usr/pat>:
+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.
+The issuer must belong to the system:administrators group.
=head1 SEE ALSO
=head1 SYNOPSIS
-B<fs storebehind> [-kbytes <I<asynchrony for specified names>>]
-[B<-files> <I<specific pathnames>>+]
- [B<-allfiles> <I<new default (KB)>>] [B<-verbose>] [-help]
+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>>] [-f <I<specific pathnames>>+]
-[B<-a> <I<new default (KB)>>] [B<-v>] [B<-h>]
+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 fs storebehind command enables the Cache Manager to perform
-a delayed asynchronous write to the File Server when an application closes a
+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 B<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 B<Cautions> section.
+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:
=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.
-
+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
+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.
-
+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.
+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.
+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 the B<Output> section of this reference page.
+specified in L<OUTPUT>.
-=head1 CAVEATS
+=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.
+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 B<close> system call has already returned with a code indicating
+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:
+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
+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 -kbytes
+=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
+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 B<0> (which
-reinstates the Cache Manager's default behavior or writing synchronously)
-to the maximum AFS file size.
+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 -files
+=item B<-files> <I<specific pathnames>>+
-Names each file to which the value set with the -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.
+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 -allfiles
+=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 B<0> (which indicates the default of
-synchronous writes) to the maximum AFS file size.
+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 -verbose
+=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.
+B<-kbytes> and B<-files> arguments, the B<-allfiles> argument, or all
+three. If provided by itself, reports the current default store
+asynchrony.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=head1 OUTPUT
-If 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
+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 I<x> kbytes.
+ 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.
+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 -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:
+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 I<y> kbytes of I<file> asynchronously.
- Default store asynchrony is I<x> kbytes.
+ 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:
+B<-kbytes> value has been set for it, the message is instead as follows:
- Will store I<file> according to default.
- Default store asynchrony is I<x> kbytes.
+ Will store <file> according to default.
+ Default store asynchrony is <x> kbytes.
-If the -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.
+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 B<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.
+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.
=head1 PRIVILEGE REQUIRED
-To include the -allfiles argument, the issuer must be logged in
-as the local superuser B<root>.
+To include the B<-allfiles> argument, the issuer must be logged in as the
+local superuser C<root>.
-To include the B<-kbytes> and -files arguments, the
-issuer must either be logged in as the local superuser B<root> or have
-the B<w> (B<write>) permission on the ACL of each file's
-directory.
+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.
+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(1)>
+L<afsd(8)>
=head1 COPYRIGHT
=head1 NAME
-fs sysname - Reports the CPU/operating system type
+fs sysname - Reports or sets the CPU/operating system type
=head1 SYNOPSIS
-sys
+B<fs sysname> [B<-newsys> <I<new sysname>>] [B<-help>]
+
+B<fs sy> [B<-n> <I<new sysname>>] [B<-h>]
=head1 DESCRIPTION
-The fs sysname command displays the string stored in kernel memory that
-indicates the local machine's CPU/operating system (OS) type. 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.
+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>>
-The command always reports the value for the local machine only. To
-set a new value in kernel memory, use the B<fs sysname> command, which
-like this command can also be used to display the current value.
+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
-The machine's system type appears as a text string:
+When the B<-newsys> argument is omitted, the output reports the machine's
+system type in the following format:
- I<system_type>
+ Current sysname is '<system_type>'
=head1 EXAMPLES
running Solaris 5.7:
% fs sysname
- sun4x_57
+ 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
-None
+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_sysname(1)>
+L<fs_exportafs(1)>,
+L<sys(1)>
I<IBM AFS Quick Beginnings>
=head1 NAME
-fs whereis - Reports the name of each file server machine housing a file or directory
+fs whereis - Reports each file server housing a file or directory
=head1 SYNOPSIS
-B<fs whereis> [B<-path> <I<dir/file path>>+] [-help]
+B<fs whereis> [B<-path> <I<dir/file path>>+] [B<-help>]
-B<fs whe> [B<-p> <I<dir/file path>>+] [-h]
+B<fs whe> [B<-p> <I<dir/file path>>+] [B<-h>]
=head1 DESCRIPTION
-The fs whereis command returns the name of each file server
-machine that houses the volume containing each directory or file named by the
+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 -path
+=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.
+machine. Partial pathnames are interpreted relative to the current working
+directory, which is also the default value if this argument is omitted.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=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.
+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.
+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
-B</afs/abc.com> resides is replicated on both
-B<fs1.abc.com> and
-B<fs3.abc.com>:
+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 NAME
-fs whichcell - Returns the name of the cell to which a file or directory belongs
+fs whichcell - Returns the cell to which a file or directory belongs
=head1 SYNOPSIS
-B<fs whichcell> [B<-path> <I<dir/file path>>+] [-help]
+B<fs whichcell> [B<-path> <I<dir/file path>>+] [B<-help>]
-B<fs whi > [B<-p> <I<dir/file path>>+] [-h]
+B<fs whi > [B<-p> <I<dir/file path>>+] [B<-h>]
=head1 DESCRIPTION
-The fs whichcell command returns the name of the cell in which
-the volume that houses each indicated directory or file resides.
+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.
+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 -path
+=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 -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=head1 EXAMPLES
-The following example shows that the current working directory resides in a
-volume in the ABC Corporation cell:
+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 SYNOPSIS
-B<fs wscell> [-help]
+B<fs wscell> [B<-help>]
-B<fs ws> [-h]
+B<fs ws> [B<-h>]
=head1 DESCRIPTION
-The fs wscell command returns the name of the local
-machine's home cell.
+The B<fs wscell> command returns the name of the local machine's home
+cell.
=head1 OPTIONS
=over 4
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=head1 OUTPUT
-The output displays the contents of the local
-B</usr/vice/etc/ThisCell> file, in the format
+The output displays the contents of the local F</usr/vice/etc/ThisCell>
+file, in the format
- This workstation belongs to cell 'I<cellname>'
+ 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:
+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 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>] [-lifetime <I<ticket lifetime in hh[:mm[:ss]]>>]
- [B<-setpag>] [B<-tmp>] [-help]
-
-B<klog> [B<-x>] [B<-pr> <I<user name>>] [B<-pa> <I<user's password>>] [-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>] [-h]
+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 klog command obtains an AFS token from the Authentication
+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.
+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 B</etc/passwd> file or
-equivalent).
+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
-B</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 B</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
+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 B</tmp/tktp>I<X> where I<X> is the
-number of the user's PAG.
+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.
+the following.
=over 4
=item *
-The lifetime specified by the issuer with the -lifetime
-argument. If the issuer does not include this argument, the value
-defaults to 720 hours (30 days).
-
+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
-B<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).
-
+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.
+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.
+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.
+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)
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 CAVEATS
+=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
+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.
+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 B<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.
+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 -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.
+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:
-
+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 I<translator_machine> has failed (err=8). . .
+ 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
+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 B<root>, so in most cases its
-local UID (normally zero) does not match the local UID of the user who issued
+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 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.
+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 -x
+=item B<-x>
-Appears only for backwards compatibility. Its former function is
-now the default behavior of this command.
+Appears only for backwards compatibility. Its former function is now the
+default behavior of this command.
-=item -principal
+=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 file system.
+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 -password
+=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.
+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 -cell
+=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
+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
-B</usr/vice/etc/CellServDB> file on the client machine on which 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
+defined
=over 4
=item *
-First, by the value of the environment variable AFSCELL
-
+First, by the value of the environment variable AFSCELL.
=item *
-Second, in the /usr/vice/etc/ThisCell file on the client
-machine on which the command is issued
-
+Second, in the F</usr/vice/etc/ThisCell> file on the client machine on
+which the command is issued.
=back
-=item -servers
+=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.
+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 B</usr/vice/etc/CellServDB> file, and then chooses one of them
+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 -pipe
+=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.
+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 -silent
+=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.
+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 -lifetime
+=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 the
-B<Description> section.
+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 -setpag
+=item B<-setpag>
Creates a process authentication group (PAG) prior to requesting
-authentication. The token is associated with the newly created
-PAG.
+authentication. The token is associated with the newly created PAG.
-=item -tmp
+=item B<-tmp>
-Creates a Kerberos-style ticket file in the /tmp directory of
-the local machine. The file is called
-B<tkt.>I<AFS_UID> where I<AFS_UID> is the AFS UID
-of the issuer.
+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 -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
-=head1 CAVEATS
-
=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).
-
+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 -tmp flag is included, the following message confirms
-that a Kerberos-style ticket file was created:
+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 file
-system. The ticket's lifetime is calculated as described in the
-B<Description> section (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).
-
+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 the
-B<Description> section, the token's lifetime is
-110:44:28, which is the next largest possible value.
+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
+ % klog -lifetime 104:30
Password:
=head1 PRIVILEGE REQUIRED
=head1 SEE ALSO
L<fs_exportafs(1)>,
-L<kas_examine(1)>,
-L<kas_setfields(1)>,
-L<kas_unlock(1)>,
-L<kaserver(1)>,
+L<kas_examine(8)>,
+L<kas_setfields(8)>,
+L<kas_unlock(8)>,
+L<kaserver(8)>,
L<pagsh(1)>,
L<tokens(1)>
=head1 NAME
-knfs - Establishes basis for authenticated access to AFS from a non-supported NFS
-client using the NFS/AFS Translator
+knfs - Establishes authenticated access via the NFS/AFS Translator
=head1 SYNOPSIS
-B<knfs -host> <I<host name>> [-id <I<user ID (decimal)>>]
-[B<-sysname> <I<host's '@sys' value>>] [B<-unlog>] [B<-tokens>] [B<-help>]
+B<knfs> B<-host> <I<host name>> [B<-id> <I<user ID (decimal)>>]
+ [B<-sysname> <I<host's '@sys' value>>] [B<-unlog>] [B<-tokens>]
+ [B<-help>]
-B<knfs -ho> <I<host name>> [-i <I<user ID (decimal)>>]
-[B<-s> <I<host's '@sys' value>>] [B<-u>] [B<-t>] [B<-he>]
+B<knfs> B<-ho> <I<host name>> [B<-i> <I<user ID (decimal)>>]
+ [B<-s> <I<host's '@sys' value>>] [B<-u>] [B<-t>] [B<-he>]
=head1 DESCRIPTION
-The knfs command creates an AFS credential structure on the
-local machine, identifying it by a process authentication group (PAG) number
-associated with the NFS client machine named by the B<-hostname>
-argument and by default with a local UID on the NFS client machine that
-matches the issuer's local UID on the local machine. It places in
-the credential structure the AFS tokens that the issuer has previously
-obtained (by logging onto the local machine if an AFS-modified login utility
-is installed, by issuing the B<klog> command, or both). To
-associate the credential structure with an NFS UID that does not match the
-issuer's local UID, use the B<-id> argument.
+The B<knfs> command creates an AFS credential structure on the local
+machine, identifying it by a process authentication group (PAG) number
+associated with the NFS client machine named by the B<-hostname> argument
+and by default with a local UID on the NFS client machine that matches the
+issuer's local UID on the local machine. It places in the credential
+structure the AFS tokens that the issuer has previously obtained (by
+logging onto the local machine if an AFS-modified login utility is
+installed, by issuing the B<klog> command, or both). To associate the
+credential structure with an NFS UID that does not match the issuer's
+local UID, use the B<-id> argument.
Issue this command only on the NFS(R)/AFS translator machine that is
-serving the NFS client machine, after obtaining AFS tokens on the translator
-machine for every cell to which authenticated access is required. The
-Cache Manager on the translator machine uses the tokens to obtain
-authenticated AFS access for the designated user working on the NFS client
-machine. This command is not effective if issued on an NFS client
+serving the NFS client machine, after obtaining AFS tokens on the
+translator machine for every cell to which authenticated access is
+required. The Cache Manager on the translator machine uses the tokens to
+obtain authenticated AFS access for the designated user working on the NFS
+client machine. This command is not effective if issued on an NFS client
machine.
-To enable the user on the NFS client machine to issue AFS commands, use the
-B<-sysname> argument to specify the NFS client machine's system
-type, which can differ from the translator machine's. The NFS
-client machine must be a system type for which AFS is supported.
+To enable the user on the NFS client machine to issue AFS commands, use
+the B<-sysname> argument to specify the NFS client machine's system type,
+which can differ from the translator machine's. The NFS client machine
+must be a system type for which AFS is supported.
-The -unlog flag discards the tokens in the credential structure,
-but does not destroy the credential structure itself. The Cache Manager
-on the translator machine retains the credential structure until the next
-reboot, and uses it each time the issuer accesses AFS through the translator
+The B<-unlog> flag discards the tokens in the credential structure, but
+does not destroy the credential structure itself. The Cache Manager on the
+translator machine retains the credential structure until the next reboot,
+and uses it each time the issuer accesses AFS through the translator
machine. The credential structure only has tokens in it if the user
-reissues the B<knfs> command on the translator machine each time the
-user logs into the NFS client machine.
+reissues the B<knfs> command on the translator machine each time the user
+logs into the NFS client machine.
-To display the tokens associated with the designated user on the NFS client
-machine, include the B<-tokens> flag.
+To display the tokens associated with the designated user on the NFS
+client machine, include the B<-tokens> flag.
-Users working on NFS client machines of system types for which AFS binaries
-are available (and for which the cell has purchased a license) can use the
-B<klog> command rather than the B<knfs> command.
+Users working on NFS client machines of system types for which AFS
+binaries are available can use the B<klog> command rather than the B<knfs>
+command.
-=head1 CAVEATS
+=head1 CAUTIONS
If the translator machine's administrator has enabled UID checking by
-issuing the B<fs exportafs> command with the B<-uidcheck on>
-argument, it is not possible to use the B<-id> argument to assign the
-tokens to an NFS UID that differs from the issuer's local UID. In
-this case, there is no point in including the B<-id> argument, because
-the only acceptable value (the issuer's local UID) is the value used when
-the B<-id> argument is omitted. Requiring matching UIDs is
-effective only when users have the same local UID on the translator machine as
-on NFS client machines. In that case, it guarantees that users assign
-their tokens only to their own NFS sessions.
+issuing the B<fs exportafs> command with the B<-uidcheck on> argument, it
+is not possible to use the B<-id> argument to assign the tokens to an NFS
+UID that differs from the issuer's local UID. In this case, there is no
+point in including the B<-id> argument, because the only acceptable value
+(the issuer's local UID) is the value used when the B<-id> argument is
+omitted. Requiring matching UIDs is effective only when users have the
+same local UID on the translator machine as on NFS client machines. In
+that case, it guarantees that users assign their tokens only to their own
+NFS sessions.
This command does not make it possible for users working on non-supported
-system types to issue AFS commands. This is possible only on NFS
-clients of a system type for which AFS is available.
+system types to issue AFS commands. This is possible only on NFS clients
+of a system type for which AFS is available.
=head1 OPTIONS
=over 4
-=item -host
+=item B<-host> <I<host name>>
-Names the NFS client machine on which the issuer is to work.
-Providing a fully-qualified hostname is best, but abbreviated forms are
-possibly acceptable depending on the state of the cell's name server at
-the time the command is issued.
+Names the NFS client machine on which the issuer is to work. Providing a
+fully-qualified hostname is best, but abbreviated forms are possibly
+acceptable depending on the state of the cell's name server at the time
+the command is issued.
-=item -id
+=item B<-id> <I<user ID (decimal)>>
Specifies the local UID on the NFS client to which to assign the
tokens. The NFS client identifies file requests by the NFS UID, so
-creating the association enables the Cache Manager on the translator machine
-to use the appropriate tokens when filling the requests. If this
-argument is omitted, the command interpreter uses an NFS UID that matches the
-issuer's local UID on the translator machine (as returned by the
-B<getuid> function).
-
-=item -sysname
-
-Specifies the value that the local (translator) machine's remote
-executor daemon substitutes for the B<@sys> variable in pathnames when
-executing AFS commands issued on the NFS client machine (which must be a
-supported system type). If the NFS user's PATH environment
-variable uses the B<@sys> variable in the pathnames for directories
-that house AFS binaries (as recommended), then setting this argument enables
-NFS users to issue AFS commands by leading the remote executor daemon to
-access the AFS binaries appropriate to the NFS client machine even if its
-system type differs from the translator machine's.
-
-=item -unlog
+creating the association enables the Cache Manager on the translator
+machine to use the appropriate tokens when filling the requests. If this
+argument is omitted, the command interpreter uses an NFS UID that matches
+the issuer's local UID on the translator machine (as returned by the
+getuid() function).
+
+=item B<-sysname> <I<host's '@sys' value>>
+
+Specifies the value that the local (translator) machine's remote executor
+daemon substitutes for the I<@sys> variable in pathnames when executing
+AFS commands issued on the NFS client machine (which must be a supported
+system type). If the NFS user's PATH environment variable uses the I<@sys>
+variable in the pathnames for directories that house AFS binaries (as
+recommended), then setting this argument enables NFS users to issue AFS
+commands by leading the remote executor daemon to access the AFS binaries
+appropriate to the NFS client machine even if its system type differs from
+the translator machine's.
+
+=item B<-unlog>
Discards the tokens stored in the credential structure identified by the
-PAG associated with the B<-host> argument and, optionally, the
-B<-id> argument.
+PAG associated with the B<-host> argument and, optionally, the B<-id>
+argument.
-=item -tokens
+=item B<-tokens>
Displays the AFS tokens assigned to the designated user on the indicated
NFS client machine.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
translator machine and that the value provided for the B<-id> argument
differs from the issuer's local UID.
-
- knfs: Translator in 'passwd sync' mode; remote uid must be the same as local uid
+ knfs: Translator in 'passwd sync' mode; remote uid must be the same as
+ local uid
=head1 EXAMPLES
The following example illustrates a typical use of this command. The
-issuer B<smith> is working on the machine
-B<nfscli1.abc.com> and has user ID B<1020> on
-that machine. The translator machine
-B<tx4.abc.com> uses an AFS-modified login utility, so
-B<smith> obtains tokens for the ABC Corporation cell automatically
-upon login via the B<telnet> program. She then issues the
-B<klog> command to obtain tokens as B<admin> in the ABC
-Corporation's test cell, B<test.abc.com>, and the
-B<knfs> command to associate both tokens with the credential structure
-identified by machine name B<nfs-cli1> and user ID
-B<1020>. She breaks the connection to B<tx4> and works
-on B<nfscli1>.
+issuer C<smith> is working on the machine C<nfscli1.abc.com> and has user
+ID C<1020> on that machine. The translator machine C<tx4.abc.com> uses an
+AFS-modified login utility, so C<smith> obtains tokens for the ABC
+Corporation cell automatically upon login via the B<telnet> program. She
+then issues the B<klog> command to obtain tokens as C<admin> in the ABC
+Corporation's test cell, C<test.abc.com>, and the B<knfs> command to
+associate both tokens with the credential structure identified by machine
+name C<nfs-cli1> and user ID C<1020>. She breaks the connection to C<tx4>
+and works on C<nfscli1>.
% telnet tx4.abc.com
. . .
% knfs nfscli1.abc.com 1020
% exit
-
-The following example shows user smith again connecting to the
-machine B<tx4> via the B<telnet> program and discarding the
-tokens.
+The following example shows user smith again connecting to the machine
+C<tx4> via the B<telnet> program and discarding the tokens.
% telnet translator4.abc.com
. . .
=head1 SYNOPSIS
-B<kpasswd> [B<-x>] [B<-principal> <I<user name>>] [-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>] [-help]
+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>>] [-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>] [-h]
+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 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 B</etc/passwd> file or equivalent).
+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 B</usr/afs/etc/CellServDB> file on
-the local disk; it chooses the machine at random. It consults the
-B</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 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.
+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:
=item *
-If the program 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 the B<kpwvalid> reference
-page.
-
+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:
-
+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:
+To prevent a user from subverting this restriction by changing the
+password twenty times in quick succession (manually or by running a
+script), use the B<-minhours> argument on the B<kaserver> initialization
+command. The following error message appears if a user attempts to change
+a password before the minimum time has passed:
Password was not changed because you changed it too
recently; see your systems administrator
=over 4
-=item -x
+=item B<-x>
Appears only for backwards compatibility.
-=item -principal
+=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 -password
+=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:
+Specifies the current password. Omit this argument to have the command
+interpreter prompt for the password, which does not echo visibly:
- Old password: I<current_password>
+ Old password: current_password
-=item -newpassword
+=item B<-newpassword> <I<user's new password>>
-Specifies the new password, which the 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.
+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:
+Omit this argument to have the command interpreter prompt for the
+password, which does not echo visibly:
- New password (RETURN to abort): I<new_password>
- Retype new password: I<new_password>
+ New password (RETURN to abort): <new_password>
+ Retype new password: <new_password>
-=item -cell
+=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 B</usr/vice/etc/CellServDB>
-file.
+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
=item *
-First, by the value of the environment variable AFSCELL
-
+First, by the value of the environment variable AFSCELL.
=item *
-Second, in the /usr/vice/etc/ThisCell file on the client
-machine on which the command is issued
-
+Second, in the F</usr/vice/etc/ThisCell> file on the client machine on
+which the command is issued.
=back
-=item -servers
+=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
-B</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.
+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 -pipe
+=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.
+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 -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=head1 EXAMPLES
-The following example shows user pat changing her password in
-the ABC Corporation cell.
+The following example shows user pat changing her password in the ABC
+Corporation cell.
% kpasswd
Changing password for 'pat' in cell 'abc.com'.
=head1 SEE ALSO
-L<kas_setfields(1)>,
-L<kas_setpassword(1)>,
+L<kas_setfields(8)>,
+L<kas_setpassword(8)>,
L<klog(1)>,
-L<kpwvalid(1)>
+L<kpwvalid(8)>
=head1 COPYRIGHT
+++ /dev/null
-=head1 NAME
-
-package - Configures files and directories on the local disk
-
-=head1 SYNOPSIS
-
-B<package> [B<initcmd>] [-config <I<base name of configuration file>>]
-[B<-fullconfig> <I<full name of configuration file, or stdin for standard input>>]
- [B<-overwrite>] [B<-noaction>] [B<-verbose>] [B<-silent>] [-rebootfiles]
- [B<-debug>] [-help]
-
-B<package> [B<i>] [-c <I<base name of configuration file>>]
-[B<-f> <I<full name of configuration file, or stdin for standard input>>]
- [B<-o>] [B<-n>] [B<-v>] [B<-s>] [B<-r>] [B<-d>] [-h]
-
-=head1 DESCRIPTION
-
-The package command configures the machine's local disk to
-comply with the instructions in the configuration file named by the
-B<-config> or B<-fullconfig> argument.
-
-By default, the package command alters any existing local disk
-element whose contents or configuration does not match the element defined in
-the configuration file. For example, if a configuration file
-B<D> instruction defines a directory that has the same name as a
-symbolic link on the local disk, the B<package> command replaces the
-symbolic link with the directory. The B<F> and B<L>
-instructions include an optional I<update_code> field that alters this
-behavior.
-
-Also by default, the package command takes no action on elements
-on the local disk that are not mentioned in the configuration file. Use
-the B<D> instruction's B<R> update code to remove files
-from the disk directory that are not mentioned in the configuration
-file.
-
-Before running the package command, the administrator must
-create the template file and other files on the local disk. For
-instructions, see the I<IBM AFS Administration Guide>.
-
-It is not possible to configure a remote client machine's disk using
-this command.
-
-=head1 CAVEATS
-
-The package command interpreter exits without executing any
-instruction if there are any syntax errors or incorrect values in the
-configuration file.
-
-=head1 OPTIONS
-
-=over 4
-
-=item initcmd
-
-Accommodates the command's use of the AFS command parser, and is
-optional.
-
-=item -config
-
-Specifies the pathname of the configuration file to use, ending in the
-file's base name, which omits the suffix that indicates the machine
-type. The B<package> command determines the machine's
-system type name and automatically appends it to the base name. An
-example of the proper value for this argument is B<staff> rather than
-B<staff.rs_aix42>. Partial pathnames are interpreted
-relative to the current working directory.
-
-Provide this argument or the -fullconfig argument.
-
-=item -fullconfig
-
-Specifies the configuration file to use. Two types of values are
-acceptable:
-
-=over 4
-
-=item *
-
-The full pathname of the configuration file to use, complete with an
-extension indicating the machine type (examples:
-B<staff.rs_aix42>, B<admin.sun4x_56>).
-
-
-=item *
-
-The string stdin to indicate that the issuer is providing
-configuration information via the standard input stream, either by piping in
-the contents of a file, or by typing configuration lines at the shell.
-In the latter case, type B<<Ctrl-d>> to conclude the input.
-
-
-=back
-
-Provide this argument or the -config argument.
-
-=item -overwrite
-
-Overwrites elements on the local disk with the source version indicated in
-the configuration file, even if the owner B<write> (B<w>) mode
-bit is turned on the disk element. Files protected by the B<I>
-update code on an B<F> line in the configuration file are not
-overwritten.
-
-=item -noaction
-
-Checks the sequence of operations to be performed when the command
-actually runs and reports any problems that the B<package> command
-interpreter expects to encounter. No elements on the local disk or in
-AFS are changed. If the B<-verbose> flag is also provided, the
-trace includes all actions to be performed as well as anticipated
-errors.
-
-=item -silent
-
-Suppresses some of the trace messages sent to the standard output stream
-by default. The output still reports major problems.
-
-=item -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 -rebootfiles
-
-Prevents overwriting of any file marked with the Q update code
-on an B<F> line in the configuration file. This effectively
-prevents the machine from rebooting automatically again when the
-B<package> command is invoked in the machine's AFS initialization
-file.
-
-=item -debug
-
-Enables debugging output, which is directed to the standard output stream
-by default. By default, no debugging output is produced.
-
-=item -help
-
-Prints the online help for this command. All other valid options
-are ignored.
-
-=back
-
-=head1 EXAMPLES
-
-This command is usually invoked in a client machine's AFS
-initialization file (B</etc/rc> or equivalent), rather than issued at
-the command shell prompt.
-
-The following command invokes the version of the staff
-configuration file appropriate for this machine's system type, and
-produces verbose output.
-
- # /etc/package -c staff -v
-
-The following example uses the configuration file whose basename is defined
-in the B</.package> file on the local machine. This
-method enables the administrator to use the same B<package> command in
-every machine's AFS initialization file but still customize configuration
-by putting the appropriate basename in the B</.package>
-file.
-
- # /etc/package -c `cat /.package` -v
-
-=head1 PRIVILEGE REQUIRED
-
-The issuer must be logged in as the local superuser root.
-
-=head1 SEE ALSO
-
-L<package Configuration File(1)>
-
-=head1 COPYRIGHT
-
-IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
-
-This documentation is covered by the IBM Public License Version 1.0. It was
-converted from HTML to POD by software written by Chas Williams and Russ
-Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
+++ /dev/null
-=head1 NAME
-
-package apropos - Displays each help entry containing a keyword string
-
-=head1 SYNOPSIS
-
-B<package apropos> [B<-topic> <I<help string>>] [-help]
-
-B<package a> [B<-t> <I<help string>>] [-h]
-
-=head1 DESCRIPTION
-
-The package apropos command displays the first line of the
-online help entry for any B<package> command that has in its name or
-short description the string specified by the B<-topic>
-argument.
-
-To display the syntax for a command, use the package help
-command.
-
-=head1 OPTIONS
-
-=over 4
-
-=item -topic
-
-Specifies the keyword string to match, in lowercase letters only.
-If the string is more than a single word, surround it with double quotes ("")
-or other delimiters.
-
-=item -help
-
-Prints the online help for this command. All other valid options
-are ignored.
-
-=back
-
-=head1 OUTPUT
-
-The first line of a command's online help entry names it and briefly
-describes its function. This command displays the first line for any
-B<package> command where the string specified with the
-B<-topic> argument is part of the command name or first line.
-
-=head1 EXAMPLES
-
-The following command lists all package commands that include
-the word B<help> in their names or short descriptions:
-
- % package apropos help
- apropos: search by help text
- help: get help on commands
-
-=head1 PRIVILEGE REQUIRED
-
-None
-
-=head1 SEE ALSO
-
-L<package(1)>,
-L<package_help(1)>
-
-=head1 COPYRIGHT
-
-IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
-
-This documentation is covered by the IBM Public License Version 1.0. It was
-converted from HTML to POD by software written by Chas Williams and Russ
-Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
+++ /dev/null
-=head1 NAME
-
-package help - Displays the syntax of specified package commands or lists
-functional descriptions of all B<package> commands
-
-=head1 SYNOPSIS
-
-B<package help> [B<-topic> <I<help string>>+] [-help]
-
-B<package h> [B<-t> <I<help string>>+] [-h]
-
-=head1 DESCRIPTION
-
-The package help command displays the complete online help entry
-(short description and syntax statement) for each command operation code
-specified by the B<-topic> argument. If the B<-topic>
-argument is omitted, the output includes the first line (name and short
-description) of the online help entry for every B<package>
-command.
-
-To list every package command whose name or short description
-includes a specified keyword, use the B<package apropos>
-command.
-
-=head1 OPTIONS
-
-=over 4
-
-=item -topic
-
-Indicates each command for which to display the complete online help
-entry. Omit the B<package> part of the command name, providing
-only the operation code (for example, specify B<initcmd>, not
-B<package initcmd>). If this argument is omitted, the output
-briefly describes every B<package> command.
-
-=item -help
-
-Prints the online help for this command. All other valid options
-are ignored.
-
-=back
-
-=head1 OUTPUT
-
-The online help entry for each package command consists of the
-following two or three lines:
-
-=over 4
-
-=item *
-
-The first line names the command and briefly describes its
-function.
-
-
-=item *
-
-The second line lists aliases for the command, if any.
-
-
-=item *
-
-The final line, which begins with the string C<Usage>, lists the
-command's options in the prescribed order. Online help entries use
-the same symbols (for example, brackets) as the reference pages in this
-document.
-
-
-=back
-
-=head1 EXAMPLES
-
-The following command displays the online help entry for the package
-initcmd command:
-
- % package help initcmd
- package initcmd: initialize the program
- Usage: package [initcmd] [-config <base name of configuration file>]
- [-fullconfig <full name of configuration file, or stdin for standard input>]
- [-overwrite] [-noaction] [-verbose] [-silent] [-rebootfiles]
- [-debug] [-help]
-
-=head1 PRIVILEGE REQUIRED
-
-None
-
-=head1 SEE ALSO
-
-L<package(1)>,
-L<package_apropos(1)>
-
-=head1 COPYRIGHT
-
-IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
-
-This documentation is covered by the IBM Public License Version 1.0. It was
-converted from HTML to POD by software written by Chas Williams and Russ
-Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
+++ /dev/null
-=head1 NAME
-
-package_test - Tests the validity of a package configuration file
-
-=head1 SYNOPSIS
-
-package_test <I<config file>>
-
-This command does not use the syntax conventions of the AFS command
-suites. Provide the command name in full.
-
-=head1 DESCRIPTION
-
-The package_test command tests the validity of a
-B<package> configuration file created when a prototype file is
-compiled. The command interpreter prints error messages on the standard
-output stream.
-
-=head1 OPTIONS
-
-=over 4
-
-=item I<config file
->
-
-Specifies the package configuration file to validate.
-
-=back
-
-=head1 EXAMPLES
-
-The following example tests the validity of the package
-configuration file I<staff.sun4x_56>.
-
- % package_test staff.sun4x_56
-
-=head1 PRIVILEGE REQUIRED
-
-None
-
-=head1 SEE ALSO
-
-L<package Configuration File(1)>
-
-L<package(1)>
-
-=head1 COPYRIGHT
-
-IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
-
-This documentation is covered by the IBM Public License Version 1.0. It was
-converted from HTML to POD by software written by Chas Williams and Russ
-Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
=head1 SYNOPSIS
-pagsh
+B<pagsh>
=head1 DESCRIPTION
-The 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.
+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.
+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 B<root>) that the AFS server
-processes recognize only as B<anonymous>. Unless PAGs are used,
-such daemons cannot access files in directories whose access control lists
-(ACLs) do not extend permissions to the B<system:anyuser>
-group.
-
+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 B<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 B<root> can assume a UNIX UID and use any tokens
-associated with that UID. Use of a PAG as an identifier eliminates that
-possibility.
-
+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 CAVEATS
+=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 the B<Description> section.
+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 the reference page for the
-B<klog> command.
+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 B<root>. The complete set of mode bits must
-be B<-rwsr-xr-x>. This is not a requirement when the command is
-issued on AFS client machines.
+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:
-
+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 I<translator_machine> has failed (err=8). . .
+ Warning: Remote setpag to <translator_machine> has failed (err=8). . .
setpag: Exec format error
=head1 EXAMPLES
=head1 DESCRIPTION
-The commands in the 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
+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.)
+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.
+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:
+There are several categories of commands in the pts command suite:
=over 4
=item *
-Commands to create and remove Protection Database entries: pts
-creategroup, B<pts createuser>, and B<pts delete>
-
+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: pts
-adduser,
-
-
-B<pts listowned>, B<pts membership>, and pts
-removeuser
+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>
-
+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>
-
+and groups: B<pts listmax> and B<pts setmax>.
=item *
-Commands to obtain help: B<pts apropos> and pts
-help
-
+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.
+B<pts> suite. The reference page for each command also lists them, but
+they are described here in greater detail.
=over 4
-=item -cell <I<cell name>
->
+=item B<-cell> <I<cell name>>
-Names the cell in which to run the command. It is acceptable to
-abbreviate the cell name to the shortest form that distinguishes it from the
-other entries in the B</usr/vice/etc/CellServDB> file on the local
-machine. If the B<-cell> argument is omitted, the command
-interpreter determines the name of the local cell by reading the following in
-order:
+Names the cell in which to run the command. It is acceptable to abbreviate
+the cell name to the shortest form that distinguishes it from the other
+entries in the F</usr/vice/etc/CellServDB> file on the local machine. If
+the B<-cell> argument is omitted, the command interpreter determines the
+name of the local cell by reading the following in order:
-=item *
+=over 4
-The value of the AFSCELL environment variable
+=item *
+The value of the AFSCELL environment variable.
=item *
-The local /usr/vice/etc/ThisCell file
+The local F</usr/vice/etc/ThisCell> file.
+=back
-=item -force
-
+=item B<-force>
-L<(1)>
-Enables the command to continue executing as far as possible when errors or
-other problems occur, rather than halting execution immediately.
+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
+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.
-L<(1)>
-
-=item -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<-help>
-=item -noauth
+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>
-L<(1)>
-Establishes an unauthenticated connection to the Protection Server, in which
-the server treats the issuer as the unprivileged user
-B<anonymous>. It is useful only when authorization checking is
-disabled on the server machine (during the installation of a file server
-machine or when the B<bos setauth> command has been used during other
-unusual circumstances). In normal circumstances, the 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.
+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.
+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.
+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
=head1 SYNOPSIS
-B<pts adduser -user> <I<user name>>+ -group <I<group name>>+
-[B<-cell> <I<cell name>>] [B<-noauth>] [B<-force>] [B<-help>]
+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 -u> <I<user name>>+ B<-g> <I<group name>>+ [B<-c> <I<cell name>>] [B<-n>] [B<-f>] [-h]
+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 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.
+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 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.
+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 CAVEATS
+=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
=over 4
-=item -user
+=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.
+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 -group
+=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.
+each group to which to add members. The group entry must already exist in
+the Protection Database.
-=item -cell
+=item B<-cell> <I<cell name>>
Names the cell in which to run the command. For more details, see
-the introductory B<pts> reference page.
+L<pts(1)>.
-=item -noauth
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. For more details, see the introductory B<pts> reference
-page.
+Assigns the unprivileged identity anonymous to the issuer. For more
+details, see L<pts(1)>.
-=item -force
+=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.
+or other problems occur, rather than halting execution at the first error.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=head1 EXAMPLES
-The following example adds user smith to the group
-B<system:administrators>.
+The following example adds user smith to the group system:administrators.
% pts adduser -user smith -group system:administrators
-The following example adds users B<jones>, terry, and
-B<pat> to the B<smith:colleagues> group.
+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 B<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).
+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>
+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
-B<system:administrators> group can add members.
-
+system:administrators group can add members.
=item *
-If it is lowercase C<a>, current members of the group can add new
-members.
-
+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.
-
+If it is uppercase C<A>, anyone who can access the cell's database server
+machines can add new members.
=back
=head1 SYNOPSIS
-B<pts apropos -topic> <I<help string>> [-help]
+B<pts apropos> B<-topic> <I<help string>> [B<-help>]
-B<pts ap -t> <I<help string>> [-h]
+B<pts ap> B<-t> <I<help string>> [B<-h>]
=head1 DESCRIPTION
-The 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.
+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 pts help
-command.
+To display the syntax for a command, use the B<pts help> command.
=head1 OPTIONS
=over 4
-=item -topic
+=item B<-topic> <I<help string>>
-Specifies the keyword string to match, in lowercase letters only.
-If the string is more than a single word, surround it with double quotes ("")
-or other delimiters.
+Specifies the keyword string to match, in lowercase letters only. If the
+string is more than a single word, surround it with double quotes ("") or
+other delimiters.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
The first line of a command's online help entry names it and briefly
describes its function. This command displays the first line for any
-B<pts> command in which the string specified by the B<-topic>
-argument is part of the command name or first line.
+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 B<create> in their names or short descriptions:
+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
=head1 SYNOPSIS
-B<pts chown -name> <I<group name>> -owner <I<new owner>>
-[B<-cell> <I<cell name>>] [B<-noauth>] [B<-force>] [B<-help>]
+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 -na> <I<group name>> B<-o> <I<new owner>> [B<-c> <I<cell name>>] [B<-no>] [B<-f>] [-h]
+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 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.
+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
+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.
+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 B<system:administrators>
-group.
+default set at creation time, the system:administrators group.
-=head1 CAVEATS
+=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.
+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 -name
+=item B<-name> <I<group name>>
-Specifies the current name of the group to which to assign a new
-owner.
+Specifies the current name of the group to which to assign a new owner.
-=item -owner
+=item B<-owner> <I<new owner>>
Names the user or group to become the group's owner.
-=item -cell
+=item B<-cell> <I<cell name>>
Names the cell in which to run the command. For more details, see
-the introductory B<pts> reference page.
+L<pts(1)>.
-=item -noauth
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. For more details, see the introductory B<pts> reference
-page.
+Assigns the unprivileged identity anonymous to the issuer. For more
+details, see L<pts(1)>.
-=item -force
+=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.
+or other problems occur, rather than halting execution at the first error.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=head1 EXAMPLES
-The following example changes the owner of the group
-B<terry:friends> from the user B<terry> to the user
-B<pat>. A side effect is that the group name changes to
-B<pat:friends>.
+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
-B<terry:friends> from the user B<terry> to the group
-B<pat:buddies>. A side effect is that the group name
-changes to B<pat:friends>.
+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.
+The issuer must belong to the system:administrators group or currently own
+the group.
=head1 SEE ALSO
=head1 SYNOPSIS
-B<pts creategroup -name> <I<group name>>+ [-owner <I<owner of the group>>]
-[B<-id> <I<id (negated) for the group>>+] [B<-cell> <I<cell name>>]
- [B<-noauth>] [B<-force>] [-help]
-
-B<pts createg -na> <I<group name>>+ [-o <I<owner of the group>>]
-[B<-i> <I<id (negated) for the group>>+] [B<-c> <I<cell name>>]
- [B<-no>] [B<-f>] [-h]
+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 -na> <I<group name>>+ [-o <I<owner of the group>>]
-[B<-i> <I<id (negated) for the group>>+]
- [B<-c> <I<cell name>>] [B<-no>] [B<-f>] [-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 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.
+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:
=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.
-
+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 B<system:administrators> group can create
-prefix-less groups.
-
+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.
+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 B<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.
+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
I<name> has id I<AFS GID>
+ group
<name> has id <AFS GID>
-=head1 CAVEATS
+=head1 CAUTIONS
-Although using the -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.
+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 -name
+=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,
+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
-(B<:>) to separate the two parts of the name; the colon
-cannot appear in a prefix-less group name.
+(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:
- I<owner_name>:I<group_name>
+ <owner_name>:<group_name>
-and the I<owner_name> field must reflect the actual owner of the
-group, as follows:
+and the <owner_name> field must reflect the actual owner of the group, as
+follows:
=over 4
=item *
-If the optional -owner argument is not included, the field must
-match the AFS username under which the issuer is currently
-authenticated.
-
+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 -owner argument names an alternate AFS user, the field
-must match that AFS username.
-
+If the B<-owner> argument names an alternate AFS user, the field must
+match that AFS username.
=item *
-If the -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.
-
+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 -owner
+=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.
+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 -id
+=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 (B<->) to indicate that it is negative.
+hyphen (C<->) to indicate that it is negative.
-If this argument is used and the -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.
+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 -cell
+=item B<-cell> <I<cell name>>
Names the cell in which to run the command. For more details, see
-the introductory B<pts> reference page.
+L<pts(1)>.
-=item -noauth
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. For more details, see the introductory B<pts> reference
-page.
+Assigns the unprivileged identity anonymous to the issuer. For more
+details, see L<pts(1)>.
-=item -force
+=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.
+or other problems occur, rather than halting execution at the first error.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=head1 EXAMPLES
In the following example, the user pat creates groups called
-
B<pat:friends> and B<pat:colleagues>.
+
C<pat:friends> and C<pat:colleagues>.
% pts creategroup -name pat:friends pat:colleagues
-The following example shows a member of the
-B<system:administrators> group creating the prefix-less group
-B<staff> and assigning its ownership to the
-B<system:administrators> group rather than to herself.
+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
-B<smith:team-members>, which is allowed because the
-B<-owner> argument specifies the required value
-(B<smith>).
+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.
+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
=item *
-Be authenticated. The command fails if the -noauth flag
-is provided.
-
+Be authenticated. The command fails if the B<-noauth> flag is provided.
=item *
-Have a group-creation quota greater than zero. The pts
-examine command displays this quota.
-
+Have a group-creation quota greater than zero. The B<pts examine> command
+displays this quota.
=back
=head1 SYNOPSIS
-B<pts createuser -name> <I<user name>>+ [B<-id> <I<user id>>+] [-cell <I<cell name>>]
-[B<-noauth>] [B<-force>] [B<-help>]
+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 -na> <I<user name>>+ [B<-i> <I<user id>>+] [-c <I<cell name>>]
-[B<-no>] [B<-f>] [B<-h>]
+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 -na> <I<user name>>+ [B<-i> <I<user id>>+] [B<-c> <I<cell name>>] [B<-no>] [B<-f>] [-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 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 pts createuser command is recorded as the
-entry's creator and the group B<system:administrators> as
-its owner.
-
-=head1 CAVEATS
-
-The Protection Server reserves AFS UID 0 (zero) and returns an error if the
-B<-id> argument has that value.
+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 -name
+=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:
+or wildcarded) for a machine entry:
=over 4
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 (B<:>) and at-sign (B<@>) 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
-B<pat.admin>.
-
+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 B<W>, B<X>, B<Y> and B<Z> each
-represent an actual number from the range 1 through 255.
-
+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 B<192.12.108.240>.
-
+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,
-B<192.12.108.0> matches both
-B<192.12.108.119> and
-B<192.12.108.120>, but does not match
-B<192.12.105.144>.
-
+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
-B<192.12.0.0> matches both
-B<192.12.106.23> and
-B<192.12.108.120>, but does not match
-B<192.5.30.95>.
-
+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 B<192.0.0.0> matches both
-B<192.5.30.95> and
-B<192.12.108.120>, but does not match
-B<138.255.63.52>.
-
+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
-B<0.0.0.0> to match every machine. The
-B<system:anyuser> group is equivalent.
+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 -id
+=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.
+the Protection Server to assign it. Provide a positive integer.
-If this argument is used and the -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,
+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.
+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 -cell
+=item B<-cell> <I<cell name>>
Names the cell in which to run the command. For more details, see
-the introductory B<pts> reference page.
+L<pts(1)>.
-=item -noauth
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. For more details, see the introductory B<pts> reference
-page.
+Assigns the unprivileged identity anonymous to the issuer. For more
+details, see L<pts(1)>.
-=item -force
+=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.
+or other problems occur, rather than halting execution at the first error.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
The command generates the following string to confirm creation of each
user:
- User I<name> has id I<id>
+ User <name> has id <id>
=head1 EXAMPLES
The following example creates a Protection Database entry for the user
-B<johnson>.
+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:
+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.
+The issuer must belong to the system:administrators group.
=head1 SEE ALSO
=head1 SYNOPSIS
-B<pts delete -nameorid> <I<user or group name or id>>+ [-cell <I<cell name>>]
-[B<-noauth>] [B<-force>] [B<-help>]
+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 -na> <I<user or group name or id>>+ [B<-c> <I<cell name>>] [B<-no>] [B<-f>] [-h]
+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 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:
+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
+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.
-
+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.
-
+group-creation quota of the group's creator by one, even if the creator no
+longer owns the group.
=back
=over 4
-=item -nameorid
+=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.
+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 -cell
+=item B<-cell> <I<cell name>>
Names the cell in which to run the command. For more details, see
-the introductory B<pts> reference page.
+L<pts(1)>.
-=item -noauth
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. For more details, see the introductory B<pts> reference
-page.
+Assigns the unprivileged identity anonymous to the issuer. For more
+details, see L<pts(1)>.
-=item -force
+=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.
+or other problems occur, rather than halting execution at the first error.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=head1 EXAMPLES
-The following example deletes the user entries pat and
-B<terry>:
+The following example deletes the user entries C<pat> and C<terry>:
% pts delete pat terry
=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
-B<system:administrators> group.
+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
=head1 SYNOPSIS
-B<pts examine -nameorid> <I<user or group name or id>>+ [-cell <I<cell name>>]
-[B<-noauth>] [B<-force>] [B<-help>]
+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 -na> <I<user or group name or id>>+ [B<-c> <I<cell name>>] [B<-no>] [B<-f>] [-h]
+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 -na> <I<user or group name or id>>+ [-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 -na> <I<user or group name or id>>+ [-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 pts examine command displays information from the Protection
+The B<pts examine> command displays information from the Protection
Database entry of each user, machine or group specified by the
B<-nameorid> argument.
=over 4
-=item -nameorid
+=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.
+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 -cell
+=item B<-cell> <I<cell name>>
Names the cell in which to run the command. For more details, see
-the introductory B<pts> reference page.
+L<pts(1)>.
-=item -noauth
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. For more details, see the introductory B<pts> reference
-page.
+Assigns the unprivileged identity anonymous to the issuer. For more
+details, see L<pts(1)>.
-=item -force
+=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.
+or other problems occur, rather than halting execution at the first error.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=over 4
-=item C<Name
->
+=item Name
The contents of this field depend on the type of entry:
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.
-
+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.
-
+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 C<id
->
+=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
+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.
-L<(1)>
-L<(1)>
-=item C<owner
->
+=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
-B<system:administrators> group in this field for user and
-machine entries at creation time.
-L<(1)>
+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 C<creator
->
+=item creator
-The user who issued the B<pts createuser> or pts
-creategroup command to create the entry. This field serves as an
-audit trail, and cannot be changed.
-L<(1)>
+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 C<membership
->
+=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.
+which the user or machine belongs. For groups, it represents the number of
+group members.
-=item C<flags
->
+=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.
+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 pts examine command to display the
-entry.
+Controls who can issue the B<pts examine> command to display the entry.
=item o
-Controls who can issue the pts listowned command to display the
-groups that a user or group owns.
+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 pts membership command to display
-the groups a user or machine belongs to, or which users or machines belong to
-a group.
+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 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.
+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 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.
+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:
+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
-B<system:administrators> group and the entry's
-owner. For user entries, it designates the user in addition.
-
+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.
-
+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
-B<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 B<system:administrators>
-group can perform other functions.
-
-=item C<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.
-L<(1)>
-L<(1)>
+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 terry and the
-machine entry B<158.12.105.44>.
+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,
=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:
+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
-B<system:administrators> group and the user associated with a
-user entry can examine it, and only members of the
-B<system:administrators> group can examine a machine or group
-entry.
-
+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.
-
+If it is uppercase C<S>, anyone who can access the cell's database server
+machines can examine the entry.
=back
=head1 NAME
-pts help - Displays the syntax of specified pts commands or lists
-functional descriptions for all B<pts> commands
+pts help - Displays help for pts commands
=head1 SYNOPSIS
-B<pts help> [B<-topic> <I<help string>>+] [-help]
+B<pts help> [B<-topic> <I<help string>>+] [B<-help>]
-B<pts h> [B<-t> <I<help string>>+] [-h]
+B<pts h> [B<-t> <I<help string>>+] [B<-h>]
=head1 DESCRIPTION
-The 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.
+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.
+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 -topic
+=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 B<membership>, not B<pts
-membership>). If this argument is omitted, the output briefly
-
describes every B<pts> command.
+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 -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=head1 OUTPUT
-The online help entry for each pts command consists of the
-following two or three lines:
+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.
-
+The first line names the command and briefly describes its function.
=item *
The second line lists aliases for the command, if any.
-
=item *
-The final line, which begins with the string C<Usage>, lists the
-command's options in the prescribed order. Online help entries use
-the same symbols (for example, brackets) as the reference pages in this
-document.
-
+The final line, which begins with the string C<Usage>, lists the command's
+options in the prescribed order. Online help entries use the same symbols
+(for example, brackets) as the reference pages in this document.
=back
=head1 EXAMPLES
-The following command displays the online help entry for the pts
-membership command:
+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
=head1 NAME
-pts listentries - Displays all user or group entries in the Protection Database
+pts listentries - Displays all users or groups in the Protection Database
=head1 SYNOPSIS
-B<pts listentries> [B<-users>] [B<-groups>] [-cell <I<cell name>>]
-[B<-noauth>] [B<-force>] [B<-help>]
+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>] [-h]
+B<pts liste> [B<-u>] [B<-g>] [B<-c> <I<cell name>>] [B<-n>] [B<-f>] [B<-h>]
=head1 DESCRIPTION
-The pts listentries command displays the name and AFS ID of all
+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.
+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 -users
+=item B<-users>
Displays user and machine entries.
-=item -groups
+=item B<-groups>
Displays group entries.
-=item -cell
+=item B<-cell> <I<cell name>>
Names the cell in which to run the command. For more details, see
-the introductory B<pts> reference page.
+L<pts(1)>.
-=item -noauth
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. For more details, see the introductory B<pts> reference
-page.
+Assigns the unprivileged identity anonymous to the issuer. For more
+details, see L<pts(1)>.
-=item -force
+=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.
+or other problems occur, rather than halting execution at the first error.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=head1 OUTPUT
-The output includes a line for each entry, with information in four columns
-that have the following headers:
+The output includes a line for each entry, with information in four
+columns that have the following headers:
=over 4
-=item C<Name
->
+=item Name
-The entry's name
+The entry's name.
-=item C<ID
->
+=item ID
-The entry's AFS ID (AFS UID for a user or machine, negative AFS GID
-for a group)
+The entry's AFS ID (AFS UID for a user or machine, negative AFS GID for a
+group).
-=item C<Owner
->
+=item Owner
-The AFS ID of the user or group that owns the entry
+The AFS ID of the user or group that owns the entry.
-=item C<Creator
->
+=item Creator
-The AFS ID of the user who created the entry (the
-B<system:administrators> group is listed as the creator of the
-entry for B<anonymous> and the system groups, but it is not otherwise
-possible for a group to create groups)
+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.
+In general, the entries appear in the order in which they were created.
=head1 EXAMPLES
=head1 PRIVILEGE REQUIRED
-The issuer must belong to the system:administrators
-group.
+The issuer must belong to the system:administrators group.
=head1 SEE ALSO
=head1 NAME
-pts listmax - Displays the C<max user id> and C<max group id> counters
+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>] [-help]
+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>] [-h]
+B<pts listm> [B<-c> <I<cell name>>] [B<-n>] [B<-f>] [B<-h>]
=head1 DESCRIPTION
-The 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
-B<system:administrators> group can issue the B<pts
-setmax> command.
+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 -cell
+=item B<-cell> <I<cell name>>
Names the cell in which to run the command. For more details, see
-the introductory B<pts> reference page.
+L<pts(1)>.
-=item -noauth
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. For more details, see the introductory B<pts> reference
-page.
+Assigns the unprivileged identity anonymous to the issuer. For more
+details, see L<pts(1)>.
-=item -force
+=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.
+or other problems occur, rather than halting execution at the first error.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
The command displays the counters in the following format:
- Max user id is I<user_counter> and max group id is I<group_counter>.
+ Max user id is <user_counter> and max group id is <group_counter>.
=head1 EXAMPLES
=head1 NAME
-pts listowned - Displays the Protection Database groups owned by a user or group
+pts listowned - Show the Protection Database groups owned by a user or group
=head1 SYNOPSIS
-B<pts listowned -nameorid> <I<user or group name or id>>+ [-cell <I<cell name>>]
-[B<-noauth>] [B<-force>] [B<-help>]
+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 -na> <I<user or group name or id>>+ [-c <I<cell name>>]
-[B<-no>] [B<-f>] [B<-h>]
+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 pts listowned command lists the groups owned by each user or
-group specified by the B<-nameorid> argument.
+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 B<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.
+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 -nameorid
+=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
+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.
+A value of 0 (zero) lists group entries for groups whose owners no longer
+have entries in the Protection Database.
-=item -cell
+=item B<-cell> <I<cell name>>
Names the cell in which to run the command. For more details, see
-the introductory B<pts> reference page.
+L<pts(1)>.
-=item -noauth
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. For more details, see the introductory B<pts> reference
-page.
+Assigns the unprivileged identity anonymous to the issuer. For more
+details, see L<pts(1)>.
-=item -force
+=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.
+or other problems occur, rather than halting execution at the first error.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
each user or group for which ownership information is requested, in the
following format:
- Groups owned by I<name> (id: I<ID>) are:
+ 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.
+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
-B<system:administrators> group.
+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 I<name> (id: I<ID>)
+ 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 B<terry:friends> does not own any
-groups:
+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:
=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):
+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 -nameorid argument specifies a
-group, only the members of the B<system:administrators> group
-and the owner of a group can list the groups it owns.
-
+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 -nameorid argument specifies a
-user, only the members of the B<system:administrators> group and
-the associated user can list the groups he or she owns.
-
+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.
-
+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 SYNOPSIS
-B<pts membership -nameorid> <I<user or group name or id>>+ [-cell <I<cell name>>]
-[B<-noauth>] [B<-force>] [B<-help>]
+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 -na> <I<user or group name or id>>+ [B<-c> <I<cell name>>] [B<-no>] [B<-f>] [-h]
+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 -na> <I<user or group name or id>>+ [-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 -na> <I<user or group name or id>>+ [B<-c> <I<cell name>>] [B<-no>] [B<-f>] [-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 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.
+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
-B<system:anyuser> or B<system:authuser> groups,
-and they do not appear in the list of groups to which a user belongs.
+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.
+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 -nameorid
+=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.
+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 -cell
+=item B<-cell> <I<cell name>>
Names the cell in which to run the command. For more details, see
-the introductory B<pts> reference page.
+L<pts(1)>.
-=item -noauth
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. For more details, see the introductory B<pts> reference
-page.
+Assigns the unprivileged identity anonymous to the issuer. For more
+details, see L<pts(1)>.
-=item -force
+=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.
+or other problems occur, rather than halting execution at the first error.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
line, followed by a list of the groups to which the user or machine
belongs:
- Groups
I<name> (id: I<AFS UID>) is a member of:
+ 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
I<group_name> (id: I<AFS GID>) are:
+ Members of
<group_name> (id: <AFS GID>) are:
=head1 EXAMPLES
-The following example lists the groups to which the user pat
-belongs and the members of the group B<smith:friends>.
-Note that third privacy flag for the B<pat> entry was changed from the
-default hyphen to enable a non-administrative user to obtain this
-listing.
+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:
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):
+B<-nameorid> argument (use the B<pts examine> command to display the
+flags):
=over 4
=item *
-If it is the hyphen and the -nameorid argument specifies a
-user, only the associated user and members of the
-B<system:administrators> group can list the groups to which the
-user belongs.
-
+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 -nameorid argument specifies a
-machine, only the members of the B<system:administrators> group
-can list the groups to which the machine belongs.
-
+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 -nameorid argument specifies a
-group, only the owner of the group and members of the
-B<system:administrators> group can list the members of the
-group.
-
+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 -nameorid argument
-specifies a user or machine entry, the meaning is equivalent to the
-hyphen.
-
+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 -nameorid argument
-specifies a group, members of the group can also list the other
-members.
-
+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.
-
+If it is uppercase C<M>, anyone who can access the cell's database server
+machines can list group memberships.
=back
=head1 SYNOPSIS
-B<pts removeuser -user> <I<user name>>+ -group <I<group name>>+
-[B<-cell> <I<cell name>>] [B<-noauth>] [B<-force>] [B<-help>]
+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 -u> <I<user name>>+ B<-g> <I<group name>>+ [-c <I<cell name>>]
-[B<-n>] [B<-f>] [B<-h>]
+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 pts removeuser command removes each user or machine named by
-the B<-user> argument from each group named by the B<-group>
-argument.
+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 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.
+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 CAVEATS
+=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.
+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 -name
+=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 -group
+=item B<-group> <I<group name>>+
Names each group from which to remove members.
-=item -cell
+=item B<-cell> <I<cell name>>
Names the cell in which to run the command. For more details, see
-the introductory B<pts> reference page.
+L<pts(1)>.
-=item -noauth
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. For more details, see the introductory B<pts> reference
-page.
+Assigns the unprivileged identity anonymous to the issuer. For more
+details, see L<pts(1)>.
-=item -force
+=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.
+or other problems occur, rather than halting execution at the first error.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=head1 EXAMPLES
-The following example removes user smith from the groups
-B<staff> and B<staff:finance>. Note that no
-switch names are necessary because only a single instance is provided for the
-first argument (the username).
+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
-B<bin-prot>:
+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):
+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
-B<system:administrators> group can remove members.
-
+system:administrators group can remove members.
=item *
-If it is lowercase C<r>, members of the group can also remove
-other members.
-
+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>.)
+(It is not possible to set the fifth flag to uppercase C<R>.)
=head1 SEE ALSO
=head1 SYNOPSIS
-B<pts rename -oldname> <I<old name>> -newname <I<new name>>
-[B<-cell> <I<cell name>>] [B<-noauth>] [B<-force>] [B<-help>]
+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 -o> <I<old name>> B<-ne> <I<new name>> [B<-c> <I<cell name>>] [B<-no>] [B<-f>] [-h]
+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 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).
+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.
+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 pts chown command
+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 CAVEATS
+=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
+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>.
=over 4
-=item -oldname
+=item B<-oldname> <I<old name>>
Specifies the current full name of the entry.
-=item -newname
+=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.
+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 -cell
+=item B<-cell> <I<cell name>>
Names the cell in which to run the command. For more details, see
-the introductory B<pts> reference page.
+L<pts(1)>.
-=item -noauth
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. For more details, see the introductory B<pts> reference
-page.
+Assigns the unprivileged identity anonymous to the issuer. For more
+details, see L<pts(1)>.
-=item -force
+=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.
+or other problems occur, rather than halting execution at the first error.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=head1 EXAMPLES
-The following example changes the name of the group staff, owned
-by the privileged user B<admin>, to
-B<admin:staff>:
+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
-B<admin:finance> to the group B<finance>. The
-issuer must belong to the B<system:administrators> group.
+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
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
-B<system:administrators> group.
+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
-B<system:administrators> group.
+system:administrators group.
=head1 SEE ALSO
=head1 NAME
-pts setfields - Sets privacy flags or the group-creation quota for a Protection Database
-entry.
+pts setfields - Sets privacy flags or quota for a Protection Database entry
=head1 SYNOPSIS
-pts setfields -nameorid <I<user or group name or id>>+
-[B<-access> <I<set privacy flags>>]
- [-groupquota <I<set limit on group creation>>]
- [B<-cell> <I<cell name>>] [B<-noauth>] [B<-force>] [-help]
+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 -na> <I<user or group name or id>>+ [-a <I<set privacy flags>>]
-[B<-g> <I<set limit on group creation>>] [B<-c> <I<cell name>>]
- [B<-no>] [B<-f>] [-h]
+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 pts setfields command sets the group-creation quota, the
-privacy flags, or both, associated with each user, machine, or group entry
+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 pts
-examine command.
+To examine the current quota and privacy flags, use the B<pts examine>
+command.
-=head1 CAVEATS
+=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.
+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. The B<Arguments> section specifies the
-appropriate settings.
+interpretation. L<OPTIONS> specifies the appropriate settings.
=head1 OPTIONS
=over 4
-=item -nameorid
+=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.
+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 -access
+=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.
+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 the
-B<pts examine> reference page.
+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 pts examine command
-to display information from a user, machine or group's Protection
-Database entry.
-
+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 s to permit the members of the
-B<system:administrators> group to display a user, machine, or
-group entry, and the associated user to display a user entry.
-
+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 S to permit anyone who can access the
-cell's database server machines to display a user, machine, or group
-entry.
-
+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 pts listowned
-command to list the groups that a user or group owns.
-
+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 (-) to permit the members of the
-B<system:administrators> group and a user to list the groups he
-or she owns, or to permit the members of the
-B<system:administrators> group and a group's owner to list
-the groups that a group owns.
-
+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 O to permit anyone who can access
-the cell's database server machines to list the groups owned by a machine
-or group entry.
-
+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 pts membership
-command to list the groups to which a user or machine belongs, or the users
-and machines that belong to a group.
-
+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 (-) to permit the members of the
-B<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
-B<system:administrators> group and a group's owner to list
-the users and machines that belong to it.
-
+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 m to permit members of a group to list the
-other members. (For user and machine entries, this setting is
-equivalent to the hyphen.)
-
+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 M to permit anyone who can access the
-cell's database server machines to list membership information for a
-user, machine or group.
-
+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 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.
-
+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 (-) to permit the members of the
-B<system:administrators> group and the owner of the group to add
-members.
-
+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 a to permit members of a group to add other
+Set it to lowercase C<a> to permit members of a group to add other
members.
-
=item *
-Set it to uppercase A to permit anyone who can access the
-cell's database server machines to add members to a group.
-
+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 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.
-
+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 (-) to permit the members of the
-B<system:administrators> group and the owner of the group to
-remove members.
-
+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 r to permit members of a group to remove
-other members.
-
+Set it to lowercase C<r> to permit members of a group to remove other
+members.
=back
=back
-=item -groupquota
+=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 -cell
+=item B<-cell> <I<cell name>>
Names the cell in which to run the command. For more details, see
-the introductory B<pts> reference page.
+L<pts(1)>.
-=item -noauth
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. For more details, see the introductory B<pts> reference
-page.
+Assigns the unprivileged identity anonymous to the issuer. For more
+details, see L<pts(1)>.
-=item -force
+=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.
+or other problems occur, rather than halting execution at the first error.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=head1 EXAMPLES
-The following example changes the privacy flags on the group
-B<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.
+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 B<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 B<admin> owns and belongs to.
-Users authenticated as B<admin> can create an additional 50
-groups.
+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
-B<system:administrators> group. To set group-creation
-quota on a user entry, the issuer must belong to the
-B<system:administrators> group.
+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
=head1 NAME
-pts setmax - Sets the value of the C<max group id> or C<max user id>
-counter
+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>>] [-cell <I<cell name>>]
-[B<-noauth>] [B<-force>] [B<-help>]
+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>] [-h]
+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 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.
+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 pts listmax command to display the current value of both
+Use the B<pts listmax> command to display the current value of both
counters.
=head1 OPTIONS
=over 4
-=item -group
+=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.
+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 -user
+=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.
+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 -cell
+=item B<-cell> <I<cell name>>
Names the cell in which to run the command. For more details, see
-the introductory B<pts> reference page.
+L<pts(1)>.
-=item -noauth
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. For more details, see the introductory B<pts> reference
-page.
+Assigns the unprivileged identity anonymous to the issuer. For more
+details, see L<pts(1)>.
-=item -force
+=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.
+or other problems occur, rather than halting execution at the first error.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=head1 EXAMPLES
-The following command sets the C<max group id> counter to -500 and
-the C<max user id> counter to 1000.
+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.
+The issuer must belong to the system:administrators group.
=head1 SEE ALSO
=head1 SYNOPSIS
-B<rxdebug -servers> <I<server machine>> [B<-port> <I<IP port>>] [-nodally]
-[B<-allconnections>] [B<-rxstats>] [B<-onlyserver>] [B<-onlyclient>]
- [B<-onlyport> <I<show only <port>>>] [-onlyhost <I<show only <host>>>]
- [B<-onlyauth> <I<show only <auth level>>>] [B<-version>] [-noconns]
- [B<-peers>] [-help]
-
-B<rxdebug -s> <I<server machine>> [B<-po> <I<IP port>>] [B<-nod>] [B<-a>] [-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>] [-h]
+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 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.
+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 -servers
+=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,
-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.
+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 -port
+=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:
+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)
-B<7000> for the File Server (fileserver process)
-
-
-7001 for the Cache Manager (specifically, its callback
-interface)
-
-
-B<7002> for the Protection Server (ptserver process)
-
-
-B<7003> for the Volume Location (VL) Server (vlserver
-process)
-
-
-B<7004> for the Authentication Server (kaserver
-process)
-
+=item C<7001> for the Cache Manager (specifically, its callback interface)
-B<7005> for the Volume Server (volserver process)
+=item C<7002> for the Protection Server (B<ptserver> process)
+=item C<7003> for the Volume Location (VL) Server (B<vlserver> process)
-B<7007> for the BOS Server (bosserver process)
+=item C<7004> for the Authentication Server (B<kaserver> process)
+=item C<7005> for the Volume Server (B<volserver> process)
-B<7008> for the Update Server (upserver process)
+=item C<7007> for the BOS Server (B<bosserver> process)
+=item C<7008> for the Update Server (B<upserver> process)
-B<7009> for the NFS/AFS Translator's rmtsysd
-daemon
+=item C<7009> for the NFS/AFS Translator's B<rmtsysd> daemon
-
-B<7021> for the Backup Server (buserver process)
-
-
-B<7025> through 65535 for the Backup Tape Coordinator
-(B<butc> process) that has the port offset number derived by
-subtracting 7025 from this value
+=item C<7021> for the Backup Server (B<buserver> process)
=back
-=item -nodally
+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 -allconnections
+=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.
+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 -rxstats
+=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
+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 -onlyserver
+=item B<-onlyserver>
Produces output only for connections in which the process designated by
the B<-port> argument is acting as the server.
-=item -onlyclient
+=item B<-onlyclient>
Produces output only for connections in which the process designated by
the B<-port> argument is acting as the client.
-=item -onlyport
+=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.
+B<-port> argument and the specified port on any another machine. Use the
+same port identifiers as for the B<-port> argument.
-=item -onlyhost
+=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.
+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 -onlyauth
+=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 for connections at authentication level
-B<rxkad_auth>
+=item auth
+Cconnections at authentication level rxkad_auth
-=item *
+=item clear
-clear for connections at authentication level
-B<rxkad_clear>
+Connections at authentication level rxkad_clear
+=item crypt
-=item *
+Connections at authentication level rxkad_crypt
-crypt for connections at authentication level
-B<rxkad_crypt>
-
-
-=item *
-
-none for unauthenticated connections (equivalents are
-B<null>, B<noauth>, and B<unauth>)
+=item none
+Unauthenticated connections (equivalents are C<null>, C<noauth>, and
+C<unauth>)
=back
-=item -version
+=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.
+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 -noconns
+=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.
+connections. Any other options combined with this one are ignored.
-=item -peers
+=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.
+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 -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=head1 OUTPUT
-If any options other than B<-version> or -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 the preceding
-B<Options> section of this reference page. The output is
-intended for debugging purposes and is meaningful to someone familiar with the
+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
=head1 SEE ALSO
-L<afsd(1)>,
-L<bosserver(1)>,
-L<buserver(1)>,
-L<butc(1)>,
-L<fileserver(1)>,
-L<kaserver(1)>,
-L<ptserver(1)>,
-L<upclient(1)>,
-L<upserver(1)>,
-L<vlserver(1)>,
-L<volserver(1)>
+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
=head1 SYNOPSIS
-B<scout> [B<initcmd>] -server <I<FileServer name(s) to monitor>>+
-[B<-basename> <I<base server name>>]
- [B<-frequency> <I<poll frequency, in seconds>>] [-host]
- [-attention <I<specify attention (highlighting) level>>+]
- [B<-debug> <I<turn debugging output on to the named file>>] [-help]
-
-B<scout> [B<i>] -s <I<FileServer name(s) to monitor>>+
-[B<-b> <I<base server name>>] [B<-f> <I<poll frequency, in seconds>>]
- [B<-ho>] [-a <I<specify attention (highlighting) level>>+]
- [B<-d> <I<turn debugging output on to the named file>>] [-he]
+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. The B<Output> section 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.
+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 CAVEATS
+=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 B<curses> as a standard utility.
+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 B<vt100>, as long as the terminal is
+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 B<xterm>, B<xterms>,
-B<vt100>, B<vt200>, and B<wyse85>.
+acceptable values includes C<xterm>, C<xterms>, C<vt100>, C<vt200>, and
+C<wyse85>.
=head1 OPTIONS
=over 4
-=item initcmd
+=item B<initcmd>
-Accommodates the command's use of the AFS command parser, and is
-optional.
+Accommodates the command's use of the AFS command parser, and is optional.
-=item -server
+=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
+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.
+resolution service (such as the Domain Name Service or a local host table)
+at the time the command is issued.
-=item -basename
+=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
-B<abc.com> rather than
-B<.abc.com>.
+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 -frequency
+=item B<-frequency> <I<poll frequency>>
-Indicates how often to probe the File Server processes. Specify a
-number of seconds greater than B<0> (zero). The default is 60
-seconds.
+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 -host
+=item B<-host>
-Displays the name of the machine that is running the scout
-program, in the banner line of the display screen.
+Displays the name of the machine that is running the scout program, in the
+banner line of the display screen.
-=item -attention
+=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:
+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.
+=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, which takes one of two types of values:
-
-
-=over 4
-
-=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.
+=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 *
-
-B<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 B<0> to B<99>, followed by the
-percent sign (B<%>) to distinguish this type of value from the one
-described just previously.
+=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%.
-=back
-
-=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.
+=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.
+=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.
+=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 -debug
+=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.
+trace. Partial pathnames are interpreted relative to the current working
+directory.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=head1 OUTPUT
-The 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> 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 scout screen has three main parts: the banner line,
-the statistics display region and the message/probe line.
+The B<scout> screen has three main parts: the banner line, the statistics
+display region and the message/probe line.
-I<The Banner 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:
+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 -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.
-
+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 -host flag is included and the
-B<scout> program is running on the machine
-B<client1.abc.com>, the banner line reads as
-follows:
+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 -basename argument displays the indicated basename on the
-banner line. For example, including the argument B<-basename
-abc.com> argument results in the following banner line:
-
+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
-I<The Statistics Display Region>
+=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
+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:
-L<(1)>
-L<(1)>
+The region is divided into six columns, labeled as indicated and
+displaying the following information:
=over 4
-=item *
+=item Conn
-C<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.
-L<(1)>
+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
-=item *
+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.
-C<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.
-L<(1)>
+=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 *
+=item Ws
-C<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.
-L<(1)>
+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 *
-
-C<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.
-L<(1)>
-L<(1)>
-L<(1)>
-
-
-=item *
+=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.
+(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
-=item *
-
-C<Disk attn>: The sixth column displays the number of
-available kilobyte blocks on each AFS disk partition on the file server
-machine.
-L<(1)>
-L<(1)>
-L<(1)>
-The display for each partition has the following form:
+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:I<free_blocks>
+ x:<free_blocks>
-where C<x> indicates the partition name. For example,
-C<B<a:8949>> specifies that the B</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
+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> C<attn> column indicates the
-threshold value at which entries in the column become highlighted. By
-default, the label is
+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.
+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.
+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
+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
-I<The Message/Probe Line>
+=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.
+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
=head1 SEE ALSO
L<afsmonitor(1)>,
-L<fstrace(1)>
+L<fstrace(8)>
=head1 COPYRIGHT
--- /dev/null
+=head1 NAME
+
+sys - Reports the CPU/operating system type
+
+=head1 SYNOPSIS
+
+sys
+
+=head1 DESCRIPTION
+
+The B<sys> command displays the string stored in kernel memory that
+indicates the local machine's CPU/operating system (OS) type. 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.
+
+The command always reports the value for the local machine only. To set a
+new value in kernel memory, use the B<fs sysname> command, which like this
+command can also be used to display the current value.
+
+=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)>
+
+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.
=head1 SYNOPSIS
-B<tokens> [-help]
+B<tokens> [B<-help>]
-B<tokens> [-h]
+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.
+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 -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
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.
-
+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,
-B<krbtgt.ABC.COM>), and ticket's expiration
-date.
+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.
+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.
+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.
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:
+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 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.
+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
=head1 SYNOPSIS
-translate_et <I<error number>>+
-
-This command does not use the syntax conventions of the AFS command
-suites. Provide the command name in full.
+B<translate_et> <I<error number>>+
=head1 DESCRIPTION
-The translate_et command translates each specified error number
-into a text message.
+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
->
+=item <I<error number>>+
Specifies each error number to translate.
=head1 NAME
-udebug - Reports status of Ubik process associated with a database server process
+udebug - Reports Ubik process status for a database server process
=head1 SYNOPSIS
-B<udebug -servers> <I<server machine>> [B<-port> <I<IP port>>] [B<-long>] [-help]
-
-B<udebug -s> <I<server machine>> [B<-p> <I<IP port>>] [B<-l>] [-h]
+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 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.
+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 -servers
+=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.
+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 -port
+=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.
+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
-B<buserver> or 7021 for the Backup Server
-
-
-B<kaserver> or 7004 for the Authentication Server
+=item B<kaserver> or 7004 for the Authentication Server
+=item B<ptserver> or 7002 for the Protection Server
-B<ptserver> or 7002 for the Protection Server
-
-
-B<vlserver> or 7003 for the Volume Location Server
+=item B<vlserver> or 7003 for the Volume Location Server
=back
-=item -long
+=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.
+B<-servers> argument. The information appears by default if that machine
+is the synchronization site.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
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 . . . (I<#_sites> servers)
+ 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>.
+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 I<IP_addr> time is I<dbserver_date/time>
- Local time is I<local_date/time> (time differential I<skew> secs)
-
-The I<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: I<list_of_IP_addrs>
- Host's I<IP_addr> time is I<dbserver_date/time>
- Local time is I<local_date/time> (time differential I<skew> secs)
-
-If the I<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.
+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.
+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 I<sync_IP_addr> was I<last_vote> secs ago (sync site);
- Last vote started I<vote_start> secs ago (at I<date/time>)
- Local db version is I<db_version>
+ 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
-I<last_vote> and I<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
-I<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.
+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.
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 -servers argument
-names the coordinator (synchronization site), the output continues with the
+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 I<expiration> secs from now (at I<date/time>) (I<#_sites> servers)
- Recovery state I<flags>
-
-The first message 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:
+ 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 C<0x1
->
+=item 0x1
-This machine is the coordinator
+This machine is the coordinator.
-=item C<0x2
->
+=item 0x2
The coordinator has determined which site has the database with the
-highest version number
+highest version number.
-=item C<0x4
->
+=item 0x4
-The coordinator has a copy of the database with the highest version number
+The coordinator has a copy of the database with the highest version
+number.
-=item C<0x8
->
+=item 0x8
-The database's version number has been updated correctly
+The database's version number has been updated correctly.
-=item C<0x10
->
+=item 0x10
-All sites have the database with the highest version number
+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.
+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 -servers argument names a secondary site, the output
-continues with the following messages.
-
+If the B<-servers> argument names a secondary site, the output continues
+with the following messages.
I am not sync site
- Lowest host I<lowest_IP_addr> was set I<low_time> secs ago
- Sync host I<sync_IP_addr> was set I<sync_time> secs ago
-
-The I<lowest_IP_addr> is the lowest IP address of any peer from which
-the Ubik process has received a message recently, whereas the
-I<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 I<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.
+ 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
-I<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.
+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 I<db_version>
- I<locked> locked pages, I<writes> of them for write
+ 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 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:
+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 I<tid>
+ Transaction tid is <tid>
-If the machine named by the -servers argument is the
-coordinator, the next message reports when the current coordinator last
-updated the database.
+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:
- I<last_restart> secs ago (at I<date/time>)
+ <last_restart> secs ago (at <date/time>)
-If the machine named by the -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.
+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( I<IP_address> ): (db I<db_version>)
- last vote rcvd I<last_vote> secs ago (at I<date/time>),
- last beacon sent I<last_beacon> secs ago (at I<date/time>), last vote was { yes | no }
+ 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 I<last_vote> field reports
-how long ago the coordinator received a vote message from the Ubik process at
-the site, and the I<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.
+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:
+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
-
+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
-
+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
-
+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 -long flag produces peer entries even when the
+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 I<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.
+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 B<afs1>, which is the synchronization
-site.
+Server on the machine C<afs1>, which is the synchronization site.
% udebug afs1 vlserver
Host's addresses are: 192.12.107.33
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.
+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
=head1 PRIVILEGE REQUIRED
+None
+
=head1 SEE ALSO
-L<buserver(1)>,
-L<kaserver(1)>,
-L<ptserver(1)>,
-L<vlserver(1)>
+L<buserver(8)>,
+L<kaserver(8)>,
+L<ptserver(8)>,
+L<vlserver(8)>
=head1 COPYRIGHT
=head1 SYNOPSIS
-B<unlog> [B<-cell> <I<cell name>>+] [-help]
+B<unlog> [B<-cell> <I<cell name>>+] [B<-help>]
-B<unlog> [B<-c ><I<cell name>>+] [-h]
+B<unlog> [B<-c ><I<cell name>>+] [B<-h>]
=head1 DESCRIPTION
-The 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.
+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.
+Since a token pertains to one client machine only, destroying tokens on
+one machine has no effect on tokens on another machine.
-=head1 CAVEATS
+=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.
+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 -cell
+=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.
+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 -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
% unlog
-The following command discards only the tokens for the
-B<abc.com> and B<stateu.edu> cells.
+The following command discards only the tokens for the C<abc.com> and
+C<stateu.edu> cells.
% unlog -cell abc.com stateu
=head1 NAME
-up - Recursively copies the contents of a source directory to a destination
-directory.
+up - Recursively copy directories, preserving AFS metadata
=head1 SYNOPSIS
-B<up> [B<-v>] [B<-1>] [B<-f>] [B<-r>] [-x] <I<source directory>> <I<destination directory>>
-
-This command does not use the syntax conventions of the AFS command
-suites. Provide the command name and all option names in full.
+B<up> [B<-v>] [B<-1>] [B<-f>] [B<-r>] [B<-x>]
+ <I<source directory>> <I<destination directory>>
=head1 DESCRIPTION
-The 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
+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
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 B<system:administrators>,
-then the source directory's owner (as reported by the B<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.
-
+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) B<w> (B<write>)
-mode bit is turned off on the version in the destination directory, unless the
-B<-f> flag is provided.
-
+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 ls -l
+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.
-
+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
+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 0 (zero) only
-if it succeeds. Otherwise, it returns a status code of B<1>
-(one).
+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 -v
+=item B<-v>
-Prints a detailed trace to the standard output stream as the command
-runs.
+Prints a detailed trace to the standard output stream as the command runs.
-=item -1
+=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
-B<l>.)
+source directory's ACL still overwrites the destination directory's. (This
+is the number one, not the letter C<l>.)
-=item -f
+=item B<-f>
Overwrites existing directories, subdirectories, and files even if the
-first (user) B<w> (B<write>) mode bit is turned off on the
-version in the destination directory.
+first (user) C<w> (write) mode bit is turned off on the version in the
+destination directory.
-=item -r
+=item B<-r>
Creates a backup copy of all files overwritten in the destination
-directory and its subdirectories, by adding a B<.old> extension
-to each filename.
+directory and its subdirectories, by adding a C<.old> extension to each
+filename.
-=item -x
+=item B<-x>
Sets the modification timestamp on each file to the time of the copying
operation.
-=item I<source directory
->
+=item I<source directory>
Names the directory to copy recursively.
-=item I<destination directory
->
+=item I<destination directory>
-Names the directory to which to copy. It does not have to exist
-already.
+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 I<dir1> to
-directory I<dir2>:
+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 B<a> (administer) permission on
-the ACL of both the source and destination directories.
+The issuer must have the C<a> (administer) permission on the ACL of both
+the source and destination directories.
=head1 COPYRIGHT
=head1 DESCRIPTION
-The commands in the vos command suite are the administrative
-interface to the Volume Server and Volume Location (VL) Server. System
+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 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
+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 <B<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. The reference pages for the files
-B<vldb.DB0> and
-B<V>I<vol_ID>B<.vol> 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:
+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: vos backup,
-B<vos backupsys>, B<vos create>, B<vos move>, and
-B<vos rename>
-
+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: vos
-delentry, B<vos remove>, and B<vos zap>
-
+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: vos
-changeaddr and B<vos listaddrs>
-
+Commands to edit or display VLDB server entries: B<vos changeaddr> and
+B<vos listaddrs>.
=item *
-Commands to create and restore dump files: vos dump and
-B<vos restore>
-
+Commands to create and restore dump files: B<vos dump> and B<vos restore>.
=item *
-Commands to administer replicated volumes: vos addsite,
-B<vos release>, and B<vos remsite>
-
+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: vos
-examine, B<vos listvldb>, and B<vos listvol>
-
+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>
-
+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>
-
+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: vos lock,
-B<vos unlock>, and B<vos unlockvldb>
-
+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: vos status
-
+A command to report Volume Server status: B<vos status>.
=item *
-Commands to obtain help: B<vos apropos> and vos
-help
-
+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.
+B<bos> suite. The reference page for each command also lists them, but
+they are described here in greater detail.
=over 4
-=item -cell <I<cell name>
->
+=item B<-cell> <I<cell name>>
-Names the cell in which to run the command. It is acceptable to
-abbreviate the cell name to the shortest form that distinguishes it from the
-other entries in the B</usr/vice/etc/CellServDB> file on the local
-machine. If the B<-cell> argument is omitted, the command
-interpreter determines the name of the local cell by reading the following in
-order:
+Names the cell in which to run the command. It is acceptable to abbreviate
+the cell name to the shortest form that distinguishes it from the other
+entries in the F</usr/vice/etc/CellServDB> file on the local machine. If
+the B<-cell> argument is omitted, the command interpreter determines the
+name of the local cell by reading the following in order:
-=item *
+=over 4
-The value of the AFSCELL environment variable
+=item *
+The value of the AFSCELL environment variable.
=item *
-The local /usr/vice/etc/ThisCell file
+The local F</usr/vice/etc/ThisCell> file.
+=back
-Do not combine the B<-cell> and -localauth
-options. A command on which the B<-localauth> flag is included
-always runs in the local cell (as defined in the server machine's local
-B</usr/afs/etc/ThisCell> file), whereas a command on which the
-B<-cell> argument is included runs in the specified foreign
-cell.
+Do not combine the B<-cell> and B<-localauth> options. A command on which
+the B<-localauth> flag is included always runs in the local cell (as
+defined in the server machine's local F</usr/afs/etc/ThisCell> file),
+whereas a command on which the B<-cell> argument is included runs in the
+specified foreign cell.
-=item -help
+=item B<-help>
-Prints a command's online help message on the standard output
-stream. Do not combine this flag with any of the command's other
-options; when it is provided, the command interpreter ignores all other
-options, and only prints the help message.
+Prints a command's online help message on the standard output stream. Do
+not combine this flag with any of the command's other options; when it is
+provided, the command interpreter ignores all other options, and only
+prints the help message.
-=item -localauth
+=item B<-localauth>
Constructs a server ticket using the server encryption key with the
-highest key version number in the local B</usr/afs/etc/KeyFile>
-file. The B<vos> command interpreter presents the ticket, which
-never expires, to the Volume Server and VL Server during mutual
-authentication.
+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 B</usr/afs/etc/KeyFile> file.
-The issuer of a command that includes this flag must be logged on to the
-server machine as the local superuser B<root>. The flag is
-useful for commands invoked by an unattended application program, such as a
-process controlled by the UNIX B<cron> utility or by a cron entry in
-the machine's B</usr/afs/local/BosConfig> file. It is also
-useful if an administrator is unable to authenticate to AFS but is logged in
-as the local superuser B<root>.
-
-Do not combine the B<-cell> and -localauth
-options. A command on which the B<-localauth> flag is included
-always runs in the local cell (as defined in the server machine's local
-B</usr/afs/etc/ThisCell> file), whereas a command on which the
-B<-cell> argument is included runs in the specified foreign
-cell. Also, do not combine the B<-localauth> and
+machines do not usually have a F</usr/afs/etc/KeyFile> file. The issuer
+of a command that includes this flag must be logged on to the server
+machine as the local superuser C<root>. The flag is useful for commands
+invoked by an unattended application program, such as a process controlled
+by the UNIX B<cron> utility or by a cron entry in the machine's
+F</usr/afs/local/BosConfig> file. It is also useful if an administrator is
+unable to authenticate to AFS but is logged in as the local superuser
+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 -noauth
+=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
-B<anonymous>. It is useful only when authorization checking is
-disabled on the server machine (during the installation of a file server
-machine or when the B<bos setauth> command has been used during other
-unusual circumstances). In normal circumstances, the 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 -partition <I<partition name>
->
+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:
+information. The B<vos> command interpreter accepts any of the following
+four name formats:
- B</vicepa> = B<vicepa> = B<a> = 0
- B</vicepb> = B<vicepb> = B<b> = 1
+ /vicepa = vicepa = a = 0
+ /vicepb = vicepb = b = 1
After /vicepz (for which the index is 25) comes
- B</vicepaa> = B<vicepaa> = B<aa> = 26
- B</vicepab> = B<vicepab> = B<ab> = 27
+ /vicepaa = vicepaa = aa = 26
+ /vicepab = vicepab = ab = 27
and so on through
- B</vicepiv> = B<vicepiv> = B<iv> = 255
+ /vicepiv = vicepiv = iv = 255
-The B<-frompartition> and -topartition arguments to the
-B<vos move> command also accept this notation.
+The B<-frompartition> and B<-topartition> arguments to the B<vos move>
+command also accept this notation.
-=item -server <I<machine name>
->
+=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, 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.
+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 -toserver arguments to the
-B<vos move> command also accept these name formats.
+The B<-fromserver> and B<-toserver> arguments to the B<vos move> command
+also accept these name formats.
-=item -verbose
+=item B<-verbose>
-Produces on the standard output stream a detailed trace of the
-command's execution. If this argument is omitted, only warnings
-and error messages appear.
+Produces on the standard output stream a detailed trace of the command's
+execution. If this argument is omitted, only warnings and error messages
+appear.
=back
=head1 PRIVILEGE REQUIRED
To issue most vos commands, the issuer must be listed in the
-B</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 B<UserList> file.
-Alternatively, if the B<-localauth> flag is included, the issuer must
-be logged on to a server machine as the local superuser
-B<root>.
+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.
+To issue a vos command that only displays information, no privilege is
+required.
=head1 SEE ALSO
-L<CellServDB (server version)(1)>
-
-L<UserList(1)>,
+L<CellServDB(5)>,
+L<UserList(5)>,
L<vos_addsite(1)>,
L<vos_apropos(1)>,
L<vos_backup(1)>,
=head1 SYNOPSIS
-vos addsite -server <I<machine name for new site>>
-B<-partition> <I<partition name for new site>>
- B<-id> <I<volume name or ID>> [-cell <I<cell name>>]
- [B<-noauth>] [B<-localauth>] [B<-verbose>] [-help]
+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 -s> <I<machine name for new site>> -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>]
+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 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 CAVEATS
-
-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.
+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.
=over 4
-=item -server
+=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
-the introductory reference page for the B<vos> command suite.
+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 -partition
+=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,
-B</vicepa>) or use one of the three acceptable abbreviated
-forms. For details, see the introductory reference page for the
-B<vos> command suite.
+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 -id
+=item B<-id> <I<volume name or ID>>
Specifies either the complete name or volume ID number of the read/write
source volume.
-=item -cell
+=item B<-cell> <I<cell name>>
-Names the cell in which to run the command. Do not combine this
-argument with the B<-localauth> flag. For more details, see the
-introductory B<vos> reference page.
+Names the cell in which to run the command. Do not combine this argument
+with the B<-localauth> flag. For more details, see L<vos(1)>.
-=item -noauth
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. Do not combine this flag with the B<-localauth>
-flag. For more details, see the introductory B<vos> reference
-page.
+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
-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 the introductory B<vos> reference page.
+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 -verbose
+=item B<-verbose>
-Produces on the standard output stream a detailed trace of the
-command's execution. If this argument is omitted, only warnings
-and error messages appear.
+Produces on the standard output stream a detailed trace of the command's
+execution. If this argument is omitted, only warnings and error messages
+appear.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=head1 EXAMPLES
The following example, appropriate in the State University cell, defines a
-read-only site for the cell's B<root.afs> volume.
+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 /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 B<root>.
+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
=head1 SYNOPSIS
-B<vos apropos -topic> <I<help string>> [-help]
+B<vos apropos> B<-topic> <I<help string>> [B<-help>]
-B<vos ap -t> <I<help string>> [-h]
+B<vos ap> B<-t> <I<help string>> [B<-h>]
=head1 DESCRIPTION
-The 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.
+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 vos help
-command.
+To display the syntax for a command, use the B<vos help> command.
=head1 OPTIONS
=over 4
-=item -topic
+=item B<-topic> <I<help string>>
-Specifies the keyword string to match. Use lowercase letters only,
-except for the acronym B<VLDB>. If the string is more than a
-single word, surround it with double quotes ("") or other delimiters.
+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 -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
The first line of a command's online help entry names it and briefly
describes its function. This command displays the first line for any
-B<vos> command where the string specified with the B<-topic>
-argument is part of the command name or first line.
+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:
+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
=head1 SYNOPSIS
-
-B<vos backup -id> <I<volume name or ID>> [B<-cell> <I<cell name>>] [-noauth]
-[B<-localauth>] [B<-verbose>] [B<-help>]
+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 -i> <I<volume name or ID>> [B<-c> <I<cell name>>] [B<-n>] [B<-l>] [B<-v>] [-h]
+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 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 B<.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.
+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 vos
-backupsys command.
+To create a backup version of multiple volumes, use the B<vos backupsys>
+command.
=head1 OPTIONS
=over 4
-=item -id
+=item B<-id> <I<volume name or ID>>
Specifies either the complete name or volume ID number of the read/write
source volume.
-=item -cell
+=item B<-cell> <I<cell name>>
-Names the cell in which to run the command. Do not combine this
-argument with the B<-localauth> flag. For more details, see the
-introductory B<vos> reference page.
+Names the cell in which to run the command. Do not combine this argument
+with the B<-localauth> flag. For more details, see L<vos(1)>.
-=item -noauth
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. Do not combine this flag with the B<-localauth>
-flag. For more details, see the introductory B<vos> reference
-page.
+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
+=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 the introductory B<vos> reference page.
+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 -verbose
+=item B<-verbose>
-Produces on the standard output stream a detailed trace of the
-command's execution. If this argument is omitted, only warnings
-and error messages appear.
+Produces on the standard output stream a detailed trace of the command's
+execution. If this argument is omitted, only warnings and error messages
+appear.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=head1 EXAMPLES
The following example creates a backup version of the volume
-B<user.smith>.
+C<user.smith>.
% vos backup user.smith
Created backup volume for user.smith
=head1 PRIVILEGE REQUIRED
-The issuer must be listed in the /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 B<root>.
+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
=head1 SYNOPSIS
-B<vos backupsys> [-prefix <I<common prefix on volume(s)>>+]
-
[B<-server> <I<machine name>>] [B<-partition> <I<partition name>>]
- [B<-exclude>] [-xprefix <I<negative prefix on volume(s)>>+]
- [B<-dryrun>] [B<-cell> <I<cell name>>] [B<-noauth>] [-localauth]
- [B<-verbose>] [-help]
+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)>>+] [-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>] [-h]
+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 vos backupsys command clones each indicated read/write
-volume to create a backup version, placing each clone at the same site as its
+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 B<.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.
+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).
+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:
+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
-B<user.> or includes the string B<afs>), use the
-B<-prefix> argument or combine the B<-xprefix> and
-B<-exclude> options.
-
+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.
-
+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 -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.
+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 -xprefix arguments both accept
-multiple values, which can be used to define disjoint groups of
-volumes. Each value can be one of two types:
+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).
-
+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 ( B<^> ) at the
-beginning of the expression, and enclose the entire string in single quotes
-(B<'> B<'>). Explaining regular
+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 B<regexp(5)> or (for a brief introduction) the
-B<backup addvolentry> reference page in this document. As an
-example, the following expression matches volumes that have the string
-B<aix> anywhere in their names:
-
+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.
+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.
+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 -prefix
+=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.
+B<-server>, B<-partition>, B<-exclude>, and B<-xprefix> options.
-=item -server
+=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
-the introductory reference page for the B<vos> command suite.
+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.
+This argument can be combined with any combination of the B<-prefix>,
+B<-partition>, B<-exclude>, and B<-xprefix> options.
-=item -partition
->
+=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, B</vicepa>) or use one of the three acceptable
-abbreviated forms. For details, see the introductory reference page for
-the B<vos> command suite.
+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.
+This argument can be combined with any combination of the B<-prefix>,
+B<-server>, B<-exclude>, and B<-xprefix> options.
-=item -exclude
+=item B<-exclude>
-Reverses the meaning of the B<-prefix> or -xprefix
-argument. This flag can be combined with any combination of the
-B<-prefix>, B<-server>, B<-partition>, and
-B<-xprefix> options.
+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 -xprefix
+=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
+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.
+B<-prefix>, B<-server>, B<-partition>, and B<-exclude> options.
-=item -dryrun
+=item B<-dryrun>
Displays on the standard output stream a list of the volumes to be cloned,
without actually cloning them.
-=item -cell
+=item B<-cell> <I<cell name>>
-Names the cell in which to run the command. Do not combine this
-argument with the B<-localauth> flag. For more details, see the
-introductory B<vos> reference page.
+Names the cell in which to run the command. Do not combine this argument
+with the B<-localauth> flag. For more details, see L<vos(1)>.
-=item -noauth
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. Do not combine this flag with the B<-localauth>
-flag. For more details, see the introductory B<vos> reference
-page.
+Assigns the unprivileged identity C<anonymous> to the issuer. Do not
+combine this flag with the B<-localauth> flag. For more details, see
+L<vos(1)>.
-=item -localauth
+=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 the introductory B<vos> reference page.
+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 -verbose
+=item B<-verbose>
-Produces on the standard output stream a detailed trace of the
-command's execution. If this argument is omitted, only warnings
-and error messages appear.
+Produces on the standard output stream a detailed trace of the command's
+execution. If this argument is omitted, only warnings and error messages
+appear.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
to confirm that the operation was successful:
done
- Total volumes backed up: I<number_cloned>; failed to backup: I<failures>
+ Total volumes backed up: <number_cloned>; failed to backup: <failures>
-If the -dryrun flag is included, a list of the volumes to be
-backed up precedes the standard confirmation messages.
+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 -dryrun
-flag, the following messages appear for each volume. The output
-concludes with 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 I<volume_name> on I<date/time>
- {Recloning backup volume | Creating a new backup clone} I<backup_volumeID> . . .done
+ 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 -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:
+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 -prefix argument is provided, or the
-B<-xprefix> and B<-exclude> options are combined:
-
+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 I<string> [orI<string>] . .
+ Would have backed up volumes which are prefixed with <string> [or <string>] . .
=item *
-If only the -xprefix argument is provided, or the
-B<-prefix> and B<-exclude> options are combined:
-
+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 I<string> [norI<string>] . .
+ Would have backed up volumes which are not prefixed with <string> [nor <string>] . .
=item *
-If the B<-prefix> and -xprefix arguments are
-combined:
+If the B<-prefix> and B<-xprefix> arguments are combined:
-
- Would have backed up volumes which are prefixed with I<string> [orI<string>] \
- removing those which are prefixed with I<x_string> [orI<x_string>] . .
+ 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 -exclude
-options are provided:
-
+If the B<-prefix>, B<-xprefix>, and B<-exclude> options are provided:
- Would have backed up volumes which are not prefixed with I<string> [norI<string>] \
- adding those which are prefixed with I<x_string> [orI<x_string>] . .
+ 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>.
+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
-B<fs3.abc.com>.
+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
-B<db1.stateu.edu> except those whose name includes the
-string B<temp>.
+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
-B<source>, but including those whose names contain the string
-B<source.current>.
+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 /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 B<root>.
+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(1)>,
+L<backup_addvolentry(8)>,
L<vos(1)>,
L<vos_backup(1)>
=head1 SYNOPSIS
-B<vos changeaddr -oldaddr> <I<original IP address>> [-newaddr <I<new IP address>>]
-[B<-remove>] [B<-cell> <I<cell name>>] [B<-noauth>] [B<-localauth>]
- [B<-verbose>] [-help]
+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 -o> <I<original IP address>> [B<-ne> <I<new IP address>>] [-r]
-[B<-c> <I<cell name>>] [B<-no>] [B<-l>] [B<-v>] [B<-h>]
+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 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 vos listaddrs
-command.
-
-=head1 CAVEATS
-
-Combining the command's B<-oldaddr> and -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 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 B<fs> process group (which includes the File
+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 the reference page for the B<sysid> file.
+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 B<CellServDB> file on every 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 -oldaddr
+=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.
+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 -newaddr
+=item B<-newaddr> <I<new IP address>>
Specifies the new IP address that replaces all currently registered
addresses.
-=item -remove
+=item B<-remove>
Removes from the VLDB the server entry that includes the address specified
by the B<-oldaddr> argument.
-=item -cell
+=item B<-cell> <I<cell name>>
-Names the cell in which to run the command. Do not combine this
-argument with the B<-localauth> flag. For more details, see the
-introductory B<vos> reference page.
+Names the cell in which to run the command. Do not combine this argument
+with the B<-localauth> flag. For more details, see L<vos(1)>.
-=item -noauth
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. Do not combine this flag with the B<-localauth>
-flag. For more details, see the introductory B<vos> reference
-page.
+Assigns the unprivileged identity C<anonymous> to the issuer. Do not
+combine this flag with the B<-localauth> flag. For more details, see
+L<vos(1)>.
-=item -localauth
+=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 the introductory B<vos> reference page.
+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 -verbose
+=item B<-verbose>
-Produces on the standard output stream a detailed trace of the
-command's execution. If this argument is omitted, only warnings
-and error messages appear.
+Produces on the standard output stream a detailed trace of the command's
+execution. If this argument is omitted, only warnings and error messages
+appear.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=head1 EXAMPLES
The following command removes the VLDB server entry that includes the IP
-address B<192.12.107.214>.
+address C<192.12.107.214>.
% vos changeaddr -oldaddr 192.12.107.214 -remove
=head1 PRIVILEGE REQUIRED
-Issuer must be listed in the /usr/afs/etc/UserList file on the
-machine specified with the B<-oldaddr> argument and on each database
-server machine.
+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 (client version)(1)>
-
-L<CellServDB (server version)(1)>
-
-L<UserList(1)>,
-L<sysid(1)>,
-L<fileserver(1)>,
+L<CellServDB(5)>,
+L<UserList(5)>,
+L<sysid(5)>,
+L<fileserver(8)>,
L<pts_rename(1)>,
L<vos(1)>,
L<vos_listaddrs(1)>
=head1 SYNOPSIS
-B<vos create -server> <I<machine name>> -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>] [-help]
+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 -s> <I<machine name>> B<-p> <I<partition name>> -na <I<volume name>>
-[B<-m> <I<initial quota (KB)>>] [B<-c> <I<cell name>>] [B<-no>] [B<-l>] [B<-v>] [B<-h>]
+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 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:
+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.
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-
+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
-B<system:administrators> group is automatically placed on the
-ACL. (In addition, the File Server by default always implicitly grants
-the B<l> (B<lookup>) and B<a> (B<administer>)
-permissions on every ACL to members of the
-B<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.)
-
+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.
-
+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.
+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 -server
+=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
-the introductory reference page for the B<vos> command suite.
+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 -partition
+=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,
-B</vicepa>) or use one of the three acceptable abbreviated
-forms. For details, see the introductory reference page for the
-B<vos> command suite.
+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 -name
+=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 B<.backup> or B<.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.
+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 -maxquota
+=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 B<1024> is one megabyte). The
-value B<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 B<5000>.
+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 -cell
+=item B<-cell> <I<cell name>>
-Names the cell in which to run the command. Do not combine this
-argument with the B<-localauth> flag. For more details, see the
-introductory B<vos> reference page.
+Names the cell in which to run the command. Do not combine this argument
+with the B<-localauth> flag. For more details, see L<vos(1)>.
-=item -noauth
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. Do not combine this flag with the B<-localauth>
-flag. For more details, see the introductory B<vos> reference
-page.
+Assigns the unprivileged identity C<anonymous> to the issuer. Do not
+combine this flag with the B<-localauth> flag. For more details, see
+L<vos(1)>.
-=item -localauth
+=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 the introductory B<vos> reference page.
+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 -verbose
+=item B<-verbose>
-Produces on the standard output stream a detailed trace of the
-command's execution. If this argument is omitted, only warnings
-and error messages appear.
+Produces on the standard output stream a detailed trace of the command's
+execution. If this argument is omitted, only warnings and error messages
+appear.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=head1 OUTPUT
-The Volume Server produces the following message to confirm that it created
-the volume:
+The Volume Server produces the following message to confirm that it
+created the volume:
- Volume I<volume_ID> created on partition I<partition_name> of I<machine_name>
+ Volume <volume_ID> created on partition <partition_name> of <machine_name>
=head1 EXAMPLES
-The following command creates the read/write volume
-B<user.pat> on the B</vicepf> partition of the file
-server machine B<fs4.abc.com>.
+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 /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 B<root>.
+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
=head1 SYNOPSIS
-B<vos delentry> [-id <I<volume name or ID>>+]
-[B<-prefix> <I<prefix of volume whose VLDB entry is to be deleted>>]
- [B<-server> <I<machine name>>] [-partition <I<partition name>>]
- [B<-cell> <I<cell name>>] [B<-noauth>] [B<-localauth>] [B<-verbose>] [-help]
+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> [-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>>] [-c <I<cell name>>]
- [B<-n>] [B<-l>] [B<-v>] [-h]
+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 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.
+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.
+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 -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:
+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, B<sys.> or B<user.>): use the
-B<-prefix> argument.
-
+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.
-
+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 B</vicepa> partition on any file server
-machine): specify the partition name with the B< -partition>
-argument.
-
+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.
-
+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.
-
+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 CAVEATS
+=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.
+machines. Use the B<vos remove> command to remove both the volume and its
+VLDB entry.
=head1 OPTIONS
=over 4
-=item -id
+=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.
+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 -prefix
+=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.
+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 -server
+=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 the introductory reference page for the
-B<vos> command suite.
+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 -prefix argument, the
-B<-partition> argument, or both.
+Combine this argument with the B<-prefix> argument, the B<-partition>
+argument, or both.
-=item -partition
+=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, B</vicepa>) or use
-one of the three acceptable abbreviated forms. For details, see the
-introductory reference page for the B<vos> command suite.
+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 -prefix argument, the
-B<-server> argument, or both.
+Combine this argument with the B<-prefix> argument, the B<-server>
+argument, or both.
-=item -cell
+=item B<-cell> <I<cell name>>
-Names the cell in which to run the command. Do not combine this
-argument with the B<-localauth> flag. For more details, see the
-introductory B<vos> reference page.
+Names the cell in which to run the command. Do not combine this argument
+with the B<-localauth> flag. For more details, see L<vos(1)>.
-=item -noauth
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. Do not combine this flag with the B<-localauth>
-flag. For more details, see the introductory B<vos> reference
-page.
+Assigns the unprivileged identity C<anonymous> to the issuer. Do not
+combine this flag with the B<-localauth> flag. For more details, see
+L<vos(1)>.
-=item -localauth
+=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 the introductory B<vos> reference page.
+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 -verbose
+=item B<-verbose>
-Produces on the standard output stream a detailed trace of the
-command's execution. If this argument is omitted, only warnings
-and error messages appear.
+Produces on the standard output stream a detailed trace of the command's
+execution. If this argument is omitted, only warnings and error messages
+appear.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=head1 OUTPUT
-The following message confirms the success of the command by indicating how
-many VLDB entries were removed.
+The following message confirms the success of the command by indicating
+how many VLDB entries were removed.
- Deleted I<number> VLDB entries
+ Deleted <number> VLDB entries
=head1 EXAMPLES
-The following command removes the VLDB entry for the volume
-B<user.temp>.
+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 B<test> and for which the VLDB lists a site on
-the file server machine B<fs3.abc.com>.
+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 /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 B<root>.
+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
=head1 SYNOPSIS
-B<vos dump -id> <I<volume name or ID>> [B<-time> <I<dump from time>>] [-file <I<dump file>>]
-[B<-server> <I<server>>] [B<-partition> <I<partition>>] [B<-cell> <I<cell name>>]
- [B<-noauth>] [B<-localauth>] [B<-verbose>] [-help]
+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 -i> <I<volume name or ID>> [B<-t> <I<dump from time>>] [-f <I<dump file>>]
-[B<-s> <I<server>>] [B<-p> <I<partition>>] [B<-c> <I<cell name>>]
- [B<-n>] [B<-l>] [B<-v>] [-h]
+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 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 B<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.
+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 vos restore
-command.
-
-=head1 CAVEATS
-
-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.
+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 -id
+=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 -time
+=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:
+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 0 (zero) to create a full dump.
-
+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 B<1970> to B<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 B<01/13/1999>.
-
+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 (" ") because it contains a space.
-An example is B<"01/13/1999 22:30">.
-
+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 -file
+=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.
+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 -server
+=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.
+Specifies the file server machine on which the volume resides. Provide
+the B<-partition> argument along with this one.
-=item -partition
+=item B<-partition> <I<partition name>>
Specifies the partition on which the volume resides. Provide the
B<-server> argument along with this one.
-=item -cell
+=item B<-cell> <I<cell name>
-Names the cell in which to run the command. Do not combine this
-argument with the B<-localauth> flag. For more details, see the
-introductory B<vos> reference page.
+Names the cell in which to run the command. Do not combine this argument
+with the B<-localauth> flag. For more details, see L<vos(1)>.
-=item -noauth
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. Do not combine this flag with the B<-localauth>
-flag. For more details, see the introductory B<vos> reference
-page.
+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
+=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 the introductory B<vos> reference page.
+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 -verbose
+=item B<-verbose>
-Produces on the standard output stream a detailed trace of the
-command's execution. If this argument is omitted, only warnings
-and error messages appear.
+Produces on the standard output stream a detailed trace of the command's
+execution. If this argument is omitted, only warnings and error messages
+appear.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=head1 EXAMPLES
-The following command writes a full dump of the volume
-B<user.terry> to the file
-B</afs/abc.com/common/dumps/terry.dump>.
+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
-B<user.smith> to the file
-B<smith.990131.dump> in the current working
+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.
+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 /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 B<root>.
+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 -file argument is included, the issuer must also have
-permission to insert and write in the directory that houses the file.
+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
=head1 NAME
-vos examine - Displays information from the volume header and VLDB entry for a
-volume.
+vos examine - Shows volume header and VLDB entry information for a volume
=head1 SYNOPSIS
-B<vos examine -id> <I<volume name or ID>> [B<-extended>] [-cell <I<cell name>>]
-[B<-noauth>] [B<-localauth>] [B<-verbose>] [B<-help>]
+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 -i> <I<volume name or ID>> [B<-e>] [B<-c> <I<cell name>>] [B<-n>] [B<-l>] [B<-v>] [-h]
+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 -i> <I<volume name or ID>> [B<-e>] [-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 -i> <I<volume name or ID>> [B<-e>] [B<-c> <I<cell name>>] [B<-n>] [B<-l>] [B<-v>] [-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 vos examine command formats and displays information from
-the Volume Location Database (VLDB) entry and the volume header of the volume
+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 vos listvol
-command. To display information from the VLDB only, use the B<vos
-listvldb> command.
+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 -id
+=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 -extended
+=item B<-extended>
Display statistics about read and write operations on files and
directories in the volume.
-=item -cell
+=item B<-cell> <I<cell name>>
-Names the cell in which to run the command. Do not combine this
-argument with the B<-localauth> flag. For more details, see the
-introductory B<vos> reference page.
+Names the cell in which to run the command. Do not combine this argument
+with the B<-localauth> flag. For more details, see L<vos(1)>.
-=item -noauth
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. Do not combine this flag with the B<-localauth>
-flag. For more details, see the introductory B<vos> reference
-page.
+Assigns the unprivileged identity C<anonymous> to the issuer. Do not
+combine this flag with the B<-localauth> flag. For more details, see
+L<vos(1)>.
-=item -localauth
+=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 the introductory B<vos> reference page.
+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 -verbose
+=item B<-verbose>
-Produces on the standard output stream a detailed trace of the
-command's execution. If this argument is omitted, only warnings
-and error messages appear.
+Produces on the standard output stream a detailed trace of the command's
+execution. If this argument is omitted, only warnings and error messages
+appear.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=head1 OUTPUT
-The first 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.
+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
Basic information about the specified volume (displayed on a single
line):
-
=over 4
=item *
Name
-
=item *
Volume ID number
-L<(1)>
-
=item *
-Type (the flag is C<RW> for read/write, C<RO> for
-read-only, C<BK> for backup)
-
+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 -extended flag is
-provided
-L<(1)>
-
+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 C<On-line
->
+=item On-line
The volume is completely accessible to Cache Managers.
-L<(1)>
-=item C<Off-line
->
+=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.
-L<(1)>
-=item C<Off-line**needs salvage**
->
+=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.
+corrupted. Use the B<bos salvage> or B<salvager> command to repair the
+corruption.
=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.
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-
+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.
-L<(1)>
-L<(1)>
-
+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.
-L<(1)>
-L<(1)>
-
=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.
-L<(1)>
-L<(1)>
-
+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.
-L<(1)>
-L<(1)>
-
+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:
-
+operation since the later of the two following times:
=over 4
12:00 a.m. on the day the command is issued
-
=item *
The last time the volume changed location
-
=back
=back
-When the -extended flag is included, two tables appear
-next:
+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
+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.
-
+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.
+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 I<volume_ID> is busy ****
+ **** 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 B<FileLog> and
-B<VolserLog> log files in the B</usr/afs/logs> directory on
-the file server machine possibly provide additional information; use the
-B<bos getlog> command to display them.
+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 I<volume_ID> ****
+ **** 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:
+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 B<.readonly> and
-B<.backup> extension, respectively.
-
+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.
-L<(1)>
-L<(1)>
-
+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 ->>.
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-
+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:
-
+(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 C<Not released
->
+=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.
-L<(1)>
+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 C<Old release
->
+=item Old release
-Indicates that a vos release command did not complete
-successfully, leaving the previous, obsolete version of the volume at this
-site.
-L<(1)>
+Indicates that a vos release command did not complete successfully,
+leaving the previous, obsolete version of the volume at this site.
-=item C<New release
->
+=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.
+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>.
-
+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 the reference page for the B<vos release>
-command.
+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
-B<usr> with two read-only replication sites (this volume is mounted at
-the B</afs/abc.com/usr> directory). For the sake of
-illustration, the output shows the volume as locked.
+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
server fs2.abc.com partition /vicepb RW Site
Volume is currently LOCKED
-The following example shows the output for the volume
-B<user.terry> using the B<-extended> flag. The
-volume has no read-only replication sites.
+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
=head1 SEE ALSO
-L<backup_diskrestore(1)>,
-L<backup_volrestore(1)>,
-L<bos_getlog(1)>,
-L<bos_salvage(1)>,
-L<salvager(1)>,
+L<backup_diskrestore(8)>,
+L<backup_volrestore(8)>,
+L<bos_getlog(8)>,
+L<bos_salvage(8)>,
+L<salvager(8)>,
L<vos(1)>,
L<vos_listvol(1)>,
L<vos_listvldb(1)>,
=head1 NAME
-vos help - Displays the syntax of specified vos commands or functional
-descriptions for all B<vos> commands
+vos help - Displays help for vos commands
=head1 SYNOPSIS
-B<vos help> [B<-topic> <I<help string>>+] [-help]
+B<vos help> [B<-topic> <I<help string>>+] [B<-help>]
-B<vos h> [B<-t> <I<help string>>+] [-h]
+B<vos h> [B<-t> <I<help string>>+] [B<-h>]
=head1 DESCRIPTION
-The 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.
+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 vos command whose name or short description
-includes a specified keyword, use the B<vos apropos> 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 -topic
+=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.
+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 -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=head1 OUTPUT
-The online help entry for each vos command consists of the
-following two or three lines:
+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.
-
+The first line names the command and briefly describes its function.
=item *
The second line lists aliases for the command, if any.
-
=item *
-The final line, which begins with the string C<Usage>, lists the
-command's options in the prescribed order. Online help entries use
-the same symbols (for example, brackets) as the reference pages in this
-document.
-
+The final line, which begins with the string C<Usage>, lists the command's
+options in the prescribed order. Online help entries use the same symbols
+(for example, brackets) as the reference pages in this document.
=back
=head1 EXAMPLES
-The following command displays the online help entry for the vos
-create command:
+The following command displays the online help entry for the B<vos create>
+command:
% vos help create
vos create: create a new volume
=head1 SYNOPSIS
-B<vos listaddrs> [B<-cell> <I<cell name>>] [-noauth]
-[B<-localauth>] [B<-verbose>] [B<-help>]
+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>] [-h]
+B<vos lista> [B<-c> <I<cell name>>] [B<-n>] [B<-l>] [B<-v>] [B<-h>]
=head1 DESCRIPTION
-The 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
-B</usr/afs/local/sysid> file in the VLDB.
+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 -cell
+=item B<-cell> <I<cell name>>
-Names the cell in which to run the command. Do not combine this
-argument with the B<-localauth> flag. For more details, see the
-introductory B<vos> reference page.
+Names the cell in which to run the command. Do not combine this argument
+with the B<-localauth> flag. For more details, see L<vos(1)>.
-=item -noauth
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. Do not combine this flag with the B<-localauth>
-flag. For more details, see the introductory B<vos> reference
-page.
+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
+=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 the introductory B<vos> reference page.
+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 -verbose
+=item B<-verbose>
-Produces on the standard output stream a detailed trace of the
-command's execution. If this argument is omitted, only warnings
-and error messages appear.
+Produces on the standard output stream a detailed trace of the command's
+execution. If this argument is omitted, only warnings and error messages
+appear.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
The output 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.
+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
+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.
+entries, use the B<vos changeaddr> command with the B<-remove> argument.
=head1 EXAMPLES
=head1 SEE ALSO
-L<sysid(1)>,
+L<sysid(5)>,
L<vos(1)>,
L<vos_changeaddr(1)>,
L<vos_examine(1)>,
=head1 SYNOPSIS
-B<vos listpart -server> <I<machine name>> [B<-cell> <I<cell name>>] [-noauth]
-[B<-localauth>] [B<-verbose>] [B<-help>]
+B<vos listpart> B<-server> <I<machine name>> [B<-cell> <I<cell name>>]
+ [B<-noauth>] [B<-localauth>] [B<-verbose>] [B<-help>]
-B<vos listp -s> <I<machine name>> [B<-c> <I<cell name>>] [B<-n>] [B<-l>] [B<-v>] [-h]
+B<vos listp> B<-s> <I<machine name>> [B<-c> <I<cell name>>] [B<-n>]
+ [B<-l>] [B<-v>] [B<-h>]
=head1 DESCRIPTION
-The 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.
+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 -server
+=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 the introductory reference page for the B<vos> command
-suite.
+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 -cell
+=item B<-cell> <I<cell name>>
-Names the cell in which to run the command. Do not combine this
-argument with the B<-localauth> flag. For more details, see the
-introductory B<vos> reference page.
+Names the cell in which to run the command. Do not combine this argument
+with the B<-localauth> flag. For more details, see L<vos(1)>.
-=item -noauth
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. Do not combine this flag with the B<-localauth>
-flag. For more details, see the introductory B<vos> reference
-page.
+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
+=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 the introductory B<vos> reference page.
+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 -verbose
+=item B<-verbose>
-Produces on the standard output stream a detailed trace of the
-command's execution. If this argument is omitted, only warnings
-and error messages appear.
+Produces on the standard output stream a detailed trace of the command's
+execution. If this argument is omitted, only warnings and error messages
+appear.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=head1 OUTPUT
The output consists of a list of partition names of the form
-B</vicep>I<xx>, following the header:
+F</vicepI<xx>>, following the header:
The partitions on the server are:
=head1 EXAMPLES
-The following command displays the partitions on
-B<fs1.abc.com>:
+The following command displays the partitions on C<fs1.abc.com>:
% vos listpart fs1.abc.com
The partitions on the server are:
=head1 SYNOPSIS
-B<vos listvldb> [B<-name> <I<volume name or ID>>] [-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>] [-help]
+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>>] [-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>] [-h]
+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 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
+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:
=item *
-Every entry in the VLDB: provide no options
-
+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
-
+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
-
+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
-
+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
-
+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
-
+certain site: combine the B<-locked> flag with any of arguments that
+define sites.
=back
=over 4
-=item -name
+=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 -server
+=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
-the introductory reference page for the B<vos> command suite.
+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 -partition argument, the
+This argument can be combined with the B<-partition> argument, the
B<-locked> flag, or both.
-=item -partition
+=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, B</vicepa>) or use one of the three acceptable
-abbreviated forms. For details, see the introductory reference page for
-the B<vos> command suite.
+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 -server argument, the
-B<-locked> flag, or both.
+This argument can be combined with the B<-server> argument, the B<-locked>
+flag, or both.
-=item -locked
+=item B<-locked>
-Displays only locked VLDB entries. This flag can be combined with
-the B<-server> argument, the B<-partition> argument, or
-both.
+Displays only locked VLDB entries. This flag can be combined with the
+B<-server> argument, the B<-partition> argument, or both.
-=item -quiet
+=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.
+status, which otherwise appear at the beginning and end of the output when
+the output includes more than one volume.
-=item -nosort
+=item B<-nosort>
Suppresses the default sorting of volume entries alphabetically by volume
name.
-=item -cell
+=item B<-cell> <I<cell name>>
-Names the cell in which to run the command. Do not combine this
-argument with the B<-localauth> flag. For more details, see the
-introductory B<vos> reference page.
+Names the cell in which to run the command. Do not combine this argument
+with the B<-localauth> flag. For more details, see L<vos(1)>.
-=item -noauth
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. Do not combine this flag with the B<-localauth>
-flag. For more details, see the introductory B<vos> reference
-page.
+Assigns the unprivileged identity C<anonymous> to the issuer. Do not
+combine this flag with the B<-localauth> flag. For more details, see
+L<vos(1)>.
-=item -localauth
+=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 the introductory B<vos> reference page.
+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 -verbose
+=item B<-verbose>
-Produces on the standard output stream a detailed trace of the
-command's execution. If this argument is omitted, only warnings
-and error messages appear.
+Produces on the standard output stream a detailed trace of the command's
+execution. If this argument is omitted, only warnings and error messages
+appear.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
If 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.
+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.
+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:
=item *
-The base (read/write) volume name. The read-only and backup
-versions have the same name with a B<.readonly> and
-B<.backup> extension, respectively.
-
+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.
-L<(1)>
-L<(1)>
-
+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 ->>.
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-
+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:
-
+(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 C<Not released
->
+=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.
-L<(1)>
+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 C<Old release
->
+=item Old release
-Indicates that a vos release command did not complete
-successfully, leaving the previous, obsolete version of the volume at this
-site.
-L<(1)>
+Indicates that a vos release command did not complete successfully,
+leaving the previous, obsolete version of the volume at this site.
-=item C<New release
->
+=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.
+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>.
-
+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 the reference page for the B<vos release>
-command.
+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 B<usr>, which has two read-only replication sites:
+volume called C<usr>, which has two read-only replication sites:
% vos listvldb -name usr
usr
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 B<fs4.abc.com>. The first
-VLDB entry is currently locked. There are 508 entries that mention the
-machine as a volume site.
+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
=head1 SYNOPSIS
-B<vos listvol -server> <I<machine name>> [-partition <I<partition name>>]
-[B<-fast>] [B<-long>] [B<-quiet>] [B<-extended>] [B<-cell> <I<cell name>>]
- [B<-noauth>] [B<-localauth>] [B<-verbose>] [-help]
+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 -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>]
+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 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:
+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.
-
+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 -server
-argument with the B<-partition> argument.
-
+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.
+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 -server
+=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 the introductory reference page for the B<vos> command
-suite.
+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 -partition argument, as
-well as the B<-fast>, B<-long>, or B<-extended>
-flag.
+This argument can be combined with the B<-partition> argument, as well as
+the B<-fast>, B<-long>, or B<-extended> flag.
-=item -partition
+=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, B</vicepa>) or use one of the three acceptable
-abbreviated forms. For details, see the introductory reference page for
-the B<vos> command suite.
+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 -fast
+=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.
+specified by the B<-server>, and optionally B<-partition>, argument. Do
+not combine this flag with the B<-extended> flag.
-=item -long
+=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.
+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 -quiet
+=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.
+status, which otherwise appear at the beginning and end of the output when
+the output includes more than one volume.
-=item -extended
+=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.
+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 -cell
+=item B<-cell> <I<cell name>>
-Names the cell in which to run the command. Do not combine this
-argument with the B<-localauth> flag. For more details, see the
-introductory B<vos> reference page.
+Names the cell in which to run the command. Do not combine this argument
+with the B<-localauth> flag. For more details, see L<vos(1)>.
-=item -noauth
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. Do not combine this flag with the B<-localauth>
-flag. For more details, see the introductory B<vos> reference
-page.
+Assigns the unprivileged identity C<anonymous> to the issuer. Do not
+combine this flag with the B<-localauth> flag. For more details, see
+L<vos(1)>.
-=item -localauth
+=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 the introductory B<vos> reference page.
+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 -verbose
+=item B<-verbose>
-Produces on the standard output stream a detailed trace of the
-command's execution. If this argument is omitted, only warnings
-and error messages appear.
+Produces on the standard output stream a detailed trace of the command's
+execution. If this argument is omitted, only warnings and error messages
+appear.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=head1 OUTPUT
-The output is ordered alphabetically by volume name and by default provides
-the following information on a single line for each volume:
+The output is ordered alphabetically by volume name and by default
+provides the following information on a single line for each volume:
=over 4
Name
-
=item *
Volume ID number
-L<(1)>
-
=item *
-Type (the flag is C<RW> for read/write, C<RO> for
-read-only, C<BK> for backup)
-
+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 -extended flag is
-provided
-L<(1)>
-
+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 C<On-line
->
+=item On-line
The volume is completely accessible to Cache Managers.
-L<(1)>
-=item C<Off-line
->
+=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.
-L<(1)>
-=item C<Off-line**needs salvage**
->
+=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.
+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.
+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 I<volume_ID> is busy ****
+ **** 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 B<FileLog> and
-B<VolserLog> log files in the B</usr/afs/logs> directory on
-the file server machine possibly provide additional information; use the
-B<bos getlog> command to display them.
+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 I<volume_ID> ****
+ **** 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.
+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 -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<-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 -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:
+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
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.
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-
=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.
-L<(1)>
-L<(1)>
-
+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.
-L<(1)>
-L<(1)>
-
=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.
-L<(1)>
-L<(1)>
-
+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.
-L<(1)>
-L<(1)>
-
+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:
-
+operation since the later of the two following times:
=over 4
12:00 a.m. on the day the command is issued
-
=item *
The last time the volume changed location
-
=back
=back
-If the -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:
+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.
-
+The table labeled C<Raw Read/Write Stats> table summarizes the number of
+times the volume has been accessed for reading or writing.
=item *
information on writes made to files and directories in the specified
volume.
-
=back
=head1 EXAMPLES
-The following example shows the output for the /vicepb partition
-on the file server machine B<fs2.abc.com> when no flags
-are provided:
+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
+ 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.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 -fast flag is
-added:
+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
+ Total number of volumes on server fs2.abc.com partition /vicepb : 66
1969516782
1969516784
.
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
+ Total number of volumes on server fs2.abc.com partition /vicepb: 66
. . . . . .
. . . . . .
user.pat 1969534536 RW 17518 K On-line
0 accesses in the past day (i.e., vnode references)
. . . . . .
. . . . . .
- Total volumes onLine 66 ; Total volumes offLine 0 ; \
- Total busy 0
+ Total volumes onLine 66 ; Total volumes offLine 0 ; Total busy 0
=head1 PRIVILEGE REQUIRED
=head1 SYNOPSIS
-B<vos lock -id> <I<volume name or ID>> [B<-cell> <I<cell name>>] [-noauth]
-[B<-localauth>] [B<-verbose>] [B<-help>]
+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 -i> <I<volume name or ID>> [B<-c> <I<cell name>>] [B<-n>] [B<-l>] [B<-v>] [-h]
+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 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.
+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 vos unlock
-command. To unlock several entries, or all locked entries in the VLDB,
-use the B<vos unlockvldb> command.
+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 CAVEATS
+=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.
+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 -id
+=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 -cell
+=item B<-cell> <I<cell name>>
-Names the cell in which to run the command. Do not combine this
-argument with the B<-localauth> flag. For more details, see the
-introductory B<vos> reference page.
+Names the cell in which to run the command. Do not combine this argument
+with the B<-localauth> flag. For more details, see L<vos(1)>.
-=item -noauth
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. Do not combine this flag with the B<-localauth>
-flag. For more details, see the introductory B<vos> reference
-page.
+Assigns the unprivileged identity C<anonymous> to the issuer. Do not
+combine this flag with the B<-localauth> flag. For more details, see
+L<vos(1)>.
-=item -localauth
+=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 the introductory B<vos> reference page.
+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 -verbose
+=item B<-verbose>
-Produces on the standard output stream a detailed trace of the
-command's execution. If this argument is omitted, only warnings
-and error messages appear.
+Produces on the standard output stream a detailed trace of the command's
+execution. If this argument is omitted, only warnings and error messages
+appear.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=head1 EXAMPLES
-The following command locks the VLDB entry for
-B<user.terry>.
+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 /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 B<root>.
+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
=head1 SYNOPSIS
-B<vos move -id> <I<volume name or ID>> -fromserver <I<machine name on source>>
-B<-frompartition> <I<partition name on source>>
- -toserver <I<machine name on destination>>
- -topartition <I<partition name on destination>>
- [B<-cell> <I<cell name>>] [B<-noauth>] [B<-localauth>] [B<-verbose>] [-help]
-
-B<vos m -i> <I<volume name or ID>> -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>] [-h]
+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 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.
+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.
+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 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:
+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 I<dest_part> to move volume I<volume>
+ vos: no space on target partition <dest_part> to move volume <volume>
-=head1 CAVEATS
+=head1 CAUTIONS
-Unless there is a compelling reason, do not interrupt a vos move
-command in progress. Interrupting a move can result in one or more of
-the following inconsistent states:
+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.)
-
+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.)
-
+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 bos
-salvage command to bring it back on line.)
-
+The volume is off-line. (If this happens, run the B<bos salvage> command
+to bring it back on line.)
=back
-If the <B<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:
+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.
+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 -id
+=item B<-id> <I<volume name or ID>>
Specifies either the complete name or volume ID number of a read/write
volume.
-=item -fromserver
+=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
-the introductory reference page for the B<vos> command suite.
+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 -frompartition
+=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 on the introductory B<vos> reference
-page.
+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 -toserver
+=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 the
-introductory reference page for the B<vos> command suite.
+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 -topartition
+=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 on the introductory B<vos> reference page.
+partition name (for, example, B</vicepa>) or one of the abbreviated forms
+described in L<vos(1)>.
-=item -cell
+=item B<-cell> <I<cell name>>
-Names the cell in which to run the command. Do not combine this
-argument with the B<-localauth> flag. For more details, see the
-introductory B<vos> reference page.
+Names the cell in which to run the command. Do not combine this argument
+with the B<-localauth> flag. For more details, see L<vos(1)>.
-=item -noauth
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. Do not combine this flag with the B<-localauth>
-flag. For more details, see the introductory B<vos> reference
-page.
+Assigns the unprivileged identity C<anonymous> to the issuer. Do not
+combine this flag with the B<-localauth> flag. For more details, see
+L<vos(1)>.
-=item -localauth
+=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 the introductory B<vos> reference page.
+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 -verbose
+=item B<-verbose>
-Produces on the standard output stream a detailed trace of the
-command's execution. If this argument is omitted, only warnings
-and error messages appear.
+Produces on the standard output stream a detailed trace of the command's
+execution. If this argument is omitted, only warnings and error messages
+appear.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=head1 EXAMPLES
-The following example moves the volume user.smith from
-the B</vicepb> partition on the file server machine
-B<fs3.abc.com> to the B</vicepg> partition on
-the file server machine B<fs7.abc.com>.
+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
+ % 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 /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 B<root>.
+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
=head1 SYNOPSIS
-B<vos partinfo -server> <I<machine name>> [-partition <I<partition name>>]
-[B<-cell> <I<cell name>>] [B<-noauth>] [B<-localauth>] [B<-verbose>] [B<-help>]
+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 -s> <I<machine name>> [B<-p> <I<partition name>>] [-c <I<cell name>>]
-[B<-n>] [B<-l>] [B<-v>] [B<-h>]
+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 B<either> all of the partitions on the indicated
-file server machine (if the B<-partition> argument is omitted)
-B<or> the specified partition on that file server machine. The
-Volume Location Database (VLDB) is not consulted.
+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 -server
+=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 the introductory reference page for the B<vos> command
-suite.
+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 -partition
+=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,
-B</vicepa>) or use one of the three acceptable abbreviated
-forms. For details, see the introductory reference page for the
-B<vos> command suite.
+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 -cell
+=item B<-cell> <I<cell name>>
-Names the cell in which to run the command. Do not combine this
-argument with the B<-localauth> flag. For more details, see the
-introductory B<vos> reference page.
+Names the cell in which to run the command. Do not combine this argument
+with the B<-localauth> flag. For more details, see L<vos(1)>.
-=item -noauth
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. Do not combine this flag with the B<-localauth>
-flag. For more details, see the introductory B<vos> reference
-page.
+Assigns the unprivileged identity C<anonymous> to the issuer. Do not
+combine this flag with the B<-localauth> flag. For more details, see
+L<vos(1)>.
-=item -localauth
+=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 the introductory B<vos> reference page.
+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 -verbose
+=item B<-verbose>
-Produces on the standard output stream a detailed trace of the
-command's execution. If this argument is omitted, only warnings
-and error messages appear.
+Produces on the standard output stream a detailed trace of the command's
+execution. If this argument is omitted, only warnings and error messages
+appear.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
-=head1 CAVEATS
+=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.
+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
=head1 EXAMPLES
The following command displays all partitions on the file server machine
-B<fs2.abc.com>.
+C<fs2.abc.com>.
% vos partinfo fs2.abc.com
Free space on partition /vicepa: 27301 K blocks out of total 549197
=head1 NAME
-vos release - Updates the contents of read-only volumes to match their read/write source
-volume
+vos release - Updates read-only volumes to match the read/write source volume
=head1 SYNOPSIS
-B<vos release -id> <I<volume name or ID>> [B<-f>] [-cell <I<cell name>>]
-[B<-noauth>] [B<-localauth>] [B<-verbose>] [B<-help>]
+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 -i> <I<volume name or ID>> [B<-f>] [B<-c> <I<cell name>>] [B<-n>] [B<-l>] [B<-v>] [-h]
+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 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 B<.readonly> extension.
+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.
+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.
+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:
+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
+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.
-
+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>.
-
+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.
+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:
=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.
-
+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.
-
+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
+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 -id
+=item B<-id> <I<volume name or id>>
Specifies either the complete name or volume ID number of a read/write
volume.
-=item -f
+=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.
+regardless of whether or not any site definitions in the VLDB entry are
+marked with a flag.
-=item -cell
+=item B<-cell> <I<cell name>>
-Names the cell in which to run the command. Do not combine this
-argument with the B<-localauth> flag. For more details, see the
-introductory B<vos> reference page.
+Names the cell in which to run the command. Do not combine this argument
+with the B<-localauth> flag. For more details, see L<vos(1)>.
-=item -noauth
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. Do not combine this flag with the B<-localauth>
-flag. For more details, see the introductory B<vos> reference
-page.
+Assigns the unprivileged identity C<anonymous> to the issuer. Do not
+combine this flag with the B<-localauth> flag. For more details, see
+L<vos(1)>.
-=item -localauth
+=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 the introductory B<vos> reference page.
+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 -verbose
+=item B<-verbose>
-Produces on the standard output stream a detailed trace of the
-command's execution. If this argument is omitted, only warnings
-and error messages appear.
+Produces on the standard output stream a detailed trace of the command's
+execution. If this argument is omitted, only warnings and error messages
+appear.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=head1 EXAMPLES
-The following command clones the read/write volume usr and
-releases it to the read-only sites defined in its VLDB entry.
+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 /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 B<root>.
+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
=head1 SYNOPSIS
-B<vos remove> [B<-server> <I<machine name>>] [-partition <I<partition name>>]
-B<-id> <I<volume name or ID>> [B<-cell> <I<cell name>>]
- [B<-noauth>] [B<-localauth>] [B<-verbose>] [-help]
+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>>] -i <I<volume name or ID>>
-[B<-c> <I<cell name>>] [B<-n>] [B<-l>] [B<-v>] [B<-h>]
+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 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.
+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 -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
+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 -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.
-
+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 -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.
-
+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.
+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 -server
+=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 the introductory reference
-page for the B<vos> command suite.
+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 -partition
+=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,
-B</vicepa>) or use one of the three acceptable abbreviated
-forms. For details, see the introductory reference page for the
-B<vos> command suite.
+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 -id argument
-names a read-only volume that exists at multiple sites. Provide the
-B<-server> argument along with this one.
+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 -id
+=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 (B<.readonly> or
-B<.backup>).
+number. If identifying a read-only or backup volume by name, include the
+appropriate extension (C<.readonly> or C<.backup>).
-=item -cell
+=item B<-cell> <I<cell name>>
-Names the cell in which to run the command. Do not combine this
-argument with the B<-localauth> flag. For more details, see the
-introductory B<vos> reference page.
+Names the cell in which to run the command. Do not combine this argument
+with the B<-localauth> flag. For more details, see L<vos(1)>.
-=item -noauth
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. Do not combine this flag with the B<-localauth>
-flag. For more details, see the introductory B<vos> reference
-page.
+Assigns the unprivileged identity C<anonymous> to the issuer. Do not
+combine this flag with the B<-localauth> flag. For more details, see
+L<vos(1)>.
-=item -localauth
+=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 the introductory B<vos> reference page.
+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 -verbose
+=item B<-verbose>
-Produces on the standard output stream a detailed trace of the
-command's execution. If this argument is omitted, only warnings
-and error messages appear.
+Produces on the standard output stream a detailed trace of the command's
+execution. If this argument is omitted, only warnings and error messages
+appear.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=head1 EXAMPLES
-The following example removes the read/write volume
-B<user.terry> and its backup version, if any.
+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
-B<root.afs.readonly> from one of its sites, the
-B</vicepa> partition on the file server machine
-B<fs1.abc.com>.
+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 /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 B<root>.
+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
=head1 SYNOPSIS
-B<vos remsite -server> <I<machine name>> -partition <I<partition name>>
-B<-id> <I<volume name or ID>> [B<-cell> <I<cell name>>] [B<-noauth>]
- [B<-localauth>] [B<-verbose>] [-help]
+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 -s> <I<machine name>> B<-p> <I<partition name>> -i <I<volume name or ID>>
-[B<-c> <I<cell name>>] [B<-n>] [B<-l>] [B<-v>] [B<-h>]
+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 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
+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.
+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 CAVEATS
+=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.
+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 -server
+=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
-the introductory reference page for the B<vos> command suite.
+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 -partition
+=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, B</vicepa>) or use one of the three acceptable
-abbreviated forms. For details, see the introductory reference page for
-the B<vos> command suite.
+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 -id
+=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 -cell
+=item B<-cell> <I<cell name>>
-Names the cell in which to run the command. Do not combine this
-argument with the B<-localauth> flag. For more details, see the
-introductory B<vos> reference page.
+Names the cell in which to run the command. Do not combine this argument
+with the B<-localauth> flag. For more details, see L<vos(1)>.
-=item -noauth
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. Do not combine this flag with the B<-localauth>
-flag. For more details, see the introductory B<vos> reference
-page.
+Assigns the unprivileged identity C<anonymous> to the issuer. Do not
+combine this flag with the B<-localauth> flag. For more details, see
+L<vos(1)>.
-=item -localauth
+=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 the introductory B<vos> reference page.
+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 -verbose
+=item B<-verbose>
-Produces on the standard output stream a detailed trace of the
-command's execution. If this argument is omitted, only warnings
-and error messages appear.
+Produces on the standard output stream a detailed trace of the command's
+execution. If this argument is omitted, only warnings and error messages
+appear.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=head1 EXAMPLES
The following command removes the mistakenly defined read-only site
-B</viceph> on the file server machine
-B<fs5.abc.com> from the VLDB entry for the volume
-B<root.cell>.
+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 /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 B<root>.
+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
=head1 SYNOPSIS
-B<vos rename -oldname> <I<old volume name>> -newname <I<new volume name>>
-[B<-cell> <I<cell name>>] [B<-noauth>] [B<-localauth>] [B<-verbose>] [B<-help>]
+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 -o> <I<old volume name>> B<-ne> <I<new volume name>> [-c <I<cell name>>]
-[B<-no>] [B<-l>] [B<-v>] [B<-h>]
+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 vos rename command changes the name of the read/write volume
+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.
+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>
+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 -oldname
+=item B<-oldname> <I<old volume name>>
Is the current name of the read/write volume.
-=item -newname
+=item B<-newname> <I<new volume name>>
Is the desired new name for the volume.
-=item -cell
+=item B<-cell> <I<cell name>>
-Names the cell in which to run the command. Do not combine this
-argument with the B<-localauth> flag. For more details, see the
-introductory B<vos> reference page.
+Names the cell in which to run the command. Do not combine this argument
+with the B<-localauth> flag. For more details, see L<vos(1)>.
-=item -noauth
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. Do not combine this flag with the B<-localauth>
-flag. For more details, see the introductory B<vos> reference
-page.
+Assigns the unprivileged identity C<anonymous> to the issuer. Do not
+combine this flag with the B<-localauth> flag. For more details, see
+L<vos(1)>.
-=item -localauth
+=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 the introductory B<vos> reference page.
+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 -verbose
+=item B<-verbose>
-Produces on the standard output stream a detailed trace of the
-command's execution. If this argument is omitted, only warnings
-and error messages appear.
+Produces on the standard output stream a detailed trace of the command's
+execution. If this argument is omitted, only warnings and error messages
+appear.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=head1 OUTPUT
-The vos rename command produces no output if the command
-succeeds.
+The B<vos rename> command produces no output if the command succeeds.
-If the volume named by the -oldname argument does not exist, the
+If the volume named by the B<-oldname> argument does not exist, the
following message appears:
- vos: Could not find entry for volume
I<old volume name>.
+ vos: Could not find entry for volume <old volume name>.
=head1 EXAMPLES
-The following example changes the mistaken volume name
-B<sun4x_56.afsws> to the correct alternative
-C<sun4x_56.usr.afsws>.
+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 /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 B<root>.
+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
=head1 NAME
-vos restore - Converts an ASCII file into proper volume format and writes it to the file
-system
+vos restore - Converts an ASCII dump file into an AFS volume
=head1 SYNOPSIS
-B<vos restore
-server> <I<machine name>> -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> <B<abort> | B<full> | incremental>]
- [B<-cell> <I<cell name>>] [B<-noauth>] [B<-localauth>] [-verbose]
- [-help]
+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
-s> <I<machine name>> -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> <B<a> | B<f> | B<inc>>] [-c <I<cell name>>]
- [B<-no>] [B<-l>] [B<-v>] [-h]
+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 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 -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 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.
+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 -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.
-
+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 B<f> or
-B<i> for the B<-overwrite> argument to indicate whether the
-dump file is full or incremental, respectively.
-
+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 B<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).
-
+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 -name argument already exists and the
-B<-overwrite> argument is omitted, the command interpreter produces
-the following prompt:
+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):
=item *
-f if restoring a full dump file
-
+C<f> if restoring a full dump file
=item *
-i if restoring an incremental dump file
-
+C<i> if restoring an incremental dump file
=item *
-B<a> or <Return> to cancel the restore operation
-
+C<a> or Return to cancel the restore operation
=back
-=head1 CAVEATS
+=head1 CAUTIONS
-If the -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.
+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 -server
+=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
-the introductory reference page for the B<vos> command suite.
+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 -partition
+=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,
-B</vicepa>) or use one of the three acceptable abbreviated
-forms. For details, see the introductory reference page for the
-B<vos> command suite.
+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 -name
+=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 B<.readonly> or
-B<.backup> extension. If the volume already exists, it
-is overwritten subject to the value of the B<-overwrite>
-argument.
+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 -file
+=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.
+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 -id
+=item B<-id> <I<volume ID>>
Specifies the volume ID number to assign to the restored volume.
-=item -overwrite
+=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:
=item *
-a to terminate the restore operation.
-
+C<a> to terminate the restore operation.
=item *
-f if restoring a full dump file.
-
+C<f> if restoring a full dump file.
=item *
-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.
-
+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 -file argument is not
-provided.
+This argument is mandatory if the B<-file> argument is not provided.
-=item -cell
+=item B<-cell> <I<cell name>>
-Names the cell in which to run the command. Do not combine this
-argument with the B<-localauth> flag. For more details, see the
-introductory B<vos> reference page.
+Names the cell in which to run the command. Do not combine this argument
+with the B<-localauth> flag. For more details, see L<vos(1)>.
-=item -noauth
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. Do not combine this flag with the B<-localauth>
-flag. For more details, see the introductory B<vos> reference
-page.
+Assigns the unprivileged identity C<anonymous> to the issuer. Do not
+combine this flag with the B<-localauth> flag. For more details, see
+L<vos(1)>.
-=item -localauth
+=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 the introductory B<vos> reference page.
+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 -verbose
+=item B<-verbose>
-Produces on the standard output stream a detailed trace of the
-command's execution. If this argument is omitted, only warnings
-and error messages appear.
+Produces on the standard output stream a detailed trace of the command's
+execution. If this argument is omitted, only warnings and error messages
+appear.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=head1 EXAMPLES
The following command restores the contents of the dump file
-B</afs/abc.com/common/dumps/terry.dump> to the
-B</vicepc> partition on the file server machine
-B<fs3.abc.com>. The restored volume is named
-B<user.terry>.
+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
-
+ % vos restore -file terry.dump -server fs3.abc.com -partition c \
+ -name user.terry
=head1 PRIVILEGE REQUIRED
-The issuer must be listed in the /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 B<root>.
+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
=head1 SYNOPSIS
-B<vos status -server> <I<machine name>> [B<-cell> <I<cell name>>] [-noauth]
-[B<-localauth>] [B<-verbose>] [B<-help>]
+B<vos status> B<-server> <I<machine name>> [B<-cell> <I<cell name>>]
+ [B<-noauth>] [B<-localauth>] [B<-verbose>] [B<-help>]
-B<vos st -s> <I<machine name>> [B<-c> <I<cell name>>] [B<-n>] [B<-l>] [B<-v>] [-h]
+B<vos st> B<-s> <I<machine name>> [B<-c> <I<cell name>>] [B<-n>] [B<-l>]
+ [B<-v>] [B<-h>]
=head1 DESCRIPTION
-The 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:
+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 I<machine_name>
+ No active transactions on <machine_name>
-This command is useful mainly if there is concern that the Volume Server is
-not performing requested actions.
+This command is useful mainly if there is concern that the Volume Server
+is not performing requested actions.
=head1 OPTIONS
=over 4
-=item -server
->
+=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 the introductory reference page for the
-B<vos> command suite.
+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 -cell
+=item B<-cell> <I<cell name>>
-Names the cell in which to run the command. Do not combine this
-argument with the B<-localauth> flag. For more details, see the
-introductory B<vos> reference page.
+Names the cell in which to run the command. Do not combine this argument
+with the B<-localauth> flag. For more details, see L<vos(1)>.
-=item -noauth
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. Do not combine this flag with the B<-localauth>
-flag. For more details, see the introductory B<vos> reference
-page.
+Assigns the unprivileged identity C<anonymous> to the issuer. Do not
+combine this flag with the B<-localauth> flag. For more details, see
+L<vos(1)>.
-=item -localauth
+=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 the introductory B<vos> reference page.
+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 -verbose
+=item B<-verbose>
-Produces on the standard output stream a detailed trace of the
-command's execution. If this argument is omitted, only warnings
-and error messages appear.
+Produces on the standard output stream a detailed trace of the command's
+execution. If this argument is omitted, only warnings and error messages
+appear.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
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.
+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:
=item *
-C<created> on the first line, which indicates the time at which
-this transaction started
-
+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
-
+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
-
+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)
-
+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
-
+C<procedure> on the third line, which indicates the internal subprocedure
+being executed
=back
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.
-
+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.
-
+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.
+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 B<fs1.abc.com> is executing a
-dump at the time this command is issued.
+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
--------------------------------------------
=head1 SYNOPSIS
-B<vos syncserv -server> <I<machine name>> [-partition <I<partition name>>]
-[B<-cell> <I<cell name>>] [B<-noauth>] [B<-localauth>]
- [B<-verbose>] [-help]
+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
-s> <I<machine name>> [-p <I<partition name>>]
-[B<-c> <I<cell name>>] [B<-n>] [B<-l>] [B<-v>] [B<-h>]
+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 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 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.
+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 vos syncvldb
-command on all file server machines in the cell, then run this command on all
-file server machines in the cell.
+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 -server
+=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
-the introductory reference page for the B<vos> command suite.
+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 -partition
+=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,
-B</vicepa>) or use one of the three acceptable abbreviated
-forms. For details, see the introductory reference page for the
-B<vos> command suite.
+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 -cell
+=item B<-cell> <I<cell name>>
-Names the cell in which to run the command. Do not combine this
-argument with the B<-localauth> flag. For more details, see the
-introductory B<vos> reference page.
+Names the cell in which to run the command. Do not combine this argument
+with the B<-localauth> flag. For more details, see L<vos(1)>.
-=item -noauth
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. Do not combine this flag with the B<-localauth>
-flag. For more details, see the introductory B<vos> reference
-page.
+Assigns the unprivileged identity C<anonymous> to the issuer. Do not
+combine this flag with the B<-localauth> flag. For more details, see
+L<vos(1)>.
-=item -localauth
+=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 the introductory B<vos> reference page.
+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 -verbose
+=item B<-verbose>
-Produces on the standard output stream a detailed trace of the
-command's execution. If this argument is omitted, only warnings
-and error messages appear.
+Produces on the standard output stream a detailed trace of the command's
+execution. If this argument is omitted, only warnings and error messages
+appear.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=head1 EXAMPLES
The following example verifies the VLDB entries in which a site definition
-mentions the file server machine B<fs3.abc.com>.
+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 /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 B<root>.
+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
=head1 SYNOPSIS
-B<vos syncvldb> [B<-server> <I<machine name>>] [-partition <I<partition name>>]
-[B<-volume> <I<volume name or ID>>] [B<-cell> <I<cell name>>] [B<-noauth>]
- [B<-localauth>] [B<-verbose>] [-help]
+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>>] [-vo <I<volume name or ID>>]
-[B<-c> <I<cell name>>] [B<-n>] [B<-l>] [B<-ve>] [B<-h>]
+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 vos syncvldb command verifies that the status of the volumes
-housed either on all partitions on the file server machine specified by the
+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.
+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 -volume argument is not included, the command interpreter
+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
+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
+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.
+machines in the cell, and then run the B<vos syncserv> command on all file
+server machines in the cell.
-Using the -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
+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.
+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 -server
+=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 the introductory reference page for the B<vos> command
-suite.
+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 -partition
+=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, B</vicepa>) or use one of the three acceptable
-abbreviated forms. For details, see the introductory reference page for
-the B<vos> command suite.
+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 -volume
+=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.
+verify the VLDB entry. This argument can be combined with the B<-server>
+(and optionally, the B<-partition>) argument.
-=item -cell
+=item B<-cell> <I<cell name>>
-Names the cell in which to run the command. Do not combine this
-argument with the B<-localauth> flag. For more details, see the
-introductory B<vos> reference page.
+Names the cell in which to run the command. Do not combine this argument
+with the B<-localauth> flag. For more details, see L<vos(1)>.
-=item -noauth
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. Do not combine this flag with the B<-localauth>
-flag. For more details, see the introductory B<vos> reference
-page.
+Assigns the unprivileged identity C<anonymous> to the issuer. Do not
+combine this flag with the B<-localauth> flag. For more details, see
+L<vos(1)>.
-=item -localauth
+=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 the introductory B<vos> reference page.
+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 -verbose
+=item B<-verbose>
-Produces on the standard output stream a detailed trace of the
-command's execution. If this argument is omitted, only warnings
-and error messages appear.
+Produces on the standard output stream a detailed trace of the command's
+execution. If this argument is omitted, only warnings and error messages
+appear.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=head1 EXAMPLES
The following example command verifies the VLDB entry for each volume
-stored on the file server machine B<fs4.abc.com>.
+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 /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 B<root>.
+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
=head1 SYNOPSIS
-B<vos unlock -id> <I<volume name or ID>> [B<-cell> <I<cell name>>] [-noauth]
-[B<-localauth>] [B<-verbose>] [B<-help>]
+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 -i> <I<volume name or ID>> [B<-c> <I<cell name>>] [B<-n>] [B<-l>] [B<-v>] [-h]
+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 vos unlock command releases the lock on the Volume Location
+The B<vos unlock> command releases the lock on the Volume Location
Database (VLDB) entry for the indicated volume.
-=head1 CAVEATS
+=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
+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 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.
+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 -id
+=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 -cell
+=item B<-cell> <I<cell name>>
-Names the cell in which to run the command. Do not combine this
-argument with the B<-localauth> flag. For more details, see the
-introductory B<vos> reference page.
+Names the cell in which to run the command. Do not combine this argument
+with the B<-localauth> flag. For more details, see L<vos(1)>.
-=item -noauth
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. Do not combine this flag with the B<-localauth>
-flag. For more details, see the introductory B<vos> reference
-page.
+Assigns the unprivileged identity C<anonymous> to the issuer. Do not
+combine this flag with the B<-localauth> flag. For more details, see
+L<vos(1)>.
-=item -localauth
+=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 the introductory B<vos> reference page.
+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 -verbose
+=item B<-verbose>
-Produces on the standard output stream a detailed trace of the
-command's execution. If this argument is omitted, only warnings
-and error messages appear.
+Produces on the standard output stream a detailed trace of the command's
+execution. If this argument is omitted, only warnings and error messages
+appear.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=head1 EXAMPLES
-The following example unlocks the VLDB entry for the volume
-B<user.terry>.
+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 /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 B<root>.
+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
=head1 SYNOPSIS
-B<vos unlockvldb> [B<-server> <I<machine name>>] [-partition <I<partition name>>]
-[B<-cell> <I<cell name>>] [B<-noauth>] [B<-localauth>]
- [B<-verbose>] [-help]
+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>>]
[-p <I<partition name>>]
-[B<-c> <I<cell name>>] [B<-n>] [B<-l>] [B<-v>] [B<-h>]
+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 vos unlockvldb command releases the lock on the Volume
-Location Database (VLDB) entries indicated by the combination of arguments
+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
-
+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
-
+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
-
+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 vos unlock command
-instead.
+To unlock a single volume, use the B<vos unlock> command instead.
-=head1 CAVEATS
+=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
+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 vos lock command locks a VLDB entry so that no one else can
-perform an action that requires writing the 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 -server
+=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
-the introductory reference page for the B<vos> command suite.
+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 -partition
+=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,
-B</vicepa>) or use one of the three acceptable abbreviated
-forms. For details, see the introductory reference page for the
-B<vos> command suite.
+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 -cell
+=item B<-cell> <I<cell name>>
-Names the cell in which to run the command. Do not combine this
-argument with the B<-localauth> flag. For more details, see the
-introductory B<vos> reference page.
+Names the cell in which to run the command. Do not combine this argument
+with the B<-localauth> flag. For more details, see L<vos(1)>.
-=item -noauth
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. Do not combine this flag with the B<-localauth>
-flag. For more details, see the introductory B<vos> reference
-page.
+Assigns the unprivileged identity C<anonymous> to the issuer. Do not
+combine this flag with the B<-localauth> flag. For more details, see
+L<vos(1)>.
-=item -localauth
+=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 the introductory B<vos> reference page.
+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 -verbose
+=item B<-verbose>
-Produces on the standard output stream a detailed trace of the
-command's execution. If this argument is omitted, only warnings
-and error messages appear.
+Produces on the standard output stream a detailed trace of the command's
+execution. If this argument is omitted, only warnings and error messages
+appear.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
% vos unlockvldb
The following command unlocks all locked VLDB entries that mention the
-B</vicepa> partition in a site definition.
+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 B</vicepc> partition of the file server machine
-B<fs3.abc.com>.
+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 /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 B<root>.
+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
=head1 SYNOPSIS
-B<vos zap -server> <I<machine name>> -partition <I<partition name>>
-B<-id> <I<volume ID>> [B<-force>] [B<-backup>] [B<-cell> <I<cell name>>]
- [B<-noauth>] [B<-localauth>] [B<-verbose>] [-help]
+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 -s> <I<machine name>> B<-p> <I<partition name>> -i <I<volume ID>>
-[B<-f>] [B<-b>] [B<-c> <I<cell name>>] [B<-n>] [B<-l>] [B<-v>] [B<-h>]
+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 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<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 -force flag removes a volume even if it cannot be "attached"
+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 the B<Cautions> section.
+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 CAVEATS
+=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.
+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 -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 -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.
+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 -server
+=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 the
-introductory reference page for the B<vos> command suite.
+or using an unambiguous abbreviation). For details, see L<vos(1)>.
-=item -partition
+=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,
-B</vicepa>) or use one of the three acceptable abbreviated
-forms. For details, see the introductory reference page for the
-B<vos> command suite.
+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 -id
+=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 -force
+=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>
-command without this flag.
+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 -backup
+=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.
+B<-id> argument. Do not use this flag if the B<-id> argument identifies a
+read-only or backup volume.
-=item -cell
+=item B<-cell> <I<cell name>>
-Names the cell in which to run the command. Do not combine this
-argument with the B<-localauth> flag. For more details, see the
-introductory B<vos> reference page.
+Names the cell in which to run the command. Do not combine this argument
+with the B<-localauth> flag. For more details, see L<vos(1)>.
-=item -noauth
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. Do not combine this flag with the B<-localauth>
-flag. For more details, see the introductory B<vos> reference
-page.
+Assigns the unprivileged identity C<anonymous> to the issuer. Do not
+combine this flag with the B<-localauth> flag. For more details, see
+L<vos(1)>.
-=item -localauth
+=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 the introductory B<vos> reference page.
+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 -verbose
+=item B<-verbose>
-Produces on the standard output stream a detailed trace of the
-command's execution. If this argument is omitted, only warnings
-and error messages appear.
+Produces on the standard output stream a detailed trace of the command's
+execution. If this argument is omitted, only warnings and error messages
+appear.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=head1 EXAMPLES
The following example removes the volume with volume ID 536870988 from the
-B</vicepf> partition of the file server machine
-B<fs6.abc.com>, without noting the change in the
-VLDB.
+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 /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 B<root>.
+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
B<kdb> command, which requires being logged in to the local machine as
the local superuser B<root>.
-=head1 CAVEATS
+=head1 CAUTIONS
The Authentication Server is possibly unable to create these files on some
operating systems that AFS otherwise supports, making the B<kdb>
B</usr/vice/cache>, but it is acceptable to use a directory on a
partition with more available space.
-=head1 CAVEATS
+=head1 CAUTIONS
Editing or removing the CacheItems file can cause a kernel
panic. If the contents of B<V>I<n> files seem out of
always remain there. The conventional directory name is
B</usr/vice/cache>.
-=head1 CAVEATS
+=head1 CAUTIONS
Editing or removing the VolumeItems file can cause a kernel
panic. To refresh the contents of the file, instead use the B<fs
--- /dev/null
+=head1 NAME
+
+VI<vol_ID>.vol - Represents an AFS volume
+
+=head1 DESCRIPTION
+
+The B<V>I<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 (B</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 Configuration File - 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 C<cm I<host_name>
+>
+
+Names a client machine for which to display Cache Manager
+statistics. The order of B<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 C<fs I<host_name>
+>
+
+Names a file server machine for which to display File Server
+statistics. The order of B<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 C<thresh fs | cm I<field_name I<thresh_val>
+[I<cmd_to_run>] [I<arg>
+
+Assigns the threshold value I<thresh_val> to the statistic
+I<field_name>, for either a File Server statistic (B<fs>) or a
+Cache Manager statistic (B<cm>). The optional
+I<cmd_to_execute> field names a binary or script to execute each time
+the value of the statistic changes from being below I<thresh_val> to
+being at or above I<thresh_val>. A change between two values that
+both exceed I<thresh_val> does not retrigger the binary or
+script. The optional I<arg>
+The B<afsmonitor> program passes the following parameters to the
+I<cmd_to_execute>:
+
+=item I<host_name fs|cm I<field_name>
+I<threshold_val>
+I<actual_val> [<I<arg>
+
+The parameters B<fs>, cm, I<field_name>,
+I<threshold_val>, and I<arg>
+
+Use the thresh line to set either a global threshold, which
+applies to all file server machines listed on B<fs> lines or client
+machines listed on B<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 B<fs> or B<cm> lines in the file.
+
+
+=item *
+
+To set a machine-specific threshold, place the thresh line
+below the corresponding B<fs> or B<cm> line, and above any
+other B<fs> or B<cm> lines. A machine-specific
+threshold value always overrides the corresponding global threshold, if
+set. Do not place a B<thresh fs> line directly after a
+B<cm> line or a B<thresh cm> line directly after a
+B<fs> line.
+
+
+=back
+
+=item C<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 (B<fs>) or
+C<Cache Managers> screen (B<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 B<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 B<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 show lines in the configuration file, then the
+screens display all statistics for both Cache Managers and File
+Servers. Similarly, if there are no B<show fs> lines, the
+C<File Servers> screen displays all file server statistics, and if
+there are no B<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 (B<#>) 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 B<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.
use of multiple addresses when accessing AFS data stored on a multihomed file
server machine.
-=head1 CAVEATS
+=head1 CAUTIONS
The 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
=back
-=head1 CAVEATS
+=head1 CAUTIONS
Do not use the -shutdown parameter. It does not shutdown
the Cache Manager effectively. Instead, halt Cache Manager activity by
volume name. The B<Options> section lists the acceptable
metacharacters.
-=head1 CAVEATS
+=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
is undamaged, it is safe to continue using it. If it is corrupted,
discontinue any backup operations until it is repaired.
-=head1 CAVEATS
+=head1 CAUTIONS
While this command runs, no other backup operation can access the Backup
Database; the other commands do not run until this command
because a dump operation was interrupted or failed), or that correspond to
dumps that are expired or otherwise no longer needed.
-=head1 CAVEATS
+=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 deleted entry, their indexes are automatically decremented to eliminate
any gaps in the indexing sequence.
-=head1 CAVEATS
+=head1 CAUTIONS
Deleting volume entries from a temporary volume set is possible only within
the interactive session in which the volume set was created.
volume sets (and their volume entries) currently defined in the Backup
Database.
-=head1 CAVEATS
+=head1 CAUTIONS
Deleting a temporary volume set is possible only within the interactive
session in which it was created. Exiting the interactive session also
complete the restore operation; the backup operator must arrange to
provide them.
-=head1 CAVEATS
+=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
or prompts for any additional tapes needed to complete the dump
operation; the issuer must arrange to provide them.
-=head1 CAVEATS
+=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
=back
-=head1 CAVEATS
+=head1 CAUTIONS
It is best not to issue the (backup) kill command against
restore operations. If the termination signal interrupts a restore
mode. Issuing the <B<Ctrl-d>> command also exits interactive
mode.
-=head1 CAVEATS
+=head1 CAUTIONS
To exit interactive mode, all jobs must be completed. Use the
B<(backup) jobs> command to list any jobs currently pending or
tapes needed to complete the restore operation; the backup operator must
arrange to provide them.
-=head1 CAVEATS
+=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
choice is to use a termination signal such as <B<Ctrl-c>> to halt
the Tape Coordinator completely.
-=head1 CAVEATS
+=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
B</usr/afs/etc/CellServDB> file on the machine named by the
B<-server> argument.
-=head1 CAVEATS
+=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
B</usr/afs/logs> directory unless an alternate pathname is provided as
part of the B<-file> argument.
-=head1 CAVEATS
+=head1 CAUTIONS
Log files can grow quite large, especially for the database server
processes. To keep them to a manageable size, periodically either use
To edit the list of keys, use the B<bos addkey> and bos
removekey commands.
-=head1 CAVEATS
+=head1 CAUTIONS
Displaying actual keys on the standard output stream (by including the
B<-showkey> flag) is a security exposure. Displaying a checksum
B</usr/afs/etc/CellServDB> file on the server machine named by the
B<-server> argument.
-=head1 CAVEATS
+=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
identify each key by its key version number; use the B<bos
listkeys> command to display the key version numbers.
-=head1 CAVEATS
+=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
parent (is higher in the filespace). Orphaned objects occupy space on
the server partition, but do not count against the volume's quota.
-=head1 CAVEATS
+=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
removes the file when this command is used to reenable authorization
checking.
-=head1 CAVEATS
+=head1 CAUTIONS
Do not create the NoAuth file directly, except when directed by
instructions for dealing with emergencies (doing so requires being logged in
=back
-=head1 CAVEATS
+=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
=back
-=head1 CAVEATS
+=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
B</usr/afs/logs/BackupLog> file. Use the B<bos getlog>
command to display the contents of the file.
-=head1 CAVEATS
+=head1 CAUTIONS
The B<buserver> process reserves port 7021 for its
use. Unexpected behavior can occur if another process tries to reserve
=back
-=head1 CAVEATS
+=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
No space left on device
-=head1 CAVEATS
+=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
Insert a tape in the drive before issuing this command.
-=head1 CAVEATS
+=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)
cleared. To change the interval between writes, use the
B<-sleep> argument.
-=head1 CAVEATS
+=head1 CAUTIONS
This command produces output only if the cm event set is
active. To display or set the event set's state, use the
problems, do not issue any B<kas> commands until the database is
repaired.
-=head1 CAVEATS
+=head1 CAUTIONS
The results can be unpredictable if the Authentication Server makes changes
to the Authentication Database while this command is running. Use the
To alter the settings displayed with this command, issue the kas
setfields command.
-=head1 CAVEATS
+=head1 CAUTIONS
Displaying actual keys on the standard output stream by including the
B<-showkey> flag constitutes a security exposure. For most
The kas examine command displays the settings made with this
command.
-=head1 CAVEATS
+=head1 CAUTIONS
The password lifetime set with the -pwexpires argument begins at
the time the user's password was last changed, rather than when this
machine, or the command interpreter chooses one at random from all the
database server machines with which it has established connections.
-=head1 CAVEATS
+=head1 CAUTIONS
The -servers argument is not available in interactive mode,
making it impossible to specify a certain machine.
file). Use the B<-cell> argument to convert a string into a key
appropriate for a cell other than the local one.
-=head1 CAVEATS
+=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
running on the machine. The files contain information on privileged
actions performed by the Authentication Server.
-=head1 CAVEATS
+=head1 CAUTIONS
It is possible that on some operating systems that AFS otherwise supports,
the Authentication Server cannot create the
--- /dev/null
+=head1 NAME
+
+package - Configures files and directories on the local disk
+
+=head1 SYNOPSIS
+
+B<package> [B<initcmd>] [-config <I<base name of configuration file>>]
+[B<-fullconfig> <I<full name of configuration file, or stdin for standard input>>]
+ [B<-overwrite>] [B<-noaction>] [B<-verbose>] [B<-silent>] [-rebootfiles]
+ [B<-debug>] [-help]
+
+B<package> [B<i>] [-c <I<base name of configuration file>>]
+[B<-f> <I<full name of configuration file, or stdin for standard input>>]
+ [B<-o>] [B<-n>] [B<-v>] [B<-s>] [B<-r>] [B<-d>] [-h]
+
+=head1 DESCRIPTION
+
+The package command configures the machine's local disk to
+comply with the instructions in the configuration file named by the
+B<-config> or B<-fullconfig> argument.
+
+By default, the package command alters any existing local disk
+element whose contents or configuration does not match the element defined in
+the configuration file. For example, if a configuration file
+B<D> instruction defines a directory that has the same name as a
+symbolic link on the local disk, the B<package> command replaces the
+symbolic link with the directory. The B<F> and B<L>
+instructions include an optional I<update_code> field that alters this
+behavior.
+
+Also by default, the package command takes no action on elements
+on the local disk that are not mentioned in the configuration file. Use
+the B<D> instruction's B<R> update code to remove files
+from the disk directory that are not mentioned in the configuration
+file.
+
+Before running the package command, the administrator must
+create the template file and other files on the local disk. For
+instructions, see the I<IBM AFS Administration Guide>.
+
+It is not possible to configure a remote client machine's disk using
+this command.
+
+=head1 CAUTIONS
+
+The package command interpreter exits without executing any
+instruction if there are any syntax errors or incorrect values in the
+configuration file.
+
+=head1 OPTIONS
+
+=over 4
+
+=item initcmd
+
+Accommodates the command's use of the AFS command parser, and is
+optional.
+
+=item -config
+
+Specifies the pathname of the configuration file to use, ending in the
+file's base name, which omits the suffix that indicates the machine
+type. The B<package> command determines the machine's
+system type name and automatically appends it to the base name. An
+example of the proper value for this argument is B<staff> rather than
+B<staff.rs_aix42>. Partial pathnames are interpreted
+relative to the current working directory.
+
+Provide this argument or the -fullconfig argument.
+
+=item -fullconfig
+
+Specifies the configuration file to use. Two types of values are
+acceptable:
+
+=over 4
+
+=item *
+
+The full pathname of the configuration file to use, complete with an
+extension indicating the machine type (examples:
+B<staff.rs_aix42>, B<admin.sun4x_56>).
+
+
+=item *
+
+The string stdin to indicate that the issuer is providing
+configuration information via the standard input stream, either by piping in
+the contents of a file, or by typing configuration lines at the shell.
+In the latter case, type B<<Ctrl-d>> to conclude the input.
+
+
+=back
+
+Provide this argument or the -config argument.
+
+=item -overwrite
+
+Overwrites elements on the local disk with the source version indicated in
+the configuration file, even if the owner B<write> (B<w>) mode
+bit is turned on the disk element. Files protected by the B<I>
+update code on an B<F> line in the configuration file are not
+overwritten.
+
+=item -noaction
+
+Checks the sequence of operations to be performed when the command
+actually runs and reports any problems that the B<package> command
+interpreter expects to encounter. No elements on the local disk or in
+AFS are changed. If the B<-verbose> flag is also provided, the
+trace includes all actions to be performed as well as anticipated
+errors.
+
+=item -silent
+
+Suppresses some of the trace messages sent to the standard output stream
+by default. The output still reports major problems.
+
+=item -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 -rebootfiles
+
+Prevents overwriting of any file marked with the Q update code
+on an B<F> line in the configuration file. This effectively
+prevents the machine from rebooting automatically again when the
+B<package> command is invoked in the machine's AFS initialization
+file.
+
+=item -debug
+
+Enables debugging output, which is directed to the standard output stream
+by default. By default, no debugging output is produced.
+
+=item -help
+
+Prints the online help for this command. All other valid options
+are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+This command is usually invoked in a client machine's AFS
+initialization file (B</etc/rc> or equivalent), rather than issued at
+the command shell prompt.
+
+The following command invokes the version of the staff
+configuration file appropriate for this machine's system type, and
+produces verbose output.
+
+ # /etc/package -c staff -v
+
+The following example uses the configuration file whose basename is defined
+in the B</.package> file on the local machine. This
+method enables the administrator to use the same B<package> command in
+every machine's AFS initialization file but still customize configuration
+by putting the appropriate basename in the B</.package>
+file.
+
+ # /etc/package -c `cat /.package` -v
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be logged in as the local superuser root.
+
+=head1 SEE ALSO
+
+L<package Configuration File(1)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+package apropos - Displays each help entry containing a keyword string
+
+=head1 SYNOPSIS
+
+B<package apropos> [B<-topic> <I<help string>>] [-help]
+
+B<package a> [B<-t> <I<help string>>] [-h]
+
+=head1 DESCRIPTION
+
+The package apropos command displays the first line of the
+online help entry for any B<package> command that has in its name or
+short description the string specified by the B<-topic>
+argument.
+
+To display the syntax for a command, use the package help
+command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item -topic
+
+Specifies the keyword string to match, in lowercase letters only.
+If the string is more than a single word, surround it with double quotes ("")
+or other delimiters.
+
+=item -help
+
+Prints the online help for this command. All other valid options
+are ignored.
+
+=back
+
+=head1 OUTPUT
+
+The first line of a command's online help entry names it and briefly
+describes its function. This command displays the first line for any
+B<package> command where the string specified with the
+B<-topic> argument is part of the command name or first line.
+
+=head1 EXAMPLES
+
+The following command lists all package commands that include
+the word B<help> in their names or short descriptions:
+
+ % package apropos help
+ apropos: search by help text
+ help: get help on commands
+
+=head1 PRIVILEGE REQUIRED
+
+None
+
+=head1 SEE ALSO
+
+L<package(1)>,
+L<package_help(1)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+package help - Displays the syntax of specified package commands or lists
+functional descriptions of all B<package> commands
+
+=head1 SYNOPSIS
+
+B<package help> [B<-topic> <I<help string>>+] [-help]
+
+B<package h> [B<-t> <I<help string>>+] [-h]
+
+=head1 DESCRIPTION
+
+The package help command displays the complete online help entry
+(short description and syntax statement) for each command operation code
+specified by the B<-topic> argument. If the B<-topic>
+argument is omitted, the output includes the first line (name and short
+description) of the online help entry for every B<package>
+command.
+
+To list every package command whose name or short description
+includes a specified keyword, use the B<package apropos>
+command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item -topic
+
+Indicates each command for which to display the complete online help
+entry. Omit the B<package> part of the command name, providing
+only the operation code (for example, specify B<initcmd>, not
+B<package initcmd>). If this argument is omitted, the output
+briefly describes every B<package> command.
+
+=item -help
+
+Prints the online help for this command. All other valid options
+are ignored.
+
+=back
+
+=head1 OUTPUT
+
+The online help entry for each package command consists of the
+following two or three lines:
+
+=over 4
+
+=item *
+
+The first line names the command and briefly describes its
+function.
+
+
+=item *
+
+The second line lists aliases for the command, if any.
+
+
+=item *
+
+The final line, which begins with the string C<Usage>, lists the
+command's options in the prescribed order. Online help entries use
+the same symbols (for example, brackets) as the reference pages in this
+document.
+
+
+=back
+
+=head1 EXAMPLES
+
+The following command displays the online help entry for the package
+initcmd command:
+
+ % package help initcmd
+ package initcmd: initialize the program
+ Usage: package [initcmd] [-config <base name of configuration file>]
+ [-fullconfig <full name of configuration file, or stdin for standard input>]
+ [-overwrite] [-noaction] [-verbose] [-silent] [-rebootfiles]
+ [-debug] [-help]
+
+=head1 PRIVILEGE REQUIRED
+
+None
+
+=head1 SEE ALSO
+
+L<package(1)>,
+L<package_apropos(1)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
--- /dev/null
+=head1 NAME
+
+package_test - Tests the validity of a package configuration file
+
+=head1 SYNOPSIS
+
+package_test <I<config file>>
+
+This command does not use the syntax conventions of the AFS command
+suites. Provide the command name in full.
+
+=head1 DESCRIPTION
+
+The package_test command tests the validity of a
+B<package> configuration file created when a prototype file is
+compiled. The command interpreter prints error messages on the standard
+output stream.
+
+=head1 OPTIONS
+
+=over 4
+
+=item I<config file
+>
+
+Specifies the package configuration file to validate.
+
+=back
+
+=head1 EXAMPLES
+
+The following example tests the validity of the package
+configuration file I<staff.sun4x_56>.
+
+ % package_test staff.sun4x_56
+
+=head1 PRIVILEGE REQUIRED
+
+None
+
+=head1 SEE ALSO
+
+L<package Configuration File(1)>
+
+L<package(1)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
problems, do not issue any B<pts> commands until the database is
repaired.
-=head1 CAVEATS
+=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
B</usr/afs/etc/KeyFile> file to construct a server ticket for mutual
authentication.
-=head1 CAVEATS
+=head1 CAUTIONS
Do not use the Update Server to distribute the contents of the
B</usr/afs/etc> directory if using the international edition of
B</usr/afs/etc/KeyFile> file to construct a server ticket for mutual
authentication.
-=head1 CAVEATS
+=head1 CAUTIONS
Do not use the Update Server to distribute the contents of the
B</usr/afs/etc> directory if using the international edition of
If there are problems, do not issue any B<vos> commands until the
database is repaired.
-=head1 CAVEATS
+=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
stores information in the inodes on server partitions, and the 256-byte inode
size that XFS uses by default is not large enough.
-=head1 CAVEATS
+=head1 CAUTIONS
This command is available on in the AFS distribution for IRIX system types
that can use XFS-formatted partitions as server partitions.
projects / packages / o / openafs.git / commitdiff