doc/xml/AdminGuide/auagd023.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <appendix id="HDRCOMMANDS">
   3   <title>Using AFS Commands</title>
   4
   5   <para>This section describes the components of AFS commands and how to make entering commands more efficient by using shortened
   6   forms. It has the following sections: <simplelist>
   7       <member><link linkend="HDRWQ613">AFS Command Syntax</link></member>
   8
   9       <member><link linkend="HDRWQ614">Rules for Entering AFS Commands</link></member>
  10
  11       <member><link linkend="HDRWQ615">Rules for Using Abbreviations and Aliases</link></member>
  12
  13       <member><link linkend="HDRWQ616">Displaying Online Help for AFS Commands</link></member>
  14     </simplelist></para>
  15
  16   <sect1 id="HDRWQ613">
  17     <title>AFS Command Syntax</title>
  18
  19     <para>AFS commands that belong to suites have the following structure:</para>
  20
  21     <programlisting><emphasis role="bold">command_suite operation_code</emphasis><emphasis role="bold">-switch</emphasis> <replaceable>&lt;value&gt;</replaceable>[+]  [<emphasis
  22         role="bold">-flag</emphasis>]
  23 </programlisting>
  24
  25     <sect2 id="Header_691">
  26       <title>Command Names</title>
  27
  28       <para>Together, the <emphasis role="bold">command_suite</emphasis> and <emphasis role="bold">operation_code</emphasis> make up
  29       the <emphasis>command name</emphasis>.</para>
  30
  31       <para>The <emphasis role="bold">command_suite</emphasis> specifies the group of related commands to which the command belongs,
  32       and indicates which command interpreter and server process perform the command. AFS has several command suites, including
  33       <emphasis role="bold">bos</emphasis>, <emphasis role="bold">fs</emphasis>, <emphasis role="bold">kas</emphasis>, <emphasis
  34       role="bold">package</emphasis>, <emphasis role="bold">pts</emphasis>, <emphasis role="bold">scout</emphasis>, <emphasis
  35       role="bold">uss</emphasis> and <emphasis role="bold">vos</emphasis>. Some of these suites have an interactive mode in which
  36       the issuer omits the <emphasis role="bold">command_suite</emphasis> portion of the command name.</para>
  37
  38       <para>The <emphasis role="bold">operation_code</emphasis> tells the command interpreter and server process which action to
  39       perform. Most command suites include several operation codes. The <emphasis>OpenAFS Administration Reference</emphasis>
  40       describes each operation code in detail, and the <emphasis>OpenAFS Administration Guide</emphasis> describes how to use them
  41       in the context of performing administrative tasks.</para>
  42
  43       <para>Several AFS commands do not belong to a suite and so their names do not have a <emphasis
  44       role="bold">command_suite</emphasis> portion. Their structure is otherwise similar to the commands in the suites.</para>
  45     </sect2>
  46
  47     <sect2 id="Header_692">
  48       <title>Options</title>
  49
  50       <para>The term <emphasis>option</emphasis> refers to both arguments and flags, which are described in the following
  51       sections.</para>
  52     </sect2>
  53
  54     <sect2 id="Header_693">
  55       <title>Arguments</title>
  56
  57       <para>One or more arguments can follow the command name. Arguments specify the entities on which to act while performing the
  58       command (for example, which server machine, server process, or file). To minimize the potential for error, provide a command's
  59       arguments in the order prescribed in its syntax definition.</para>
  60
  61       <para>Each argument has two parts, which appear in the indicated order: <itemizedlist>
  62           <listitem>
  63             <para>The <emphasis>switch</emphasis> specifies the argument's type and is preceded by a hyphen ( <emphasis
  64             role="bold">-</emphasis> ). For instance, the switch <emphasis role="bold">-server</emphasis> usually indicates that the
  65             argument names a server machine. Switches can often be omitted, subject to the rules outlined in <link
  66             linkend="HDRNOSWITCH">Conditions for Omitting Switches</link>.</para>
  67           </listitem>
  68
  69           <listitem>
  70             <para>The <emphasis>value</emphasis> names a particular entity of the type specified by the preceding switch. For
  71             example, the proper value for a <emphasis role="bold">-server</emphasis> switch is a server machine name like <emphasis
  72             role="bold">fs3.abc.com</emphasis>. Unlike switches (which have a required form), values vary depending on what the
  73             issuer wants to accomplish. Values appear surrounded by angle brackets (<emphasis role="bold">&lt; &gt;</emphasis>) in
  74             command descriptions and the online help to show that they are user-supplied variable information.</para>
  75           </listitem>
  76         </itemizedlist></para>
  77
  78       <para>Some arguments accept multiple values, as indicated by trailing plus sign ( <emphasis role="bold">+</emphasis> ) in the
  79       command descriptions and online help. How many of a command's arguments take multiple values, and their ordering with respect
  80       to other arguments, determine when it is acceptable to omit switches. See <link linkend="HDRNOSWITCH">Conditions for Omitting
  81       Switches</link>.</para>
  82
  83       <para>Some commands have optional as well as required arguments; the command descriptions and online help show optional
  84       arguments in square brackets ([ ]).</para>
  85     </sect2>
  86
  87     <sect2 id="Header_694">
  88       <title>Flags</title>
  89
  90       <para>Some commands have one or more flags, which specify the manner in which the command interpreter and server process
  91       perform the command, or what kind of output it produces. Flags are preceded by hyphens like switches, but they take no values.
  92       Although the command descriptions and online help generally list a command's flags after its arguments, there is no prescribed
  93       order for flags. They can appear anywhere on the command line following the operation code, except in between the parts of an
  94       argument. Flags are always optional.</para>
  95     </sect2>
  96
  97     <sect2 id="HDRCOMMAND-EX">
  98       <title>An Example Command</title>
  99
 100       <para>The following example illustrates the different parts of a command that belongs to an AFS command suite.</para>
 101
 102       <programlisting>
 103    % <emphasis role="bold">bos getdate -server fs1.abc.com -file ptserver kaserver</emphasis>
 104 </programlisting>
 105
 106       <para>where <itemizedlist>
 107           <listitem>
 108             <para><emphasis role="bold">bos</emphasis> is the command suite. The BOS Server executes most of the commands in this
 109             suite.</para>
 110           </listitem>
 111
 112           <listitem>
 113             <para><emphasis role="bold">getdate</emphasis> is the operation code. It tells the BOS Server on the specified server
 114             machine (in this case <emphasis role="bold">fs1.abc.com</emphasis>) to report the modification dates of binary files in
 115             the local <emphasis role="bold">/usr/afs/bin</emphasis> directory.</para>
 116           </listitem>
 117
 118           <listitem>
 119             <para><emphasis role="bold">-server fs1.abc.com</emphasis> is one argument, with <emphasis
 120             role="bold">-server</emphasis> as the switch and <emphasis role="bold">fs1.abc.com</emphasis> as the value. This
 121             argument specifies the server machine on which BOS Server is to collect and report binary dates.</para>
 122           </listitem>
 123
 124           <listitem>
 125             <para><emphasis role="bold">-file ptserver kaserver</emphasis> is an argument that takes multiple values. The switch is
 126             <emphasis role="bold">-file</emphasis> and the values are <emphasis role="bold">ptserver</emphasis> and <emphasis
 127             role="bold">kaserver</emphasis>. This argument tells the BOS Server to report the modification dates on the files
 128             <emphasis role="bold">/usr/afs/bin/kaserver</emphasis> and <emphasis
 129             role="bold">/usr/afs/bin/ptserver</emphasis>.</para>
 130           </listitem>
 131         </itemizedlist></para>
 132     </sect2>
 133
 134     <sect2 id="HDRWQ614">
 135       <title>Rules for Entering AFS Commands</title>
 136
 137       <para>Enter each AFS command on a single line (press <emphasis role="bold">&lt;Return&gt;</emphasis> only at the end of the
 138       command). Some commands in this document appear broken across multiple lines, but that is for legibility only.</para>
 139
 140       <para>Use a space to separate each element on a command line from its neighbors. Spaces rather than commas also separate
 141       multiple values of an argument.</para>
 142
 143       <para>In many cases, the issuer of a command can reduce the amount of typing necessary by using one or both of the following
 144       methods: <itemizedlist>
 145           <listitem>
 146             <para>Omitting switches</para>
 147           </listitem>
 148
 149           <listitem>
 150             <para>Using accepted abbreviations for operation codes, switches (if they are included at all), and some types of
 151             values</para>
 152           </listitem>
 153         </itemizedlist></para>
 154
 155       <para>The following sections explain the conditions for omitting or shortening parts of the command line. It is always
 156       acceptable to type a command in full, with all of its switches and no abbreviations.</para>
 157
 158       <sect3 id="HDRNOSWITCH">
 159         <title>Conditions for Omitting Switches</title>
 160
 161         <para>It is always acceptable to type the switch part of an argument, but in many cases it is not necessary. Specifically,
 162         switches can be omitted if the following conditions are met. <itemizedlist>
 163             <listitem>
 164               <para>All of the command's required arguments appear in the order prescribed by the syntax statement</para>
 165             </listitem>
 166
 167             <listitem>
 168               <para>No switch is provided for any argument</para>
 169             </listitem>
 170
 171             <listitem>
 172               <para>There is only one value for each argument (but note the important exception discussed in the following
 173               paragraph)</para>
 174             </listitem>
 175           </itemizedlist></para>
 176
 177         <para>Omitting switches is possible only because there is a prescribed order for each command's arguments. When the issuer
 178         does not include switches, the command interpreter relies instead on the order of arguments; it assumes that the first
 179         element after the operation code is the command's first argument, the next element is the command's second argument, and so
 180         on. The important exception is when a command's final required argument accepts multiple values. In this case, the command
 181         interpreter assumes that the issuer has correctly provided one value for each argument up through the final one, so any
 182         additional values at the end belong to the final argument.</para>
 183
 184         <para>The following list describes the rules for omitting switches from the opposite perspective: an argument's switch must
 185         be provided when any of the following conditions apply. <itemizedlist>
 186             <listitem>
 187               <para>The command's arguments do not appear in the prescribed order</para>
 188             </listitem>
 189
 190             <listitem>
 191               <para>An optional argument is omitted but a subsequent optional argument is provided</para>
 192             </listitem>
 193
 194             <listitem>
 195               <para>A switch is provided for a preceding argument</para>
 196             </listitem>
 197
 198             <listitem>
 199               <para>More than one value is supplied for a preceding argument (which must take multiple values, of course); without a
 200               switch on the current argument, the command interpreter assumes that the current argument is another value for the
 201               preceding argument</para>
 202             </listitem>
 203           </itemizedlist></para>
 204       </sect3>
 205
 206       <sect3 id="Header_698">
 207         <title>An Example of Omitting Switches</title>
 208
 209         <para>Consider again the example command from <link linkend="HDRCOMMAND-EX">An Example Command</link>.</para>
 210
 211         <programlisting>
 212    % <emphasis role="bold">bos getdate -server fs1.abc.com -file ptserver kaserver</emphasis>
 213 </programlisting>
 214
 215         <para>This command has two required arguments: the server machine name (identified by the <emphasis
 216         role="bold">-server</emphasis> switch) and binary file name (identified by the <emphasis role="bold">-file</emphasis>
 217         switch). The second argument accepts multiple values. By complying with all three conditions, the issuer can omit the
 218         switches:</para>
 219
 220         <programlisting>
 221    % <emphasis role="bold">bos getdate fs1.abc.com ptserver kaserver</emphasis>
 222 </programlisting>
 223
 224         <para>Because there are no switches, the <emphasis role="bold">bos</emphasis> command interpreter relies on the order of
 225         arguments. It assumes that the first element following the operation code, <emphasis role="bold">fs1.abc.com</emphasis>, is
 226         the server machine name, and that the next argument, <emphasis role="bold">ptserver</emphasis>, is a binary file name. Then,
 227         because the command's second (and last) argument accepts multiple values, the command interpreter correctly interprets
 228         <emphasis role="bold">kaserver</emphasis> as an additional value for it.</para>
 229
 230         <para>On the other hand, the following is not acceptable because it violates the first two conditions in <link
 231         linkend="HDRNOSWITCH">Conditions for Omitting Switches</link>: even though there is only one value per argument, the
 232         arguments do not appear in the prescribed order, and a switch is provided for one argument but not the other.</para>
 233
 234         <programlisting>
 235    % <emphasis role="bold">bos getdate ptserver -server fs1.abc.com</emphasis>
 236 </programlisting>
 237       </sect3>
 238     </sect2>
 239
 240     <sect2 id="HDRWQ615">
 241       <title>Rules for Using Abbreviations and Aliases</title>
 242
 243       <para>This section explains how to abbreviate operation codes, option names, server machine names, partition names, and cell
 244       names. It is not possible to abbreviate other types of values.</para>
 245
 246       <sect3 id="Header_700">
 247         <title>Abbreviating Operation Codes</title>
 248
 249         <para>It is acceptable to abbreviate an operation code to the shortest form that still distinguishes it from the other
 250         operation codes in its suite.</para>
 251
 252         <para>For example, it is acceptable to shorten <emphasis role="bold">bos install</emphasis> to <emphasis role="bold">bos
 253         i</emphasis> because there are no other operation codes in the <emphasis role="bold">bos</emphasis> command suite that begin
 254         with the letter <emphasis role="bold">i</emphasis>. In contrast, there are several <emphasis role="bold">bos</emphasis>
 255         operation codes that start with the letter <emphasis role="bold">s</emphasis>, so the abbreviations must be longer to remain
 256         unambiguous: <simplelist>
 257             <member><emphasis role="bold">bos sa</emphasis> for <emphasis role="bold">bos salvage</emphasis></member>
 258
 259             <member><emphasis role="bold">bos seta</emphasis> for <emphasis role="bold">bos setauth</emphasis></member>
 260
 261             <member><emphasis role="bold">bos setc</emphasis> for <emphasis role="bold">bos setcellname</emphasis></member>
 262
 263             <member><emphasis role="bold">bos setr</emphasis> for <emphasis role="bold">bos setrestart</emphasis></member>
 264
 265             <member><emphasis role="bold">bos sh</emphasis> for <emphasis role="bold">bos shutdown</emphasis></member>
 266
 267             <member><emphasis role="bold">bos start</emphasis> for <emphasis role="bold">bos start</emphasis></member>
 268
 269             <member><emphasis role="bold">bos startu</emphasis> for <emphasis role="bold">bos startup</emphasis></member>
 270
 271             <member><emphasis role="bold">bos stat</emphasis> for <emphasis role="bold">bos status</emphasis></member>
 272
 273             <member><emphasis role="bold">bos sto</emphasis> for <emphasis role="bold">bos stop</emphasis></member>
 274           </simplelist></para>
 275
 276         <para>In addition to abbreviations, some operation codes have an <emphasis>alias</emphasis>, a short form that is not
 277         derived by abbreviating the operation code to its shortest unambiguous form. For example, the alias for the <emphasis
 278         role="bold">fs setacl</emphasis> command is <emphasis role="bold">fs sa</emphasis>, whereas the shortest unambiguous
 279         abbreviation is <emphasis role="bold">fs seta</emphasis>.</para>
 280
 281         <para>There are two usual reasons an operation code has an alias: <itemizedlist>
 282             <listitem>
 283               <para>Because the command is frequently issued, it is convenient to have a form shorter than the one derived by
 284               abbreviating. The <emphasis role="bold">fs setacl</emphasis> command is an example.</para>
 285             </listitem>
 286
 287             <listitem>
 288               <para>Because the command's name has changed, but users of previous versions of AFS know the former name. For example,
 289               <emphasis role="bold">bos listhosts</emphasis> has the alias <emphasis role="bold">bos getcell</emphasis>, its former
 290               name. It is acceptable to abbreviate aliases to their shortest unambiguous form (for example, <emphasis
 291               role="bold">bos getcell</emphasis> to <emphasis role="bold">bos getc</emphasis>).</para>
 292             </listitem>
 293           </itemizedlist></para>
 294
 295         <para>Even if an operation code has an alias, it is still acceptable to use the shortest unambiguous form. Thus, the
 296         <emphasis role="bold">fs setacl</emphasis> command has three acceptable forms: <emphasis role="bold">fs setacl</emphasis>
 297         (the full form), <emphasis role="bold">fs seta</emphasis> (the shortest abbreviation), and <emphasis role="bold">fs
 298         sa</emphasis> (the alias).</para>
 299       </sect3>
 300
 301       <sect3 id="Header_701">
 302         <title>Abbreviating Switches and Flags</title>
 303
 304         <para>It is acceptable to shorten a switch or flag to the shortest form that distinguishes it from the other switches and
 305         flags for its operation code. It is often possible to omit switches entirely, subject to the conditions listed in <link
 306         linkend="HDRNOSWITCH">Conditions for Omitting Switches</link>.</para>
 307       </sect3>
 308
 309       <sect3 id="HDRFMSABBREV">
 310         <title>Abbreviating Server Machine Names</title>
 311
 312         <para>AFS server machines must have fully-qualified Internet-style host names (for example, <emphasis
 313         role="bold">fs1.abc.com</emphasis>), but it is not always necessary to type the full name on the command line. AFS commands
 314         accept unambiguous shortened forms, but depend on the cell's name service (such as the Domain Name Service) or a local host
 315         table to resolve a shortened name to the fully-qualified equivalent when the command is issued.</para>
 316
 317         <para>Most commands also accept the dotted decimal form of the machine's IP address as an identifier.</para>
 318       </sect3>
 319
 320       <sect3 id="HDRPARTABBREV">
 321         <title>Abbreviating Partition Names</title>
 322
 323         <para>Partitions that house AFS volumes must have names of the form <emphasis
 324         role="bold">/vicep</emphasis><replaceable>x</replaceable> or <emphasis
 325         role="bold">/vicep</emphasis><replaceable>xx</replaceable>, where the variable final portion is one or two lowercase
 326         letters. By convention, the first server partition created on a file server machine is called <emphasis
 327         role="bold">/vicepa</emphasis>, the second <emphasis role="bold">/vicepb</emphasis>, and so on. The <emphasis>OpenAFS Quick
 328         Beginnings</emphasis> explains how to configure and name a file server machine's partitions in preparation for storing AFS
 329         volumes on them.</para>
 330
 331         <para>When issuing AFS commands, you can abbreviate a partition name using any of the following forms:</para>
 332
 333         <programlisting>
 334 <emphasis role="bold">/vicepa</emphasis>     =     <emphasis role="bold">vicepa</emphasis>      =      <emphasis role="bold">a</emphasis>      =      <emphasis
 335             role="bold">0</emphasis>
 336 <emphasis role="bold">/vicepb</emphasis>     =     <emphasis role="bold">vicepb</emphasis>      =      <emphasis role="bold">b</emphasis>      =      <emphasis
 337             role="bold">1</emphasis>
 338 </programlisting>
 339
 340         <para>After <emphasis role="bold">/vicepz</emphasis> (for which the index is 25) comes</para>
 341
 342         <programlisting>
 343 <emphasis role="bold">/vicepaa</emphasis>    =     <emphasis role="bold">vicepaa</emphasis>     =      <emphasis role="bold">aa</emphasis>     =      <emphasis
 344             role="bold">26</emphasis>
 345 <emphasis role="bold">/vicepab</emphasis>    =     <emphasis role="bold">vicepab</emphasis>     =      <emphasis role="bold">ab</emphasis>     =      <emphasis
 346             role="bold">27</emphasis>
 347 </programlisting>
 348
 349         <para>and so on through</para>
 350
 351         <programlisting>
 352 <emphasis role="bold">/vicepiv</emphasis>    =     <emphasis role="bold">vicepiv</emphasis>     =      <emphasis role="bold">iv</emphasis>     =      <emphasis
 353             role="bold">255</emphasis>
 354 </programlisting>
 355       </sect3>
 356
 357       <sect3 id="HDRCELLABBREV">
 358         <title>Abbreviating Cell Names</title>
 359
 360         <para>A cell's full name usually matches its Internet domain name (such as <emphasis role="bold">stateu.edu</emphasis> for
 361         the State University or <emphasis role="bold">abc.com</emphasis> for ABC Corporation). Some AFS commands accept unambiguous
 362         shortened forms, usually with respect to the local <emphasis role="bold">/usr/vice/etc/CellServDB file</emphasis> but
 363         sometimes depending on the ability of the local name service to resolve the corresponding domain name.</para>
 364       </sect3>
 365     </sect2>
 366
 367     <sect2 id="HDRWQ616">
 368       <title>Displaying Online Help for AFS Commands</title>
 369
 370       <para>To display online help for AFS commands that belong to suites, use the <emphasis role="bold">help</emphasis> and
 371       <emphasis role="bold">apropos</emphasis> operation codes. A <emphasis role="bold">-help</emphasis> flag is also available on
 372       every almost every AFS command.</para>
 373
 374       <para>The online help entry for a command consists of two or three lines: <itemizedlist>
 375           <listitem>
 376             <para>The first line names the command and briefly describes what it does</para>
 377           </listitem>
 378
 379           <listitem>
 380             <para>If the command has aliases, they appear on the next line</para>
 381           </listitem>
 382
 383           <listitem>
 384             <para>The final line, which begins with the string <computeroutput>Usage:</computeroutput>, lists the command's options
 385             in the prescribed order; online help entries use the same typographical symbols (brackets and so on) as this
 386             documentation.</para>
 387           </listitem>
 388         </itemizedlist></para>
 389
 390       <para>If no operation code is specified, the <emphasis role="bold">help</emphasis> operation code displays the first line
 391       (short description) for every operation code in the suite:</para>
 392
 393       <programlisting>
 394    % <replaceable>command_suite</replaceable> <emphasis role="bold">help</emphasis>
 395 </programlisting>
 396
 397       <para>If the issuer specifies one or more operation codes, the <emphasis role="bold">help</emphasis> operation code displays
 398       each command's complete online entry (short description, alias if any, and syntax):</para>
 399
 400       <programlisting>
 401    % <replaceable>command_suite</replaceable> <emphasis role="bold">help</emphasis> <replaceable>operation_code</replaceable>+
 402 </programlisting>
 403
 404       <para>The <emphasis role="bold">-help</emphasis> flag displays a command's syntax but not the short description or
 405       alias:</para>
 406
 407       <programlisting>
 408    % <replaceable>command_name</replaceable> <emphasis role="bold">-help</emphasis>
 409 </programlisting>
 410
 411       <para>The <emphasis role="bold">apropos</emphasis> operation code displays the short description of any command in a suite
 412       whose operation code or short description includes the specified keyword:</para>
 413
 414       <programlisting>
 415    % <replaceable>command_suite</replaceable> <emphasis role="bold">apropos</emphasis> <replaceable>"&lt;help string&gt;"</replaceable>
 416 </programlisting>
 417
 418       <para>The following example command displays the complete online help entry for the <emphasis role="bold">fs setacl</emphasis>
 419       command:</para>
 420
 421       <programlisting>
 422    % <emphasis role="bold">fs help setacl</emphasis>
 423    fs setacl: set access control list
 424    aliases: sa
 425    Usage: fs setacl -dir &lt;<replaceable>directory</replaceable>&gt;+ -acl &lt;<replaceable>access list entries</replaceable>&gt;+
 426    [-clear] [-negative] [-id] [-if] [-help]
 427 </programlisting>
 428
 429       <para>To see only the syntax statement, use the <emphasis role="bold">-help</emphasis> flag:</para>
 430
 431       <programlisting>
 432    % <emphasis role="bold">fs setacl -help</emphasis>
 433    Usage: fs setacl -dir &lt;<replaceable>directory</replaceable>&gt;+ -acl &lt;<replaceable>access list entries</replaceable>&gt;+
 434    [-clear] [-negative] [-id] [-if] [-help]
 435 </programlisting>
 436
 437       <para>In the following example, a user wants to display the quota for her home volume. She knows that the relevant command
 438       belongs to the <emphasis role="bold">fs</emphasis> suite, but cannot remember the operation code. She uses <emphasis
 439       role="bold">quota</emphasis> as the keyword:</para>
 440
 441       <programlisting>
 442    % <emphasis role="bold">fs apropos quota</emphasis>
 443    listquota: list volume quota
 444    quota: show volume quota usage
 445    setquota: set volume quota
 446 </programlisting>
 447
 448       <para>The following illustrates the error message that results if no command name or short description contains the
 449       keyword:</para>
 450
 451       <programlisting>
 452    % <emphasis role="bold">fs apropos "list quota"</emphasis>
 453    Sorry, no commands found
 454 </programlisting>
 455     </sect2>
 456   </sect1>
 457 </appendix>