From: Zhanna Tsitkov Date: Fri, 5 Aug 2011 16:59:52 +0000 (+0000) Subject: Added .k5login, k5srvutil, ktutil, kadmind manual documnets to Sphins doc tree X-Git-Tag: krb5-1.10-alpha1~302 X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=b0b94b9330fbf671da6c9dcd06d3b07eab4c63c6;p=krb5.git Added .k5login, k5srvutil, ktutil, kadmind manual documnets to Sphins doc tree git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@25073 dc483132-0cff-0310-8789-dd5450dbe970 --- diff --git a/doc/rst_source/conf.py b/doc/rst_source/conf.py index 0933a77b7..d7719d057 100644 --- a/doc/rst_source/conf.py +++ b/doc/rst_source/conf.py @@ -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), ] diff --git a/doc/rst_source/krb_admins/admin_commands/index.rst b/doc/rst_source/krb_admins/admin_commands/index.rst index 3ddc86d99..00f64f73e 100644 --- a/doc/rst_source/krb_admins/admin_commands/index.rst +++ b/doc/rst_source/krb_admins/admin_commands/index.rst @@ -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 index 000000000..a5dd45e5c --- /dev/null +++ b/doc/rst_source/krb_admins/admin_commands/k5srvutil.rst @@ -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) + + diff --git a/doc/rst_source/krb_admins/admin_commands/kadmin_local.rst b/doc/rst_source/krb_admins/admin_commands/kadmin_local.rst index 8710be4ba..8957013fd 100644 --- a/doc/rst_source/krb_admins/admin_commands/kadmin_local.rst +++ b/doc/rst_source/krb_admins/admin_commands/kadmin_local.rst @@ -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 index 000000000..4c7144aa5 --- /dev/null +++ b/doc/rst_source/krb_admins/admin_commands/kadmind.rst @@ -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* = + specifies the number of connections to be maintained per LDAP server. + + **-x** *host* = + specifies the LDAP server to connect to by a LDAP URI. + + **-x** *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* = + 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 + +.kadm5 KADM5 administrative database. (This would be "principal.kadm5", if you use the default database name.) Contains policy information. + +.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 index 000000000..5324d5e9a --- /dev/null +++ b/doc/rst_source/krb_admins/admin_commands/ktutil.rst @@ -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) + diff --git a/doc/rst_source/krb_users/user_commands/index.rst b/doc/rst_source/krb_users/user_commands/index.rst index 6ae62d2a6..5232eb818 100644 --- a/doc/rst_source/krb_users/user_commands/index.rst +++ b/doc/rst_source/krb_users/user_commands/index.rst @@ -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 index 000000000..f40aae15c --- /dev/null +++ b/doc/rst_source/krb_users/user_commands/k5login.rst @@ -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) +