doc/xml/UserGuide/auusg005.xml

   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>  &lt;<replaceable>cell name</replaceable>&gt;<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    % &lt;<emphasis role="bold">Ctrl-d</emphasis>&gt;
 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 (&nbsp;<emphasis
 518       role="bold">\</emphasis>&nbsp;) rather than a forward slash (&nbsp;<emphasis role="bold">/</emphasis>&nbsp;) 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>