doc/rst_source/krb_admins/realm_config.rst

   1 Realm configuration decisions
   2 =============================
   3
   4 .. note:: This document was copied from **Kerberos V5 Installation
   5           Guide** with minor changes. Currently it is under review.
   6           Please, send your feedback, corrections and additions to
   7           krb5-bugs@mit.edu.  Your contribution is greatly
   8           appreciated.
   9
  10 Before installing Kerberos V5, it is necessary to consider the
  11 following issues:
  12
  13 * The name of your Kerberos realm (or the name of each realm, if you
  14   need more than one).
  15 * How you will map your hostnames onto Kerberos realms.
  16 * Which ports your KDC and and kadmin (database access) services will
  17   use.
  18 * How many slave KDCs you need and where they should be located.
  19 * The hostnames of your master and slave KDCs.
  20 * How frequently you will propagate the database from the master KDC
  21   to the slave KDCs.
  22
  23
  24 Realm name
  25 ----------
  26
  27 Although your Kerberos realm can be any ASCII string, convention is to
  28 make it the same as your domain name, in upper-case letters.
  29
  30 For example, hosts in the domain ``example.com`` would be in the
  31 Kerberos realm::
  32
  33     EXAMPLE.COM
  34
  35 If you need multiple Kerberos realms, MIT recommends that you use
  36 descriptive names which end with your domain name, such as::
  37
  38     BOSTON.EXAMPLE.COM
  39     HOUSTON.EXAMPLE.COM
  40
  41
  42 .. _mapping_hostnames:
  43
  44 Mapping hostnames onto Kerberos realms
  45 --------------------------------------
  46
  47 Mapping hostnames onto Kerberos realms is done in one of two ways.
  48
  49 The first mechanism, which has been in use for years in MIT-based
  50 Kerberos distributions, works through a set of rules in the
  51 :ref:`krb5.conf(5)` configuration file.  You can specify mappings for
  52 an entire domain or subdomain, and/or on a hostname-by-hostname basis.
  53 Since greater specificity takes precedence, you would do this by
  54 specifying the mappings for a given domain or subdomain and listing
  55 the exceptions.
  56
  57 The second mechanism works by looking up the information in special
  58 TXT records in the Domain Name Service.  This is currently not used by
  59 default because security holes could result if the DNS TXT records
  60 were spoofed.  If this mechanism is enabled on the client, it will try
  61 to look up a TXT record for the DNS name formed by putting the prefix
  62 ``_kerberos`` in front of the hostname in question. If that record is
  63 not found, it will try using ``_kerberos`` and the host's domain name,
  64 then its parent domain, and so forth.  So for the hostname
  65 ``BOSTON.ENGINEERING.FOOBAR.COM``, the names looked up would be::
  66
  67     _kerberos.boston.engineering.foobar.com
  68     _kerberos.engineering.foobar.com
  69     _kerberos.foobar.com
  70     _kerberos.com
  71
  72 The value of the first TXT record found is taken as the realm name.
  73 (Obviously, this doesn't work all that well if a host and a subdomain
  74 have the same name, and different realms.  For example, if all the
  75 hosts in the ``ENGINEERING.FOOBAR.COM`` domain are in the
  76 ``ENGINEERING.FOOBAR.COM`` realm, but a host named
  77 ``ENGINEERING.FOOBAR.COM`` is for some reason in another realm.  In
  78 that case, you would set up TXT records for all hosts, rather than
  79 relying on the fallback to the domain name.)
  80
  81 Even if you do not choose to use this mechanism within your site, you
  82 may wish to set it up anyway, for use when interacting with other
  83 sites.
  84
  85
  86 Ports for the KDC and admin services
  87 ------------------------------------
  88
  89 The default ports used by Kerberos are port 88 for the KDC1 and port
  90 749 for the admin server.  You can, however, choose to run on other
  91 ports, as long as they are specified in each host's ``/etc/services``
  92 and :ref:`krb5.conf(5)` files, and the :ref:`kdc.conf(5)` file on each
  93 KDC.  For a more thorough treatment of port numbers used by the
  94 Kerberos V5 programs, refer to the :ref:`conf_firewall`.
  95
  96
  97 Slave KDCs
  98 ----------
  99
 100 Slave KDCs provide an additional source of Kerberos ticket-granting
 101 services in the event of inaccessibility of the master KDC.  The
 102 number of slave KDCs you need and the decision of where to place them,
 103 both physically and logically, depends on the specifics of your
 104 network.
 105
 106 All of the Kerberos authentication on your network requires that each
 107 client be able to contact a KDC.  Therefore, you need to anticipate
 108 any likely reason a KDC might be unavailable and have a slave KDC to
 109 take up the slack.
 110
 111 Some considerations include:
 112
 113 * Have at least one slave KDC as a backup, for when the master KDC is
 114   down, is being upgraded, or is otherwise unavailable.
 115 * If your network is split such that a network outage is likely to
 116   cause a network partition (some segment or segments of the network
 117   to become cut off or isolated from other segments), have a slave KDC
 118   accessible to each segment.
 119 * If possible, have at least one slave KDC in a different building
 120   from the master, in case of power outages, fires, or other localized
 121   disasters.
 122
 123
 124 .. _kdc_hostnames:
 125
 126 Hostnames for KDCs
 127 ------------------
 128
 129 MIT recommends that your KDCs have a predefined set of CNAME records
 130 (DNS hostname aliases), such as ``kerberos`` for the master KDC and
 131 ``kerberos-1``, ``kerberos-2``, ... for the slave KDCs.  This way, if
 132 you need to swap a machine, you only need to change a DNS entry,
 133 rather than having to change hostnames.
 134
 135 A new mechanism for locating KDCs of a realm through DNS has been
 136 added to the MIT Kerberos V5 distribution.  A relatively new record
 137 type called SRV has been added to DNS.  Looked up by a service name
 138 and a domain name, these records indicate the hostname and port number
 139 to contact for that service, optionally with weighting and
 140 prioritization.  (See :rfc:`2782` if you want more information. You
 141 can follow the example below for straightforward cases.)
 142
 143 The use with Kerberos is fairly straightforward.  The domain name used
 144 in the SRV record name is the domain-style Kerberos realm name.  (It
 145 is possible to have Kerberos realm names that are not DNS-style names,
 146 but we don't recommend it for Internet use, and our code does not
 147 support it well.)  Several different Kerberos-related service names
 148 are used:
 149
 150 _kerberos._udp
 151     This is for contacting any KDC by UDP.  This entry will be used
 152     the most often.  Normally you should list port 88 on each of your
 153     KDCs.
 154 _kerberos._tcp
 155     This is for contacting any KDC by TCP.  The MIT KDC by default
 156     will not listen on any TCP ports, so unless you've changed the
 157     configuration or you're running another KDC implementation, you
 158     should leave this unspecified.  If you do enable TCP support,
 159     normally you should use port 88.
 160 _kerberos-master._udp
 161     This entry should refer to those KDCs, if any, that will
 162     immediately see password changes to the Kerberos database.  This
 163     entry is used only in one case, when the user is logging in and
 164     the password appears to be incorrect; the master KDC is then
 165     contacted, and the same password used to try to decrypt the
 166     response, in case the user's password had recently been changed
 167     and the first KDC contacted hadn't been updated.  Only if that
 168     fails is an "incorrect password" error given.
 169
 170     If you have only one KDC, or for whatever reason there is no
 171     accessible KDC that would get database changes faster than the
 172     others, you do not need to define this entry.
 173 _kerberos-adm._tcp
 174     This should list port 749 on your master KDC.  Support for it is
 175     not complete at this time, but it will eventually be used by the
 176     :ref:`kadmin(1)` program and related utilities.  For now, you will
 177     also need the admin_server entry in :ref:`krb5.conf(5)`.
 178 _kpasswd._udp
 179     This should list port 464 on your master KDC.  It is used when a
 180     user changes her password.
 181
 182 Be aware, however, that the DNS SRV specification requires that the
 183 hostnames listed be the canonical names, not aliases.  So, for
 184 example, you might include the following records in your (BIND-style)
 185 zone file::
 186
 187     $ORIGIN foobar.com.
 188     _kerberos               TXT       "FOOBAR.COM"
 189     kerberos                CNAME     daisy
 190     kerberos-1              CNAME     use-the-force-luke
 191     kerberos-2              CNAME     bunny-rabbit
 192     _kerberos._udp          SRV       0 0 88 daisy
 193                             SRV       0 0 88 use-the-force-luke
 194                             SRV       0 0 88 bunny-rabbit
 195     _kerberos-master._udp   SRV       0 0 88 daisy
 196     _kerberos-adm._tcp      SRV       0 0 749 daisy
 197     _kpasswd._udp           SRV       0 0 464 daisy
 198
 199 As with the DNS-based mechanism for determining the Kerberos realm of
 200 a host, we recommend distributing the information this way for use by
 201 other sites that may want to interact with yours using Kerberos, even
 202 if you don't immediately make use of it within your own site.  If you
 203 anticipate installing a very large number of machines on which it will
 204 be hard to update the Kerberos configuration files, you may wish to do
 205 all of your Kerberos service lookups via DNS and not put the
 206 information (except for **admin_server** as noted above) in future
 207 versions of your :ref:`krb5.conf(5)` files at all.  Eventually, we
 208 hope to phase out the listing of server hostnames in the client-side
 209 configuration files; making preparations now will make the transition
 210 easier in the future.
 211
 212
 213 .. _db_prop:
 214
 215 Database propagation
 216 --------------------
 217
 218 The Kerberos database resides on the master KDC, and must be
 219 propagated regularly (usually by a cron job) to the slave KDCs.  In
 220 deciding how frequently the propagation should happen, you will need
 221 to balance the amount of time the propagation takes against the
 222 maximum reasonable amount of time a user should have to wait for a
 223 password change to take effect.
 224
 225 If the propagation time is longer than this maximum reasonable time
 226 (e.g., you have a particularly large database, you have a lot of
 227 slaves, or you experience frequent network delays), you may wish to
 228 cut down on your propagation delay by performing the propagation in
 229 parallel.  To do this, have the master KDC propagate the database to
 230 one set of slaves, and then have each of these slaves propagate the
 231 database to additional slaves.
 232
 233 See also :ref:`incr_db_prop`