From 8a42038eaf80bd1da88d909a5196157ae41973b9 Mon Sep 17 00:00:00 2001 From: Greg Hudson Date: Sat, 3 Mar 2012 06:17:51 +0000 Subject: [PATCH] Consolidate realm config docs into one file Move the contents of the realm_config directory into one file realm_config.rst. git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@25728 dc483132-0cff-0310-8789-dd5450dbe970 --- doc/rst_source/krb_admins/index.rst | 2 +- doc/rst_source/krb_admins/realm_config.rst | 240 ++++++++++++++++++ .../krb_admins/realm_config/db_prop.rst | 28 -- .../krb_admins/realm_config/index.rst | 42 --- .../krb_admins/realm_config/kdc_hn.rst | 100 -------- .../krb_admins/realm_config/kdc_ports.rst | 16 -- .../krb_admins/realm_config/mapping_hn.rst | 55 ---- .../krb_admins/realm_config/realm_name.rst | 23 -- .../krb_admins/realm_config/slave_kdc.rst | 32 --- 9 files changed, 241 insertions(+), 297 deletions(-) create mode 100644 doc/rst_source/krb_admins/realm_config.rst delete mode 100644 doc/rst_source/krb_admins/realm_config/db_prop.rst delete mode 100644 doc/rst_source/krb_admins/realm_config/index.rst delete mode 100644 doc/rst_source/krb_admins/realm_config/kdc_hn.rst delete mode 100644 doc/rst_source/krb_admins/realm_config/kdc_ports.rst delete mode 100644 doc/rst_source/krb_admins/realm_config/mapping_hn.rst delete mode 100644 doc/rst_source/krb_admins/realm_config/realm_name.rst delete mode 100644 doc/rst_source/krb_admins/realm_config/slave_kdc.rst diff --git a/doc/rst_source/krb_admins/index.rst b/doc/rst_source/krb_admins/index.rst index 5f06cf97b..a71731a6e 100644 --- a/doc/rst_source/krb_admins/index.rst +++ b/doc/rst_source/krb_admins/index.rst @@ -9,7 +9,7 @@ Contents: install.rst conf_files/index.rst - realm_config/index.rst + realm_config.rst dns.rst database/index.rst conf_ldap.rst diff --git a/doc/rst_source/krb_admins/realm_config.rst b/doc/rst_source/krb_admins/realm_config.rst new file mode 100644 index 000000000..11987f7be --- /dev/null +++ b/doc/rst_source/krb_admins/realm_config.rst @@ -0,0 +1,240 @@ +Realm configuration decisions +============================= + +.. note:: This document was copied from **Kerberos V5 Installation + Guide** with minor changes. Currently it is under review. + Please, send your feedback, corrections and additions to + krb5-bugs@mit.edu. Your contribution is greatly + appreciated. + +Before installing Kerberos V5, it is necessary to consider the +following issues: + +* The name of your Kerberos realm (or the name of each realm, if you + need more than one). +* How you will map your hostnames onto Kerberos realms. +* Which ports your KDC and and kadmin (database access) services will + use. +* How many slave KDCs you need and where they should be located. +* The hostnames of your master and slave KDCs. +* How frequently you will propagate the database from the master KDC + to the slave KDCs. + + +Realm name +---------- + +Although your Kerberos realm can be any ASCII string, convention is to +make it the same as your domain name, in upper-case letters. + +For example, hosts in the domain ``example.com`` would be in the +Kerberos realm:: + + EXAMPLE.COM + +If you need multiple Kerberos realms, MIT recommends that you use +descriptive names which end with your domain name, such as:: + + BOSTON.EXAMPLE.COM + HOUSTON.EXAMPLE.COM + + +.. _mapping_hostnames: + +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 +:ref:`krb5.conf(5)` configuration file. 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 works by looking up the information in special +TXT records in the Domain Name Service. This is currently not used by +default because security holes could result if the DNS TXT records +were spoofed. If this mechanism is enabled on the client, it will try +to look up a TXT record for the DNS name formed by putting the prefix +``_kerberos`` in front of the hostname in question. If that record is +not found, it will try using ``_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:: + + _kerberos.boston.engineering.foobar.com + _kerberos.engineering.foobar.com + _kerberos.foobar.com + _kerberos.com + +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. + + +Ports for the KDC and admin services +------------------------------------ + +The default ports used by Kerberos are port 88 for the KDC1 and port +749 for the admin server. You can, however, choose to run on other +ports, as long as they are specified in each host's ``/etc/services`` +and :ref:`krb5.conf(5)` files, and the :ref:`kdc.conf(5)` file on each +KDC. For a more thorough treatment of port numbers used by the +Kerberos V5 programs, refer to the :ref:`conf_firewall`. + + +Slave KDCs +---------- + +Slave KDCs provide an additional source of Kerberos ticket-granting +services in the event of inaccessibility of the master KDC. The +number of slave KDCs you need and the decision of where to place them, +both physically and logically, depends on the specifics of your +network. + +All of the Kerberos authentication on your network requires that each +client be able to contact a KDC. Therefore, you need to anticipate +any likely reason a KDC might be unavailable and have a slave KDC to +take up the slack. + +Some considerations include: + +* Have at least one slave KDC as a backup, for when the master KDC is + down, is being upgraded, or is otherwise unavailable. +* If your network is split such that a network outage is likely to + cause a network partition (some segment or segments of the network + to become cut off or isolated from other segments), have a slave KDC + accessible to each segment. +* If possible, have at least one slave KDC in a different building + from the master, in case of power outages, fires, or other localized + disasters. + + +.. _kdc_hostnames: + +Hostnames for KDCs +------------------ + +MIT recommends that your KDCs have a predefined set of CNAME records +(DNS hostname aliases), such as ``kerberos`` for the master KDC and +``kerberos-1``, ``kerberos-2``, ... 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 MIT Kerberos V5 distribution. A relatively new record +type called 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: + +_kerberos._udp + This is for contacting any KDC by UDP. This entry will be used + the most often. Normally you should list port 88 on each of your + KDCs. +_kerberos._tcp + This is for contacting any KDC by TCP. The MIT KDC by default + will not listen on any TCP ports, so unless you've changed the + configuration or you're running another KDC implementation, you + should leave this unspecified. If you do enable TCP support, + normally you should use port 88. +_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. +_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 + :ref:`kadmin(1)` program and related utilities. For now, you will + also need the admin_server entry in :ref:`krb5.conf(5)`. +_kpasswd._udp + This should list port 464 on your master KDC. It is used when a + user changes her password. + +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:: + + $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 + +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 **admin_server** as noted above) in future +versions of your :ref:`krb5.conf(5)` 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. + + +.. _db_prop: + +Database propagation +-------------------- + +The Kerberos database resides on the master KDC, and must be +propagated regularly (usually by a cron job) to the slave KDCs. In +deciding how frequently the propagation should happen, you will need +to balance the amount of time the propagation takes against the +maximum reasonable amount of time a user should have to wait for a +password change to take effect. + +If the propagation time is longer than this maximum reasonable time +(e.g., you have a particularly large database, you have a lot of +slaves, or you experience frequent network delays), you may wish to +cut down on your propagation delay by performing the propagation in +parallel. To do this, have the master KDC propagate the database to +one set of slaves, and then have each of these slaves propagate the +database to additional slaves. + +See also :ref:`incr_db_prop` + + +Feedback +-------- + +Please, provide your feedback or suggest a new topic at +krb5-bugs@mit.edu?subject=Documentation___realm_config diff --git a/doc/rst_source/krb_admins/realm_config/db_prop.rst b/doc/rst_source/krb_admins/realm_config/db_prop.rst deleted file mode 100644 index c8e46d309..000000000 --- a/doc/rst_source/krb_admins/realm_config/db_prop.rst +++ /dev/null @@ -1,28 +0,0 @@ -.. _db_prop: - -Database propagation -==================== - -The Kerberos database resides on the master KDC, and must be -propagated regularly (usually by a cron job) to the slave KDCs. In -deciding how frequently the propagation should happen, you will need -to balance the amount of time the propagation takes against the -maximum reasonable amount of time a user should have to wait for a -password change to take effect. - -If the propagation time is longer than this maximum reasonable time -(e.g., you have a particularly large database, you have a lot of -slaves, or you experience frequent network delays), you may wish to -cut down on your propagation delay by performing the propagation in -parallel. To do this, have the master KDC propagate the database to -one set of slaves, and then have each of these slaves propagate the -database to additional slaves. - -See also :ref:`incr_db_prop` - - -Feedback --------- - -Please, provide your feedback or suggest a new topic at -krb5-bugs@mit.edu?subject=Documentation___realm_config diff --git a/doc/rst_source/krb_admins/realm_config/index.rst b/doc/rst_source/krb_admins/realm_config/index.rst deleted file mode 100644 index 5f1826a61..000000000 --- a/doc/rst_source/krb_admins/realm_config/index.rst +++ /dev/null @@ -1,42 +0,0 @@ -Realm configuration decisions -============================= - -.. note:: This document was copied from **Kerberos V5 Installation - Guide** with minor changes. Currently it is under review. - Please, send your feedback, corrections and additions to - krb5-bugs@mit.edu. Your contribution is greatly - appreciated. - -Before installing Kerberos V5, it is necessary to consider the -following issues: - -* The name of your Kerberos realm (or the name of each realm, if you - need more than one). -* How you will map your hostnames onto Kerberos realms. -* Which ports your KDC and and kadmin (database access) services will - use. -* How many slave KDCs you need and where they should be located. -* The hostnames of your master and slave KDCs. -* How frequently you will propagate the database from the master KDC - to the slave KDCs. - - -Contents --------- - -.. toctree:: - :maxdepth: 2 - - realm_name.rst - mapping_hn.rst - kdc_ports.rst - slave_kdc.rst - kdc_hn.rst - db_prop.rst - - -Feedback --------- - -Please, provide your feedback or suggest a new topic at -krb5-bugs@mit.edu?subject=Documentation___realm_config diff --git a/doc/rst_source/krb_admins/realm_config/kdc_hn.rst b/doc/rst_source/krb_admins/realm_config/kdc_hn.rst deleted file mode 100644 index eb50e5ec8..000000000 --- a/doc/rst_source/krb_admins/realm_config/kdc_hn.rst +++ /dev/null @@ -1,100 +0,0 @@ -.. _kdc_hostnames: - -Hostnames for KDCs -================== - -.. note:: This document was copied from **Kerberos V5 System - Administrator's Guide** with minor changes. Currently it is - under review. Please, send your feedback, corrections and - additions to krb5-bugs@mit.edu. Your contribution is - greatly appreciated. - -MIT recommends that your KDCs have a predefined set of CNAME records -(DNS hostname aliases), such as ``kerberos`` for the master KDC and -``kerberos-1``, ``kerberos-2``, ... 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 MIT Kerberos V5 distribution. A relatively new record -type called 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: - -_kerberos._udp - This is for contacting any KDC by UDP. This entry will be used - the most often. Normally you should list port 88 on each of your - KDCs. -_kerberos._tcp - This is for contacting any KDC by TCP. The MIT KDC by default - will not listen on any TCP ports, so unless you've changed the - configuration or you're running another KDC implementation, you - should leave this unspecified. If you do enable TCP support, - normally you should use port 88. -_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. -_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 - :ref:`kadmin(1)` program and related utilities. For now, you will - also need the admin_server entry in :ref:`krb5.conf(5)`. -_kpasswd._udp - This should list port 464 on your master KDC. It is used when a - user changes her password. - -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:: - - $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 - -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 **admin_server** as noted above) in future -versions of your :ref:`krb5.conf(5)` 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. - - -Feedback --------- - -Please, provide your feedback or suggest a new topic at -krb5-bugs@mit.edu?subject=Documentation___hostnames diff --git a/doc/rst_source/krb_admins/realm_config/kdc_ports.rst b/doc/rst_source/krb_admins/realm_config/kdc_ports.rst deleted file mode 100644 index 4e1aeff99..000000000 --- a/doc/rst_source/krb_admins/realm_config/kdc_ports.rst +++ /dev/null @@ -1,16 +0,0 @@ -Ports for the KDC and admin services -==================================== - -The default ports used by Kerberos are port 88 for the KDC1 and port -749 for the admin server. You can, however, choose to run on other -ports, as long as they are specified in each host's ``/etc/services`` -and :ref:`krb5.conf(5)` files, and the :ref:`kdc.conf(5)` file on each -KDC. For a more thorough treatment of port numbers used by the -Kerberos V5 programs, refer to the :ref:`conf_firewall`. - -Feedback --------- - -Please, provide your feedback or suggest a new topic at -krb5-bugs@mit.edu?subject=Documentation___realm_config - diff --git a/doc/rst_source/krb_admins/realm_config/mapping_hn.rst b/doc/rst_source/krb_admins/realm_config/mapping_hn.rst deleted file mode 100644 index 4ed422eee..000000000 --- a/doc/rst_source/krb_admins/realm_config/mapping_hn.rst +++ /dev/null @@ -1,55 +0,0 @@ -.. _mapping_hostnames: - - -Mapping hostnames onto Kerberos realms -====================================== - -.. note:: This document was copied from **Kerberos V5 System - Administrator's Guide** with minor changes. Currently it is - under review. Please, send your feedback, corrections and - additions to krb5-bugs@mit.edu. Your contribution is - greatly appreciated. - -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 -:ref:`krb5.conf(5)` configuration file. 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 works by looking up the information in special -TXT records in the Domain Name Service. This is currently not used by -default because security holes could result if the DNS TXT records -were spoofed. If this mechanism is enabled on the client, it will try -to look up a TXT record for the DNS name formed by putting the prefix -``_kerberos`` in front of the hostname in question. If that record is -not found, it will try using ``_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:: - - _kerberos.boston.engineering.foobar.com - _kerberos.engineering.foobar.com - _kerberos.foobar.com - _kerberos.com - -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. - -Feedback --------- - -Please, provide your feedback or suggest a new topic at -krb5-bugs@mit.edu?subject=Documentation___hostnames diff --git a/doc/rst_source/krb_admins/realm_config/realm_name.rst b/doc/rst_source/krb_admins/realm_config/realm_name.rst deleted file mode 100644 index 3ca44d9d2..000000000 --- a/doc/rst_source/krb_admins/realm_config/realm_name.rst +++ /dev/null @@ -1,23 +0,0 @@ -Kerberos realms -=============== - -Although your Kerberos realm can be any ASCII string, convention is to -make it the same as your domain name, in upper-case letters. - -For example, hosts in the domain ``example.com`` would be in the -Kerberos realm:: - - EXAMPLE.COM - -If you need multiple Kerberos realms, MIT recommends that you use -descriptive names which end with your domain name, such as:: - - BOSTON.EXAMPLE.COM - HOUSTON.EXAMPLE.COM - - -Feedback --------- - -Please, provide your feedback or suggest a new topic at -krb5-bugs@mit.edu?subject=Documentation___realm_config diff --git a/doc/rst_source/krb_admins/realm_config/slave_kdc.rst b/doc/rst_source/krb_admins/realm_config/slave_kdc.rst deleted file mode 100644 index 6fd019726..000000000 --- a/doc/rst_source/krb_admins/realm_config/slave_kdc.rst +++ /dev/null @@ -1,32 +0,0 @@ -Slave KDCs -========== - -Slave KDCs provide an additional source of Kerberos ticket-granting -services in the event of inaccessibility of the master KDC. The -number of slave KDCs you need and the decision of where to place them, -both physically and logically, depends on the specifics of your -network. - -All of the Kerberos authentication on your network requires that each -client be able to contact a KDC. Therefore, you need to anticipate -any likely reason a KDC might be unavailable and have a slave KDC to -take up the slack. - -Some considerations include: - -* Have at least one slave KDC as a backup, for when the master KDC is - down, is being upgraded, or is otherwise unavailable. -* If your network is split such that a network outage is likely to - cause a network partition (some segment or segments of the network - to become cut off or isolated from other segments), have a slave KDC - accessible to each segment. -* If possible, have at least one slave KDC in a different building - from the master, in case of power outages, fires, or other localized - disasters. - - -Feedback --------- - -Please, provide your feedback or suggest a new topic at -krb5-bugs@mit.edu?subject=Documentation___realm_config -- 2.26.2