krb5 commit: Add documentation for DNS URI lookups

[Greg Hudson]

https://github.com/krb5/krb5/commit/b99e0e3038423beb867afe4071c310a9707b25a5
commit b99e0e3038423beb867afe4071c310a9707b25a5
Author: Matt Rogers <mrogers at redhat.com>
Date:   Tue Aug 23 20:03:22 2016 -0400

    Add documentation for DNS URI lookups
    
    ticket: 8496

 doc/admin/conf_files/krb5_conf.rst |    7 +++++
 doc/admin/install_clients.rst      |    3 +-
 doc/admin/install_kdc.rst          |    9 +++---
 doc/admin/realm_config.rst         |   48 ++++++++++++++++++++++++++++++++++++
 4 files changed, 62 insertions(+), 5 deletions(-)

diff --git a/doc/admin/conf_files/krb5_conf.rst b/doc/admin/conf_files/krb5_conf.rst
index b31ddff..653aad6 100644
--- 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 ec2cd81..f2c87d0 100644
--- 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 b160932..1b4cc75 100644
--- 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 3747038..c016d72 100644
--- 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