Improve demand-attach fileserver bos documentation
[openafs.git] / doc / xml / UserGuide / auusg006.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <chapter id="HDRWQ38">
3   <title>Displaying Information about OpenAFS</title>
4
5   <para>This chapter explains how to display information that can help you use AFS more effectively. It includes the following
6   sections.
7
8   <simplelist>
9     <member><link linkend="HDRWQ39">Displaying Volume Quota</link></member>
10
11     <member><link linkend="HDRWQ40">Locating Files and Directories</link>.</member>
12
13     <member><link linkend="HDRWQ41">Checking the Status of Server Machines</link></member>
14
15     <member><link linkend="HDRWQ42">Determining Access to Foreign Cells</link></member>
16
17     <member><link linkend="HDRWQ43">Displaying Server Preference Ranks</link></member>
18   </simplelist>
19 </para>
20
21   <sect1 id="HDRWQ39">
22     <title>Displaying Volume Quota</title>
23
24     <para>By convention, the files in your home directory are stored together in a single volume. (For information about volumes,
25     see <link linkend="HDRWQ6">Volumes and Mount Points</link>.) To allocate your cell's available disk space as fairly as possible,
26     your system administrators impose a size limit, or <emphasis>quota</emphasis>, on each volume. You cannot store more data in a
27     volume than its quota allows. If a volume is close to its quota, you sometimes cannot save changes you have made to files stored
28     in the volume.</para>
29
30     <para>The amount of space available on the partition that houses the volume also limits how large the volume can grow. If the
31     disk partition is full, you can become unable to save changes to a file even though the volume is not close to its quota.
32     <indexterm><primary>volume quota</primary></indexterm> <indexterm><primary>disk partition</primary><secondary>consequences when full</secondary></indexterm></para>
33
34     <para>Check the quota on your home volume periodically to make sure you have adequate space. Also, if you encounter problems
35     saving a file, check the quota of the volume in which the file is stored. Use the following commands to display volume
36     quota.
37
38     <itemizedlist>
39       <listitem>
40         <para>The <emphasis role="bold">fs quota</emphasis> command lists the percentage of the volume quota used.</para>
41       </listitem>
42
43       <listitem>
44         <para>Both the <emphasis role="bold">fs listquota</emphasis> and <emphasis role="bold">fs examine</emphasis> commands list
45         the volume name, its maximum size (quota), and its current size. They also report the following additional
46         information.
47
48         <itemizedlist>
49           <listitem>
50             <para>The <emphasis role="bold">fs listquota</emphasis> command lists the percentage used of both the volume and the
51             partition.</para>
52           </listitem>
53
54           <listitem>
55             <para>The <emphasis role="bold">fs examine</emphasis> command lists the partition's size, the amount of space currently
56             used, and any messages associated with the volume.</para>
57           </listitem>
58         </itemizedlist>
59 </para>
60       </listitem>
61     </itemizedlist>
62 </para>
63
64     <sect2 id="Header_63">
65       <title>To Display Percentage of Quota Used</title>
66
67       <indexterm><primary>fs commands</primary><secondary>quota</secondary></indexterm>
68
69       <indexterm><primary>volume quota</primary><secondary>displaying percentage used</secondary></indexterm>
70
71       <indexterm><primary>commands</primary><secondary>fs quota</secondary></indexterm>
72
73       <indexterm><primary>displaying</primary><secondary>percentage of volume quota used</secondary></indexterm>
74
75       <para>Issue the <emphasis role="bold">fs quota</emphasis> command to display the percentage of the quota currently used for
76       the volume that contains a specified directory or file.</para>
77
78       <programlisting>
79    % <emphasis role="bold">fs quota</emphasis> [&lt;<replaceable>dir/file path</replaceable>&gt;<superscript>+</superscript>]
80 </programlisting>
81
82       <para>where <replaceable>dir/file path</replaceable> specifies the pathname of a file or directory in each volume for which to
83       display quota information. If you do not provide a pathname, the output reports quota information for the volume that contains
84       the current working directory.</para>
85     </sect2>
86
87     <sect2 id="Header_64">
88       <title>Example: Displaying Percentage of Quota Used</title>
89
90       <para><indexterm><primary>examples</primary><secondary>displaying volume quota percentage used</secondary></indexterm> The following example displays the percentage of quota used for the volumes that contain two user
91       home directories in the ABC Corporation cell.</para>
92
93       <programlisting>
94    % <emphasis role="bold">cd /afs/abc.com/usr</emphasis>
95    % <emphasis role="bold">fs quota terry pat</emphasis>
96    34% of quota used.
97    85% of quota used.
98 </programlisting>
99     </sect2>
100
101     <sect2 id="Header_65">
102       <title>To Display Quota and Other Information about a Volume</title>
103
104       <indexterm><primary>fs commands</primary><secondary>listquota</secondary></indexterm>
105
106       <indexterm><primary>volume quota</primary><secondary>displaying with other information</secondary></indexterm>
107
108       <indexterm><primary>commands</primary><secondary>fs listquota</secondary></indexterm>
109
110       <indexterm><primary>displaying</primary><secondary>volume quota with other information</secondary></indexterm>
111
112       <indexterm><primary>displaying</primary><secondary>disk partition percentage space used</secondary></indexterm>
113
114       <indexterm><primary>disk partition</primary><secondary>displaying percentage of space used</secondary></indexterm>
115
116       <para>Issue the <emphasis role="bold">fs listquota</emphasis> command to display the following information:
117
118       <itemizedlist>
119         <listitem>
120           <para>The name of the volume that houses each specified file or directory</para>
121         </listitem>
122
123         <listitem>
124           <para>The quota, expressed as a number of kilobytes (<computeroutput>1024</computeroutput> indicates one megabyte)</para>
125         </listitem>
126
127         <listitem>
128           <para>The current size of the volume (the number of kilobytes of currently used)</para>
129         </listitem>
130
131         <listitem>
132           <para>The percentage of the quota used</para>
133         </listitem>
134
135         <listitem>
136           <para>The percentage of space used on the disk partition housing the volume</para>
137         </listitem>
138       </itemizedlist>
139 </para>
140
141       <para>The command's syntax is as follows.</para>
142
143       <programlisting>
144    % <emphasis role="bold">fs listquota</emphasis> [&lt;<replaceable>dir/file path</replaceable>&gt;<superscript>+</superscript>]
145 </programlisting>
146
147       <para>where <replaceable>dir/file path</replaceable> specifies the pathname of a file or directory in each volume for which to
148       display quota information. If you do not provide a pathname, the output reports quota information for the volume that contains
149       the current working directory.</para>
150     </sect2>
151
152     <sect2 id="Header_66">
153       <title>Example: Display Quota and Other Information about a Volume</title>
154
155       <indexterm><primary>examples</primary><secondary>displaying volume quota and other information</secondary></indexterm>
156
157       <para>The following example displays quota information about the volume that houses the home directory of user <emphasis
158       role="bold">terry</emphasis>.</para>
159
160       <programlisting>
161    % <emphasis role="bold">fs listquota ~terry</emphasis>
162    Volume Name     Quota    Used    % Used   Partition
163    user.terry      10000    3400       34%         86%
164 </programlisting>
165     </sect2>
166
167     <sect2 id="Header_67">
168       <title>To Display Quota and Other Information about a Volume and Partition</title>
169
170       <indexterm><primary>fs commands</primary><secondary>examine</secondary></indexterm>
171
172       <indexterm><primary>commands</primary><secondary>fs examine</secondary></indexterm>
173
174       <indexterm><primary>volume quota</primary><secondary>displaying with other information</secondary></indexterm>
175
176       <indexterm><primary>displaying</primary><secondary>volume quota with other information</secondary></indexterm>
177
178       <indexterm><primary>displaying</primary><secondary>disk partition space available and total size</secondary></indexterm>
179
180       <indexterm><primary>disk partition</primary><secondary>displaying space available and total size</secondary></indexterm>
181
182       <para>Issue the <emphasis role="bold">fs examine</emphasis> command to display the following information about a volume and
183       the partition it resides on:
184
185       <itemizedlist>
186         <listitem>
187           <para>The volume's ID number (abbreviated in the output as <computeroutput>vid</computeroutput>)</para>
188         </listitem>
189
190         <listitem>
191           <para>The volume name</para>
192         </listitem>
193
194         <listitem>
195           <para>The volume's quota and current size, in kilobytes</para>
196         </listitem>
197
198         <listitem>
199           <para>The number of kilobyte blocks available on the disk partition housing the volume and the total size of that
200           partition</para>
201         </listitem>
202
203         <listitem>
204           <para>An <emphasis>off-line message</emphasis> associated with the volume, if any, as set by a system administrator</para>
205         </listitem>
206       </itemizedlist>
207 </para>
208
209       <para>The command's syntax is as follows.</para>
210
211       <programlisting>
212    % <emphasis role="bold">fs examine</emphasis> [&lt;<replaceable>dir/file path</replaceable>&gt;<superscript>+</superscript>]
213 </programlisting>
214
215       <para>where <replaceable>dir/file path</replaceable> specifies the pathname of a file or directory in each volume for which to
216       display quota information. If you do not provide a pathname, the output reports quota information for the volume that contains
217       the current working directory.</para>
218     </sect2>
219
220     <sect2 id="Header_68">
221       <title>Example: Displaying Quota and Other Information about a Volume and Partition</title>
222
223       <indexterm><primary>examples</primary><secondary>displaying volume information</secondary></indexterm>
224
225       <para>The following example displays quota and other information about the volume that houses the current working
226       directory.</para>
227
228       <programlisting>
229    % <emphasis role="bold">fs examine</emphasis>
230    Volume status for vid = 536871122 named user.terry
231    Current disk quota is 10000
232    Current blocks used are 5745
233    The partition has 1593 blocks available out of 99162
234 </programlisting>
235     </sect2>
236   </sect1>
237
238   <sect1 id="HDRWQ40">
239     <title>Locating Files and Directories</title>
240
241     <indexterm><primary>files</primary><secondary>displaying location</secondary></indexterm>
242
243     <indexterm><primary>directories</primary><secondary>displaying location</secondary></indexterm>
244
245     <para>Normally, you do not need to know which file server machine stores the volume containing a file or directory. Given the
246     pathname to a file, the Cache Manager on your client machine automatically accesses the appropriate server machine.</para>
247
248     <para>If you become unable to access a file, however, it can be useful to know which file server machine houses it. You can then
249     check whether the File Server process or machine is functioning correctly, as described in <link linkend="HDRWQ41">Checking the
250     Status of Server Machines</link>. Or, if your system administrators schedule downtime for a machine, you can learn whether the
251     outage is likely to prevent you from accessing certain files.</para>
252
253     <sect2 id="Header_70">
254       <title>To Display a File or Directory's Location</title>
255
256       <indexterm><primary>fs commands</primary><secondary>whereis</secondary></indexterm>
257
258       <indexterm><primary>commands</primary><secondary>fs whereis</secondary></indexterm>
259
260       <indexterm><primary>displaying</primary><secondary>directory/file location</secondary></indexterm>
261
262       <indexterm><primary>displaying</primary><secondary>file or directory location</secondary></indexterm>
263
264       <para>Issue the <emphasis role="bold">fs whereis</emphasis> command to display the file server machine on which a file or
265       directory is stored.</para>
266
267       <programlisting>
268    % <emphasis role="bold">fs whereis</emphasis> [&lt;<replaceable>dir/file path</replaceable>&gt;<superscript>+</superscript>]
269 </programlisting>
270
271       <para>where <replaceable>dir/file path</replaceable> specifies the pathname of each file or directory for which you want
272       location information. If you do not provide a pathname, the output reports the machine housing the volume that contains the
273       current working directory.</para>
274
275       <para>If the output mentions more than one machine, there is a copy of the volume at each site (the volume is
276       <emphasis>replicated</emphasis>). Your system administrators can choose to replicate volumes that contain information many
277       people need to use, both for load balancing reasons and to make the information available even if there is an outage on one
278       machine that houses the volume.</para>
279     </sect2>
280
281     <sect2 id="Header_71">
282       <title>Example: Displaying Directory Location</title>
283
284       <indexterm><primary>examples</primary><secondary>locating multiple files</secondary></indexterm>
285
286       <para>The following example displays the names of the server machines that house the home volumes for users <emphasis
287       role="bold">terry</emphasis> and <emphasis role="bold">pat</emphasis>.</para>
288
289       <programlisting>
290    % <emphasis role="bold">cd /afs/abc.com/usr</emphasis>
291    % <emphasis role="bold">fs whereis terry pat</emphasis>
292    File /afs/abc.com/usr/terry is on host fs2.abc.com
293    File /afs/abc.com/usr/pat is on host fs3.abc.com
294 </programlisting>
295     </sect2>
296   </sect1>
297
298   <sect1 id="HDRWQ41">
299     <title>Checking the Status of Server Machines</title>
300
301     <indexterm><primary>file server machines</primary><secondary>checking status</secondary></indexterm>
302
303     <indexterm><primary>status of file server machines</primary></indexterm>
304
305     <indexterm><primary>saving files</primary><secondary>on inaccessible file server machines</secondary></indexterm>
306
307     <para>Sometimes one or more server machines in your cell become inaccessible due to hardware problems, software problems, or
308     routine maintenance. During the outage, you cannot access files stored on those machines or save any changes you have made to
309     files that are stored on those machines. (Your Cache Manager possibly has copies of the files stored locally, which you can
310     still work with.)</para>
311
312     <para>To check the status of server machines, use the <emphasis role="bold">fs checkservers</emphasis> command. If a server
313     machine has more than one network interface address (is <emphasis>multihomed</emphasis>), the Cache Manager sends the
314     status-checking message to all of the machine's interfaces. If at least one of the server's interfaces replies, the command's
315     output reports the machine as accessible. If there is no reply from any of the interfaces, the output reports the machine as
316     inaccessible but displays only one of the interfaces (usually the one with the best preference rank; see <link
317     linkend="HDRWQ43">Displaying Server Preference Ranks</link>).</para>
318
319     <para>To check the status of different groups of server machines, combine the <emphasis role="bold">fs checkservers</emphasis>
320     command's options as indicated:
321
322     <itemizedlist>
323       <listitem>
324         <para>To check file server machines in the local cell only, do not include any options</para>
325       </listitem>
326
327       <listitem>
328         <para>To check file server machines in a particular foreign cell only, include the <emphasis role="bold">-cell</emphasis>
329         argument</para>
330       </listitem>
331
332       <listitem>
333         <para>To check every file server machine that your Cache Manager has contacted in any cell, include the <emphasis
334         role="bold">-all</emphasis> flag</para>
335       </listitem>
336     </itemizedlist>
337 </para>
338
339     <para>It can take several minutes for the command shell prompt to return, because the <emphasis role="bold">fs</emphasis>
340     command interpreter waits a timeout period before concluding that an unresponsive machine is really inaccessible. To have the
341     command shell prompt return immediately, add the ampersand (<emphasis role="bold">&amp;</emphasis>), which runs the <emphasis
342     role="bold">fs checkservers</emphasis> command in the background.</para>
343
344     <sect2 id="Header_73">
345       <title>To Check File Server Machine Status</title>
346
347       <indexterm><primary>fs commands</primary><secondary>checkservers</secondary></indexterm>
348
349       <indexterm><primary>commands</primary><secondary>fs checkservers</secondary></indexterm>
350
351       <para>Issue the <emphasis role="bold">fs checkservers</emphasis> command to check the status of file server machines.</para>
352
353       <programlisting>
354    % <emphasis role="bold">fs checkservers</emphasis> [<emphasis role="bold">-cell</emphasis> &lt;<replaceable>cell to check</replaceable>&gt;] [<emphasis
355           role="bold">-all</emphasis>]  [<emphasis role="bold">&amp;</emphasis>]
356 </programlisting>
357
358       <para>where
359
360       <variablelist>
361         <varlistentry>
362           <term><emphasis role="bold">-cell</emphasis></term>
363
364           <listitem>
365             <para>Names each cell for which to check server machine status. Do not combine this argument and the <emphasis
366             role="bold">-all</emphasis> flag.</para>
367           </listitem>
368         </varlistentry>
369
370         <varlistentry>
371           <term><emphasis role="bold">-all</emphasis></term>
372
373           <listitem>
374             <para>Checks the status of all server machines. Do not combine this flag and the <emphasis role="bold">-cell</emphasis>
375             argument.</para>
376           </listitem>
377         </varlistentry>
378       </variablelist>
379 </para>
380
381       <para>The following message indicates that all server machines replied to the Cache Manager's status-checking message:</para>
382
383       <programlisting>
384    All servers are running.
385 </programlisting>
386
387       <para>Otherwise, a message like the following lists the inaccessible machines:</para>
388
389       <programlisting>
390    These servers unavailable due to network or server problems: <replaceable>list of machines</replaceable>.
391 </programlisting>
392     </sect2>
393
394     <sect2 id="Header_74">
395       <title>Example: Checking Server Machine Status</title>
396
397       <indexterm><primary>examples</primary><secondary>checking status of file servers</secondary></indexterm>
398
399       <para>The following example checks the status of every file server machine the Cache Manager has contacted in any cell. Two
400       machines are not responding.</para>
401
402       <programlisting>
403    % <emphasis role="bold">fs checkservers -all &amp;</emphasis>
404    These servers unavailable due to network or server problems:
405       fs1.abc.com server7.stateu.edu.
406 </programlisting>
407     </sect2>
408   </sect1>
409
410   <sect1 id="HDRWQ42">
411     <title>Determining Access to Foreign Cells</title>
412
413     <indexterm><primary>foreign cells</primary><secondary>enabling access</secondary></indexterm>
414
415     <para>The Cache Manager maintains a list of foreign cells that it knows how to reach. A cell must appear in the list for you to
416     access its AFS filespace. (In addition, the ACL on each directory in the pathname to the file must grant you the necessary
417     permissions, and your system administrator must mount the cell in the local AFS filespace--by convention, just under the
418     <emphasis role="bold">/afs</emphasis> directory.)</para>
419
420     <sect2 id="Header_76">
421       <title>To Display Foreign Cells</title>
422
423       <indexterm><primary>commands</primary><secondary>fs listcells</secondary></indexterm>
424
425       <indexterm><primary>fs commands</primary><secondary>listcells</secondary></indexterm>
426
427       <para>Issue the <emphasis role="bold">fs listcells</emphasis> command to display the cells you can access from this client
428       machine. It can take several minutes for the command shell prompt to return. The Cache Manager stores the machines as IP
429       addresses, but has the addresses translated to names before displaying them. To have the command shell prompt return
430       immediately, use the ampersand (<emphasis role="bold">&amp;</emphasis>) to run the <emphasis role="bold">fs
431       listcells</emphasis> command in the background as in the following example.</para>
432
433       <programlisting>
434    % <emphasis role="bold">fs listcells &amp;</emphasis>
435    Cell abc.com  on hosts
436         db1.abc.com
437         db2.abc.com
438         db3.abc.com
439    Cell test.abc.com on hosts
440         test4.abc.com.
441    Cell stateu.edu on hosts
442         sv5.stateu.edu.
443         sv2.stateu.edu.
444         sv11.stateu.edu.
445    Cell def.com on hosts
446         serverA.def.com
447 </programlisting>
448     </sect2>
449   </sect1>
450
451   <sect1 id="HDRWQ43">
452     <title>Displaying Server Preference Ranks</title>
453
454     <indexterm><primary>commands</primary><secondary>fs getserverprefs</secondary></indexterm>
455
456     <indexterm><primary>fs commands</primary><secondary>getserverprefs</secondary></indexterm>
457
458     <indexterm><primary>Cache Manager</primary><secondary>displaying file server preferences</secondary></indexterm>
459
460     <para>The Cache Manager stores a list of preference ranks for file server machines. When it needs to access a file or directory,
461     the Cache Manager compares the ranks of the file server machines that house the relevant volume. It first tries to access the
462     volume on the machine with the best rank. (If a file server machine is multihomed--has more than one network interface--the
463     Cache Manager actually assigns a separate rank to each interface.)</para>
464
465     <para>The Cache Manager assigns a default rank to a file server machine interface by comparing its own IP address to the
466     interface's IP address. It assigns a better rank to interfaces that are on its own subnetwork or network than to interfaces on
467     other networks. Therefore, the ranks bias the Cache Manager to fetch files from file server machines that are close in terms of
468     network distance, which tends to reduce network traffic and help the Cache Manager deliver data to applications more
469     quickly.</para>
470
471     <para>The Cache Manager stores each rank as a pairing of a file server machine interface's IP address and an integer rank from
472     the range <emphasis role="bold">0</emphasis> to <emphasis role="bold">65,534</emphasis>. A lower number is a better rank. To
473     display the server preference ranks on the local client machine, use the <emphasis role="bold">fs getserverprefs</emphasis>
474     command.</para>
475
476     <para>The Cache Manager stores a separate but similar set of ranks for Volume Location (VL) Servers, which tell the Cache
477     Manager the location of volumes that house files and directories. To display those ranks, add the <emphasis
478     role="bold">-vlservers</emphasis> flag to the <emphasis role="bold">fs getserverprefs</emphasis> command.</para>
479
480     <para>If the default ranks do not seem to result in the best performance, your system administrator can change them. Ask your
481     system administrator about the ranks if appropriate.</para>
482
483     <sect2 id="Header_78">
484       <title>To Display Server Preference Ranks</title>
485
486       <para>Issue the <emphasis role="bold">fs getserverprefs</emphasis> command to display the file server machine preference ranks
487       used by the Cache Manager on the local machine. To display VL Server ranks, add the <emphasis
488       role="bold">-vlservers</emphasis> flag. By default, the Cache Manager has the IP address of each interface translated into a
489       hostname before displaying it. To bypass the translation and display IP addresses, include the <emphasis
490       role="bold">-numeric</emphasis> flag. This can significantly speed up the command's output.</para>
491
492       <programlisting>
493    % <emphasis role="bold">fs getserverprefs</emphasis> [<emphasis role="bold">-numeric</emphasis>] [<emphasis role="bold">-vlservers</emphasis>]
494 </programlisting>
495
496       <para>The following example displays the file server machine preference ranks for a client machine in the <emphasis
497       role="bold">abc.com</emphasis> cell. The ranks of the file server machines in that cell are lower than the ranks of the file
498       server machines from the foreign cell, <emphasis role="bold">def.com</emphasis>. Because the <emphasis
499       role="bold">-numeric</emphasis> flag is not used, the output displays hostnames. The appearance of an IP address for two
500       machines indicates that translating them was not possible.</para>
501
502       <programlisting>
503    % <emphasis role="bold">fs getserverprefs</emphasis>
504    fs2.abc.com           20007
505    fs3.abc.com           30002
506    fs1.abc.com           20011
507    fs4.abc.com           30010
508    server1.def.com       40002
509    192.12.105.34         40000
510    server6.def.com       40012
511    192.12.105.37         40005
512 </programlisting>
513     </sect2>
514   </sect1>
515 </chapter>