* Introduction::
* How Kerberos Works::
* Configuration Files::
+* Using DNS::
* Administrating Kerberos Database Entries::
* Application Servers::
* Backups of Secure Hosts::
@include glossary.texinfo
-@node Configuration Files, Administrating Kerberos Database Entries, How Kerberos Works, Top
+@node Configuration Files, Using DNS, How Kerberos Works, Top
@chapter Configuration Files
@menu
@end group
@end smallexample
-@node Administrating Kerberos Database Entries, Application Servers, Configuration Files, Top
+@node Using DNS, Administrating Kerberos Database Entries, Configuration Files, Top
+@chapter Using DNS
+
+@menu
+* Mapping Hostnames onto Kerberos Realms::
+* Hostnames for KDCs::
+@end menu
+
+@node Mapping Hostnames onto Kerberos Realms, Hostnames for KDCs, Using DNS, Using DNS
+@section Mapping Hostnames onto Kerberos Realms
+
+@include dnstxt.texinfo
+
+@node Hostnames for KDCs, , Mapping Hostnames onto Kerberos Realms, Using DNS
+@section Hostnames for KDCs
+
+@include dnssrv.texinfo
+
+@node Administrating Kerberos Database Entries, Application Servers, Using DNS, Top
@chapter Administrating the Kerberos Database
Your Kerberos database contains all of your realm's Kerberos principals,
--- /dev/null
+@value{COMPANY} recommends that your KDCs have a predefined set of
+CNAME records (DNS hostname aliases), such as @code{@value{KDCSERVER}}
+for the master KDC and
+@code{@value{KDCSLAVE1}}, @code{@value{KDCSLAVE2}}, @dots{} for the
+slave KDCs. This way, if 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 @value{COMPANY} @value{PRODUCT} distribution. A relatively new
+record type called @code{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.)
+
+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:
+
+@table @code
+@item _kerberos._udp
+This is for contacting any KDC. This entry will be used the most often.
+Normally you should list ports 88 and 750 on each of your KDCs.
+
+@item _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.
+
+If you have only one KDC, or for whatever reason there is no accessible
+KDC that would get database changes faster than the others, you do not
+need to define this entry.
+
+@item _kerberos-adm._tcp
+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
+@code{kadmin} program and related utilities. For now, you will also
+need the @code{admin_server} entry in @code{krb5.conf}.
+
+@item _kpasswd._udp
+This should list port 464 on your master KDC. It is used when a user
+changes her password.
+
+@end table
+
+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:
+
+@smallexample
+$ORIGIN foobar.com.
+_kerberos TXT "FOOBAR.COM"
+kerberos CNAME daisy
+kerberos-1 CNAME use-the-force-luke
+kerberos-2 CNAME bunny-rabbit
+_kerberos._udp SRV 0 0 88 daisy
+ SRV 0 0 88 use-the-force-luke
+ SRV 0 0 88 bunny-rabbit
+_kerberos-master._udp SRV 0 0 88 daisy
+_kerberos-adm._tcp SRV 0 0 749 daisy
+_kpasswd._udp SRV 0 0 464 daisy
+@end smallexample
+
+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 @code{admin_server} as noted above) in future versions of
+your @code{krb5.conf} 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.
+
--- /dev/null
+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 @code{krb5.conf} configuration file. (@xref{krb5.conf}.) 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 second mechanism, recently introduced into the MIT code base but not
+currently used by default, works by looking up the information in
+special @code{TXT} records in the Domain Name Service. If this
+mechanism is enabled on the client, it will try to look up a @code{TXT}
+record for the DNS name formed by putting the prefix @code{_kerberos} in
+front of the hostname in question. If that record is not found, it will
+try using @code{_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:
+
+@smallexample
+_kerberos.boston.engineering.foobar.com
+_kerberos.engineering.foobar.com
+_kerberos.foobar.com
+_kerberos.com
+@end smallexample
+
+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.
+
@node Mapping Hostnames onto Kerberos Realms, Ports for the KDC and Admin Services, Kerberos Realms, Realm Configuration Decisions
@section Mapping Hostnames onto Kerberos Realms
-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 @code{krb5.conf} configuration file. (@xref{krb5.conf}.) 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 @value{PRODUCT} System Administrator's Guide contains a thorough
-description of the parts of the @code{krb5.conf} file and what may be
-specified in each. A sample @code{krb5.conf} file appears in
-@ref{krb5.conf}. You should be able to use this file, substituting the
-relevant information for your Kerberos installation for the samples.
-
-The second mechanism, recently introduced into the MIT code base but not
-currently used by default, works by looking up the information in
-special @code{TXT} records in the Domain Name Service. If this
-mechanism is enabled on the client, it will try to look up a @code{TXT}
-record for the DNS name formed by putting the prefix @code{_kerberos} in
-front of the hostname in question. If that record is not found, it will
-try using @code{_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:
-
-@smallexample
-_kerberos.boston.engineering.foobar.com
-_kerberos.engineering.foobar.com
-_kerberos.foobar.com
-_kerberos.com
-@end smallexample
-
-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.
+@include dnstxt.texinfo
@node Ports for the KDC and Admin Services, Slave KDCs, Mapping Hostnames onto Kerberos Realms, Realm Configuration Decisions
@section Ports for the KDC and Admin Services
@node Hostnames for the Master and Slave KDCs, Database Propagation, Slave KDCs, Realm Configuration Decisions
@section Hostnames for the Master and Slave KDCs
-@value{COMPANY} recommends that your KDCs have a predefined set of
-CNAME records (DNS hostname aliases), such as @code{@value{KDCSERVER}}
-for the master KDC and
-@code{@value{KDCSLAVE1}}, @code{@value{KDCSLAVE2}}, @dots{} for the
-slave KDCs. This way, if 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 @value{COMPANY} @value{PRODUCT} distribution. A relatively new
-record type called @code{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.)
-
-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:
-
-@table @code
-@item _kerberos._udp
-This is for contacting any KDC. This entry will be used the most often.
-Normally you should list ports 88 and 750 on each of your KDCs.
-
-@item _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.
-
-If you have only one KDC, or for whatever reason there is no accessible
-KDC that would get database changes faster than the others, you do not
-need to define this entry.
-
-@item _kerberos-adm._tcp
-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
-@code{kadmin} program and related utilities. For now, you will also
-need the @code{admin_server} entry in @code{krb5.conf}.
-
-@item _kpasswd._udp
-This should list port 464 on your master KDC. It is used when a user
-changes her password.
-
-@end table
-
-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:
-
-@smallexample
-$ORIGIN foobar.com.
-_kerberos TXT "FOOBAR.COM"
-kerberos CNAME daisy
-kerberos-1 CNAME use-the-force-luke
-kerberos-2 CNAME bunny-rabbit
-_kerberos._udp SRV 0 0 88 daisy
- SRV 0 0 88 use-the-force-luke
- SRV 0 0 88 bunny-rabbit
-_kerberos-master._udp SRV 0 0 88 daisy
-_kerberos-adm._tcp SRV 0 0 749 daisy
-_kpasswd._udp SRV 0 0 464 daisy
-@end smallexample
-
-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 @code{admin_server} as noted above) in future versions of
-your @code{krb5.conf} 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.
+@include dnssrv.texinfo
@node Database Propagation, , Hostnames for the Master and Slave KDCs, Realm Configuration Decisions
@section Database Propagation
projects / krb5.git / commitdiff