Added .k5login, k5srvutil, ktutil, kadmind manual documnets to Sphins doc tree
authorZhanna Tsitkov <tsitkova@mit.edu>
Fri, 5 Aug 2011 16:59:52 +0000 (16:59 +0000)
committerZhanna Tsitkov <tsitkova@mit.edu>
Fri, 5 Aug 2011 16:59:52 +0000 (16:59 +0000)
git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@25073 dc483132-0cff-0310-8789-dd5450dbe970

doc/rst_source/conf.py
doc/rst_source/krb_admins/admin_commands/index.rst
doc/rst_source/krb_admins/admin_commands/k5srvutil.rst [new file with mode: 0644]
doc/rst_source/krb_admins/admin_commands/kadmin_local.rst
doc/rst_source/krb_admins/admin_commands/kadmind.rst [new file with mode: 0644]
doc/rst_source/krb_admins/admin_commands/ktutil.rst [new file with mode: 0644]
doc/rst_source/krb_users/user_commands/index.rst
doc/rst_source/krb_users/user_commands/k5login.rst [new file with mode: 0644]

index 0933a77b7b4205f3d58e02a194c9071a0a8e3797..d7719d05768fef7101d0745c44939cd83992dc9f 100644 (file)
@@ -224,6 +224,7 @@ man_pages = [
     ('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_admins/admin_commands/krb5kdc', 'krb5kdc', u'Kerberos V5 KDC', [u'MIT'], 8),
     ('krb_admins/admin_commands/kadmin_local', 'kadmin.local', u'Kerberos V5 database administration program', [u'MIT'], 8),
     ('krb_admins/admin_commands/kadmin_local', 'kadmin', u'Kerberos V5 database administration program', [u'MIT'], 1),
@@ -231,4 +232,7 @@ man_pages = [
     ('krb_admins/admin_commands/kproplog', 'kproplog', u'display the contents of the Kerberos principal update log', [u'MIT'], 8),
     ('krb_admins/admin_commands/kpropd', 'kpropd', u'Kerberos V5 slave KDC update server', [u'MIT'], 8),
     ('krb_admins/admin_commands/kdb5_util', 'kdb5_util', u'Kerberos database maintenance utility', [u'MIT'], 8),
+    ('krb_admins/admin_commands/ktutil', 'ktutil', u'Kerberos keytab file maintenance utility', [u'MIT'], 1),
+    ('krb_admins/admin_commands/k5srvutil', 'k5srvutil', u'host key table (keytab) manipulation utility', [u'MIT'], 1),
+    ('krb_admins/admin_commands/kadmind', 'kadmind', u'KADM5 administration server', [u'MIT'], 8),
 ]
index 3ddc86d9952ea5e42e594cd9e2398b53add69eb3..00f64f73e48c1c42fef064d23a3fd3c884df3279 100644 (file)
@@ -13,6 +13,9 @@ Administration  programs
    kpropd.rst
    kproplog.rst
    kdb5_util.rst
+   ktutil.rst
+   k5srvutil.rst
+   kadmind.rst
 
 ------------
 
diff --git a/doc/rst_source/krb_admins/admin_commands/k5srvutil.rst b/doc/rst_source/krb_admins/admin_commands/k5srvutil.rst
new file mode 100644 (file)
index 0000000..a5dd45e
--- /dev/null
@@ -0,0 +1,49 @@
+k5srvutil - host key table (keytab) manipulation utility
+=============================================================
+
+SYNOPSIS
+----------
+
+**k5srvutil** *operation* [ **-i** ] [ **-f** *filename* ]
+
+DESCRIPTION
+-------------
+
+*k5srvutil* allows a system manager to list or change keys currently in his keytab or to add new keys to the keytab.
+
+Operation must be one of the following:
+
+       **list**
+                 Lists the keys in a keytab showing version number and principal name.
+
+       **change**
+                 Changes all the keys in the keytab to new randomly-generated keys,
+                 updating the keys in the Kerberos server's database to match by using the kadmin protocol.
+                 If a key's version number doesn't match the version number stored in the Kerberos server's database,
+                 then the operation will fail. The old keys are retained so that existing tickets continue to work.
+                 If the *-i* flag is given, *k5srvutil* will prompt for yes or no before changing each key.
+                 If the *-k* option is used, the old and new keys will be displayed.
+
+       **delold**
+                 Deletes keys that are not the most recent version from the keytab.
+                 This operation should be used some time after a change operation to remove old keys.
+                 If the *-i* flag is used, then the program prompts the user whether the old keys associated
+                 with each principal should be removed.
+
+       **delete**
+                 Deletes particular keys in the keytab, interactively prompting for each key.
+
+
+In all cases, the default file used is /etc/krb5.keytab file unless this is overridden by the **-f** option.
+
+
+*k5srvutil*  uses the kadmin program to edit the keytab in place.
+However, old keys are retained, so they are available in case of failure.
+
+
+SEE ALSO
+-------------
+
+kadmin(8), ktutil(8)
+
+
index 8710be4ba4b35aacd4d2067c0bb94e85fb100765..8957013fd136cea0e88e269c7c498dd208b46825 100644 (file)
@@ -685,7 +685,7 @@ principal.db            default name for Kerberos principal database
 NOTE: The above three files are specific to db2 database.
 
 ====================== =================================================
-kadm5.acl               File containing list of principals and their *kadmin* administrative privileges.  See kadmind(8) for a description.
+kadm5.acl               File containing list of principals and their *kadmin* administrative privileges.  See :ref:`kadmind(8)` for a description.
 kadm5.keytab            *keytab* file for *kadmin/admin* principal.
 kadm5.dict              file containing dictionary of strings explicitly disallowed as passwords.
 ====================== =================================================
diff --git a/doc/rst_source/krb_admins/admin_commands/kadmind.rst b/doc/rst_source/krb_admins/admin_commands/kadmind.rst
new file mode 100644 (file)
index 0000000..4c7144a
--- /dev/null
@@ -0,0 +1,188 @@
+.. _kadmind(8):
+
+kadmind
+==========
+
+SYNOPSIS
+-----------
+       
+**kadmind** [**-x** *db_args*] [**-r** *realm*] [**-m**] [**-nofork**] [**-port** *port-number*] [**-P** *pid_file*]
+
+DESCRIPTION
+-----------
+
+This command starts the KADM5 administration server. If the database is db2, the administration server runs on the master Kerberos server, 
+which stores the KDC prinicpal database and the KADM5 policy database. If the database is LDAP, the administration server and
+the KDC server need not run on the same machine.  *kadmind* accepts remote requests to administer the information in these databases.
+Remote requests are sent, for example, by kadmin(8) and the kpasswd(1) command, both of which are clients of *kadmind*.
+
+*kadmind* requires a number of configuration files to be set up in order for it to work:
+
+:ref:`kdc.conf`  
+            The KDC configuration file contains configuration informatin for the KDC and the KADM5 system.  *kadmind* understands a number
+            of  variable  settings in this file, some of whch are mandatory and some of which are optional.
+            See the CONFIGURATION VALUES section below.
+
+*keytab*    
+            Kadmind requires a keytab containing correct entries for the kadmin/admin and kadmin/changepw principals for every realm that
+            *kadmind* will answer requests for.  The keytab can be created with the kadmin(8) client.
+            The location of the keytab is determined by the *admin_keytab* configuration variable (see CONFIGURATION VALUES).
+
+*ACL* file 
+            *kadmind*'s *ACL* (access control list) tells it which principals are allowed to perform KADM5 administration actions.
+            The  path of  the *ACL* file is specified via the acl_file configuration variable (see CONFIGURATION VALUES).
+            The syntax of the *ACL* file is specified in the *ACL* FILE SYNTAX section below.
+
+After the server begins running, it puts itself in the background and disassociates itself from its controlling terminal.
+
+*kadmind* can be configured for incremental database propagation.  Incremental propagation allows slave KDC servers to receive  principal
+and  policy  updates  incrementally instead of receiving full dumps of the database.  This facility can be enabled in the :ref:`kdc.conf` file
+with the *iprop_enable* option.  See the :ref:`kdc.conf` documentation for other options for tuning incremental propagation parameters.
+Incremental propagation requires the principal "kiprop/MASTER\@REALM" i
+(where MASTER is the master KDC's canonical host name, and REALM the realm name) to be registered in the database.
+
+
+OPTIONS
+-----------
+
+       **-x** *db_args*
+              specifies the database specific arguments.
+
+              Options supported for LDAP database are:
+
+                   **-x** *nconns* =<number_of_connections>
+                          specifies the number of connections to be maintained per LDAP server.
+
+                   **-x** *host* =<ldapuri>
+                          specifies the LDAP server to connect to by a LDAP URI.
+
+                   **-x** *binddn* =<binddn>
+                          specifies the DN of the object used by the administration server to bind to the LDAP server.  This object should have the
+                          read and write rights on the realm container, principal container and the subtree that is referenced by the realm.
+
+                   **-x** *bindpwd* =<bind_password>
+                          specifies the password for the above mentioned binddn. It is recommended not to use this option.
+                          Instead, the password can be stashed using the stashsrvpw command of kdb5_ldap_util.
+
+       **-r** *realm*
+              specifies the default realm that *kadmind* will serve; if it is not specified, the default realm of the host is used.
+              *kadmind* will answer requests for any realm that exists in the local KDC database and for which the appropriate principals are in its keytab.
+
+       **-m**
+              specifies that the master database password should be fetched from the keyboard rather than from a file on disk.
+              Note that the server gets the password prior to putting itself in the background; 
+              in combination with the *-nofork* option, you must place it in the background by hand.
+
+       **-nofork**
+              specifies that the server does not put itself in the background and does not disassociate itself from the terminal.
+              In normal operation, you should always allow the server place itself in the background.
+
+       **-port** *port-number*
+              specifies the port on which the administration server listens for connections.  The default is is controlled by the *kadmind_port*
+              configuration variable (see below).
+
+       **-P** *pid_file*
+              specifies the file to which the PID of *kadmind* process should be written to after it starts up.  This can be used to identify
+              whether *kadmind* is still running and to allow init scripts to stop the correct process.
+
+CONFIGURATION VALUES
+---------------------------
+
+In addition to the relations defined in kdc.conf(5), *kadmind* understands the following relations, 
+all of which should appear in the [realms] section:
+
+       **acl_file**
+              The path of *kadmind*'s *ACL* file.  **Mandatory**.  No default.
+
+       **admin_keytab**
+              The  name  of  the keytab containing entries for the principals kadmin/admin and kadmin/changepw in each realm that *kadmind* will
+              serve.  The default is the value of the KRB5_KTNAME environment variable, if defined.  **Mandatory**.
+
+       **dict_file**
+              The path of *kadmind*'s password dictionary.  A principal with any password policy will not be allowed to select any  password  in
+              the dictionary.  Optional.  No default.
+
+       **kadmind_port**
+              The TCP port on which *kadmind* will listen.  The default is 749.
+
+*ACL* FILE SYNTAX
+-------------------
+
+The *ACL* file controls which principals can or cannot perform which administrative functions.  For operations  that  affect  principals,
+the  *ACL* file also controls which principals can operate on which other principals.  This file can contain comment lines, null lines or
+lines which contain *ACL* entries.  Comment lines start with the sharp sign (#) and continue until the end of the line.  
+Lines containing *ACL* entries have the format of principal whitespace *operation-mask* [whitespace *operation-target*]
+
+Ordering  is important.  The first matching entry is the one which will control access for a particular principal on a particular principal.
+
+       **principal**
+              may specify a partially or fully qualified Kerberos version 5 principal name.  Each component of  the  name  may  be  wildcarded
+              using the asterisk ( * ) character.
+
+       **operation-target**
+              [Optional]  may specify a partially or fully qualified Kerberos version 5 principal name.  Each component of the name may be
+              wildcarded using the asterisk ( \* ) character.
+
+       **operation-mask**
+              Specifies what operations may or may not be peformed by a principal matching a particular entry.  This is a string of one or
+              more of the following list of characters or their upper-case counterparts.  If the character is upper-case, then the operation
+              is disallowed.  If the character is lower-case, then the operation is permitted.
+
+              ::
+
+                  a    [Dis]allows the addition of principals or policies in the database.
+                  d    [Dis]allows the deletion of principals or policies in the database.
+                  m    [Dis]allows the modification of principals or policies in the database.
+                  c    [Dis]allows the changing of passwords for principals in the database.
+                  i    [Dis]allows inquiries to the database.
+                  l    [Dis]allows the listing of principals or policies in the database.
+                  p    [Dis]allows the propagation of the principal database.
+                  x    Short for admcil.
+                  *    Same as x.
+       
+Some examples of valid entries here are:
+
+*user/instance@realm adm*
+              A standard fully qualified name.  The *operation-mask* only applies to this principal and specifies that [s]he may add, delete  or
+              modify principals and policies, but not change anybody else's password.
+
+*user/instance@realm cim service/instance@realm*
+              A  standard fully qualified name and a standard fully qualified target.  The *operation-mask* only applies to this principal oper‐
+              ating on this target and specifies that [s]he may change the target's password, request information about the target and  modify
+              it.
+
+*user/\*@realm ac*
+              A  wildcarded name.  The *operation-mask* applies to all principals in realm "realm" whose first component is "user" and specifies
+              that [s]he may add principals and change anybody's password.
+
+*user/\*@realm i \*/instance@realm*
+              A wildcarded name and target.  The *operation-mask* applies to all principals in realm "realm" whose first component is "user" and
+              specifies that [s]he may perform inquiries on principals whose second component is "instance" and realm is "realm".
+
+FILES
+-----------
+
+=================== ===================================================================
+principal.db        default name for Kerberos principal database
+
+<dbname>.kadm5      KADM5  administrative database.  (This would be "principal.kadm5", if you use the default database name.)  Contains policy information.
+
+<dbname>.kadm5.lock lock file for the KADM5 administrative database.  This file works backwards from most other lock files.  I.e., kadmin will exit with an error if this file does not exist.
+=================== ===================================================================
+
+Note: The above three files are specific to db2 database.
+
+=================== ===================================================================
+kadm5.acl           file containing list of principals and their kadmin administrative privileges.  See above for a description.
+
+kadm5.keytab        keytab file for *kadmin/admin* principal.
+
+kadm5.dict          file containing dictionary of strings explicitly disallowed as passwords.
+=================== ===================================================================
+
+SEE ALSO
+-----------
+
+kpasswd(1), kadmin(8), kdb5_util(8), kadm5_export(8), kadm5_import(8), kdb5_ldap_util(8)
+
+
diff --git a/doc/rst_source/krb_admins/admin_commands/ktutil.rst b/doc/rst_source/krb_admins/admin_commands/ktutil.rst
new file mode 100644 (file)
index 0000000..5324d5e
--- /dev/null
@@ -0,0 +1,72 @@
+ktutil
+=============
+
+
+SYNOPSIS
+-------------
+
+**ktutil**
+
+DESCRIPTION
+-------------
+
+The *ktutil* command invokes a subshell from which an administrator can read, write, or edit entries in a Kerberos V5 keytab or V4 srvtab file.
+
+COMMANDS
+-------------
+
+       **list**   
+              Displays the current keylist.
+
+              Alias: **l**
+
+       **read_kt** *keytab*
+              Read the Kerberos V5 keytab file *keytab* into the current keylist.
+
+              Alias: **rkt**
+
+       **read_st** *srvtab*
+              Read the Kerberos V4 srvtab file *srvtab* into the current keylist.
+
+              Alias: **rst**
+
+       **write_kt** *keytab*
+              Write the current keylist into the Kerberos V5 keytab file *keytab*.
+
+              Alias: **wkt**
+
+       **write_st** *srvtab*
+              Write the current keylist into the Kerberos V4 srvtab file *srvtab*.
+
+              Alias: **wst**
+
+       **clear_list**
+              Clear the current keylist.
+
+              Alias: **clear**
+
+       **delete_entry** *slot*
+              Delete the entry in slot number *slot* from the current keylist.
+
+              Alias: *delent*
+
+       **add_entry** (**-key | -password)** **-p** *principal* **-k** *kvno* **-e** *enctype*
+              Add *principal* to keylist using key or password.
+
+              Alias: **addent**
+
+       **list_requests**
+              Displays a listing of available commands.
+
+              Aliases: **lr**, **?**
+
+       **quit**
+              Quits ktutil.
+
+              Aliases: **exit**, **q**
+
+SEE ALSO
+-------------
+
+       kadmin(8), kdb5_util(8)
+
index 6ae62d2a6a07c49d921a1e3026bdd3e67449bb5b..5232eb818e769e21ac57af4ed45a887993a0bc4b 100644 (file)
@@ -13,7 +13,9 @@ User commands
    kpasswd.rst
    kvno.rst
    ksu.rst
+   k5login.rst
    ../../krb_admins/admin_commands/kadmin_local.rst
+   ../../krb_admins/admin_commands/k5srvutil.rst
 
 
 ------------------
diff --git a/doc/rst_source/krb_users/user_commands/k5login.rst b/doc/rst_source/krb_users/user_commands/k5login.rst
new file mode 100644 (file)
index 0000000..f40aae1
--- /dev/null
@@ -0,0 +1,37 @@
+.k5login - Kerberos V5 acl file for host access
+===================================================
+
+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.
+
+EXAMPLES
+-----------
+
+Suppose the user "alice" had a *.k5login* file in her home directory containing the following line:
+
+                 bob\@FUBAR.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.
+
+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
+
+                 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.
+
+SEE ALSO
+-----------
+
+telnet(1), rlogin(1), rsh(1), rcp(1), ksu(1), telnetd(8), klogind(8)
+