doc/xml/UserGuide/auusg010.xml

   1 <?xml version="1.0" encoding="utf-8"?>
   2     <appendix id="HDRWQ80"><title>Using the NFS/AFS Translator</title>
   3     <para>
   4 <indexterm><primary>NFS</primary><secondary>accessing AFS from client</secondary></indexterm>
   5
   6 <indexterm><primary>NFS/AFS Translator</primary></indexterm>
   7
   8 <indexterm><primary>AFS</primary><secondary>accessing from NFS client machine</secondary></indexterm>
   9
  10 <indexterm><primary>access to AFS filespace</primary><secondary>from NFS client machines</secondary></indexterm>
  11  Some
  12     cells use the Network File System (NFS) in addition to AFS. If you work on an NFS client machine, your system
  13     administrator can configure it to access the AFS filespace through a program called the <emphasis>NFS/AFS
  14     Translator</emphasis><superscript>TM</superscript>. If you have an AFS account, you can access AFS as an
  15     authenticated user while working on your NFS client machine. Otherwise, you access AFS as the
  16     <emphasis role="bold">anonymous</emphasis> user.</para>
  17     <note>
  18         <para>Acceptable NFS/AFS Translator performance requires that NFS is functioning correctly.</para>
  19     </note>
  20     <sect1 id="HDRWQ81"><title>Requirements for Using the NFS/AFS Translator</title>
  21     <para>
  22 <indexterm><primary>NFS</primary><secondary>issuing AFS commands on NFS client machine</secondary></indexterm>
  23
  24 <indexterm><primary>commands</primary><secondary>AFS, issuing on NFS client machine</secondary></indexterm>
  25  For you to use the NFS/AFS Translator, your system
  26     administrator must configure the following types of machines as indicated:</para>
  27     <itemizedlist>
  28       <listitem><para>An <emphasis>NFS/AFS translator machine</emphasis> is an AFS client machine that also acts as an
  29       NFS server machine. Its Cache Manager acts as the surrogate Cache Manager for your NFS client machine. Ask your
  30       system administrator which translator machines you can use.</para></listitem>
  31       <listitem><para>Your NFS client machine must have an NFS mount to a translator machine. Most often, your system
  32       administrator mounts the translator machine's <emphasis role="bold">/afs</emphasis> directory and names the mount
  33       <emphasis role="bold">/afs</emphasis> as well. This enables you to access the entire AFS filespace using standard
  34       AFS pathnames. It is also possible to create mounts directly to subdirectories of
  35       <emphasis role="bold">/afs</emphasis>, and to give NFS mounts different names on the NFS client
  36       machine.</para></listitem>
  37     </itemizedlist>
  38     <para>Your access to AFS is much more extensive if you have an AFS user account. If you do not, the AFS servers
  39     recognize you as the <emphasis role="bold">anonymous</emphasis> user and only grant you the access available to
  40     members of the <emphasis role="bold">system:anyuser</emphasis> group.</para>
  41     <para>If your NFS client machine uses an operating system that AFS supports, your system administrator can
  42     configure it to enable you to issue many AFS commands on the machine. Ask him or her about the configuration and
  43     which commands you can issue.</para>
  44     </sect1><sect1 id="Header_160"><title>Accessing AFS via the Translator</title>
  45
  46 <indexterm><primary>authentication</primary><secondary>to AFS on NFS client machines</secondary></indexterm>
  47
  48     <para>If you do not have an AFS account or choose not to access AFS as an authenticated user, then all you do to
  49     access AFS is provide the pathname of the relevant file. Its ACL must grant the necessary permissions to the
  50     <emphasis role="bold">system:anyuser</emphasis> group.</para>
  51     <para>If you have an AFS account and want to access AFS as an authenticated user, the best method depends on
  52     whether your NFS machine is a supported type. If it is, use the instructions in <link linkend="HDRWQ82">To
  53     Authenticate on a Supported Operating System</link>. If it is not a supported type, use the instructions in
  54     <link linkend="HDRWQ83">To Authenticate on an Unsupported Operating System</link>.</para>
  55     <sect2 id="HDRWQ82"><title>To Authenticate on a Supported Operating System</title>
  56     <orderedlist>
  57       <listitem><para>Log into the NFS client machine using your NFS username.</para></listitem>
  58       <listitem><para>
  59         Issue the <emphasis role="bold">klog</emphasis> command. For complete instructions, see
  60         <link linkend="HDRWQ29">To Authenticate with AFS</link>.
  61 <programlisting>
  62    % <emphasis role="bold">klog -setpag</emphasis>
  63 </programlisting>
  64       </para></listitem>
  65     </orderedlist>
  66     </sect2><sect2 id="HDRWQ83"><title>To Authenticate on an Unsupported Operating System</title>
  67     <orderedlist>
  68       <listitem><para>Log onto the NFS client machine using your NFS username.</para></listitem>
  69       <listitem id="LINFS-TELNET"><para>Establish a connection to the NFS/AFS translator machine you are
  70       using (for example, using the <emphasis role="bold">telnet</emphasis> utility) and log onto it using your AFS
  71       username (which is normally the same as your NFS username).</para></listitem>
  72       <listitem><para>
  73         If the NFS/AFS translator machine uses an AFS-modified login utility, then you obtained AFS tokens in Step
  74         <link linkend="LINFS-TELNET">2</link>. To check, issue the <emphasis role="bold">tokens</emphasis> command,
  75         which is described fully in <link linkend="HDRWQ30">To Display Your Tokens</link>.
  76 <programlisting>
  77    % <emphasis role="bold">tokens</emphasis>
  78 </programlisting>
  79         If you do not have tokens, issue the <emphasis role="bold">klog</emphasis> command, which is described fully in
  80         <link linkend="HDRWQ29">To Authenticate with AFS</link>.
  81 <programlisting>
  82    % <emphasis role="bold">klog -setpag</emphasis>
  83 </programlisting>
  84       </para></listitem>
  85       <listitem id="LINFS-KNFS"><para>
  86         Issue the <emphasis role="bold">knfs</emphasis> command to associate your AFS tokens
  87         with your UNIX UID on the NFS client machine where you are working. This enables the Cache Manager on the
  88         translator machine to use the tokens properly when you access AFS from the NFS client machine.
  89         </para><para>If your NFS client machine is a system type for which AFS defines a system name, it can make sense
  90         to add the <emphasis role="bold">-sysname</emphasis> argument. This argument helps the Cache Manager access
  91         binaries specific to your NFS client machine, if your system administrator has used the
  92         <emphasis>@sys</emphasis> variable in pathnames. Ask your system administrator if this argument is useful for
  93         you.
  94 <indexterm><primary>knfs command</primary></indexterm>
  95
  96 <indexterm><primary>commands</primary><secondary>knfs</secondary></indexterm>
  97 </para>
  98 <programlisting>
  99    % <emphasis role="bold">knfs</emphasis> &lt;<replaceable>host name</replaceable>&gt; [&lt;<replaceable>user ID (decimal)</replaceable>&gt;]  \
 100           [<emphasis role="bold">-sysname</emphasis> &lt;<replaceable>host's '@sys' value</replaceable>&gt;]
 101 </programlisting>
 102         <para>where</para>
 103         <variablelist>
 104           <varlistentry><term><emphasis role="bold"><replaceable>host name</replaceable></emphasis></term>
 105           <listitem><para>Specifies the fully-qualified hostname of your NFS client machine (such as
 106           <emphasis role="bold">nfs52.example.com</emphasis>).</para></listitem></varlistentry>
 107           <varlistentry><term><emphasis role="bold"><replaceable>user ID</replaceable></emphasis></term>
 108           <listitem><para>Specifies your UNIX UID or equivalent (not your username) on the NFS client machine. If your
 109           system administrator has followed the conventional practice, then your UNIX and AFS UIDs are the same. If you
 110           do not know your local UID on the NFS machine, ask your system administrator for assistance. Your system
 111           administrator can also explain the issues you need to be aware of if your two UIDs do not match, or if you
 112           omit this argument.</para></listitem></varlistentry>
 113           <varlistentry><term><emphasis role="bold">-sysname</emphasis></term>
 114           <listitem><para>Specifies your NFS client machine's system type name.</para></listitem></varlistentry>
 115         </variablelist>
 116       </listitem>
 117       <listitem id="LINFS-LOGOUT"><para>(<emphasis role="bold">Optional</emphasis>) Log out from the
 118       translator machine, but do not unauthenticate.</para></listitem>
 119       <listitem><para>Work on the NFS client machine, accessing AFS as necessary.</para></listitem>
 120       <listitem><para>
 121         When you are finished accessing AFS, issue the <emphasis role="bold">knfs</emphasis> command on the translator
 122         machine again. Provide the same <replaceable>host name</replaceable> and <replaceable>user ID</replaceable>
 123         arguments as in Step <link linkend="LINFS-KNFS">4</link>, and add the <emphasis role="bold">-unlog</emphasis>
 124         flag to destroy your tokens. If you logged out from the translator machine in Step
 125         <link linkend="LINFS-LOGOUT">5</link>, then you must first reestablish a connection to the translator machine
 126         as in Step <link linkend="LINFS-TELNET">2</link>.
 127 <programlisting>
 128    % <emphasis role="bold">knfs</emphasis> &lt;<replaceable>host name</replaceable>&gt; [&lt;<replaceable>user ID (decimal)</replaceable>&gt;] <emphasis role="bold">-unlog</emphasis>
 129 </programlisting>
 130       </para></listitem>
 131     </orderedlist>
 132     </sect2></sect1><sect1 id="HDRWQ84"><title>Troubleshooting the NFS/AFS Translator</title>
 133     <para>Acceptable performance by the NFS/AFS translator depends for the most part on NFS. Sometimes, problems that
 134     appear to be AFS file server outages, broken connections, or inaccessible files are actually caused by NFS
 135     outages.</para>
 136     <para>This section describes some common problems and their possible causes. If other problems arise, contact your
 137     system administrator, who can ask the AFS Product Support group for assistance if necessary.</para>
 138     <note>
 139         <para>To avoid degrading AFS performance, the Cache Manager on the translator machine does not immediately
 140         send changes made on NFS client machines to the File Server. Instead, it checks every 60 seconds for such
 141         changes and sends them then. It can take longer for changes made on an NFS client machine to be saved than for
 142         changes made on an AFS client machine. The save operation must complete before the changes are visible on NFS
 143         client machines that are using a different translator machine or on AFS client machines.</para>
 144     </note>
 145     <sect2 id="HDRWQ85"><title>Your NFS Client Machine is Frozen</title>
 146     <para>If your system administrator has used the recommended options when creating an NFS mount to an NFS/AFS
 147     translator machine, then the mount is both <emphasis>hard</emphasis> and <emphasis>interruptible</emphasis>:</para>
 148     <itemizedlist>
 149       <listitem><para>A hard mount means that the NFS client retries its requests if it does not receive a response
 150       within the expected time frame. This is useful because requests have to pass through both the NFS and AFS client
 151       software, which can sometimes take longer than the NFS client expects. However, it means that if the NFS/AFS
 152       translator machine actually becomes inaccessible, your NFS client machine can become inoperative
 153       (<emphasis>freeze</emphasis> or <emphasis>hang</emphasis>).</para></listitem>
 154       <listitem><para>If the NFS mount is interruptible, then in the case of an NFS/AFS translator machine outage you
 155       can press &lt;<emphasis role="bold">Ctrl-c</emphasis>&gt; or another interrupt signal to halt the NFS client's
 156       repeated attempts to access AFS. You can then continue to work locally, or can NFS-mount another translator
 157       machine. If the NFS mount is not interruptible, you must actually remove the mount to the inaccessible translator
 158       machine.</para></listitem>
 159     </itemizedlist>
 160     </sect2><sect2 id="Header_165"><title>NFS/AFS Translator Reboots</title>
 161     <para>If you have authenticated to AFS and your translator machine reboots, you must issue the
 162     <emphasis role="bold">klog</emphasis> command (and <emphasis role="bold">knfs</emphasis> command, if appropriate)
 163     to reauthenticate. If you used the <emphasis role="bold">knfs</emphasis> command's
 164     <emphasis role="bold">-sysname</emphasis> argument to define your NFS client machine's system name, use it
 165     again.</para>
 166     </sect2><sect2 id="Header_166"><title>System Error Messages</title>
 167     <para>This section explains possible meanings for NFS error messages you receive while accessing AFS
 168     filespace.</para>
 169     <para><computeroutput>stale NFS client</computeroutput></para>
 170     <para><computeroutput>Getpwd: can't read</computeroutput></para>
 171     <para>Both messages possibly means that your translator machine was rebooted and cannot determine the pathname to
 172     the current working directory. To reestablish the path, change directory and specify the complete pathname starting
 173     with <emphasis role="bold">/afs</emphasis>.</para>
 174     <para><computeroutput>NFS server <replaceable>translator_machine</replaceable> is not responding still
 175     trying</computeroutput>.</para>
 176     <para>The NFS client is not getting a response from the NFS/AFS translator machine. If the NFS mount to the
 177     translator machine is a hard mount, your NFS client continues retrying the request until it gets a response (see
 178     <link linkend="HDRWQ85">Your NFS Client Machine is Frozen</link>). If the NFS mount to the translator machine is a
 179     soft mount, the NFS client stops retrying after a certain number of attempts (three by default).</para>
 180 </sect2></sect1></appendix>