doc/html/AdminGuide/auagd023.htm

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