Appendix B. AFS Command Syntax and Online Help

The AFS commands available to you are used to authenticate, list AFS information, protect directories, create and manage groups, and create and manage ACLs. There are three general types of commands available to all AFS users: file server commands, protection server commands, and miscellaneous commands. This chapter discusses the syntax of these AFS commands, the rules that must be followed when issuing them, and ways of accessing help relevant to them.

AFS Command Syntax

Most AFS commands use the following syntax:

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

The command suite indicates the general type of command and the server process that performs the command. Regular AFS users have access to two main command suites and a miscellaneous set of commands:

• The fs command suite is used to issue file server commands that interact with the File Server process.
• The pts command suite is used to issue protection-related commands.
• The miscellaneous commands are not associated with any command suite.

The operation code indicates the action that the command performs. Miscellaneous commands have operation codes only.

A command can have multiple options, which can be arguments or flags:

• Arguments are used to supply additional information for use by the command. They consist of a paired switch and instance. A switch defines the type of argument and is always preceded by a hyphen; arguments can take multiple instances if a plus sign (+) appears after the instance. An instance represents some variable piece of information that is used by the command. Arguments can be optional or required.
• Flags are used to direct a command to perform in a specific way (for example, to generate a specific type of output). Flags are always preceded by a hyphen and are always optional.

Command Syntax Example

In the following AFS command

   % fs setacl -dir $HOME -acl pat all terry none -negative

• fs is the command suite.
• setacl is the operation code, which directs the File Server process to set an access control list.
• -dir $HOME and -acl pat all terry none are arguments.
  • -dir and -acl are switches; -dir indicates the name of the directory on which to set the ACL, and -acl defines the entries to set on it.
  • $HOME and pat all terry none are instances of the arguments. $HOME defines a specific directory for the directory argument. The -acl argument has two instances specifying two ACL entries: pat all and terry none.
• -negative is a flag; it directs the command to put the access list entries on the negative rather than the normal permissions list.

Rules for Using AFS Commands

This section describes the rules to follow when using AFS commands.

Spaces and Lines

Separate each command element (command suite, operation code, switches, instances, and flags) with a space. Multiple instances of an argument are also separated by a space.

Type all AFS commands on one line, followed by a carriage return. Some commands in this document appear on more than one line, but that is for legibility only.

Abbreviations and Aliases for Operation Codes

You can type operation codes in one of three ways:

• You can type the operation code in full.
• You can abbreviate the operation code to the shortest form that distinguishes it from the other operation codes in its command suite.
• You can use the alias for the operation code, if one exists.

For example, the fs listacl command can be issued as follows:

• fs listacl (full command)
• fs lista (abbreviation)
• fs la (alias)

The AFS Administration Reference provides information on the full and abbreviated command syntax as well as any aliases for all of the commands discussed in this guide.

Omitting Argument Switches

You can omit an argument's switch if the command takes only one argument, or 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 acceptable to provide multiple values without providing the switch.

For example, the following two commands are equivalent:

   % fs setacl -dir /afs/abc.com/usr/terry/private -acl pat rl
   % fs setacl /afs/abc.com/usr/terry/private pat rl

However, the following is not an acceptable short form because the arguments are not in the prescribed order:

   % fs setacl -acl pat rl /afs/abc.com/usr/terry/private

Shortening Switches and Flags

If you are required to use a switch, or if you decide to use a flag, you can often shorten the name of that switch or flag provided that the shortened form still distinguishes it from the command's other flags and switches.

For example, when you issue the fs setacl command, you can abbreviate all of the switches and flags of the command to their initial letter because they all begin with a different letter. However, when you issue the knfs command, the -host argument and -help flag both begin with the letter h, so the shortest unambiguous abbreviations are -ho and -he respectively.

Shortening Directory References

Most AFS command arguments that require directory or pathnames instances accept one or more of the following short forms:

• A single period (.) indicates the current working directory.
• Two periods (..) indicate the parent directory of the current working directory.
• The $HOME environment variable indicates the issuer's home directory.

For example, if the user terry wants to grant r (read) and l (lookup) permissions on his home directory to his manager pat, terry can issue the following command.

   % fs setacl -dir $HOME -acl pat rl

If the current working directory is terry's home directory, he can issue the following command.

   % fs setacl -dir  .  -acl pat rl 

Both of the previous examples are acceptable short forms for the following command:

   % fs setacl -dir /afs/abc.com/usr/terry -acl pat rl

Commonly Used fs and pts Commands

This section provides additional information on the commonly used AFS fs and pts commands. For more detailed information, see the AFS Administration Reference.

About the fs Commands

Some fs commands extend UNIX file system semantics by invoking file-related functions that UNIX does not provide (setting access control lists, for example). Other fs commands help you control the performance of the Cache Manager running on your local client machine.

All fs commands accept the optional -help flag. It has the same function as the fs help command: it prints a command's online help message on the screen. Do not provide other options at the same time as this flag. It overrides them, and the only effect of issuing the command is to display the help message.

The privilege required for issuing fs commands varies. The necessary privileges for the fs commands described in this guide include the following:

• Having certain permissions on a directory's access control list. For example, creating and removing mount points requires a (administer), i (insert), and d (delete) permissions for the directory in which the mount point resides.
• Belonging to the system:administrators group (see Using the System Groups on ACLs).
• No privilege. Many fs commands simply list information and so do not require any special privilege.

About the pts Commands

The pts command suite is the interface through which you can create protection groups and add members to them. System administrators who belong to a special system group called system:administrators group can manipulate any group, and also create the user and machine entries that can belong to groups. Users who do not belong to the system:administrators group can always list the information associated with the group entries they own, as well as their own user entries. Depending on the setting of an entry's privacy flags, regular users can sometimes access and manipulate group entries in certain ways.

All pts commands accept optional arguments and flags. They are listed in the command descriptions in the AFS Administration Reference and are described here in detail:

[-cell <cell name>]

This argument indicates that the command runs in the indicated cell. The issuer can abbreviate the cell name value to the shortest form that distinguishes it from the other cells listed in the /usr/vice/etc/CellServDB file on the client machine on which the command is issued. By default, commands are executed in the local cell as defined

• First, by the value of the environment variable AFSCELL. (This variable is normally not defined by default. If you are working in another, nonlocal cell for an extended period of time, you can set the variable to the name of that cell.)
• Second, in the /usr/vice/etc/ThisCell file on the client machine on which the command is issued.

[-force]

This flag directs the pts command interpreter to continue executing the command, if possible, even if it encounters problems during the command's execution. The command interpreter performs as much of the requested operation as possible, rather than halting if it encounters a problem. The command interpreter reports any errors it encounters during the command's execution. This flag is especially useful if you provide many instances for an argument; if one of the instances is invalid, the command reports the error and proceeds with the remaining arguments.

[-help]

This flag has the same function as the pts help command: it prints the command's online help message on the screen. Do not provide other options at the same time as this flag. It overrides them, and the only effect of issuing the command is to display the help message.

Getting Help in AFS

AFS online help consists of basic syntax messages. The AFS distribution also includes help in HTML format which your system administrator can make available to you.

Displaying Command Syntax and Aliases

To display a brief description of a command, its syntax statement, and alias if any, use the help operation code. For example, to display the online help entry for the fs listacl command, enter the following command:

   % fs help listacl
   fs listacl: list access control list 
   aliases: la
   Usage: fs listacl  [-path <dir/file path>+]  [-id] [-if] [-help]

To display the syntax statement only, use the -help flag, which is available on most AFS commands. For example, to display the syntax statement for the fs setacl command, enter the following command:

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

Displaying Operation Code Descriptions

To display a short description of all of a command suite's operation codes, issue the help operation code without any other arguments. For example, the fs help command displays a short description of every operation code in the fs command suite.

To display a list of the commands in a command suite that concern a certain type of object, provide a relevant keyword argument to the apropos operation code. For example, if you want to set an ACL but cannot remember which fs command to use, issue the following command:

   % fs apropos set
   setacl: set access control list
   setcachesize: set cache size
   setcell: set cell status
   setclientaddrs: set client network interface addresses
   setquota: set volume quota
   setserverprefs: set file server ranks
   setvol: set volume status
   sysname: get/set sysname (i.e. @sys) value

The following message indicates that there are no commands whose names or descriptions include the keyword string you have provided:

   Sorry, no commands found