Commit | Line | Data |
---|---|---|
805e021f CE |
1 | <?xml version="1.0" encoding="UTF-8"?> |
2 | <chapter id="HDRWQ20"> | |
3 | <title>Using OpenAFS</title> | |
4 | ||
5 | <para>This chapter explains how to perform four basic AFS tasks: logging in and authenticating with AFS, ending an AFS session, | |
6 | accessing the AFS filespace, and changing your password.</para> | |
7 | ||
8 | <sect1 id="HDRWQ21"> | |
9 | <title>Logging in and Authenticating with AFS</title> | |
10 | ||
11 | <para>To access the AFS filespace as an authenticated user, you must both log into an AFS client machine's local (UNIX) file | |
12 | system and authenticate with AFS. When you log in, you establish your local system identity. When you authenticate, you prove | |
13 | your identity to AFS and obtain a token, which your Cache Manager uses to prove your authenticated status to the AFS server | |
14 | processes it contacts on your behalf. Users who are not authenticated (who do not have a token) have limited access to AFS | |
15 | directories and files.</para> | |
16 | ||
17 | <sect2 id="HDRWQ22"> | |
18 | <title>Logging In</title> | |
19 | ||
20 | <indexterm><primary>logging in</primary></indexterm> | |
21 | ||
22 | <indexterm><primary>login utility</primary></indexterm> | |
23 | ||
24 | <indexterm><primary>commands</primary><secondary>login</secondary></indexterm> | |
25 | ||
26 | <para>On machines that use AFS enabled PAM modules with their login utility, you log in and authenticate in one step. On machines that do not use | |
27 | an AFS enabled PAM modules, you log in and authenticate in separate steps. To determine which type of login configuration your | |
28 | machine uses, you can check for AFS tokens after logging in, or ask your system administrator, who can also tell you about any | |
29 | differences between your login procedure and the two methods described here.</para> | |
30 | </sect2> | |
31 | ||
32 | <sect2 id="Header_33"> | |
33 | <title>To Log In Using an AFS enabled PAM module</title> | |
34 | ||
35 | <para>Provide your username at the <computeroutput>login:</computeroutput> prompt that appears when you establish a new | |
36 | connection to a machine. Then provide your password at the <computeroutput>Password:</computeroutput> prompt as shown in the | |
37 | following example. (Your password does not echo visibly on the screen.)</para> | |
38 | ||
39 | <programlisting> | |
40 | login: <replaceable>username</replaceable> | |
41 | Password: <replaceable>password</replaceable> | |
42 | </programlisting> | |
43 | ||
44 | <para>If you are not sure which type of login utility is running on your machine, it is best to issue the <emphasis | |
45 | role="bold">tokens</emphasis> command to check if you are authenticated; for instructions, see <link linkend="HDRWQ30">To | |
46 | Display Your Tokens</link>. If you do not have tokens, issue the <emphasis role="bold">kinit/aklog</emphasis> command pair as described in | |
47 | <link linkend="HDRWQ29">To Authenticate with AFS</link>.</para> | |
48 | </sect2> | |
49 | ||
50 | <sect2 id="HDRWQ23"> | |
51 | <title>To Log In Using a Two-Step Login Procedure</title> | |
52 | ||
53 | <para>If your machine does not use AFS enabled PAM modules, you must perform a two-step procedure: | |
54 | ||
55 | <orderedlist> | |
56 | <listitem> | |
57 | <para>Log in to your client machine's local file system by providing a user name and password at the <emphasis | |
58 | role="bold">login</emphasis> program's prompts.</para> | |
59 | </listitem> | |
60 | ||
61 | <listitem> | |
62 | <para>Issue the <emphasis role="bold">kinit</emphasis> command to authenticate with kerberos and | |
63 | obtain a ticket granting ticket ( or TGT). | |
64 | ||
65 | <programlisting> | |
66 | % <emphasis role="bold">kinit</emphasis> | |
67 | Password: <replaceable>your_Kerberos_password</replaceable> | |
68 | </programlisting></para> | |
69 | </listitem> | |
70 | <listitem> | |
71 | <para>Issue the <emphasis role="bold">aklog</emphasis> command to obtain an AFS token using your TGT. | |
72 | <programlisting> | |
73 | ||
74 | % <emphasis role="bold">aklog</emphasis> | |
75 | ||
76 | </programlisting> | |
77 | </para> | |
78 | <para>On systems with an AFS enabled kinit program, the kinit program can be configured to run the aklog | |
79 | program for you by default, but running it again has no negative side effects.</para> | |
80 | ||
81 | </listitem> | |
82 | </orderedlist> | |
83 | </para> | |
84 | <note> | |
85 | <para>If your machine uses a two-step login procedure, you can choose to use different passwords for logging in and | |
86 | authenticating.</para> | |
87 | </note> | |
88 | </sect2> | |
89 | ||
90 | <sect2 id="HDRWQ24"> | |
91 | <title>Authenticating with AFS</title> | |
92 | ||
93 | <para>To work most effectively in the AFS filespace, you must authenticate with AFS. When you do, your Cache Manager is given | |
94 | a token as proof of your authenticated status. It uses your token when requesting services from AFS servers, which accept the | |
95 | token as proof of your authenticated status. If you do not have a token, AFS servers consider you to be the <emphasis | |
96 | role="bold">anonymous</emphasis> user and your access to AFS filespace is limited: you have only the ACL permissions granted | |
97 | to the <emphasis role="bold">system:anyuser</emphasis> group. <indexterm><primary>authentication</primary><secondary>tokens as proof</secondary></indexterm> <indexterm><primary>tokens</primary><secondary>as proof of authentication</secondary></indexterm> <indexterm><primary>Cache Manager</primary><secondary>tokens, use of</secondary></indexterm></para> | |
98 | ||
99 | <para>You can obtain new tokens (reauthenticate) at any time, even after using an AFS enabled login utility, which logs you | |
100 | in and authenticates you in one step. Issue the <emphasis role="bold">aklog</emphasis> command as described in <link | |
101 | linkend="HDRWQ29">To Authenticate with AFS</link>. If your kerberos TGT has expired, you will also need to use the <emphasis role="bold">kinit</emphasis> command.</para> | |
102 | ||
103 | <sect3 id="HDRWQ25"> | |
104 | <title>Protecting Your Tokens with a PAG</title> | |
105 | ||
106 | <para>To make your access to AFS as secure as possible, it is best to associate your tokens with a unique identification | |
107 | number called a <emphasis>PAG</emphasis> (for <emphasis>process authentication group</emphasis>). | |
108 | <indexterm><primary>PAG</primary></indexterm> | |
109 | <indexterm><primary>process authentication group (PAG)</primary></indexterm> | |
110 | <indexterm><primary>setpag argument to klog command</primary></indexterm> | |
111 | AFS enabled login utilities automatically create a PAG and associate the new | |
112 | token with it. To create a PAG when you use the two-step login procedure, include the <emphasis role="bold">aklog</emphasis> | |
113 | command's <emphasis role="bold">-setpag</emphasis> flag. If you do not use this flag, your tokens are associated with your | |
114 | UNIX UID number instead. This type of association has two potential drawbacks: | |
115 | ||
116 | <itemizedlist> | |
117 | <listitem> | |
118 | <para>Anyone who can assume your local UNIX identity can use your tokens. The local superuser <emphasis | |
119 | role="bold">root</emphasis> can always use the UNIX <emphasis role="bold">su</emphasis> command to assume your UNIX UID, | |
120 | even without knowing your password.</para> | |
121 | </listitem> | |
122 | ||
123 | <listitem> | |
124 | <para>In some environments, certain programs cannot use your tokens even when it is appropriate for them to do so. For | |
125 | example, printing commands such as <emphasis role="bold">lp</emphasis> or <emphasis role="bold">lpr</emphasis> possibly | |
126 | cannot access the files you want to print, because they cannot use your tokens.</para> | |
127 | </listitem> | |
128 | </itemizedlist> | |
129 | </para> | |
130 | </sect3> | |
131 | ||
132 | <sect3 id="HDRWQ26"> | |
133 | <title>Obtaining Tokens For Foreign Cells</title> | |
134 | ||
135 | <indexterm><primary>authentication</primary><secondary>in a foreign cell</secondary></indexterm> | |
136 | ||
137 | <para>A token is valid only in one cell (the cell whose AFS authentication service issued it). The AFS server processes in | |
138 | any other cell consider you to be the <emphasis role="bold">anonymous</emphasis> user unless you have an account in the cell | |
139 | and authenticate with its AFS authentication service.</para> | |
140 | ||
141 | <para>To obtain tokens in a foreign cell, you must first obtain a kerberos TGT for the realm used to authenticate for that cell. | |
142 | Unfortunately, while AFS tokens have support for multi-realm credentials, most kerberos implementations don't handle this as | |
143 | gracefully. You can control where kerberos stores it's credentials by using the ENV variable <emphasis role="bold">KRB5CCNAME</emphasis>. | |
144 | If you want to get a token for a foreign cell, without destroying the kerberos credentials of your current session, you | |
145 | need to follow this sequence of commands. | |
146 | <programlisting> | |
147 | ||
148 | env KRB5CCNAME=/tmp/test.ticket kinit user@REMOTE.REALM | |
149 | env KRB5CCNAME=/tmp/test.ticket aklog -c remote.realm -k REMOTE.REALM | |
150 | ||
151 | </programlisting> | |
152 | It's probably a good idea to remove the TGT from the remote realm after doing this. For kerberos implementations that don't use | |
153 | file based ticket caches ( Mac OS X, Windows), you will need to use the graphic kerberos ticket manager included in the OS to | |
154 | switch kerberos identities. | |
155 | You can have tokens for your home cell and one or more foreign cells at the same | |
156 | time.</para> | |
157 | </sect3> | |
158 | ||
159 | <sect3 id="HDRWQ27"> | |
160 | <title>The One-Token-Per-Cell Rule</title> | |
161 | ||
162 | <para>You can have only one token per cell for each PAG you have obtained on a client machine. If you already have a token | |
163 | for a particular cell and issue the <emphasis role="bold">aklog</emphasis> command, the new token overwrites the existing | |
164 | one. Getting a new token is useful if your current token is almost expired but you want to continue accessing AFS files. For | |
165 | a discussion of token expiration, see <link linkend="HDRWQ28">Token Lifetime</link>.</para> | |
166 | ||
167 | <para>To obtain a second token for the same cell, you need to run a process in a different PAG. OpenAFS provides the <emphasis role="bold">pagsh</emphasis> command to start a new shell in with a different PAG. You will then need to authenticate as described in <link | |
168 | linkend="HDRWQ29">To Authenticate with AFS</link>. | |
169 | </para> | |
170 | </sect3> | |
171 | ||
172 | <sect3 id="Header_39"> | |
173 | <title>Obtaining Tokens as Another User</title> | |
174 | ||
175 | <indexterm><primary>authentication</primary><secondary>as another user</secondary></indexterm> | |
176 | ||
177 | <para>You can authenticate as another username if you know the associated password. (It is, of course, unethical to use | |
178 | someone else's tokens without permission.) If you use the <emphasis role="bold">kinit</emphasis> and | |
179 | <emphasis role="bold">aklog</emphasis> commands to authenticate as | |
180 | another Kerberos username and obtain an AFS token, you retain your own local (UNIX) identity, but the AFS | |
181 | server processes recognize you as the other user. The new token replaces any token you already have for the | |
182 | relevant cell (for the reason described in <link | |
183 | linkend="HDRWQ27">The One-Token-Per-Cell Rule</link>).</para> | |
184 | </sect3> | |
185 | ||
186 | <sect3 id="HDRWQ28"> | |
187 | <title>Token Lifetime</title> | |
188 | ||
189 | <indexterm><primary>tokens</primary><secondary>lifetime</secondary></indexterm> | |
190 | ||
191 | <indexterm><primary>lifetime of tokens</primary></indexterm> | |
192 | ||
193 | <para>Tokens and Kerberos TGT's have a limited lifetime. To determine when your tokens expire, issue the <emphasis | |
194 | role="bold">tokens</emphasis> command as described in <link linkend="HDRWQ30">To Display Your Tokens</link>. If you are ever | |
195 | unable to access AFS in a way that you normally can, issuing the <emphasis role="bold">tokens</emphasis> command tells you | |
196 | whether an expired token is a possible reason.</para> | |
197 | ||
198 | <para>Your cell's kerberos administrators set the default lifetime of your kerberos TGT. The AFS authentication service never grants a token | |
199 | lifetime longer than the current TGT lifetime, but you can request a TGT with a shorter lifetime. See the <emphasis | |
200 | role="bold">kinit</emphasis> man page on your system to learn how to use | |
201 | its <emphasis role="bold">-lifetime</emphasis> argument for this purpose.</para> | |
202 | </sect3> | |
203 | ||
204 | </sect2> | |
205 | ||
206 | <sect2 id="HDRWQ29"> | |
207 | <title>To Authenticate with AFS</title> | |
208 | ||
209 | <indexterm><primary>aklog command</primary></indexterm> | |
210 | <indexterm><primary>kinit command</primary></indexterm> | |
211 | <indexterm><primary>commands</primary><secondary>aklog</secondary></indexterm> | |
212 | <indexterm><primary>commands</primary><secondary>kinit</secondary></indexterm> | |
213 | <indexterm><primary>tokens</primary><secondary>getting</secondary></indexterm> | |
214 | ||
215 | <para>If your machine is not using an AFS enabled login utility, you must authenticate after login by issuing the <emphasis | |
216 | role="bold">kinit</emphasis> command and then use <emphasis role="bold">aklog</emphasis> to obtain a token. You can also | |
217 | issue these commands at any time to obtain a token with a later expiration | |
218 | date than your current token.</para> | |
219 | ||
220 | <programlisting> | |
221 | % <emphasis role="bold">kinit</emphasis> [<emphasis role="bold">userid@KRB5.REALM</emphasis>] | |
222 | Password: <replaceable>your_kerberos_password</replaceable> | |
223 | </programlisting> | |
224 | ||
225 | <para>where | |
226 | ||
227 | <variablelist> | |
228 | <varlistentry> | |
229 | <term><emphasis role="bold">userid@KRB5.REALM</emphasis></term> | |
230 | ||
231 | <listitem> | |
232 | <para>is the kerberos userid and realm that you want to get a TGT from. If the machine is properly configured | |
233 | for your local cell and realm, you should not need to specify the kerberos identity.</para> | |
234 | </listitem> | |
235 | </varlistentry> | |
236 | ||
237 | </variablelist> | |
238 | </para> | |
239 | ||
240 | <para>Your password does not echo visibly appear on the screen. When the command shell prompt returns, | |
241 | you have a kerberos TGT. You then need to use the <emphasis role="bold">aklog</emphasis> command to | |
242 | obtain an AFS token.</para> | |
243 | ||
244 | <programlisting> | |
245 | % <emphasis role="bold">aklog</emphasis> [<emphasis role="bold">-cell afs.cell.name</emphasis>] [<emphasis role="bold">-k KRB5.REALM</emphasis>] | |
246 | </programlisting> | |
247 | ||
248 | <para>where | |
249 | ||
250 | <variablelist> | |
251 | <varlistentry> | |
252 | <term><emphasis role="bold">KRB5.REALM</emphasis></term> | |
253 | ||
254 | <listitem> | |
255 | <para>is the kerberos realm used to authenticate the AFS cell.</para> | |
256 | </listitem> | |
257 | </varlistentry> | |
258 | ||
259 | <varlistentry> | |
260 | <term><emphasis role="bold">afs.cell.name</emphasis></term> | |
261 | ||
262 | <listitem> | |
263 | <para>is the AFS cell for which you want a token.</para> | |
264 | </listitem> | |
265 | </varlistentry> | |
266 | ||
267 | </variablelist> | |
268 | </para> | |
269 | ||
270 | <para>You can use the <emphasis role="bold">tokens</emphasis> command to verify that you are authenticated, | |
271 | as described in the following section.</para> | |
272 | ||
273 | <note id="note.a.note.on.kerberos.realms.and.afs.cellnames"> | |
274 | <title>A Note on Kerberos Realms and AFS Cellnames</title> | |
275 | <para>These are two things that are often the same, but each has it's own distinct rules. | |
276 | By convention, kerberos realms are always in UPPER CASE and afs cellnames are in lower case. | |
277 | Thus username@KRB5.REALM is the kerberos identity used for the AFS cell krb5.realm. There is | |
278 | no restriction that the cell and realm names must match, but most sites are set up that way | |
279 | to avoid confusion. In a well configured system you should never need worry about this until | |
280 | you need to access remote realms/cells.</para> | |
281 | </note> | |
282 | ||
283 | </sect2> | |
284 | ||
285 | <sect2 id="HDRWQ30"> | |
286 | <title>To Display Your Tokens</title> | |
287 | ||
288 | <indexterm><primary>checking</primary><secondary>tokens</secondary></indexterm> | |
289 | ||
290 | <indexterm><primary>commands</primary><secondary>tokens</secondary></indexterm> | |
291 | ||
292 | <indexterm><primary>tokens</primary><secondary>command</secondary></indexterm> | |
293 | ||
294 | <indexterm><primary>tokens</primary><secondary>displaying</secondary></indexterm> | |
295 | ||
296 | <indexterm><primary>displaying</primary><secondary>tokens</secondary></indexterm> | |
297 | ||
298 | <para>Use the <emphasis role="bold">tokens</emphasis> command to display your tokens.</para> | |
299 | ||
300 | <programlisting> | |
301 | % <emphasis role="bold">tokens</emphasis> | |
302 | </programlisting> | |
303 | ||
304 | <para>The following output indicates that you have no tokens:</para> | |
305 | ||
306 | <programlisting> | |
307 | Tokens held by the Cache Manager: | |
308 | --End of list-- | |
309 | </programlisting> | |
310 | ||
311 | <para>If you have one or more tokens, the output looks something like the following example, in which the tokens for AFS UID | |
312 | 1022 in the <emphasis role="bold">example.com</emphasis> cell expire on August 3 at 2:35 p.m. The tokens for AFS UID 9554 in the | |
313 | <emphasis role="bold">example.org</emphasis> cell expire on August 4 at 1:02 a.m.</para> | |
314 | ||
315 | <programlisting> | |
316 | Tokens held by the Cache Manager: | |
317 | User's (AFS ID 1022) tokens for afs@example.com [Expires Aug 3 14:35] | |
318 | User's (AFS ID 9554) tokens for afs@example.org [Expires Aug 4 1:02] | |
319 | --End of list-- | |
320 | </programlisting> | |
321 | </sect2> | |
322 | ||
323 | <sect2 id="Header_44"> | |
324 | <title>Example: Authenticating in the Local Cell</title> | |
325 | ||
326 | <indexterm><primary>examples</primary><secondary>authenticating</secondary></indexterm> | |
327 | ||
328 | <para>Suppose that user <emphasis role="bold">terry</emphasis> cannot save a file. He uses the <emphasis | |
329 | role="bold">tokens</emphasis> command and finds that his tokens have expired. He reauthenticates in his local cell under his | |
330 | current identity by issuing the following commands:</para> | |
331 | ||
332 | <programlisting> | |
333 | % <emphasis role="bold">kinit</emphasis> | |
334 | Password: <replaceable>terry's_password</replaceable> | |
335 | % <emphasis role="bold">aklog</emphasis> | |
336 | ||
337 | </programlisting> | |
338 | ||
339 | <para>The he issues the <emphasis role="bold">tokens</emphasis> command to make sure he is authenticated.</para> | |
340 | ||
341 | <programlisting> | |
342 | % <emphasis role="bold">tokens</emphasis> | |
343 | Tokens held by the Cache Manager: | |
344 | User's (AFS ID 4562) tokens for afs@example.com [Expires Jun 22 14:35] | |
345 | --End of list-- | |
346 | </programlisting> | |
347 | </sect2> | |
348 | ||
349 | <sect2 id="Header_45"> | |
350 | <title>Example: Authenticating as a Another User</title> | |
351 | ||
352 | <indexterm><primary>examples</primary><secondary>authenticating as another user</secondary></indexterm> | |
353 | ||
354 | <para>Now <emphasis role="bold">terry</emphasis> authenticates in his local cell as another user, <emphasis | |
355 | role="bold">pat</emphasis>. The new token replaces <emphasis role="bold">terry</emphasis>'s existing token, because the Cache | |
356 | Manager can store only one token per cell per login session on a machine.</para> | |
357 | ||
358 | <programlisting> | |
359 | % <emphasis role="bold">kinit pat</emphasis> | |
360 | Password: <replaceable>pat's_password</replaceable> | |
361 | % <emphasis role="bold">aklog</emphasis> | |
362 | % <emphasis role="bold">tokens</emphasis> | |
363 | Tokens held by the Cache Manager: | |
364 | User's (AFS ID 4278) tokens for afs@example.com [Expires Jun 23 9:46] | |
365 | --End of list-- | |
366 | </programlisting> | |
367 | </sect2> | |
368 | ||
369 | <sect2 id="Header_46"> | |
370 | <title>Example: Authenticating in a Foreign Cell</title> | |
371 | ||
372 | <indexterm><primary>examples</primary><secondary>authenticating in a foreign cell</secondary></indexterm> | |
373 | ||
374 | <para>Now <emphasis role="bold">terry</emphasis> authenticates in the <emphasis role="bold">example.org</emphasis> cell where | |
375 | his account is called <emphasis role="bold">ts09</emphasis>.</para> | |
376 | ||
377 | <programlisting> | |
378 | % <emphasis role="bold">env KRB5CCNAME=/tmp/temp.tgt kinit ts09@EXAMPLE.ORG</emphasis> | |
379 | Password: <replaceable>ts09's_password</replaceable> | |
380 | % <emphasis role="bold">env KRB5CCNAME=/tmp/temp.tgt aklog ts09 -cell example.org</emphasis> | |
381 | ||
382 | % <emphasis role="bold">tokens</emphasis> | |
383 | Tokens held by the Cache Manager: | |
384 | User's (AFS ID 4562) tokens for afs@example.com [Expires Jun 22 14:35] | |
385 | User's (AFS ID 8346) tokens for afs@example.org [Expires Jun 23 1:02] | |
386 | --End of list-- | |
387 | </programlisting> | |
388 | </sect2> | |
389 | </sect1> | |
390 | ||
391 | <sect1 id="HDRWQ33"> | |
392 | <title>Exiting an AFS Session</title> | |
393 | ||
394 | <indexterm><primary>tokens</primary><secondary>destroying</secondary></indexterm> | |
395 | ||
396 | <indexterm><primary>unauthenticating</primary></indexterm> | |
397 | ||
398 | <indexterm><primary>exiting an AFS session</primary></indexterm> | |
399 | ||
400 | <indexterm><primary>logging out</primary></indexterm> | |
401 | ||
402 | <indexterm><primary>quitting an AFS session</primary></indexterm> | |
403 | ||
404 | <para>Because logging in and authenticating with AFS are distinct operations, you must both logout and unauthenticate (issue the | |
405 | <emphasis role="bold">unlog</emphasis> command to discard your tokens) when exiting an AFS session. Simply logging out does not | |
406 | necessarily destroy your tokens.</para> | |
407 | ||
408 | <para>You can use the <emphasis role="bold">unlog</emphasis> command any time you want to unauthenticate, not just when logging | |
409 | out. For instance, it is a good practice to unauthenticate before leaving your machine unattended, to prevent other users from | |
410 | using your tokens during your absence. When you return to your machine, issue the <emphasis role="bold">aklog</emphasis> command | |
411 | to reauthenticate, as described in <link linkend="HDRWQ29">To Authenticate with AFS</link>.</para> | |
412 | ||
413 | <para>Do not issue the <emphasis role="bold">unlog</emphasis> command when you are running jobs that take a long time to | |
414 | complete, even if you are logging out. Such processes must have a token during the entire time they need authenticated access to | |
415 | AFS.</para> | |
416 | ||
417 | <para>If you have tokens from multiple cells and want to discard only some of them, include the <emphasis | |
418 | role="bold">unlog</emphasis> command's <emphasis role="bold">-cell</emphasis> argument.</para> | |
419 | ||
420 | <sect2 id="Header_50"> | |
421 | <title>To Discard Tokens</title> | |
422 | ||
423 | <indexterm><primary>commands</primary><secondary>unlog</secondary></indexterm> | |
424 | ||
425 | <indexterm><primary>unlog command</primary></indexterm> | |
426 | ||
427 | <para>Issue the <emphasis role="bold">unlog</emphasis> command to discard your tokens:</para> | |
428 | ||
429 | <programlisting> | |
430 | % <emphasis role="bold">unlog -cell</emphasis> <<replaceable>cell name</replaceable>><superscript>+</superscript> | |
431 | </programlisting> | |
432 | ||
433 | <para>Omit the <emphasis role="bold">-cell</emphasis> argument to discard all of your tokens, or use it to name each cell for | |
434 | which to discard tokens. It is best to provide the full name of each cell (such as <emphasis role="bold">example.org</emphasis> | |
435 | or <emphasis role="bold">example.com</emphasis>).</para> | |
436 | ||
437 | <para>You can issue the <emphasis role="bold">tokens</emphasis> command to verify that your tokens were destroyed, as in the | |
438 | following example.</para> | |
439 | ||
440 | <programlisting> | |
441 | % <emphasis role="bold">tokens</emphasis> | |
442 | Tokens held by the Cache Manager: | |
443 | --End of list-- | |
444 | </programlisting> | |
445 | </sect2> | |
446 | ||
447 | <sect2 id="Header_51"> | |
448 | <title>Example: Unauthenticating from a Specific Cell</title> | |
449 | ||
450 | <indexterm><primary>examples</primary><secondary>unauthenticating from selected cells</secondary></indexterm> | |
451 | ||
452 | <para>In the following example, a user has tokens in both the <emphasis role="bold">accounting</emphasis> and <emphasis | |
453 | role="bold">marketing</emphasis> cells at her company. She discards the token for the <emphasis | |
454 | role="bold">acctg.example.com</emphasis> cell but keeps the token for the <emphasis role="bold">mktg.example.com</emphasis> | |
455 | cell.</para> | |
456 | ||
457 | <programlisting> | |
458 | % <emphasis role="bold">tokens</emphasis> | |
459 | Tokens held by the Cache Manager: | |
460 | User's (AFS ID 35) tokens for afs@acctg.example.com [Expires Nov 10 22:30] | |
461 | User's (AFS ID 674) tokens for afs@mktg.example.com [Expires Nov 10 18:44] | |
462 | --End of list-- | |
463 | % <emphasis role="bold">unlog -cell acctg.example.com</emphasis> | |
464 | % <emphasis role="bold">tokens</emphasis> | |
465 | Tokens held by the Cache Manager: | |
466 | User's (AFS ID 674) tokens for afs@mktg.example.com [Expires Nov 10 18:44] | |
467 | --End of list-- | |
468 | </programlisting> | |
469 | </sect2> | |
470 | ||
471 | <sect2 id="Header_52"> | |
472 | <title>To Log Out</title> | |
473 | ||
474 | <para>After you have unauthenticated, log out by issuing the command appropriate for your machine type, which is possibly one | |
475 | of the following.</para> | |
476 | ||
477 | <programlisting> | |
478 | % <emphasis role="bold">logout</emphasis> | |
479 | </programlisting> | |
480 | ||
481 | <para>or</para> | |
482 | ||
483 | <programlisting> | |
484 | % <emphasis role="bold">exit</emphasis> | |
485 | </programlisting> | |
486 | ||
487 | <para>or</para> | |
488 | ||
489 | <programlisting> | |
490 | % <<emphasis role="bold">Ctrl-d</emphasis>> | |
491 | </programlisting> | |
492 | </sect2> | |
493 | </sect1> | |
494 | ||
495 | <sect1 id="HDRWQ34"> | |
496 | <title>Accessing the AFS Filespace</title> | |
497 | ||
498 | <indexterm><primary>files</primary><secondary>accessing AFS</secondary></indexterm> | |
499 | ||
500 | <indexterm><primary>directories</primary><secondary>accessing AFS</secondary></indexterm> | |
501 | ||
502 | <para>While you are logged in and authenticated, you can access files in AFS just as you do in the UNIX file system. The only | |
503 | difference is that you can access potentially many more files. Just as in the UNIX file system, you can only access those files | |
504 | for which you have permission. AFS uses access control lists (ACLs) to control access, as described in <link | |
505 | linkend="HDRWQ44">Protecting Your Directories and Files</link>.</para> | |
506 | ||
507 | <sect2 id="Header_54"> | |
508 | <title>AFS Pathnames</title> | |
509 | ||
510 | <indexterm><primary>pathnames</primary></indexterm> | |
511 | ||
512 | <para>AFS pathnames look very similar to UNIX file system names. The main difference is that every AFS pathname begins with | |
513 | the AFS root directory, which is called <emphasis role="bold">/afs</emphasis> by convention. Having <emphasis | |
514 | role="bold">/afs</emphasis> at the top of every AFS cell's filespace links together their filespaces into a global filespace. | |
515 | <indexterm><primary>AFS</primary><secondary>accessing filespace</secondary></indexterm> <indexterm><primary>access to AFS filespace</primary><secondary>format of pathnames</secondary></indexterm> <indexterm><primary>afs (/afs) directory</primary><secondary>as root of AFS filespace</secondary></indexterm> <indexterm><primary>format of AFS pathnames</primary></indexterm></para> | |
516 | ||
517 | <para><emphasis role="bold">Note for Windows users:</emphasis> Windows uses a backslash ( <emphasis | |
518 | role="bold">\</emphasis> ) rather than a forward slash ( <emphasis role="bold">/</emphasis> ) to separate the | |
519 | elements in a pathname. Otherwise, your access to AFS filespace is much the same as for users working on UNIX machines.</para> | |
520 | ||
521 | <para>The second element in AFS pathnames is generally a cell's name. For example, the Example Corporation cell is called | |
522 | <emphasis role="bold">example.com</emphasis> and the pathname of every file in its filespace begins with the string <emphasis | |
523 | role="bold">/afs/example.com</emphasis>. Some cells also create a directory at the second level with a shortened name (such as | |
524 | <emphasis role="bold">example</emphasis> for <emphasis role="bold">example.com</emphasis> or <emphasis role="bold">testcell</emphasis> | |
525 | for <emphasis role="bold">testcell.example.org</emphasis>), to reduce the amount of typing necessary. Your system administrator can tell | |
526 | you if your cell's filespace includes shortened names like this. The rest of the pathname depends on how the cell's | |
527 | administrators organized its filespace.</para> | |
528 | ||
529 | <para>To access directories and files in AFS you must both specify the correct pathname and have the required permissions on | |
530 | the ACL that protects the directory and the files in it.</para> | |
531 | </sect2> | |
532 | ||
533 | <sect2 id="Header_55"> | |
534 | <title>Example: Displaying the Contents of Another User's Directory</title> | |
535 | ||
536 | <para>The user <emphasis role="bold">terry</emphasis> wants to look for a file belonging to another user, <emphasis | |
537 | role="bold">pat</emphasis>. He issues the <emphasis role="bold">ls</emphasis> command on the appropriate pathname.</para> | |
538 | ||
539 | <programlisting> | |
540 | % <emphasis role="bold">ls /afs/example.com/usr/pat/public</emphasis> | |
541 | doc/ directions/ | |
542 | guide/ jokes/ | |
543 | library/ | |
544 | </programlisting> | |
545 | </sect2> | |
546 | ||
547 | <sect2 id="HDRWQ35"> | |
548 | <title>Accessing Foreign Cells</title> | |
549 | ||
550 | <indexterm><primary>foreign cells</primary><secondary>accessing</secondary></indexterm> | |
551 | ||
552 | <indexterm><primary>system:anyuser group</primary><secondary>controlling access by foreign users</secondary></indexterm> | |
553 | ||
554 | <para>You can access files not only in your own cell, but in any AFS cell that you can reach via the network, regardless of | |
555 | geographical location. There are two additional requirements: | |
556 | ||
557 | <itemizedlist> | |
558 | <listitem> | |
559 | <para>Your Cache Manager's list of foreign cells must include the cell you want to access. Only the local superuser | |
560 | <emphasis role="bold">root</emphasis> can edit the list of cells, but anyone can display it. See <link | |
561 | linkend="HDRWQ42">Determining Access to Foreign Cells</link>.</para> | |
562 | </listitem> | |
563 | ||
564 | <listitem> | |
565 | <para>The ACL on the directory that houses the file, and on every parent directory in the pathname, must grant you the | |
566 | necessary permissions. The simplest way for the directory's owner to extend permission to foreign users is to put an entry | |
567 | for the <emphasis role="bold">system:anyuser</emphasis> group on the ACL.</para> | |
568 | ||
569 | <para>The alternative is for the foreign cell's administrator to create an account for you, essentially making you a local | |
570 | user in the cell. The directory's owner creates an ACL entry for you as for any other local user. To authenticate in the | |
571 | foreign cell, issue the <emphasis role="bold">aklog</emphasis> command with the <emphasis role="bold">-cell</emphasis> | |
572 | argument.</para> | |
573 | </listitem> | |
574 | </itemizedlist> | |
575 | </para> | |
576 | ||
577 | <para>For further discussion of directory and file protection, see <link linkend="HDRWQ44">Protecting Your Directories and | |
578 | Files</link>.</para> | |
579 | </sect2> | |
580 | </sect1> | |
581 | ||
582 | <sect1 id="HDRWQ36"> | |
583 | <title>Changing Your Password</title> | |
584 | ||
585 | <para>In cells that use an AFS and kerberos enabled login utility, the password is the same for both logging in and authenticating with AFS. | |
586 | In this case, generally you use a single command, <emphasis role="bold">kpasswd</emphasis>, to change the password. But this may vary from system to system, if in doubt contact your local system administrator.</para> | |
587 | ||
588 | <para>If your machine does not use an AFS and kerberos enabled login utility, there are separate passwords for logging into the local file | |
589 | system and authenticating with AFS. (The two passwords can be the same or different, at your discretion.) In this case, use the | |
590 | <emphasis role="bold">kpasswd</emphasis> command to change your Kerberos password and the UNIX <emphasis | |
591 | role="bold">passwd</emphasis> command to change your UNIX password.</para> | |
592 | ||
593 | </sect1> | |
594 | </chapter> |