Added k5identity doc in RST format.

git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@25648 dc483132-0cff-0310-8789-dd5450dbe970

doc/rst_source/conf.py

@@ -225,7 +225,10 @@
     ('krb_users/user_commands/kpasswd', 'kpasswd', u'change a user\'s Kerberos password', [u'MIT'], 1),
     ('krb_users/user_commands/kvno', 'kvno', u'print key version numbers of Kerberos principals', [u'MIT'], 1),
     ('krb_users/user_commands/ksu', 'ksu', u'Kerberized super-user', [u'MIT'], 1),
-    ('krb_users/user_commands/k5login', 'k5login', u'Kerberos V5 acl file for host access', [u'MIT'], 5),
+    ('krb_users/user_commands/k5login', '.k5login', u'', [u'MIT'], 5),
+    ('krb_users/user_commands/k5login', 'k5login', u'.k5login - Kerberos V5 acl file for host access', [u'MIT'], 5),
+    ('krb_users/user_commands/k5identity', '.k5identity', u'', [u'MIT'], 5),
+    ('krb_users/user_commands/k5identity', 'k5identity', u'.k5identity - Kerberos V5 client principal selection rules', [u'MIT'], 5),
     ('krb_admins/admin_commands/krb5kdc', 'krb5kdc', u'Kerberos V5 KDC', [u'MIT'], 8),
     ('krb_admins/admin_commands/kadmin_local', 'kadmin', u'Kerberos V5 database administration program', [u'MIT'], 1),
     ('krb_admins/admin_commands/kprop', 'kprop', u'propagate a Kerberos V5 principal database to a slave server', [u'MIT'], 8),

doc/rst_source/krb_admins/install_kdc/slave_install.rst

@@ -97,9 +97,6 @@ Since in our case the updates should only come from *kerberos.mit.edu* server,
 Then, add the following line to */etc/inetd.conf* file on each KDC (Adjust the path to *kpropd*)::
 
      krb5_prop stream tcp nowait root /usr/local/sbin/kpropd kpropd
-     eklogin stream tcp nowait root  /usr/local/sbin/klogind klogind -5 -c -e
-
-     
 
 You also need to add the following lines to */etc/services* on each KDC (assuming that default ports are used)::
 

doc/rst_source/krb_users/user_commands/index.rst

@@ -17,6 +17,7 @@ User commands
    kvno.rst
    ksu.rst
    k5login.rst
+   k5identity.rst
    ../../krb_admins/admin_commands/kadmin_local.rst
    ../../krb_admins/admin_commands/k5srvutil.rst
    sclient.rst

doc/rst_source/krb_users/user_commands/k5identity.rst

@@ -0,0 +1,59 @@
+.k5identity - Kerberos V5 client principal selection rules
+===============================================================
+
+DESCRIPTION
+-------------
+
+The *.k5identity*  file, which resides in a user's home directory, 
+contains a list of rules for selecting a client principals based on 
+the server being accessed. These rules are used to choose a credential 
+cache within the cache collection when possible.
+
+Blank lines and lines beginning with '#' are ignored.  Each line has the form:
+
+        principal field=value ...
+
+If the server principal meets all of the field constraints, then principal 
+is chosen as the client principal.  The following fields are recognized:
+
+**realm**  
+        If the realm of the server principal is known, it is matched
+        against *value*, which may be a pattern using shell wildcards.
+        For host-based server principals, the realm will generally only
+        be known if there is a :ref:`domain_realm` section 
+        in :ref:`krb5.conf` with a mapping for the hostname.
+
+**service**
+        If the server principal is a host-based principal,
+        its service component is matched against *value*, which may be
+        a pattern using shell wildcards.
+
+**host** 
+       If the server principal is a host-based principal,
+       its hostname component is converted to lower case and matched
+       against *value*, which may be a pattern using shell wildcards.
+
+       If  the server principal matches the constraints of multiple lines
+       in the .k5identity file, the principal from the first matching line is used.
+       If no line  matches, credentials will be selected some other way,
+       such as the realm heuristic or the current primary cache.
+
+EXAMPLE
+-----------
+
+The following example .k5identity file selects the client principal
+alice\@KRBTEST.COM if the server principal is within that realm,
+the principal alice/root\@EXAMPLE.COM if the server host is within
+a servers subdomain, and the principal alice/mail\@EXAMPLE.COM
+when accessing the IMAP service on mail.example.com::
+
+        alice@KRBTEST.COM       realm=KRBTEST.COM
+        alice/root@EXAMPLE.COM  host=*.servers.example.com
+        alice/mail@EXAMPLE.COM  host=mail.example.com service=imap
+
+SEE ALSO
+----------
+
+kerberos(1), krb5.conf(5)
+
+

doc/rst_source/krb_users/user_commands/k5login.rst

@@ -4,34 +4,41 @@
 DESCRIPTION
 --------------
 
-The *.k5login* file, which resides in a user's home directory, contains a list of the Kerberos principals.
-Anyone with valid tickets for a principal in the file is allowed host access with the UID of the user in whose home directory the file resides.  
-One common use is to place a *.k5login* file in root's home directory, thereby granting system administrators remote root access to the host via Kerberos.
+The *.k5login* file, which resides in a user's home directory, 
+contains a list of the Kerberos principals.
+Anyone with valid tickets for a principal in the file is allowed host access 
+with the UID of the user in whose home directory the file resides.  
+One common use is to place a *.k5login* file in root's home directory, 
+thereby granting system administrators remote root access to the host via Kerberos.
 
 EXAMPLES
 -----------
 
-Suppose the user "alice" had a *.k5login* file in her home directory containing the following line:
+Suppose the user *alice* had a *.k5login* file in her home directory containing the following line:
 
-                 bob\@FUBAR.ORG
+        bob\@FOOBAR.ORG
 
-This  would  allow  "bob"  to use any of the Kerberos network applications, such as telnet(1), rlogin(1), rsh(1), and rcp(1), 
-to access alice's account, using bob's Kerberos tickets.
+This would allow *bob* to use any of the Kerberos network applications, 
+such as telnet(1), rlogin(1), rsh(1), and rcp(1), 
+to access *alice*'s account, using *bob*'s Kerberos tickets.
 
-Let us further suppose that "alice" is a system administrator.  
-Alice and the other system administrators would have  their  principals in root's *.k5login* file on each host:
+Let us further suppose that *alice* is a system administrator.
+Alice and the other system administrators would have their principals
+in root's *.k5login* file on each host:
 
-                 alice\@BLEEP.COM
+        alice\@BLEEP.COM
 
-                 joeadmin/root\@BLEEP.COM
+        joeadmin/root\@BLEEP.COM
 
-This  would  allow either system administrator to log in to these hosts using their Kerberos tickets instead of having to type the root password.  
-Note that because "bob" retains the Kerberos tickets for his own principal, "bob\@FUBAR.ORG", 
-he would not have  any  of  the privileges that require alice's tickets, such as root access to any of the site's hosts, 
-or the ability to change alice's password.
+This would allow either system administrator to log in to these hosts 
+using their Kerberos tickets instead of having to type the root password.  
+Note that because *bob* retains the Kerberos tickets for his own principal, 
+"bob\@FOOBAR.ORG", he would not have any of the privileges that require *alice*'s tickets, 
+such as root access to any of the site's hosts, 
+or the ability to change *alice*'s password.
 
 SEE ALSO
 -----------
 
-telnet(1), rlogin(1), rsh(1), rcp(1), ksu(1), telnetd(8), klogind(8)
+telnet(1), rlogin(1), rsh(1), rcp(1), ksu(1), telnetd(8)