[openafs.git] / doc / html / UserGuide / auusg010.htm
3 <TITLE>User Guide</TITLE>
4 <!-- Begin Header Records  ========================================== -->
5 <!-- /tmp/idwt3629/auusg000.scr converted by idb2h R4.2 (359) ID      -->
6 <!-- Workbench Version (AIX) on 2 Oct 2000 at 14:38:44                -->
7 <META HTTP-EQUIV="updated" CONTENT="Mon, 02 Oct 2000 14:38:42">
8 <META HTTP-EQUIV="review" CONTENT="Tue, 02 Oct 2001 14:38:42">
9 <META HTTP-EQUIV="expires" CONTENT="Wed, 02 Oct 2002 14:38:42">
10 </HEAD><BODY>
11 <!-- (C) IBM Corporation 2000. All Rights Reserved    --> 
12 <BODY bgcolor="ffffff"> 
13 <!-- End Header Records  ============================================ -->
14 <A NAME="Top_Of_Page"></A>
15 <H1>User Guide</H1>
16 <HR><P ALIGN="center"> <A HREF="../index.htm"><IMG SRC="../books.gif" BORDER="0" ALT="[Return to Library]"></A> <A HREF="auusg002.htm#ToC"><IMG SRC="../toc.gif" BORDER="0" ALT="[Contents]"></A> <A HREF="auusg009.htm"><IMG SRC="../prev.gif" BORDER="0" ALT="[Previous Topic]"></A> <A HREF="#Bot_Of_Page"><IMG SRC="../bot.gif" BORDER="0" ALT="[Bottom of Topic]"></A> <A HREF="auusg011.htm"><IMG SRC="../next.gif" BORDER="0" ALT="[Next Topic]"></A> <A HREF="auusg013.htm#HDRINDEX"><IMG SRC="../index.gif" BORDER="0" ALT="[Index]"></A> <P> 
17 <P>
18 <HR><H1><A NAME="HDRWQ80" HREF="auusg002.htm#ToC_158">Appendix A. Using the NFS/AFS Translator</A></H1>
19 <P>
20 <A NAME="IDX1135"></A>
21 <A NAME="IDX1136"></A>
22 <A NAME="IDX1137"></A>
23 <A NAME="IDX1138"></A>
24 Some cells use the Network File System (NFS) in addition to AFS. If you
25 work on an NFS client machine, your system administrator can configure it to
26 access the AFS filespace through a program called the <I>NFS/AFS
27 Translator</I><SUP>TM</SUP>. If you have an AFS account, you can
28 access AFS as an authenticated user while working on your NFS client
29 machine. Otherwise, you access AFS as the <B>anonymous</B>
30 user.
31 <TABLE><TR><TD ALIGN="LEFT" VALIGN="TOP"><B>Note:</B></TD><TD ALIGN="LEFT" VALIGN="TOP">Acceptable NFS/AFS Translator performance requires that NFS is functioning
32 correctly.
33 </TD></TR></TABLE>
34 <HR><H2><A NAME="HDRWQ81" HREF="auusg002.htm#ToC_159">Requirements for Using the NFS/AFS Translator</A></H2>
35 <P>
36 <A NAME="IDX1139"></A>
37 <A NAME="IDX1140"></A>
38 For you to use the NFS/AFS Translator, your system administrator must
39 configure the following types of machines as indicated:
40 <UL>
41 <P><LI>An <I>NFS/AFS translator machine</I> is an AFS client machine that
42 also acts as an NFS server machine. Its Cache Manager acts as the
43 surrogate Cache Manager for your NFS client machine. Ask your system
44 administrator which translator machines you can use.
45 <P><LI>Your NFS client machine must have an NFS mount to a translator
46 machine. Most often, your system administrator mounts the translator
47 machine's <B>/afs</B> directory and names the mount <B>/afs</B>
48 as well. This enables you to access the entire AFS filespace using
49 standard AFS pathnames. It is also possible to create mounts directly
50 to subdirectories of <B>/afs</B>, and to give NFS mounts different names
51 on the NFS client machine.
52 </UL>
53 <P>Your access to AFS is much more extensive if you have an AFS user
54 account. If you do not, the AFS servers recognize you as the
55 <B>anonymous</B> user and only grant you the access available to members
56 of the <B>system:anyuser</B> group.
57 <P>If your NFS client machine uses an operating system that AFS supports, your
58 system administrator can configure it to enable you to issue many AFS commands
59 on the machine. Ask him or her about the configuration and which
60 commands you can issue.
61 <HR><H2><A NAME="Header_160" HREF="auusg002.htm#ToC_160">Accessing AFS via the Translator</A></H2>
62 <A NAME="IDX1141"></A>
63 <P>If you do not have an AFS account or choose not to access AFS as an
64 authenticated user, then all you do to access AFS is provide the pathname of
65 the relevant file. Its ACL must grant the necessary permissions to the
66 <B>system:anyuser</B> group.
67 <P>If you have an AFS account and want to access AFS as an authenticated user,
68 the best method depends on whether your NFS machine is a supported
69 type. If it is, use the instructions in <A HREF="#HDRWQ82">To Authenticate on a Supported Operating System</A>. If it is not a supported type, use the
70 instructions in <A HREF="#HDRWQ83">To Authenticate on an Unsupported Operating System</A>.
71 <P><H3><A NAME="HDRWQ82" HREF="auusg002.htm#ToC_161">To Authenticate on a Supported Operating System</A></H3>
72 <OL TYPE=1>
73 <P><LI>Log into the NFS client machine using your NFS username.
74 <P><LI>Issue the <B>klog</B> command. For complete instructions, see <A HREF="auusg005.htm#HDRWQ29">To Authenticate with AFS</A>.
75 <PRE>   % <B>klog -setpag</B>
76 </PRE>
77 </OL>
78 <P><H3><A NAME="HDRWQ83" HREF="auusg002.htm#ToC_162">To Authenticate on an Unsupported Operating System</A></H3>
79 <OL TYPE=1>
80 <P><LI>Log onto the NFS client machine using your NFS username.
81 <P><LI><A NAME="LINFS-TELNET"></A>Establish a connection to the NFS/AFS translator machine
82 you are using (for example, using the <B>telnet</B> utility) and log onto
83 it using your AFS username (which is normally the same as your NFS
84 username).
85 <P><LI>If the NFS/AFS translator machine uses an AFS-modified login utility, then
86 you obtained AFS tokens in Step <A HREF="#LINFS-TELNET">2</A>. To check, issue the <B>tokens</B> command, which
87 is described fully in <A HREF="auusg005.htm#HDRWQ30">To Display Your Tokens</A>. 
88 <PRE>   % <B>tokens</B>
89 </PRE>If you do not have tokens, issue the <B>klog</B> command, which is
90 described fully in <A HREF="auusg005.htm#HDRWQ29">To Authenticate with AFS</A>. 
91 <PRE>   % <B>klog -setpag</B>
92 </PRE>
93 <P><LI><A NAME="LINFS-KNFS"></A>Issue the <B>knfs</B> command to associate your AFS
94 tokens with your UNIX UID on the NFS client machine where you are
95 working. This enables the Cache Manager on the translator machine to
96 use the tokens properly when you access AFS from the NFS client
97 machine. 
98 <P>If your NFS client machine is a system type for which AFS defines a system
99 name, it can make sense to add the <B>-sysname</B> argument. This
100 argument helps the Cache Manager access binaries specific to your NFS client
101 machine, if your system administrator has used the <I>@sys</I> variable in
102 pathnames. Ask your system administrator if this argument is useful for
103 you.
104 <A NAME="IDX1142"></A>
105 <A NAME="IDX1143"></A>
106 <PRE>   % <B>knfs</B> &lt;<VAR>host&nbsp;name</VAR>> [&lt;<VAR>user&nbsp;ID&nbsp;(decimal)</VAR>>]  \
107           [<B>-sysname</B> &lt;<VAR>host's '@sys' value</VAR>>]
108 </PRE> 
109 <P>where 
110 <DL>
111 <P><DT><B><VAR>host name</VAR>
112 </B><DD>Specifies the fully-qualified hostname of your NFS client machine (such as
113 <B></B>).
114 <P><DT><B><VAR>user ID</VAR>
115 </B><DD>Specifies your UNIX UID or equivalent (not your username) on the NFS
116 client machine. If your system administrator has followed the
117 conventional practice, then your UNIX and AFS UIDs are the same. If you
118 do not know your local UID on the NFS machine, ask your system administrator
119 for assistance. Your system administrator can also explain the issues
120 you need to be aware of if your two UIDs do not match, or if you omit this
121 argument.
122 <P><DT><B>-sysname
123 </B><DD>Specifies your NFS client machine's system type name.
124 </DL>
125 <P><LI><A NAME="LINFS-LOGOUT"></A>(<B>Optional</B>) Log out from the translator machine,
126 but do not unauthenticate.
127 <P><LI>Work on the NFS client machine, accessing AFS as necessary.
128 <P><LI>When you are finished accessing AFS, issue the <B>knfs</B> command on
129 the translator machine again. Provide the same <VAR>host name</VAR> and
130 <VAR>user ID</VAR> arguments as in Step <A HREF="#LINFS-KNFS">4</A>, and add the <B>-unlog</B> flag to destroy your
131 tokens. If you logged out from the translator machine in Step <A HREF="#LINFS-LOGOUT">5</A>, then you must first reestablish a connection to the
132 translator machine as in Step <A HREF="#LINFS-TELNET">2</A>. 
133 <PRE>   % <B>knfs</B> &lt;<VAR>host&nbsp;name</VAR>> [&lt;<VAR>user&nbsp;ID&nbsp;(decimal)</VAR>>] <B>-unlog</B>
134 </PRE>
135 </OL>
136 <HR><H2><A NAME="HDRWQ84" HREF="auusg002.htm#ToC_163">Troubleshooting the NFS/AFS Translator</A></H2>
137 <P>Acceptable performance by the NFS/AFS translator depends for
138 the most part on NFS. Sometimes, problems that appear to be AFS file
139 server outages, broken connections, or inaccessible files are actually caused
140 by NFS outages.
141 <P>This section describes some common problems and their possible
142 causes. If other problems arise, contact your system administrator, who
143 can ask the AFS Product Support group for assistance if necessary.
144 <TABLE><TR><TD ALIGN="LEFT" VALIGN="TOP"><B>Note:</B></TD><TD ALIGN="LEFT" VALIGN="TOP">To avoid degrading AFS performance, the Cache Manager on the translator
145 machine does not immediately send changes made on NFS client machines to the
146 File Server. Instead, it checks every 60 seconds for such changes and
147 sends them then. It can take longer for changes made on an NFS client
148 machine to be saved than for changes made on an AFS client machine. The
149 save operation must complete before the changes are visible on NFS client
150 machines that are using a different translator machine or on AFS client
151 machines.
152 </TD></TR></TABLE>
153 <P><H3><A NAME="HDRWQ85" HREF="auusg002.htm#ToC_164">Your NFS Client Machine is Frozen</A></H3>
154 <P>If your system administrator has used the recommended options
155 when creating an NFS mount to an NFS/AFS translator machine, then the mount is
156 both <I>hard</I> and <I>interruptible</I>:
157 <UL>
158 <P><LI>A hard mount means that the NFS client retries its requests if it does not
159 receive a response within the expected time frame. This is useful
160 because requests have to pass through both the NFS and AFS client software,
161 which can sometimes take longer than the NFS client expects. However,
162 it means that if the NFS/AFS translator machine actually becomes inaccessible,
163 your NFS client machine can become inoperative (<I>freeze</I> or
164 <I>hang</I>).
165 <P><LI>If the NFS mount is interruptible, then in the case of an NFS/AFS
166 translator machine outage you can press &lt;<B>Ctrl-c</B>> or another
167 interrupt signal to halt the NFS client's repeated attempts to access
168 AFS. You can then continue to work locally, or can NFS-mount another
169 translator machine. If the NFS mount is not interruptible, you must
170 actually remove the mount to the inaccessible translator machine.
171 </UL>
172 <P><H3><A NAME="Header_165" HREF="auusg002.htm#ToC_165">NFS/AFS Translator Reboots</A></H3>
173 <P>If you have authenticated to AFS and your translator machine reboots,
174 you must issue the <B>klog</B> command (and <B>knfs</B> command, if
175 appropriate) to reauthenticate. If you used the <B>knfs</B>
176 command's <B>-sysname</B> argument to define your NFS client
177 machine's system name, use it again.
178 <P><H3><A NAME="Header_166" HREF="auusg002.htm#ToC_166">System Error Messages</A></H3>
179 <P>This section explains possible meanings for NFS error messages you
180 receive while accessing AFS filespace.
181 <P><TT>stale NFS client</TT>
182 <P><TT>Getpwd: can't read</TT>
183 <P>Both messages possibly means that your translator machine was rebooted and
184 cannot determine the pathname to the current working directory. To
185 reestablish the path, change directory and specify the complete pathname
186 starting with <B>/afs</B>.
187 <P><TT>NFS server <VAR>translator_machine</VAR> is not responding still
188 trying</TT>.
189 <P>The NFS client is not getting a response from the NFS/AFS translator
190 machine. If the NFS mount to the translator machine is a hard mount,
191 your NFS client continues retrying the request until it gets a response (see <A HREF="#HDRWQ85">Your NFS Client Machine is Frozen</A>). If the NFS mount to the translator machine is a
192 soft mount, the NFS client stops retrying after a certain number of attempts
193 (three by default).
194 <HR><P ALIGN="center"> <A HREF="../index.htm"><IMG SRC="../books.gif" BORDER="0" ALT="[Return to Library]"></A> <A HREF="auusg002.htm#ToC"><IMG SRC="../toc.gif" BORDER="0" ALT="[Contents]"></A> <A HREF="auusg009.htm"><IMG SRC="../prev.gif" BORDER="0" ALT="[Previous Topic]"></A> <A HREF="#Top_Of_Page"><IMG SRC="../top.gif" BORDER="0" ALT="[Top of Topic]"></A> <A HREF="auusg011.htm"><IMG SRC="../next.gif" BORDER="0" ALT="[Next Topic]"></A> <A HREF="auusg013.htm#HDRINDEX"><IMG SRC="../index.gif" BORDER="0" ALT="[Index]"></A> <P> 
195 <!-- Begin Footer Records  ========================================== -->
196 <P><HR><B> 
197 <br>&#169; <A HREF="">IBM Corporation 2000.</A>  All Rights Reserved 
198 </B> 
199 <!-- End Footer Records  ============================================ -->
200 <A NAME="Bot_Of_Page"></A>
201 </BODY></HTML>