mirror of
https://git.openafs.org/openafs.git
synced 2025-01-19 07:20:11 +00:00
fc145e7162
This patchset contains updates to the OpenAFS UserGuide that explains how to authentication OpenAFS using kinit/aklog and uses language describing Kerberos outside the context of the kaserver. References to applications such as telnet have been replaced with more modern equivalents such as ssh. Change-Id: Ifae779b04a26beb9be9cf58b450958acdc477c06 Reviewed-on: http://gerrit.openafs.org/1521 Tested-by: Jeffrey Altman <jaltman@openafs.org> Reviewed-by: Jeffrey Altman <jaltman@openafs.org>
326 lines
16 KiB
XML
326 lines
16 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<chapter id="HDRWQ76">
|
|
<title>Troubleshooting</title>
|
|
|
|
<para>This chapter explains how to investigate and solve some problems you can sometimes encounter when working with AFS files. To
|
|
use the instructions, find the heading that describes your problem or matches the error message you received.</para>
|
|
|
|
<sect1 id="HDRWQ77">
|
|
<title>Problem: Cannot Access, Copy, or Save File</title>
|
|
|
|
<para><indexterm>
|
|
<primary>troubleshooting</primary>
|
|
|
|
<secondary>inability to access, copy or save file</secondary>
|
|
</indexterm> <indexterm>
|
|
<primary>files</primary>
|
|
|
|
<secondary>inability to access, copy or save</secondary>
|
|
</indexterm> <indexterm>
|
|
<primary>saving files</primary>
|
|
|
|
<secondary>inability to</secondary>
|
|
</indexterm> <indexterm>
|
|
<primary>copying</primary>
|
|
|
|
<secondary>files, inability to</secondary>
|
|
</indexterm> <indexterm>
|
|
<primary>directories</primary>
|
|
|
|
<secondary>inability to access</secondary>
|
|
</indexterm> <indexterm>
|
|
<primary>access to AFS filespace</primary>
|
|
|
|
<secondary>failures, troubleshooting</secondary>
|
|
</indexterm></para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para><anchor id="LINOSAVE-TOKENS" />Issue the <emphasis role="bold">tokens</emphasis> command to verify that you have valid
|
|
tokens. For complete instructions, see <link linkend="HDRWQ30">To Display Your Tokens</link>. <programlisting>
|
|
% <emphasis role="bold">tokens</emphasis>
|
|
</programlisting></para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>If your tokens are valid, proceed to Step <link linkend="LINOSAVE-FSCHECKS">2</link>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If your do not have tokens for the relevant cell, or they are expired, issue the <emphasis
|
|
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
|
|
Authenticate with AFS</link>. Then try accessing or saving the file again. If you are not successful, proceed to Step
|
|
<link linkend="LINOSAVE-FSCHECKS">2</link>. <programlisting>
|
|
% <emphasis role="bold">aklog</emphasis>
|
|
</programlisting></para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><anchor id="LINOSAVE-FSCHECKS" />Issue the <emphasis role="bold">fs checkservers</emphasis> command to check the
|
|
status of file server machines. For complete instructions, see <link linkend="HDRWQ41">Checking the Status of Server
|
|
Machines</link>. <programlisting>
|
|
% <emphasis role="bold">fs checkservers &</emphasis>
|
|
</programlisting></para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>If the following message appears, proceed to Step <link linkend="LINOSAVE-PERMS">3</link>. <programlisting>
|
|
All servers are running.
|
|
</programlisting></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Output like the following indicates that your Cache Manager cannot reach the indicated file server machines.
|
|
<programlisting>
|
|
These servers unavailable due to network or server problem:
|
|
<replaceable>list of machines</replaceable>.
|
|
</programlisting></para>
|
|
|
|
<para>Issue the <emphasis role="bold">fs whereis</emphasis> command to check if the file you are attempting to access or
|
|
save is stored on one of the inaccessible file server machines. For complete instructions, see <link
|
|
linkend="HDRWQ40">Locating Files and Directories</link>.</para>
|
|
|
|
<programlisting>
|
|
% <emphasis role="bold">fs whereis</emphasis> <<replaceable>dir/file path</replaceable>>
|
|
</programlisting>
|
|
|
|
<para>If your file is stored on an inaccessible machine, then you cannot access the file or save it back to the File
|
|
Server until the machine is again accessible. If your file is on a machine that is not listed as inaccessible, proceed
|
|
to Step <link linkend="LINOSAVE-PERMS">3</link>.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><anchor id="LINOSAVE-PERMS" />Issue the <emphasis role="bold">fs listacl</emphasis> command to verify that you have
|
|
the permissions you need for accessing, copying, or saving the file. For complete instructions, see <link
|
|
linkend="HDRWQ53">To display an ACL</link>. <programlisting>
|
|
% <emphasis role="bold">fs listacl</emphasis> <<replaceable>dir/file path</replaceable>>
|
|
</programlisting></para>
|
|
|
|
<para>You need the indicated permissions:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>To access, copy, or save a file, you must have the <emphasis role="bold">l</emphasis> (<emphasis
|
|
role="bold">lookup</emphasis>) permission on the directory and on all directories above it in the pathname.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>To save changes to an existing file, you must in addition have the <emphasis role="bold">w</emphasis> (<emphasis
|
|
role="bold">write</emphasis>) permission. To create a new file, you must in addition have the <emphasis
|
|
role="bold">i</emphasis> (<emphasis role="bold">insert</emphasis>) and <emphasis role="bold">w</emphasis>
|
|
permissions.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>To copy a file between two directories, you must in addition have the <emphasis role="bold">r</emphasis>
|
|
(<emphasis role="bold">read</emphasis>) permission on the source directory and the <emphasis role="bold">i</emphasis>
|
|
permission on the destination directory.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>If you do not have the necessary permissions but own the directory, you always have the <emphasis
|
|
role="bold">a</emphasis> (<emphasis role="bold">administer</emphasis>) permission even if you do not appear on the ACL.
|
|
Issue the <emphasis role="bold">fs setacl</emphasis> command to grant yourself the necessary permissions. For complete
|
|
instructions, see <link linkend="HDRWQ54">Changing an ACL</link>.</para>
|
|
|
|
<programlisting>
|
|
% <emphasis role="bold">fs setacl -dir</emphasis> <<replaceable>directory</replaceable>><superscript>+</superscript> <emphasis
|
|
role="bold">-acl</emphasis> <<replaceable>access list entries</replaceable>><superscript>+</superscript>
|
|
</programlisting>
|
|
|
|
<para>If you do not have the necessary permissions and do not own the directory, ask the owner or a system administrator to
|
|
grant them to you. If they add you to a group that has the required permissions, you must issue the <emphasis
|
|
role="bold">aklog</emphasis> command to reauthenticate before you can exercise them.</para>
|
|
|
|
<para>If you still cannot access the file even though you have the necessary permissions, contact your system administrator
|
|
for help in investigating further possible causes of your problem. If you still cannot copy or save the file even though you
|
|
have the necessary permissions, proceed to Step <link linkend="LINOSAVE-QUOTA">4</link>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><anchor id="LINOSAVE-QUOTA" />If copying a file, issue the <emphasis role="bold">fs listquota</emphasis> command to
|
|
check whether the volume into which you are copying it, or the partition that houses that volume, is almost full. For
|
|
saving, check the volume and partition that contain the directory into which you are saving the file. For complete
|
|
instructions, see <link linkend="HDRWQ39">Displaying Volume Quota</link>. <programlisting>
|
|
% <emphasis role="bold">fs listquota</emphasis> <<replaceable>dir/file path</replaceable>>
|
|
</programlisting></para>
|
|
|
|
<para>The command produces output as in the following example:</para>
|
|
|
|
<programlisting>
|
|
% <emphasis role="bold">fs listquota /afs/abc.com/usr/terry</emphasis>
|
|
Volume Name Quota Used % Used Partition
|
|
user.terry 10000 3400 34% 86%
|
|
</programlisting>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>If the value in the <computeroutput>Partition</computeroutput> field is not close to 100%, the partition is not
|
|
almost full. Check the value in the <computeroutput>% Used</computeroutput> field. If it is close to 100%, then the
|
|
volume is almost full. If possible, delete files from the volume that are no longer needed, or ask your system
|
|
administrator to increase the volume's quota.</para>
|
|
|
|
<para>If the value in the <computeroutput>% Used</computeroutput> field is not close to 100% (is, say, 90% or less),
|
|
then it is unlikely that you are exceeding the volume's quota, unless the file is very large or the volume's quota is
|
|
small. Contact your system administrator for help in investigating further possible causes of your problem.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If the value in the <computeroutput>Partition</computeroutput> field is very close to 100%, the partition is
|
|
possibly nearly full. However, server machine partitions are usually very large and can still have enough space for an
|
|
average file when nearly full. You can either ask your system administrator about the partition's status, or issue the
|
|
<emphasis role="bold">fs examine</emphasis> command. The final line in its output reports how many kilobyte blocks are
|
|
still available on the partition. For complete instructions, see <link linkend="HDRWQ39">Displaying Volume Quota</link>.
|
|
<programlisting>
|
|
% <emphasis role="bold">fs examine</emphasis> <<replaceable>dir/file path</replaceable>>
|
|
</programlisting></para>
|
|
|
|
<para>If there is enough free space on the partition but you still cannot save the file, ask your system administrator
|
|
for help in investigating further possible causes of your problem.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
</orderedlist>
|
|
</sect1>
|
|
|
|
<sect1 id="HDRWQ78">
|
|
<title>Problem: Accidentally Removed Your Entry from an ACL</title>
|
|
|
|
<para><indexterm>
|
|
<primary>troubleshooting</primary>
|
|
|
|
<secondary>accidental removal from ACL</secondary>
|
|
</indexterm> <indexterm>
|
|
<primary>ACL</primary>
|
|
|
|
<secondary>accidentally removed yourself</secondary>
|
|
</indexterm></para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>If you own the directory from which you have accidentally removed your ACL entry, then you actually still have the
|
|
<emphasis role="bold">a</emphasis> (<emphasis role="bold">administer</emphasis>) permission even if it does not appear on
|
|
the ACL. You normally own your home directory and all of its subdirectories, for instance. Issue the <emphasis
|
|
role="bold">fs setacl</emphasis> command to grant yourself all other permissions. For complete instructions, see <link
|
|
linkend="HDRWQ55">To Add, Remove, or Edit Normal ACL Permissions</link>. <programlisting>
|
|
% <emphasis role="bold">fs setacl -dir</emphasis> <<replaceable>directory</replaceable>> <emphasis role="bold">-acl <</emphasis><replaceable>your_username</replaceable>> <emphasis
|
|
role="bold">all</emphasis>
|
|
</programlisting></para>
|
|
|
|
<para>For <replaceable>directory</replaceable>, provide the complete pathname to the directory (for example, <emphasis
|
|
role="bold">/afs/abc.com/usr/</emphasis><replaceable>your_username</replaceable>). This is necessary because AFS cannot
|
|
interpret pathname abbreviations if you do not have the <emphasis role="bold">l</emphasis> (<emphasis
|
|
role="bold">lookup</emphasis>) permission.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If you do not own the directory, issue the <emphasis role="bold">fs listacl</emphasis> to check if any remaining
|
|
entries grant you the permissions you need (perhaps you belong to one or more groups that appear on the ACL). For complete
|
|
instructions, see <link linkend="HDRWQ53">To display an ACL</link>. <programlisting>
|
|
% <emphasis role="bold">fs listacl</emphasis> <<replaceable>dir/file path</replaceable>>
|
|
</programlisting></para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>The following message displays the directory's ACL. If you need permissions that no entry currently grants you,
|
|
ask the directory's owner or your system administrator for help. <programlisting>
|
|
Access list for <<replaceable>dir/file path</replaceable>> is
|
|
Normal rights
|
|
<replaceable>list of entries</replaceable>
|
|
</programlisting></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If the command returns the following error message instead of an ACL, then you do not have the <emphasis
|
|
role="bold">l</emphasis> permission. <programlisting>
|
|
fs: You don't have the required access rights on '<replaceable>dir/file path</replaceable>'
|
|
</programlisting></para>
|
|
|
|
<para>Ask the directory's owner or your system administrator to grant you the permissions you need. If they add you to a
|
|
group that has the required permissions, you must issue the <emphasis role="bold">aklog</emphasis> command to
|
|
reauthenticate before you can exercise them.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
</orderedlist>
|
|
</sect1>
|
|
|
|
<sect1 id="HDRWQ79">
|
|
<title>Error Message: "afs: Lost contact with fileserver"</title>
|
|
|
|
<indexterm>
|
|
<primary>troubleshooting</primary>
|
|
|
|
<secondary>error messages</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>error messages, troubleshooting</primary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>lost contact with fileserver (error message)</primary>
|
|
</indexterm>
|
|
|
|
<para>Issue the <emphasis role="bold">fs checkservers</emphasis> command to check the status of file server machines. For
|
|
complete instructions, see <link linkend="HDRWQ41">Checking the Status of Server Machines</link>.</para>
|
|
|
|
<programlisting>
|
|
% <emphasis role="bold">fs checkservers &</emphasis>
|
|
</programlisting>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>If the following message appears, ask your system administrator for assistance in diagnosing the cause of the
|
|
<computeroutput>Lost contact</computeroutput> error message. <programlisting>
|
|
All servers are running.
|
|
</programlisting></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Output like the following indicates that your Cache Manager cannot reach the indicated file server machines. You must
|
|
wait until they are again accessible before continuing to work with the files that are stored on them. <programlisting>
|
|
These servers unavailable due to network or server problem:
|
|
<replaceable>list_of_machines</replaceable>.
|
|
</programlisting></para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<indexterm>
|
|
<primary>connection timed out (error message)</primary>
|
|
</indexterm>
|
|
</sect1>
|
|
|
|
<sect1 id="Header_155">
|
|
<title>Error Message: "<replaceable>command</replaceable>: Connection timed out"</title>
|
|
|
|
<para>Issue the <emphasis role="bold">fs checkservers</emphasis> command as described in <link linkend="HDRWQ79">Error Message:
|
|
afs: Lost contact with fileserver</link>. <indexterm>
|
|
<primary>you don't have the required access rights (error message)</primary>
|
|
</indexterm></para>
|
|
</sect1>
|
|
|
|
<sect1 id="Header_156">
|
|
<title>Error Message: "fs: You don't have the required access rights on '<replaceable>file</replaceable>'"</title>
|
|
|
|
<para>You do not have the ACL permissions you need to perform the operation you are attempting. If you own the directory and
|
|
have accidentally removed yourself from the ACL, see <link linkend="HDRWQ78">Problem: Accidentally Removed Your Entry from an
|
|
ACL</link>. Otherwise, ask the directory's owner or your system administrator to grant you the appropriate permissions.
|
|
<indexterm>
|
|
<primary>afs: failed to store file (error message)</primary>
|
|
</indexterm> <indexterm>
|
|
<primary>failed to store file (error message)</primary>
|
|
</indexterm></para>
|
|
</sect1>
|
|
|
|
<sect1 id="Header_157">
|
|
<title>Error Message: "afs: failed to store file"</title>
|
|
|
|
<para>Follow the instructions in <link linkend="HDRWQ77">Problem: Cannot Access, Copy, or Save File</link>.</para>
|
|
</sect1>
|
|
</chapter>
|