Commit | Line | Data |
---|---|---|
805e021f CE |
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> |