From eadfb030fb1117968b3ce6a5d57c164c523d9843 Mon Sep 17 00:00:00 2001 From: Greg Hudson Date: Fri, 16 Mar 2012 13:57:55 +0000 Subject: [PATCH] Miscellaneous RST documentation edits Make small changes to various RST documentation pages to improve clarity or remove outdated statements. git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@25776 dc483132-0cff-0310-8789-dd5450dbe970 --- .../admin_commands/kadmin_local.rst | 7 ++++-- .../admin_commands/kdb5_ldap_util.rst | 8 ++----- .../krb_admins/admin_commands/kdb5_util.rst | 20 +++++++++------- .../krb_admins/admin_commands/kpropd.rst | 14 +++++------ .../krb_admins/admin_commands/kproplog.rst | 4 ++-- doc/rst_source/krb_admins/appl_servers.rst | 4 ---- doc/rst_source/krb_admins/conf_ldap.rst | 2 +- doc/rst_source/krb_admins/database.rst | 9 ------- .../krb_admins/install_appl_srv.rst | 15 ++++++------ doc/rst_source/krb_admins/install_kdc.rst | 5 ++-- doc/rst_source/krb_admins/troubleshoot.rst | 6 +++-- doc/rst_source/krb_users/tkt_mgmt.rst | 24 ++++++++----------- .../krb_users/user_commands/kdestroy.rst | 9 ------- .../krb_users/user_commands/sclient.rst | 7 +++--- .../krb_users/user_config/k5login.rst | 8 +++---- 15 files changed, 59 insertions(+), 83 deletions(-) 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 4f2e7215e..8e85300d7 100644 --- a/doc/rst_source/krb_admins/admin_commands/kadmin_local.rst +++ b/doc/rst_source/krb_admins/admin_commands/kadmin_local.rst @@ -647,7 +647,9 @@ The following options are available: sets the minimum length of a password **-minclasses** *number* - sets the minimum number of character classes allowed in a password + sets the minimum number of character classes required in a + password. The five character classes are lower case, upper case, + numbers, punctuation, and whitespace/unprintable characters. **-history** *number* sets the number of past keys kept for a principal. This option is @@ -881,7 +883,8 @@ Example: lock ~~~~ -Lock database exclusively. Use with extreme caution! +Lock database exclusively. Use with extreme caution! This command +only works with the DB2 KDC database module. unlock ~~~~~~ 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 295e46458..2399024bd 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 @@ -368,9 +368,6 @@ modify_policy Modifies the attributes of a ticket policy. Options are same as for **create_policy**. -**-r** *realm* - Specifies the Kerberos realm of the database. - Example: :: @@ -427,9 +424,8 @@ Destroys an existing ticket policy. Options: Specifies the Kerberos realm of the database. **-force** - Forces the deletion of the policy object. If not specified, will - be prompted for confirmation while deleting the policy. Enter yes - to confirm the deletion. + Forces the deletion of the policy object. If not specified, the + user will be prompted for confirmation before deleting the policy. *policy_name* Specifies the name of the ticket policy. 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 1520dac14..9184df17b 100644 --- a/doc/rst_source/krb_admins/admin_commands/kdb5_util.rst +++ b/doc/rst_source/krb_admins/admin_commands/kdb5_util.rst @@ -164,8 +164,8 @@ load_dump version 6". If filename is not specified, or is the string **-mkey_convert** prompts for a new master key. This new master key will be used to - re-encrypt the key data in the dumpfile. The key data in the - database will not be changed. + re-encrypt principal key data in the dumpfile. The principal keys + themselves will not be changed. **-new_mkey_file** *mkey_file* the filename of a stash file. The master key in this stash file @@ -193,13 +193,15 @@ load **load** [**-old**\|\ **-b6**\|\ **-b7**\|\ **-ov**\|\ **-r13**] [**-hash**] [**-verbose**] [**-update**] *filename* [*dbname*] -Loads a database dump from the named file into the named database. -Unless the **-old** or **-b6** option is given, the format of the dump -file is detected automatically and handled as appropriate. Unless the -**-update** option is given, load creates a new database containing -only the principals in the dump file, overwriting the contents of any -previously existing database. Note that when using the LDAP KDB -plugin the **-update** must be given. Options: +Loads a database dump from the named file into the named database. If +no option is given to determine the format of the dump file, the +format is detected automatically and handled as appropriate. Unless +the **-update** option is given, **load** creates a new database +containing only the data in the dump file, overwriting the contents of +any previously existing database. Note that when using the LDAP KDC +database module, the **-update** flag is required. + +Options: **-old** requires the database to be in the Kerberos 5 Beta 5 and earlier diff --git a/doc/rst_source/krb_admins/admin_commands/kpropd.rst b/doc/rst_source/krb_admins/admin_commands/kpropd.rst index 46d6704ad..3b20fe676 100644 --- a/doc/rst_source/krb_admins/admin_commands/kpropd.rst +++ b/doc/rst_source/krb_admins/admin_commands/kpropd.rst @@ -47,13 +47,13 @@ Incremental propagation may be enabled with the **iprop_enable** variable in :ref:`kdc.conf(5)`. If incremental propagation is enabled, the slave periodically polls the master KDC for updates, at an interval determined by the **iprop_slave_poll** variable. If the -slave receives updates, kpropd 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. If incremental -propagation is enabled, 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. +slave receives updates, kpropd updates its log 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. If incremental propagation is +enabled, 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. OPTIONS diff --git a/doc/rst_source/krb_admins/admin_commands/kproplog.rst b/doc/rst_source/krb_admins/admin_commands/kproplog.rst index 00b27d172..5d71575a5 100644 --- a/doc/rst_source/krb_admins/admin_commands/kproplog.rst +++ b/doc/rst_source/krb_admins/admin_commands/kproplog.rst @@ -19,8 +19,8 @@ update log maintained by the :ref:`kadmind(8)` process on the master KDC server and the :ref:`kpropd(8)` 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. +data from the master KDC and update their log file with any updates +returned. The kproplog command requires read access to the update log file. It will display update entries only for the KDC it runs on. diff --git a/doc/rst_source/krb_admins/appl_servers.rst b/doc/rst_source/krb_admins/appl_servers.rst index bcb08a1ff..f6474cdbd 100644 --- a/doc/rst_source/krb_admins/appl_servers.rst +++ b/doc/rst_source/krb_admins/appl_servers.rst @@ -36,10 +36,6 @@ the **ktadd** command from kadmin. :start-after: _ktadd: :end-before: _ktadd_end: -.. note:: Alternatively, the keytab can be generated using - :ref:`ktutil(1)` **add_entry -password** and **write_kt** - commands. - Examples ######## diff --git a/doc/rst_source/krb_admins/conf_ldap.rst b/doc/rst_source/krb_admins/conf_ldap.rst index c5e872809..0a85f6f1a 100644 --- a/doc/rst_source/krb_admins/conf_ldap.rst +++ b/doc/rst_source/krb_admins/conf_ldap.rst @@ -139,7 +139,7 @@ Configuring Kerberos with OpenLDAP back-end kdb5_ldap_util -D cn=admin,dc=example,dc=com stashsrvpw -f /etc/kerberos/service.keyfile cn=krbadmin,dc=example,dc=com -10. Add ``krb5principalname`` to the indexes in slapd.conf to speed up +10. Add ``krbPrincipalName`` to the indexes in slapd.conf to speed up the access. With the LDAP back end it is possible to provide aliases for principal diff --git a/doc/rst_source/krb_admins/database.rst b/doc/rst_source/krb_admins/database.rst index 7ac764f40..9cca18893 100644 --- a/doc/rst_source/krb_admins/database.rst +++ b/doc/rst_source/krb_admins/database.rst @@ -229,9 +229,6 @@ To delete a policy, use the kadmin **delete_policy** command. :start-after: _add_policy: :end-before: _add_policy_end: -.. note:: The policies are created under **realm** container in the - LDAP database. - .. include:: admin_commands/kadmin_local.rst :start-after: _modify_policy: :end-before: _modify_policy_end: @@ -455,12 +452,6 @@ will not be dumped:: If you do not specify a dump file, kdb5_util will dump the database to the standard output. -There is currently a bug where the default dump format omits the -per-principal policy information. In order to dump all the data -contained in the Kerberos database, you must perform a normal dump -(with no option flags) and an additional dump using the "-ov" flag to -a different file. - .. _restore_from_dump: diff --git a/doc/rst_source/krb_admins/install_appl_srv.rst b/doc/rst_source/krb_admins/install_appl_srv.rst index b18ca263f..239ddf4e4 100644 --- a/doc/rst_source/krb_admins/install_appl_srv.rst +++ b/doc/rst_source/krb_admins/install_appl_srv.rst @@ -23,14 +23,13 @@ The keytab file All Kerberos server machines need a keytab file to authenticate to the KDC. By default on UNIX-like systems this file is named -``/etc/krb5.keytab``. The keytab file is an encrypted, local, on-disk -copy of the host's key. The keytab file, like the stash file (see -:ref:`create_db`) is a potential point-of-entry for a break-in, and if -compromised, would allow unrestricted access to its host. The keytab -file should be readable only by root, and should exist only on the -machine'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 machine's root password itself. +``/etc/krb5.keytab``. The keytab file is an local copy of the host's +key. The keytab file is a potential point of entry for a break-in, +and if compromised, would allow unrestricted access to its host. The +keytab file should be readable only by root, and should exist only on +the machine'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 machine's root password. 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 diff --git a/doc/rst_source/krb_admins/install_kdc.rst b/doc/rst_source/krb_admins/install_kdc.rst index 95f70ac13..2589831f6 100644 --- a/doc/rst_source/krb_admins/install_kdc.rst +++ b/doc/rst_source/krb_admins/install_kdc.rst @@ -87,8 +87,7 @@ section. If you are not using DNS SRV records (see :ref:`kdc_hostnames`), you must include the **kdc** tag for each *realm* in the :ref:`realms` section. To communicate with the kadmin 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`. +:ref:`realms` section. An example krb5.conf file:: @@ -318,7 +317,7 @@ between the Kerberos administration daemon kadmind and the kadmin program over the network for further administration. To do this, use the kadmin.local utility on the master KDC. kadmin.local is designed to be run on the master KDC host without using Kerberos authentication -to its database; instead, it must have read and write access to the +to an admin server; instead, it must have read and write access to the Kerberos database on the local filesystem. The administrative principals you create should be the ones you added diff --git a/doc/rst_source/krb_admins/troubleshoot.rst b/doc/rst_source/krb_admins/troubleshoot.rst index 7d2f48288..036f0b50b 100644 --- a/doc/rst_source/krb_admins/troubleshoot.rst +++ b/doc/rst_source/krb_admins/troubleshoot.rst @@ -12,8 +12,10 @@ List This most commonly happens when trying to use a principal with only DES keys, in a release (MIT krb5 1.7 or later) which disables DES by -default. You can re-enable DES by adding ``allow_weak_crypto = true`` -to the :ref:`libdefaults` section of :ref:`krb5.conf(5)`. +default. DES encryption is considered weak due to its inadequate key +size. If you cannot migrate away from its use, you can re-enable DES +by adding ``allow_weak_crypto = true`` to the :ref:`libdefaults` +section of :ref:`krb5.conf(5)`. Seen in: clients diff --git a/doc/rst_source/krb_users/tkt_mgmt.rst b/doc/rst_source/krb_users/tkt_mgmt.rst index 5d17e6a1f..9fdd2b4eb 100644 --- a/doc/rst_source/krb_users/tkt_mgmt.rst +++ b/doc/rst_source/krb_users/tkt_mgmt.rst @@ -50,8 +50,8 @@ A **postdated** ticket is issued with the invalid flag set. After the starting time listed on the ticket, it can be presented to the KDC to obtain valid tickets. -Tickets with the **postdateable** flag set can be used to issue -postdated tickets. +Ticket-granting tickets with the **postdateable** flag set can be used +to obtain postdated service tickets. **Renewable** tickets can be used to obtain new session keys without the user entering their password again. A renewable ticket has two @@ -60,10 +60,10 @@ ticket expires. The second is the latest possible expiration time for any ticket issued based on this renewable ticket. A ticket with the **initial flag** set was issued based on the -authentication protocol, and not on a ticket-granting ticket. Clients -that wish to ensure that the user's key has been recently presented -for verification could specify that this flag must be set to accept -the ticket. +authentication protocol, and not on a ticket-granting ticket. +Application servers that wish to ensure that the user's key has been +recently presented for verification could specify that this flag must +be set to accept the ticket. An **invalid** ticket must be rejected by application servers. Postdated tickets are usually issued with this flag set, and must be @@ -94,8 +94,7 @@ applications do not honor it. An **anonymous** ticket is one in which the named principal is a generic principal for that realm; it does not actually specify the individual that will be using the ticket. This ticket is meant only -to securely distribute a session key. This is a new addition to the -Kerberos V5 protocol and is not yet implemented on MIT servers. +to securely distribute a session key. .. _obtain_tkt: @@ -132,8 +131,7 @@ and you won't get Kerberos tickets. By default, kinit assumes you want tickets for your own username in your default realm. Suppose Jennifer's friend David is visiting, and he wants to borrow a window to check his mail. David needs to get -tickets for himself in his own realm, EXAMPLE.COM [1]_. He would -type:: +tickets for himself in his own realm, EXAMPLE.COM. He would type:: shell% kinit david@EXAMPLE.COM Password for david@EXAMPLE.COM: <-- [Type david's password here.] @@ -174,9 +172,6 @@ type:: lifetime, it will be automatically truncated to the maximum lifetime. -.. [1] Note: the realm EXAMPLE.COM must be listed in your computer's - Kerberos configuration file, :ref:`krb5.conf(5)`. - .. _view_tkt: @@ -303,7 +298,8 @@ Destroying tickets with kdestroy -------------------------------- Your Kerberos tickets are proof that you are indeed yourself, and -tickets can be stolen. If this happens, the person who has them can +tickets could be stolen if someone gains access to a computer where +they are stored. If this happens, the person who has them can masquerade as you until they expire. For this reason, you should destroy your Kerberos tickets when you are away from your computer. diff --git a/doc/rst_source/krb_users/user_commands/kdestroy.rst b/doc/rst_source/krb_users/user_commands/kdestroy.rst index f664f302e..7676dc496 100644 --- a/doc/rst_source/krb_users/user_commands/kdestroy.rst +++ b/doc/rst_source/krb_users/user_commands/kdestroy.rst @@ -76,12 +76,3 @@ SEE ALSO -------- :ref:`kinit(1)`, :ref:`klist(1)` - - -BUGS ----- - -Only the tickets in the specified credentials cache are destroyed. -Separate ticket caches are used to hold root instance and password -changing tickets. These should probably be destroyed too, or all of a -user's tickets kept in a single credentials cache. diff --git a/doc/rst_source/krb_users/user_commands/sclient.rst b/doc/rst_source/krb_users/user_commands/sclient.rst index 13aa14d6b..ebf797253 100644 --- a/doc/rst_source/krb_users/user_commands/sclient.rst +++ b/doc/rst_source/krb_users/user_commands/sclient.rst @@ -12,9 +12,10 @@ SYNOPSIS DESCRIPTION ----------- -sclient will contact a sample server :ref:`sserver(8)` and -authenticate to it using Kerberos version 5 tickets, then display the -server's response. +sclient is a sample application, primarily useful for testing +purposes. It contacts a sample server :ref:`sserver(8)` and +authenticates to it using Kerberos version 5 tickets, then displays +the server's response. SEE ALSO diff --git a/doc/rst_source/krb_users/user_config/k5login.rst b/doc/rst_source/krb_users/user_config/k5login.rst index bf607f789..478967ace 100644 --- a/doc/rst_source/krb_users/user_config/k5login.rst +++ b/doc/rst_source/krb_users/user_config/k5login.rst @@ -29,9 +29,9 @@ containing the following line: bob@FOOBAR.ORG -This would allow ``bob`` to use any of the Kerberos network -applications, such as telnet(1), rlogin(1), rsh(1), and rcp(1), to -access ``alice``'s account, using ``bob``'s Kerberos tickets. +This would allow ``bob`` to use Kerberos network applications, such as +ssh(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 @@ -55,4 +55,4 @@ password. SEE ALSO -------- -telnet(1), rlogin(1), rsh(1), rcp(1), ksu(1), telnetd(8), klogind(8) +kerberos(1) -- 2.26.2