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