| 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> <<replaceable>host name</replaceable>> [<<replaceable>user ID (decimal)</replaceable>>] \ |
| 100 | [<emphasis role="bold">-sysname</emphasis> <<replaceable>host's '@sys' value</replaceable>>] |
| 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> <<replaceable>host name</replaceable>> [<<replaceable>user ID (decimal)</replaceable>>] <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 <<emphasis role="bold">Ctrl-c</emphasis>> 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> |