Add documentation for DNS URI lookups

ticket: 8496

diff --git a/doc/admin/conf_files/krb5_conf.rst b/doc/admin/conf_files/krb5_conf.rst
index b31ddff6fce0ff4671b5bb7969bb7fbf334bda8f..653aad613cbc5809381f551826de02f06f1afe58 100644 (file)
--- a/doc/admin/conf_files/krb5_conf.rst
+++ b/doc/admin/conf_files/krb5_conf.rst
@@ -212,6 +212,13 @@ The libdefaults section may contain any of the following relations:
     data), and anything the fake KDC sends will not be trusted without
     verification using some secret that it won't know.
 
+**dns_uri_lookup**
+    Indicate whether DNS URI records should be used to locate the KDCs
+    and other servers for a realm, if they are not listed in the
+    krb5.conf information for the realm.  SRV records are used as a
+    fallback if no URI records were found.  The default value is true.
+    New in release 1.15.
+
 **err_fmt**
     This relation allows for custom error message formatting.  If a
     value is set, error messages will be formatted by substituting a

diff --git a/doc/admin/install_clients.rst b/doc/admin/install_clients.rst
index ec2cd81258902647f9d11ac4729e536abf1f04a3..f2c87d072cb962cbfb145bd6e0e6dc9821e42738 100644 (file)
--- a/doc/admin/install_clients.rst
+++ b/doc/admin/install_clients.rst
@@ -23,7 +23,8 @@ Client machine configuration files
 
 Each machine running Kerberos should have a :ref:`krb5.conf(5)` file.
 At a minimum, it should define a **default_realm** setting in
-:ref:`libdefaults`.  If you are not using DNS SRV records, it must
+:ref:`libdefaults`.  If you are not using DNS SRV records
+(:ref:`kdc_hostnames`) or URI records (:ref:`kdc_discovery`), it must
 also contain a :ref:`realms` section containing information for your
 realm's KDCs.
 

diff --git a/doc/admin/install_kdc.rst b/doc/admin/install_kdc.rst
index b160932ee1cbf7478d9f971e60a0ffe597bb863c..1b4cc75dfa80a70bddfe2de8cb500fbf24dd77c0 100644 (file)
--- a/doc/admin/install_kdc.rst
+++ b/doc/admin/install_kdc.rst
@@ -79,10 +79,11 @@ krb5.conf
 
 If you are not using DNS TXT records (see :ref:`mapping_hostnames`),
 you must specify the **default_realm** in the :ref:`libdefaults`
-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
+section.  If you are not using DNS URI or SRV records (see
+:ref:`kdc_hostnames` and :ref:`kdc_discovery`), 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.
 
 An example krb5.conf file::

diff --git a/doc/admin/realm_config.rst b/doc/admin/realm_config.rst
index 374703885cfa3534239c94ddbcae5a8e9c194fd3..c016d720fded730196113b216ab97b97c982551a 100644 (file)
--- a/doc/admin/realm_config.rst
+++ b/doc/admin/realm_config.rst
@@ -194,6 +194,54 @@ explicit server locations, providing SRV records will still benefit
 unconfigured clients, and be useful for other sites.
 
 
+.. _kdc_discovery:
+
+KDC Discovery
+-------------
+
+As of MIT krb5 1.15, clients can also locate KDCs in DNS through URI
+records (:rfc:`7553`).  Limitations with the SRV record format may
+result in extra DNS queries in situations where a client must failover
+to other transport types, or find a master server.  The URI record can
+convey more information about a realm's KDCs with a single query.
+
+The client performs a query for the following URI records:
+
+* ``_kerberos.REALM`` for fiding KDCs.
+* ``_kerberos-adm.REALM`` for finding kadmin services.
+* ``_kpasswd.REALM`` for finding password services.
+
+The URI record includes a priority, weight, and a URI string that
+consists of case-insensitive colon separated fields, in the form
+``scheme:[flags]:transport:residual``.
+
+* *scheme* defines the registered URI type.  It should always be
+  ``krb5srv``.
+* *flags* contains zero or more flag characters.  Currently the only
+  valid flag is ``m``, which indicates that the record is for a master
+  server.
+* *transport* defines the transport type of the residual URL or
+  address.  Accepted values are ``tcp``, ``udp``, or ``kkdcp`` for the
+  MS-KKDCP type.
+* *residual* contains the hostname, IP address, or URL to be
+  contacted using the specified transport, with an optional port
+  extension.  The MS-KKDCP transport type uses a HTTPS URL, and can
+  include a port and/or path extension.
+
+An example of URI records in a zone file::
+
+  _kerberos.EXAMPLE.COM  URI  10 1 krb5srv:m:tcp:kdc1.example.com
+                         URI  20 1 krb5srv:m:udp:kdc2.example.com:89
+                         URI  40 1 krb5srv::udp:10.10.0.23
+                         URI  30 1 krb5srv::kkdcp:https://proxy:89/auth
+
+URI lookups are enabled by default, and can be disabled by setting
+**dns_uri_lookup** in the :ref:`libdefaults` section of
+:ref:`krb5.conf(5)` to False.  When enabled, URI lookups take
+precedence over SRV lookups, falling back to SRV lookups if no URI
+records are found.
+
+
 .. _db_prop:
 
 Database propagation