Displaying Information about AFS

This chapter explains how to display information that can help you use AFS more effectively. It includes the following sections.

Displaying Volume Quota

Locating Files and Directories.

Checking the Status of Server Machines

Determining Access to Foreign Cells

Displaying Server Preference Ranks

Displaying Volume Quota

By convention, the files in your home directory are stored together in a single volume. (For information about volumes, see Volumes and Mount Points.) To allocate your cell's available disk space as fairly as possible, your system administrators impose a size limit, or quota, on each volume. You cannot store more data in a volume than its quota allows. If a volume is close to its quota, you sometimes cannot save changes you have made to files stored in the volume.

The amount of space available on the partition that houses the volume also limits how large the volume can grow. If the disk partition is full, you can become unable to save changes to a file even though the volume is not close to its quota.

Check the quota on your home volume periodically to make sure you have adequate space. Also, if you encounter problems saving a file, check the quota of the volume in which the file is stored. Use the following commands to display volume quota.

• The fs quota command lists the percentage of the volume quota used.
• Both the fs listquota and fs examine commands list the volume name, its maximum size (quota), and its current size. They also report the following additional information.
  • The fs listquota command lists the percentage used of both the volume and the partition.
  • The fs examine command lists the partition's size, the amount of space currently used, and any messages associated with the volume.

To Display Percentage of Quota Used

Issue the fs quota command to display the percentage of the quota currently used for the volume that contains a specified directory or file.

   % fs quota [<dir/file path>+]

where dir/file path specifies the pathname of a file or directory in each volume for which to display quota information. If you do not provide a pathname, the output reports quota information for the volume that contains the current working directory.

Example: Displaying Percentage of Quota Used

The following example displays the percentage of quota used for the volumes that contain two user home directories in the ABC Corporation cell.

   % cd /afs/abc.com/usr
   % fs quota terry pat
   34% of quota used.
   85% of quota used.

To Display Quota and Other Information about a Volume

Issue the fs listquota command to display the following information:

• The name of the volume that houses each specified file or directory
• The quota, expressed as a number of kilobytes (1024 indicates one megabyte)
• The current size of the volume (the number of kilobytes of currently used)
• The percentage of the quota used
• The percentage of space used on the disk partition housing the volume

The command's syntax is as follows.

   % fs listquota [<dir/file path>+]

where dir/file path specifies the pathname of a file or directory in each volume for which to display quota information. If you do not provide a pathname, the output reports quota information for the volume that contains the current working directory.

Example: Display Quota and Other Information about a Volume

The following example displays quota information about the volume that houses the home directory of user terry.

   % fs listquota ~terry
   Volume Name     Quota    Used    % Used   Partition 
   user.terry      10000    3400       34%         86% 

To Display Quota and Other Information about a Volume and Partition

Issue the fs examine command to display the following information about a volume and the partition it resides on:

• The volume's ID number (abbreviated in the output as vid)
• The volume name
• The volume's quota and current size, in kilobytes
• The number of kilobyte blocks available on the disk partition housing the volume and the total size of that partition
• An off-line message associated with the volume, if any, as set by a system administrator

The command's syntax is as follows.

   % fs examine [<dir/file path>+]

where dir/file path specifies the pathname of a file or directory in each volume for which to display quota information. If you do not provide a pathname, the output reports quota information for the volume that contains the current working directory.

Example: Displaying Quota and Other Information about a Volume and Partition

The following example displays quota and other information about the volume that houses the current working directory.

   % fs examine
   Volume status for vid = 536871122 named user.terry
   Current disk quota is 10000
   Current blocks used are 5745
   The partition has 1593 blocks available out of 99162

Locating Files and Directories

Normally, you do not need to know which file server machine stores the volume containing a file or directory. Given the pathname to a file, the Cache Manager on your client machine automatically accesses the appropriate server machine.

If you become unable to access a file, however, it can be useful to know which file server machine houses it. You can then check whether the File Server process or machine is functioning correctly, as described in Checking the Status of Server Machines. Or, if your system administrators schedule downtime for a machine, you can learn whether the outage is likely to prevent you from accessing certain files.

To Display a File or Directory's Location

Issue the fs whereis command to display the file server machine on which a file or directory is stored.

   % fs whereis [<dir/file path>+]

where dir/file path specifies the pathname of each file or directory for which you want location information. If you do not provide a pathname, the output reports the machine housing the volume that contains the current working directory.

If the output mentions more than one machine, there is a copy of the volume at each site (the volume is replicated). Your system administrators can choose to replicate volumes that contain information many people need to use, both for load balancing reasons and to make the information available even if there is an outage on one machine that houses the volume.

Example: Displaying Directory Location

The following example displays the names of the server machines that house the home volumes for users terry and pat.

   % cd /afs/abc.com/usr
   % fs whereis terry pat
   File /afs/abc.com/usr/terry is on host fs2.abc.com
   File /afs/abc.com/usr/pat is on host fs3.abc.com

Checking the Status of Server Machines

Sometimes one or more server machines in your cell become inaccessible due to hardware problems, software problems, or routine maintenance. During the outage, you cannot access files stored on those machines or save any changes you have made to files that are stored on those machines. (Your Cache Manager possibly has copies of the files stored locally, which you can still work with.)

To check the status of server machines, use the fs checkservers command. If a server machine has more than one network interface address (is multihomed), the Cache Manager sends the status-checking message to all of the machine's interfaces. If at least one of the server's interfaces replies, the command's output reports the machine as accessible. If there is no reply from any of the interfaces, the output reports the machine as inaccessible but displays only one of the interfaces (usually the one with the best preference rank; see Displaying Server Preference Ranks).

To check the status of different groups of server machines, combine the fs checkservers command's options as indicated:

• To check file server machines in the local cell only, do not include any options
• To check file server machines in a particular foreign cell only, include the -cell argument
• To check every file server machine that your Cache Manager has contacted in any cell, include the -all flag

It can take several minutes for the command shell prompt to return, because the fs command interpreter waits a timeout period before concluding that an unresponsive machine is really inaccessible. To have the command shell prompt return immediately, add the ampersand (&), which runs the fs checkservers command in the background.

To Check File Server Machine Status

Issue the fs checkservers command to check the status of file server machines.

   % fs checkservers [-cell <cell to check>] [-all]  [&]

where

-cell

Names each cell for which to check server machine status. Do not combine this argument and the -all flag.

-all

Checks the status of all server machines. Do not combine this flag and the -cell argument.

The following message indicates that all server machines replied to the Cache Manager's status-checking message:

   All servers are running.

Otherwise, a message like the following lists the inaccessible machines:

   These servers unavailable due to network or server problems: list of machines.

Example: Checking Server Machine Status

The following example checks the status of every file server machine the Cache Manager has contacted in any cell. Two machines are not responding.

   % fs checkservers -all &
   These servers unavailable due to network or server problems: 
      fs1.abc.com server7.stateu.edu.

Determining Access to Foreign Cells

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 access its AFS filespace. (In addition, the ACL on each directory in the pathname to the file must grant you the necessary permissions, and your system administrator must mount the cell in the local AFS filespace--by convention, just under the /afs directory.)

To Display Foreign Cells

Issue the fs listcells command to display the cells you can access from this client machine. It can take several minutes for the command shell prompt to return. The Cache Manager stores the machines as IP addresses, but has the addresses translated to names before displaying them. To have the command shell prompt return immediately, use the ampersand (&) to run the fs listcells command in the background as in the following example.

   % fs listcells &
   Cell abc.com  on hosts 
        db1.abc.com
        db2.abc.com
        db3.abc.com
   Cell test.abc.com on hosts 
        test4.abc.com.
   Cell stateu.edu on hosts 
        sv5.stateu.edu.
        sv2.stateu.edu.
        sv11.stateu.edu.
   Cell def.com on hosts 
        serverA.def.com 

Displaying Server Preference Ranks

The Cache Manager stores a list of preference ranks for file server machines. When it needs to access a file or directory, the Cache Manager compares the ranks of the file server machines that house the relevant volume. It first tries to access the volume on the machine with the best rank. (If a file server machine is multihomed--has more than one network interface--the Cache Manager actually assigns a separate rank to each interface.)

The Cache Manager assigns a default rank to a file server machine interface by comparing its own IP address to the interface's IP address. It assigns a better rank to interfaces that are on its own subnetwork or network than to interfaces on other networks. Therefore, the ranks bias the Cache Manager to fetch files from file server machines that are close in terms of network distance, which tends to reduce network traffic and help the Cache Manager deliver data to applications more quickly.

The Cache Manager stores each rank as a pairing of a file server machine interface's IP address and an integer rank from the range 0 to 65,534. A lower number is a better rank. To display the server preference ranks on the local client machine, use the fs getserverprefs command.

The Cache Manager stores a separate but similar set of ranks for Volume Location (VL) Servers, which tell the Cache Manager the location of volumes that house files and directories. To display those ranks, add the -vlservers flag to the fs getserverprefs command.

If the default ranks do not seem to result in the best performance, your system administrator can change them. Ask your system administrator about the ranks if appropriate.

To Display Server Preference Ranks

Issue the fs getserverprefs command to display the file server machine preference ranks used by the Cache Manager on the local machine. To display VL Server ranks, add the -vlservers flag. By default, the Cache Manager has the IP address of each interface translated into a hostname before displaying it. To bypass the translation and display IP addresses, include the -numeric flag. This can significantly speed up the command's output.

   % fs getserverprefs [-numeric] [-vlservers]

The following example displays the file server machine preference ranks for a client machine in the abc.com cell. The ranks of the file server machines in that cell are lower than the ranks of the file server machines from the foreign cell, def.com. Because the -numeric flag is not used, the output displays hostnames. The appearance of an IP address for two machines indicates that translating them was not possible.

   % fs getserverprefs
   fs2.abc.com           20007
   fs3.abc.com           30002
   fs1.abc.com           20011
   fs4.abc.com           30010
   server1.def.com       40002
   192.12.105.34         40000
   server6.def.com       40012
   192.12.105.37         40005