release-notes-1-4-5-20071025
[openafs.git] / doc / html / UserGuide / auusg006.htm
1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 4//EN">
2 <HTML><HEAD>
3 <TITLE>User Guide</TITLE>
4 <!-- Begin Header Records  ========================================== -->
5 <!-- /tmp/idwt3629/auusg000.scr converted by idb2h R4.2 (359) ID      -->
6 <!-- Workbench Version (AIX) on 2 Oct 2000 at 14:38:44                -->
7 <META HTTP-EQUIV="updated" CONTENT="Mon, 02 Oct 2000 14:38:42">
8 <META HTTP-EQUIV="review" CONTENT="Tue, 02 Oct 2001 14:38:42">
9 <META HTTP-EQUIV="expires" CONTENT="Wed, 02 Oct 2002 14:38:42">
10 </HEAD><BODY>
11 <!-- (C) IBM Corporation 2000. All Rights Reserved    --> 
12 <BODY bgcolor="ffffff"> 
13 <!-- End Header Records  ============================================ -->
14 <A NAME="Top_Of_Page"></A>
15 <H1>User Guide</H1>
16 <HR><P ALIGN="center"> <A HREF="../index.htm"><IMG SRC="../books.gif" BORDER="0" ALT="[Return to Library]"></A> <A HREF="auusg002.htm#ToC"><IMG SRC="../toc.gif" BORDER="0" ALT="[Contents]"></A> <A HREF="auusg005.htm"><IMG SRC="../prev.gif" BORDER="0" ALT="[Previous Topic]"></A> <A HREF="#Bot_Of_Page"><IMG SRC="../bot.gif" BORDER="0" ALT="[Bottom of Topic]"></A> <A HREF="auusg007.htm"><IMG SRC="../next.gif" BORDER="0" ALT="[Next Topic]"></A> <A HREF="auusg013.htm#HDRINDEX"><IMG SRC="../index.gif" BORDER="0" ALT="[Index]"></A> <P> 
17 <HR><H1><A NAME="HDRWQ38" HREF="auusg002.htm#ToC_61">Displaying Information about AFS</A></H1>
18 <P>This chapter explains how to display information that can
19 help you use AFS more effectively. It includes the following
20 sections.
21 <DL>
22 <DD><P><A HREF="#HDRWQ39">Displaying Volume Quota</A>
23 <DD><P><A HREF="#HDRWQ40">Locating Files and Directories</A>.
24 <DD><P><A HREF="#HDRWQ41">Checking the Status of Server Machines</A>
25 <DD><P><A HREF="#HDRWQ42">Determining Access to Foreign Cells</A>
26 <DD><P><A HREF="#HDRWQ43">Displaying Server Preference Ranks</A>
27 </DL>
28 <HR><H2><A NAME="HDRWQ39" HREF="auusg002.htm#ToC_62">Displaying Volume Quota</A></H2>
29 <P>By convention, the files in your home directory are stored
30 together in a single volume. (For information about volumes, see <A HREF="auusg004.htm#HDRWQ6">Volumes and Mount Points</A>.) To allocate your cell's available disk space
31 as fairly as possible, your system administrators impose a size limit, or
32 <I>quota</I>, on each volume. You cannot store more data in a
33 volume than its quota allows. If a volume is close to its quota, you
34 sometimes cannot save changes you have made to files stored in the
35 volume.
36 <P>The amount of space available on the partition that houses the volume also
37 limits how large the volume can grow. If the disk partition is full,
38 you can become unable to save changes to a file even though the volume is not
39 close to its quota.
40 <A NAME="IDX884"></A>
41 <A NAME="IDX885"></A>
42 <P>Check the quota on your home volume periodically to make sure you have
43 adequate space. Also, if you encounter problems saving a file, check
44 the quota of the volume in which the file is stored. Use the following
45 commands to display volume quota.
46 <UL>
47 <P><LI>The <B>fs quota</B> command lists the percentage of the volume quota
48 used.
49 <P><LI>Both the <B>fs listquota</B> and <B>fs examine</B> commands list
50 the volume name, its maximum size (quota), and its current size. They
51 also report the following additional information.
52 <UL>
53 <P><LI>The <B>fs listquota</B> command lists the percentage used of both the
54 volume and the partition.
55 <P><LI>The <B>fs examine</B> command lists the partition's size, the
56 amount of space currently used, and any messages associated with the
57 volume.
58 </UL>
59 </UL>
60 <P><H3><A NAME="Header_63" HREF="auusg002.htm#ToC_63">To Display Percentage of Quota Used</A></H3>
61 <A NAME="IDX886"></A>
62 <A NAME="IDX887"></A>
63 <A NAME="IDX888"></A>
64 <A NAME="IDX889"></A>
65 <P>Issue the <B>fs quota</B> command to display the percentage of the
66 quota currently used for the volume that contains a specified directory or
67 file.
68 <PRE>   % <B>fs quota</B> [&lt;<VAR>dir/file&nbsp;path</VAR>><SUP>+</SUP>]
69 </PRE>
70 <P>where <VAR>dir/file path</VAR> specifies the pathname of a file or directory
71 in each volume for which to display quota information. If you do not
72 provide a pathname, the output reports quota information for the volume that
73 contains the current working directory.
74 <P><H3><A NAME="Header_64" HREF="auusg002.htm#ToC_64">Example: Displaying Percentage of Quota Used</A></H3>
75 <P>
76 <A NAME="IDX890"></A>
77 The following example displays the percentage of quota used for the volumes
78 that contain two user home directories in the ABC Corporation cell. 
79 <PRE>   % <B>cd /afs/abc.com/usr</B>
80    % <B>fs quota terry pat</B>
81    34% of quota used.
82    85% of quota used.
83 </PRE>
84 <P><H3><A NAME="Header_65" HREF="auusg002.htm#ToC_65">To Display Quota and Other Information about a Volume</A></H3>
85 <A NAME="IDX891"></A>
86 <A NAME="IDX892"></A>
87 <A NAME="IDX893"></A>
88 <A NAME="IDX894"></A>
89 <A NAME="IDX895"></A>
90 <A NAME="IDX896"></A>
91 <P>Issue the <B>fs listquota</B> command to display the following
92 information:
93 <UL>
94 <P><LI>The name of the volume that houses each specified file or directory
95 <P><LI>The quota, expressed as a number of kilobytes (<TT>1024</TT> indicates
96 one megabyte)
97 <P><LI>The current size of the volume (the number of kilobytes of currently used)
98 <P><LI>The percentage of the quota used
99 <P><LI>The percentage of space used on the disk partition housing the volume
100 </UL>
101 <P>The command's syntax is as follows.
102 <PRE>   % <B>fs listquota</B> [&lt;<VAR>dir/file&nbsp;path</VAR>><SUP>+</SUP>]
103 </PRE>
104 <P>where <VAR>dir/file path</VAR> specifies the pathname of a file or directory
105 in each volume for which to display quota information. If you do not
106 provide a pathname, the output reports quota information for the volume that
107 contains the current working directory.
108 <P><H3><A NAME="Header_66" HREF="auusg002.htm#ToC_66">Example: Display Quota and Other Information about a Volume</A></H3>
109 <A NAME="IDX897"></A>
110 <P>The following example displays quota information about the volume that
111 houses the home directory of user <B>terry</B>.
112 <PRE>   % <B>fs listquota ~terry</B>
113    Volume Name     Quota    Used    % Used   Partition 
114    user.terry      10000    3400       34%         86% 
115 </PRE>
116 <P><H3><A NAME="Header_67" HREF="auusg002.htm#ToC_67">To Display Quota and Other Information about a Volume and Partition</A></H3>
117 <A NAME="IDX898"></A>
118 <A NAME="IDX899"></A>
119 <A NAME="IDX900"></A>
120 <A NAME="IDX901"></A>
121 <A NAME="IDX902"></A>
122 <A NAME="IDX903"></A>
123 <P>Issue the <B>fs examine</B> command to display the following
124 information about a volume and the partition it resides on:
125 <UL>
126 <P><LI>The volume's ID number (abbreviated in the output as <TT>vid</TT>)
127 <P><LI>The volume name
128 <P><LI>The volume's quota and current size, in kilobytes
129 <P><LI>The number of kilobyte blocks available on the disk partition housing the
130 volume and the total size of that partition
131 <P><LI>An <I>off-line message</I> associated with the volume, if any, as set
132 by a system administrator
133 </UL>
134 <P>The command's syntax is as follows.
135 <PRE>   % <B>fs examine</B> [&lt;<VAR>dir/file&nbsp;path</VAR>><SUP>+</SUP>]
136 </PRE>
137 <P>where <VAR>dir/file path</VAR> specifies the pathname of a file or directory
138 in each volume for which to display quota information. If you do not
139 provide a pathname, the output reports quota information for the volume that
140 contains the current working directory.
141 <P><H3><A NAME="Header_68" HREF="auusg002.htm#ToC_68">Example: Displaying Quota and Other Information about a Volume and Partition</A></H3>
142 <A NAME="IDX904"></A>
143 <P>The following example displays quota and other information about the volume
144 that houses the current working directory.
145 <PRE>   % <B>fs examine</B>
146    Volume status for vid = 536871122 named user.terry
147    Current disk quota is 10000
148    Current blocks used are 5745
149    The partition has 1593 blocks available out of 99162
150 </PRE>
151 <HR><H2><A NAME="HDRWQ40" HREF="auusg002.htm#ToC_69">Locating Files and Directories</A></H2>
152 <A NAME="IDX905"></A>
153 <A NAME="IDX906"></A>
154 <P>Normally, you do not need to know which file server machine stores the
155 volume containing a file or directory. Given the pathname to a file,
156 the Cache Manager on your client machine automatically accesses the
157 appropriate server machine.
158 <P>If you become unable to access a file, however, it can be useful to know
159 which file server machine houses it. You can then check whether the
160 File Server process or machine is functioning correctly, as described in <A HREF="#HDRWQ41">Checking the Status of Server Machines</A>. Or, if your system administrators schedule downtime
161 for a machine, you can learn whether the outage is likely to prevent you from
162 accessing certain files.
163 <P><H3><A NAME="Header_70" HREF="auusg002.htm#ToC_70">To Display a File or Directory's Location</A></H3>
164 <A NAME="IDX907"></A>
165 <A NAME="IDX908"></A>
166 <A NAME="IDX909"></A>
167 <A NAME="IDX910"></A>
168 <P>Issue the <B>fs whereis</B> command to display the file server machine
169 on which a file or directory is stored.
170 <PRE>   % <B>fs whereis</B> [&lt;<VAR>dir/file&nbsp;path</VAR>><SUP>+</SUP>]
171 </PRE>
172 <P>where <VAR>dir/file path</VAR> specifies the pathname of each file or
173 directory for which you want location information. If you do not
174 provide a pathname, the output reports the machine housing the volume that
175 contains the current working directory.
176 <P>If the output mentions more than one machine, there is a copy of the volume
177 at each site (the volume is <I>replicated</I>). Your system
178 administrators can choose to replicate volumes that contain information many
179 people need to use, both for load balancing reasons and to make the
180 information available even if there is an outage on one machine that houses
181 the volume.
182 <P><H3><A NAME="Header_71" HREF="auusg002.htm#ToC_71">Example: Displaying Directory Location</A></H3>
183 <A NAME="IDX911"></A>
184 <P>The following example displays the names of the server machines that house
185 the home volumes for users <B>terry</B> and <B>pat</B>.
186 <PRE>   % <B>cd /afs/abc.com/usr</B>
187    % <B>fs whereis terry pat</B>
188    File /afs/abc.com/usr/terry is on host fs2.abc.com
189    File /afs/abc.com/usr/pat is on host fs3.abc.com
190 </PRE>
191 <HR><H2><A NAME="HDRWQ41" HREF="auusg002.htm#ToC_72">Checking the Status of Server Machines</A></H2>
192 <A NAME="IDX912"></A>
193 <A NAME="IDX913"></A>
194 <A NAME="IDX914"></A>
195 <P>Sometimes one or more server machines in your cell become inaccessible due
196 to hardware problems, software problems, or routine maintenance. During
197 the outage, you cannot access files stored on those machines or save any
198 changes you have made to files that are stored on those machines. (Your
199 Cache Manager possibly has copies of the files stored locally, which you can
200 still work with.)
201 <P>To check the status of server machines, use the <B>fs checkservers</B>
202 command. If a server machine has more than one network interface
203 address (is <I>multihomed</I>), the Cache Manager sends the
204 status-checking message to all of the machine's interfaces. If at
205 least one of the server's interfaces replies, the command's output
206 reports the machine as accessible. If there is no reply from any of the
207 interfaces, the output reports the machine as inaccessible but displays only
208 one of the interfaces (usually the one with the best preference rank; see
209 <A HREF="#HDRWQ43">Displaying Server Preference Ranks</A>).
210 <P>To check the status of different groups of server machines, combine the
211 <B>fs checkservers</B> command's options as indicated:
212 <UL>
213 <P><LI>To check file server machines in the local cell only, do not include any
214 options
215 <P><LI>To check file server machines in a particular foreign cell only, include
216 the <B>-cell</B> argument
217 <P><LI>To check every file server machine that your Cache Manager has contacted
218 in any cell, include the <B>-all</B> flag
219 </UL>
220 <P>It can take several minutes for the command shell prompt to return, because
221 the <B>fs</B> command interpreter waits a timeout period before concluding
222 that an unresponsive machine is really inaccessible. To have the
223 command shell prompt return immediately, add the ampersand (<B>&amp;</B>),
224 which runs the <B>fs checkservers</B> command in the background.
225 <P><H3><A NAME="Header_73" HREF="auusg002.htm#ToC_73">To Check File Server Machine Status</A></H3>
226 <A NAME="IDX915"></A>
227 <A NAME="IDX916"></A>
228 <P>Issue the <B>fs checkservers</B> command to check the status of file
229 server machines.
230 <PRE>   % <B>fs checkservers</B> [<B>-cell</B> &lt;<VAR>cell&nbsp;to&nbsp;check</VAR>>] [<B>-all</B>]  [<B>&amp;</B>]
231 </PRE>
232 <P>where
233 <DL>
234 <P><DT><B>-cell
235 </B><DD>Names each cell for which to check server machine status. Do not
236 combine this argument and the <B>-all</B> flag.
237 <P><DT><B>-all
238 </B><DD>Checks the status of all server machines. Do not combine this flag
239 and the <B>-cell</B> argument.
240 </DL>
241 <P>The following message indicates that all server machines replied to the
242 Cache Manager's status-checking message:
243 <PRE>   All servers are running.
244 </PRE>
245 <P>Otherwise, a message like the following lists the inaccessible
246 machines:
247 <PRE>   These servers unavailable due to network or server problems: <VAR>list&nbsp;of&nbsp;machines</VAR>.
248 </PRE>
249 <P><H3><A NAME="Header_74" HREF="auusg002.htm#ToC_74">Example: Checking Server Machine Status</A></H3>
250 <A NAME="IDX917"></A>
251 <P>The following example checks the status of every file server machine the
252 Cache Manager has contacted in any cell. Two machines are not
253 responding.
254 <PRE>   % <B>fs checkservers -all &amp;</B>
255    These servers unavailable due to network or server problems: 
256       fs1.abc.com server7.stateu.edu.
257 </PRE>
258 <HR><H2><A NAME="HDRWQ42" HREF="auusg002.htm#ToC_75">Determining Access to Foreign Cells</A></H2>
259 <A NAME="IDX918"></A>
260 <P>The Cache Manager maintains a list of foreign cells that it knows how to
261 reach. A cell must appear in the list for you to access its AFS
262 filespace. (In addition, the ACL on each directory in the pathname to
263 the file must grant you the necessary permissions, and your system
264 administrator must mount the cell in the local AFS filespace--by
265 convention, just under the <B>/afs</B> directory.)
266 <P><H3><A NAME="Header_76" HREF="auusg002.htm#ToC_76">To Display Foreign Cells</A></H3>
267 <A NAME="IDX919"></A>
268 <A NAME="IDX920"></A>
269 <P>Issue the <B>fs listcells</B> command to display the cells you can
270 access from this client machine. It can take several minutes for the
271 command shell prompt to return. The Cache Manager stores the machines
272 as IP addresses, but has the addresses translated to names before displaying
273 them. To have the command shell prompt return immediately, use the
274 ampersand (<B>&amp;</B>) to run the <B>fs listcells</B> command in the
275 background as in the following example.
276 <PRE>   % <B>fs listcells &amp;</B>
277    Cell abc.com  on hosts 
278         db1.abc.com
279         db2.abc.com
280         db3.abc.com
281    Cell test.abc.com on hosts 
282         test4.abc.com.
283    Cell stateu.edu on hosts 
284         sv5.stateu.edu.
285         sv2.stateu.edu.
286         sv11.stateu.edu.
287    Cell def.com on hosts 
288         serverA.def.com 
289 </PRE>
290 <HR><H2><A NAME="HDRWQ43" HREF="auusg002.htm#ToC_77">Displaying Server Preference Ranks</A></H2>
291 <A NAME="IDX921"></A>
292 <A NAME="IDX922"></A>
293 <A NAME="IDX923"></A>
294 <P>The Cache Manager stores a list of preference ranks for file server
295 machines. When it needs to access a file or directory, the Cache
296 Manager compares the ranks of the file server machines that house the relevant
297 volume. It first tries to access the volume on the machine with the
298 best rank. (If a file server machine is multihomed--has more than
299 one network interface--the Cache Manager actually assigns a separate rank
300 to each interface.)
301 <P>The Cache Manager assigns a default rank to a file server machine interface
302 by comparing its own IP address to the interface's IP address. It
303 assigns a better rank to interfaces that are on its own subnetwork or network
304 than to interfaces on other networks. Therefore, the ranks bias the
305 Cache Manager to fetch files from file server machines that are close in terms
306 of network distance, which tends to reduce network traffic and help the Cache
307 Manager deliver data to applications more quickly.
308 <P>The Cache Manager stores each rank as a pairing of a file server machine
309 interface's IP address and an integer rank from the range <B>0</B> to
310 <B>65,534</B>. A lower number is a better rank. To display
311 the server preference ranks on the local client machine, use the <B>fs
312 getserverprefs</B> command.
313 <P>The Cache Manager stores a separate but similar set of ranks for Volume
314 Location (VL) Servers, which tell the Cache Manager the location of volumes
315 that house files and directories. To display those ranks, add the
316 <B>-vlservers</B> flag to the <B>fs getserverprefs</B> command.
317 <P>If the default ranks do not seem to result in the best performance, your
318 system administrator can change them. Ask your system administrator
319 about the ranks if appropriate.
320 <P><H3><A NAME="Header_78" HREF="auusg002.htm#ToC_78">To Display Server Preference Ranks</A></H3>
321 <P>Issue the <B>fs getserverprefs</B> command to display the file
322 server machine preference ranks used by the Cache Manager on the local
323 machine. To display VL Server ranks, add the <B>-vlservers</B>
324 flag. By default, the Cache Manager has the IP address of each
325 interface translated into a hostname before displaying it. To bypass
326 the translation and display IP addresses, include the <B>-numeric</B>
327 flag. This can significantly speed up the command's output.
328 <PRE>   % <B>fs getserverprefs</B> [<B>-numeric</B>] [<B>-vlservers</B>]
329 </PRE>
330 <P>The following example displays the file server machine preference ranks for
331 a client machine in the <B>abc.com</B> cell. The ranks of
332 the file server machines in that cell are lower than the ranks of the file
333 server machines from the foreign cell, <B>def.com</B>.
334 Because the <B>-numeric</B> flag is not used, the output displays
335 hostnames. The appearance of an IP address for two machines indicates
336 that translating them was not possible.
337 <PRE>   % <B>fs getserverprefs</B>
338    fs2.abc.com           20007
339    fs3.abc.com           30002
340    fs1.abc.com           20011
341    fs4.abc.com           30010
342    server1.def.com       40002
343    192.12.105.34         40000
344    server6.def.com       40012
345    192.12.105.37         40005
346 </PRE>
347 <HR><P ALIGN="center"> <A HREF="../index.htm"><IMG SRC="../books.gif" BORDER="0" ALT="[Return to Library]"></A> <A HREF="auusg002.htm#ToC"><IMG SRC="../toc.gif" BORDER="0" ALT="[Contents]"></A> <A HREF="auusg005.htm"><IMG SRC="../prev.gif" BORDER="0" ALT="[Previous Topic]"></A> <A HREF="#Top_Of_Page"><IMG SRC="../top.gif" BORDER="0" ALT="[Top of Topic]"></A> <A HREF="auusg007.htm"><IMG SRC="../next.gif" BORDER="0" ALT="[Next Topic]"></A> <A HREF="auusg013.htm#HDRINDEX"><IMG SRC="../index.gif" BORDER="0" ALT="[Index]"></A> <P> 
348 <!-- Begin Footer Records  ========================================== -->
349 <P><HR><B> 
350 <br>&#169; <A HREF="http://www.ibm.com/">IBM Corporation 2000.</A>  All Rights Reserved 
351 </B> 
352 <!-- End Footer Records  ============================================ -->
353 <A NAME="Bot_Of_Page"></A>
354 </BODY></HTML>