From: Matt Rogers Date: Wed, 24 Aug 2016 00:03:22 +0000 (-0400) Subject: Add documentation for DNS URI lookups X-Git-Tag: krb5-1.15-beta1~38 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=b99e0e3038423beb867afe4071c310a9707b25a5;p=thirdparty%2Fkrb5.git 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 b31ddff6fc..653aad613c 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 ec2cd81258..f2c87d072c 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 b160932ee1..1b4cc75dfa 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 374703885c..c016d720fd 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