Improve demand-attach fileserver bos documentation
[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 <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>