doc: fixes for the xsltproc -> fop -> pdf toolchain
[openafs.git] / doc / xml / AdminGuide / auagd022.xml
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: &lt;<replaceable>root_password</replaceable>&gt;
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: &lt;<replaceable>root_password</replaceable>&gt;
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: &lt;<replaceable>root_password</replaceable>&gt;
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 &lt;<emphasis
781                   role="bold">Ctrl-c</emphasis>&gt;) 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> &lt;<replaceable>host name</replaceable>&gt;  [<emphasis role="bold">-id</emphasis> &lt;<replaceable>user ID (decimal)</replaceable>&gt;]  \
1010                 [<emphasis role="bold">-sysname</emphasis>  &lt;<replaceable>host's '@sys' value</replaceable>&gt;]
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> &lt;<replaceable>host name</replaceable>&gt;  [<emphasis role="bold">-id</emphasis> &lt;<replaceable>user ID (decimal)</replaceable>&gt;] <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>  &lt;<replaceable>host name</replaceable>&gt;  [<emphasis role="bold">-id</emphasis> &lt;<replaceable>user ID (decimal)</replaceable>&gt;]  <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>