Command Reference Manual

How to Use This Document

Refer to this document when you need detailed information about a specific command. For a description of all the steps in a procedure, refer to the AFS System Administrator's Guide.

Related Documents

The following documents are included in the AFS documentation set.

AFS System Administrator's Guide

This guide describes the concepts and procedures that a system administrator must know to manage an AFS cell. It assumes familiarity with UNIX, but requires no previous knowledge of AFS.

The first chapters of the AFS System Administrator's Guide present basic concepts and guidelines. Understanding them is crucial to successful administration of an AFS cell. The remaining chapters in the guide provide step-by-step instructions for specific administrative tasks, along with discussions of the concepts important to that particular task.

AFS Installation Guide

This guide provides instructions for installing AFS server and client machines. It is assumed that the installer is an experienced UNIX ^(R) system administrator.

For predictable performance, machines must be installed and configured in accordance with the instructions in this guide.

AFS Release Notes

This document provides information specific to each release of AFS, such as a list of new features and commands, a list of requirements and limitations, and instructions for upgrading server and client machines.

AFS User's Guide

This guide presents the basic concepts and procedures necessary for using AFS effectively. It assumes that the reader has some experience with UNIX, but does not require familiarity with networking or AFS.

The guide explains how to perform basic functions including logging in, changing a password, listing information, protecting files, creating groups, and troubleshooting. It provides illustrative examples for each function and describes some of the differences between the UNIX file system and AFS.

Document Conventions

This document uses the following conventions:

• Command and option names appear in bold type in syntax definitions, examples, and running text.

• Variable information appears in italic type. This includes user-supplied information on command lines and the parts of prompts that differ depending on who issues the command.

• Names of directories, files, server machines, partitions, volumes, and users appear in bold type.

• New terms appear in italic type.

• Examples of screen output and file contents appear in monospace type.

In addition, the following symbols appear in command syntax definitions, both in the manuals and in AFS online help statements. When issuing a command, do not type these symbols.

• Square brackets [ ] surround optional items.

• Angle brackets < > surround user-supplied values in AFS commands.

• A superscripted plus sign + follows an argument that accepts more than one value.

• The percent sign % represents the regular command shell prompt. Different operating systems can use a different character for this prompt.

• The number sign # represents the command shell prompt for the local superuser root. Different operating systems can use a different character for this prompt.

• The pipe symbol | in a command syntax statement separates mutually exclusive values for an argument.

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. The name indicates which command interpreter and server process perform the command. AFS has several command suites, including bos, fs, kas, package, pts, scout, uss and vos. Some of these suites have an interactive mode in which the command_suite portion of the command name is omitted.

The operation_code tells the command interpreter and server process what action to perform. Most command suites include multiple operation codes. The AFS Command Reference Manual describes each operation code in detail, and the AFS System Administrator's Guide describes how to use them in the context of performing administrative tasks.

Several AFS commands do not belong to a suite and so do not have a command_suite portion in their name. They are 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

Following the command name come one or more arguments, each of which has two parts: a switch and an value. Arguments tell the command interpreter and server process which entities to act on while performing the command (for example, which file 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.

The two parts of an argument appear in this 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 file server machine. Switches can usually be omitted, subject to the rules outlined in Rules 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 file server machine name like fs1.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 plus sign ( + ) in the command descriptions and online help. The number and prescribed order of arguments that take multiple values affects when it is legal to omit the switches. See Rules 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 all flags after all values, there is no prescribed order for flags. They can appear anywhere on the command line following the operation code, except in between a switch and its values. Flags are always optional.

An Example Command

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

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

• 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 file server machine (in this case fs1.abc.com) to report the modification dates of binary files in the /usr/afs/bin directory on its local disk.

• -server fs1.abc.com is one argument, with -server as the switch and fs1.abc.com as the value. This argument specifies the file 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/afs/bin/kaserver and /usr/afs/bin/ptserver.

• -noauth is a flag. It tells the BOS Server not to attempt to authenticate the issuer of the command.

Rules for Typing AFS Commands

Enter each AFS command on a single line, followed by a carriage 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 (command suite, operation code, switch, value, flag) from its neighbors. Spaces (not commas) also separate multiple values of an argument.

In many cases, it is possible to reduce the typing necessary on a command line by

• Omitting the switch

• 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 legal to type a command in full, with all of its switches and no abbreviations.

Rules for Omitting Switches

It is always acceptable to type the switch part of an argument, but in many cases it is not necessary. Specifically, a command's 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 switches are used on any arguments, even if they are in the correct order.

• There is only one value for each argument. The important exception to this condition is if the final required argument accepts multiple values ; in this case, it is legal to provide multiple values without providing the switch.

Omitting switches is possible only because there is a prescribed order for the arguments in each AFS command. If no switches are provided to distinguish arguments from one another, 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, that the next element is the command's second argument, and so on. The important exception is when a command's final required argument takes 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 summarizes 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 argument (even an optional one) that precedes this argument in the syntax statement is missing.

• 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 thinks that the current argument is simply 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 -noauth

This command has two required arguments: the file server machine name (identified by the -server switch ) and binary file name (identified by the -file switch). The second argument accepts multiple values. By obeying all three conditions, the issuer can omit the switches:

   % bos getdate fs1.abc.com ptserver kaserver -noauth

Because there are no switches (-noauth is a flag, not a switch), 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 file 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 value, the command interpreter correctly interprets kaserver as an additional value.

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

Rules for Using Abbreviations and Aliases

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

Abbreviating Command Names

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 legal 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. Note that it is legal 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

It is acceptable to shorten a switch to the shortest form that distinguishes it from the other switches for its operation code. It is often possible to omit switches entirely subject to the conditions listed in Rules for Omitting Switches.

Abbreviating File Server Machine Names

File 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 AFS Installation 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

and so on through

   /vicepiv    =     vicepiv     =      iv     =      255

Abbreviating Cell Names

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

Getting Online Help on AFS Commands

To access online help for AFS commands that belong to suites, use the help and apropos operation codes. The -help flag is 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 symbols (brackets and so on) as described in Document Conventions.

The help operation code displays the first line (short description) for every operation code in the suite if no operation code is specified, or the complete online entry (short description, alias if any, and syntax) for each specified operation code. Use it to see a complete list of a suite's operation codes or to review a command's syntax.

The -help flag displays the syntax for the command (it does not display the short description or alias).

The apropos operation code lists a short description of any command in a suite whose operation code or short online description includes the specified keyword.

To display the brief descriptions of all commands in a suite, enter the following command.

   % command_suite  help

To display the complete help entry for one or more operation codes, enter one of the following commands.

   % command_name help operation_code+
   % command_name operation_code -help  

To display all commands that include a certain keyword, type the following command:

   % command_name apropos "<help string>"

As an example, the following 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, type the following:

    % fs setacl -help -help
   Usage: fs setacl -dir <directory>+ -acl <access list entries>+ [-clear] 
                    [-negative] [-id] [-if] [-help]

As an example of using the apropos operation code, suppose that a user wants to list the quota on her directory. She knows that the relevant command belongs to the fs suite, but cannot remember the operation code. She uses list as the keyword:

   % fs apropos list
   cleanacl: clean up access control list
   copyacl: Copy access control list
   listacl: list access control list
   listcells: list configured cells
   listquota: list volume quota
   lsmount: list mount point
   primarycell: obsolete (listed primary cell)
   setacl: set access control list
   whereis: list file's location
   whichcell: list file's cell
   wscell: list workstation's cell

Using quota as the keyword yields more succinct results:

   % 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