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 Example Corporation cell.</para>
  92
  93       <programlisting>
  94    % <emphasis role="bold">cd /afs/example.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/example.com/usr</emphasis>
 291    % <emphasis role="bold">fs whereis terry pat</emphasis>
 292    File /afs/example.com/usr/terry is on host fs2.example.com
 293    File /afs/example.com/usr/pat is on host fs3.example.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.example.com server7.example.org.
 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 example.com on hosts
 436         db1.example.com
 437         db2.example.com
 438         db3.example.com
 439    Cell test.example.com on hosts
 440         test4.example.com.
 441    Cell example.org on hosts
 442         sv5.example.org.
 443         sv2.example.org.
 444         sv11.example.org.
 445    Cell example.net on hosts
 446         serverA.example.net
 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">example.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">example.net</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.example.com           20007
 505    fs3.example.com           30002
 506    fs1.example.com           20011
 507    fs4.example.com           30010
 508    server1.example.net       40002
 509    192.12.105.34             40000
 510    server6.example.net       40012
 511    192.12.105.37             40005
 512 </programlisting>
 513     </sect2>
 514   </sect1>
 515 </chapter>