From: Greg Hudson Date: Mon, 27 Feb 2012 04:48:54 +0000 (+0000) Subject: Improve man page references in RST documentation X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=fe44da52deea41483326debf2d9ad525f65e19f6;p=krb5.git Improve man page references in RST documentation Give each command and config file a reference label, and change many uses of command names and config file names to be references. git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@25714 dc483132-0cff-0310-8789-dd5450dbe970 --- diff --git a/doc/rst_source/krb_admins/admin_commands/k5srvutil.rst b/doc/rst_source/krb_admins/admin_commands/k5srvutil.rst index f611d2c4e..ebd7a5660 100644 --- a/doc/rst_source/krb_admins/admin_commands/k5srvutil.rst +++ b/doc/rst_source/krb_admins/admin_commands/k5srvutil.rst @@ -46,12 +46,12 @@ his keytab or to add new keys to the keytab. 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. +k5srvutil uses the :ref:`kadmin(1)` 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) +:ref:`kadmin(1)`, :ref:`ktutil(1)` 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 3d9689634..3c78ad9a2 100644 --- a/doc/rst_source/krb_admins/admin_commands/kadmin_local.rst +++ b/doc/rst_source/krb_admins/admin_commands/kadmin_local.rst @@ -1,9 +1,7 @@ .. _kadmin(1): -.. _kadmin.local(1): - -kadmin, kadmin.local -==================== +kadmin +====== SYNOPSIS -------- @@ -66,9 +64,7 @@ kadmin.local can be configured to log updates 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. +the :ref:`kdc.conf(5)` file with the **iprop_enable** option. OPTIONS @@ -99,8 +95,8 @@ OPTIONS Requests anonymous processing. Two types of anonymous principals are supported. For fully anonymous Kerberos, configure pkinit on the KDC and configure **pkinit_anchors** in the client's - :ref:`krb5.conf`. Then use the **-n** option with a principal of - the form ``@REALM`` (an empty principal name followed by the + :ref:`krb5.conf(5)`. Then use the **-n** option with a principal + of the form ``@REALM`` (an empty principal name followed by the at-sign and a realm name). If permitted by the KDC, an anonymous ticket will be returned. A second form of anonymous tickets is supported; these realm-exposed tickets hide the identity of the @@ -924,7 +920,7 @@ The options are: key of the principal. The enctype-salttype pairs may be delimited with commas or whitespace. The quotes are necessary for whitespace-delimited list. If this option is not specified, then - **supported_enctypes** from :ref:`krb5.conf` will be used. See + **supported_enctypes** from :ref:`krb5.conf(5)` will be used. See :ref:`Supported_Encryption_Types_and_Salts` for all possible values. @@ -970,7 +966,7 @@ If the string "all" is specified, all entries for that principal are removed; if the string "old" is specified, all entries for that principal except those with the highest kvno are removed. Otherwise, the value specified is parsed as an integer, and all entries whose -*kvno* match that integer are removed. +kvno match that integer are removed. The options are: @@ -1042,4 +1038,4 @@ interface to the OpenVision Kerberos administration program. SEE ALSO -------- -kerberos(1), kpasswd(1), kadmind(8) +kerberos(1), :ref:`kpasswd(1)`, kadmind(8) diff --git a/doc/rst_source/krb_admins/admin_commands/kadmind.rst b/doc/rst_source/krb_admins/admin_commands/kadmind.rst index 248a0ff92..52ca28c1f 100644 --- a/doc/rst_source/krb_admins/admin_commands/kadmind.rst +++ b/doc/rst_source/krb_admins/admin_commands/kadmind.rst @@ -23,13 +23,13 @@ which stores the KDC principal 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. +sent, for example, by kadmin(8) and the :ref:`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` +:ref:`kdc.conf(5)` The KDC configuration file contains configuration information for the KDC and the KADM5 system. kadmind understands a number of variable settings in this file, some of which are mandatory and @@ -38,11 +38,11 @@ for it to work: 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). + ``kadmin/admin`` and ``kadmin/changepw`` principals for every + realm that kadmind will answer requests for. The keytab can be + created with the :ref:`kadmin(1)` 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 @@ -60,12 +60,11 @@ 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`` (where MASTER is the master KDC's canonical -host name, and REALM the realm name) to be registered in the database. +the database. This facility can be enabled in the :ref:`kdc.conf(5)` +file with the **iprop_enable** option. Incremental propagation +requires the principal ``kiprop/MASTER\@REALM`` (where MASTER is the +master KDC's canonical host name, and REALM the realm name) to be +registered in the database. OPTIONS @@ -131,7 +130,7 @@ OPTIONS CONFIGURATION VALUES -------------------- -In addition to the relations defined in kdc.conf(5), kadmind +In addition to the relations defined in :ref:`kdc.conf(5)`, kadmind understands the following relations, all of which should appear in the [realms] section: @@ -140,9 +139,9 @@ understands the following relations, all of which should appear in the **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**. + ``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 @@ -245,5 +244,5 @@ kadm5.dict file containing dictionary of strings explicitly disallowe SEE ALSO -------- -kpasswd(1), kadmin(8), kdb5_util(8), kadm5_export(8), kadm5_import(8), -kdb5_ldap_util(8) +:ref:`kpasswd(1)`, :ref:`kadmin(1)`, :ref:`kdb5_util(8)`, +:ref:`kdb5_ldap_util(8)` diff --git a/doc/rst_source/krb_admins/admin_commands/kdb5_ldap_util.rst b/doc/rst_source/krb_admins/admin_commands/kdb5_ldap_util.rst index e0b428df2..59304bf34 100644 --- a/doc/rst_source/krb_admins/admin_commands/kdb5_ldap_util.rst +++ b/doc/rst_source/krb_admins/admin_commands/kdb5_ldap_util.rst @@ -85,7 +85,7 @@ Creates realm in directory. Options: **-k** *mkeytype* Specifies the key type of the master key in the database; the - default is that given in kdc.conf. + default is that given in :ref:`kdc.conf(5)`. **-kv** *mkeyVNO* Specifies the version number of the master key in the database; @@ -997,4 +997,4 @@ EXAMPLE:: SEE ALSO -------- -kadmin(8) +:ref:`kadmin(1)` diff --git a/doc/rst_source/krb_admins/admin_commands/kdb5_util.rst b/doc/rst_source/krb_admins/admin_commands/kdb5_util.rst index ad1217b30..bc9c3c5b1 100644 --- a/doc/rst_source/krb_admins/admin_commands/kdb5_util.rst +++ b/doc/rst_source/krb_admins/admin_commands/kdb5_util.rst @@ -48,13 +48,13 @@ COMMAND-LINE OPTIONS **-d** *dbname* specifies the name under which the principal database is stored; - by default the database is that listed in :ref:`kdc.conf`. The + by default the database is that listed in :ref:`kdc.conf(5)`. The KADM5 policy database and lock file are also derived from this value. **-k** *mkeytype* specifies the key type of the master key in the database; the - default is that given in :ref:`kdc.conf`. + default is that given in :ref:`kdc.conf(5)`. **-kv** *mkeyVNO* Specifies the version number of the master key in the database; @@ -62,7 +62,7 @@ COMMAND-LINE OPTIONS **-M** *mkeyname* principal name for the master key in the database; the default is - that given in :ref:`kdc.conf`. + that given in :ref:`kdc.conf(5)`. **-m** specifies that the master database password should be read from @@ -267,7 +267,8 @@ the principal keys change, are newly created or when the **update_princ_encryption** command is run. If the time argument is provided then that will be the activation time otherwise the current time is used by default. The format of the optional time argument is -that specified in the *Time Formats* section of the kadmin man page. +that specified in the *Time Formats* section of the :ref:`kadmin(1)` +man page. list_mkeys ~~~~~~~~~~ @@ -276,8 +277,8 @@ list_mkeys List all master keys from most recent to earliest in ``K/M`` principal. The output will show the kvno, enctype and salt for each -mkey similar to kadmin getprinc output. A ``*`` following an mkey -denotes the currently active master key. +mkey similar to :ref:`kadmin(1)` **getprinc** output. A ``*`` +following an mkey denotes the currently active master key. purge_mkeys ~~~~~~~~~~~ @@ -321,4 +322,4 @@ seek confirmation. SEE ALSO -------- -kadmin(8) +:ref:`kadmin(1)` diff --git a/doc/rst_source/krb_admins/admin_commands/kprop.rst b/doc/rst_source/krb_admins/admin_commands/kprop.rst index a999130b5..d984ec0f0 100644 --- a/doc/rst_source/krb_admins/admin_commands/kprop.rst +++ b/doc/rst_source/krb_admins/admin_commands/kprop.rst @@ -57,4 +57,4 @@ ENVIRONMENT SEE ALSO -------- -kpropd(8), kdb5_util(8), krb5kdc(8) +:ref:`kpropd(8)`, :ref:`kdb5_util(8)`, :ref:`krb5kdc(8)` diff --git a/doc/rst_source/krb_admins/admin_commands/kpropd.rst b/doc/rst_source/krb_admins/admin_commands/kpropd.rst index 33ba3aa8c..5856e5a12 100644 --- a/doc/rst_source/krb_admins/admin_commands/kpropd.rst +++ b/doc/rst_source/krb_admins/admin_commands/kpropd.rst @@ -46,7 +46,7 @@ updates its principal.ulog file with any updates from the master. :ref:`kproplog(8)` can be used to view a summary of the update entry log on the slave KDC. Incremental propagation is not enabled by default; it can be enabled using the **iprop_enable** and -**iprop_slave_poll** settings in :ref:`kdc.conf`. The principal +**iprop_slave_poll** settings in :ref:`kdc.conf(5)`. The principal ``kiprop/slavehostname@REALM`` (where *slavehostname* is the name of the slave KDC host, and *REALM* is the name of the Kerberos realm) must be present in the slave's keytab file. @@ -108,4 +108,4 @@ kpropd.acl SEE ALSO -------- -kprop(8), kdb5_util(8), krb5kdc(8), inetd(8) +:ref:`kprop(8)`, :ref:`kdb5_util(8)`, :ref:`krb5kdc(8)`, inetd(8) diff --git a/doc/rst_source/krb_admins/admin_commands/kproplog.rst b/doc/rst_source/krb_admins/admin_commands/kproplog.rst index b269242e4..b9b36e716 100644 --- a/doc/rst_source/krb_admins/admin_commands/kproplog.rst +++ b/doc/rst_source/krb_admins/admin_commands/kproplog.rst @@ -14,12 +14,12 @@ DESCRIPTION The kproplog command displays the contents of the Kerberos principal update log to standard output. It can be used to keep track of the incremental updates to the principal database, when enabled. The -update log file contains the update log maintained by the kadmind -process on the master KDC server and the kpropd process on the slave -KDC servers. When updates occur, they are logged to this file. -Subsequently any KDC slave configured for incremental updates will -request the current data from the master KDC and update their -principal.ulog file with any updates returned. +update log file contains the update log maintained by the +:ref:`kadmind(8)` process on the master KDC server and the kpropd +process on the slave KDC servers. When updates occur, they are logged +to this file. Subsequently any KDC slave configured for incremental +updates will request the current data from the master KDC and update +their principal.ulog file with any updates returned. The kproplog command can only be run on a KDC server by someone with privileges comparable to the superuser. It will display update @@ -73,4 +73,4 @@ kproplog uses the following environment variables: SEE ALSO -------- -kpropd(8) +:ref:`kpropd(8)` diff --git a/doc/rst_source/krb_admins/admin_commands/krb5kdc.rst b/doc/rst_source/krb_admins/admin_commands/krb5kdc.rst index c86b8846e..6a3013ccf 100644 --- a/doc/rst_source/krb_admins/admin_commands/krb5kdc.rst +++ b/doc/rst_source/krb_admins/admin_commands/krb5kdc.rst @@ -112,17 +112,17 @@ For example:: specifies that the KDC listen on port 2001 for REALM1 and on port 2002 for REALM2 and REALM3. Additionally, per-realm parameters may be -specified in the :ref:`kdc.conf` file. The location of this file may -be specified by the **KRB5_KDC_PROFILE** environment variable. +specified in the :ref:`kdc.conf(5)` file. The location of this file +may be specified by the **KRB5_KDC_PROFILE** environment variable. Parameters specified in this file take precedence over options -specified on the command line. See the :ref:`kdc.conf` description +specified on the command line. See the :ref:`kdc.conf(5)` description for further details. ENVIRONMENT ----------- -*krb5kdc* uses the following environment variables: +krb5kdc uses the following environment variables: * **KRB5_CONFIG** * **KRB5_KDC_PROFILE** @@ -131,4 +131,5 @@ ENVIRONMENT SEE ALSO -------- -kdb5_util(8), kdc.conf(5), krb5.conf(5), kdb5_ldap_util(8) +:ref:`kdb5_util(8)`, :ref:`kdc.conf(5)`, :ref:`krb5.conf(5)`, +:ref:`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 index fa79b4471..0cdbfaf0e 100644 --- a/doc/rst_source/krb_admins/admin_commands/ktutil.rst +++ b/doc/rst_source/krb_admins/admin_commands/ktutil.rst @@ -127,4 +127,4 @@ EXAMPLE SEE ALSO -------- -kadmin(8), kdb5_util(8) +:ref:`kadmin(1)`, :ref:`kdb5_util(8)` diff --git a/doc/rst_source/krb_admins/admin_commands/sserver.rst b/doc/rst_source/krb_admins/admin_commands/sserver.rst index 5f446d36f..2ee42a5a9 100644 --- a/doc/rst_source/krb_admins/admin_commands/sserver.rst +++ b/doc/rst_source/krb_admins/admin_commands/sserver.rst @@ -42,8 +42,8 @@ like this:: When using sclient, you will first have to have an entry in the Kerberos database, by using :ref:`kadmin(1)`, and then you have to get -Kerberos tickets, by using kinit(1). Also, if you are running the -sclient program on a different host than the sserver it will be +Kerberos tickets, by using :ref:`kinit(1)`. Also, if you are running +the sclient program on a different host than the sserver it will be connecting to, be sure that both hosts have an entry in /etc/services for the sample tcp port, and that the same port number is in both files. @@ -58,7 +58,7 @@ When you run sclient you should see something like this:: COMMON ERROR MESSAGES --------------------- -1) *kinit* returns the error:: +1) kinit returns the error:: kinit: Client not found in Kerberos database while getting initial credentials @@ -85,8 +85,8 @@ COMMON ERROR MESSAGES This means that the ``sample/hostname@LOCAL.REALM`` service was not defined in the Kerberos database; it should be created using - kadmin, and a keytab file needs to be generated to make the key for - that service principal available for sclient. + :ref:`kadmin(1)`, and a keytab file needs to be generated to make + the key for that service principal available for sclient. 5) sclient returns the error:: diff --git a/doc/rst_source/krb_admins/advanced/ldapbackend.rst b/doc/rst_source/krb_admins/advanced/ldapbackend.rst index 221ed6d1c..38fa7f745 100644 --- a/doc/rst_source/krb_admins/advanced/ldapbackend.rst +++ b/doc/rst_source/krb_admins/advanced/ldapbackend.rst @@ -155,7 +155,7 @@ Stash the password:: kdb5_ldap_util -D cn=admin,dc=example,dc=com -H ldapi:/// stashsrvpw cn=admin,dc=example,dc=com -Start kdc:: +Start :ref:`krb5kdc(8)`:: krb5kdc diff --git a/doc/rst_source/krb_admins/appl_servers/clock_skew.rst b/doc/rst_source/krb_admins/appl_servers/clock_skew.rst index ed29acfa2..d6bea7a49 100644 --- a/doc/rst_source/krb_admins/appl_servers/clock_skew.rst +++ b/doc/rst_source/krb_admins/appl_servers/clock_skew.rst @@ -4,14 +4,15 @@ Clock Skew In order to prevent intruders from resetting their system clocks in order to continue to use expired tickets, Kerberos V5 is set up to reject ticket requests from any host whose clock is not within the -specified maximum clock skew of the KDC (as specified in the kdc.conf -file). Similarly, hosts are configured to reject responses from any -KDC whose clock is not within the specified maximum clock skew of the -host (as specified in the krb5.conf file). The default value for -maximum clock skew is 300 seconds, or five minutes. MIT suggests that -you add a line to client machines' ``/etc/rc`` files to synchronize -the machine's clock to your KDC at boot time. On UNIX hosts, assuming -you had a kdc called kerberos in your realm, this would be:: +specified maximum clock skew of the KDC (as specified in the KDC's +:ref:`krb5.conf(5)` file). Similarly, hosts are configured to reject +responses from any KDC whose clock is not within the specified maximum +clock skew of the host (as specified in the :ref:`krb5.conf(5)` file). +The default value for maximum clock skew is 300 seconds, or five +minutes. MIT suggests that you add a line to client machines' +``/etc/rc`` files to synchronize the machine's clock to your KDC at +boot time. On UNIX hosts, assuming you had a kdc called kerberos in +your realm, this would be:: gettime -s kerberos diff --git a/doc/rst_source/krb_admins/appl_servers/conf_firewall.rst b/doc/rst_source/krb_admins/appl_servers/conf_firewall.rst index b58270237..783c90039 100644 --- a/doc/rst_source/krb_admins/appl_servers/conf_firewall.rst +++ b/doc/rst_source/krb_admins/appl_servers/conf_firewall.rst @@ -8,10 +8,10 @@ realm, they must be able to get to your KDC. This requires either that you have a slave KDC outside your firewall, or you configure your firewall to allow UDP requests into at least one of your KDCs, on whichever port the KDC is running. (The default is port 88; other -ports may be specified in the KDC's kdc.conf file.) Similarly, if you -need off-site users to be able to change their passwords in your -realm, they must be able to get to your Kerberos admin server. The -default port for the admin server is 749. +ports may be specified in the KDC's :ref:`kdc.conf(5)` file.) +Similarly, if you need off-site users to be able to change their +passwords in your realm, they must be able to get to your Kerberos +admin server. The default port for the admin server is 749. If your on-site users inside your firewall will need to get to KDCs in other realms, you will also need to configure your firewall to allow @@ -22,8 +22,8 @@ firewall will need to get to Kerberos admin servers in other realms, you will also need to allow outgoing TCP and UDP requests to port 749. If any of your KDCs are outside your firewall, you will need to allow -kprop requests to get through to the remote KDC. kprop uses the -``krb5_prop`` service on port 754 (tcp). +kprop requests to get through to the remote KDC. :ref:`kprop(8)` uses +the ``krb5_prop`` service on port 754 (tcp). If you need your off-site users to have access to machines inside your firewall, you need to allow TCP connections from their off-site hosts diff --git a/doc/rst_source/krb_admins/appl_servers/dns_info.rst b/doc/rst_source/krb_admins/appl_servers/dns_info.rst index 83cf54749..c3e433e08 100644 --- a/doc/rst_source/krb_admins/appl_servers/dns_info.rst +++ b/doc/rst_source/krb_admins/appl_servers/dns_info.rst @@ -37,7 +37,8 @@ issuing the command ``klist -k``. For example:: 1 host/daffodil.mit.edu@ATHENA.MIT.EDU If you telnet to the host with a fresh credentials cache (ticket -file), and then klist, the host's service principal should be:: +file), and then :ref:`klist(1)`, the host's service principal should +be:: host/fully-qualified-hostname@REALM_NAME. diff --git a/doc/rst_source/krb_admins/appl_servers/keytabs.rst b/doc/rst_source/krb_admins/appl_servers/keytabs.rst index 9d94ccc11..ad8215b2e 100644 --- a/doc/rst_source/krb_admins/appl_servers/keytabs.rst +++ b/doc/rst_source/krb_admins/appl_servers/keytabs.rst @@ -8,8 +8,9 @@ and key. Just as it is important for users to protect their passwords, it is equally important for hosts to protect their keytabs. You should always store keytab files on local disk, and make them readable only by root, and you should never send a keytab file over a -network in the clear. Ideally, you should run the kadmin command to -extract a keytab on the host on which the keytab is to reside. +network in the clear. Ideally, you should run the :ref:`kadmin(1)` +command to extract a keytab on the host on which the keytab is to +reside. .. _add_princ_kt: @@ -47,7 +48,7 @@ Here is a sample session, using configuration files that enable only Removing principals from keytabs --------------------------------- -To remove a principal from an existing keytab, use the *kadmin* +To remove a principal from an existing keytab, use the kadmin **ktremove** command. .. include:: ../admin_commands/kadmin_local.rst diff --git a/doc/rst_source/krb_admins/conf_files/kdc_conf.rst b/doc/rst_source/krb_admins/conf_files/kdc_conf.rst index 062ed765a..9633ce3b4 100644 --- a/doc/rst_source/krb_admins/conf_files/kdc_conf.rst +++ b/doc/rst_source/krb_admins/conf_files/kdc_conf.rst @@ -1,4 +1,4 @@ -.. _kdc.conf: +.. _kdc.conf(5): kdc.conf ======== @@ -13,7 +13,8 @@ setting the environment variable KRB5_KDC_PROFILE. Structure --------- -The kdc.conf file is set up in the same format as the :ref:`krb5.conf` file. +The kdc.conf file is set up in the same format as the +:ref:`krb5.conf(5)` file. Sections @@ -92,8 +93,8 @@ subsection: **acl_file** (String.) Location of the access control list (acl) file that - kadmin uses to determine which principals are allowed which - permissions on the database. The default is + :ref:`kadmind(8)` uses to determine which principals are allowed + which permissions on the database. The default is ``/usr/local/var/krb5kdc/kadm5.acl``. **admin_keytab** @@ -235,8 +236,9 @@ subsection: default value will not use values from the [dbmodules] section.) **kadmind_port** - (Port number.) Specifies the port on which the kadmind daemon is - to listen for this realm. The assigned port for kadmind is 749. + (Port number.) Specifies the port on which the :ref:`kadmind(8)` + daemon is to listen for this realm. The assigned port for kadmind + is 749. **key_stash_file** (String.) Specifies the location where the master key has been @@ -285,12 +287,12 @@ subsection: A boolean value (true, false). If set to true, the KDC will check the list of transited realms for cross-realm tickets against the transit path computed from the realm names and the capaths section - of its krb5.conf file; if the path in the ticket to be issued - contains any realms not in the computed path, the ticket will not - be issued, and an error will be returned to the client instead. - If this value is set to false, such tickets will be issued - anyways, and it will be left up to the application server to - validate the realm transit path. + of its :ref:`krb5.conf(5)` file; if the path in the ticket to be + issued contains any realms not in the computed path, the ticket + will not be issued, and an error will be returned to the client + instead. If this value is set to false, such tickets will be + issued anyways, and it will be left up to the application server + to validate the realm transit path. If the disable-transited-check flag is set in the incoming request, this check is not performed at all. Having the @@ -319,8 +321,8 @@ subsection: **supported_enctypes** List of *key*:*salt* strings. Specifies the default key/salt combinations of principals for this realm. Any principals created - through kadmin will have keys of these types. The default value - for this tag is ``aes256-cts-hmac-sha1-96:normal + through :ref:`kadmin(1)` will have keys of these types. The + default value for this tag is ``aes256-cts-hmac-sha1-96:normal aes128-cts-hmac-sha1-96:normal des3-cbc-sha1:normal arcfour-hmac-md5:normal``. For lists of possible values, see :ref:`Supported_Encryption_Types_and_Salts` @@ -331,7 +333,7 @@ subsection: [logging] ~~~~~~~~~ -See :ref:`logging` section in :ref:`krb5.conf` +See :ref:`logging` section in :ref:`krb5.conf(5)` PKINIT options @@ -471,4 +473,4 @@ FILES SEE ALSO --------- -krb5.conf(5), krb5kdc(8) +:ref:`krb5.conf(5)`, :ref:`krb5kdc(8)` diff --git a/doc/rst_source/krb_admins/conf_files/krb5_conf.rst b/doc/rst_source/krb_admins/conf_files/krb5_conf.rst index 7efecaa9e..ee469c524 100644 --- a/doc/rst_source/krb_admins/conf_files/krb5_conf.rst +++ b/doc/rst_source/krb_admins/conf_files/krb5_conf.rst @@ -1,4 +1,4 @@ -.. _krb5.conf: +.. _krb5.conf(5): krb5.conf ========= @@ -63,7 +63,7 @@ headers:: *MODULEPATH* may be relative to the library path of the krb5 installation, or it may be an absolute path. *RESIDUAL* is provided to the module at initialization time. If krb5.conf uses a module -directive, kdc.conf should also use one if it exists. +directive, :ref:`kdc.conf(5)` should also use one if it exists. Sections @@ -116,12 +116,12 @@ The libdefaults section may contain any of the following relations: **ccache_type** Use this parameter on systems which are DCE clients, to specify - the type of cache to be created by kinit, or when forwarded - tickets are received. DCE and Kerberos can share the cache, but - some versions of DCE do not support the default cache as created - by this version of Kerberos. Use a value of 1 on DCE 1.0.3a - systems, and a value of 2 on DCE 1.1 systems. The default value - is 4. + the type of cache to be created by :ref:`kinit(1)`, or when + forwarded tickets are received. DCE and Kerberos can share the + cache, but some versions of DCE do not support the default cache + as created by this version of Kerberos. Use a value of 1 on DCE + 1.0.3a systems, and a value of 2 on DCE 1.1 systems. The default + value is 4. **clockskew** Sets the maximum allowable amount of clockskew in seconds that the @@ -224,10 +224,10 @@ The libdefaults section may contain any of the following relations: **k5login_authoritative** If the value of this relation is true (the default), principals must be listed in a local user's k5login file to be granted login - access, if a .k5login file exists. If the value of this relation - is false, a principal may still be granted login access through - other mechanisms even if a k5login file exists but does not list - the principal. + access, if a :ref:`.k5login(5)` file exists. If the value of this + relation is false, a principal may still be granted login access + through other mechanisms even if a k5login file exists but does + not list the principal. **k5login_directory** If set, the library will look for a local user's k5login file @@ -357,8 +357,8 @@ following tags may be specified in the realm's subsection: **admin_server** Identifies the host where the administration server is running. Typically, this is the master Kerberos server. This tag must be - given a value in order to communicate with the kadmin server for - the realm. + given a value in order to communicate with the :ref:`kadmind(8)` + server for the realm. **auth_to_local** This tag allows you to set a general rule for mapping principal @@ -703,9 +703,9 @@ The following tags are used in this section: **ldap_service_password_file** This LDAP specific tag indicates the file containing the stashed - passwords (created by kdb5_ldap_util stashsrvpw) for the objects - used by the Kerberos servers to bind to the LDAP server. This - file must be kept secure. This value is used if no service + passwords (created by ``kdb5_ldap_util stashsrvpw``) for the + objects used by the Kerberos servers to bind to the LDAP server. + This file must be kept secure. This value is used if no service password file is mentioned in the configuration section under dbmodules_. @@ -795,9 +795,9 @@ subsection: **ldap_service_password_file** This LDAP specific tag indicates the file containing the stashed - passwords (created by "kdb5_ldap_util stashsrvpw") for the objects - used by the Kerberos servers to bind to the LDAP server. This - file must be kept secure. + passwords (created by ``kdb5_ldap_util stashsrvpw``) for the + objects used by the Kerberos servers to bind to the LDAP server. + This file must be kept secure. .. _appdefaults: diff --git a/doc/rst_source/krb_admins/conf_ldap.rst b/doc/rst_source/krb_admins/conf_ldap.rst index bcbe9150f..3b842626c 100644 --- a/doc/rst_source/krb_admins/conf_ldap.rst +++ b/doc/rst_source/krb_admins/conf_ldap.rst @@ -38,19 +38,20 @@ Configuring Kerberos with OpenLDAP back-end include /etc/openldap/schema/kerberos.schema -3. Choose DNs for the KDC and kadmin servers to bind to the LDAP - server, and create them if necessary. These DNs will be specified - with the **ldap_kdc_dn** and **ldap_kadmind_dn** directives in - krb5.conf; their passwords can be stashed with "``kdb5_ldap_util - stashsrvpw``" and the resulting file specified with the - **ldap_service_password_file** directive. +3. Choose DNs for the :ref:`krb5kdc(8)` and :ref:`kadmind(8)` servers + to bind to the LDAP server, and create them if necessary. These DNs + will be specified with the **ldap_kdc_dn** and **ldap_kadmind_dn** + directives in :ref:`krb5.conf(5)`; their passwords can be stashed + with "``kdb5_ldap_util stashsrvpw``" and the resulting file + specified with the **ldap_service_password_file** directive. 4. Choose a DN for the global Kerberos container entry (but do not create the entry at this time). This DN will be specified with the - **ldap_kerberos_container_dn** directive in krb5.conf. Realm - container entries will be created underneath this DN. Principal - entries may exist either underneath the realm container (the - default) or in separate trees referenced from the realm container. + **ldap_kerberos_container_dn** directive in :ref:`krb5.conf(5)`. + Realm container entries will be created underneath this DN. + Principal entries may exist either underneath the realm container + (the default) or in separate trees referenced from the realm + container. 5. Configure the LDAP server ACLs to enable the KDC and kadmin server DNs to read and write the Kerberos data. @@ -94,8 +95,8 @@ Configuring Kerberos with OpenLDAP back-end slapd -h "ldapi:/// ldaps:///" -7. Modify the krb5.conf file to include LDAP specific items listed - below:: +7. Modify the :ref:`krb5.conf(5)` file to include LDAP specific items + listed below:: realms database_module @@ -109,11 +110,10 @@ Configuring Kerberos with OpenLDAP back-end ldap_servers ldap_conns_per_server - For the sample krb5.conf file, refer to - :ref:`krb5_conf_sample_label`. For more details, refer to - :ref:`krb5.conf` + For the sample :ref:`krb5.conf(5)` file, refer to + :ref:`krb5_conf_sample_label`. -8. Create the realm using kdb5_ldap_util (see +8. Create the realm using :ref:`kdb5_ldap_util(8)` (see :ref:`ldap_create_realm_label`):: kdb5_ldap_util -D cn=admin,dc=example,dc=com create -subtrees ou=users,dc=example,dc=com -r EXAMPLE.COM -s @@ -136,10 +136,10 @@ Configuring Kerberos with OpenLDAP back-end 9. Stash the password of the service object used by the KDC and Administration service to bind to the LDAP server using the - **stashsrvpw** command of kdb5_ldap_util (see + :ref:`kdb5_ldap_util(8)` **stashsrvpw** command (see :ref:`stash_ldap_label`). The object DN should be the same as **ldap_kdc*_dn* and **ldap_kadmind_dn** values specified in the - krb5.conf file:: + :ref:`krb5.conf(5)` file:: kdb5_ldap_util -D cn=admin,dc=example,dc=com stashsrvpw -f /etc/kerberos/service.keyfile cn=krbadmin,dc=example,dc=com diff --git a/doc/rst_source/krb_admins/database/change_tgtkey.rst b/doc/rst_source/krb_admins/database/change_tgtkey.rst index a4a830a17..a7ff8cdeb 100644 --- a/doc/rst_source/krb_admins/database/change_tgtkey.rst +++ b/doc/rst_source/krb_admins/database/change_tgtkey.rst @@ -8,11 +8,11 @@ However, it will only have the encryption types supported by the KDC at the time of the initial database creation. To allow use of newer encryption types for the TGT, this key has to be changed. -Changing this key using the normal kadmin **change_password** command -would invalidate any previously issued TGTs. Therefore, when changing -this key, normally one should use the **-keepold** flag to -change_password to retain the previous key in the database as well as -the new key. For example:: +Changing this key using the normal :ref:`kadmin(1)` +**change_password** command would invalidate any previously issued +TGTs. Therefore, when changing this key, normally one should use the +**-keepold** flag to change_password to retain the previous key in the +database as well as the new key. For example:: kadmin: change_password -randkey -keepold krbtgt/ATHENA.MIT.EDU@ATHENA.MIT.EDU diff --git a/doc/rst_source/krb_admins/database/db_operations/create_stash.rst b/doc/rst_source/krb_admins/database/db_operations/create_stash.rst index c99e7da8a..785235be3 100644 --- a/doc/rst_source/krb_admins/database/db_operations/create_stash.rst +++ b/doc/rst_source/krb_admins/database/db_operations/create_stash.rst @@ -4,7 +4,8 @@ Creating a stash file ===================== A stash file allows a KDC to authenticate itself to the database -utilities, such as kadmin, kadmind, krb5kdc, and kdb5_util. +utilities, such as :ref:`kadmind(8)`, :ref:`krb5kdc(5)`, and +:ref:`kdb5_util(8)`. To create a stash file, use the :ref:`kdb5_util(8)` **stash** command. @@ -23,7 +24,7 @@ Example shell% If you do not specify a stash file, kdb5_util will stash the key in -the file specified in your :ref:`kdc.conf` file. +the file specified in your :ref:`kdc.conf(5)` file. Feedback diff --git a/doc/rst_source/krb_admins/database/db_options.rst b/doc/rst_source/krb_admins/database/db_options.rst index d64ccec14..4020ad45d 100644 --- a/doc/rst_source/krb_admins/database/db_options.rst +++ b/doc/rst_source/krb_admins/database/db_options.rst @@ -1,8 +1,8 @@ kadmin options ============== -You can invoke kadmin or kadmin.local with any of the following -options: +You can invoke :ref:`kadmin(1)` or kadmin.local with any of the +following options: .. include:: ../admin_commands/kadmin_local.rst :start-after: kadmin_synopsys: diff --git a/doc/rst_source/krb_admins/database/db_policies/mod_pol.rst b/doc/rst_source/krb_admins/database/db_policies/mod_pol.rst index a313bb827..150a45641 100644 --- a/doc/rst_source/krb_admins/database/db_policies/mod_pol.rst +++ b/doc/rst_source/krb_admins/database/db_policies/mod_pol.rst @@ -1,7 +1,7 @@ Adding, modifying and deleting policies ======================================= -To add a new policy, use the kadmin **add_policy** command. +To add a new policy, use the :ref:`kadmin(1)` **add_policy** command. To modify attributes of a principal, use the kadmin **modify_policy** command. diff --git a/doc/rst_source/krb_admins/database/db_policies/retr_pol.rst b/doc/rst_source/krb_admins/database/db_policies/retr_pol.rst index d4cb78666..da9fc2e5b 100644 --- a/doc/rst_source/krb_admins/database/db_policies/retr_pol.rst +++ b/doc/rst_source/krb_admins/database/db_policies/retr_pol.rst @@ -1,7 +1,7 @@ Retrieving policies =================== -To retrieve a policy, use the kadmin **get_policy** command. +To retrieve a policy, use the :ref:`kadmin(1)` **get_policy** command. You can retrieve the list of policies with the kadmin **list_policies** command. diff --git a/doc/rst_source/krb_admins/database/db_policies/update_histkey.rst b/doc/rst_source/krb_admins/database/db_policies/update_histkey.rst index 28a6f2c47..f4f21897f 100644 --- a/doc/rst_source/krb_admins/database/db_policies/update_histkey.rst +++ b/doc/rst_source/krb_admins/database/db_policies/update_histkey.rst @@ -5,7 +5,7 @@ The following text is for release < 1.8. If a policy specifies a number of old keys kept of two or more, the stored old keys are encrypted in a history key, which is found in the -key data of the *kadmin/history* principal. +key data of the ``kadmin/history`` principal. Currently there is no support for proper rollover of the history key, but you can change the history key (for example, to use a better diff --git a/doc/rst_source/krb_admins/database/db_princs/info_princ.rst b/doc/rst_source/krb_admins/database/db_princs/info_princ.rst index 2d8903570..fcc51acb6 100644 --- a/doc/rst_source/krb_admins/database/db_princs/info_princ.rst +++ b/doc/rst_source/krb_admins/database/db_princs/info_princ.rst @@ -2,7 +2,7 @@ Retrieving information about a principal ======================================== To retrieve a listing of the attributes and/or policies associated -with a principal, use the kadmin **get_principal** command. +with a principal, use the :ref:`kadmin(1)` **get_principal** command. To generate a listing of principals, use the kadmin **list_principals** command. diff --git a/doc/rst_source/krb_admins/database/db_princs/modify_princ.rst b/doc/rst_source/krb_admins/database/db_princs/modify_princ.rst index 755cac23a..1d3678c8d 100644 --- a/doc/rst_source/krb_admins/database/db_princs/modify_princ.rst +++ b/doc/rst_source/krb_admins/database/db_princs/modify_princ.rst @@ -3,8 +3,8 @@ Adding, modifying and deleting principals ============================================ -To add a principal to the database, use the kadmin **add_principal** -command. +To add a principal to the database, use the :ref:`kadmin(1)` +**add_principal** command. To modify attributes of a principal, use the kadmin **modify_principal** command. diff --git a/doc/rst_source/krb_admins/database/db_princs/pass_princ.rst b/doc/rst_source/krb_admins/database/db_princs/pass_princ.rst index 575c6a449..dfd683044 100644 --- a/doc/rst_source/krb_admins/database/db_princs/pass_princ.rst +++ b/doc/rst_source/krb_admins/database/db_princs/pass_princ.rst @@ -1,8 +1,8 @@ Changing passwords ================== -To change a principal's password use the kadmin **change_password** -command. +To change a principal's password use the :ref:`kadmin(1)` +**change_password** command. .. include:: ../../admin_commands/kadmin_local.rst :start-after: _change_password: diff --git a/doc/rst_source/krb_admins/database/incr_db_prop.rst b/doc/rst_source/krb_admins/database/incr_db_prop.rst index 0edfb405f..0dc4360fb 100644 --- a/doc/rst_source/krb_admins/database/incr_db_prop.rst +++ b/doc/rst_source/krb_admins/database/incr_db_prop.rst @@ -21,25 +21,25 @@ With incremental propagation enabled, all programs on the master KDC that change the database also write information about the changes to an "update log" file, maintained as a circular buffer of a certain size. A process on each slave KDC connects to a service on the master -KDC (currently implmented in the kadmind server) and periodically -requests the changes that have been made since the last check. By -default, this check is done every two minutes. If the database has -just been modified in the previous several seconds (currently the -threshold is hard-coded at 10 seconds), the slave will not retrieve -updates, but instead will pause and try again soon after. This -reduces the likelihood that incremental update queries will cause +KDC (currently implemented in the :ref:`kadmind(8)` server) and +periodically requests the changes that have been made since the last +check. By default, this check is done every two minutes. If the +database has just been modified in the previous several seconds +(currently the threshold is hard-coded at 10 seconds), the slave will +not retrieve updates, but instead will pause and try again soon after. +This reduces the likelihood that incremental update queries will cause delays for an administrator trying to make a bunch of changes to the database at the same time. Incremental propagation uses the following entries in the per-realm -data in the KDC config file (See :ref:`kdc.conf`): +data in the KDC config file (See :ref:`kdc.conf(5)`): ====================== =============== =========================================== iprop_enable *boolean* If *true*, then incremental propagation is enabled, and (as noted below) normal kprop propagation is disabled. The default is *false*. iprop_master_ulogsize *integer* Indicates the number of entries that should be retained in the update log. The default is 1000; the maximum number is 2500. iprop_slave_poll *time interval* Indicates how often the slave should poll the master KDC for changes to the database. The default is two minutes. iprop_port *integer* Specifies the port number to be used for incremental propagation. This is required in both master and slave configuration files. -iprop_logfile *file name* Specifies where the update log file for the realm database is to be stored. The default is to use the *database_name* entry from the realms section of the config file :ref:`kdc.conf`, with *.ulog* appended. (NOTE: If database_name isn't specified in the realms section, perhaps because the LDAP database back end is being used, or the file name is specified in the *dbmodules* section, then the hard-coded default for *database_name* is used. Determination of the *iprop_logfile* default value will not use values from the *dbmodules* section.) +iprop_logfile *file name* Specifies where the update log file for the realm database is to be stored. The default is to use the *database_name* entry from the realms section of the config file :ref:`kdc.conf(5)`, with *.ulog* appended. (NOTE: If database_name isn't specified in the realms section, perhaps because the LDAP database back end is being used, or the file name is specified in the *dbmodules* section, then the hard-coded default for *database_name* is used. Determination of the *iprop_logfile* default value will not use values from the *dbmodules* section.) ====================== =============== =========================================== Both master and slave sides must have principals named @@ -51,9 +51,9 @@ On the master KDC side, the ``kiprop/hostname`` principal must be listed in the kadmind ACL file kadm5.acl, and given the **p** privilege (See :ref:`privileges_label`) -On the slave KDC side, kpropd should be run. When incremental -propagation is enabled, it will connect to the kadmind on the master -KDC and start requesting updates. +On the slave KDC side, :ref:`kpropd(8)` should be run. When +incremental propagation is enabled, it will connect to the kadmind on +the master KDC and start requesting updates. The normal kprop mechanism is disabled by the incremental propagation support. However, if the slave has been unable to fetch changes from diff --git a/doc/rst_source/krb_admins/database/index.rst b/doc/rst_source/krb_admins/database/index.rst index 232f00d57..c0e60557e 100644 --- a/doc/rst_source/krb_admins/database/index.rst +++ b/doc/rst_source/krb_admins/database/index.rst @@ -11,8 +11,8 @@ Your Kerberos database contains all of your realm's Kerberos principals, their passwords, and other administrative information about each principal. For the most part, you will use the :ref:`kdb5_util(8)` program to manipulate the Kerberos database as a -whole, and the kadmin program to make changes to the entries in the -database. (One notable exception is that users will use the +whole, and the :ref:`kadmin(1)` program to make changes to the entries +in the database. (One notable exception is that users will use the :ref:`kpasswd(1)` program to change their own passwords.) The kadmin program has its own command-line interface, to which you type the database administrating commands. @@ -20,7 +20,8 @@ database administrating commands. :ref:`kdb5_util(8)` provides a means to create, delete, load, or dump a Kerberos database. It also includes a command to stash a copy of the master database key in a file on a KDC, so that the KDC can -authenticate itself to the kadmind and krb5kdc daemons at boot time. +authenticate itself to the :ref:`kadmind(8)` and :ref:`krb5kdc(8)` +daemons at boot time. kadmin provides for the maintenance of Kerberos principals, KADM5 policies, and service key tables (keytabs). It exists as both a diff --git a/doc/rst_source/krb_admins/database/ldap_operations/index.rst b/doc/rst_source/krb_admins/database/ldap_operations/index.rst index fd5efbbba..6f2a631c3 100644 --- a/doc/rst_source/krb_admins/database/ldap_operations/index.rst +++ b/doc/rst_source/krb_admins/database/ldap_operations/index.rst @@ -3,9 +3,9 @@ Operations on the LDAP database =============================== -The kdb5_ldap_util is the primary tool for administrating the Kerberos -LDAP database. It allows an administrator to manage realms, Kerberos -services (KDC and Admin Server) and ticket policies. +The :ref:`kdb5_ldap_util(8)` is the primary tool for administrating +the Kerberos LDAP database. It allows an administrator to manage +realms, Kerberos services (KDC and Admin Server) and ticket policies. .. include:: ../../admin_commands/kdb5_ldap_util.rst :start-after: _kdb5_ldap_util_synopsis: diff --git a/doc/rst_source/krb_admins/env_variables.rst b/doc/rst_source/krb_admins/env_variables.rst index 66e7bfcd0..702b014c7 100644 --- a/doc/rst_source/krb_admins/env_variables.rst +++ b/doc/rst_source/krb_admins/env_variables.rst @@ -36,12 +36,12 @@ The following environment variables can be used during runtime: default location) **KPROP_PORT** - *kprop* port to use. Defaults to 754. + :ref:`kprop(8)` port to use. Defaults to 754. **KRB5_TRACE** Debugging and tracing. (Introduced in release 1.9) - E.g. *KRB5_TRACE=/dev/stdout kinit* + E.g. ``KRB5_TRACE=/dev/stdout kinit`` The setting of this environment variable can be overridden by the tracing behavior set by the application using either of the following API: diff --git a/doc/rst_source/krb_admins/install_appl_srv.rst b/doc/rst_source/krb_admins/install_appl_srv.rst index 3d2929a40..045a080cb 100644 --- a/doc/rst_source/krb_admins/install_appl_srv.rst +++ b/doc/rst_source/krb_admins/install_appl_srv.rst @@ -36,7 +36,8 @@ In order to generate a keytab for a host, the host must have a principal in the Kerberos database. The procedure for adding hosts to the database is described fully in :ref:`add_mod_del_princs_label`. (See :ref:`slave_host_key_label` for a brief description.) The keytab -is generated by running kadmin and issuing the :ref:`ktadd` command. +is generated by running :ref:`kadmin(1)` and issuing the :ref:`ktadd` +command. For example, to generate a keytab file to allow the host ``trillium.mit.edu`` to authenticate for the services host, ftp, and diff --git a/doc/rst_source/krb_admins/install_clients/cl_config.rst b/doc/rst_source/krb_admins/install_clients/cl_config.rst index 63e4097ff..e0ba0a349 100644 --- a/doc/rst_source/krb_admins/install_clients/cl_config.rst +++ b/doc/rst_source/krb_admins/install_clients/cl_config.rst @@ -1,8 +1,7 @@ Client machine configuration files ================================== -Each machine running Kerberos must have a ``/etc/krb5.conf`` file. -(See :ref:`krb5.conf`.) +Each machine running Kerberos must have a :ref:`krb5.conf(5)` file. Also, for most UNIX systems, you must add the appropriate Kerberos services to each client machine's ``/etc/services`` file. If you are diff --git a/doc/rst_source/krb_admins/install_clients/index.rst b/doc/rst_source/krb_admins/install_clients/index.rst index 73a2dfb1e..ca795a80c 100644 --- a/doc/rst_source/krb_admins/install_clients/index.rst +++ b/doc/rst_source/krb_admins/install_clients/index.rst @@ -1,12 +1,12 @@ Installing and configuring UNIX client machines =============================================== -The Kerberized client programs are kinit, klist, kdestroy, kpasswd, -and ksu. All of these programs are in the directory -``/usr/local/bin``. MIT recommends that you use login.krb5 in place -of ``/bin/login`` to give your users a single-sign-on system. You will -need to make sure your users know to use their Kerberos passwords when -they log in. +The Kerberized client programs are :ref:`kinit(1)`, :ref:`klist(1)`, +:ref:`kdestroy(1)`, :ref:`kpasswd(1)`, and :ref:`ksu(1)`. All of +these programs are in the directory ``/usr/local/bin``. MIT +recommends that you use login.krb5 in place of ``/bin/login`` to give +your users a single-sign-on system. You will need to make sure your +users know to use their Kerberos passwords when they log in. You will also need to educate your users to use the ticket management programs kinit, klist, kdestroy, and to use the Kerberos programs ksu diff --git a/doc/rst_source/krb_admins/install_kdc/admins_to_acl.rst b/doc/rst_source/krb_admins/install_kdc/admins_to_acl.rst index 517ca98a6..d9b3b69a3 100644 --- a/doc/rst_source/krb_admins/install_kdc/admins_to_acl.rst +++ b/doc/rst_source/krb_admins/install_kdc/admins_to_acl.rst @@ -5,11 +5,11 @@ Add administrators to the ACL file Next, you need create an Access Control List (ACL) file, and put the Kerberos principal of at least one of the administrators into it. -This file is used by the kadmind daemon to control which principals -may view and make privileged modifications to the Kerberos database -files. The filename should match the value you have set for -**acl_file** (see :ref:`kdc_realms`) in your kdc.conf file. The -default file name is ``/usr/local/var/krb5kdc/kadm5.acl`` (See +This file is used by the :ref:`kadmind(8)` daemon to control which +principals may view and make privileged modifications to the Kerberos +database files. The filename should match the value you have set for +**acl_file** (see :ref:`kdc_realms`) in your :ref:`kdc.conf(5)` file. +The default file name is ``/usr/local/var/krb5kdc/kadm5.acl`` (See :ref:`mitK5defaults`). The format of the file is:: diff --git a/doc/rst_source/krb_admins/install_kdc/create_db.rst b/doc/rst_source/krb_admins/install_kdc/create_db.rst index 2c2ac34d4..894778f42 100644 --- a/doc/rst_source/krb_admins/install_kdc/create_db.rst +++ b/doc/rst_source/krb_admins/install_kdc/create_db.rst @@ -11,14 +11,14 @@ create the Kerberos database and the optional :ref:`stash_definition`. means that the KDC will not be able to start automatically, such as after a system reboot. -Note that **kdb5_util** will prompt you for the master key for the -Kerberos database. This key can be any string. A good key is one you -can remember, but that no one else can guess. Examples of bad keys -are words that can be found in a dictionary, any common or popular -name, especially a famous person (or cartoon character), your username -in any form (e.g., forward, backward, repeated twice, etc.), and any -of the sample keys that appear in this manual. One example of a key -which might be good if it did not appear in this manual is +Note that :ref:`kdb5_util(8)` will prompt you for the master key for +the Kerberos database. This key can be any string. A good key is one +you can remember, but that no one else can guess. Examples of bad +keys are words that can be found in a dictionary, any common or +popular name, especially a famous person (or cartoon character), your +username in any form (e.g., forward, backward, repeated twice, etc.), +and any of the sample keys that appear in this manual. One example of +a key which might be good if it did not appear in this manual is "MITiys4K5!", which represents the sentence "MIT is your source for Kerberos 5!" (It's the first letter of each word, substituting the numeral "4" for the word "for", and includes the punctuation mark at @@ -40,8 +40,8 @@ realm:: shell% This will create five files in the directory specified in your -**kdc.conf** file (The default location is ``/usr/local/var/krb5kdc`` -directory. See :ref:`mitK5defaults`): +:ref:`kdc.conf(5)` file (The default location is +``/usr/local/var/krb5kdc`` directory. See :ref:`mitK5defaults`): - two Kerberos database files, ``principal``, and ``principal.ok``; - the Kerberos administrative database file, ``principal.kadm5``; diff --git a/doc/rst_source/krb_admins/install_kdc/index.rst b/doc/rst_source/krb_admins/install_kdc/index.rst index e9dc1be56..018f6b185 100644 --- a/doc/rst_source/krb_admins/install_kdc/index.rst +++ b/doc/rst_source/krb_admins/install_kdc/index.rst @@ -76,11 +76,11 @@ Install the Slave KDCs slave_install.rst kdc_prop_slave.rst -Once your KDCs are set up and running, you are ready to use kadmin to -load principals for your users, hosts, and other services into the -Kerberos database. This procedure is described fully in the -:ref:`add_mod_del_princs_label`. The keytab is generated by running -kadmin and issuing the :ref:`ktadd` command. +Once your KDCs are set up and running, you are ready to use +:ref:`kadmin(1)` to load principals for your users, hosts, and other +services into the Kerberos database. This procedure is described +fully in the :ref:`add_mod_del_princs_label`. The keytab is generated +by running kadmin and issuing the :ref:`ktadd` command. You may occasionally want to use one of your slave KDCs as the master. This might happen if you are upgrading the master KDC, or if your diff --git a/doc/rst_source/krb_admins/install_kdc/kadmind_kt.rst b/doc/rst_source/krb_admins/install_kdc/kadmind_kt.rst index 30b8a4062..3e2d22936 100644 --- a/doc/rst_source/krb_admins/install_kdc/kadmind_kt.rst +++ b/doc/rst_source/krb_admins/install_kdc/kadmind_kt.rst @@ -32,7 +32,7 @@ create it.) To create the kadmin keytab, run kadmin.local and use the As specified in the **-k** argument, :ref:`ktadd` will save the extracted keytab as ``/usr/local/var/krb5kdc/kadm5.keytab`` (This is also the default location for the admin keytab). The filename you use -must be the one specified in your kdc.conf file. +must be the one specified in your :ref:`kdc.conf(5)` file. Feedback diff --git a/doc/rst_source/krb_admins/install_kdc/kdc_prop_slave.rst b/doc/rst_source/krb_admins/install_kdc/kdc_prop_slave.rst index 2ac232ba2..b30b0fdff 100644 --- a/doc/rst_source/krb_admins/install_kdc/kdc_prop_slave.rst +++ b/doc/rst_source/krb_admins/install_kdc/kdc_prop_slave.rst @@ -18,14 +18,14 @@ following example:: Just in case you need an additional confirmation of the successful propagation, do the following on the slave: -* make sure that only this slave's kdc is listed in the krb5.conf - file, then -* start krb5kdc on the slave server and +* make sure that only this slave's kdc is listed in the + :ref:`krb5.conf(5)` file, then +* start :ref:`krb5kdc(8)` on the slave server and * run ``kinit admin/admin@ATHENA.MIT.EDU`` which should succeed once the correct password (i.e. password that was entered on the master server for this principal) is provided. -* now klist should display the message similar to ``Default principal: - admin/admin@ATHENA.MIT.EDU`` +* now :ref:`klist(1)` should display the message similar to ``Default + principal: admin/admin@ATHENA.MIT.EDU`` You will need a script to dump and propagate the database. The following is an example of a bourne shell script that will do this. @@ -61,11 +61,11 @@ As with the master KDC, you will probably want to add this command to the KDCs' ``/etc/rc`` or ``/etc/inittab`` files, so they will start the krb5kdc daemon automatically at boot time. -Once your KDCs are set up and running, you are ready to use kadmin to -load principals for your users, hosts, and other services into the -Kerberos database. This procedure is described fully in the -:ref:`add_mod_del_princs_label`. The keytab is generated by running -kadmin and issuing the ktadd command. +Once your KDCs are set up and running, you are ready to use +:ref:`kadmin(1)` to load principals for your users, hosts, and other +services into the Kerberos database. This procedure is described +fully in the :ref:`add_mod_del_princs_label`. The keytab is generated +by running kadmin and issuing the ktadd command. Propagation failed? @@ -90,9 +90,9 @@ Make sure that: master to the expected location on the slaves; #. Kerberos database was created on the slaves prior the propagation from the master. -#. if kpropd is invoked from inetd (or its equivalent xinetd), the - inetd daemon was restarted after the configuration files - ``/etc/inetd.conf`` and ``/etc/services`` were updated; +#. if :ref:`kpropd(8)` is invoked from inetd (or its equivalent + xinetd), the inetd daemon was restarted after the configuration + files ``/etc/inetd.conf`` and ``/etc/services`` were updated; #. kpropd is running on the slave server; #. if the locations of the configuration/keytab files differ from the default ones, provide the proper environment variables and/or diff --git a/doc/rst_source/krb_admins/install_kdc/krb_daemon.rst b/doc/rst_source/krb_admins/install_kdc/krb_daemon.rst index d2a503834..97774727f 100644 --- a/doc/rst_source/krb_admins/install_kdc/krb_daemon.rst +++ b/doc/rst_source/krb_admins/install_kdc/krb_daemon.rst @@ -17,7 +17,7 @@ Each server daemon will fork and run in the background. You can verify that they started properly by checking for their startup messages in the logging locations you defined in -krb5.conf. (See :ref:`logging`). For example:: +:ref:`krb5.conf(5)` (see :ref:`logging`). For example:: shell% tail /var/log/krb5kdc.log Dec 02 12:35:47 beeblebrox krb5kdc[3187](info): commencing operation @@ -27,8 +27,8 @@ krb5.conf. (See :ref:`logging`). For example:: Any errors the daemons encounter while starting will also be listed in the logging output. -As an additional verification, check if kinit succeeds against the -principals that you have created on the previous step +As an additional verification, check if :ref:`kinit(1)` succeeds +against the principals that you have created on the previous step (:ref:`addadmin_kdb`). Run:: shell% /usr/local/bin/kinit admin/admin@ATHENA.MIT.EDU diff --git a/doc/rst_source/krb_admins/install_kdc/mod_conf.rst b/doc/rst_source/krb_admins/install_kdc/mod_conf.rst index 157f05a13..d4e1e1966 100644 --- a/doc/rst_source/krb_admins/install_kdc/mod_conf.rst +++ b/doc/rst_source/krb_admins/install_kdc/mod_conf.rst @@ -1,16 +1,16 @@ Edit the configuration files ============================ -Modify the configuration files, krb5.conf and kdc.conf, to reflect the -correct information (such as domain-realm mappings and Kerberos -servers names) for your realm. (See :ref:`mitK5defaults` for the -recommended default locations for these files). +Modify the configuration files, :ref:`krb5.conf(5)` and +:ref:`kdc.conf(5)`, to reflect the correct information (such as +domain-realm mappings and Kerberos servers names) for your realm. +(See :ref:`mitK5defaults` for the recommended default locations for +these files). Most of the tags in the configuration have default values that will -work well for most sites. There are some tags in the krb5.conf file -whose values must be specified, and this section will explain those. -For more information on Kerberos V5 configuration files see -:ref:`krb5.conf` and :ref:`kdc.conf`. +work well for most sites. There are some tags in the +:ref:`krb5.conf(5)` file whose values must be specified, and this +section will explain those. If the locations for these configuration files differs from the default ones, set **KRB5_CONFIG** and **KRB5_KDC_PROFILE** environment @@ -33,8 +33,8 @@ server in each realm, the **admin_server** tag must be set in the :ref:`realms` section. If your domain name and realm name are not the same, you must provide a translation in :ref:`domain_realm`. It is also higly recommeneded that you create a :ref:`logging` stanza if the -computer will be functioning as a KDC so that the KDC and kadmind will -generate logging output. +computer will be functioning as a KDC so that :ref:`krb5kdc(8)` and +:ref:`kadmind(8)` will generate logging output. An example krb5.conf file:: diff --git a/doc/rst_source/krb_admins/install_kdc/stash_file_def.rst b/doc/rst_source/krb_admins/install_kdc/stash_file_def.rst index 4e2ee8355..ad019274d 100644 --- a/doc/rst_source/krb_admins/install_kdc/stash_file_def.rst +++ b/doc/rst_source/krb_admins/install_kdc/stash_file_def.rst @@ -4,13 +4,18 @@ stash file ============ -The stash file is a local copy of the master key that resides in encrypted form on the KDC's local disk. -The stash file is used to authenticate the KDC to itself automatically before starting the *kadmind* and *krb5kdc* daemons -(e.g., as part of the machine's boot sequence). -The stash file, like the keytab file (see :ref:`kt_file_label` for more information) is a potential point-of-entry for a break-in, -and if compromised, would allow unrestricted access to the Kerberos database. -If you choose to install a stash file, it should be readable only by root, and should exist only on the KDC's local disk. -The file should not be part of any backup of the machine, unless access to the backup data is secured as tightly as access to the master password itself. +The stash file is a local copy of the master key that resides in +encrypted form on the KDC's local disk. The stash file is used to +authenticate the KDC to itself automatically before starting the +:ref:`kadmind(8)` and :ref:`krb5kdc(8)` daemons (e.g., as part of the +machine's boot sequence). The stash file, like the keytab file (see +:ref:`kt_file_label` for more information) is a potential +point-of-entry for a break-in, and if compromised, would allow +unrestricted access to the Kerberos database. If you choose to +install a stash file, it should be readable only by root, and should +exist only on the KDC's local disk. The file should not be part of +any backup of the machine, unless access to the backup data is secured +as tightly as access to the master password itself. .. note:: If you choose not to install a stash file, the KDC will prompt you for the master key each time it starts up. This means that the KDC will not be able to start automatically, such as after a system reboot. diff --git a/doc/rst_source/krb_admins/install_kdc/switch_master_slave.rst b/doc/rst_source/krb_admins/install_kdc/switch_master_slave.rst index 46a040723..c3239cb3a 100644 --- a/doc/rst_source/krb_admins/install_kdc/switch_master_slave.rst +++ b/doc/rst_source/krb_admins/install_kdc/switch_master_slave.rst @@ -28,12 +28,13 @@ master KDC: On the *new* master KDC: #. Create a database keytab. (See Create a kadmind Keytab (optional).) -#. Start the kadmind daemon. (See Start the Kerberos Daemons.) +#. Start the :ref:`kadmind(8)` daemon. (See Start the Kerberos + Daemons.) #. Set up the cron job to propagate the database. (See Propagate the Database to Each Slave KDC.) #. Switch the CNAMEs of the old and new master KDCs. (If you don't do - this, you'll need to change the krb5.conf file on every client - machine in your Kerberos realm.) + this, you'll need to change the :ref:`krb5.conf(5)` file on every + client machine in your Kerberos realm.) Feedback diff --git a/doc/rst_source/krb_admins/realm_config/kdc_hn.rst b/doc/rst_source/krb_admins/realm_config/kdc_hn.rst index 9fd2ea19b..939f2a600 100644 --- a/doc/rst_source/krb_admins/realm_config/kdc_hn.rst +++ b/doc/rst_source/krb_admins/realm_config/kdc_hn.rst @@ -56,8 +56,8 @@ _kerberos-master._udp _kerberos-adm._tcp This should list port 749 on your master KDC. Support for it is not complete at this time, but it will eventually be used by the - kadmin program and related utilities. For now, you will also need - the admin_server entry in :ref:`krb5.conf`. + :ref:`kadmin(1)` program and related utilities. For now, you will + also need the admin_server entry in :ref:`krb5.conf(5)`. _kpasswd._udp This should list port 464 on your master KDC. It is used when a user changes her password. @@ -87,10 +87,10 @@ anticipate installing a very large number of machines on which it will be hard to update the Kerberos configuration files, you may wish to do all of your Kerberos service lookups via DNS and not put the information (except for **admin_server** as noted above) in future -versions of your krb5.conf files at all. Eventually, we hope to phase -out the listing of server hostnames in the client-side configuration -files; making preparations now will make the transition easier in the -future. +versions of your :ref:`krb5.conf(5)` files at all. Eventually, we +hope to phase out the listing of server hostnames in the client-side +configuration files; making preparations now will make the transition +easier in the future. Feedback diff --git a/doc/rst_source/krb_admins/realm_config/kdc_ports.rst b/doc/rst_source/krb_admins/realm_config/kdc_ports.rst index a23f6b676..2bb1b61ff 100644 --- a/doc/rst_source/krb_admins/realm_config/kdc_ports.rst +++ b/doc/rst_source/krb_admins/realm_config/kdc_ports.rst @@ -4,9 +4,9 @@ Ports for the KDC and admin services The default ports used by Kerberos are port 88 for the KDC1 and port 749 for the admin server. You can, however, choose to run on other ports, as long as they are specified in each host's ``/etc/services`` -and :ref:`krb5.conf` files, and the :ref:`kdc.conf` file on each KDC. -For a more thorough treatment of port numbers used by the Kerberos V5 -programs, refer to the :ref:`conf_firewall_label`. +and :ref:`krb5.conf(5)` files, and the :ref:`kdc.conf(5)` file on each +KDC. For a more thorough treatment of port numbers used by the +Kerberos V5 programs, refer to the :ref:`conf_firewall_label`. Feedback -------- diff --git a/doc/rst_source/krb_admins/realm_config/mapping_hn.rst b/doc/rst_source/krb_admins/realm_config/mapping_hn.rst index cc925c149..26954f183 100644 --- a/doc/rst_source/krb_admins/realm_config/mapping_hn.rst +++ b/doc/rst_source/krb_admins/realm_config/mapping_hn.rst @@ -14,8 +14,8 @@ Mapping hostnames onto Kerberos realms is done in one of two ways. The first mechanism, which has been in use for years in MIT-based Kerberos distributions, works through a set of rules in the -:ref:`krb5.conf` configuration file. You can specify mappings for an -entire domain or subdomain, and/or on a hostname-by-hostname basis. +:ref:`krb5.conf(5)` configuration file. You can specify mappings for +an entire domain or subdomain, and/or on a hostname-by-hostname basis. Since greater specificity takes precedence, you would do this by specifying the mappings for a given domain or subdomain and listing the exceptions. diff --git a/doc/rst_source/krb_admins/troubleshoot.rst b/doc/rst_source/krb_admins/troubleshoot.rst index 2740a56a0..f47dc9163 100644 --- a/doc/rst_source/krb_admins/troubleshoot.rst +++ b/doc/rst_source/krb_admins/troubleshoot.rst @@ -11,7 +11,7 @@ List encryption type Add ``allow_weak_crypto = true`` to the [libdefaults] section of -krb5.conf. +:ref:`krb5.conf(5)`. Version 1.7+ diff --git a/doc/rst_source/krb_build/options2configure.rst b/doc/rst_source/krb_build/options2configure.rst index b30cc3f47..8edbd9f69 100644 --- a/doc/rst_source/krb_build/options2configure.rst +++ b/doc/rst_source/krb_build/options2configure.rst @@ -48,10 +48,10 @@ Most commonly used options **--enable-dns-for-realm** Enable the use of DNS to look up a host's Kerberos realm, or a realm's KDCs, if the information is not provided in - :ref:`krb5.conf`. See :ref:`kdc_hn_label` for information about - using DNS to locate the KDCs, and :ref:`mapping_hn_label` for - information about using DNS to determine the default realm. By - default, DNS lookups are enabled for the former but not for the + :ref:`krb5.conf(5)`. See :ref:`kdc_hn_label` for information + about using DNS to locate the KDCs, and :ref:`mapping_hn_label` + for information about using DNS to determine the default realm. + By default, DNS lookups are enabled for the former but not for the latter. **--with-system-et** diff --git a/doc/rst_source/krb_users/pwd_mgmt/grant_access.rst b/doc/rst_source/krb_users/pwd_mgmt/grant_access.rst index e93ef607c..5d9b8a4f8 100644 --- a/doc/rst_source/krb_users/pwd_mgmt/grant_access.rst +++ b/doc/rst_source/krb_users/pwd_mgmt/grant_access.rst @@ -5,10 +5,10 @@ Granting access to your account If you need to give someone access to log into your account, you can do so through Kerberos, without telling the person your password. -Simply create a file called .k5login in your home directory. This -file should contain the Kerberos principal of each person to whom you -wish to give access. Each principal must be on a separate line. Here -is a sample .k5login file:: +Simply create a file called :ref:`.k5login(5)` in your home directory. +This file should contain the Kerberos principal of each person to whom +you wish to give access. Each principal must be on a separate line. +Here is a sample .k5login file:: jennifer@ATHENA.MIT.EDU david@EXAMPLE.COM diff --git a/doc/rst_source/krb_users/pwd_mgmt/pwd_management.rst b/doc/rst_source/krb_users/pwd_mgmt/pwd_management.rst index 2ae116d84..2af7aeb8e 100644 --- a/doc/rst_source/krb_users/pwd_mgmt/pwd_management.rst +++ b/doc/rst_source/krb_users/pwd_mgmt/pwd_management.rst @@ -1,12 +1,12 @@ Changing your password ====================== -To change your Kerberos password, use the kpasswd command. It will ask -you for your old password (to prevent someone else from walking up to -your computer when you're not there and changing your password), and -then prompt you for the new one twice. (The reason you have to type -it twice is to make sure you have typed it correctly.) For example, -user ``david`` would do the following:: +To change your Kerberos password, use the :ref:`kpasswd(1)` command. +It will ask you for your old password (to prevent someone else from +walking up to your computer when you're not there and changing your +password), and then prompt you for the new one twice. (The reason you +have to type it twice is to make sure you have typed it correctly.) +For example, user ``david`` would do the following:: shell% kpasswd Password for david: <- Type your old password. diff --git a/doc/rst_source/krb_users/tkt_mgmt/destroy_tkt.rst b/doc/rst_source/krb_users/tkt_mgmt/destroy_tkt.rst index a232178c7..644196902 100644 --- a/doc/rst_source/krb_users/tkt_mgmt/destroy_tkt.rst +++ b/doc/rst_source/krb_users/tkt_mgmt/destroy_tkt.rst @@ -11,9 +11,9 @@ Destroying your tickets is easy. Simply type kdestroy:: shell% kdestroy shell% -If kdestroy fails to destroy your tickets, it will beep and give an -error message. For example, if kdestroy can't find any tickets to -destroy, it will give the following message:: +If :ref:`kdestroy(1)` fails to destroy your tickets, it will beep and +give an error message. For example, if kdestroy can't find any +tickets to destroy, it will give the following message:: shell% kdestroy kdestroy: No credentials cache file found while destroying cache diff --git a/doc/rst_source/krb_users/tkt_mgmt/index.rst b/doc/rst_source/krb_users/tkt_mgmt/index.rst index c915d8d08..c2c1225b1 100644 --- a/doc/rst_source/krb_users/tkt_mgmt/index.rst +++ b/doc/rst_source/krb_users/tkt_mgmt/index.rst @@ -13,10 +13,10 @@ remote host. Most of these programs also automatically destroy your tickets when they exit. However, MIT recommends that you explicitly destroy your Kerberos tickets when you are through with them, just to be sure. One way to help ensure that this happens is to add the -kdestroy command to your .logout file. Additionally, if you are going -to be away from your machine and are concerned about an intruder using -your permissions, it is safest to either destroy all copies of your -tickets, or use a screensaver that locks the screen. +:ref:`kdestroy(1)` command to your .logout file. Additionally, if you +are going to be away from your machine and are concerned about an +intruder using your permissions, it is safest to either destroy all +copies of your tickets, or use a screensaver that locks the screen. .. toctree:: :maxdepth: 1 diff --git a/doc/rst_source/krb_users/tkt_mgmt/obtain_kinit.rst b/doc/rst_source/krb_users/tkt_mgmt/obtain_kinit.rst index d9f6afcde..777f877ba 100644 --- a/doc/rst_source/krb_users/tkt_mgmt/obtain_kinit.rst +++ b/doc/rst_source/krb_users/tkt_mgmt/obtain_kinit.rst @@ -1,15 +1,16 @@ .. _otwk_labal: -Obtaining tickets with *kinit* -============================== +Obtaining tickets with kinit +============================ If your site is using the Kerberos V5 login program, you will get Kerberos tickets automatically when you log in. If your site uses a different login program, you may need to explicitly obtain your -Kerberos tickets, using the kinit program. Similarly, if your -Kerberos tickets expire, use the kinit program to obtain new ones. +Kerberos tickets, using the :ref:`kinit(1)` program. Similarly, if +your Kerberos tickets expire, use the kinit program to obtain new +ones. -To use the kinit program, simply type kinit and then type your +To use the kinit program, simply type ``kinit`` and then type your password at the prompt. For example, Jennifer (whose username is ``jennifer``) works for Bleep, Inc. (a fictitious company with the domain name mit.edu and the Kerberos realm ATHENA.MIT.EDU). She would @@ -53,7 +54,7 @@ need to request forwardable tickets. You do this by specifying the shell% Note that kinit does not tell you that it obtained forwardable -tickets; you can verify this using the *klist* command (see +tickets; you can verify this using the :ref:`klist(1)` command (see :ref:`vytwk_label`). Normally, your tickets are good for your system's default ticket @@ -75,7 +76,7 @@ type:: lifetime. .. [1] Note: the realm EXAMPLE.COM must be listed in your computer's - Kerberos configuration file, */etc/krb5.conf*. + Kerberos configuration file, :ref:`krb5.conf(5)`. Feedback diff --git a/doc/rst_source/krb_users/tkt_mgmt/view_klist.rst b/doc/rst_source/krb_users/tkt_mgmt/view_klist.rst index 3a9879e33..9d43a7329 100644 --- a/doc/rst_source/krb_users/tkt_mgmt/view_klist.rst +++ b/doc/rst_source/krb_users/tkt_mgmt/view_klist.rst @@ -3,9 +3,9 @@ Viewing tickets with klist ========================== -The klist command shows your tickets. When you first obtain tickets, -you will have only the ticket-granting ticket. The listing would look -like this:: +The :ref:`klist(1)` command shows your tickets. When you first obtain +tickets, you will have only the ticket-granting ticket. The listing +would look like this:: shell% klist Ticket cache: /tmp/krb5cc_ttypa diff --git a/doc/rst_source/krb_users/user_appl/index.rst b/doc/rst_source/krb_users/user_appl/index.rst index 4a87cc24a..982399fe4 100644 --- a/doc/rst_source/krb_users/user_appl/index.rst +++ b/doc/rst_source/krb_users/user_appl/index.rst @@ -29,8 +29,8 @@ because Kerberos has already proven your identity. The Kerberos V5 network programs allow you the options of forwarding your tickets to the remote host (if you obtained forwardable tickets -with the kinit program; see :ref:`otwk_labal`), and encrypting data -transmitted between you and the remote host. +with the :ref:`kinit(1)` program; see :ref:`otwk_labal`), and +encrypting data transmitted between you and the remote host. The Kerberos V5 applications are versions of existing UNIX network programs with the Kerberos features added. diff --git a/doc/rst_source/krb_users/user_appl/ksu.rst b/doc/rst_source/krb_users/user_appl/ksu.rst index 830f4fee9..360763229 100644 --- a/doc/rst_source/krb_users/user_appl/ksu.rst +++ b/doc/rst_source/krb_users/user_appl/ksu.rst @@ -1,17 +1,17 @@ ksu === -The Kerberos V5 ksu program replaces the standard UNIX su program (See -ksu_vs_su_). ksu first authenticates you to Kerberos. Depending on -the configuration of your system, ksu may ask for your Kerberos -password if authentication fails. Note that you should never type -your password if you are remotely logged in using an unencrypted +The Kerberos V5 :ref:`ksu(1)` program replaces the standard UNIX su +program (See ksu_vs_su_). ksu first authenticates you to Kerberos. +Depending on the configuration of your system, ksu may ask for your +Kerberos password if authentication fails. Note that you should never +type your password if you are remotely logged in using an unencrypted connection. Once ksu has authenticated you, if your Kerberos principal appears in -the target's .k5login file (see Granting Access to Your Account) or in -the target's .k5users file (see below), it switches your user ID to -the target user ID. +the target's :ref:`.k5login(5)` file (see Granting Access to Your +Account) or in the target's .k5users file (see below), it switches +your user ID to the target user ID. For example, ``david`` has put ``jennifer``'s Kerberos principal in his .k5login file. If ``jennifer`` uses ksu to become ``david``, the diff --git a/doc/rst_source/krb_users/user_commands/k5identity.rst b/doc/rst_source/krb_users/user_commands/k5identity.rst index d1ea2d13f..fb97497e1 100644 --- a/doc/rst_source/krb_users/user_commands/k5identity.rst +++ b/doc/rst_source/krb_users/user_commands/k5identity.rst @@ -1,5 +1,7 @@ -Kerberos V5 client principal selection rules -============================================ +.. _.k5identity(5): + +.k5identity +=========== SYNOPSIS -------- @@ -28,7 +30,7 @@ recognized: 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. + :ref:`krb5.conf(5)` with a mapping for the hostname. **service** If the server principal is a host-based principal, its service @@ -64,4 +66,4 @@ accessing the IMAP service on ``mail.example.com``:: SEE ALSO -------- -kerberos(1), krb5.conf(5) +kerberos(1), :ref:`krb5.conf(5)` diff --git a/doc/rst_source/krb_users/user_commands/k5login.rst b/doc/rst_source/krb_users/user_commands/k5login.rst index 192942f41..fc046dad9 100644 --- a/doc/rst_source/krb_users/user_commands/k5login.rst +++ b/doc/rst_source/krb_users/user_commands/k5login.rst @@ -1,5 +1,7 @@ -Kerberos V5 acl file for host access -==================================== +.. _.k5login(5): + +.k5login +======== SYNOPSIS -------- diff --git a/doc/rst_source/krb_users/user_commands/kdestroy.rst b/doc/rst_source/krb_users/user_commands/kdestroy.rst index 91698a76d..f7469d5f1 100644 --- a/doc/rst_source/krb_users/user_commands/kdestroy.rst +++ b/doc/rst_source/krb_users/user_commands/kdestroy.rst @@ -1,5 +1,7 @@ -kdestroy - destroy Kerberos tickets -=================================== +.. _kdestroy(1): + +kdestroy +======== SYNOPSIS -------- @@ -73,7 +75,7 @@ FILES SEE ALSO -------- -kinit(1), klist(1) +:ref:`kinit(1)`, :ref:`klist(1)` BUGS diff --git a/doc/rst_source/krb_users/user_commands/kinit.rst b/doc/rst_source/krb_users/user_commands/kinit.rst index 582028702..0728c306d 100644 --- a/doc/rst_source/krb_users/user_commands/kinit.rst +++ b/doc/rst_source/krb_users/user_commands/kinit.rst @@ -1,7 +1,7 @@ .. _kinit(1): -kinit - obtain and cache Kerberos ticket-granting ticket -======================================================== +kinit +===== SYNOPSIS -------- @@ -120,10 +120,11 @@ OPTIONS are supported. For fully anonymous Kerberos, configure pkinit on the KDC and - configure **pkinit_anchors** in the client's krb5.conf. Then use - the **-n** option with a principal of the form ``@REALM`` (an - empty principal name followed by the at-sign and a realm name). - If permitted by the KDC, an anonymous ticket will be returned. + configure **pkinit_anchors** in the client's :ref:`krb5.conf(5)`. + Then use the **-n** option with a principal of the form ``@REALM`` + (an empty principal name followed by the at-sign and a realm + name). If permitted by the KDC, an anonymous ticket will be + returned. A second form of anonymous tickets is supported; these realm-exposed tickets hide the identity of the client but not the @@ -210,4 +211,4 @@ FILES SEE ALSO -------- -klist(1), kdestroy(1), kerberos(1) +:ref:`klist(1)`, :ref:`kdestroy(1)`, kerberos(1) diff --git a/doc/rst_source/krb_users/user_commands/klist.rst b/doc/rst_source/krb_users/user_commands/klist.rst index 4c21bb9eb..63b0b1c06 100644 --- a/doc/rst_source/krb_users/user_commands/klist.rst +++ b/doc/rst_source/krb_users/user_commands/klist.rst @@ -1,5 +1,7 @@ -klist - list cached Kerberos tickets -==================================== +.. _klist(1): + +klist +===== SYNOPSIS -------- @@ -118,4 +120,4 @@ FILES SEE ALSO -------- -kinit(1), kdestroy(1) +:ref:`kinit(1)`, :ref:`kdestroy(1)` diff --git a/doc/rst_source/krb_users/user_commands/kpasswd.rst b/doc/rst_source/krb_users/user_commands/kpasswd.rst index 64500e6ca..00629259e 100644 --- a/doc/rst_source/krb_users/user_commands/kpasswd.rst +++ b/doc/rst_source/krb_users/user_commands/kpasswd.rst @@ -43,15 +43,15 @@ kpasswd looks first for:: kpasswd_server = host:port -in the [realms] section of the krb5.conf file under the current realm. -If that is missing, kpasswd looks for the **admin_server** entry, but -substitutes 464 for the port. +in the [realms] section of the :ref:`krb5.conf(5)` file under the +current realm. If that is missing, kpasswd looks for the +**admin_server** entry, but substitutes 464 for the port. SEE ALSO -------- -kadmin(8), kadmind(8) +:ref:`kadmin(1)`, :ref:`kadmind(8)` BUGS diff --git a/doc/rst_source/krb_users/user_commands/ksu.rst b/doc/rst_source/krb_users/user_commands/ksu.rst index 6951f77ed..9ab03eb9f 100644 --- a/doc/rst_source/krb_users/user_commands/ksu.rst +++ b/doc/rst_source/krb_users/user_commands/ksu.rst @@ -1,5 +1,7 @@ -ksu - Kerberized super-user -=========================== +.. _ksu(1): + +ksu +=== SYNOPSIS -------- @@ -78,8 +80,9 @@ option, see the OPTIONS section. Upon successful authentication, ksu checks whether the target principal is authorized to access the target account. In the target user's home directory, ksu attempts to access two authorization files: -.k5login and .k5users. In the .k5login file each line contains the -name of a principal that is authorized to access the account. +:ref:`.k5login(5)` and .k5users. In the .k5login file each line +contains the name of a principal that is authorized to access the +account. For example:: diff --git a/doc/rst_source/krb_users/user_commands/kswitch.rst b/doc/rst_source/krb_users/user_commands/kswitch.rst index c81b06909..6c83a5c86 100644 --- a/doc/rst_source/krb_users/user_commands/kswitch.rst +++ b/doc/rst_source/krb_users/user_commands/kswitch.rst @@ -1,5 +1,7 @@ -kswitch - switch primary credential cache -========================================= +.. _kswitch(1): + +kswitch +======= SYNOPSIS ~~~~~~~~ @@ -52,4 +54,4 @@ FILES SEE ALSO -------- -kinit(1), kdestroy(1), klist(1), kerberos(1) +:ref:`kinit(1)`, :ref:`kdestroy(1)`, :ref:`klist(1)`), kerberos(1) diff --git a/doc/rst_source/krb_users/user_commands/kvno.rst b/doc/rst_source/krb_users/user_commands/kvno.rst index 4b2090185..6db4353b5 100644 --- a/doc/rst_source/krb_users/user_commands/kvno.rst +++ b/doc/rst_source/krb_users/user_commands/kvno.rst @@ -1,5 +1,7 @@ -kvno - print key version numbers of Kerberos principals -======================================================= +.. _kvno(1): + +kvno +==== SYNOPSIS -------- @@ -79,4 +81,4 @@ FILES SEE ALSO -------- -kinit(1), kdestroy(1) +:ref:`kinit(1)`, :ref:`kdestroy(1)` diff --git a/doc/rst_source/krb_users/user_commands/sclient.rst b/doc/rst_source/krb_users/user_commands/sclient.rst index cb6474186..13aa14d6b 100644 --- a/doc/rst_source/krb_users/user_commands/sclient.rst +++ b/doc/rst_source/krb_users/user_commands/sclient.rst @@ -20,4 +20,4 @@ server's response. SEE ALSO -------- -kinit(1), sserver(8) +:ref:`kinit(1)`, :ref:`sserver(8)`