Complete an initial editing and cleanup pass for all section one man pages.
Fix various conversion problems, formatting inconsistencies, and obvious
problems. Please note that no editing for content has yet been done; this
is solely editing for formatting and correct conversion to POD.
Also, add some additional section five man pages that were omitted from the
first conversion run due to unusual file names, and globally replace
CAVEATS with CAUTIONS in the man pages to match the original section name.
The section one man pages should now be in reasonable shape and ready for
additional review and further updates, although there are probably still
remaining obvious problems.
====================
This delta was composed from multiple commits as part of the CVS->Git migration.
The checkin message with each commit was inconsistent.
The following are the additional commit messages.
====================
This file got the wrong name when it was originally committed. Fix.
$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&
git://git.openafs.org / openafs.git / commitdiff