doc/xml/UserGuide/auusg009.xml

   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>
  39         <para><anchor id="LINOSAVE-TOKENS" />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">klog</emphasis> command to authenticate. 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">klog</emphasis>
  55 </programlisting></para>
  56           </listitem>
  57         </itemizedlist>
  58       </listitem>
  59
  60       <listitem>
  61         <para><anchor id="LINOSAVE-FSCHECKS" />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 &amp;</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> &lt;<replaceable>dir/file path</replaceable>&gt;
  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>
  97         <para><anchor id="LINOSAVE-PERMS" />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> &lt;<replaceable>dir/file path</replaceable>&gt;
 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> &lt;<replaceable>directory</replaceable>&gt;<superscript>+</superscript> <emphasis
 132             role="bold">-acl</emphasis> &lt;<replaceable>access list entries</replaceable>&gt;<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">klog</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>
 145         <para><anchor id="LINOSAVE-QUOTA" />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>  &lt;<replaceable>dir/file path</replaceable>&gt;
 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/abc.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>  &lt;<replaceable>dir/file path</replaceable>&gt;
 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> &lt;<replaceable>directory</replaceable>&gt; <emphasis role="bold">-acl &lt;</emphasis><replaceable>your_username</replaceable>&gt; <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/abc.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> &lt;<replaceable>dir/file path</replaceable>&gt;
 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 &lt;<replaceable>dir/file path</replaceable>&gt; 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">klog</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 &amp;</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>