NAME

afs - Introduction to Auristor File System (AFS) commands

DESCRIPTION

Auristor 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 Auristor Backup System.

bos

Interface to the Basic Overseer (BOS) Server for administering server processes.

fs

Interface for administering the client Cache Manager and the file namespace including mount points and access control lists (ACLs).

fstrace

Interface for tracing Cache Manager operations when debugging problems.

pts

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

vos

Interface to the Volume Server and Location Server for administering volumes, the file servers they are stored on, and their properties including Maximum Access Lists and Security Policies.

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

Auristor Command Syntax

Auristor 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. Auristor has several command suites, including bos, fs, pts, 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 Auristor Administration Guide describes how to use them in the context of performing administrative tasks.

Several Auristor 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:

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 Auristor command suite.

   % bos getdate -server fs1.your-cell-name.com -file ptserver vlserver

where

Rules for Entering Auristor Commands

Enter each Auristor 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:

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.

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.

An Example of Omitting Switches

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

   % bos getdate -server fs1.your-cell-name.com -file ptserver vlserver

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.your-cell-name.com ptserver vlserver

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.your-cell-name.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 vlserver 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.your-cell-name.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 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.

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

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

Please note that when writing scripts it is important to specify the full name of the operation code in order to avoid failures if new operations are added in the future.

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

Auristor server machines must have fully-qualified Internet-style host names (for example, fs1.your-cell-name.com), but it is not always necessary to type the full name on the command line. Auristor commands accept unambiguous shortened forms but depend on the cell's Domain Name Service 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 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 Auristor QuickStart Guide explains how to configure and name a file server machine's partitions in preparation for storing volumes on them.

When issuing Auristor 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

   /vicepiu    =     vicepiu     =      iu     =      254

/vicepiu is the last acceptable partition name.

Abbreviating Cell Names

A cell's full name usually matches its Internet domain name (such as your-cell-name.com or foreign-cell-name.com. Some Auristor commands accept unambiguous shortened forms, either searching the cells listed in the local configuration /etc/yfs/yfs-client.conf file or querying the local name service to resolve the corresponding domain name.

Displaying Online Help for Auristor Commands

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

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

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 -path <path>+ -acl <access list entries>+ [-clear]
            [-negative] [-help]
   Where: -clear     clear access list
           -negative  apply to negative rights

To see only the syntax statement, use the -help flag:

   % fs setacl -help
   Usage: fs setacl -path <path>+ -acl <access list entries>+ [-clear]
            [-negative] [-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 Auristor commands require one or more types of administrative privilege. See the reference page for each command.

SEE ALSO

afsd(8), backup(8), bos(8), bosserver(8), buserver(8), butc(8), fileserver(8), fms(8), fs(1), fstrace(8), pagsh(1), prdb_check(8), pts(1), ptserver(8), rxdebug(1), rxperf(1), salvager(8), tokens(1), translate_et(1), unlog(1), upclient(8), upserver(8), vldb_check(8), vlserver(8), volinfo(8), volscan(8), volserver(8), vos(1), xstat_cm(1), xstat_fs(1), yfs-client.conf(5), yfs-server.conf(5), yfs-up(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.

ACKNOWLEDGEMENTS

"AFS" is a registered mark of International Business Machines Corporation, used under license. (USPTO Registration 1598389)

"OpenAFS" is a registered mark of International Business Machines Corporation. (USPTO Registration 4577045)

The "AuriStor" name, log 'S' brand mark, and icon are registered marks of AuriStor, Inc. (USPTO Registrations 4849419, 4849421, and 4928460) (EUIPO Registration 015539653).

"Your File System" is a registered mark of AuriStor, Inc. (USPTO Registrations 4801402 and 4849418).

"YFS" and "AuriStor File System" are trademarks of AuriStor, Inc.