Updating UserGuide with Kerberos v5 authentication
authorBooker Bense <bbense@slac.stanford.edu>
Fri, 5 Mar 2010 15:11:41 +0000 (10:11 -0500)
committerJeffrey Altman <jaltman@openafs.org>
Wed, 24 Mar 2010 04:17:00 +0000 (21:17 -0700)
This patchset contains updates to the OpenAFS UserGuide that
explains how to authentication OpenAFS using kinit/aklog
and uses language describing Kerberos outside the context
of the kaserver.  References to applications such as telnet
have been replaced with more modern equivalents such as ssh.

Change-Id: Ifae779b04a26beb9be9cf58b450958acdc477c06
Reviewed-on: http://gerrit.openafs.org/1521
Tested-by: Jeffrey Altman <jaltman@openafs.org>
Reviewed-by: Jeffrey Altman <jaltman@openafs.org>

doc/xml/UserGuide/auusg000.xml
doc/xml/UserGuide/auusg003.xml
doc/xml/UserGuide/auusg004.xml
doc/xml/UserGuide/auusg005.xml
doc/xml/UserGuide/auusg006.xml
doc/xml/UserGuide/auusg007.xml
doc/xml/UserGuide/auusg008.xml
doc/xml/UserGuide/auusg009.xml
doc/xml/UserGuide/auusg010.xml
doc/xml/UserGuide/auusg011.xml
doc/xml/UserGuide/auusg012.xml

index d1265d3..cbd0fd8 100644 (file)
@@ -34,6 +34,7 @@
 
         <revremark>First IBM Edition, Document Number GC09-4561-00</revremark>
        </revision>
+
     </revhistory>
 
     <abstract>
index 7204d8e..71c717a 100644 (file)
@@ -28,8 +28,8 @@
     <para><link linkend="HDRWQ2">An Introduction to OpenAFS</link> introduces the basic concepts and functions of AFS. To use AFS
     successfully, it is important to be familiar with the terms and concepts described in this chapter.</para>
 
-    <para><link linkend="HDRWQ20">Using OpenAFS</link> describes how to use AFS's basic features: how to log in and authenticate, unlog,
-    log out, access AFS files and directories in AFS, and change your password.</para>
+    <para><link linkend="HDRWQ20">Using OpenAFS</link> describes how to use AFS's basic features: how to log in and authenticate,
+    and access AFS files and directories in AFS.</para>
 
     <para><link linkend="HDRWQ38">Displaying Information about OpenAFS</link> describes how to display information about AFS volume
     quota and location, file server machine status, and the foreign cells you can access.</para>
index c992482..ee62696 100644 (file)
         </listitem>
 
         <listitem>
-          <para>On machines that do not use an AFS-modified login utility, you must perform two steps.
+          <para>On machines that do not use an AFS-modified login utility, you must perform three steps.
 
           <orderedlist>
             <listitem>
             </listitem>
 
             <listitem>
-              <para>Issue the <emphasis role="bold">klog</emphasis> command with the <emphasis role="bold">-setpag</emphasis>
-              argument to authenticate with AFS and get your token.</para>
+              <para>Issue the <emphasis role="bold">kinit</emphasis> command to obtain a kerberos Ticket Granting Ticket or
+              <emphasis role="bold">TGT</emphasis>. If the kinit is compiled with AFS support, it may automatically get a
+               token for you. However to ensure that you get an afs token, you will need to run a second command.</para>
             </listitem>
+                       <listitem>
+              <para>OpenAFS provides the <emphasis role="bold">aklog</emphasis> command to allow you to obtain a token,
+              or AFS service ticket using your kerberos TGT. A kinit with AFS support will run this as part of it's execution,
+                         but if you issue the aklog command that will ensure you have an AFS token.</para>
+            </listitem>
+
           </orderedlist>
 </para>
         </listitem>
       <para>Your system administrator can tell you whether your machine uses an AFS-modified login utility or not. Then see the
       login instructions in <link linkend="HDRWQ21">Logging in and Authenticating with AFS</link>.</para>
 
-      <para>AFS authentication passwords are stored in special AFS database, rather than in the local password file (<emphasis
+      <para>AFS uses the kerberos authentication protocol, rather than storing passwords in the local password file (<emphasis
       role="bold">/etc/passwd</emphasis> or equivalent). If your machine uses an AFS-modified login utility, you can change your
       password with a single command. If your machine does not use an AFS-modified login utility, you must issue separate commands
       to change your AFS and local passwords. See <link linkend="HDRWQ36">Changing Your Password</link>. <indexterm><primary>UNIX, differences with AFS</primary><secondary>passwords</secondary></indexterm>
     <sect2 id="HDRWQ18">
       <title>Remote Commands</title>
 
-      <para><indexterm><primary>UNIX, differences with AFS</primary><secondary>commands</secondary></indexterm> <indexterm><primary>remote commands</primary></indexterm> <indexterm><primary>commands</primary><secondary>ftp</secondary></indexterm> <indexterm><primary>ftp command</primary></indexterm> <indexterm><primary>commands</primary><secondary>rcp</secondary></indexterm>
-      <indexterm><primary>rcp command</primary></indexterm> <indexterm><primary>commands</primary><secondary>rsh</secondary></indexterm> <indexterm><primary>rsh command</primary></indexterm> The UNIX <emphasis>remote commands</emphasis> enable you
-      to run programs on a remote machine without establishing a connection to it by using a program such as <emphasis
-      role="bold">telnet</emphasis>. Many of the remote commands (such as <emphasis role="bold">ftp</emphasis>, <emphasis
-      role="bold">rcp</emphasis>, and <emphasis role="bold">rsh</emphasis>) remain available in AFS, depending on how your
-      administrators have configured them. If the remote machine has a Cache Manager, your token is used there also and you are
-      authenticated while the remote command runs. If the remote machine does not run a Cache Manager, you receive the following
-      message:</para>
-
+      <para>
+         <indexterm><primary>SSH, differences with AFS</primary><secondary>commands</secondary></indexterm>
+         <indexterm><primary>remote commands</primary></indexterm>
+         <indexterm><primary>commands</primary><secondary>ssh</secondary></indexterm>
+         <indexterm><primary>ftp command</primary></indexterm>
+         <indexterm><primary>commands</primary><secondary>scp</secondary></indexterm>
+      <indexterm><primary>scp command</primary></indexterm>
+      The <emphasis>ssh</emphasis> and <emphasis>scp</emphasis> commands enable you
+      to run programs on a remote machine or copy files to/from a remote machine. ssh commands can work seamlessly with AFS, depending
+      on how your administrators have configured them. For the recent versions of OpenSSH, you need to have a kerberos ticket on the machine you are
+      connecting from and support in the ssh client to forward that ticket to the remote machine. The remote machine needs to be configured
+      to use that ticket to obtain a token after it is forwarded.
+      </para>
+
+      <para>Most current unix OS's come with a version of OpenSSH that understands the necessary GSSAPI protocol that can use kerberos to forward
+      TGT's, but this ability is generally not enabled by default. In order to configure your ssh client to use this you need to add the
+      following lines to your ~/.ssh/config file.</para>
       <programlisting>
-   Warning: unable to authenticate.
-</programlisting>
-
-      <para>In this case, you are logged into the remote machine's UNIX file system, but you are not authenticated to AFS. You can
-      access the local files on the remote machine and the AFS directories that grant access to the <emphasis
-      role="bold">system:anyuser</emphasis> group, but you cannot access protected AFS directories.</para>
+       GSSAPIAuthentication yes
+       GSSAPIDelegateCredentials yes
+       GSSAPITrustDNS yes
+      </programlisting>
+      <para>See the ssh_config man page on your system for more details about these configuration options. In particular, you may
+        want to limit them to specific hosts or domains.</para>
+
+
+      <para>If you do not have an ssh client that can do TGT forwarding, when you login into a remote machine, you will have access to
+         native UNIX file system. However, since you are not authenticated to AFS, you can only
+      access the AFS directories that grant access to the <emphasis
+      role="bold">system:anyuser</emphasis> group, but you cannot access protected AFS directories. You can enable this access by
+      following the kinit/aklog procedure listed above.</para>
     </sect2>
 
     <sect2 id="Header_28">
       <title>Differences in the Semantics of Standard UNIX Commands</title>
 
-      <para>This section summarizes differences in the functionality of some commonly issued UNIX commands.
+      <para>This section summarizes differences in the functionality of some commonly issued UNIX commands.</para>
 
       <variablelist>
         <varlistentry>
         </varlistentry>
 
         <varlistentry>
-          <term><emphasis role="bold">inetd <indexterm><primary>inetd command</primary></indexterm> <indexterm><primary>commands</primary><secondary>inetd</secondary></indexterm> </emphasis></term>
-
-          <listitem>
-            <para>The AFS version of this daemon authenticates remote issuers of the AFS-modified <emphasis
-            role="bold">rcp</emphasis> and <emphasis role="bold">rsh</emphasis> commands with AFS.</para>
-          </listitem>
-        </varlistentry>
-
-        <varlistentry>
           <term><emphasis role="bold">login utilities <indexterm><primary>login utility</primary></indexterm> </emphasis></term>
 
           <listitem>
-            <para>AFS-modified login utilities both log you into the local UNIX file system and authenticate you with AFS.</para>
+            <para>In general, most systems will use a combination of PAM modules to provide both kerberos enabled logins and automatic AFS tokens on login. Often these PAM modules will also be used with screenlockers and graphic logins at the console.</para>
           </listitem>
         </varlistentry>
 
           </listitem>
         </varlistentry>
       </variablelist>
-</para>
     </sect2>
   </sect1>
 
index b9b3fd9..c965ce8 100644 (file)
 
       <indexterm><primary>commands</primary><secondary>login</secondary></indexterm>
 
-      <para>On machines that use an AFS-modified login utility, you log in and authenticate in one step. On machines that do not use
-      an AFS-modified login utility, you log in and authenticate in separate steps. To determine which type of login utility your
+      <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
+      an AFS enabled PAM modules, you log in and authenticate in separate steps. To determine which type of login configuration your
       machine uses, you can check for AFS tokens after logging in, or ask your system administrator, who can also tell you about any
       differences between your login procedure and the two methods described here.</para>
     </sect2>
 
     <sect2 id="Header_33">
-      <title>To Log In Using an AFS-modified Login Utility</title>
+      <title>To Log In Using an AFS enabled PAM module</title>
 
       <para>Provide your username at the <computeroutput>login:</computeroutput> prompt that appears when you establish a new
       connection to a machine. Then provide your password at the <computeroutput>Password:</computeroutput> prompt as shown in the
       <programlisting>
    login: <replaceable>username</replaceable>
    Password: <replaceable>password</replaceable>
-</programlisting>
+      </programlisting>
 
       <para>If you are not sure which type of login utility is running on your machine, it is best to issue the <emphasis
       role="bold">tokens</emphasis> command to check if you are authenticated; for instructions, see <link linkend="HDRWQ30">To
-      Display Your Tokens</link>. If you do not have tokens, issue the <emphasis role="bold">klog</emphasis> command as described in
+      Display Your Tokens</link>. If you do not have tokens, issue the <emphasis role="bold">kinit/aklog</emphasis> command pair as described in
       <link linkend="HDRWQ29">To Authenticate with AFS</link>.</para>
     </sect2>
 
     <sect2 id="HDRWQ23">
       <title>To Log In Using a Two-Step Login Procedure</title>
 
-      <para>If your machine does not use an AFS-modified login utility, you must perform a two-step procedure:
+      <para>If your machine does not use AFS enabled PAM modules, you must perform a two-step procedure:
 
       <orderedlist>
         <listitem>
         </listitem>
 
         <listitem>
-          <para>Issue the <emphasis role="bold">klog</emphasis> command to authenticate with AFS. Include the command's <emphasis
-          role="bold">-setpag</emphasis> argument to associate your token with a special identification number called a
-          <emphasis>PAG</emphasis> (for <emphasis>process authentication group</emphasis>). For a description of PAGs, see <link
-          linkend="HDRWQ25">Protecting Your Tokens with a PAG</link>. <programlisting>
-  
-   % <emphasis role="bold">klog -setpag</emphasis>
-   Password: <replaceable>your_AFS_password</replaceable>
-</programlisting></para>
+          <para>Issue the <emphasis role="bold">kinit</emphasis> command to authenticate with kerberos and
+                 obtain a ticket granting ticket ( or TGT).
+
+               <programlisting>
+   % <emphasis role="bold">kinit</emphasis>
+   Password: <replaceable>your_Kerberos_password</replaceable>
+                </programlisting></para>
         </listitem>
-      </orderedlist>
-</para>
+        <listitem>
+                 <para>Issue the <emphasis role="bold">aklog</emphasis> command to obtain an AFS token using your TGT.
+       <programlisting>
+
+   % <emphasis role="bold">aklog</emphasis>
 
+       </programlisting>
+        </para>
+       <para>On systems with an AFS enabled kinit program, the kinit program can be configured to run the aklog
+              program for you by default, but running it again has no negative side effects.</para>
+
+       </listitem>
+      </orderedlist>
+      </para>
       <note>
         <para>If your machine uses a two-step login procedure, you can choose to use different passwords for logging in and
-        authenticating. It is simplest to use the same one for both, though. Talk with your system administrator.</para>
+        authenticating.</para>
       </note>
     </sect2>
 
       role="bold">anonymous</emphasis> user and your access to AFS filespace is limited: you have only the ACL permissions granted
       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>
 
-      <para>You can obtain new tokens (reauthenticate) at any time, even after using an AFS-modified login utility, which logs you
-      in and authenticates you in one step. Issue the <emphasis role="bold">klog</emphasis> command as described in <link
-      linkend="HDRWQ29">To Authenticate with AFS</link>.</para>
+      <para>You can obtain new tokens (reauthenticate) at any time, even after using an AFS enabled login utility, which logs you
+      in and authenticates you in one step. Issue the <emphasis role="bold">aklog</emphasis> command as described in <link
+      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>
 
       <sect3 id="HDRWQ25">
         <title>Protecting Your Tokens with a PAG</title>
 
         <para>To make your access to AFS as secure as possible, it is best to associate your tokens with a unique identification
-        number called a <emphasis>PAG</emphasis> (for <emphasis>process authentication group</emphasis>). <indexterm><primary>PAG</primary></indexterm>
-        <indexterm><primary>process authentication group (PAG)</primary></indexterm> <indexterm><primary>setpag argument to klog command</primary></indexterm> AFS-modified login utilities automatically create a PAG and associate the new
-        token with it. To create a PAG when you use the two-step login procedure, include the <emphasis role="bold">klog</emphasis>
+        number called a <emphasis>PAG</emphasis> (for <emphasis>process authentication group</emphasis>).
+               <indexterm><primary>PAG</primary></indexterm>
+        <indexterm><primary>process authentication group (PAG)</primary></indexterm>
+               <indexterm><primary>setpag argument to klog command</primary></indexterm>
+               AFS enabled login utilities automatically create a PAG and associate the new
+        token with it. To create a PAG when you use the two-step login procedure, include the <emphasis role="bold">aklog</emphasis>
         command's <emphasis role="bold">-setpag</emphasis> flag. If you do not use this flag, your tokens are associated with your
         UNIX UID number instead. This type of association has two potential drawbacks:
 
         any other cell consider you to be the <emphasis role="bold">anonymous</emphasis> user unless you have an account in the cell
         and authenticate with its AFS authentication service.</para>
 
-        <para>To obtain tokens in a foreign cell, use the <emphasis role="bold">-cell</emphasis> argument to the <emphasis
-        role="bold">klog</emphasis> command. You can have tokens for your home cell and one or more foreign cells at the same
+        <para>To obtain tokens in a foreign cell, you must first obtain a kerberos TGT for the realm used to authenticate for that cell.
+               Unfortunately, while AFS tokens have support for multi-realm credentials, most kerberos implementations don't handle this as
+               gracefully. You can control where kerberos stores it's credentials by using the ENV variable <emphasis role="bold">KRB5CCNAME</emphasis>.
+               If you want to get a token for a foreign cell, without destroying the kerberos credentials of your current session, you
+               need to follow this sequence of commands.
+       <programlisting>
+
+   env KRB5CCNAME=/tmp/test.ticket kinit user@REMOTE.REALM
+   env KRB5CCNAME=/tmp/test.ticket aklog -c remote.realm -k REMOTE.REALM
+
+       </programlisting>
+               It's probably a good idea to remove the TGT from the remote realm after doing this. For kerberos implementations that don't use
+               file based ticket caches ( Mac OS X, Windows), you will need to use the graphic kerberos ticket manager included in the OS to
+               switch kerberos identities.
+           You can have tokens for your home cell and one or more foreign cells at the same
         time.</para>
       </sect3>
 
         <title>The One-Token-Per-Cell Rule</title>
 
         <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
-        for a particular cell and issue the <emphasis role="bold">klog</emphasis> command, the new token overwrites the existing
+        for a particular cell and issue the <emphasis role="bold">aklog</emphasis> command, the new token overwrites the existing
         one. Getting a new token is useful if your current token is almost expired but you want to continue accessing AFS files. For
         a discussion of token expiration, see <link linkend="HDRWQ28">Token Lifetime</link>.</para>
 
-        <para>To obtain a second token for the same cell, you must either login on a different machine or establish another separate
-        connection to the machine where you already have a token (by using the <emphasis role="bold">telnet</emphasis> utility, for
-        example). You get a new PAG for each separate machine or connection, and can use the associated tokens only while working on
-        that machine or connection.</para>
+        <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
+             linkend="HDRWQ29">To Authenticate with AFS</link>.
+             </para>
       </sect3>
 
       <sect3 id="Header_39">
         <indexterm><primary>authentication</primary><secondary>as another user</secondary></indexterm>
 
         <para>You can authenticate as another username if you know the associated password. (It is, of course, unethical to use
-        someone else's tokens without permission.) If you use the <emphasis role="bold">klog</emphasis> command to authenticate as
-        another AFS username, you retain your own local (UNIX) identity, but the AFS server processes recognize you as the other
-        user. The new token replaces any token you already have for the relevant cell (for the reason described in <link
+        someone else's tokens without permission.) If you use the <emphasis role="bold">kinit</emphasis> and
+               <emphasis role="bold">aklog</emphasis>  commands to authenticate as
+        another Kerberos username and obtain an AFS token, you retain your own local (UNIX) identity, but the AFS
+               server processes recognize you as the other user. The new token replaces any token you already have for the
+               relevant cell (for the reason described in <link
         linkend="HDRWQ27">The One-Token-Per-Cell Rule</link>).</para>
       </sect3>
 
 
         <indexterm><primary>lifetime of tokens</primary></indexterm>
 
-        <para>Tokens have a limited lifetime. To determine when your tokens expire, issue the <emphasis
+        <para>Tokens and Kerberos TGT's have a limited lifetime. To determine when your tokens expire, issue the <emphasis
         role="bold">tokens</emphasis> command as described in <link linkend="HDRWQ30">To Display Your Tokens</link>. If you are ever
         unable to access AFS in a way that you normally can, issuing the <emphasis role="bold">tokens</emphasis> command tells you
         whether an expired token is a possible reason.</para>
 
-        <para>Your cell's administrators set the default lifetime of your token. The AFS authentication service never grants a token
-        lifetime longer than the default, but you can request a token with a shorter lifetime. See the <emphasis
-        role="bold">klog</emphasis> reference page in the <emphasis>OpenAFS Administration Reference</emphasis> to learn how to use
+        <para>Your cell's kerberos administrators set the default lifetime of your kerberos TGT. The AFS authentication service never grants a token
+        lifetime longer than the current TGT lifetime, but you can request a TGT with a shorter lifetime. See the <emphasis
+        role="bold">kinit</emphasis> man page on your system to learn how to use
         its <emphasis role="bold">-lifetime</emphasis> argument for this purpose.</para>
       </sect3>
 
-      <sect3 id="Header_41">
-        <title>Authenticating for DFS Access</title>
-
-        <indexterm><primary>commands</primary><secondary>dlog</secondary></indexterm>
-
-        <indexterm><primary>commands</primary><secondary>dpass</secondary></indexterm>
-
-        <indexterm><primary>dlog command</primary></indexterm>
-
-        <indexterm><primary>dpass command</primary></indexterm>
-
-        <indexterm><primary>authentication</primary><secondary>with DCE for DFS access</secondary></indexterm>
-
-        <para>If your machine is configured to access a DCE cell's DFS filespace by means of the AFS/DFS Migration Toolkit, you can
-        use the <emphasis role="bold">dlog</emphasis> command to authenticate with DCE. The <emphasis role="bold">dlog</emphasis>
-        command has no effect on your ability to access AFS filespace.</para>
-
-        <para>If your system administrator has converted your AFS account to a DCE account and you are not sure of your DCE
-        password, use the <emphasis role="bold">dpass</emphasis> command to display it. You must be authenticated as the AFS user
-        whose AFS account was converted to a DCE account, and be able to provide the correct AFS password. Like the <emphasis
-        role="bold">dlog</emphasis> command, the <emphasis role="bold">dpass</emphasis> command has no functionality with respect to
-        AFS.</para>
-
-        <para>For more information on using the <emphasis role="bold">dlog</emphasis> and <emphasis role="bold">dpass</emphasis>
-        commands, see your system administrator.</para>
-      </sect3>
     </sect2>
 
     <sect2 id="HDRWQ29">
       <title>To Authenticate with AFS</title>
 
-      <indexterm><primary>klog command</primary></indexterm>
-
-      <indexterm><primary>commands</primary><secondary>klog</secondary></indexterm>
-
+      <indexterm><primary>aklog command</primary></indexterm>
+      <indexterm><primary>kinit command</primary></indexterm>
+      <indexterm><primary>commands</primary><secondary>aklog</secondary></indexterm>
+     <indexterm><primary>commands</primary><secondary>kinit</secondary></indexterm>
       <indexterm><primary>tokens</primary><secondary>getting</secondary></indexterm>
 
-      <para>If your machine is not using an AFS-modified login utility, you must authenticate after login by issuing the <emphasis
-      role="bold">klog</emphasis> command. You can also issue this command at any time to obtain a token with a later expiration
+      <para>If your machine is not using an AFS enabled login utility, you must authenticate after login by issuing the <emphasis
+      role="bold">kinit</emphasis> command and then use <emphasis role="bold">aklog</emphasis> to obtain a token. You can also
+      issue these commands at any time to obtain a token with a later expiration
       date than your current token.</para>
 
       <programlisting>
-   % <emphasis role="bold">klog</emphasis> [<emphasis role="bold">-setpag</emphasis>] [<emphasis role="bold">-cell</emphasis> &lt;<replaceable>cell name</replaceable>&gt;]
-   Password: <replaceable>your_AFS_password</replaceable>
+   % <emphasis role="bold">kinit</emphasis> [<emphasis role="bold">userid@KRB5.REALM</emphasis>]
+   Password: <replaceable>your_kerberos_password</replaceable>
 </programlisting>
 
       <para>where
 
       <variablelist>
         <varlistentry>
-          <term><emphasis role="bold">-setpag</emphasis></term>
+          <term><emphasis role="bold">userid@KRB5.REALM</emphasis></term>
 
           <listitem>
-            <para>Associates the resulting tokens with a PAG (see <link linkend="HDRWQ25">Protecting Your Tokens with a PAG</link>).
-            Include this flag the first time you obtain a token for a particular cell during a login session or connection. Do not
-            include it when refreshing the token for a cell during the same session.</para>
+            <para>is the kerberos userid and realm that you want to get a TGT from. If the machine is properly configured
+                               for your local cell and realm, you should not need to specify the kerberos identity.</para>
           </listitem>
         </varlistentry>
 
+      </variablelist>
+      </para>
+
+      <para>Your password does not echo visibly appear on the screen. When the command shell prompt returns,
+      you have a kerberos TGT. You then need to use the <emphasis role="bold">aklog</emphasis> command to
+      obtain an AFS token.</para>
+
+         <programlisting>
+   % <emphasis role="bold">aklog</emphasis> [<emphasis role="bold">-cell afs.cell.name</emphasis>]  [<emphasis role="bold">-k KRB5.REALM</emphasis>]
+          </programlisting>
+
+      <para>where
+
+      <variablelist>
         <varlistentry>
-          <term><emphasis role="bold">-cell</emphasis></term>
+          <term><emphasis role="bold">KRB5.REALM</emphasis></term>
 
           <listitem>
-            <para>Names the cell for which to obtain the token. You must have an account in the cell.</para>
+            <para>is the kerberos realm used to authenticate the AFS cell.</para>
           </listitem>
         </varlistentry>
+
+       <varlistentry>
+         <term><emphasis role="bold">afs.cell.name</emphasis></term>
+
+         <listitem>
+           <para>is the AFS cell for which you want a token.</para>
+         </listitem>
+       </varlistentry>
+
       </variablelist>
-</para>
+      </para>
 
-      <para>Your password does not echo visibly appear on the screen. When the command shell prompt returns, you are an
-      authenticated AFS user. You can use the <emphasis role="bold">tokens</emphasis> command to verify that you are authenticated,
+      <para>You can use the <emphasis role="bold">tokens</emphasis> command to verify that you are authenticated,
       as described in the following section.</para>
+
+      <note xml:id="note.a.note.on.kerberos.realms.and.afs.cellnames">
+          <title>A Note on Kerberos Realms and AFS Cellnames</title>
+          <para>These are two things that are often the same, but each has it's own distinct rules.
+          By convention, kerberos realms are always in UPPER CASE and afs cellnames are in lower case.
+          Thus username@KRB5.REALM is the kerberos identity used for the AFS cell krb5.realm. There is
+          no restriction that the cell and realm names must match, but most sites are set up that way
+          to avoid confusion. In a well configured system you should never need worry about this until
+          you need to access remote realms/cells.</para>
+      </note>
+
     </sect2>
 
     <sect2 id="HDRWQ30">
       <programlisting>
    Tokens held by the Cache Manager:
    User's (AFS ID 1022) tokens for afs@abc.com [Expires Aug   3 14:35]
-   User's (AFS ID 9554) tokens for afs@stateu.edu [Expires Aug   4  1:02] 
+   User's (AFS ID 9554) tokens for afs@stateu.edu [Expires Aug   4  1:02]
       --End of list--
 </programlisting>
     </sect2>
 
       <para>Suppose that user <emphasis role="bold">terry</emphasis> cannot save a file. He uses the <emphasis
       role="bold">tokens</emphasis> command and finds that his tokens have expired. He reauthenticates in his local cell under his
-      current identity by issuing the following command:</para>
+      current identity by issuing the following commands:</para>
 
       <programlisting>
-   % <emphasis role="bold">klog</emphasis>
+   % <emphasis role="bold">kinit</emphasis>
    Password:  <replaceable>terry's_password</replaceable>
+   % <emphasis role="bold">aklog</emphasis>
+
 </programlisting>
 
       <para>The he issues the <emphasis role="bold">tokens</emphasis> command to make sure he is authenticated.</para>
       Manager can store only one token per cell per login session on a machine.</para>
 
       <programlisting>
-   % <emphasis role="bold">klog pat</emphasis>
+   % <emphasis role="bold">kinit pat</emphasis>
    Password: <replaceable>pat's_password</replaceable>
+   % <emphasis role="bold">aklog</emphasis>
    % <emphasis role="bold">tokens</emphasis>
    Tokens held by the Cache Manager:
    User's (AFS ID 4278) tokens for afs@abc.com [Expires Jun 23 9:46]
       his account is called <emphasis role="bold">ts09</emphasis>.</para>
 
       <programlisting>
-   % <emphasis role="bold">klog  ts09 -cell stateu.edu</emphasis>
-   Password: <replaceable>ts09's_password</replaceable>
+   % <emphasis role="bold">env KRB5CCNAME=/tmp/temp.tgt kinit ts09@STATEU.EDU</emphasis>
+       Password: <replaceable>ts09's_password</replaceable>
+   % <emphasis role="bold">env KRB5CCNAME=/tmp/temp.tgt aklog  ts09 -cell stateu.edu</emphasis>
+
    % <emphasis role="bold">tokens</emphasis>
    Tokens held by the Cache Manager:
    User's (AFS ID 4562) tokens for afs@abc.com [Expires Jun 22 14:35]
        --End of list--
 </programlisting>
     </sect2>
-
-    <sect2 id="HDRWQ31">
-      <title>Limits on Failed Authentication Attempts</title>
-
-      <indexterm><primary>authentication</primary><secondary>limits on consecutive failed attempts</secondary></indexterm>
-
-      <para>Your system administrator can choose to limit the number of times that you fail to provide the correct password when
-      authenticating with AFS (using either an AFS-modified login utility or the <emphasis role="bold">klog</emphasis> command). If
-      you exceed the limit, the AFS authentication service refuses further authentication attempts for a period of time set by your
-      system administrator. The purpose of this limit is to prevent unauthorized users from breaking into your account by trying a
-      series of passwords.</para>
-
-      <para>To determine if your user account is subject to this limit, ask your system administrator or issue the <emphasis
-      role="bold">kas examine</emphasis> command as described in <link linkend="HDRWQ32">To Display Your Failed Authentication Limit
-      and Lockout Time</link>.</para>
-
-      <para>The following message indicates that you have exceeded the limit on failed authentication attempts.</para>
-
-      <programlisting>
-   Unable to authenticate to AFS because ID is locked - see your system admin
-</programlisting>
-    </sect2>
-
-    <sect2 id="HDRWQ32">
-      <title>To Display Your Failed Authentication Limit and Lockout Time</title>
-
-      <indexterm><primary>kas commands</primary><secondary>examine</secondary></indexterm>
-
-      <indexterm><primary>commands</primary><secondary>kas examine</secondary></indexterm>
-
-      <indexterm><primary>limits on authentication attempts</primary></indexterm>
-
-      <indexterm><primary>users</primary><secondary>account lockout time</secondary></indexterm>
-
-      <para>Issue the <emphasis role="bold">kas examine</emphasis> command to determine if there is a limit on the number of
-      unsuccessful authentication attempts for your user account and any associated lockout time. You can examine only your own
-      account. The fourth line of the output reports the maximum number of times you can provide an incorrect password before being
-      locked out of your account. The <computeroutput>lock time</computeroutput> field on the next line reports how long the AFS
-      authentication service refuses authentication attempts after the limit is exceeded.</para>
-
-      <programlisting>
-   % <emphasis role="bold">kas examine</emphasis> <replaceable>your_username</replaceable>
-   Password for <replaceable>your_username</replaceable>: <replaceable>your_AFS_password</replaceable>
-</programlisting>
-
-      <para>The following example displays the output for the user <emphasis role="bold">pat</emphasis>, who is allowed nine failed
-      authentication attempts. The lockout time is 25.5 minutes.</para>
-
-      <programlisting>
-   User data for pat
-    key (15) cksum is 3414844392,  last cpw: Thu Oct 21 16:05:44 1999
-    password will expire:  Fri Nov 26 20:44:36 1999
-    9 consecutive unsuccessful authentications are permitted.
-    The lock time for this user is 25.5 minutes.
-    User is not locked.
-    entry never expires. Max ticket lifetime 100.00 hours.
-    last mod on Wed Aug 18 08:22:29 1999 by admin
-    permit password reuse
-</programlisting>
-    </sect2>
   </sect1>
 
   <sect1 id="HDRWQ33">
 
     <para>You can use the <emphasis role="bold">unlog</emphasis> command any time you want to unauthenticate, not just when logging
     out. For instance, it is a good practice to unauthenticate before leaving your machine unattended, to prevent other users from
-    using your tokens during your absence. When you return to your machine, issue the <emphasis role="bold">klog</emphasis> command
+    using your tokens during your absence. When you return to your machine, issue the <emphasis role="bold">aklog</emphasis> command
     to reauthenticate, as described in <link linkend="HDRWQ29">To Authenticate with AFS</link>.</para>
 
     <para>Do not issue the <emphasis role="bold">unlog</emphasis> command when you are running jobs that take a long time to
 
           <para>The alternative is for the foreign cell's administrator to create an account for you, essentially making you a local
           user in the cell. The directory's owner creates an ACL entry for you as for any other local user. To authenticate in the
-          foreign cell, issue the <emphasis role="bold">klog</emphasis> command with the <emphasis role="bold">-cell</emphasis>
+          foreign cell, issue the <emphasis role="bold">aklog</emphasis> command with the <emphasis role="bold">-cell</emphasis>
           argument.</para>
         </listitem>
       </itemizedlist>
-</para>
+      </para>
 
       <para>For further discussion of directory and file protection, see <link linkend="HDRWQ44">Protecting Your Directories and
       Files</link>.</para>
   <sect1 id="HDRWQ36">
     <title>Changing Your Password</title>
 
-    <para>In cells that use an AFS-modified login utility, the password is the same for both logging in and authenticating with AFS.
-    In this case, you use a single command, <emphasis role="bold">kpasswd</emphasis>, to change the password.</para>
+    <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.
+    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>
 
-    <para>If your machine does not use an AFS-modified login utility, there are separate passwords for logging into the local file
+    <para>If your machine does not use an AFS and kerberos enabled login utility, there are separate passwords for logging into the local file
     system and authenticating with AFS. (The two passwords can be the same or different, at your discretion.) In this case, use the
-    <emphasis role="bold">kpasswd</emphasis> command to change your AFS password and the UNIX <emphasis
+    <emphasis role="bold">kpasswd</emphasis> command to change your Kerberos password and the UNIX <emphasis
     role="bold">passwd</emphasis> command to change your UNIX password.</para>
 
-    <para>Your system administrator can improve cell security by configuring several features that guide your choice of password.
-    Keep them in mind when you issue the <emphasis role="bold">kpasswd</emphasis> command:
-
-    <itemizedlist>
-      <listitem>
-        <para>Limiting the amount of time your password is valid. This improves your cell's security by limiting the amount of time
-        an unauthorized user has to try to guess your password. Your system administrator needs to tell you when your password is
-        due to expire so that you can change it in time. The administrator can configure the AFS-modified login utility to report
-        this information automatically each time you log in. You can also use the <emphasis role="bold">kas examine</emphasis>
-        command to display the password expiration date, as instructed in <link linkend="HDRWQ37">To Display Password Expiration
-        Date and Reuse Policy</link>.</para>
-
-        <para>You can change your password prior to the expiration date, but your system administrator can choose to set a minimum
-        time between password changes. The following message indicates that the minimum time has not yet passed.</para>
-
-        <programlisting>
-   kpasswd:  password was not changed because you changed it too 
-   recently; see your system administrator
-</programlisting>
-      </listitem>
-
-      <listitem>
-        <para>Enforcing password quality standards, such as a minimum length or inclusion of nonalphabetic characters. The
-        administrator needs to tell you about such requirements so that you do not waste time picking unacceptable passwords.</para>
-      </listitem>
-
-      <listitem>
-        <para>Rejecting a password that is too similar to the last 20 passwords you used. You can use the <emphasis role="bold">kas
-        examine</emphasis> command to check whether this policy applies to you, as instructed in <link linkend="HDRWQ37">To Display
-        Password Expiration Date and Reuse Policy</link>. The following message indicates that the password you have chosen is too
-        similar to a previous password. <programlisting>
-   kpasswd:  Password was not changed because it seems like a reused password
-</programlisting></para>
-      </listitem>
-    </itemizedlist>
-</para>
-
-    <sect2 id="HDRWQ37">
-      <title>To Display Password Expiration Date and Reuse Policy</title>
-
-      <indexterm><primary>kas commands</primary><secondary>examine</secondary></indexterm>
-
-      <indexterm><primary>commands</primary><secondary>kas examine</secondary></indexterm>
-
-      <indexterm><primary>password</primary><secondary>expiration date, displaying</secondary></indexterm>
-
-      <indexterm><primary>password</primary><secondary>reuse policy, displaying</secondary></indexterm>
-
-      <indexterm><primary>displaying</primary><secondary>password expiration date</secondary></indexterm>
-
-      <indexterm><primary>displaying</primary><secondary>password reuse policy</secondary></indexterm>
-
-      <para>Issue the <emphasis role="bold">kas examine</emphasis> command to display your password expiration date and reuse
-      policy. You can examine only your own account. The third line of the output reports your password's expiration date. The last
-      line reports the password reuse policy that applies to you.</para>
-
-      <programlisting>
-   % <emphasis role="bold">kas examine</emphasis> <replaceable>your_username</replaceable>
-   Password for <replaceable>your_username</replaceable>: <replaceable>your_AFS_password</replaceable>
-</programlisting>
-
-      <para>The following example displays the output for the user <emphasis role="bold">pat</emphasis>.</para>
-
-      <programlisting>
-   User data for pat
-    key (15) cksum is 3414844392,  last cpw: Thu Oct 21 16:05:44 1999
-    password will expire:  Fri Nov 26 20:44:36 1999
-    9 consecutive unsuccessful authentications are permitted.
-    The lock time for this user is 25.5 minutes.
-    User is not locked.
-    entry never expires. Max ticket lifetime 100.00 hours.
-    last mod on Wed Aug 18 08:22:29 1999 by admin
-    don't permit password reuse
-</programlisting>
-    </sect2>
-
-    <sect2 id="Header_59">
-      <title>To Change Your AFS Password</title>
-
-      <indexterm><primary>password</primary><secondary>changing AFS</secondary></indexterm>
-
-      <indexterm><primary>changing</primary><secondary>AFS password</secondary></indexterm>
-
-      <indexterm><primary>commands</primary><secondary>kpasswd</secondary></indexterm>
-
-      <indexterm><primary>kpasswd command</primary></indexterm>
-
-      <para>Issue the <emphasis role="bold">kpasswd</emphasis> command, which prompts you to provide your old and new passwords and
-      to confirm the new password. The passwords do not echo visibly on the screen.</para>
-
-      <programlisting>
-   % <emphasis role="bold">kpasswd</emphasis>
-   Old password: <replaceable>current_password</replaceable>
-   New password (RETURN to abort): <replaceable>new_password</replaceable>
-   Retype new password: <replaceable>new_password</replaceable>
-</programlisting>
-    </sect2>
-
-    <sect2 id="Header_60">
-      <title>To Change Your UNIX Password</title>
-
-      <para><indexterm><primary>commands</primary><secondary>passwd</secondary></indexterm> <indexterm><primary>passwd</primary><secondary>command</secondary></indexterm> <indexterm><primary>password</primary><secondary>changing UNIX</secondary></indexterm> <indexterm><primary>changing</primary><secondary>UNIX password</secondary></indexterm> Issue the UNIX <emphasis
-      role="bold">passwd</emphasis> command, which prompts you to provide your old and new passwords and to confirm the new
-      password. The passwords do not echo visibly on the screen. On many machines, the <emphasis role="bold">passwd</emphasis>
-      resides in the <emphasis role="bold">/bin</emphasis> directory, and you possibly need to type the complete pathname.</para>
-
-      <programlisting>
-   % <emphasis role="bold">passwd</emphasis>
-   Changing password for <replaceable>username</replaceable>.
-   Old password: <replaceable>current_password</replaceable>
-   New password: <replaceable>new_password</replaceable>
-   Retype new passwd: <replaceable>new_password</replaceable>
-</programlisting>
-    </sect2>
   </sect1>
 </chapter>
index 6d0db93..14bb25b 100644 (file)
 
       <programlisting>
    % <emphasis role="bold">fs listquota ~terry</emphasis>
-   Volume Name     Quota    Used    % Used   Partition 
-   user.terry      10000    3400       34%         86% 
+   Volume Name     Quota    Used    % Used   Partition
+   user.terry      10000    3400       34%         86%
 </programlisting>
     </sect2>
 
 
       <programlisting>
    % <emphasis role="bold">fs checkservers -all &amp;</emphasis>
-   These servers unavailable due to network or server problems: 
+   These servers unavailable due to network or server problems:
       fs1.abc.com server7.stateu.edu.
 </programlisting>
     </sect2>
 
       <programlisting>
    % <emphasis role="bold">fs listcells &amp;</emphasis>
-   Cell abc.com  on hosts 
+   Cell abc.com  on hosts
         db1.abc.com
         db2.abc.com
         db3.abc.com
-   Cell test.abc.com on hosts 
+   Cell test.abc.com on hosts
         test4.abc.com.
-   Cell stateu.edu on hosts 
+   Cell stateu.edu on hosts
         sv5.stateu.edu.
         sv2.stateu.edu.
         sv11.stateu.edu.
-   Cell def.com on hosts 
-        serverA.def.com 
+   Cell def.com on hosts
+        serverA.def.com
 </programlisting>
     </sect2>
   </sect1>
index ace0543..82a4ffa 100644 (file)
    Normal rights:
       system:anyuser rl
       pat rlidwka
-      terry rliw 
+      terry rliw
    Access list for ../plans is
    Normal rights:
       terry rlidwka
       <programlisting>
    % <emphasis role="bold">fs setacl  -dir</emphasis> &lt;<replaceable>directory</replaceable>&gt;<superscript>+</superscript> <emphasis
           role="bold">-acl</emphasis> &lt;<replaceable>access list entries</replaceable>&gt;<superscript>+</superscript>  <emphasis
-          role="bold">-negative</emphasis> 
+          role="bold">-negative</emphasis>
 </programlisting>
 
       <para>where <variablelist>
    Normal rights:
       terry rlidwka
       pat rl
-      smith rl   
-     
+      smith rl
+
   % <emphasis role="bold">fs copyacl -from . -to plans</emphasis>
-   
+
    % <emphasis role="bold">fs listacl . plans</emphasis>
    Access list for . is
    Normal rights:
       terry rlidwka
       pat rlidwk
       jones rl
-      smith rl   
+      smith rl
 </programlisting>
     </sect2>
   </sect1>
index 746e7aa..a1980d7 100644 (file)
    % <emphasis role="bold">pts membership terry:team</emphasis>
    Members of terry:team (id: -286) are:
      terry
-     smith 
+     smith
      pat
      johnson
 </programlisting>
    Groups owned by pat (id: 1845) are:
       pat:accounting
       pat:plans
-   
+
 </programlisting>
     </sect2>
 
 
       <programlisting>
   % <emphasis role="bold">pts examine pat</emphasis>
-   Name: pat, id: 1045, owner: system:administrators, creator: admin, 
+   Name: pat, id: 1045, owner: system:administrators, creator: admin,
      membership: 12, flags: S-M--, group quota: 17
 </programlisting>
     </sect2>
    % <emphasis role="bold">pts creategroup terry:team</emphasis>
    group terry:team has id -286
    % <emphasis role="bold">pts examine terry:team</emphasis>
-   Name: terry:team, id: -286, owner: terry, creator: terry, 
+   Name: terry:team, id: -286, owner: terry, creator: terry,
      membership: 0, flags: S----, group quota: 0.
 </programlisting>
     </sect2>
       own the group.</para>
 
       <note>
-        <para>If you already have a token when you are added to a group, you must issue the <emphasis role="bold">klog</emphasis>
+        <para>If you already have a token when you are added to a group, you must issue the <emphasis role="bold">aklog</emphasis>
         command to reauthenticate before you can exercise the permissions granted to the group on ACLs.</para>
       </note>
 
 
       <programlisting>
    % <emphasis role="bold">pts chown pat:staff terry</emphasis>
-   % <emphasis role="bold">pts examine terry:staff</emphasis> 
-   Name: terry:staff, id: -534, owner: terry, creator: pat, 
+   % <emphasis role="bold">pts examine terry:staff</emphasis>
+   Name: terry:staff, id: -534, owner: terry, creator: pat,
      membership: 15, flags: SOm--, group quota: 0.
 </programlisting>
     </sect2>
       <programlisting>
    % <emphasis role="bold">pts chown terry:team terry:team</emphasis>
    % <emphasis role="bold">pts examine terry:team</emphasis>
-   Name: terry:team, id: -286, owner: terry:team, creator: terry, 
+   Name: terry:team, id: -286, owner: terry:team, creator: terry,
      membership: 6, flags: SOm--, group quota: 0.
 </programlisting>
     </sect2>
 
       <programlisting>
    % <emphasis role="bold">pts examine sam:project</emphasis>
-   Name: sam:project, id: -522, owner: sam, creator: sam, 
+   Name: sam:project, id: -522, owner: sam, creator: sam,
      membership: 33, flags: SOm--, group quota: 0.
    % <emphasis role="bold">pts chown sam:project smith:cpa</emphasis>
    % <emphasis role="bold">pts examine smith:project</emphasis>
-   Name: smith:project, id: -522, owner: smith:cpa, creator: sam, 
+   Name: smith:project, id: -522, owner: smith:cpa, creator: sam,
      membership: 33, flags: SOm--, group quota: 0.
 </programlisting>
     </sect2>
 
       <programlisting>
    % <emphasis role="bold">pts examine smith:project</emphasis>
-   Name: smith:project, id: -522, owner: smith:cpa, creator: sam, 
+   Name: smith:project, id: -522, owner: smith:cpa, creator: sam,
      membership: 33, flags: SOm--, group quota: 0.
    % <emphasis role="bold">pts rename smith:project smith:fiscal-closing</emphasis>
    % <emphasis role="bold">pts examine smith:fiscal-closing</emphasis>
-   Name: smith:fiscal-closing, id: -522, owner: smith:cpa, creator: sam, 
+   Name: smith:fiscal-closing, id: -522, owner: smith:cpa, creator: sam,
      membership: 33, flags: SOm--, group quota: 0.
 </programlisting>
     </sect2>
       the name to <emphasis role="bold">terry:plans</emphasis> to reflect its actual ownership.</para>
 
       <programlisting>
-   % <emphasis role="bold">pts examine pat:plans</emphasis> 
-   Name: pat:plans, id: -535, owner: terry:staff, creator: pat, 
+   % <emphasis role="bold">pts examine pat:plans</emphasis>
+   Name: pat:plans, id: -535, owner: terry:staff, creator: pat,
      membership: 8, flags: SOm--, group quota: 0.
    % <emphasis role="bold">pts rename pat:plans terry:plans</emphasis>
-   % <emphasis role="bold">pts examine terry:plans</emphasis> 
-   Name: terry:plans, id: -535, owner: terry:staff, creator: pat, 
+   % <emphasis role="bold">pts examine terry:plans</emphasis>
+   Name: terry:plans, id: -535, owner: terry:staff, creator: pat,
      membership: 8, flags: SOm--, group quota: 0.
 </programlisting>
     </sect2>
 
       <programlisting>
    % <emphasis role="bold">pts setfields terry:team -access SOm--</emphasis>
-  
+
 </programlisting>
 
       <itemizedlist>
       </itemizedlist>
     </sect2>
   </sect1>
-</chapter>
\ No newline at end of file
+</chapter>
index 0693be7..ac0c15a 100644 (file)
 
           <listitem>
             <para>If your do not have tokens for the relevant cell, or they are expired, issue the <emphasis
-            role="bold">klog</emphasis> command to authenticate. For complete instructions, see <link linkend="HDRWQ29">To
+            role="bold">aklog</emphasis> command to authenticate. You may also need to first obtain a kerberos ticket using<emphasis role="bold">kinit</emphasis> since tokens often expire at the same time as TGT's. For complete instructions, see <link linkend="HDRWQ29">To
             Authenticate with AFS</link>. Then try accessing or saving the file again. If you are not successful, proceed to Step
             <link linkend="LINOSAVE-FSCHECKS">2</link>. <programlisting>
-   % <emphasis role="bold">klog</emphasis>
+   % <emphasis role="bold">aklog</emphasis>
 </programlisting></para>
           </listitem>
         </itemizedlist>
@@ -74,7 +74,7 @@
           <listitem>
             <para>Output like the following indicates that your Cache Manager cannot reach the indicated file server machines.
             <programlisting>
-   These servers unavailable due to network or server problem:  
+   These servers unavailable due to network or server problem:
    <replaceable>list of machines</replaceable>.
 </programlisting></para>
 
 
         <para>If you do not have the necessary permissions and do not own the directory, ask the owner or a system administrator to
         grant them to you. If they add you to a group that has the required permissions, you must issue the <emphasis
-        role="bold">klog</emphasis> command to reauthenticate before you can exercise them.</para>
+        role="bold">aklog</emphasis> command to reauthenticate before you can exercise them.</para>
 
         <para>If you still cannot access the file even though you have the necessary permissions, contact your system administrator
         for help in investigating further possible causes of your problem. If you still cannot copy or save the file even though you
 
         <programlisting>
    % <emphasis role="bold">fs listquota /afs/abc.com/usr/terry</emphasis>
-   Volume Name     Quota    Used    % Used   Partition 
-   user.terry      10000    3400       34%         86% 
+   Volume Name     Quota    Used    % Used   Partition
+   user.terry      10000    3400       34%         86%
 </programlisting>
 
         <itemizedlist>
 </programlisting></para>
 
             <para>Ask the directory's owner or your system administrator to grant you the permissions you need. If they add you to a
-            group that has the required permissions, you must issue the <emphasis role="bold">klog</emphasis> command to
+            group that has the required permissions, you must issue the <emphasis role="bold">aklog</emphasis> command to
             reauthenticate before you can exercise them.</para>
           </listitem>
         </itemizedlist>
       <listitem>
         <para>Output like the following indicates that your Cache Manager cannot reach the indicated file server machines. You must
         wait until they are again accessible before continuing to work with the files that are stored on them. <programlisting>
-   These servers unavailable due to network or server problem: 
+   These servers unavailable due to network or server problem:
    <replaceable>list_of_machines</replaceable>.
 </programlisting></para>
       </listitem>
 
     <para>Follow the instructions in <link linkend="HDRWQ77">Problem: Cannot Access, Copy, or Save File</link>.</para>
   </sect1>
-</chapter>
\ No newline at end of file
+</chapter>
index a4d5f23..7480a5e 100644 (file)
@@ -2,11 +2,11 @@
     <appendix id="HDRWQ80"><title>Using the NFS/AFS Translator</title>
     <para>
 <indexterm><primary>NFS</primary><secondary>accessing AFS from client</secondary></indexterm>
+
 <indexterm><primary>NFS/AFS Translator</primary></indexterm>
+
 <indexterm><primary>AFS</primary><secondary>accessing from NFS client machine</secondary></indexterm>
+
 <indexterm><primary>access to AFS filespace</primary><secondary>from NFS client machines</secondary></indexterm>
  Some
     cells use the Network File System (NFS) in addition to AFS. If you work on an NFS client machine, your system
@@ -20,7 +20,7 @@
     <sect1 id="HDRWQ81"><title>Requirements for Using the NFS/AFS Translator</title>
     <para>
 <indexterm><primary>NFS</primary><secondary>issuing AFS commands on NFS client machine</secondary></indexterm>
+
 <indexterm><primary>commands</primary><secondary>AFS, issuing on NFS client machine</secondary></indexterm>
  For you to use the NFS/AFS Translator, your system
     administrator must configure the following types of machines as indicated:</para>
@@ -42,9 +42,9 @@
     configure it to enable you to issue many AFS commands on the machine. Ask him or her about the configuration and
     which commands you can issue.</para>
     </sect1><sect1 id="Header_160"><title>Accessing AFS via the Translator</title>
-    
+
 <indexterm><primary>authentication</primary><secondary>to AFS on NFS client machines</secondary></indexterm>
+
     <para>If you do not have an AFS account or choose not to access AFS as an authenticated user, then all you do to
     access AFS is provide the pathname of the relevant file. Its ACL must grant the necessary permissions to the
     <emphasis role="bold">system:anyuser</emphasis> group.</para>
@@ -57,7 +57,7 @@
       <listitem><para>Log into the NFS client machine using your NFS username.</para></listitem>
       <listitem><para>
         Issue the <emphasis role="bold">klog</emphasis> command. For complete instructions, see
-        <link linkend="HDRWQ29">To Authenticate with AFS</link>. 
+        <link linkend="HDRWQ29">To Authenticate with AFS</link>.
 <programlisting>
    % <emphasis role="bold">klog -setpag</emphasis>
 </programlisting>
       <listitem><para>
         If the NFS/AFS translator machine uses an AFS-modified login utility, then you obtained AFS tokens in Step
         <link linkend="LINFS-TELNET">2</link>. To check, issue the <emphasis role="bold">tokens</emphasis> command,
-        which is described fully in <link linkend="HDRWQ30">To Display Your Tokens</link>. 
+        which is described fully in <link linkend="HDRWQ30">To Display Your Tokens</link>.
 <programlisting>
    % <emphasis role="bold">tokens</emphasis>
 </programlisting>
         If you do not have tokens, issue the <emphasis role="bold">klog</emphasis> command, which is described fully in
-        <link linkend="HDRWQ29">To Authenticate with AFS</link>. 
+        <link linkend="HDRWQ29">To Authenticate with AFS</link>.
 <programlisting>
    % <emphasis role="bold">klog -setpag</emphasis>
 </programlisting>
       <listitem><para>
         <anchor id="LINFS-KNFS" />Issue the <emphasis role="bold">knfs</emphasis> command to associate your AFS tokens
         with your UNIX UID on the NFS client machine where you are working. This enables the Cache Manager on the
-        translator machine to use the tokens properly when you access AFS from the NFS client machine. 
+        translator machine to use the tokens properly when you access AFS from the NFS client machine.
         </para><para>If your NFS client machine is a system type for which AFS defines a system name, it can make sense
         to add the <emphasis role="bold">-sysname</emphasis> argument. This argument helps the Cache Manager access
         binaries specific to your NFS client machine, if your system administrator has used the
         <emphasis>@sys</emphasis> variable in pathnames. Ask your system administrator if this argument is useful for
-        you. 
+        you.
 <indexterm><primary>knfs command</primary></indexterm>
+
 <indexterm><primary>commands</primary><secondary>knfs</secondary></indexterm>
 </para>
 <programlisting>
         arguments as in Step <link linkend="LINFS-KNFS">4</link>, and add the <emphasis role="bold">-unlog</emphasis>
         flag to destroy your tokens. If you logged out from the translator machine in Step
         <link linkend="LINFS-LOGOUT">5</link>, then you must first reestablish a connection to the translator machine
-        as in Step <link linkend="LINFS-TELNET">2</link>. 
+        as in Step <link linkend="LINFS-TELNET">2</link>.
 <programlisting>
    % <emphasis role="bold">knfs</emphasis> &lt;<replaceable>host name</replaceable>&gt; [&lt;<replaceable>user ID (decimal)</replaceable>&gt;] <emphasis role="bold">-unlog</emphasis>
 </programlisting>
index 334c56f..d29b2cf 100644 (file)
@@ -1,8 +1,8 @@
 <?xml version="1.0" encoding="utf-8"?>
     <appendix id="HDRWQ86"><title>OpenAFS Command Syntax and Online Help</title>
-    
+
 <indexterm><primary>syntax of AFS commands described</primary></indexterm>
+
     <para>The AFS commands available to you are used to authenticate, list AFS information, protect directories, create
     and manage groups, and create and manage ACLs. There are three general types of commands available to all AFS
     users: file server commands, protection server commands, and miscellaneous commands. This chapter discusses the
@@ -17,9 +17,9 @@
 </programlisting>
     <para>The <emphasis>command suite</emphasis> indicates the general type of command and the server process that
     performs the command. Regular AFS users have access to two main command suites and a miscellaneous set of commands:
-    
+
 <indexterm><primary>commands</primary><secondary>suite organization for AFS</secondary></indexterm>
+
 <indexterm><primary>suite, defined for AFS command</primary></indexterm>
 </para>
     <itemizedlist>
       <listitem><para>The miscellaneous commands are not associated with any command suite.</para></listitem>
     </itemizedlist>
     <para>The <emphasis>operation code</emphasis> indicates the action that the command performs. Miscellaneous
-    commands have operation codes only. 
+    commands have operation codes only.
 <indexterm><primary>operation codes in AFS commands</primary><secondary>defined</secondary></indexterm>
 </para>
     <para>A command can have multiple <emphasis>options</emphasis>, which can be <emphasis>arguments</emphasis> or
     <emphasis>flags</emphasis>:</para>
     <itemizedlist>
       <listitem><para>Arguments are used to supply additional information for use by the command.
-      
+
 <indexterm><primary>arguments to AFS commands</primary></indexterm>
  They consist of a paired <emphasis>switch</emphasis> and <emphasis>instance</emphasis>.
-      
+
 <indexterm><primary>switches on AFS commands</primary><secondary>defined</secondary></indexterm>
+
 <indexterm><primary>instances to AFS commands</primary></indexterm>
  A switch defines the type of argument and is always preceded
       by a hyphen; arguments can take multiple instances if a plus sign (+) appears after the instance. An instance
       represents some variable piece of information that is used by the command. Arguments can be optional or
       required.</para></listitem>
       <listitem><para>Flags are used to direct a command to perform in a specific way (for example, to generate a
-      specific type of output). 
+      specific type of output).
 <indexterm><primary>flags on AFS commands</primary></indexterm>
  Flags are always preceded by a hyphen and are always
       optional.</para></listitem>
@@ -65,7 +65,7 @@
       the File Server process to set an access control list.</para></listitem>
       <listitem><para>
         <emphasis role="bold">-dir $HOME</emphasis> and <emphasis role="bold">-acl pat all terry none</emphasis> are
-        <emphasis>arguments</emphasis>. 
+        <emphasis>arguments</emphasis>.
         </para><itemizedlist>
           <listitem><para><emphasis role="bold">-dir</emphasis> and <emphasis role="bold">-acl</emphasis> are switches;
           <emphasis role="bold">-dir</emphasis> indicates the name of the directory on which to set the ACL, and
@@ -88,9 +88,9 @@
     <para>Type all AFS commands on one line, followed by a carriage return. Some commands in this document appear on
     more than one line, but that is for legibility only.</para>
     </sect2><sect2 id="Header_172"><title>Abbreviations and Aliases for Operation Codes</title>
-    
+
 <indexterm><primary>operation codes in AFS commands</primary><secondary>abbreviating</secondary></indexterm>
+
     <para>You can type operation codes in one of three ways:</para>
     <itemizedlist>
       <listitem><para>You can type the operation code in full.</para></listitem>
     <para>The <emphasis>OpenAFS Administration Reference</emphasis> provides information on the full and abbreviated
     command syntax as well as any aliases for all of the commands discussed in this guide.</para>
     </sect2><sect2 id="Header_173"><title>Omitting Argument Switches</title>
-    
+
 <indexterm><primary>switches on AFS commands</primary><secondary>omitting</secondary></indexterm>
+
     <para>You can omit an argument's switch if the command takes only one argument, or if the following conditions are
     met.</para>
     <itemizedlist>
     <para>If the current working directory is <emphasis role="bold">terry</emphasis>'s home directory, he can issue the
     following command.</para>
 <programlisting>
-   % <emphasis role="bold">fs setacl -dir  .  -acl pat rl</emphasis> 
+   % <emphasis role="bold">fs setacl -dir  .  -acl pat rl</emphasis>
 </programlisting>
     <para>Both of the previous examples are acceptable short forms for the following command:</para>
 <programlisting>
     <emphasis role="bold">pts</emphasis> commands. For more detailed information, see the <emphasis>OpenAFS
     Administration Reference</emphasis>.</para>
     <sect2 id="Header_177"><title>About the fs Commands</title>
-    
+
 <indexterm><primary>fs commands</primary><secondary>introduction</secondary></indexterm>
+
     <para>Some <emphasis role="bold">fs</emphasis> commands extend UNIX file system semantics by invoking file-related
     functions that UNIX does not provide (setting access control lists, for example). Other
     <emphasis role="bold">fs</emphasis> commands help you control the performance of the Cache Manager running on your
-    local client machine. 
+    local client machine.
 <indexterm><primary>fs commands</primary><secondary>help flag</secondary></indexterm>
+
 <indexterm><primary>fs commands</primary><secondary>getting help</secondary></indexterm>
 </para>
     <para>All <emphasis role="bold">fs</emphasis> commands accept the optional <emphasis role="bold">-help</emphasis>
     flag. It has the same function as the <emphasis role="bold">fs help</emphasis> command: it prints a command's
     online help message on the screen. Do not provide other options at the same time as this flag. It overrides them,
-    and the only effect of issuing the command is to display the help message. 
+    and the only effect of issuing the command is to display the help message.
 <indexterm><primary>fs commands</primary><secondary>privileges required</secondary></indexterm>
 </para>
     <para>The privilege required for issuing <emphasis role="bold">fs</emphasis> commands varies. The necessary
       not require any special privilege.</para></listitem>
     </itemizedlist>
     </sect2><sect2 id="Header_178"><title>About the pts Commands</title>
-    
+
 <indexterm><primary>pts commands</primary><secondary>privilege required</secondary></indexterm>
+
 <indexterm><primary>Protection Database</primary></indexterm>
+
     <para>The <emphasis role="bold">pts</emphasis> command suite is the interface through which you can create
     protection groups and add members to them. System administrators who belong to a special system group called
     <emphasis role="bold">system:administrators</emphasis> group can manipulate any group, and also create the user and
     command descriptions in the <emphasis>OpenAFS Administration Reference</emphasis> and are described here in
     detail:</para>
     <variablelist>
-      
+
 <indexterm><primary>pts commands</primary><secondary>cell argument</secondary></indexterm>
 
       <varlistentry><term><emphasis role="bold">[-cell &lt;<replaceable>cell name</replaceable>&gt;]</emphasis></term>
         This argument indicates that the command runs in the indicated cell. The issuer can abbreviate the
         <replaceable>cell name</replaceable> value to the shortest form that distinguishes it from the other cells
         listed in the <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> file on the client machine on which the
-        command is issued. By default, commands are executed in the local cell as defined 
+        command is issued. By default, commands are executed in the local cell as defined
         </para><itemizedlist>
           <listitem><para>First, by the value of the environment variable AFSCELL. (This variable is normally not
           defined by default. If you are working in another, nonlocal cell for an extended period of time, you can set
       <varlistentry><term><emphasis role="bold">[-force]</emphasis></term>
       <listitem><para>This flag directs the <emphasis role="bold">pts</emphasis> command interpreter to continue
       executing the command, if possible, even if it encounters problems during the command's execution.
-      
+
 <indexterm><primary>pts commands</primary><secondary>force flag</secondary></indexterm>
  The command interpreter performs as much of the requested operation as possible, rather
       than halting if it encounters a problem. The command interpreter reports any errors it encounters during the
       arguments.</para></listitem></varlistentry>
     </variablelist>
     <variablelist>
-      <varlistentry><term><emphasis role="bold">[-help] 
+      <varlistentry><term><emphasis role="bold">[-help]
 <indexterm><primary>pts commands</primary><secondary>help flag</secondary></indexterm>
 
-      
+
 <indexterm><primary>pts commands</primary><secondary>getting help</secondary></indexterm>
 </emphasis></term>
       <listitem><para>This flag has the same function as the <emphasis role="bold">pts help</emphasis> command: it
       message.</para></listitem></varlistentry>
     </variablelist>
     </sect2></sect1><sect1 id="HDRWQ89"><title>Getting Help in AFS</title>
-    
+
 <indexterm><primary>help</primary><secondary>online for AFS commands</secondary></indexterm>
+
 <indexterm><primary>online help</primary></indexterm>
+
     <para>AFS online help consists of basic syntax messages. The AFS distribution also includes help in HTML format
     which your system administrator can make available to you.</para>
     <sect2 id="Header_180"><title>Displaying Command Syntax and Aliases</title>
-    
+
 <indexterm><primary>apropos operation code</primary></indexterm>
+
 <indexterm><primary>help</primary><secondary>operation code in AFS command suites</secondary></indexterm>
+
 <indexterm><primary>help</primary><secondary>examples</secondary></indexterm>
+
     <para>To display a brief description of a command, its syntax statement, and alias if any, use the
     <emphasis role="bold">help</emphasis> operation code. For example, to display the online help entry for the
     <emphasis role="bold">fs listacl</emphasis> command, enter the following command:</para>
 <programlisting>
    % <emphasis role="bold">fs help listacl</emphasis>
-   fs listacl: list access control list 
+   fs listacl: list access control list
    aliases: la
    Usage: fs listacl  [-path &lt;dir/file path&gt;+]  [-id] [-if] [-help]
 </programlisting>
     setacl</emphasis> command, enter the following command:</para>
 <programlisting>
    % <emphasis role="bold">fs setacl -help</emphasis>
-   Usage: fs setacl -dir &lt;directory&gt;+ -acl &lt;access list entries&gt;+ [-clear] [-negative] 
+   Usage: fs setacl -dir &lt;directory&gt;+ -acl &lt;access list entries&gt;+ [-clear] [-negative]
    [-id] [-if] [-help]
 </programlisting>
     </sect2><sect2 id="Header_181"><title>Displaying Operation Code Descriptions</title>
     <para>To display a short description of all of a command suite's operation codes, issue the
     <emphasis role="bold">help</emphasis> operation code without any other arguments. For example, the
     <emphasis role="bold">fs help</emphasis> command displays a short description of every operation code in the
-    <emphasis role="bold">fs</emphasis> command suite. 
+    <emphasis role="bold">fs</emphasis> command suite.
 <indexterm><primary>keyword for apropos command</primary></indexterm>
 </para>
     <para>To display a list of the commands in a command suite that concern a certain type of object, provide a
index 3fc6780..d5bd028 100644 (file)
@@ -82,8 +82,8 @@
       <glossterm><emphasis role="bold">Authenticate</emphasis></glossterm>
 
       <glossdef>
-        <para>To become recognized as a valid AFS user by providing the correct password. Authenticate by logging onto a machine
-        that uses an AFS-modified login utility or by issuing the <emphasis role="bold">klog</emphasis> command. Only authenticated
+        <para>To become recognized as a valid AFS user by getting an AFS token using your kerberos TGT. Authenticate by logging onto a machine
+        that uses an AFS enabled login utility or by issuing the <emphasis role="bold">aklog</emphasis> command after using <emphasis role="bold">kinit</emphasis> to obtain a kerberos TGT. Only authenticated
         users can perform most AFS actions.</para>
       </glossdef>
     </glossentry>