Commit | Line | Data |
---|---|---|
805e021f CE |
1 | <?xml version="1.0" encoding="UTF-8"?> |
2 | <chapter id="HDRWQ76"> | |
3 | <title>Troubleshooting</title> | |
4 | ||
5 | <para>This chapter explains how to investigate and solve some problems you can sometimes encounter when working with AFS files. To | |
6 | use the instructions, find the heading that describes your problem or matches the error message you received.</para> | |
7 | ||
8 | <sect1 id="HDRWQ77"> | |
9 | <title>Problem: Cannot Access, Copy, or Save File</title> | |
10 | ||
11 | <para><indexterm> | |
12 | <primary>troubleshooting</primary> | |
13 | ||
14 | <secondary>inability to access, copy or save file</secondary> | |
15 | </indexterm> <indexterm> | |
16 | <primary>files</primary> | |
17 | ||
18 | <secondary>inability to access, copy or save</secondary> | |
19 | </indexterm> <indexterm> | |
20 | <primary>saving files</primary> | |
21 | ||
22 | <secondary>inability to</secondary> | |
23 | </indexterm> <indexterm> | |
24 | <primary>copying</primary> | |
25 | ||
26 | <secondary>files, inability to</secondary> | |
27 | </indexterm> <indexterm> | |
28 | <primary>directories</primary> | |
29 | ||
30 | <secondary>inability to access</secondary> | |
31 | </indexterm> <indexterm> | |
32 | <primary>access to AFS filespace</primary> | |
33 | ||
34 | <secondary>failures, troubleshooting</secondary> | |
35 | </indexterm></para> | |
36 | ||
37 | <orderedlist> | |
38 | <listitem id="LINOSAVE-TOKENS"> | |
39 | <para>Issue the <emphasis role="bold">tokens</emphasis> command to verify that you have valid | |
40 | tokens. For complete instructions, see <link linkend="HDRWQ30">To Display Your Tokens</link>. <programlisting> | |
41 | % <emphasis role="bold">tokens</emphasis> | |
42 | </programlisting></para> | |
43 | ||
44 | <itemizedlist> | |
45 | <listitem> | |
46 | <para>If your tokens are valid, proceed to Step <link linkend="LINOSAVE-FSCHECKS">2</link>.</para> | |
47 | </listitem> | |
48 | ||
49 | <listitem> | |
50 | <para>If your do not have tokens for the relevant cell, or they are expired, issue the <emphasis | |
51 | role="bold">aklog</emphasis> command to authenticate. You may also need to first obtain a kerberos ticket using<emphasis role="bold">kinit</emphasis> since tokens often expire at the same time as TGT's. For complete instructions, see <link linkend="HDRWQ29">To | |
52 | Authenticate with AFS</link>. Then try accessing or saving the file again. If you are not successful, proceed to Step | |
53 | <link linkend="LINOSAVE-FSCHECKS">2</link>. <programlisting> | |
54 | % <emphasis role="bold">aklog</emphasis> | |
55 | </programlisting></para> | |
56 | </listitem> | |
57 | </itemizedlist> | |
58 | </listitem> | |
59 | ||
60 | <listitem id="LINOSAVE-FSCHECKS"> | |
61 | <para>Issue the <emphasis role="bold">fs checkservers</emphasis> command to check the | |
62 | status of file server machines. For complete instructions, see <link linkend="HDRWQ41">Checking the Status of Server | |
63 | Machines</link>. <programlisting> | |
64 | % <emphasis role="bold">fs checkservers &</emphasis> | |
65 | </programlisting></para> | |
66 | ||
67 | <itemizedlist> | |
68 | <listitem> | |
69 | <para>If the following message appears, proceed to Step <link linkend="LINOSAVE-PERMS">3</link>. <programlisting> | |
70 | All servers are running. | |
71 | </programlisting></para> | |
72 | </listitem> | |
73 | ||
74 | <listitem> | |
75 | <para>Output like the following indicates that your Cache Manager cannot reach the indicated file server machines. | |
76 | <programlisting> | |
77 | These servers unavailable due to network or server problem: | |
78 | <replaceable>list of machines</replaceable>. | |
79 | </programlisting></para> | |
80 | ||
81 | <para>Issue the <emphasis role="bold">fs whereis</emphasis> command to check if the file you are attempting to access or | |
82 | save is stored on one of the inaccessible file server machines. For complete instructions, see <link | |
83 | linkend="HDRWQ40">Locating Files and Directories</link>.</para> | |
84 | ||
85 | <programlisting> | |
86 | % <emphasis role="bold">fs whereis</emphasis> <<replaceable>dir/file path</replaceable>> | |
87 | </programlisting> | |
88 | ||
89 | <para>If your file is stored on an inaccessible machine, then you cannot access the file or save it back to the File | |
90 | Server until the machine is again accessible. If your file is on a machine that is not listed as inaccessible, proceed | |
91 | to Step <link linkend="LINOSAVE-PERMS">3</link>.</para> | |
92 | </listitem> | |
93 | </itemizedlist> | |
94 | </listitem> | |
95 | ||
96 | <listitem id="LINOSAVE-PERMS"> | |
97 | <para>Issue the <emphasis role="bold">fs listacl</emphasis> command to verify that you have | |
98 | the permissions you need for accessing, copying, or saving the file. For complete instructions, see <link | |
99 | linkend="HDRWQ53">To display an ACL</link>. <programlisting> | |
100 | % <emphasis role="bold">fs listacl</emphasis> <<replaceable>dir/file path</replaceable>> | |
101 | </programlisting></para> | |
102 | ||
103 | <para>You need the indicated permissions:</para> | |
104 | ||
105 | <itemizedlist> | |
106 | <listitem> | |
107 | <para>To access, copy, or save a file, you must have the <emphasis role="bold">l</emphasis> (<emphasis | |
108 | role="bold">lookup</emphasis>) permission on the directory and on all directories above it in the pathname.</para> | |
109 | </listitem> | |
110 | ||
111 | <listitem> | |
112 | <para>To save changes to an existing file, you must in addition have the <emphasis role="bold">w</emphasis> (<emphasis | |
113 | role="bold">write</emphasis>) permission. To create a new file, you must in addition have the <emphasis | |
114 | role="bold">i</emphasis> (<emphasis role="bold">insert</emphasis>) and <emphasis role="bold">w</emphasis> | |
115 | permissions.</para> | |
116 | </listitem> | |
117 | ||
118 | <listitem> | |
119 | <para>To copy a file between two directories, you must in addition have the <emphasis role="bold">r</emphasis> | |
120 | (<emphasis role="bold">read</emphasis>) permission on the source directory and the <emphasis role="bold">i</emphasis> | |
121 | permission on the destination directory.</para> | |
122 | </listitem> | |
123 | </itemizedlist> | |
124 | ||
125 | <para>If you do not have the necessary permissions but own the directory, you always have the <emphasis | |
126 | role="bold">a</emphasis> (<emphasis role="bold">administer</emphasis>) permission even if you do not appear on the ACL. | |
127 | Issue the <emphasis role="bold">fs setacl</emphasis> command to grant yourself the necessary permissions. For complete | |
128 | instructions, see <link linkend="HDRWQ54">Changing an ACL</link>.</para> | |
129 | ||
130 | <programlisting> | |
131 | % <emphasis role="bold">fs setacl -dir</emphasis> <<replaceable>directory</replaceable>><superscript>+</superscript> <emphasis | |
132 | role="bold">-acl</emphasis> <<replaceable>access list entries</replaceable>><superscript>+</superscript> | |
133 | </programlisting> | |
134 | ||
135 | <para>If you do not have the necessary permissions and do not own the directory, ask the owner or a system administrator to | |
136 | grant them to you. If they add you to a group that has the required permissions, you must issue the <emphasis | |
137 | role="bold">aklog</emphasis> command to reauthenticate before you can exercise them.</para> | |
138 | ||
139 | <para>If you still cannot access the file even though you have the necessary permissions, contact your system administrator | |
140 | for help in investigating further possible causes of your problem. If you still cannot copy or save the file even though you | |
141 | have the necessary permissions, proceed to Step <link linkend="LINOSAVE-QUOTA">4</link>.</para> | |
142 | </listitem> | |
143 | ||
144 | <listitem id="LINOSAVE-QUOTA"> | |
145 | <para>If copying a file, issue the <emphasis role="bold">fs listquota</emphasis> command to | |
146 | check whether the volume into which you are copying it, or the partition that houses that volume, is almost full. For | |
147 | saving, check the volume and partition that contain the directory into which you are saving the file. For complete | |
148 | instructions, see <link linkend="HDRWQ39">Displaying Volume Quota</link>. <programlisting> | |
149 | % <emphasis role="bold">fs listquota</emphasis> <<replaceable>dir/file path</replaceable>> | |
150 | </programlisting></para> | |
151 | ||
152 | <para>The command produces output as in the following example:</para> | |
153 | ||
154 | <programlisting> | |
155 | % <emphasis role="bold">fs listquota /afs/example.com/usr/terry</emphasis> | |
156 | Volume Name Quota Used % Used Partition | |
157 | user.terry 10000 3400 34% 86% | |
158 | </programlisting> | |
159 | ||
160 | <itemizedlist> | |
161 | <listitem> | |
162 | <para>If the value in the <computeroutput>Partition</computeroutput> field is not close to 100%, the partition is not | |
163 | almost full. Check the value in the <computeroutput>% Used</computeroutput> field. If it is close to 100%, then the | |
164 | volume is almost full. If possible, delete files from the volume that are no longer needed, or ask your system | |
165 | administrator to increase the volume's quota.</para> | |
166 | ||
167 | <para>If the value in the <computeroutput>% Used</computeroutput> field is not close to 100% (is, say, 90% or less), | |
168 | then it is unlikely that you are exceeding the volume's quota, unless the file is very large or the volume's quota is | |
169 | small. Contact your system administrator for help in investigating further possible causes of your problem.</para> | |
170 | </listitem> | |
171 | ||
172 | <listitem> | |
173 | <para>If the value in the <computeroutput>Partition</computeroutput> field is very close to 100%, the partition is | |
174 | possibly nearly full. However, server machine partitions are usually very large and can still have enough space for an | |
175 | average file when nearly full. You can either ask your system administrator about the partition's status, or issue the | |
176 | <emphasis role="bold">fs examine</emphasis> command. The final line in its output reports how many kilobyte blocks are | |
177 | still available on the partition. For complete instructions, see <link linkend="HDRWQ39">Displaying Volume Quota</link>. | |
178 | <programlisting> | |
179 | % <emphasis role="bold">fs examine</emphasis> <<replaceable>dir/file path</replaceable>> | |
180 | </programlisting></para> | |
181 | ||
182 | <para>If there is enough free space on the partition but you still cannot save the file, ask your system administrator | |
183 | for help in investigating further possible causes of your problem.</para> | |
184 | </listitem> | |
185 | </itemizedlist> | |
186 | </listitem> | |
187 | </orderedlist> | |
188 | </sect1> | |
189 | ||
190 | <sect1 id="HDRWQ78"> | |
191 | <title>Problem: Accidentally Removed Your Entry from an ACL</title> | |
192 | ||
193 | <para><indexterm> | |
194 | <primary>troubleshooting</primary> | |
195 | ||
196 | <secondary>accidental removal from ACL</secondary> | |
197 | </indexterm> <indexterm> | |
198 | <primary>ACL</primary> | |
199 | ||
200 | <secondary>accidentally removed yourself</secondary> | |
201 | </indexterm></para> | |
202 | ||
203 | <orderedlist> | |
204 | <listitem> | |
205 | <para>If you own the directory from which you have accidentally removed your ACL entry, then you actually still have the | |
206 | <emphasis role="bold">a</emphasis> (<emphasis role="bold">administer</emphasis>) permission even if it does not appear on | |
207 | the ACL. You normally own your home directory and all of its subdirectories, for instance. Issue the <emphasis | |
208 | role="bold">fs setacl</emphasis> command to grant yourself all other permissions. For complete instructions, see <link | |
209 | linkend="HDRWQ55">To Add, Remove, or Edit Normal ACL Permissions</link>. <programlisting> | |
210 | % <emphasis role="bold">fs setacl -dir</emphasis> <<replaceable>directory</replaceable>> <emphasis role="bold">-acl <</emphasis><replaceable>your_username</replaceable>> <emphasis | |
211 | role="bold">all</emphasis> | |
212 | </programlisting></para> | |
213 | ||
214 | <para>For <replaceable>directory</replaceable>, provide the complete pathname to the directory (for example, <emphasis | |
215 | role="bold">/afs/example.com/usr/</emphasis><replaceable>your_username</replaceable>). This is necessary because AFS cannot | |
216 | interpret pathname abbreviations if you do not have the <emphasis role="bold">l</emphasis> (<emphasis | |
217 | role="bold">lookup</emphasis>) permission.</para> | |
218 | </listitem> | |
219 | ||
220 | <listitem> | |
221 | <para>If you do not own the directory, issue the <emphasis role="bold">fs listacl</emphasis> to check if any remaining | |
222 | entries grant you the permissions you need (perhaps you belong to one or more groups that appear on the ACL). For complete | |
223 | instructions, see <link linkend="HDRWQ53">To display an ACL</link>. <programlisting> | |
224 | % <emphasis role="bold">fs listacl</emphasis> <<replaceable>dir/file path</replaceable>> | |
225 | </programlisting></para> | |
226 | ||
227 | <itemizedlist> | |
228 | <listitem> | |
229 | <para>The following message displays the directory's ACL. If you need permissions that no entry currently grants you, | |
230 | ask the directory's owner or your system administrator for help. <programlisting> | |
231 | Access list for <<replaceable>dir/file path</replaceable>> is | |
232 | Normal rights | |
233 | <replaceable>list of entries</replaceable> | |
234 | </programlisting></para> | |
235 | </listitem> | |
236 | ||
237 | <listitem> | |
238 | <para>If the command returns the following error message instead of an ACL, then you do not have the <emphasis | |
239 | role="bold">l</emphasis> permission. <programlisting> | |
240 | fs: You don't have the required access rights on '<replaceable>dir/file path</replaceable>' | |
241 | </programlisting></para> | |
242 | ||
243 | <para>Ask the directory's owner or your system administrator to grant you the permissions you need. If they add you to a | |
244 | group that has the required permissions, you must issue the <emphasis role="bold">aklog</emphasis> command to | |
245 | reauthenticate before you can exercise them.</para> | |
246 | </listitem> | |
247 | </itemizedlist> | |
248 | </listitem> | |
249 | </orderedlist> | |
250 | </sect1> | |
251 | ||
252 | <sect1 id="HDRWQ79"> | |
253 | <title>Error Message: "afs: Lost contact with fileserver"</title> | |
254 | ||
255 | <indexterm> | |
256 | <primary>troubleshooting</primary> | |
257 | ||
258 | <secondary>error messages</secondary> | |
259 | </indexterm> | |
260 | ||
261 | <indexterm> | |
262 | <primary>error messages, troubleshooting</primary> | |
263 | </indexterm> | |
264 | ||
265 | <indexterm> | |
266 | <primary>lost contact with fileserver (error message)</primary> | |
267 | </indexterm> | |
268 | ||
269 | <para>Issue the <emphasis role="bold">fs checkservers</emphasis> command to check the status of file server machines. For | |
270 | complete instructions, see <link linkend="HDRWQ41">Checking the Status of Server Machines</link>.</para> | |
271 | ||
272 | <programlisting> | |
273 | % <emphasis role="bold">fs checkservers &</emphasis> | |
274 | </programlisting> | |
275 | ||
276 | <itemizedlist> | |
277 | <listitem> | |
278 | <para>If the following message appears, ask your system administrator for assistance in diagnosing the cause of the | |
279 | <computeroutput>Lost contact</computeroutput> error message. <programlisting> | |
280 | All servers are running. | |
281 | </programlisting></para> | |
282 | </listitem> | |
283 | ||
284 | <listitem> | |
285 | <para>Output like the following indicates that your Cache Manager cannot reach the indicated file server machines. You must | |
286 | wait until they are again accessible before continuing to work with the files that are stored on them. <programlisting> | |
287 | These servers unavailable due to network or server problem: | |
288 | <replaceable>list_of_machines</replaceable>. | |
289 | </programlisting></para> | |
290 | </listitem> | |
291 | </itemizedlist> | |
292 | ||
293 | <indexterm> | |
294 | <primary>connection timed out (error message)</primary> | |
295 | </indexterm> | |
296 | </sect1> | |
297 | ||
298 | <sect1 id="Header_155"> | |
299 | <title>Error Message: "<replaceable>command</replaceable>: Connection timed out"</title> | |
300 | ||
301 | <para>Issue the <emphasis role="bold">fs checkservers</emphasis> command as described in <link linkend="HDRWQ79">Error Message: | |
302 | afs: Lost contact with fileserver</link>. <indexterm> | |
303 | <primary>you don't have the required access rights (error message)</primary> | |
304 | </indexterm></para> | |
305 | </sect1> | |
306 | ||
307 | <sect1 id="Header_156"> | |
308 | <title>Error Message: "fs: You don't have the required access rights on '<replaceable>file</replaceable>'"</title> | |
309 | ||
310 | <para>You do not have the ACL permissions you need to perform the operation you are attempting. If you own the directory and | |
311 | have accidentally removed yourself from the ACL, see <link linkend="HDRWQ78">Problem: Accidentally Removed Your Entry from an | |
312 | ACL</link>. Otherwise, ask the directory's owner or your system administrator to grant you the appropriate permissions. | |
313 | <indexterm> | |
314 | <primary>afs: failed to store file (error message)</primary> | |
315 | </indexterm> <indexterm> | |
316 | <primary>failed to store file (error message)</primary> | |
317 | </indexterm></para> | |
318 | </sect1> | |
319 | ||
320 | <sect1 id="Header_157"> | |
321 | <title>Error Message: "afs: failed to store file"</title> | |
322 | ||
323 | <para>Follow the instructions in <link linkend="HDRWQ77">Problem: Cannot Access, Copy, or Save File</link>.</para> | |
324 | </sect1> | |
325 | </chapter> |