Commit | Line | Data |
---|---|---|
805e021f CE |
1 | <?xml version="1.0" encoding="UTF-8"?> |
2 | <appendix id="HDRWQ595"> | |
3 | <title>Managing the NFS/AFS Translator</title> | |
4 | ||
5 | <para> | |
6 | <indexterm> | |
7 | <primary>NFS/AFS Translator</primary> | |
8 | </indexterm> | |
9 | ||
10 | <indexterm> | |
11 | <primary>translator</primary> | |
12 | ||
13 | <secondary>NFS/AFS</secondary> | |
14 | </indexterm> | |
15 | ||
16 | The NFS(R)/AFS(R) Translator enables users working on NFS client machines to access, create and remove files stored in AFS. | |
17 | This chapter assumes familiarity with both NFS and AFS.</para> | |
18 | ||
19 | <sect1 id="HDRWQ596"> | |
20 | <title>Summary of Instructions</title> | |
21 | ||
22 | <para>This chapter explains how to perform the following tasks by using the indicated commands:</para> | |
23 | ||
24 | <informaltable frame="none"> | |
25 | <tgroup cols="2"> | |
26 | <colspec colwidth="70*" /> | |
27 | ||
28 | <colspec colwidth="30*" /> | |
29 | ||
30 | <tbody> | |
31 | <row> | |
32 | <entry>Mount directory on translator machine</entry> | |
33 | ||
34 | <entry><emphasis role="bold">mount</emphasis></entry> | |
35 | </row> | |
36 | ||
37 | <row> | |
38 | <entry>Examine value of <emphasis role="bold">@sys</emphasis> variable</entry> | |
39 | ||
40 | <entry><emphasis role="bold">fs sysname</emphasis></entry> | |
41 | </row> | |
42 | ||
43 | <row> | |
44 | <entry>Enable/disable reexport of AFS, set other parameters</entry> | |
45 | ||
46 | <entry><emphasis role="bold">fs exportafs</emphasis></entry> | |
47 | </row> | |
48 | ||
49 | <row> | |
50 | <entry>Assign AFS tokens to user on NFS client machine</entry> | |
51 | ||
52 | <entry><emphasis role="bold">knfs</emphasis></entry> | |
53 | </row> | |
54 | </tbody> | |
55 | </tgroup> | |
56 | </informaltable> | |
57 | </sect1> | |
58 | ||
59 | <sect1 id="HDRWQ598"> | |
60 | <title>Overview</title> | |
61 | ||
62 | <para>The NFS/AFS Translator enables users on NFS client machines to access the AFS filespace as if they are working on an AFS | |
63 | client machine, which facilitates collaboration with other AFS users.</para> | |
64 | ||
65 | <para>An <emphasis>NFS/AFS translator machine</emphasis> (or simply <emphasis>ltranslator machine</emphasis>) is a machine | |
66 | configured as both an AFS client and an NFS server: <itemizedlist> | |
67 | <listitem> | |
68 | <para>Its AFS client functionality enables it to access the AFS filespace. The Cache Manager requests and caches files | |
69 | from AFS file server machines, and can even maintain tokens for NFS users, if you have made the configuration changes that | |
70 | enable NFS users to authenticate with AFS.</para> | |
71 | </listitem> | |
72 | ||
73 | <listitem> | |
74 | <para>Its NFS server functionality makes it possible for the translator machine to export the AFS filespace to NFS client | |
75 | machines. When a user on an NFS client machine mounts the translator machine's <emphasis role="bold">/afs</emphasis> | |
76 | directory (or one of its subdirectories, if that feature is enabled), access to AFS is immediate and transparent. The NFS | |
77 | client machine does not need to run any AFS software.</para> | |
78 | </listitem> | |
79 | </itemizedlist></para> | |
80 | ||
81 | <sect2 id="HDRWQ599"> | |
82 | <title>Enabling Unauthenticated or Authenticated AFS Access</title> | |
83 | ||
84 | <para>By configuring the translation environment appropriately, you can provide either unauthenticated or authenticated access | |
85 | to AFS from NFS client machines. The sections of this chapter on configuring translator machines, NFS client machines, and AFS | |
86 | user accounts explain how to configure the translation environment appropriately. <itemizedlist> | |
87 | <listitem> | |
88 | <para>If you configure the environment for unauthenticated access, the AFS File Server considers the NFS users to be the | |
89 | user <emphasis role="bold">anonymous</emphasis>. They can access only those AFS files and directories for which the | |
90 | access control list (ACL) extends the required permissions to the <emphasis role="bold">system:anyuser</emphasis> group. | |
91 | They can issue only those AFS commands that do not require privilege, and then only if their NFS client machine is a | |
92 | system type for which AFS binaries are available and accessible by the <emphasis role="bold">system:anyuser</emphasis> | |
93 | group. Such users presumably do not have AFS accounts.</para> | |
94 | </listitem> | |
95 | ||
96 | <listitem> | |
97 | <para>If you configure the environment for authenticated access, you must create entries in the AFS Authentication and | |
98 | Protection Databases for the NFS users. The authentication procedure they use depends on whether the NFS client machine | |
99 | is a supported system type (one for which AFS binaries are available): <itemizedlist> | |
100 | <listitem> | |
101 | <para>If AFS binaries are available for the NFS client machine, NFS users can issue the <emphasis | |
102 | role="bold">klog</emphasis> command on the NFS client machine. They can access the filespace and issue AFS | |
103 | commands to the same extent as authenticated users working on AFS client machines.</para> | |
104 | </listitem> | |
105 | ||
106 | <listitem> | |
107 | <para>If AFS binaries are not available for the NFS client machine, NFS users must establish a connection with the | |
108 | translator machine (using the <emphasis role="bold">telnet</emphasis> utility, for example) and then issue the | |
109 | <emphasis role="bold">klog</emphasis> and <emphasis role="bold">knfs</emphasis> commands on the translator machine | |
110 | to make its Cache Manager use the tokens correctly while users work on the NFS client. They can access the AFS | |
111 | filespace as authenticated users, but cannot issue AFS commands. For instructions, see <link | |
112 | linkend="HDRWQ612">Authenticating on Unsupported NFS Client Machines</link>.</para> | |
113 | </listitem> | |
114 | </itemizedlist></para> | |
115 | </listitem> | |
116 | </itemizedlist></para> | |
117 | </sect2> | |
118 | ||
119 | <sect2 id="HDRWQ600"> | |
120 | <title>Setting the AFSSERVER and AFSCONF Environment Variables</title> | |
121 | ||
122 | <para>If you wish to enable your NFS users to issue AFS commands, you must define the AFSSERVER and AFSCONF environment | |
123 | variables in their command shell. This section explains the variables' function and outlines the various methods for setting | |
124 | them.</para> | |
125 | ||
126 | <para>Issuing AFS commands also requires that the NFS client machine is a supported system type (one for which AFS binaries | |
127 | are available and accessible). Users working on NFS client machines of unsupported system types can access AFS as | |
128 | authenticated users, but they cannot issue AFS commands. It is not necessary to define the AFSSERVER and AFSCONF variables for | |
129 | such users. For instructions on using the <emphasis role="bold">knfs</emphasis> command to obtain authenticated access on | |
130 | unsupported system types, see <link linkend="HDRWQ612">Authenticating on Unsupported NFS Client Machines</link>. <indexterm> | |
131 | <primary>AFSSERVER environment variable (NFS/AFS Translator)</primary> | |
132 | </indexterm></para> | |
133 | ||
134 | <sect3 id="HDRWQ601"> | |
135 | <title>The AFSSERVER Variable</title> | |
136 | ||
137 | <para>The AFSSERVER variable designates the AFS client machine that performs two functions for NFS clients: <itemizedlist> | |
138 | <listitem> | |
139 | <para>It acts as the NFS client's <emphasis>remote executor</emphasis> by executing AFS-specific system calls on its | |
140 | behalf, such as those invoked by the <emphasis role="bold">klog</emphasis> and <emphasis role="bold">tokens</emphasis> | |
141 | commands and by many commands in the AFS suites.</para> | |
142 | </listitem> | |
143 | ||
144 | <listitem> | |
145 | <para>Its stores the tokens that NFS users obtain when they authenticate with AFS. This implies that the remote | |
146 | executor machine and the translator machine must be the same if the user needs authenticated access to AFS.</para> | |
147 | </listitem> | |
148 | </itemizedlist></para> | |
149 | ||
150 | <para>The choice of remote executor most directly affects commands that display or change Cache Manager configuration, such | |
151 | as the <emphasis role="bold">fs getcacheparms</emphasis>, <emphasis role="bold">fs getcellstatus</emphasis>, and <emphasis | |
152 | role="bold">fs setcell</emphasis> commands. When issued on an NFS client, these commands affect the Cache Manager on the | |
153 | designated remote executor machine. (Note, however, that several such commands require the issuer to be logged into the | |
154 | remote executor's local file system as the local superuser <emphasis role="bold">root</emphasis>. The ability of NFS client | |
155 | users to log in as <emphasis role="bold">root</emphasis> is controlled by NFS, not by the NFS/AFS Translator, so setting the | |
156 | remote executor properly does not necessarily enable users on the NFS client to issue such commands.)</para> | |
157 | ||
158 | <para>The choice of remote executor is also relevant for AFS commands that do not concern Cache Manager configuration but | |
159 | rather have the same result on every machine, such as the <emphasis role="bold">fs</emphasis> commands that display or set | |
160 | ACLs and volume quota. These commands take an AFS path as one of their arguments. If the Cache Manager on the remote | |
161 | executor machine mounts the AFS filespace at the <emphasis role="bold">/afs</emphasis> directory, as is conventional for AFS | |
162 | clients, then the pathname specified on the NFS client must begin with the string <emphasis role="bold">/afs</emphasis> for | |
163 | the Cache Manager to understand it. This implies that the remote executor must be the NFS client's primary translator | |
164 | machine (the one whose <emphasis role="bold">/afs</emphasis> directory is mounted at <emphasis role="bold">/afs</emphasis> | |
165 | on the NFS client). <indexterm> | |
166 | <primary>NFS/AFS Translator</primary> | |
167 | ||
168 | <secondary>AFSCONF environment variable</secondary> | |
169 | </indexterm> <indexterm> | |
170 | <primary>AFSCONF environment variable (NFS/AFS Translator)</primary> | |
171 | </indexterm></para> | |
172 | </sect3> | |
173 | ||
174 | <sect3 id="Header_672"> | |
175 | <title>The AFSCONF Variable</title> | |
176 | ||
177 | <para>The AFSCONF environment variable names the directory that houses the <emphasis role="bold">ThisCell</emphasis> and | |
178 | <emphasis role="bold">CellServDB</emphasis> files to use when running AFS commands issued on the NFS client machine. As on | |
179 | an AFS client, these files determine the default cell for command execution.</para> | |
180 | ||
181 | <para>For predictable performance, it is best that the files in the directory named by the AFSCONF variable match those in | |
182 | the <emphasis role="bold">/usr/vice/etc</emphasis> directory on the translator machine. If your cell has an AFS directory | |
183 | that serves as the central update source for files in the <emphasis role="bold">/usr/vice/etc</emphasis> directory, it is | |
184 | simplest to set the AFSCONF variable to refer to it. In the conventional configuration, this directory is called <emphasis | |
185 | role="bold">/afs/</emphasis>cellname<emphasis role="bold">/common/etc</emphasis>.</para> | |
186 | </sect3> | |
187 | ||
188 | <sect3 id="Header_673"> | |
189 | <title>Setting Values for the Variables</title> | |
190 | ||
191 | <para>To learn the values of the AFSSERVER and AFSCONF variables, AFS command interpreters consult the following three | |
192 | sources in sequence: <orderedlist> | |
193 | <listitem> | |
194 | <para>The current command shell's environment variable definitions</para> | |
195 | </listitem> | |
196 | ||
197 | <listitem> | |
198 | <para>The <emphasis role="bold">.AFSSERVER</emphasis> or <emphasis role="bold">.AFSCONF</emphasis> file in the | |
199 | issuer's home directory</para> | |
200 | </listitem> | |
201 | ||
202 | <listitem> | |
203 | <para>The <emphasis role="bold">/.AFSSERVER</emphasis> or <emphasis role="bold">/.AFSCONF</emphasis> file in the NFS | |
204 | client machine's root (<emphasis>/</emphasis>) directory. If the client machine is diskless, its root directory can | |
205 | reside on an NFS server machine.</para> | |
206 | </listitem> | |
207 | </orderedlist></para> | |
208 | ||
209 | <para>(Actually, before consulting these sources, the NFS client looks for the <emphasis role="bold">CellServDB</emphasis> | |
210 | and <emphasis role="bold">ThisCell</emphasis> files in its own <emphasis role="bold">/usr/vice/etc</emphasis> directory. If | |
211 | the directory exists, the NFS client does not use the value of the AFSCONF variable. However, the <emphasis | |
212 | role="bold">/usr/vice/etc</emphasis> directory usually exists only on AFS clients, not NFS clients.)</para> | |
213 | ||
214 | <para>As previously detailed, correct performance generally requires that the remote executor machine be the NFS client's | |
215 | primary translator machine (the one whose <emphasis role="bold">/afs</emphasis> directory is mounted at the <emphasis | |
216 | role="bold">/afs</emphasis> directory on the NFS client). The requirement holds for all users accessing AFS from the NFS | |
217 | client, so it is usually simplest to create the <emphasis role="bold">.AFSSERVER</emphasis> file in the NFS client's root | |
218 | directory. The main reason to create the file in a user's home directory or to set the AFSSERVER environment variable in the | |
219 | current command shell is that the user needs to switch to a different translator machine, perhaps because the original one | |
220 | has become inaccessible.</para> | |
221 | ||
222 | <para>Similarly, it generally makes sense to create the <emphasis role="bold">.AFSCONF</emphasis> file in the NFS client's | |
223 | root directory. Creating it in the user's home directory or setting the AFSCONF environment variable in the current command | |
224 | shell is useful mostly when there is a reason to specify a different set of database server machines for the cell, perhaps | |
225 | in a testing situation.</para> | |
226 | </sect3> | |
227 | </sect2> | |
228 | ||
229 | <sect2 id="HDRWQ602"> | |
230 | <title>Delayed Writes for Files Saved on NFS Client Machines</title> | |
231 | ||
232 | <indexterm> | |
233 | <primary>asynchrony</primary> | |
234 | ||
235 | <secondary>when AFS files saved on NFS clients</secondary> | |
236 | </indexterm> | |
237 | ||
238 | <indexterm> | |
239 | <primary>synchrony</primary> | |
240 | ||
241 | <secondary>when AFS files saved on NFS clients</secondary> | |
242 | </indexterm> | |
243 | ||
244 | <indexterm> | |
245 | <primary>delayed write operations</primary> | |
246 | ||
247 | <secondary>when AFS files saved on NFS clients</secondary> | |
248 | </indexterm> | |
249 | ||
250 | <indexterm> | |
251 | <primary>write</primary> | |
252 | ||
253 | <secondary>operations delayed from NFS clients</secondary> | |
254 | </indexterm> | |
255 | ||
256 | <indexterm> | |
257 | <primary>write</primary> | |
258 | ||
259 | <secondary>system call for files saved on NFS client</secondary> | |
260 | </indexterm> | |
261 | ||
262 | <indexterm> | |
263 | <primary>fsync system call</primary> | |
264 | ||
265 | <secondary>for files saved on NFS client</secondary> | |
266 | </indexterm> | |
267 | ||
268 | <indexterm> | |
269 | <primary>close system call</primary> | |
270 | ||
271 | <secondary>for files saved on NFS client</secondary> | |
272 | </indexterm> | |
273 | ||
274 | <para>When an application running on an AFS client machine issues the <emphasis role="bold">close</emphasis> or <emphasis | |
275 | role="bold">fsync</emphasis> system call on a file, the Cache Manager by default performs a synchronous write of the data to | |
276 | the File Server. (For further discussion, see <link linkend="HDRWQ33">AFS Implements Save on Close</link> and <link | |
277 | linkend="HDRWQ418">Enabling Asynchronous Writes</link>.)</para> | |
278 | ||
279 | <para>To avoid degrading performance for the AFS users working on a translator machine, AFS does not perform synchronous | |
280 | writes for applications running on the translator machine's NFS clients. Instead, one of the Cache Manager daemons (the | |
281 | maintenance daemon) checks every 60 seconds for chunks in the cache that contain data saved on NFS clients, and writes their | |
282 | contents to the File Server. This does not guarantee that data saved on NFS clients is written to the File Server within 60 | |
283 | seconds, but only that the <emphasis>maintenance daemon</emphasis> checks for and begins the write of data at that | |
284 | interval.</para> | |
285 | ||
286 | <para>Furthermore, AFS always ignores the <emphasis role="bold">fsync</emphasis> system call as issued on an NFS client. The | |
287 | call requires an immediate and possibly time-consuming response from the File Server, which potentially causes delays for | |
288 | other AFS clients of the File Server. NFS version 3 automatically issues the <emphasis role="bold">fsync</emphasis> system | |
289 | call directly after the <emphasis role="bold">close</emphasis> call, but the Cache Manager ignores it and handles the | |
290 | operation just like a regular <emphasis role="bold">close</emphasis>.</para> | |
291 | ||
292 | <para>The delayed write mechanism means that there is usually a delay between the time when an NFS application issues the | |
293 | <emphasis role="bold">close</emphasis> or <emphasis role="bold">fsync</emphasis> system call on a file and the time when the | |
294 | changes are recorded at the File Server, which is when they become visible to users working on other AFS client machines | |
295 | (either directly or on its NFS clients). The delay is likely to be longer than for files saved by users working directly on an | |
296 | AFS client machine.</para> | |
297 | ||
298 | <para>The exact amount of delay is difficult to predict. The NFS protocol itself allows a standard delay before saved data | |
299 | must be transferred from the NFS client to the NFS server (the translator machine). The modified data remains in the | |
300 | translator machine's AFS client cache until the maintenance daemon's next scheduled check for such data, and it takes | |
301 | additional time to transfer the data to the File Server. The maintenance daemon uses a single thread, so there can be | |
302 | additional delay if it takes more than 60 seconds to write out all of the modified NFS data. That is, if the maintenance | |
303 | daemon is still writing data at the time of the next scheduled check, it cannot notice any additional modified data until the | |
304 | scheduled time after it completes the long write operation.</para> | |
305 | ||
306 | <para>The Cache Manager's response to the <emphasis role="bold">write</emphasis> system call is the same whether it is issued | |
307 | on an AFS client machine or on an NFS client of a translator machine: it records the modifications in the local AFS client | |
308 | cache only.</para> | |
309 | </sect2> | |
310 | </sect1> | |
311 | ||
312 | <sect1 id="HDRWQ603"> | |
313 | <title>Configuring NFS/AFS Translator Machines</title> | |
314 | ||
315 | <para>To act as an NFS/AFS translator machine, a machine must configured as follows: <itemizedlist> | |
316 | <listitem> | |
317 | <para>It must be an AFS client. Many system types supported as AFS clients can be translator machines. To learn about | |
318 | possible restrictions in a specific release of AFS, see the <emphasis>OpenAFS Release Notes</emphasis>.</para> | |
319 | </listitem> | |
320 | ||
321 | <listitem> | |
322 | <para>It must be an NFS server. The appropriate number of NFS server daemons (<emphasis role="bold">nfsd</emphasis> and | |
323 | others) depends on the anticipated NFS client load.</para> | |
324 | </listitem> | |
325 | ||
326 | <listitem> | |
327 | <para>It must export the local directory on which the AFS filespace is mounted, <emphasis role="bold">/afs</emphasis> by | |
328 | convention.</para> | |
329 | </listitem> | |
330 | </itemizedlist></para> | |
331 | ||
332 | <para>If users on a translator machine's NFS clients are to issue AFS commands, the translator machine must also meet the | |
333 | requirements discussed in <link linkend="HDRRMTSYS">Configuring the Translator Machine to Accept AFS Commands</link>.</para> | |
334 | ||
335 | <sect2 id="Header_676"> | |
336 | <title>Loading NFS and AFS Kernel Extensions</title> | |
337 | ||
338 | <para>The AFS distribution for system types that can act as NFS/AFS Translator machines usually includes two versions of the | |
339 | AFS kernel extensions file, one for machines where the kernel supports NFS server functionality, and one for machines not | |
340 | using NFS (the latter AFS kernel extensions file generally has the string <emphasis role="bold">nonfs</emphasis> in its name). | |
341 | A translator machine must use the NFS-enabled version of the AFS extensions file. On some system types, you select the | |
342 | appropriate file by moving it to a certain location, whereas on other system types you set a variable that results in | |
343 | automatic selection of the correct file. See the instructions in the <emphasis>OpenAFS Quick Beginnings</emphasis> for | |
344 | incorporating AFS into the kernel on each system type.</para> | |
345 | ||
346 | <para>On many system types, NFS is included in the kernel by default, so it is not necessary to load NFS kernel extensions | |
347 | explicitly. On system types where you must load NFS extensions, then in general you must load them before loading the AFS | |
348 | kernel extensions. The <emphasis>OpenAFS Quick Beginnings</emphasis> describes how to incorporate the AFS initialization | |
349 | script into a machine's startup sequence so that it is ordered correctly with respect to the script that handles NFS.</para> | |
350 | ||
351 | <para>In addition, the AFS extensions must be loaded into the kernel before the <emphasis role="bold">afsd</emphasis> command | |
352 | runs. The AFS initialization script included in the AFS distribution correctly orders the loading and <emphasis | |
353 | role="bold">afsd</emphasis> commands.</para> | |
354 | </sect2> | |
355 | ||
356 | <sect2 id="HDRRMTSYS"> | |
357 | <title>Configuring the Translator Machine to Accept AFS Commands</title> | |
358 | ||
359 | <para>For users working on a translator machine's NFS clients to issue AFS commands, the <emphasis | |
360 | role="bold">-rmtsys</emphasis> flag must be included on the <emphasis role="bold">afsd</emphasis> command which initializes | |
361 | the translator machine's Cache Manager. The flag starts an additional daemon (the <emphasis>remote executor</emphasis> | |
362 | daemon), which executes AFS-specific system calls on behalf of NFS clients. For a discussion of the implications of NFS users | |
363 | issuing AFS commands, see <link linkend="HDRWQ600">Setting the AFSSERVER and AFSCONF Environment Variables</link>.</para> | |
364 | ||
365 | <para>The instructions in the OpenAFS Quick Beginnings for configuring the Cache Manager explain how to add options such as | |
366 | the <emphasis role="bold">-rmtsys</emphasis> flag to the <emphasis role="bold">afsd</emphasis> command in the AFS | |
367 | initialization script. On many system types, it is simplest to list the flag on the line in the script that defines the | |
368 | OPTIONS variable. The <emphasis>remote executor daemon</emphasis> does not consume many resources, so it is simplest to add it | |
369 | to the <emphasis role="bold">afsd</emphasis> command on every translator machine, even if not all users on the machine's NFS | |
370 | clients issue AFS commands.</para> | |
371 | </sect2> | |
372 | ||
373 | <sect2 id="HDRWQ604"> | |
374 | <title>Controlling Optional Translator Features</title> | |
375 | ||
376 | <para>After an AFS client machine is configured as a translator machine, it by default exports the AFS filespace to NFS | |
377 | clients. You can disable and reenable translator functionality by using the <emphasis role="bold">fs exportafs</emphasis> | |
378 | command's <emphasis role="bold">-start</emphasis> argument. The command's other arguments control other aspects of translator | |
379 | behavior. <itemizedlist> | |
380 | <listitem> | |
381 | <para>The <emphasis role="bold">-convert</emphasis> argument controls whether the second and third (<emphasis | |
382 | role="bold">group</emphasis> and <emphasis role="bold">other</emphasis>) sets of UNIX mode bits on an AFS file or | |
383 | directory being exported to NFS are set to match the first (<emphasis role="bold">owner</emphasis>) mode bits. By | |
384 | default, the mode bits are set to match.</para> | |
385 | ||
386 | <para>Unlike AFS, NFS uses all three sets of mode bits when determining whether a user can read or write a file, even | |
387 | one stored in AFS. Some AFS files possibly do not have any <emphasis role="bold">group</emphasis> and <emphasis | |
388 | role="bold">other</emphasis> mode bits turned on, because AFS uses only the <emphasis role="bold">owner</emphasis> bits | |
389 | in combination with the ACL on the file's directory. If only the <emphasis role="bold">owner</emphasis> mode bits are | |
390 | set, NFS allows only the file's owner of the file to read or write it. Setting the <emphasis | |
391 | role="bold">-convert</emphasis> argument to the value <emphasis role="bold">on</emphasis> enables other users to access | |
392 | the file in the same manner as the owner. Setting the value <emphasis role="bold">off</emphasis> preserves the mode bits | |
393 | set on the file as stored in AFS.</para> | |
394 | </listitem> | |
395 | ||
396 | <listitem> | |
397 | <para>The <emphasis role="bold">-uidcheck</emphasis> argument controls whether tokens can be assigned to an NFS user | |
398 | whose local UID on the NFS client machine differs from the local UID associated with the tokens on the translator | |
399 | machine. By default, this is possible.</para> | |
400 | ||
401 | <para>If you turn on UID checking by setting the value <emphasis role="bold">on</emphasis>, then tokens can be assigned | |
402 | only to an NFS user whose local UID matches the local UID of the process on the translator machine that is assigning the | |
403 | tokens. One consequence is that there is no point in including the <emphasis role="bold">-id</emphasis> argument to the | |
404 | <emphasis role="bold">knfs</emphasis> command: the only acceptable value is the local UID of the command's issuer, which | |
405 | is the value used when the <emphasis role="bold">-id</emphasis> argument is omitted. Requiring matching UIDs in this way | |
406 | is effective only when users have the same local UID on the translator machine as on NFS client machines. In that case, | |
407 | it guarantees that users assign their tokens only to their own NFS sessions. For instructions, see <link | |
408 | linkend="HDRWQ612">Authenticating on Unsupported NFS Client Machines</link>.</para> | |
409 | ||
410 | <note> | |
411 | <para>Turning on UID checking also prevents users on supported NFS clients from using the <emphasis | |
412 | role="bold">klog</emphasis> command to authenticate on the NFS client directly. They must authenticated and use the | |
413 | <emphasis role="bold">knfs</emphasis> command on the translator machine instead. This is because after the <emphasis | |
414 | role="bold">klog</emphasis> command interpreter obtains the token on the NFS client, it passes it to the Cache | |
415 | Manager's remote executor daemon, which makes the system call that stores the token in a credential structure on the | |
416 | translator machine. The remote executor generally runs as the local superuser <emphasis role="bold">root</emphasis>, | |
417 | so in most cases its local UID (normally zero) does not match the local UID of the user who issued the <emphasis | |
418 | role="bold">klog</emphasis> command on the NFS client machine.</para> | |
419 | ||
420 | <para>On the other hand, although using the <emphasis role="bold">knfs</emphasis> command instead of the <emphasis | |
421 | role="bold">klog</emphasis> command is possibly less convenient for users, it eliminates a security exposure: the | |
422 | <emphasis role="bold">klog</emphasis> command interpreter passes the token across the network to the remote executor | |
423 | daemon in clear text mode.</para> | |
424 | </note> | |
425 | ||
426 | <para>If you disable UID checking by assigning the value <emphasis role="bold">off</emphasis> , the issuer of the | |
427 | <emphasis role="bold">knfs</emphasis> command can assign tokens to a user who has a different local UID on the NFS | |
428 | client machine, such as the local superuser <emphasis role="bold">root</emphasis>. Indeed, more than one issuer of the | |
429 | <emphasis role="bold">knfs</emphasis> command can assign tokens to the same user on the NFS client machine. Each time a | |
430 | different user issues the <emphasis role="bold">knfs</emphasis> command with the same value for the <emphasis | |
431 | role="bold">-id</emphasis> argument, that user's tokens overwrite the existing ones. This can result in unpredictable | |
432 | access for the NFS user.</para> | |
433 | </listitem> | |
434 | ||
435 | <listitem> | |
436 | <para>The <emphasis role="bold">-submounts</emphasis> argument controls whether users on the NFS client can mount AFS | |
437 | directories other than the top-level <emphasis role="bold">/afs</emphasis> directory. By default, the translator does | |
438 | not permit these submounts.</para> | |
439 | ||
440 | <para>Submounts can be useful in a couple of circumstances. If, for example, NFS users need to access their own AFS home | |
441 | directories only, then creating a submount to it eliminates the need for them to know or enter the complete path. | |
442 | Similarly, you can use a submount to prevent users from accessing parts of the filespace higher in the AFS hierarchy | |
443 | than the submount.</para> | |
444 | </listitem> | |
445 | </itemizedlist></para> | |
446 | </sect2> | |
447 | ||
448 | <sect2 id="Header_679"> | |
449 | <title>To configure an NFS/AFS translator machine</title> | |
450 | ||
451 | <para>The following instructions configure the translator to enable users to issue AFS commands. Omit Step <link | |
452 | linkend="LIWQ605">6</link> if you do not want to enable this functionality. <orderedlist> | |
453 | <listitem> | |
454 | <para>Become the local superuser <emphasis role="bold">root</emphasis> on the machine, if you are not already, by | |
455 | issuing the <emphasis role="bold">su</emphasis> command. <programlisting> | |
456 | % <emphasis role="bold">su root</emphasis> | |
457 | Password: <<replaceable>root_password</replaceable>> | |
458 | </programlisting></para> | |
459 | </listitem> | |
460 | ||
461 | <listitem> | |
462 | <para>Configure the NFS/AFS translator machine as an NFS server, if it is not already. Follow the instructions provided | |
463 | by your NFS supplier. The appropriate number of NFS server daemons (such as <emphasis role="bold">nfsd</emphasis>) | |
464 | depends on the number of potential NFS clients.</para> | |
465 | </listitem> | |
466 | ||
467 | <listitem> | |
468 | <para>Configure the NFS/AFS translator machine as an AFS client, if it is not already. For the most predictable | |
469 | performance, the translator machine's local copies of the <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> and | |
470 | <emphasis role="bold">/usr/vice/etc/ThisCell</emphasis> files must be the same as on other client machines in the | |
471 | cell.</para> | |
472 | </listitem> | |
473 | ||
474 | <listitem id="LITRANS-MOUNTFILE"> | |
475 | <para>Modify the file that controls mounting of directories on the machine by remote | |
476 | NFS clients. <itemizedlist> | |
477 | <indexterm> | |
478 | <primary>etc/exports file</primary> | |
479 | </indexterm> | |
480 | ||
481 | <indexterm> | |
482 | <primary>files</primary> | |
483 | ||
484 | <secondary>exports</secondary> | |
485 | </indexterm> | |
486 | ||
487 | <listitem> | |
488 | <para>On systems that use the <emphasis role="bold">/etc/exports</emphasis> file, edit it to enable export of the | |
489 | <emphasis role="bold">/afs</emphasis> directory to NFS clients. You can list the names of specific NFS client | |
490 | machines if you want to provide access only to certain users. For a description of the file's format, see the NFS | |
491 | manual page for <emphasis role="bold">exports(5)</emphasis>.</para> | |
492 | ||
493 | <para>The following example enables any NFS client machine to mount the machine's <emphasis | |
494 | role="bold">/afs</emphasis>, <emphasis role="bold">/usr</emphasis>, and <emphasis role="bold">/usr2</emphasis> | |
495 | directories:</para> | |
496 | ||
497 | <programlisting> | |
498 | /afs | |
499 | /usr | |
500 | /usr2 | |
501 | </programlisting> | |
502 | ||
503 | <indexterm> | |
504 | <primary>share command</primary> | |
505 | </indexterm> | |
506 | ||
507 | <indexterm> | |
508 | <primary>commands</primary> | |
509 | ||
510 | <secondary>share</secondary> | |
511 | </indexterm> | |
512 | </listitem> | |
513 | ||
514 | <listitem> | |
515 | <para>On system types that use the <emphasis role="bold">share</emphasis> command, edit the <emphasis | |
516 | role="bold">/etc/dfs/dfstab</emphasis> file or equivalent to include <emphasis role="bold">share</emphasis> | |
517 | instructions that enable remote mounts of the <emphasis role="bold">/afs</emphasis> directory. Most distributions | |
518 | include the binary as <emphasis role="bold">/usr/sbin/share</emphasis>. The following example commands enable | |
519 | remote mounts of the root ( <emphasis role="bold">/</emphasis> ) and <emphasis role="bold">/afs</emphasis> | |
520 | directories. To verify the correct syntax, consult the manual page for the <emphasis role="bold">share</emphasis> | |
521 | command. <programlisting> | |
522 | share -F nfs -o rw -d "root" / | |
523 | share -F nfs -o rw -d "afs gateway" /afs | |
524 | </programlisting></para> | |
525 | </listitem> | |
526 | </itemizedlist></para> | |
527 | </listitem> | |
528 | ||
529 | <listitem> | |
530 | <para>Edit the machine's AFS initialization file to invoke the standard UNIX <emphasis role="bold">exportfs</emphasis> | |
531 | command after the <emphasis role="bold">afsd</emphasis> program runs. On some system types, the modifications you made | |
532 | in Step <link linkend="LITRANS-MOUNTFILE">4</link> are not enough to enable exporting the AFS filespace via the | |
533 | <emphasis role="bold">/afs</emphasis> directory, because the resulting configuration changes are made before the | |
534 | <emphasis role="bold">afsd</emphasis> program runs during machine initialization. Only after the <emphasis | |
535 | role="bold">afsd</emphasis> program runs does the <emphasis role="bold">/afs</emphasis> directory become the mount point | |
536 | for the entire AFS filespace; before, it is a local directory like any other.</para> | |
537 | </listitem> | |
538 | ||
539 | <listitem id="LIWQ605"> | |
540 | <para>Modify the <emphasis role="bold">afsd</emphasis> command in the AFS initialization file to | |
541 | include the <emphasis role="bold">-rmtsys</emphasis> flag.</para> | |
542 | ||
543 | <para>For system types other than IRIX, the instructions in the <emphasis>OpenAFS Quick Beginnings</emphasis> for | |
544 | configuring the Cache Manager explain how to add the <emphasis role="bold">-rmtsys</emphasis> flag, for example by | |
545 | adding it to the line in the script that defines the value for the OPTIONS variable.</para> | |
546 | ||
547 | <para>On IRIX systems, the AFS initialization script automatically adds the <emphasis role="bold">-rmtsys</emphasis> | |
548 | flag if you have activated the <emphasis role="bold">afsxnfs</emphasis> configuration variable as instructed in the | |
549 | <emphasis>OpenAFS Quick Beginnings</emphasis> instructions for incorporating AFS extensions into the kernel. If the | |
550 | variable is not already activated, issue the following command.</para> | |
551 | ||
552 | <programlisting> | |
553 | # <emphasis role="bold">/etc/chkconfig -f afsxnfs on</emphasis> | |
554 | </programlisting> | |
555 | </listitem> | |
556 | ||
557 | <listitem> | |
558 | <para><emphasis role="bold">(Optional)</emphasis> Depending on the number of NFS clients you expect this machine to | |
559 | serve, it can be beneficial to add other arguments to the <emphasis role="bold">afsd</emphasis> command in the machine's | |
560 | initialization file, such as the <emphasis role="bold">-daemons</emphasis> argument to set the number of background | |
561 | daemons. See <link linkend="HDRWQ387">Administering Client Machines and the Cache Manager</link> and the <emphasis | |
562 | role="bold">afsd</emphasis> reference page in the <emphasis>OpenAFS Administration Reference</emphasis>.</para> | |
563 | </listitem> | |
564 | ||
565 | <listitem> | |
566 | <para>Reboot the machine. On many system types, the appropriate command is <emphasis role="bold">shutdown</emphasis>; | |
567 | consult your operating system administrator's guide. <programlisting> | |
568 | # <emphasis role="bold">shutdown</emphasis> appropriate_options | |
569 | </programlisting></para> | |
570 | </listitem> | |
571 | </orderedlist></para> | |
572 | ||
573 | <indexterm> | |
574 | <primary>fs commands</primary> | |
575 | ||
576 | <secondary>exportafs</secondary> | |
577 | </indexterm> | |
578 | ||
579 | <indexterm> | |
580 | <primary>commands</primary> | |
581 | ||
582 | <secondary>fs exportafs</secondary> | |
583 | </indexterm> | |
584 | </sect2> | |
585 | ||
586 | <sect2 id="Header_680"> | |
587 | <title>To disable or enable Translator functionality, or set optional features</title> | |
588 | ||
589 | <orderedlist> | |
590 | <listitem> | |
591 | <para>Become the local superuser <emphasis role="bold">root</emphasis> on the machine, if you are not already, by issuing | |
592 | the <emphasis role="bold">su</emphasis> command. <programlisting> | |
593 | % <emphasis role="bold">su root</emphasis> | |
594 | Password: <<replaceable>root_password</replaceable>> | |
595 | </programlisting></para> | |
596 | </listitem> | |
597 | ||
598 | <listitem> | |
599 | <para>Issue the <emphasis role="bold">fs exportafs</emphasis> command. <programlisting> | |
600 | # <emphasis role="bold">fs exportafs nfs</emphasis> [<emphasis role="bold">-start</emphasis> {<emphasis role="bold">on</emphasis> | <emphasis | |
601 | role="bold">off</emphasis>}} ] [<emphasis role="bold">-convert</emphasis> {<emphasis role="bold">on</emphasis> | <emphasis | |
602 | role="bold">off</emphasis>}] | |
603 | [<emphasis role="bold">-uidcheck</emphasis> {<emphasis role="bold">on</emphasis> | <emphasis role="bold">off</emphasis>}] [<emphasis | |
604 | role="bold">-submounts</emphasis> {<emphasis role="bold">on</emphasis> | <emphasis role="bold">off</emphasis>}] | |
605 | </programlisting> <variablelist> | |
606 | <varlistentry> | |
607 | <term><emphasis role="bold">-start</emphasis></term> | |
608 | ||
609 | <listitem> | |
610 | <para>Disables translator functionality if the value is <emphasis role="bold">off</emphasis> or reenables it if | |
611 | the value is <emphasis role="bold">on</emphasis>. Omit this argument to display the current setting of all | |
612 | parameters set by this command.</para> | |
613 | </listitem> | |
614 | </varlistentry> | |
615 | ||
616 | <varlistentry> | |
617 | <term><emphasis role="bold">-convert</emphasis></term> | |
618 | ||
619 | <listitem> | |
620 | <para>Controls the setting of the second and third (<emphasis role="bold">group</emphasis> and <emphasis | |
621 | role="bold">other</emphasis>) sets of UNIX mode bits on AFS files and directories as exported to NFS clients If | |
622 | the value is <emphasis role="bold">on</emphasis>, they are set to match the <emphasis role="bold">owner</emphasis> | |
623 | mode bits. If the value is <emphasis role="bold">off</emphasis>, the bits are not changed. If this argument is | |
624 | omitted, the default value is <emphasis role="bold">on</emphasis>.</para> | |
625 | </listitem> | |
626 | </varlistentry> | |
627 | ||
628 | <varlistentry> | |
629 | <term><emphasis role="bold">-uidcheck</emphasis></term> | |
630 | ||
631 | <listitem> | |
632 | <para>Controls whether issuers of the <emphasis role="bold">knfs</emphasis> command can specify a value for its | |
633 | <emphasis role="bold">-id</emphasis> argument that does not match their AFS UID: <itemizedlist> | |
634 | <listitem> | |
635 | <para>If the value is <emphasis role="bold">on</emphasis>, the value of the <emphasis | |
636 | role="bold">-id</emphasis> argument must match the issuer's local UID.</para> | |
637 | </listitem> | |
638 | ||
639 | <listitem> | |
640 | <para>If the value is <emphasis role="bold">off</emphasis>, the issuer of the <emphasis | |
641 | role="bold">knfs</emphasis> command can use the <emphasis role="bold">-id</emphasis> argument to assign | |
642 | tokens to a user who has a different local UID on the NFS client machine, such as the local superuser | |
643 | <emphasis role="bold">root</emphasis>.</para> | |
644 | </listitem> | |
645 | </itemizedlist></para> | |
646 | ||
647 | <para>If this argument is omitted, the default value is <emphasis role="bold">off</emphasis>.</para> | |
648 | </listitem> | |
649 | </varlistentry> | |
650 | ||
651 | <varlistentry> | |
652 | <term><emphasis role="bold">-submounts</emphasis></term> | |
653 | ||
654 | <listitem> | |
655 | <para>Controls whether the translator services an NFS mount of any directory in the AFS filespace other than the | |
656 | top-level <emphasis role="bold">/afs</emphasis> directory. If the value is <emphasis role="bold">on</emphasis>, | |
657 | such submounts are allowed. If the value is off, only mounts of the <emphasis role="bold">/afs</emphasis> | |
658 | directory are allowed. If this argument is omitted, the default value is <emphasis | |
659 | role="bold">off</emphasis>.</para> | |
660 | </listitem> | |
661 | </varlistentry> | |
662 | </variablelist></para> | |
663 | </listitem> | |
664 | </orderedlist> | |
665 | </sect2> | |
666 | </sect1> | |
667 | ||
668 | <sect1 id="HDRWQ606"> | |
669 | <title>Configuring NFS Client Machines</title> | |
670 | ||
671 | <para>Any NFS client machine that meets the following requirements can access files in AFS via the NFS/AFS Translator. It does | |
672 | not need to be configured as an AFS client machine. <itemizedlist> | |
673 | <listitem> | |
674 | <para>It must NFS-mount a translator machine's <emphasis role="bold">/afs</emphasis> directory on a local directory, which | |
675 | by convention is also called <emphasis role="bold">/afs</emphasis>. The following instructions explain how to add the | |
676 | <emphasis role="bold">mount</emphasis> command to the NFS client machine's <emphasis role="bold">/etc/fstab</emphasis> | |
677 | file or equivalent.</para> | |
678 | ||
679 | <para>The directory on which an NFS client mounts the translator's machine's <emphasis role="bold">/afs</emphasis> | |
680 | directory can be called something other than <emphasis role="bold">/afs</emphasis>. For instance, to make it easy to | |
681 | switch to another translator machine if the original one becomes inaccessible, you can mount more than one translator | |
682 | machine's <emphasis role="bold">/afs</emphasis> directory. Name the mount <emphasis role="bold">/afs</emphasis> for the | |
683 | translator machine that you normally use, and use a different name the mount to each alternate translator machine.</para> | |
684 | ||
685 | <para>Mounting the AFS filespace on a directory other than <emphasis role="bold">/afs</emphasis> introduces another | |
686 | requirement, however: when issuing a command that takes an AFS pathname argument, you must specify the full pathname, | |
687 | starting with <emphasis role="bold">/afs</emphasis>, rather than a relative pathname. Suppose, for example, that a | |
688 | translator machine's AFS filespace is mounted at <emphasis role="bold">/afs2</emphasis> on an NFS client machine and you | |
689 | issue the following command to display the ACL on the current working directory, which is in AFS:</para> | |
690 | ||
691 | <programlisting> | |
692 | % <emphasis role="bold">fs listacl .</emphasis> | |
693 | </programlisting> | |
694 | ||
695 | <para>The <emphasis role="bold">fs</emphasis> command interpreter on the NFS client must construct a full pathname before | |
696 | passing the request to the Cache Manager on the translator machine. The AFS filespace is mounted at <emphasis | |
697 | role="bold">/afs2</emphasis>, so the full pathname starts with that string. However, the Cache Manager on the translator | |
698 | cannot find a directory called <emphasis role="bold">/afs2</emphasis>, because its mount of the AFS filespace is called | |
699 | <emphasis role="bold">/afs</emphasis>. The command fails. To prevent the failure, provide the file's complete pathname, | |
700 | starting with the string <emphasis role="bold">/afs</emphasis>.</para> | |
701 | </listitem> | |
702 | ||
703 | <listitem> | |
704 | <para>It must run an appropriate number of NFS client <emphasis role="bold">biod</emphasis> daemons, which improve | |
705 | performance by handling pre-reading and delayed writing. Most NFS vendors recommend running four such daemons, and most | |
706 | NFS initialization scripts start them automatically. Consult your NFS documentation.</para> | |
707 | </listitem> | |
708 | </itemizedlist></para> | |
709 | ||
710 | <para>To enable users to issue AFS commands, the NFS client machine must also be a supported system type (one for which AFS | |
711 | binaries are available) and able to access the AFS command binaries. The <emphasis>OpenAFS Release Notes</emphasis> list the | |
712 | supported system types in each release.</para> | |
713 | ||
714 | <para>In addition, the AFSSERVER and AFSCONF environment variables must be set appropriately, as discussed in <link | |
715 | linkend="HDRWQ600">Setting the AFSSERVER and AFSCONF Environment Variables</link>.</para> | |
716 | ||
717 | <sect2 id="Header_682"> | |
718 | <title>To configure an NFS client machine to access AFS</title> | |
719 | ||
720 | <note> | |
721 | <para>The following instructions enable NFS users to issue AFS commands. Omit Step <link linkend="LIWQ608">5</link> and Step | |
722 | <link linkend="LIWQ609">6</link> if you do not want to enable this functionality.</para> | |
723 | </note> | |
724 | ||
725 | <orderedlist> | |
726 | <listitem> | |
727 | <para>Become the local superuser <emphasis role="bold">root</emphasis> on the machine, if you are not already, by issuing | |
728 | the <emphasis role="bold">su</emphasis> command. <programlisting> | |
729 | % <emphasis role="bold">su root</emphasis> | |
730 | Password: <<replaceable>root_password</replaceable>> | |
731 | </programlisting></para> | |
732 | </listitem> | |
733 | ||
734 | <listitem> | |
735 | <para>Configure the machine as an NFS client machine, if it is not already. Follow the instructions provided by your NFS | |
736 | vendor. The number of NFS client (<emphasis role="bold">biod</emphasis>) daemons needs to be appropriate for the expected | |
737 | load on this machine. The usual recommended number is four.</para> | |
738 | </listitem> | |
739 | ||
740 | <listitem> | |
741 | <para>Create a directory called <emphasis role="bold">/afs</emphasis> on the machine, if one does not already exist, to | |
742 | act as the mount point for the translator machine's <emphasis role="bold">/afs</emphasis> directory. It is acceptable to | |
743 | use other names, but doing so introduces the limitation discussed in the introduction to this section. <programlisting> | |
744 | # <emphasis role="bold">mkdir /afs</emphasis> | |
745 | </programlisting> <indexterm> | |
746 | <primary>commands</primary> | |
747 | ||
748 | <secondary>mount</secondary> | |
749 | </indexterm> <indexterm> | |
750 | <primary>mount command</primary> | |
751 | </indexterm></para> | |
752 | </listitem> | |
753 | ||
754 | <listitem id="LIWQ607"> | |
755 | <para>Modify the machine's file systems registry file (<emphasis role="bold">/etc/fstab</emphasis> | |
756 | or equivalent) to include a command that mounts a translator machine's <emphasis role="bold">/afs</emphasis> directory. To | |
757 | verify the correct syntax of the <emphasis role="bold">mount</emphasis> command, see the operating system's <emphasis | |
758 | role="bold">mount(5)</emphasis> manual page. The following example includes options that are appropriate on many system | |
759 | types. <programlisting> | |
760 | mount -o hard,intr,timeo=300 translator_machine:/afs /afs | |
761 | </programlisting></para> | |
762 | ||
763 | <para>where <variablelist> | |
764 | <varlistentry> | |
765 | <term><computeroutput>hard</computeroutput></term> | |
766 | ||
767 | <listitem> | |
768 | <para>Indicates that the NFS client retries NFS requests until the NFS server (translator machine) responds. When | |
769 | using the translator, file operations possibly take longer than with NFS alone, because they must also pass | |
770 | through the AFS Cache Manager. With a soft mount, a delayed response from the translator machine can cause the | |
771 | request to abort. Many NFS versions use hard mounts by default; if your version does not, it is best to add this | |
772 | option.</para> | |
773 | </listitem> | |
774 | </varlistentry> | |
775 | ||
776 | <varlistentry> | |
777 | <term><computeroutput>intr</computeroutput></term> | |
778 | ||
779 | <listitem> | |
780 | <para>Enables the user to use a keyboard interrupt signal (such as <<emphasis | |
781 | role="bold">Ctrl-c</emphasis>>) to break the mount when the translator machine is inaccessible. Include this | |
782 | option only if the <computeroutput>hard</computeroutput> option is used, in which case the connection does not | |
783 | automatically break off when a translator machine goes down.</para> | |
784 | </listitem> | |
785 | </varlistentry> | |
786 | ||
787 | <varlistentry> | |
788 | <term><computeroutput>timeo</computeroutput></term> | |
789 | ||
790 | <listitem> | |
791 | <para>Sets the maximum time (in tenths of seconds) the translator can take to respond to the NFS client's request | |
792 | before the client considers the request timed out. With a hard mount, setting this option to a high number like | |
793 | 300 reduces the number of error messages like the following, which are generated when the translator does not | |
794 | respond immediately. <programlisting> | |
795 | NFS server translator is not responding, still trying | |
796 | </programlisting></para> | |
797 | ||
798 | <para>With a soft mount, it reduces the number of actual errors returned on timed-out requests.</para> | |
799 | </listitem> | |
800 | </varlistentry> | |
801 | ||
802 | <varlistentry> | |
803 | <term><replaceable>translator_machine</replaceable></term> | |
804 | ||
805 | <listitem> | |
806 | <para>Specifies the fully-qualified hostname of the translator machine whose <emphasis role="bold">/afs</emphasis> | |
807 | directory is to be mounted on the client machine's <emphasis role="bold">/afs</emphasis> directory.</para> | |
808 | </listitem> | |
809 | </varlistentry> | |
810 | </variablelist></para> | |
811 | ||
812 | <note> | |
813 | <para>To mount the translator machine's <emphasis role="bold">/afs</emphasis> directory onto a directory on the NFS | |
814 | client other than <emphasis role="bold">/afs</emphasis>, substitute the alternate directory name for the second instance | |
815 | of <computeroutput>/afs</computeroutput> in the <emphasis role="bold">mount</emphasis> command.</para> | |
816 | </note> | |
817 | </listitem> | |
818 | ||
819 | <listitem id="LIWQ608"> | |
820 | <para><emphasis role="bold">(Optional)</emphasis> If appropriate, create the <emphasis | |
821 | role="bold">/.AFSSERVER</emphasis> file to set the AFSSERVER environment variable for all of the machine's users. For a | |
822 | discussion, see <link linkend="HDRWQ600">Setting the AFSSERVER and AFSCONF Environment Variables</link>. Place a single | |
823 | line in the file, specifying the fully-qualified hostname of the translator machine that is to serve as the remote | |
824 | executor. To enable users to issue commands that handle tokens, it must be the machine named as translator_machine in Step | |
825 | <link linkend="LIWQ607">4</link>.</para> | |
826 | </listitem> | |
827 | ||
828 | <listitem id="LIWQ609"> | |
829 | <para><emphasis role="bold">(Optional)</emphasis> If appropriate, create the <emphasis | |
830 | role="bold">/.AFSCONF</emphasis> file to set the AFSCONF environment variable for all of the machine's users. For a | |
831 | discussion, see <link linkend="HDRWQ600">Setting the AFSSERVER and AFSCONF Environment Variables</link>. Place a single | |
832 | line in the file, specifying the name of the directory where the <emphasis role="bold">CellServDB</emphasis> and <emphasis | |
833 | role="bold">ThisCell</emphasis> files reside. If you use a central update source for these files (by convention, <emphasis | |
834 | role="bold">/afs/</emphasis>cellname<emphasis role="bold">/common/etc</emphasis>), name it here.</para> | |
835 | </listitem> | |
836 | </orderedlist> | |
837 | </sect2> | |
838 | </sect1> | |
839 | ||
840 | <sect1 id="HDRWQ610"> | |
841 | <title>Configuring User Accounts</title> | |
842 | ||
843 | <para>There are no requirements for NFS users to access AFS as unauthenticated users. To take advantage of more AFS | |
844 | functionality, however, they must meet the indicated requirements. <itemizedlist> | |
845 | <listitem> | |
846 | <para>To access AFS as authenticated users, they must of course authenticate with AFS, which requires an entry in the | |
847 | Protection and Authentication Databases.</para> | |
848 | </listitem> | |
849 | ||
850 | <listitem> | |
851 | <para>To create and store files, they need the required ACL permissions. If you are providing a home directory for storage | |
852 | of personal files, it is conventional to create a dedicated volume and mount it at the user's home directory location in | |
853 | the AFS filespace.</para> | |
854 | </listitem> | |
855 | ||
856 | <listitem> | |
857 | <para>To issue AFS commands, they must meet several additional requirements: <itemizedlist> | |
858 | <listitem> | |
859 | <para>They must be working on an NFS client machine of a supported system type and from which the AFS command | |
860 | binaries are accessible.</para> | |
861 | </listitem> | |
862 | ||
863 | <listitem> | |
864 | <para>Their command shell must define values for the AFSSERVER and AFSCONF environment variables, as described in | |
865 | <link linkend="HDRWQ600">Setting the AFSSERVER and AFSCONF Environment Variables</link>. It is often simplest to | |
866 | define the variables by creating <emphasis role="bold">/.AFSSERVER</emphasis> and <emphasis | |
867 | role="bold">/.AFSCONF</emphasis> file in the NFS client machine's root directory, but you can also either set the | |
868 | variables in each user's shell initialization file (<emphasis role="bold">.cshrc</emphasis> or equivalent), or | |
869 | create files called <emphasis role="bold">.AFSSERVER</emphasis> and <emphasis role="bold">.AFSCONF</emphasis> in | |
870 | each user's home directory.</para> | |
871 | </listitem> | |
872 | ||
873 | <listitem> | |
874 | <para>They must have an entry in the AFS Protection and Authentication Databases, so that they can authenticate if | |
875 | the command requires AFS privilege. Other commands instead require assuming the local <emphasis | |
876 | role="bold">root</emphasis> identity on the translator machine; for further discussion, see <link | |
877 | linkend="HDRWQ601">The AFSSERVER Variable</link>.</para> | |
878 | </listitem> | |
879 | ||
880 | <listitem> | |
881 | <para>Their PATH environment variable must include the pathname to the appropriate AFS binaries. If a user works on | |
882 | NFS client machines of different system types, include the <emphasis role="bold">@sys</emphasis> variable in the | |
883 | pathname rather than an actual system type name.</para> | |
884 | </listitem> | |
885 | </itemizedlist></para> | |
886 | </listitem> | |
887 | </itemizedlist></para> | |
888 | ||
889 | <sect2 id="Header_684"> | |
890 | <title>To configure a user account for issuing AFS commands</title> | |
891 | ||
892 | <orderedlist> | |
893 | <listitem> | |
894 | <para>Create entries for the user in the Protection and Authentication Databases, or create a complete AFS account. See | |
895 | the instructions for account creation in <link linkend="HDRWQ449">Creating and Deleting User Accounts with the uss Command | |
896 | Suite</link> or <link linkend="HDRWQ491">Administering User Accounts</link>.</para> | |
897 | </listitem> | |
898 | ||
899 | <listitem id="LIWQ611"> | |
900 | <para>Modify the user's PATH environment variable to include the pathname of AFS binaries, such as | |
901 | <emphasis role="bold">/afs/</emphasis>cellname<emphasis role="bold">/</emphasis>sysname<emphasis | |
902 | role="bold">/usr/afsws/bin</emphasis>. If the user works on NFS client machines of different system types, considering | |
903 | replacing the specific sysname value with the <emphasis role="bold">@sys</emphasis> variable. The PATH variable is | |
904 | commonly defined in a login or shell initialization file (such as the <emphasis role="bold">.login</emphasis> or <emphasis | |
905 | role="bold">.cshrc</emphasis> file).</para> | |
906 | </listitem> | |
907 | ||
908 | <listitem> | |
909 | <para><emphasis role="bold">(Optional)</emphasis> Set the AFSSERVER and AFSCONF environment variables if appropriate. This | |
910 | is required if the NFS client machines on which the user works do not have the <emphasis | |
911 | role="bold">/.AFSSERVER</emphasis> and <emphasis role="bold">/.AFSCONF</emphasis> files in their root directories, or if | |
912 | you want user-specific values to override those settings.</para> | |
913 | ||
914 | <para>Either define the variables in the user's login or shell initialization file, or create the files <emphasis | |
915 | role="bold">.AFSSERVER</emphasis> and <emphasis role="bold">.AFSCONF</emphasis> files in the user's home directory.</para> | |
916 | ||
917 | <para>For the AFSSERVER variable, specify the fully-qualified hostname of the translator machine that is to serve as the | |
918 | remote executor. For the AFSCONF variable, specify the name of the directory where the <emphasis | |
919 | role="bold">CellServDB</emphasis> and <emphasis role="bold">ThisCell</emphasis> files reside. If you use a central update | |
920 | source for these files (by convention, <emphasis role="bold">/afs/</emphasis>cellname<emphasis | |
921 | role="bold">/common/etc</emphasis>), name it here.</para> | |
922 | </listitem> | |
923 | ||
924 | <listitem> | |
925 | <para>If the pathname you defined in Step <link linkend="LIWQ611">2</link> includes the <emphasis | |
926 | role="bold">@sys</emphasis> variable, instruct users to check that their system name is defined correctly before they | |
927 | issue AFS commands. They issue the following command: <programlisting> | |
928 | % <emphasis role="bold">fs sysname</emphasis> | |
929 | </programlisting></para> | |
930 | </listitem> | |
931 | </orderedlist> | |
932 | </sect2> | |
933 | </sect1> | |
934 | ||
935 | <sect1 id="HDRWQ612"> | |
936 | <title>Authenticating on Unsupported NFS Client Machines</title> | |
937 | ||
938 | <para>The <emphasis role="bold">knfs</emphasis> command enables users to authenticate with AFS when they are working on NFS | |
939 | clients of unsupported system types (those for which AFS binaries are not available). This enables such users to access the AFS | |
940 | file tree to the same extent as any other AFS user. They cannot, however, issue AFS commands, which is possible only on NFS | |
941 | client machines of supported system types.</para> | |
942 | ||
943 | <para>To authenticate on an unsupported system type, establish a connection to the translator machine (using a facility such as | |
944 | <emphasis role="bold">telnet</emphasis>), and issue the <emphasis role="bold">klog</emphasis> command to obtain tokens for all | |
945 | the cells you wish to contact during the upcoming NFS session. Then issue the <emphasis role="bold">knfs</emphasis> command, | |
946 | which stores the tokens in a credential structure associated with your NFS session. The Cache Manager uses the tokens when | |
947 | performing AFS access requests that originate from your NFS session.</para> | |
948 | ||
949 | <para>More specifically, the credential structure is identified by a process authentication group (PAG) number associated with a | |
950 | particular local UID on a specific NFS client machine. By default, the NFS UID recorded in the credential structure is the same | |
951 | as your local UID on the translator machine. You can include the <emphasis role="bold">-id</emphasis> argument to specify an | |
952 | alternate NFS UID, unless the translator machine's administrator has used the <emphasis role="bold">fs exportafs</emphasis> | |
953 | command's <emphasis role="bold">-uidcheck</emphasis> argument to enable UID checking. In that case, the value of the <emphasis | |
954 | role="bold">-id</emphasis> argument must match your local UID on the translator machine (so there is not point to including the | |
955 | <emphasis role="bold">-id</emphasis> argument). Enforcing matching UIDs prevents someone else from placing their tokens in your | |
956 | credential structure, either accidentally or on purpose. However, it means that your cell's administrators must set your local | |
957 | UID on the NFS client to match your local UID on the translator machine. It also makes it impossible to authenticate by issuing | |
958 | the <emphasis role="bold">klog</emphasis> command on supported NFS clients, meaning that all NFS users must use the <emphasis | |
959 | role="bold">knfs</emphasis> command. See <link linkend="HDRWQ604">Controlling Optional Translator Features</link>.</para> | |
960 | ||
961 | <para>After issuing the <emphasis role="bold">knfs</emphasis> command, you can begin working on the NFS client with | |
962 | authenticated access to AFS. When you are finished working, it is a good policy to destroy your tokens by issuing the <emphasis | |
963 | role="bold">knfs</emphasis> command on the translator machine again, this time with the <emphasis role="bold">-unlog</emphasis> | |
964 | flag. This is simpler if you have left the connection to the translator machine open, but you can always establish a new | |
965 | connection if you closed the original one.</para> | |
966 | ||
967 | <para>If your NFS client machine is a supported system type and you wish to issue AFS commands on it, include the <emphasis | |
968 | role="bold">-sysname</emphasis> argument to the <emphasis role="bold">knfs</emphasis> command. The remote executor daemon on the | |
969 | translator machine substitutes its value for the <emphasis role="bold">@sys</emphasis> variable in pathnames when executing AFS | |
970 | commands that you issue on the NFS client machine. If your PATH environment variable uses the <emphasis | |
971 | role="bold">@sys</emphasis> variable in the pathnames for directories that house AFS binaries (as recommended), then setting | |
972 | this argument enables the remote executor daemon to access the AFS binaries appropriate for your NFS client machine even if its | |
973 | system type differs from the translator machine's.</para> | |
974 | ||
975 | <para>If you do not issue the <emphasis role="bold">knfs</emphasis> command (or the <emphasis role="bold">klog</emphasis> | |
976 | command on the NFS client machine itself, if it is a supported system type), then you are not authenticated with AFS. For a | |
977 | description of unauthenticated access, see <link linkend="HDRWQ599">Enabling Unauthenticated or Authenticated AFS Access</link>. | |
978 | <indexterm> | |
979 | <primary>knfs command</primary> | |
980 | </indexterm> <indexterm> | |
981 | <primary>commands</primary> | |
982 | ||
983 | <secondary>knfs</secondary> | |
984 | </indexterm></para> | |
985 | ||
986 | <sect2 id="Header_686"> | |
987 | <title>To authenticate using the knfs command</title> | |
988 | ||
989 | <orderedlist> | |
990 | <listitem> | |
991 | <para>Log on to the relevant translator machine, either on the console or remotely by using a program such as <emphasis | |
992 | role="bold">telnet</emphasis>.</para> | |
993 | </listitem> | |
994 | ||
995 | <listitem> | |
996 | <para>Obtain tokens for every cell you wish to access while working on the NFS client. AFS-modified login utilities | |
997 | acquire a token for the translator machine's local cell by default; use <emphasis role="bold">klog</emphasis> command to | |
998 | obtain tokens for other cells if desired.</para> | |
999 | </listitem> | |
1000 | ||
1001 | <listitem> | |
1002 | <para>Issue the <emphasis role="bold">knfs</emphasis> command to create a credential structure in the translator machine's | |
1003 | kernel memory for storing the tokens obtained in the previous step. Include the <emphasis role="bold">-id</emphasis> | |
1004 | argument to associate the structure with a UID on the NFS client that differs from your local UID on the translator | |
1005 | machine. This is possible unless the translator machine's administrator has enabled UID checking on the translator | |
1006 | machine; see <link linkend="HDRWQ604">Controlling Optional Translator Features</link>. If the NFS client machine is a | |
1007 | supported system type and you wish to issue AFS commands on it, include the <emphasis role="bold">-sysname</emphasis> | |
1008 | argument to specify its system type. <programlisting> | |
1009 | % <emphasis role="bold">knfs -host</emphasis> <<replaceable>host name</replaceable>> [<emphasis role="bold">-id</emphasis> <<replaceable>user ID (decimal)</replaceable>>] \ | |
1010 | [<emphasis role="bold">-sysname</emphasis> <<replaceable>host's '@sys' value</replaceable>>] | |
1011 | </programlisting></para> | |
1012 | ||
1013 | <para>where <variablelist> | |
1014 | <varlistentry> | |
1015 | <term><emphasis role="bold">-host</emphasis></term> | |
1016 | ||
1017 | <listitem> | |
1018 | <para>Specifies the fully-qualified hostname of the NFS client machine on which you are working.</para> | |
1019 | </listitem> | |
1020 | </varlistentry> | |
1021 | ||
1022 | <varlistentry> | |
1023 | <term><emphasis role="bold">-id</emphasis></term> | |
1024 | ||
1025 | <listitem> | |
1026 | <para>Specifies a local UID number on the NFS client machine with which to associate the tokens, if different from | |
1027 | your local UID on the translator machine. If this argument is omitted, the tokens are associated with an NFS UID | |
1028 | that matches your local UID on the translator machine. In both cases, the NFS client software marks your AFS | |
1029 | access requests with the NFS UID when it forwards them to the Cache Manager on the translator machine.</para> | |
1030 | </listitem> | |
1031 | </varlistentry> | |
1032 | ||
1033 | <varlistentry> | |
1034 | <term><emphasis role="bold">-sysname</emphasis></term> | |
1035 | ||
1036 | <listitem> | |
1037 | <para>Specifies the value that the local machine's remote executor daemon substitutes for the <emphasis | |
1038 | role="bold">@sys</emphasis> variable in pathnames when executing AFS commands issued on the NFS client machine | |
1039 | (which must be a supported system type).</para> | |
1040 | </listitem> | |
1041 | </varlistentry> | |
1042 | </variablelist></para> | |
1043 | ||
1044 | <para>The following error message indicates that the translator machine's administrator has enabled UID checking and you | |
1045 | have provided a value that differs from your local UID on the translator machine.</para> | |
1046 | ||
1047 | <programlisting> | |
1048 | knfs: Translator in 'passwd sync' mode; remote uid must be the same as local uid | |
1049 | </programlisting> | |
1050 | </listitem> | |
1051 | ||
1052 | <listitem> | |
1053 | <para>Close the connection to the translator machine (if desired) and work on the NFS client machine.</para> | |
1054 | </listitem> | |
1055 | </orderedlist> | |
1056 | ||
1057 | <indexterm> | |
1058 | <primary>tokens</primary> | |
1059 | ||
1060 | <secondary>displaying with knfs command</secondary> | |
1061 | </indexterm> | |
1062 | </sect2> | |
1063 | ||
1064 | <sect2 id="Header_687"> | |
1065 | <title>To display tokens using the knfs command</title> | |
1066 | ||
1067 | <orderedlist> | |
1068 | <listitem> | |
1069 | <para>Log on to the relevant translator machine, either on the console or remotely by using a program such as <emphasis | |
1070 | role="bold">telnet</emphasis>.</para> | |
1071 | </listitem> | |
1072 | ||
1073 | <listitem> | |
1074 | <para>Issue the <emphasis role="bold">knfs</emphasis> command with the <emphasis role="bold">-tokens</emphasis> flag to | |
1075 | display the tokens associated with either the NFS UID that matches your local UID on the translator machine or the NFS UID | |
1076 | specified by the <emphasis role="bold">-id</emphasis> argument. <programlisting> | |
1077 | % <emphasis role="bold">knfs -host</emphasis> <<replaceable>host name</replaceable>> [<emphasis role="bold">-id</emphasis> <<replaceable>user ID (decimal)</replaceable>>] <emphasis | |
1078 | role="bold">-tokens</emphasis> | |
1079 | </programlisting></para> | |
1080 | ||
1081 | <para>where <variablelist> | |
1082 | <varlistentry> | |
1083 | <term><emphasis role="bold">-host</emphasis></term> | |
1084 | ||
1085 | <listitem> | |
1086 | <para>Specifies the fully-qualified hostname of the NFS client machine on which you are working.</para> | |
1087 | </listitem> | |
1088 | </varlistentry> | |
1089 | ||
1090 | <varlistentry> | |
1091 | <term><emphasis role="bold">-id</emphasis></term> | |
1092 | ||
1093 | <listitem> | |
1094 | <para>Specifies the local UID on the NFS client machine for which to display tokens, if different from your local | |
1095 | UID on the translator machine. If this argument is omitted, the tokens are for the NFS UID that matches your local | |
1096 | UID on the translator machine.</para> | |
1097 | </listitem> | |
1098 | </varlistentry> | |
1099 | ||
1100 | <varlistentry> | |
1101 | <term><emphasis role="bold">-tokens</emphasis></term> | |
1102 | ||
1103 | <listitem> | |
1104 | <para>Displays the tokens.</para> | |
1105 | </listitem> | |
1106 | </varlistentry> | |
1107 | </variablelist></para> | |
1108 | </listitem> | |
1109 | ||
1110 | <listitem> | |
1111 | <para>Close the connection to the translator machine if desired.</para> | |
1112 | </listitem> | |
1113 | </orderedlist> | |
1114 | ||
1115 | <indexterm> | |
1116 | <primary>tokens</primary> | |
1117 | ||
1118 | <secondary>discarding with knfs command</secondary> | |
1119 | </indexterm> | |
1120 | </sect2> | |
1121 | ||
1122 | <sect2 id="Header_688"> | |
1123 | <title>To discard tokens using the knfs command</title> | |
1124 | ||
1125 | <orderedlist> | |
1126 | <listitem> | |
1127 | <para>If you closed your connection to the translator machine after issuing the <emphasis role="bold">knfs</emphasis> | |
1128 | command, reopen it.</para> | |
1129 | </listitem> | |
1130 | ||
1131 | <listitem> | |
1132 | <para>Issue the <emphasis role="bold">knfs</emphasis> command with the <emphasis role="bold">-unlog</emphasis> flag. | |
1133 | <programlisting> | |
1134 | % <emphasis role="bold">knfs -host</emphasis> <<replaceable>host name</replaceable>> [<emphasis role="bold">-id</emphasis> <<replaceable>user ID (decimal)</replaceable>>] <emphasis | |
1135 | role="bold">-unlog</emphasis> | |
1136 | </programlisting></para> | |
1137 | ||
1138 | <para>where <variablelist> | |
1139 | <varlistentry> | |
1140 | <term><emphasis role="bold">-host</emphasis></term> | |
1141 | ||
1142 | <listitem> | |
1143 | <para>Specifies the fully-qualified hostname of the NFS client machine you are working on.</para> | |
1144 | </listitem> | |
1145 | </varlistentry> | |
1146 | ||
1147 | <varlistentry> | |
1148 | <term><emphasis role="bold">-id</emphasis></term> | |
1149 | ||
1150 | <listitem> | |
1151 | <para>Specifies the local UID number on the NFS client machine for which to discard the associated tokens, if | |
1152 | different from your local UID on the translator machine. If this argument is omitted, the tokens associated with | |
1153 | an NFS UID that matches your local UID on the translator machine are discarded.</para> | |
1154 | </listitem> | |
1155 | </varlistentry> | |
1156 | ||
1157 | <varlistentry> | |
1158 | <term><emphasis role="bold">-unlog</emphasis></term> | |
1159 | ||
1160 | <listitem> | |
1161 | <para>Discards the tokens.</para> | |
1162 | </listitem> | |
1163 | </varlistentry> | |
1164 | </variablelist></para> | |
1165 | </listitem> | |
1166 | ||
1167 | <listitem> | |
1168 | <para>If desired, close the connection to the translator machine.</para> | |
1169 | </listitem> | |
1170 | </orderedlist> | |
1171 | </sect2> | |
1172 | </sect1> | |
1173 | </appendix> |