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

4 files changed, 142 insertions, 125 deletions

diff --git a/doc/admin.texinfo b/doc/admin.texinfo
index 0bd6c9f747..37bda96692 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 0000000000..6d157afb36
--- /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 0000000000..535ac44381
--- /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 b0114d1800..9dfd27958a 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