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 assign your hostnames to Kerberos realms.
  16 * Which ports your KDC and and kadmind services will use, if they will
  17   not be using the default ports.
  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 works through a set of rules in the
  50 :ref:`domain_realm` section of :ref:`krb5.conf(5)`.  You can specify
  51 mappings for an entire domain or on a per-hostname basis.  Typically
  52 you would do this by specifying the mappings for a given domain or
  53 subdomain and listing the exceptions.
  54
  55 The second mechanism is to use KDC host-based service referrals.  With
  56 this method, the KDC's krb5.conf has a full [domain_realm] mapping for
  57 hosts, but the clients do not, or have mappings for only a subset of
  58 the hosts they might contact.  When a client needs to contact a server
  59 host for which it has no mapping, it will ask the client realm's KDC
  60 for the service ticket, and will receive a referral to the appropriate
  61 service realm.
  62
  63 To use referrals, clients must be running MIT krb5 1.6 or later, and
  64 the KDC must be running MIT krb5 1.7 or later.  The
  65 **host_based_services** and **no_host_referral** variables in the
  66 :ref:`kdc_realms` section of :ref:`kdc.conf(5)` can be used to
  67 fine-tune referral behavior on the KDC.
  68
  69
  70 Ports for the KDC and admin services
  71 ------------------------------------
  72
  73 The default ports used by Kerberos are port 88 for the KDC1 and port
  74 749 for the admin server.  You can, however, choose to run on other
  75 ports, as long as they are specified in each host's
  76 :ref:`krb5.conf(5)` files or in DNS SRV records, and the
  77 :ref:`kdc.conf(5)` file on each KDC.  For a more thorough treatment of
  78 port numbers used by the Kerberos V5 programs, refer to the
  79 :ref:`conf_firewall`.
  80
  81
  82 Slave KDCs
  83 ----------
  84
  85 Slave KDCs provide an additional source of Kerberos ticket-granting
  86 services in the event of inaccessibility of the master KDC.  The
  87 number of slave KDCs you need and the decision of where to place them,
  88 both physically and logically, depends on the specifics of your
  89 network.
  90
  91 Kerberos authentication requires that each client be able to contact a
  92 KDC.  Therefore, you need to anticipate any likely reason a KDC might
  93 be unavailable and have a slave KDC to take up the slack.
  94
  95 Some considerations include:
  96
  97 * Have at least one slave KDC as a backup, for when the master KDC is
  98   down, is being upgraded, or is otherwise unavailable.
  99 * If your network is split such that a network outage is likely to
 100   cause a network partition (some segment or segments of the network
 101   to become cut off or isolated from other segments), have a slave KDC
 102   accessible to each segment.
 103 * If possible, have at least one slave KDC in a different building
 104   from the master, in case of power outages, fires, or other localized
 105   disasters.
 106
 107
 108 .. _kdc_hostnames:
 109
 110 Hostnames for KDCs
 111 ------------------
 112
 113 MIT recommends that your KDCs have a predefined set of CNAME records
 114 (DNS hostname aliases), such as ``kerberos`` for the master KDC and
 115 ``kerberos-1``, ``kerberos-2``, ... for the slave KDCs.  This way, if
 116 you need to swap a machine, you only need to change a DNS entry,
 117 rather than having to change hostnames.
 118
 119 As of MIT krb5 1.4, clients can locate a realm's KDCs through DNS
 120 using SRV records (:rfc:`2782`), assuming the Kerberos realm name is
 121 also a DNS domain name.  These records indicate the hostname and port
 122 number to contact for that service, optionally with weighting and
 123 prioritization.  The domain name used in the SRV record name is the
 124 realm name.  Several different Kerberos-related service names are
 125 used:
 126
 127 _kerberos._udp
 128     This is for contacting any KDC by UDP.  This entry will be used
 129     the most often.  Normally you should list port 88 on each of your
 130     KDCs.
 131 _kerberos._tcp
 132     This is for contacting any KDC by TCP.  The MIT KDC by default
 133     will not listen on any TCP ports, so unless you've changed the
 134     configuration or you're running another KDC implementation, you
 135     should leave this unspecified.  If you do enable TCP support,
 136     normally you should use port 88.
 137 _kerberos-master._udp
 138     This entry should refer to those KDCs, if any, that will
 139     immediately see password changes to the Kerberos database.  If a
 140     user is logging in and the password appears to be incorrect, the
 141     client will retry with the master KDC before failing with an
 142     "incorrect password" error given.
 143
 144     If you have only one KDC, or for whatever reason there is no
 145     accessible KDC that would get database changes faster than the
 146     others, you do not need to define this entry.
 147 _kerberos-adm._tcp
 148     This should list port 749 on your master KDC.  Support for it is
 149     not complete at this time, but it will eventually be used by the
 150     :ref:`kadmin(1)` program and related utilities.  For now, you will
 151     also need the **admin_server** variable in :ref:`krb5.conf(5)`.
 152 _kpasswd._udp
 153     This should list port 464 on your master KDC.  It is used when a
 154     user changes her password.  If this entry is not defined but a
 155     _kerberos-adm._tcp entry is defined, the client will use the
 156     _kerberos-adm._tcp entry with the port number changed to 749.
 157
 158 The DNS SRV specification requires that the hostnames listed be the
 159 canonical names, not aliases.  So, for example, you might include the
 160 following records in your (BIND-style) zone file::
 161
 162     $ORIGIN foobar.com.
 163     _kerberos               TXT       "FOOBAR.COM"
 164     kerberos                CNAME     daisy
 165     kerberos-1              CNAME     use-the-force-luke
 166     kerberos-2              CNAME     bunny-rabbit
 167     _kerberos._udp          SRV       0 0 88 daisy
 168                             SRV       0 0 88 use-the-force-luke
 169                             SRV       0 0 88 bunny-rabbit
 170     _kerberos-master._udp   SRV       0 0 88 daisy
 171     _kerberos-adm._tcp      SRV       0 0 749 daisy
 172     _kpasswd._udp           SRV       0 0 464 daisy
 173
 174 Clients can also locate services using the **kdc**, **master_kdc**,
 175 **admin_server**, and **kpasswd_server** variables in the
 176 :ref:`realms` section of :ref:`krb5.conf(5)`.  However, providing SRV
 177 records may still be useful for use by other sites or by unconfigured
 178 client hosts.
 179
 180
 181 .. _db_prop:
 182
 183 Database propagation
 184 --------------------
 185
 186 The Kerberos database resides on the master KDC, and must be
 187 propagated regularly (usually by a cron job) to the slave KDCs.  In
 188 deciding how frequently the propagation should happen, you will need
 189 to balance the amount of time the propagation takes against the
 190 maximum reasonable amount of time a user should have to wait for a
 191 password change to take effect.
 192
 193 If the propagation time is longer than this maximum reasonable time
 194 (e.g., you have a particularly large database, you have a lot of
 195 slaves, or you experience frequent network delays), you may wish to
 196 cut down on your propagation delay by performing the propagation in
 197 parallel.  To do this, have the master KDC propagate the database to
 198 one set of slaves, and then have each of these slaves propagate the
 199 database to additional slaves.
 200
 201 See also :ref:`incr_db_prop`