[hcoop/debian/openafs.git] / doc / xml / UserGuide / auusg011.xml

<?xml version="1.0" encoding="utf-8"?>
    <appendix id="HDRWQ86"><title>OpenAFS Command Syntax and Online Help</title>

<para>
<indexterm><primary>syntax of AFS commands described</primary></indexterm>

    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.</para>
    <sect1 id="HDRWQ87"><title>OpenAFS Command Syntax</title>
    <para>
<indexterm><primary>commands</primary><secondary>syntax for AFS</secondary></indexterm>
 Most AFS commands use the following syntax:</para>
<programlisting>
   <emphasis role="bold">command_suite operation_code -switch</emphasis> &lt;<replaceable>value</replaceable>&gt;<superscript>[+]</superscript>  <emphasis role="bold">-flag</emphasis>
</programlisting>
    <para>The <emphasis>command suite</emphasis> 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:

<indexterm><primary>commands</primary><secondary>suite organization for AFS</secondary></indexterm>

<indexterm><primary>suite, defined for AFS command</primary></indexterm>
</para>
    <itemizedlist>
      <listitem><para>The <emphasis role="bold">fs</emphasis> command suite is used to issue file server commands that
      interact with the File Server process.</para></listitem>
      <listitem><para>The <emphasis role="bold">pts</emphasis> command suite is used to issue protection-related
      commands.</para></listitem>
      <listitem><para>The miscellaneous commands are not associated with any command suite.</para></listitem>
    </itemizedlist>
    <para>The <emphasis>operation code</emphasis> indicates the action that the command performs. Miscellaneous
    commands have operation codes only.
<indexterm><primary>operation codes in AFS commands</primary><secondary>defined</secondary></indexterm>
</para>
    <para>A command can have multiple <emphasis>options</emphasis>, which can be <emphasis>arguments</emphasis> or
    <emphasis>flags</emphasis>:</para>
    <itemizedlist>
      <listitem><para>Arguments are used to supply additional information for use by the command.

<indexterm><primary>arguments to AFS commands</primary></indexterm>
 They consist of a paired <emphasis>switch</emphasis> and <emphasis>instance</emphasis>.

<indexterm><primary>switches on AFS commands</primary><secondary>defined</secondary></indexterm>

<indexterm><primary>instances to AFS commands</primary></indexterm>
 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.</para></listitem>
      <listitem><para>Flags are used to direct a command to perform in a specific way (for example, to generate a
      specific type of output).
<indexterm><primary>flags on AFS commands</primary></indexterm>
 Flags are always preceded by a hyphen and are always
      optional.</para></listitem>
    </itemizedlist>
    <sect2 id="Header_169"><title>Command Syntax Example</title>
    <para>In the following AFS command</para>
<programlisting>
   % <emphasis role="bold">fs setacl -dir $HOME -acl pat all terry none -negative</emphasis>
</programlisting>
    <itemizedlist>
      <listitem><para><emphasis role="bold">fs</emphasis> is the command suite.</para></listitem>
      <listitem><para><emphasis role="bold">setacl</emphasis> is the <emphasis>operation code</emphasis>, which directs
      the File Server process to set an access control list.</para></listitem>
      <listitem><para>
        <emphasis role="bold">-dir $HOME</emphasis> and <emphasis role="bold">-acl pat all terry none</emphasis> are
        <emphasis>arguments</emphasis>.
        </para><itemizedlist>
          <listitem><para><emphasis role="bold">-dir</emphasis> and <emphasis role="bold">-acl</emphasis> are switches;
          <emphasis role="bold">-dir</emphasis> indicates the name of the directory on which to set the ACL, and
          <emphasis role="bold">-acl</emphasis> defines the entries to set on it.</para></listitem>
          <listitem><para><emphasis role="bold">$HOME</emphasis> and <emphasis role="bold">pat all terry
          none</emphasis> are <emphasis>instances</emphasis> of the arguments. <emphasis role="bold">$HOME</emphasis>
          defines a specific directory for the directory argument. The <emphasis role="bold">-acl</emphasis> argument
          has two instances specifying two ACL entries: <emphasis role="bold">pat all</emphasis> and
          <emphasis role="bold">terry none</emphasis>.</para></listitem>
        </itemizedlist>
      </listitem>
      <listitem><para><emphasis role="bold">-negative</emphasis> is a flag; it directs the command to put the access
      list entries on the negative rather than the normal permissions list.</para></listitem>
    </itemizedlist>
    </sect2></sect1><sect1 id="HDRWQ88"><title>Rules for Using OpenAFS Commands</title>
    <para>This section describes the rules to follow when using AFS commands.</para>
    <sect2 id="Header_171"><title>Spaces and Lines</title>
    <para>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.</para>
    <para>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.</para>
    </sect2><sect2 id="Header_172"><title>Abbreviations and Aliases for Operation Codes</title>

<indexterm><primary>operation codes in AFS commands</primary><secondary>abbreviating</secondary></indexterm>

    <para>You can type operation codes in one of three ways:</para>
    <itemizedlist>
      <listitem><para>You can type the operation code in full.</para></listitem>
      <listitem><para>You can abbreviate the operation code to the shortest form that distinguishes it from the other
      operation codes in its command suite.</para></listitem>
      <listitem><para>You can use the alias for the operation code, if one exists.</para></listitem>
    </itemizedlist>
    <para>For example, the <emphasis role="bold">fs listacl</emphasis> command can be issued as follows:</para>
    <itemizedlist>
      <listitem><para><emphasis role="bold">fs listacl</emphasis> (full command)</para></listitem>
      <listitem><para><emphasis role="bold">fs lista</emphasis> (abbreviation)</para></listitem>
      <listitem><para><emphasis role="bold">fs la</emphasis> (alias)</para></listitem>
    </itemizedlist>
    <para>The <emphasis>OpenAFS Administration Reference</emphasis> provides information on the full and abbreviated
    command syntax as well as any aliases for all of the commands discussed in this guide.</para>
    </sect2><sect2 id="Header_173"><title>Omitting Argument Switches</title>

<indexterm><primary>switches on AFS commands</primary><secondary>omitting</secondary></indexterm>

    <para>You can omit an argument's switch if the command takes only one argument, or if the following conditions are
    met.</para>
    <itemizedlist>
      <listitem><para>All of the command's required arguments appear in the order prescribed by the syntax
      statement.</para></listitem>
      <listitem><para>No switches are used on any arguments, even if they are in the correct order.</para></listitem>
      <listitem><para>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.</para></listitem>
    </itemizedlist>
    <para>For example, the following two commands are equivalent:</para>
<programlisting>
   % <emphasis role="bold">fs setacl -dir /afs/example.com/usr/terry/private -acl pat rl</emphasis>
   % <emphasis role="bold">fs setacl /afs/example.com/usr/terry/private pat rl</emphasis>
</programlisting>
    <para>However, the following is not an acceptable short form because the arguments are not in the prescribed
    order:</para>
<programlisting>
   % <emphasis role="bold">fs setacl -acl pat rl /afs/example.com/usr/terry/private</emphasis>
</programlisting>
    </sect2><sect2 id="Header_174"><title>Shortening Switches and Flags</title>
    <para>
<indexterm><primary>switches on AFS commands</primary><secondary>abbreviating</secondary></indexterm>
 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.</para>
    <para>For example, when you issue the <emphasis role="bold">fs setacl</emphasis> 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 <emphasis role="bold">knfs</emphasis> command, the
    <emphasis role="bold">-host</emphasis> argument and <emphasis role="bold">-help</emphasis> flag both begin with the
    letter <emphasis role="bold">h</emphasis>, so the shortest unambiguous abbreviations are
    <emphasis role="bold">-ho</emphasis> and <emphasis role="bold">-he</emphasis> respectively.</para>
    </sect2><sect2 id="Header_175"><title>Shortening Directory References</title>
    <para>
<indexterm><primary>directories</primary><secondary>shorthand notation for referencing</secondary></indexterm>
 Most AFS command arguments that require directory or pathnames instances accept one
    or more of the following short forms:</para>
    <itemizedlist>
      <listitem><para>A single period (<emphasis role="bold">.</emphasis>) indicates the current working
      directory.</para></listitem>
      <listitem><para>Two periods (<emphasis role="bold">..</emphasis>) indicate the parent directory of the current
      working directory.</para></listitem>
      <listitem><para>The $HOME environment variable indicates the issuer's home directory.</para></listitem>
    </itemizedlist>
    <para>For example, if the user <emphasis role="bold">terry</emphasis> wants to grant
    <emphasis role="bold">r</emphasis> (<emphasis role="bold">read</emphasis>) and <emphasis role="bold">l</emphasis>
    (<emphasis role="bold">lookup</emphasis>) permissions on his home directory to his manager
    <emphasis role="bold">pat</emphasis>, <emphasis role="bold">terry</emphasis> can issue the following
    command.</para>
<programlisting>
   % <emphasis role="bold">fs setacl -dir $HOME -acl pat rl</emphasis>
</programlisting>
    <para>If the current working directory is <emphasis role="bold">terry</emphasis>'s home directory, he can issue the
    following command.</para>
<programlisting>
   % <emphasis role="bold">fs setacl -dir  .  -acl pat rl</emphasis>
</programlisting>
    <para>Both of the previous examples are acceptable short forms for the following command:</para>
<programlisting>
   % <emphasis role="bold">fs setacl -dir /afs/example.com/usr/terry -acl pat rl</emphasis>
</programlisting>
    </sect2></sect1><sect1 id="Header_176"><title>Commonly Used fs and pts Commands</title>
    <para>This section provides additional information on the commonly used AFS <emphasis role="bold">fs</emphasis> and
    <emphasis role="bold">pts</emphasis> commands. For more detailed information, see the <emphasis>OpenAFS
    Administration Reference</emphasis>.</para>
    <sect2 id="Header_177"><title>About the fs Commands</title>

<indexterm><primary>fs commands</primary><secondary>introduction</secondary></indexterm>

    <para>Some <emphasis role="bold">fs</emphasis> commands extend UNIX file system semantics by invoking file-related
    functions that UNIX does not provide (setting access control lists, for example). Other
    <emphasis role="bold">fs</emphasis> commands help you control the performance of the Cache Manager running on your
    local client machine.
<indexterm><primary>fs commands</primary><secondary>help flag</secondary></indexterm>

<indexterm><primary>fs commands</primary><secondary>getting help</secondary></indexterm>
</para>
    <para>All <emphasis role="bold">fs</emphasis> commands accept the optional <emphasis role="bold">-help</emphasis>
    flag. It has the same function as the <emphasis role="bold">fs help</emphasis> 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.
<indexterm><primary>fs commands</primary><secondary>privileges required</secondary></indexterm>
</para>
    <para>The privilege required for issuing <emphasis role="bold">fs</emphasis> commands varies. The necessary
    privileges for the <emphasis role="bold">fs</emphasis> commands described in this guide include the
    following:</para>
    <itemizedlist>
      <listitem><para>Having certain permissions on a directory's access control list. For example, creating and
      removing mount points requires <emphasis role="bold">a</emphasis> (<emphasis role="bold">administer</emphasis>),
      <emphasis role="bold">i</emphasis> (<emphasis role="bold">insert</emphasis>), and
      <emphasis role="bold">d</emphasis> (<emphasis role="bold">delete</emphasis>) permissions for the directory in
      which the mount point resides.</para></listitem>
      <listitem><para>Belonging to the <emphasis role="bold">system:administrators</emphasis> group (see
      <link linkend="HDRWQ50">Using the System Groups on ACLs</link>).</para></listitem>
      <listitem><para>No privilege. Many <emphasis role="bold">fs</emphasis> commands simply list information and so do
      not require any special privilege.</para></listitem>
    </itemizedlist>
    </sect2><sect2 id="Header_178"><title>About the pts Commands</title>

<indexterm><primary>pts commands</primary><secondary>privilege required</secondary></indexterm>

<indexterm><primary>Protection Database</primary></indexterm>

    <para>The <emphasis role="bold">pts</emphasis> 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
    <emphasis role="bold">system:administrators</emphasis> 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
    <emphasis role="bold">system:administrators</emphasis> 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.</para>
    <para>All <emphasis role="bold">pts</emphasis> commands accept optional arguments and flags. They are listed in the
    command descriptions in the <emphasis>OpenAFS Administration Reference</emphasis> and are described here in
    detail:</para>
    <variablelist>

<indexterm><primary>pts commands</primary><secondary>cell argument</secondary></indexterm>

      <varlistentry><term><emphasis role="bold">[-cell &lt;<replaceable>cell name</replaceable>&gt;]</emphasis></term>
      <listitem><para>
        This argument indicates that the command runs in the indicated cell. The issuer can abbreviate the
        <replaceable>cell name</replaceable> value to the shortest form that distinguishes it from the other cells
        listed in the <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> file on the client machine on which the
        command is issued. By default, commands are executed in the local cell as defined
        </para><itemizedlist>
          <listitem><para>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.)</para></listitem>
          <listitem><para>Second, in the <emphasis role="bold">/usr/vice/etc/ThisCell</emphasis> file on the client
          machine on which the command is issued.</para></listitem>
        </itemizedlist>
      </listitem></varlistentry>
    </variablelist>
    <variablelist>
      <varlistentry><term><emphasis role="bold">[-force]</emphasis></term>
      <listitem><para>This flag directs the <emphasis role="bold">pts</emphasis> command interpreter to continue
      executing the command, if possible, even if it encounters problems during the command's execution.

<indexterm><primary>pts commands</primary><secondary>force flag</secondary></indexterm>
 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.</para></listitem></varlistentry>
    </variablelist>
    <variablelist>
      <varlistentry><term><emphasis role="bold">[-help]
<indexterm><primary>pts commands</primary><secondary>help flag</secondary></indexterm>


<indexterm><primary>pts commands</primary><secondary>getting help</secondary></indexterm>
</emphasis></term>
      <listitem><para>This flag has the same function as the <emphasis role="bold">pts help</emphasis> 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.</para></listitem></varlistentry>
    </variablelist>
    </sect2></sect1><sect1 id="HDRWQ89"><title>Getting Help in AFS</title>

<indexterm><primary>help</primary><secondary>online for AFS commands</secondary></indexterm>

<indexterm><primary>online help</primary></indexterm>

    <para>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.</para>
    <sect2 id="Header_180"><title>Displaying Command Syntax and Aliases</title>

<indexterm><primary>apropos operation code</primary></indexterm>

<indexterm><primary>help</primary><secondary>operation code in AFS command suites</secondary></indexterm>

<indexterm><primary>help</primary><secondary>examples</secondary></indexterm>

    <para>To display a brief description of a command, its syntax statement, and alias if any, use the
    <emphasis role="bold">help</emphasis> operation code. For example, to display the online help entry for the
    <emphasis role="bold">fs listacl</emphasis> command, enter the following command:</para>
<programlisting>
   % <emphasis role="bold">fs help listacl</emphasis>
   fs listacl: list access control list
   aliases: la
   Usage: fs listacl  [-path &lt;dir/file path&gt;+]  [-id] [-if] [-help]
</programlisting>
    <para>To display the syntax statement only, use the <emphasis role="bold">-help</emphasis> flag, which is available
    on most AFS commands. For example, to display the syntax statement for the <emphasis role="bold">fs
    setacl</emphasis> command, enter the following command:</para>
<programlisting>
   % <emphasis role="bold">fs setacl -help</emphasis>
   Usage: fs setacl -dir &lt;directory&gt;+ -acl &lt;access list entries&gt;+ [-clear] [-negative]
   [-id] [-if] [-help]
</programlisting>
    </sect2><sect2 id="Header_181"><title>Displaying Operation Code Descriptions</title>
    <para>To display a short description of all of a command suite's operation codes, issue the
    <emphasis role="bold">help</emphasis> operation code without any other arguments. For example, the
    <emphasis role="bold">fs help</emphasis> command displays a short description of every operation code in the
    <emphasis role="bold">fs</emphasis> command suite.
<indexterm><primary>keyword for apropos command</primary></indexterm>
</para>
    <para>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 <emphasis role="bold">apropos</emphasis> operation code. For example, if you want
    to set an ACL but cannot remember which <emphasis role="bold">fs</emphasis> command to use, issue the following
    command:</para>
<programlisting>
   % <emphasis role="bold">fs apropos set</emphasis>
   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
</programlisting>
    <para>The following message indicates that there are no commands whose names or descriptions include the keyword
    string you have provided:</para>
<programlisting>
   Sorry, no commands found
</programlisting>
    <note>
        <para>If the keyword you provide has spaces in it, enclose it in double quotes (<emphasis role="bold">"
        "</emphasis>).</para>
    </note>
</sect2></sect1></appendix>