doc/html/UserGuide/auusg011.htm

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