Provided by: openafs-client_1.6.15-1ubuntu1.1_amd64 bug

NAME

       afs - Introduction to AFS commands

DESCRIPTION

       AFS provides many commands that enable users and system administrators to use and
       customize its features. Many of the commands belong to the following categories, called
       command suites.

       backup
           Interface for configuring and operating the AFS Backup System.

       bos Interface to the Basic Overseer (BOS) Server for administering server processes and
           configuration files.

       fs  Interface for administering access control lists (ACLs), the Cache Manager, and other
           miscellaneous file system functions.

       fstrace
           Interface for tracing Cache Manager operations when debugging problems.

       kas Interface to the Authentication Server for administering security and authentication
           information. This aspect of OpenAFS has been deprecated.

       pts Interface to the Protection Server for administering AFS ID and group membership
           information.

       uss Interface for automated administration of user accounts. Deprecated, may be removed
           from a future version of OpenAFS. See uss man page for more detail.

       vos Interface to the Volume Server and Volume Location (VL) Server for administering
           volumes.

       In addition, there are several commands that do not belong to suites.

   AFS Command Syntax
       AFS commands that belong to suites have the following structure:

       command_suite operation_code -switch <value>[+] [-flag]

       Command Names

       Together, the command_suite and operation_code make up the 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 bos, fs, kas, package, pts, uss (deprecated) and vos.
       Some of these suites have an interactive mode in which the issuer omits the 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 man pages for each
       command name describe each operation code in detail, and the OpenAFS 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
       command_suite portion. Their structure is otherwise similar to the commands in the suites.

       Options

       The term option refers to both arguments and flags, which are described in the following
       sections.

       Arguments

       One or more arguments can follow the command name. Arguments specify the entities on which
       to act while performing the command (for example, which server machine, server process, or
       file). To minimize the potential for error, provide a command's arguments in the order
       prescribed in its syntax definition.

       Each argument has two parts, which appear in the indicated order:

       •   The switch specifies the argument's type and is preceded by a hyphen (-). For
           instance, the switch -server usually indicates that the argument names a server
           machine. Switches can often be omitted, subject to the rules outlined in "Conditions
           for Omitting Switches".

       •   The value names a particular entity of the type specified by the preceding switch. For
           example, the proper value for a -server switch is a server machine name like
           "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 ("<>")
           in command descriptions and the online help to show that they are user-supplied
           variable information.

       Some arguments accept multiple values, as indicated by trailing plus sign ("+") 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 "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 ("[]").

       Flags

       Some commands have one or more flags, which specify the manner in which the command
       interpreter and server process perform the command, or what kind of output it produces.
       Flags are preceded by hyphens like switches, but they take no values. Although the command
       descriptions and online help generally list a command's flags after its arguments, there
       is no prescribed order for flags. They can appear anywhere on the command line following
       the operation code, except in between the parts of an argument. Flags are always optional.

       An Example Command

       The following example illustrates the different parts of a command that belongs to an AFS
       command suite.

          % bos getdate -server fs1.abc.com -file ptserver kaserver

       where

       •   bos is the command suite. The BOS Server executes most of the commands in this suite.

       •   getdate is the operation code. It tells the BOS Server on the specified server machine
           (in this case "fs1.abc.com") to report the modification dates of binary files in the
           local /usr/lib/openafs directory.

       •   "-server fs1.abc.com" is one argument, with -server as the switch and "fs1.abc.com" as
           the value. This argument specifies the server machine on which BOS Server is to
           collect and report binary dates.

       •   "-file ptserver kaserver" is an argument that takes multiple values. The switch is
           -file and the values are "ptserver" and "kaserver". This argument tells the BOS Server
           to report the modification dates on the files /usr/lib/openafs/kaserver and
           /usr/lib/openafs/ptserver.

       Rules for Entering AFS Commands

       Enter each AFS command on a single line (press <Return> only at the end of the command).
       Some commands in this document appear broken across multiple lines, but that is for
       legibility only.

       Use a space to separate each element on a command line from its neighbors. Spaces rather
       than commas also separate multiple values of an argument.

       In many cases, the issuer of a command can reduce the amount of typing necessary by using
       one or both of the following methods:

       •   Omitting switches.

       •   Using accepted abbreviations for operation codes, switches (if they are included at
           all), and some types of values.

       The following sections explain the conditions for omitting or shortening parts of the
       command line. It is always acceptable to type a command in full, with all of its switches
       and no abbreviations.

       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.

       •   All of the command's required arguments appear in the order prescribed by the syntax
           statement.

       •   No switch is provided for any argument.

       •   There is only one value for each argument (but note the important exception discussed
           in the following paragraph).

       Omitting switches is possible only because there is a prescribed order for each command's
       arguments. When the issuer does not include switches, the command interpreter relies
       instead on the order of arguments; it assumes that the first element after the operation
       code is the command's first argument, the next element is the command's second argument,
       and so on. The important exception is when a command's final required argument accepts
       multiple values. In this case, the command interpreter assumes that the issuer has
       correctly provided one value for each argument up through the final one, so any additional
       values at the end belong to the final argument.

       The following list describes the rules for omitting switches from the opposite
       perspective: an argument's switch must be provided when any of the following conditions
       apply.

       •   The command's arguments do not appear in the prescribed order.

       •   An optional argument is omitted but a subsequent optional argument is provided.

       •   A switch is provided for a preceding argument.

       •   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.

       An Example of Omitting Switches

       Consider again the example command from "An Example Command".

          % bos getdate -server fs1.abc.com -file ptserver kaserver

       This command has two required arguments: the server machine name (identified by the
       -server switch) and binary file name (identified by the -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, "fs1.abc.com",
       is the server machine name, and that the next argument, "ptserver", is a binary file name.
       Then, because the command's second (and last) argument accepts multiple values, the
       command interpreter correctly interprets "kaserver" as an additional value for it.

       On the other hand, the following is not acceptable because it violates the first two
       conditions in "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

       Rules for Using Abbreviations and Aliases

       This section explains how to abbreviate operation codes, option names, server machine
       names, partition names, and cell names. It is not possible to abbreviate other types of
       values.

       Abbreviating Operation Codes

       It is acceptable to abbreviate an operation code to the shortest form that still
       distinguishes it from the other operation codes in its suite.

       For example, it is acceptable to shorten bos install to bos i because there are no other
       operation codes in the bos command suite that begin with the letter "i". In contrast,
       there are several bos operation codes that start with the letter "s", so the abbreviations
       must be longer to remain unambiguous:

       bos sa for bos salvage
       bos seta for bos setauth
       bos setc for bos setcellname
       bos setr for bos setrestart
       bos sh for bos shutdown
       bos start for bos start
       bos startu for bos startup
       bos stat for bos status
       bos sto for bos stop

       In addition to abbreviations, some operation codes have an alias, a short form that is not
       derived by abbreviating the operation code to its shortest unambiguous form. For example,
       the alias for the fs setacl command is fs sa, whereas the shortest unambiguous
       abbreviation is fs seta.

       There are two usual reasons an operation code has an alias:

       •   Because the command is frequently issued, it is convenient to have a form shorter than
           the one derived by abbreviating. The fs setacl command is an example.

       •   Because the command's name has changed, but users of previous versions of AFS know the
           former name. For example, bos listhosts has the alias bos getcell, its former name.
           It is acceptable to abbreviate aliases to their shortest unambiguous form (for
           example, bos getcell to bos getc).

       Even if an operation code has an alias, it is still acceptable to use the shortest
       unambiguous form. Thus, the fs setacl command has three acceptable forms: fs setacl (the
       full form), fs seta (the shortest abbreviation), and fs sa (the alias).

       Abbreviating Switches and Flags

       It is acceptable to shorten a switch or flag to the shortest form that distinguishes it
       from the other switches and flags for its operation code. It is often possible to omit
       switches entirely, subject to the conditions listed in "Conditions for Omitting Switches".

       Abbreviating Server Machine Names

       AFS server machines must have fully-qualified Internet-style host names (for example,
       "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.

       Abbreviating Partition Names

       Partitions that house AFS volumes must have names of the form /vicepx or /vicepxx, 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 /vicepa, the second /vicepb,
       and so on.  The OpenAFS QuickStart Guide explains how to configure and name a file server
       machine's partitions in preparation for storing AFS volumes on them.

       When issuing AFS commands, you can abbreviate a partition name using any of the following
       forms:

          /vicepa     =     vicepa      =      a      =      0
          /vicepb     =     vicepb      =      b      =      1

       After /vicepz (for which the index is 25) comes

          /vicepaa    =     vicepaa     =      aa     =      26
          /vicepab    =     vicepab     =      ab     =      27

       and so on through

          /vicepiv    =     vicepiv     =      iv     =      255

       /vicepiv is the last permissible AFS partition name. In practice it will not work well;
       stopping with /vicepiu is highly recommended.

       Abbreviating Cell Names

       A cell's full name usually matches its Internet domain name (such as stateu.edu for the
       State University or "abc.com" for ABC Corporation). Some AFS commands accept unambiguous
       shortened forms, usually with respect to the local /etc/openafs/CellServDB file but
       sometimes depending on the ability of the local name service to resolve the corresponding
       domain name.

       Displaying Online Help for AFS Commands

       To display online help for AFS commands that belong to suites, use the help and apropos
       operation codes.  A -help flag is also available on every almost every AFS command.

       The online help entry for a command consists of two or three lines:

       •   The first line names the command and briefly describes what it does.

       •   If the command has aliases, they appear on the next line.

       •   The final line, which begins with the string "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.

       If no operation code is specified, the help operation code displays the first line (short
       description) for every operation code in the suite:

          % <command_suite> help

       If the issuer specifies one or more operation codes, the help operation code displays each
       command's complete online entry (short description, alias if any, and syntax):

          % <command_suite> help <operation_code>+

       The -help flag displays a command's syntax but not the short description or alias:

          % <command_name> -help

       The apropos operation code displays the short description of any command in a suite whose
       operation code or short description includes the specified keyword:

          % <command_suite> apropos "<help string>"

       The following example command displays the complete online help entry for the 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:

          % 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 fs suite, but cannot remember the operation code.
       She uses quota as the keyword:

          % fs apropos quota
          listquota: list volume quota
          quota: show volume quota usage
          setquota: set volume quota

       The following illustrates the error message that results if no command name or short
       description contains the keyword:

          % fs apropos "list quota"
          Sorry, no commands found

PRIVILEGE REQUIRED

       Many AFS commands require one or more types of administrative privilege. See the reference
       page for each command.

SEE ALSO

       afsd(8), afsmonitor(1), backup(8), bos(8), bosserver(8), buserver(8), butc(8), dlog(1),
       dpass(1), fileserver(8), fms(8), fs(1), fstrace(8), kadb_check(8), kas(8), kaserver(8),
       kdb(8), klog(1), knfs(1), kpasswd(1), kpwvalid(8), package(1), pagsh(1), prdb_check(8),
       pts(1), ptserver(8), rxdebug(1), salvager(8), scout(1), sys(1), tokens(1),
       translate_et(1), unlog(1), up(1), upclient(8), upserver(8), uss(8), vldb_check(8),
       vlserver(8), volinfo(8), volscan(8), volserver(8), vos(1), xfs_size_check(8),
       xstat_cm_test(1), xstat_fs_test(1)

COPYRIGHT

       IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.

       This documentation is covered by the IBM Public License Version 1.0.  It was converted
       from HTML to POD by software written by Chas Williams and Russ Allbery, based on work by
       Alf Wachsmann and Elizabeth Cassell.