From a6753706efd19dc14e718c33a62a4f2062e619a1 Mon Sep 17 00:00:00 2001 From: Jen Selby Date: Thu, 30 May 2002 21:25:47 +0000 Subject: [PATCH] Added the DNS information to the admin guide. The dns information is now in separate files, which are included by the install and admin guides. git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@14459 dc483132-0cff-0310-8789-dd5450dbe970 --- doc/admin.texinfo | 23 +++++++- doc/dnssrv.texinfo | 81 ++++++++++++++++++++++++++++ doc/dnstxt.texinfo | 38 ++++++++++++++ doc/install.texinfo | 125 +------------------------------------------- 4 files changed, 142 insertions(+), 125 deletions(-) create mode 100644 doc/dnssrv.texinfo create mode 100644 doc/dnstxt.texinfo diff --git a/doc/admin.texinfo b/doc/admin.texinfo index 0bd6c9f74..37bda9669 100644 --- a/doc/admin.texinfo +++ b/doc/admin.texinfo @@ -60,6 +60,7 @@ installation. * Introduction:: * How Kerberos Works:: * Configuration Files:: +* Using DNS:: * Administrating Kerberos Database Entries:: * Application Servers:: * Backups of Secure Hosts:: @@ -331,7 +332,7 @@ Following are definitions of some of the Kerberos terminology. @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 @@ -989,7 +990,25 @@ Here's an example of a @code{kdc.conf} file: @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, diff --git a/doc/dnssrv.texinfo b/doc/dnssrv.texinfo new file mode 100644 index 000000000..6d157afb3 --- /dev/null +++ b/doc/dnssrv.texinfo @@ -0,0 +1,81 @@ +@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. + diff --git a/doc/dnstxt.texinfo b/doc/dnstxt.texinfo new file mode 100644 index 000000000..535ac4438 --- /dev/null +++ b/doc/dnstxt.texinfo @@ -0,0 +1,38 @@ +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. + diff --git a/doc/install.texinfo b/doc/install.texinfo index b0114d180..9dfd27958 100644 --- a/doc/install.texinfo +++ b/doc/install.texinfo @@ -229,49 +229,7 @@ BOSTON.@value{SECONDREALM} and HOUSTON.@value{SECONDREALM}. @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 @@ -323,86 +281,7 @@ disasters. @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 -- 2.26.2