doc/xml/UserGuide/auusg011.xml

   1 <?xml version="1.0" encoding="utf-8"?>
   2     <appendix id="HDRWQ86"><title>OpenAFS Command Syntax and Online Help</title>
   3
   4 <indexterm><primary>syntax of AFS commands described</primary></indexterm>
   5
   6     <para>The AFS commands available to you are used to authenticate, list AFS information, protect directories, create
   7     and manage groups, and create and manage ACLs. There are three general types of commands available to all AFS
   8     users: file server commands, protection server commands, and miscellaneous commands. This chapter discusses the
   9     syntax of these AFS commands, the rules that must be followed when issuing them, and ways of accessing help
  10     relevant to them.</para>
  11     <sect1 id="HDRWQ87"><title>OpenAFS Command Syntax</title>
  12     <para>
  13 <indexterm><primary>commands</primary><secondary>syntax for AFS</secondary></indexterm>
  14  Most AFS commands use the following syntax:</para>
  15 <programlisting>
  16    <emphasis role="bold">command_suite operation_code -switch</emphasis> &lt;<replaceable>value</replaceable>&gt;<superscript>[+]</superscript>  <emphasis role="bold">-flag</emphasis>
  17 </programlisting>
  18     <para>The <emphasis>command suite</emphasis> indicates the general type of command and the server process that
  19     performs the command. Regular AFS users have access to two main command suites and a miscellaneous set of commands:
  20
  21 <indexterm><primary>commands</primary><secondary>suite organization for AFS</secondary></indexterm>
  22
  23 <indexterm><primary>suite, defined for AFS command</primary></indexterm>
  24 </para>
  25     <itemizedlist>
  26       <listitem><para>The <emphasis role="bold">fs</emphasis> command suite is used to issue file server commands that
  27       interact with the File Server process.</para></listitem>
  28       <listitem><para>The <emphasis role="bold">pts</emphasis> command suite is used to issue protection-related
  29       commands.</para></listitem>
  30       <listitem><para>The miscellaneous commands are not associated with any command suite.</para></listitem>
  31     </itemizedlist>
  32     <para>The <emphasis>operation code</emphasis> indicates the action that the command performs. Miscellaneous
  33     commands have operation codes only.
  34 <indexterm><primary>operation codes in AFS commands</primary><secondary>defined</secondary></indexterm>
  35 </para>
  36     <para>A command can have multiple <emphasis>options</emphasis>, which can be <emphasis>arguments</emphasis> or
  37     <emphasis>flags</emphasis>:</para>
  38     <itemizedlist>
  39       <listitem><para>Arguments are used to supply additional information for use by the command.
  40
  41 <indexterm><primary>arguments to AFS commands</primary></indexterm>
  42  They consist of a paired <emphasis>switch</emphasis> and <emphasis>instance</emphasis>.
  43
  44 <indexterm><primary>switches on AFS commands</primary><secondary>defined</secondary></indexterm>
  45
  46 <indexterm><primary>instances to AFS commands</primary></indexterm>
  47  A switch defines the type of argument and is always preceded
  48       by a hyphen; arguments can take multiple instances if a plus sign (+) appears after the instance. An instance
  49       represents some variable piece of information that is used by the command. Arguments can be optional or
  50       required.</para></listitem>
  51       <listitem><para>Flags are used to direct a command to perform in a specific way (for example, to generate a
  52       specific type of output).
  53 <indexterm><primary>flags on AFS commands</primary></indexterm>
  54  Flags are always preceded by a hyphen and are always
  55       optional.</para></listitem>
  56     </itemizedlist>
  57     <sect2 id="Header_169"><title>Command Syntax Example</title>
  58     <para>In the following AFS command</para>
  59 <programlisting>
  60    % <emphasis role="bold">fs setacl -dir $HOME -acl pat all terry none -negative</emphasis>
  61 </programlisting>
  62     <itemizedlist>
  63       <listitem><para><emphasis role="bold">fs</emphasis> is the command suite.</para></listitem>
  64       <listitem><para><emphasis role="bold">setacl</emphasis> is the <emphasis>operation code</emphasis>, which directs
  65       the File Server process to set an access control list.</para></listitem>
  66       <listitem><para>
  67         <emphasis role="bold">-dir $HOME</emphasis> and <emphasis role="bold">-acl pat all terry none</emphasis> are
  68         <emphasis>arguments</emphasis>.
  69         </para><itemizedlist>
  70           <listitem><para><emphasis role="bold">-dir</emphasis> and <emphasis role="bold">-acl</emphasis> are switches;
  71           <emphasis role="bold">-dir</emphasis> indicates the name of the directory on which to set the ACL, and
  72           <emphasis role="bold">-acl</emphasis> defines the entries to set on it.</para></listitem>
  73           <listitem><para><emphasis role="bold">$HOME</emphasis> and <emphasis role="bold">pat all terry
  74           none</emphasis> are <emphasis>instances</emphasis> of the arguments. <emphasis role="bold">$HOME</emphasis>
  75           defines a specific directory for the directory argument. The <emphasis role="bold">-acl</emphasis> argument
  76           has two instances specifying two ACL entries: <emphasis role="bold">pat all</emphasis> and
  77           <emphasis role="bold">terry none</emphasis>.</para></listitem>
  78         </itemizedlist>
  79       </listitem>
  80       <listitem><para><emphasis role="bold">-negative</emphasis> is a flag; it directs the command to put the access
  81       list entries on the negative rather than the normal permissions list.</para></listitem>
  82     </itemizedlist>
  83     </sect2></sect1><sect1 id="HDRWQ88"><title>Rules for Using OpenAFS Commands</title>
  84     <para>This section describes the rules to follow when using AFS commands.</para>
  85     <sect2 id="Header_171"><title>Spaces and Lines</title>
  86     <para>Separate each command element (command suite, operation code, switches, instances, and flags) with a space.
  87     Multiple instances of an argument are also separated by a space.</para>
  88     <para>Type all AFS commands on one line, followed by a carriage return. Some commands in this document appear on
  89     more than one line, but that is for legibility only.</para>
  90     </sect2><sect2 id="Header_172"><title>Abbreviations and Aliases for Operation Codes</title>
  91
  92 <indexterm><primary>operation codes in AFS commands</primary><secondary>abbreviating</secondary></indexterm>
  93
  94     <para>You can type operation codes in one of three ways:</para>
  95     <itemizedlist>
  96       <listitem><para>You can type the operation code in full.</para></listitem>
  97       <listitem><para>You can abbreviate the operation code to the shortest form that distinguishes it from the other
  98       operation codes in its command suite.</para></listitem>
  99       <listitem><para>You can use the alias for the operation code, if one exists.</para></listitem>
 100     </itemizedlist>
 101     <para>For example, the <emphasis role="bold">fs listacl</emphasis> command can be issued as follows:</para>
 102     <itemizedlist>
 103       <listitem><para><emphasis role="bold">fs listacl</emphasis> (full command)</para></listitem>
 104       <listitem><para><emphasis role="bold">fs lista</emphasis> (abbreviation)</para></listitem>
 105       <listitem><para><emphasis role="bold">fs la</emphasis> (alias)</para></listitem>
 106     </itemizedlist>
 107     <para>The <emphasis>OpenAFS Administration Reference</emphasis> provides information on the full and abbreviated
 108     command syntax as well as any aliases for all of the commands discussed in this guide.</para>
 109     </sect2><sect2 id="Header_173"><title>Omitting Argument Switches</title>
 110
 111 <indexterm><primary>switches on AFS commands</primary><secondary>omitting</secondary></indexterm>
 112
 113     <para>You can omit an argument's switch if the command takes only one argument, or if the following conditions are
 114     met.</para>
 115     <itemizedlist>
 116       <listitem><para>All of the command's required arguments appear in the order prescribed by the syntax
 117       statement.</para></listitem>
 118       <listitem><para>No switches are used on any arguments, even if they are in the correct order.</para></listitem>
 119       <listitem><para>There is only one value for each argument. The important exception to this condition is if the
 120       final required argument accepts multiple values; in this case, it is acceptable to provide multiple values
 121       without providing the switch.</para></listitem>
 122     </itemizedlist>
 123     <para>For example, the following two commands are equivalent:</para>
 124 <programlisting>
 125    % <emphasis role="bold">fs setacl -dir /afs/abc.com/usr/terry/private -acl pat rl</emphasis>
 126    % <emphasis role="bold">fs setacl /afs/abc.com/usr/terry/private pat rl</emphasis>
 127 </programlisting>
 128     <para>However, the following is not an acceptable short form because the arguments are not in the prescribed
 129     order:</para>
 130 <programlisting>
 131    % <emphasis role="bold">fs setacl -acl pat rl /afs/abc.com/usr/terry/private</emphasis>
 132 </programlisting>
 133     </sect2><sect2 id="Header_174"><title>Shortening Switches and Flags</title>
 134     <para>
 135 <indexterm><primary>switches on AFS commands</primary><secondary>abbreviating</secondary></indexterm>
 136  If you are required to use a switch, or if you decide to use a flag, you can often
 137     shorten the name of that switch or flag provided that the shortened form still distinguishes it from the command's
 138     other flags and switches.</para>
 139     <para>For example, when you issue the <emphasis role="bold">fs setacl</emphasis> command, you can abbreviate all of
 140     the switches and flags of the command to their initial letter because they all begin with a different letter.
 141     However, when you issue the <emphasis role="bold">knfs</emphasis> command, the
 142     <emphasis role="bold">-host</emphasis> argument and <emphasis role="bold">-help</emphasis> flag both begin with the
 143     letter <emphasis role="bold">h</emphasis>, so the shortest unambiguous abbreviations are
 144     <emphasis role="bold">-ho</emphasis> and <emphasis role="bold">-he</emphasis> respectively.</para>
 145     </sect2><sect2 id="Header_175"><title>Shortening Directory References</title>
 146     <para>
 147 <indexterm><primary>directories</primary><secondary>shorthand notation for referencing</secondary></indexterm>
 148  Most AFS command arguments that require directory or pathnames instances accept one
 149     or more of the following short forms:</para>
 150     <itemizedlist>
 151       <listitem><para>A single period (<emphasis role="bold">.</emphasis>) indicates the current working
 152       directory.</para></listitem>
 153       <listitem><para>Two periods (<emphasis role="bold">..</emphasis>) indicate the parent directory of the current
 154       working directory.</para></listitem>
 155       <listitem><para>The $HOME environment variable indicates the issuer's home directory.</para></listitem>
 156     </itemizedlist>
 157     <para>For example, if the user <emphasis role="bold">terry</emphasis> wants to grant
 158     <emphasis role="bold">r</emphasis> (<emphasis role="bold">read</emphasis>) and <emphasis role="bold">l</emphasis>
 159     (<emphasis role="bold">lookup</emphasis>) permissions on his home directory to his manager
 160     <emphasis role="bold">pat</emphasis>, <emphasis role="bold">terry</emphasis> can issue the following
 161     command.</para>
 162 <programlisting>
 163    % <emphasis role="bold">fs setacl -dir $HOME -acl pat rl</emphasis>
 164 </programlisting>
 165     <para>If the current working directory is <emphasis role="bold">terry</emphasis>'s home directory, he can issue the
 166     following command.</para>
 167 <programlisting>
 168    % <emphasis role="bold">fs setacl -dir  .  -acl pat rl</emphasis>
 169 </programlisting>
 170     <para>Both of the previous examples are acceptable short forms for the following command:</para>
 171 <programlisting>
 172    % <emphasis role="bold">fs setacl -dir /afs/abc.com/usr/terry -acl pat rl</emphasis>
 173 </programlisting>
 174     </sect2></sect1><sect1 id="Header_176"><title>Commonly Used fs and pts Commands</title>
 175     <para>This section provides additional information on the commonly used AFS <emphasis role="bold">fs</emphasis> and
 176     <emphasis role="bold">pts</emphasis> commands. For more detailed information, see the <emphasis>OpenAFS
 177     Administration Reference</emphasis>.</para>
 178     <sect2 id="Header_177"><title>About the fs Commands</title>
 179
 180 <indexterm><primary>fs commands</primary><secondary>introduction</secondary></indexterm>
 181
 182     <para>Some <emphasis role="bold">fs</emphasis> commands extend UNIX file system semantics by invoking file-related
 183     functions that UNIX does not provide (setting access control lists, for example). Other
 184     <emphasis role="bold">fs</emphasis> commands help you control the performance of the Cache Manager running on your
 185     local client machine.
 186 <indexterm><primary>fs commands</primary><secondary>help flag</secondary></indexterm>
 187
 188 <indexterm><primary>fs commands</primary><secondary>getting help</secondary></indexterm>
 189 </para>
 190     <para>All <emphasis role="bold">fs</emphasis> commands accept the optional <emphasis role="bold">-help</emphasis>
 191     flag. It has the same function as the <emphasis role="bold">fs help</emphasis> command: it prints a command's
 192     online help message on the screen. Do not provide other options at the same time as this flag. It overrides them,
 193     and the only effect of issuing the command is to display the help message.
 194 <indexterm><primary>fs commands</primary><secondary>privileges required</secondary></indexterm>
 195 </para>
 196     <para>The privilege required for issuing <emphasis role="bold">fs</emphasis> commands varies. The necessary
 197     privileges for the <emphasis role="bold">fs</emphasis> commands described in this guide include the
 198     following:</para>
 199     <itemizedlist>
 200       <listitem><para>Having certain permissions on a directory's access control list. For example, creating and
 201       removing mount points requires <emphasis role="bold">a</emphasis> (<emphasis role="bold">administer</emphasis>),
 202       <emphasis role="bold">i</emphasis> (<emphasis role="bold">insert</emphasis>), and
 203       <emphasis role="bold">d</emphasis> (<emphasis role="bold">delete</emphasis>) permissions for the directory in
 204       which the mount point resides.</para></listitem>
 205       <listitem><para>Belonging to the <emphasis role="bold">system:administrators</emphasis> group (see
 206       <link linkend="HDRWQ50">Using the System Groups on ACLs</link>).</para></listitem>
 207       <listitem><para>No privilege. Many <emphasis role="bold">fs</emphasis> commands simply list information and so do
 208       not require any special privilege.</para></listitem>
 209     </itemizedlist>
 210     </sect2><sect2 id="Header_178"><title>About the pts Commands</title>
 211
 212 <indexterm><primary>pts commands</primary><secondary>privilege required</secondary></indexterm>
 213
 214 <indexterm><primary>Protection Database</primary></indexterm>
 215
 216     <para>The <emphasis role="bold">pts</emphasis> command suite is the interface through which you can create
 217     protection groups and add members to them. System administrators who belong to a special system group called
 218     <emphasis role="bold">system:administrators</emphasis> group can manipulate any group, and also create the user and
 219     machine entries that can belong to groups. Users who do not belong to the
 220     <emphasis role="bold">system:administrators</emphasis> group can always list the information associated with the
 221     group entries they own, as well as their own user entries. Depending on the setting of an entry's privacy flags,
 222     regular users can sometimes access and manipulate group entries in certain ways.</para>
 223     <para>All <emphasis role="bold">pts</emphasis> commands accept optional arguments and flags. They are listed in the
 224     command descriptions in the <emphasis>OpenAFS Administration Reference</emphasis> and are described here in
 225     detail:</para>
 226     <variablelist>
 227
 228 <indexterm><primary>pts commands</primary><secondary>cell argument</secondary></indexterm>
 229
 230       <varlistentry><term><emphasis role="bold">[-cell &lt;<replaceable>cell name</replaceable>&gt;]</emphasis></term>
 231       <listitem><para>
 232         This argument indicates that the command runs in the indicated cell. The issuer can abbreviate the
 233         <replaceable>cell name</replaceable> value to the shortest form that distinguishes it from the other cells
 234         listed in the <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> file on the client machine on which the
 235         command is issued. By default, commands are executed in the local cell as defined
 236         </para><itemizedlist>
 237           <listitem><para>First, by the value of the environment variable AFSCELL. (This variable is normally not
 238           defined by default. If you are working in another, nonlocal cell for an extended period of time, you can set
 239           the variable to the name of that cell.)</para></listitem>
 240           <listitem><para>Second, in the <emphasis role="bold">/usr/vice/etc/ThisCell</emphasis> file on the client
 241           machine on which the command is issued.</para></listitem>
 242         </itemizedlist>
 243       </listitem></varlistentry>
 244     </variablelist>
 245     <variablelist>
 246       <varlistentry><term><emphasis role="bold">[-force]</emphasis></term>
 247       <listitem><para>This flag directs the <emphasis role="bold">pts</emphasis> command interpreter to continue
 248       executing the command, if possible, even if it encounters problems during the command's execution.
 249
 250 <indexterm><primary>pts commands</primary><secondary>force flag</secondary></indexterm>
 251  The command interpreter performs as much of the requested operation as possible, rather
 252       than halting if it encounters a problem. The command interpreter reports any errors it encounters during the
 253       command's execution. This flag is especially useful if you provide many instances for an argument; if one of the
 254       instances is invalid, the command reports the error and proceeds with the remaining
 255       arguments.</para></listitem></varlistentry>
 256     </variablelist>
 257     <variablelist>
 258       <varlistentry><term><emphasis role="bold">[-help]
 259 <indexterm><primary>pts commands</primary><secondary>help flag</secondary></indexterm>
 260
 261
 262 <indexterm><primary>pts commands</primary><secondary>getting help</secondary></indexterm>
 263 </emphasis></term>
 264       <listitem><para>This flag has the same function as the <emphasis role="bold">pts help</emphasis> command: it
 265       prints the command's online help message on the screen. Do not provide other options at the same time as this
 266       flag. It overrides them, and the only effect of issuing the command is to display the help
 267       message.</para></listitem></varlistentry>
 268     </variablelist>
 269     </sect2></sect1><sect1 id="HDRWQ89"><title>Getting Help in AFS</title>
 270
 271 <indexterm><primary>help</primary><secondary>online for AFS commands</secondary></indexterm>
 272
 273 <indexterm><primary>online help</primary></indexterm>
 274
 275     <para>AFS online help consists of basic syntax messages. The AFS distribution also includes help in HTML format
 276     which your system administrator can make available to you.</para>
 277     <sect2 id="Header_180"><title>Displaying Command Syntax and Aliases</title>
 278
 279 <indexterm><primary>apropos operation code</primary></indexterm>
 280
 281 <indexterm><primary>help</primary><secondary>operation code in AFS command suites</secondary></indexterm>
 282
 283 <indexterm><primary>help</primary><secondary>examples</secondary></indexterm>
 284
 285     <para>To display a brief description of a command, its syntax statement, and alias if any, use the
 286     <emphasis role="bold">help</emphasis> operation code. For example, to display the online help entry for the
 287     <emphasis role="bold">fs listacl</emphasis> command, enter the following command:</para>
 288 <programlisting>
 289    % <emphasis role="bold">fs help listacl</emphasis>
 290    fs listacl: list access control list
 291    aliases: la
 292    Usage: fs listacl  [-path &lt;dir/file path&gt;+]  [-id] [-if] [-help]
 293 </programlisting>
 294     <para>To display the syntax statement only, use the <emphasis role="bold">-help</emphasis> flag, which is available
 295     on most AFS commands. For example, to display the syntax statement for the <emphasis role="bold">fs
 296     setacl</emphasis> command, enter the following command:</para>
 297 <programlisting>
 298    % <emphasis role="bold">fs setacl -help</emphasis>
 299    Usage: fs setacl -dir &lt;directory&gt;+ -acl &lt;access list entries&gt;+ [-clear] [-negative]
 300    [-id] [-if] [-help]
 301 </programlisting>
 302     </sect2><sect2 id="Header_181"><title>Displaying Operation Code Descriptions</title>
 303     <para>To display a short description of all of a command suite's operation codes, issue the
 304     <emphasis role="bold">help</emphasis> operation code without any other arguments. For example, the
 305     <emphasis role="bold">fs help</emphasis> command displays a short description of every operation code in the
 306     <emphasis role="bold">fs</emphasis> command suite.
 307 <indexterm><primary>keyword for apropos command</primary></indexterm>
 308 </para>
 309     <para>To display a list of the commands in a command suite that concern a certain type of object, provide a
 310     relevant keyword argument to the <emphasis role="bold">apropos</emphasis> operation code. For example, if you want
 311     to set an ACL but cannot remember which <emphasis role="bold">fs</emphasis> command to use, issue the following
 312     command:</para>
 313 <programlisting>
 314    % <emphasis role="bold">fs apropos set</emphasis>
 315    setacl: set access control list
 316    setcachesize: set cache size
 317    setcell: set cell status
 318    setclientaddrs: set client network interface addresses
 319    setquota: set volume quota
 320    setserverprefs: set file server ranks
 321    setvol: set volume status
 322    sysname: get/set sysname (i.e. @sys) value
 323 </programlisting>
 324     <para>The following message indicates that there are no commands whose names or descriptions include the keyword
 325     string you have provided:</para>
 326 <programlisting>
 327    Sorry, no commands found
 328 </programlisting>
 329     <note>
 330         <para>If the keyword you provide has spaces in it, enclose it in double quotes (<emphasis role="bold">"
 331         "</emphasis>).</para>
 332     </note>
 333 </sect2></sect1></appendix>