svn rev #25762: trunk/doc/rst_source/krb_admins/ advanced/ conf_files/
ghudson@MIT.EDU
ghudson at MIT.EDU
Mon Mar 12 16:24:45 EDT 2012
http://src.mit.edu/fisheye/changelog/krb5/?cs=25762
Commit By: ghudson
Log Message:
Edit RST admin guide for clarity and accuracy
Some more notable changes include:
* plugin development is a top-level guide, so remove the advanced
topic page in the admin guide.
* Remove krb5-appl references in firewall configuration section.
* Remove dns.rst since it was only referenced from a man page (which
doesn't work) and just contained a pair of links, one of which was
to the immediately preceding section.
* Don't document TXT record support as if it were supported in the
default build. It can be documented in an appendix.
* A couple of troubleshooting segments gave very
specifically-applicable advice based on general error messages, or
described problems which were fixed several releases ago.
Changed Files:
U trunk/doc/rst_source/krb_admins/advanced/index.rst
U trunk/doc/rst_source/krb_admins/advanced/ldapbackend.rst
D trunk/doc/rst_source/krb_admins/advanced/plugins.rst
U trunk/doc/rst_source/krb_admins/appl_servers.rst
U trunk/doc/rst_source/krb_admins/backup_host.rst
U trunk/doc/rst_source/krb_admins/conf_files/krb5_conf.rst
U trunk/doc/rst_source/krb_admins/database.rst
D trunk/doc/rst_source/krb_admins/dns.rst
U trunk/doc/rst_source/krb_admins/env_variables.rst
U trunk/doc/rst_source/krb_admins/index.rst
U trunk/doc/rst_source/krb_admins/realm_config.rst
U trunk/doc/rst_source/krb_admins/troubleshoot.rst
Modified: trunk/doc/rst_source/krb_admins/advanced/index.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/advanced/index.rst 2012-03-09 20:40:55 UTC (rev 25761)
+++ trunk/doc/rst_source/krb_admins/advanced/index.rst 2012-03-12 20:24:45 UTC (rev 25762)
@@ -8,7 +8,6 @@
:maxdepth: 1
ldapbackend.rst
- plugins.rst
Topics in TODO list:
Modified: trunk/doc/rst_source/krb_admins/advanced/ldapbackend.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/advanced/ldapbackend.rst 2012-03-09 20:40:55 UTC (rev 25761)
+++ trunk/doc/rst_source/krb_admins/advanced/ldapbackend.rst 2012-03-12 20:24:45 UTC (rev 25762)
@@ -3,7 +3,7 @@
LDAP backend on Ubuntu 10.4 (lucid)
===================================
-Setting up Kerberos v1.9 with LDAP backend on Ubuntu 10.4 (lucid Lynx)
+Setting up Kerberos v1.9 with LDAP backend on Ubuntu 10.4 (Lucid Lynx)
Prerequisites
@@ -31,62 +31,35 @@
::
- util/reconf
- ./configure –with-ldap
+ ./configure --with-ldap
make
sudo make install
-.. note:: in some environments one may need to suppress rpath linker
- option: ``./configure –with-ldap –disable-rpath``
-
Setting up Kerberos
-------------------
Configuration
~~~~~~~~~~~~~
-Update Kerberos configuration files with the backend information:
+Update kdc.conf with the LDAP back-end information::
-krb5.conf::
-
[realms]
EXAMPLE.COM = {
database_module = LDAP
}
- [dbdefaults]
- ldap_kerberos_container_dn = "cn=krbContainer,dc=example,dc=com"
-
[dbmodules]
LDAP = {
db_library = kldap
- ldap_kerberos_container_dn = "cn=krbContainer,dc=example,dc=com"
+ ldap_kerberos_container_dn = cn=krbContainer,dc=example,dc=com
ldap_kdc_dn = cn=admin,dc=example,dc=com
ldap_kadmind_dn = cn=admin,dc=example,dc=com
- ldap_service_password_file = /tmp/krb5kdc/admin.stash
+ ldap_service_password_file = /usr/local/var/krb5kdc/admin.stash
ldap_servers = ldapi:///
}
-kdc.conf::
- [realms]
- EXAMPLE.COM = {
- acl_file = /tmp/kadm5.acl
-
-kadm5.acl::
-
- # See Kerberos V5 Installation Guide for detail of ACL setup and
- # configuration
- */admin *
-
-Setup run-time environment to point to the Kerberos configuration
-files::
-
- export KRB5_CONFIG=/tmp/krb5.conf
- export KRB5_KDC_PROFILE=/tmp/kdc.conf
-
-
Schema
~~~~~~
@@ -94,28 +67,28 @@
``src/plugins/kdb/ldap/libkdb_ldap/kerberos.schema`` into
``/etc/ldap/schema``
-Warning: it should be done after slapd is installed to avoid problems
-with slapd installation
+Warning: this step should be done after slapd is installed to avoid
+problems with slapd installation.
To convert kerberos.schema to run-time configuration (``cn=config``)
-do the folowing:
+do the following:
-#. create temporary file ``/tmp/schema_convert.conf`` with the
+#. Create a temporary file ``/tmp/schema_convert.conf`` with the
following content::
include /etc/ldap/schema/kerberos.schema
-#. Create temporary directory ``/tmp/krb5_ldif``
+#. Create a temporary directory ``/tmp/krb5_ldif``.
#. Run::
slaptest -f /tmp/schema_convert.conf -F /tmp/krb5_ldif
- It should result into a new file
- ``/tmp/krb5_ldif/cn=config/cn=schema/cn={0}kerberos.ldif``
+ This should in a new file named
+ ``/tmp/krb5_ldif/cn=config/cn=schema/cn={0}kerberos.ldif``.
#. Edit ``/tmp/krb5_ldif/cn=config/cn=schema/cn={0}kerberos.ldif`` by
- replacing lines::
+ replacing the lines::
dn: cn={0}kerberos
cn: {0}kerberos
@@ -133,25 +106,25 @@
createTimestamp: ...
entryCSN: ...
modifiersName: cn=config
- modifyTimestamp: ...
+ modifyTimestamp: ...
#. Load the new schema with ldapadd (with the proper authentication)::
ldapadd -Y EXTERNAL -H ldapi:/// -f /tmp/krb5_ldif/cn=config/cn=schema/cn={0}kerberos.ldif
- which should result into ``adding new entry
- "cn=kerberos,cn=schema,cn=config"`` message
+ which should result the message ``adding new entry
+ "cn=kerberos,cn=schema,cn=config"``.
Create Kerberos database
------------------------
Using LDAP administrator credentials, create Kerberos database and
-stash::
+master key stash::
- kdb5_ldap_util -D cn=admin,dc=example,dc=com -H ldapi:/// create
+ kdb5_ldap_util -D cn=admin,dc=example,dc=com -H ldapi:/// create -s
-Stash the password::
+Stash the LDAP administrative passwords::
kdb5_ldap_util -D cn=admin,dc=example,dc=com -H ldapi:/// stashsrvpw cn=admin,dc=example,dc=com
Modified: trunk/doc/rst_source/krb_admins/appl_servers.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/appl_servers.rst 2012-03-09 20:40:55 UTC (rev 25761)
+++ trunk/doc/rst_source/krb_admins/appl_servers.rst 2012-03-12 20:24:45 UTC (rev 25762)
@@ -45,17 +45,14 @@
########
Here is a sample session, using configuration files that enable only
-*des-cbc-crc* encryption::
+AES encryption::
kadmin: ktadd host/daffodil.mit.edu at ATHENA.MIT.EDU
- kadmin: Entry for principal host/daffodil.mit.edu at ATHENA.MIT.EDU with kvno 2, encryption type DES-CBC-CRC added to keytab WRFILE:/etc/krb5.keytab.
+ Entry for principal host/daffodil.mit.edu with kvno 2, encryption type aes256-cts-hmac-sha1-96 added to keytab FILE:/etc/krb5.keytab
+ Entry for principal host/daffodil.mit.edu with kvno 2, encryption type aes128-cts-hmac-sha1-96 added to keytab FILE:/etc/krb5.keytab
kadmin:
- kadmin: ktadd -k /usr/local/var/krb5kdc/kadmind.keytab kadmin/admin kadmin/changepw
- kadmin: Entry for principal kadmin/admin at ATHENA.MIT.EDU with kvno 3, encryption type DES-CBC-CRC added to keytab WRFILE:/usr/local/var/krb5kdc/kadmind.keytab.
- kadmin:
-
Removing principals from keytabs
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -70,70 +67,57 @@
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'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::
+A Kerberos application server host must keep its clock synchronized or
+it will reject authentication requests from clients. Modern operating
+systems typically provide a facility to maintain the correct time;
+make sure it is enabled. This is especially important on virtual
+machines, where clocks tend to drift more rapidly than normal machine
+clocks.
- gettime -s kerberos
+The default allowable clock skew is controlled by the **clockskew**
+variable in :ref:`libdefaults`.
-If the host is not likely to be rebooted frequently, you may also want
-to set up a cron job that adjusts the time on a regular basis.
-
Getting DNS information correct
-------------------------------
-Several aspects of Kerberos rely on name service. In order for
-Kerberos to provide its high level of security, it is less forgiving
-of name service problems than some other parts of your network. It is
-important that your Domain Name System (DNS) entries and your hosts
-have the correct information.
+Several aspects of Kerberos rely on name service. When a hostname is
+used to name a service, the Kerberos library canonicalizes the
+hostname using forward and reverse name resolution. (The reverse name
+resolution step can be turned off using the **rdns** variable in
+:ref:`libdefaults`.) The result of this canonicalization must match
+the principal entry in the host's keytab, or authentication will fail.
Each host's canonical name must be the fully-qualified host name
(including the domain), and each host's IP address must
reverse-resolve to the canonical name.
-Other than the localhost entry, make all entries in each machine's
-/etc/hosts file in the following form::
+Configuration of hostnames varies by operating system. On the
+application server itself, canonicalization will typically use the
+``/etc/hosts`` file rather than the DNS. Ensure that the line for the
+server's hostname is in the following form::
IP address fully-qualified hostname aliases
Here is a sample ``/etc/hosts`` file::
# this is a comment
- 127.0.0.1 localhost localhost at mit.edu
- 10.0.0.6 daffodil.mit.edu trillium wake-robin
+ 127.0.0.1 localhost localhost.mit.edu
+ 10.0.0.6 daffodil.mit.edu daffodil trillium wake-robin
-Additionally, on Solaris machines, you need to be sure the ``hosts``
-entry in the file ``/etc/nsswitch.conf`` includes the source ``dns``
-as well as ``file``.
+The output of ``klist -k`` for this example host should look like::
-Finally, each host's keytab file must include a host/key pair for the
-host's canonical name. You can list the keys in a keytab file by
-issuing the command ``klist -k``. For example::
-
viola# klist -k
Keytab name: /etc/krb5.keytab
KVNO Principal
---- ------------------------------------------------------------
- 1 host/daffodil.mit.edu at ATHENA.MIT.EDU
+ 2 host/daffodil.mit.edu at ATHENA.MIT.EDU
-If you telnet to the host with a fresh credentials cache (ticket
-file), and then :ref:`klist(1)`, the host's service principal should
-be::
+If you were to ssh to this host with a fresh credentials cache (ticket
+file), and then :ref:`klist(1)`, the output should list a service
+principal of ``host/daffodil.mit.edu at ATHENA.MIT.EDU``.
- host/fully-qualified-hostname at REALM_NAME.
-
.. _conf_firewall:
Configuring your firewall to work with Kerberos V5
@@ -141,67 +125,27 @@
If you need off-site users to be able to get Kerberos tickets in your
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
+that you have a slave KDC outside your firewall, or that 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 :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.
+admin server on the kpasswd port (which defaults to 464). If you need
+off-site users to be able to administer your Kerberos realm, they must
+be able to get to your Kerberos admin server on the administrative
+port (which defaults to 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
-outgoing TCP and UDP requests to port 88. Additionally, if they will
-need to get to any Kerberos V4 KDCs, you may also need to allow TCP
-and UDP requests to port 750. If your on-site users inside your
-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.
+outgoing TCP and UDP requests to port 88, and to port 464 to allow
+password changes. If your on-site users inside your 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. :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
-on the appropriate ports for the programs they will be using. The
-following lines from ``/etc/services`` show the default port numbers
-for the Kerberos V5 programs::
-
- ftp 21/tcp # Kerberos ftp and telnet use the
- telnet 23/tcp # default ports
- kerberos 88/udp kdc # Kerberos V5 KDC
- kerberos 88/tcp kdc # Kerberos V5 KDC
- klogin 543/tcp # Kerberos authenticated rlogin
- kshell 544/tcp cmd # and remote shell
- kerberos-adm 749/tcp # Kerberos 5 admin/changepw
- kerberos-adm 749/udp # Kerberos 5 admin/changepw
- krb5_prop 754/tcp # Kerberos slave propagation
- eklogin 2105/tcp # Kerberos auth. & encrypted rlogin
-
-By default, Kerberos V5 telnet and ftp use the same ports as the
-standard telnet and ftp programs, so if you already allow telnet and
-ftp connections through your firewall, the Kerberos V5 versions will
-get through as well. If you do not already allow telnet and ftp
-connections through your firewall, but need your users to be able to
-use Kerberos V5 telnet and ftp, you can either allow ftp and telnet
-connections on the standard ports, or switch these programs to
-non-default port numbers and allow ftp and telnet connections on those
-ports to get through. Kerberos V5 rlogin uses the ``klogin`` service,
-which by default uses port 543. Encrypted Kerberos V5 rlogin uses the
-``eklogin`` service, which by default uses port 2105. Kerberos V5 rsh
-uses the kshell service, which by default uses port 544. However, the
-server must be able to make a TCP connection from the kshell port to
-an arbitrary port on the client, so if your users are to be able to
-use rsh from outside your firewall, the server they connect to must be
-able to send outgoing packets to arbitrary port numbers. Similarly,
-if your users need to run rsh from inside your firewall to hosts
-outside your firewall, the outside server needs to be able to connect
-to an arbitrary port on the machine inside your firewall. Because
-Kerberos V5 rcp uses rsh, the same issues apply. If you need to use
-rsh (or rcp) through your firewall and are concerned with the security
-implications of allowing connections to arbitrary ports, MIT suggests
-that you have rules that specifically name these applications and, if
-possible, list the allowed hosts.
-
-The book UNIX System Security, by David Curry, is a good starting
+The book *UNIX System Security*, by David Curry, is a good starting
point for learning to configure firewalls.
Modified: trunk/doc/rst_source/krb_admins/backup_host.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/backup_host.rst 2012-03-09 20:40:55 UTC (rev 25761)
+++ trunk/doc/rst_source/krb_admins/backup_host.rst 2012-03-12 20:24:45 UTC (rev 25762)
@@ -10,12 +10,14 @@
When you back up a secure host, you should exclude the host's keytab
file from the backup. If someone obtained a copy of the keytab from a
backup, that person could make any host masquerade as the host whose
-keytab was compromised. This could be particularly dangerous if the
-compromised keytab was from one of your KDCs. If the machine has a
-disk crash and the keytab file is lost, it is easy to generate another
-keytab file. (See :ref:`add_princ_kt`.) If you are unable to exclude
-particular files from backups, you should ensure that the backups are
-kept as secure as the host's root password.
+keytab was compromised. In many configurations, knowledge of the
+host's keytab also allows root access to the host. This could be
+particularly dangerous if the compromised keytab was from one of your
+KDCs. If the machine has a disk crash and the keytab file is lost, it
+is easy to generate another keytab file. (See :ref:`add_princ_kt`.)
+If you are unable to exclude particular files from backups, you should
+ensure that the backups are kept as secure as the host's root
+password.
Backing up the Kerberos database
Modified: trunk/doc/rst_source/krb_admins/conf_files/krb5_conf.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/conf_files/krb5_conf.rst 2012-03-09 20:40:55 UTC (rev 25761)
+++ trunk/doc/rst_source/krb_admins/conf_files/krb5_conf.rst 2012-03-12 20:24:45 UTC (rev 25762)
@@ -406,8 +406,7 @@
distinguish the colon from a port separator. For your computer to
be able to communicate with the KDC for each realm, this tag must
be given a value in each realm subsection in the configuration
- file, or there must be DNS SRV records specifying the KDCs (see
- :ref:`using_dns`).
+ file, or there must be DNS SRV records specifying the KDCs.
**kpasswd_server**
Points to the server where all the password changes are performed.
Modified: trunk/doc/rst_source/krb_admins/database.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/database.rst 2012-03-09 20:40:55 UTC (rev 25761)
+++ trunk/doc/rst_source/krb_admins/database.rst 2012-03-12 20:24:45 UTC (rev 25762)
@@ -7,38 +7,34 @@
additions to krb5-bugs at mit.edu. Your contribution is
greatly appreciated.
-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 :ref:`kadmin(1)` program to make changes to the entries
-in the database. (One notable exception is that users will use the
+A Kerberos database contains all of a 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
+: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.
: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 :ref:`kadmind(8)` and :ref:`krb5kdc(8)`
-daemons at boot time.
+a Kerberos database. It also contains commands to roll over the
+database master key, and to stash a copy of the key so that the
+:ref:`kadmind(8)` and :ref:`krb5kdc(8)` daemons can use the database
+without manual input.
-kadmin provides for the maintenance of Kerberos principals, KADM5
-policies, and service key tables (keytabs). It exists as both a
-Kerberos client, kadmin, using Kerberos authentication and an RPC, to
-operate securely from anywhere on the network, and as a local client,
-kadmin.local, intended to run directly on the KDC without Kerberos
-authentication. kadmin.local need not run on the kdc if the database
-is LDAP. Other than the fact that the remote client uses Kerberos to
-authenticate the person using it, the functionalities of the two
-versions are identical. The local version is necessary to enable you
-to set up enough of the database to be able to use the remote version.
-It replaces the now obsolete kdb5_edit (except for database dump and
-load, which are provided by kdb5_util).
+:ref:`kadmin(1)` provides for the maintenance of Kerberos principals,
+password policies, and service key tables (keytabs). Normally it
+operates as a network client using Kerberos authentication to
+communicate with :ref:`kadmind(8)`, but there is also a variant, named
+kadmin.local, which directly accesses the Kerberos database on the
+local filesystem (or through LDAP). kadmin.local is necessary to set
+up enough of the database to be able to use the remote version.
-The remote version authenticates to the KADM5 server using the service
-principal ``kadmin/admin``. If the credentials cache contains a ticket
-for the ``kadmin/admin`` principal, and the **-c** ccache option is
+kadmin can authenticate to the admin server using the service
+principal ``kadmin/HOST`` (where *HOST* is the hostname of the admin
+server) or ``kadmin/admin``. If the credentials cache contains a
+ticket for either service principal and the **-c** ccache option is
specified, that ticket is used to authenticate to KADM5. Otherwise,
the **-p** and **-k** options are used to specify the client Kerberos
principal name used to authenticate. Once kadmin has determined the
@@ -309,8 +305,9 @@
:start-after: _change_password:
:end-before: _change_password_end:
-.. note:: *change_password* will not let you change the password to
- one that is in the principal's password history.
+.. note:: Password changes through kadmin are subject to the same
+ password policies as would apply to password changes through
+ :ref:`kpasswd(1)`.
Policies
@@ -372,8 +369,6 @@
Updating the history key
~~~~~~~~~~~~~~~~~~~~~~~~
-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.
@@ -381,9 +376,9 @@
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
encryption type) at the cost of invalidating currently stored old
-keys. To change the history key, run::
+keys. To change the history key, run::
- kadmin: change_password -randkey kadmin/history
+ kadmin: change_password -randkey kadmin/history
This command will fail if you specify the **-keepold** flag. Only one
new history key will be created, even if you specify multiple key/salt
@@ -391,7 +386,7 @@
In the future, we plan to migrate towards encrypting old keys in the
master key instead of the history key, and implementing proper
-rollover support for stored old keys. - implemented in 1.8+
+rollover support for stored old keys.
.. _db_operations:
@@ -725,7 +720,7 @@
In order for a KDC in one realm to authenticate Kerberos users in a
different realm, it must share a key with the KDC in the other realm.
In both databases, there must be krbtgt service principals for realms.
-These principals should all have the same passwords, key version
+These principals must all have the same passwords, key version
numbers, and encryption types.
For example, if the administrators of ATHENA.MIT.EDU and EXAMPLE.COM
@@ -823,10 +818,11 @@
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
-``kiprop/hostname`` (where *hostname* is, as usual, the lower-case,
-fully-qualified, canonical name for the host) registered and keys
-stored in the default keytab file (``/etc/krb5.keytab``).
+Both master and slave sides must have a principal named
+``kiprop/hostname`` (where *hostname* is the lowercase,
+fully-qualified, canonical name for the host) registered in the
+Kerberos database, and have keys for that principal stored in the
+default keytab file (``/etc/krb5.keytab``).
On the master KDC side, the ``kiprop/hostname`` principal must be
listed in the kadmind ACL file kadm5.acl, and given the **p**
@@ -854,9 +850,7 @@
propagation fails to connect for some reason, the process on the
slave may hang waiting for it, and will need to be restarted.
- The master and slave must be able to initiate TCP connections in
- both directions, without an intervening NAT. They must also be able
- to communicate over IPv4, since MIT's kprop and RPC code does not
- currently support IPv6.
+ both directions, without an intervening NAT.
Sun/MIT incremental propagation differences
Modified: trunk/doc/rst_source/krb_admins/env_variables.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/env_variables.rst 2012-03-09 20:40:55 UTC (rev 25761)
+++ trunk/doc/rst_source/krb_admins/env_variables.rst 2012-03-12 20:24:45 UTC (rev 25762)
@@ -5,46 +5,37 @@
**KRB5_CONFIG**
Main Kerberos configuration file. (See :ref:`mitK5defaults` for
- the default name)
+ the default name.)
**KRB5_KDC_PROFILE**
KDC configuration file. (See :ref:`mitK5defaults` for the default
- name)
+ name.)
**KRB5_KTNAME**
- Default *keytab* file name. (See :ref:`mitK5defaults` for the
- default name)
+ Default keytab file name. (See :ref:`mitK5defaults` for the
+ default name.)
**KRB5CCNAME**
Default name for the credentials cache file, in the form *type*\:\
*residual*. The type of the default cache may determine the
availability of a cache collection. For instance, a default cache
- of type DIR causes caches within the directory to be present in
- the global cache collection.
+ of type ``DIR`` causes caches within the directory to be present
+ in the global cache collection.
**KRB5RCACHETYPE**
- Default replay cache type. Defaults to "dfl".
+ Default replay cache type. Defaults to ``dfl``. A value of
+ ``none`` disables the replay cache.
- E.g. ``KRB5RCACHETYPE=none``
-
-**KRB5RCACHENAME**
- Default replay cache name. (See :ref:`mitK5defaults` for the
- default name)
-
**KRB5RCACHEDIR**
Default replay cache directory. (See :ref:`mitK5defaults` for the
- default location)
+ default location.)
**KPROP_PORT**
: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``
-
- The setting of this environment variable can be overridden by
- the tracing behavior set by the application using either of the following API:
-
- * :c:func:`krb5_set_trace_callback()` or
- * :c:func:`krb5_set_trace_filename()`
+ Filename for trace-logging output (introduced in release 1.9).
+ For example, ``env KRB5_TRACE=/dev/stdout kinit`` would send
+ tracing information for kinit to ``/dev/stdout``. Some programs
+ may ignore this variable (particularly setuid or login system
+ programs).
Modified: trunk/doc/rst_source/krb_admins/index.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/index.rst 2012-03-09 20:40:55 UTC (rev 25761)
+++ trunk/doc/rst_source/krb_admins/index.rst 2012-03-12 20:24:45 UTC (rev 25762)
@@ -10,7 +10,6 @@
install.rst
conf_files/index.rst
realm_config.rst
- dns.rst
database.rst
conf_ldap.rst
appl_servers.rst
Modified: trunk/doc/rst_source/krb_admins/realm_config.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/realm_config.rst 2012-03-09 20:40:55 UTC (rev 25761)
+++ trunk/doc/rst_source/krb_admins/realm_config.rst 2012-03-12 20:24:45 UTC (rev 25762)
@@ -12,9 +12,9 @@
* The name of your Kerberos realm (or the name of each realm, if you
need more than one).
-* How you will map your hostnames onto Kerberos realms.
-* Which ports your KDC and and kadmin (database access) services will
- use.
+* How you will assign your hostnames to Kerberos realms.
+* Which ports your KDC and and kadmind services will use, if they will
+ not be using the default ports.
* How many slave KDCs you need and where they should be located.
* The hostnames of your master and slave KDCs.
* How frequently you will propagate the database from the master KDC
@@ -46,52 +46,37 @@
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(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.
+The first mechanism works through a set of rules in the
+:ref:`domain_realm` section of :ref:`krb5.conf(5)`. You can specify
+mappings for an entire domain or on a per-hostname basis. Typically
+you would do this by specifying the mappings for a given domain or
+subdomain and listing the exceptions.
-The second mechanism works by looking up the information in special
-TXT records in the Domain Name Service. This is currently not used by
-default because security holes could result if the DNS TXT records
-were spoofed. If this mechanism is enabled on the client, it will try
-to look up a TXT record for the DNS name formed by putting the prefix
-``_kerberos`` in front of the hostname in question. If that record is
-not found, it will try using ``_kerberos`` and the host's domain name,
-then its parent domain, and so forth. So for the hostname
-``BOSTON.ENGINEERING.FOOBAR.COM``, the names looked up would be::
+The second mechanism is to use KDC host-based service referrals. With
+this method, the KDC's krb5.conf has a full [domain_realm] mapping for
+hosts, but the clients do not, or have mappings for only a subset of
+the hosts they might contact. When a client needs to contact a server
+host for which it has no mapping, it will ask the client realm's KDC
+for the service ticket, and will receive a referral to the appropriate
+service realm.
- _kerberos.boston.engineering.foobar.com
- _kerberos.engineering.foobar.com
- _kerberos.foobar.com
- _kerberos.com
+To use referrals, clients must be running MIT krb5 1.6 or later, and
+the KDC must be running MIT krb5 1.7 or later. The
+**host_based_services** and **no_host_referral** variables in the
+:ref:`kdc_realms` section of :ref:`kdc.conf(5)` can be used to
+fine-tune referral behavior on the KDC.
-The value of the first TXT record found is taken as the realm name.
-(Obviously, this doesn't work all that well if a host and a subdomain
-have the same name, and different realms. For example, if all the
-hosts in the ``ENGINEERING.FOOBAR.COM`` domain are in the
-``ENGINEERING.FOOBAR.COM`` realm, but a host named
-``ENGINEERING.FOOBAR.COM`` is for some reason in another realm. In
-that case, you would set up TXT records for all hosts, rather than
-relying on the fallback to the domain name.)
-Even if you do not choose to use this mechanism within your site, you
-may wish to set it up anyway, for use when interacting with other
-sites.
-
-
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(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`.
+ports, as long as they are specified in each host's
+:ref:`krb5.conf(5)` files or in DNS SRV records, 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`.
Slave KDCs
@@ -103,10 +88,9 @@
both physically and logically, depends on the specifics of your
network.
-All of the Kerberos authentication on your network requires that each
-client be able to contact a KDC. Therefore, you need to anticipate
-any likely reason a KDC might be unavailable and have a slave KDC to
-take up the slack.
+Kerberos authentication requires that each client be able to contact a
+KDC. Therefore, you need to anticipate any likely reason a KDC might
+be unavailable and have a slave KDC to take up the slack.
Some considerations include:
@@ -132,21 +116,14 @@
you need to swap a machine, you only need to change a DNS entry,
rather than having to change hostnames.
-A new mechanism for locating KDCs of a realm through DNS has been
-added to the MIT Kerberos V5 distribution. A relatively new record
-type called SRV has been added to DNS. Looked up by a service name
-and a domain name, these records indicate the hostname and port number
-to contact for that service, optionally with weighting and
-prioritization. (See :rfc:`2782` if you want more information. You
-can follow the example below for straightforward cases.)
+As of MIT krb5 1.4, clients can locate a realm's KDCs through DNS
+using SRV records (:rfc:`2782`), assuming the Kerberos realm name is
+also a DNS domain name. These records indicate the hostname and port
+number to contact for that service, optionally with weighting and
+prioritization. The domain name used in the SRV record name is the
+realm name. Several different Kerberos-related service names are
+used:
-The use with Kerberos is fairly straightforward. The domain name used
-in the SRV record name is the domain-style Kerberos realm name. (It
-is possible to have Kerberos realm names that are not DNS-style names,
-but we don't recommend it for Internet use, and our code does not
-support it well.) Several different Kerberos-related service names
-are used:
-
_kerberos._udp
This is for contacting any KDC by UDP. This entry will be used
the most often. Normally you should list port 88 on each of your
@@ -159,13 +136,10 @@
normally you should use port 88.
_kerberos-master._udp
This entry should refer to those KDCs, if any, that will
- immediately see password changes to the Kerberos database. This
- entry is used only in one case, when the user is logging in and
- the password appears to be incorrect; the master KDC is then
- contacted, and the same password used to try to decrypt the
- response, in case the user's password had recently been changed
- and the first KDC contacted hadn't been updated. Only if that
- fails is an "incorrect password" error given.
+ immediately see password changes to the Kerberos database. If a
+ user is logging in and the password appears to be incorrect, the
+ client will retry with the master KDC before failing with an
+ "incorrect password" error given.
If you have only one KDC, or for whatever reason there is no
accessible KDC that would get database changes faster than the
@@ -174,15 +148,16 @@
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
:ref:`kadmin(1)` program and related utilities. For now, you will
- also need the admin_server entry in :ref:`krb5.conf(5)`.
+ also need the **admin_server** variable 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.
+ user changes her password. If this entry is not defined but a
+ _kerberos-adm._tcp entry is defined, the client will use the
+ _kerberos-adm._tcp entry with the port number changed to 749.
-Be aware, however, that the DNS SRV specification requires that the
-hostnames listed be the canonical names, not aliases. So, for
-example, you might include the following records in your (BIND-style)
-zone file::
+The DNS SRV specification requires that the hostnames listed be the
+canonical names, not aliases. So, for example, you might include the
+following records in your (BIND-style) zone file::
$ORIGIN foobar.com.
_kerberos TXT "FOOBAR.COM"
@@ -196,18 +171,11 @@
_kerberos-adm._tcp SRV 0 0 749 daisy
_kpasswd._udp SRV 0 0 464 daisy
-As with the DNS-based mechanism for determining the Kerberos realm of
-a host, we recommend distributing the information this way for use by
-other sites that may want to interact with yours using Kerberos, even
-if you don't immediately make use of it within your own site. If you
-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 :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.
+Clients can also locate services using the **kdc**, **master_kdc**,
+**admin_server**, and **kpasswd_server** variables in the
+:ref:`realms` section of :ref:`krb5.conf(5)`. However, providing SRV
+records may still be useful for use by other sites or by unconfigured
+client hosts.
.. _db_prop:
Modified: trunk/doc/rst_source/krb_admins/troubleshoot.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/troubleshoot.rst 2012-03-09 20:40:55 UTC (rev 25761)
+++ trunk/doc/rst_source/krb_admins/troubleshoot.rst 2012-03-12 20:24:45 UTC (rev 25762)
@@ -10,58 +10,15 @@
.. error:: credential verification failed: KDC has no support for
encryption type
-Add ``allow_weak_crypto = true`` to the [libdefaults] section of
-:ref:`krb5.conf(5)`.
+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)`.
-Version 1.7+
-
Seen in: clients
----
-.. error:: Hostname cannot be canonicalized
-
-The problem is that ssh is attempting to authenticate to the
-canonicalization of inside-host in DNS, but since that's inside your
-internal network, there is no DNS available to do the
-canonicalization, so one needs to tell GSSAPI what the hostname is
-separately.
-
-| Host inside-host
-| GSSAPITrustDns no
-| HostName inside-host.inside.domain
-| ProxyCommand ssh -t jump-box.example.com "nc -w2 %h %p"
-
-``GSSAPITrustDns yes`` is setting the exact opposite of ``rdns =
-false``. It's the equivalent of ``rdns = true``.
-
-External links: [http://www.mail-archive.com/kerberos@mit.edu/msg17101.html]
-
-Seen in: ssh
-
-----
-
-.. error:: Wrong principal in request
-
-If referrals are being used, specifying the host to realm mapping in
-the krb5 profile results in the referrals logic being disabled and may
-solve the problem.
-
-External links: [http://www.mail-archive.com/kerberos@mit.edu/msg16257.html]
-
-Seen in: ssh
-
-----
-
.. include:: ./install_kdc.rst
:start-after: _prop_failed_start:
:end-before: _prop_failed_end:
-
-----
-
-.. error:: Unable to find requested database type - while initializing
- database for realm X.Y
-
-Set **db_module_dir** in :ref:`dbmodules` to the absolute path to the
-location of the database plugin
-
More information about the cvs-krb5
mailing list