diff options
Diffstat (limited to 'crypto/krb5/doc/admin/realm_config.rst')
| -rw-r--r-- | crypto/krb5/doc/admin/realm_config.rst | 278 |
1 files changed, 0 insertions, 278 deletions
diff --git a/crypto/krb5/doc/admin/realm_config.rst b/crypto/krb5/doc/admin/realm_config.rst deleted file mode 100644 index 32c5b9cf11ee..000000000000 --- a/crypto/krb5/doc/admin/realm_config.rst +++ /dev/null @@ -1,278 +0,0 @@ -Realm configuration decisions -============================= - -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 assign your hostnames to Kerberos realms. -* Which ports your KDC and and kadmind services will use, if they will - not be using the default ports. -* How many replica KDCs you need and where they should be located. -* The hostnames of your primary and replica KDCs. -* How frequently you will propagate the database from the primary KDC - to the replica 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 three ways. - -The first mechanism works through a set of rules in the -:ref:`domain_realm` section of :ref:`krb5.conf(5)`. You can specify -mappings for an entire domain or on a per-hostname basis. Typically -you would do this by specifying the mappings for a given domain or -subdomain and listing the exceptions. - -The second mechanism is to use KDC host-based service referrals. With -this method, the KDC's krb5.conf has a full [domain_realm] mapping for -hosts, but the clients do not, or have mappings for only a subset of -the hosts they might contact. When a client needs to contact a server -host for which it has no mapping, it will ask the client realm's KDC -for the service ticket, and will receive a referral to the appropriate -service realm. - -To use referrals, clients must be running MIT krb5 1.6 or later, and -the KDC must be running MIT krb5 1.7 or later. The -**host_based_services** and **no_host_referral** variables in the -:ref:`kdc_realms` section of :ref:`kdc.conf(5)` can be used to -fine-tune referral behavior on the KDC. - -It is also possible for clients to use DNS TXT records, if -**dns_lookup_realm** is enabled in :ref:`krb5.conf(5)`. Such lookups -are disabled by default because DNS is an insecure protocol and security -holes could result if DNS records are spoofed. If enabled, the client -will try to look up a TXT record formed by prepending the prefix -``_kerberos`` to the hostname in question. If that record is not -found, the client will attempt a lookup by prepending ``_kerberos`` to the -host's domain name, then its parent domain, up to the top-level domain. -For the hostname ``boston.engineering.example.com``, the names looked up -would be:: - - _kerberos.boston.engineering.example.com - _kerberos.engineering.example.com - _kerberos.example.com - _kerberos.com - -The value of the first TXT record found is taken as the realm 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 KDC 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 -:ref:`krb5.conf(5)` files or in DNS SRV records, 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`. - - -Replica KDCs ------------- - -Replica KDCs provide an additional source of Kerberos ticket-granting -services in the event of inaccessibility of the primary KDC. The -number of replica KDCs you need and the decision of where to place them, -both physically and logically, depends on the specifics of your -network. - -Kerberos authentication 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 replica KDC to take up the slack. - -Some considerations include: - -* Have at least one replica KDC as a backup, for when the primary 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 replica - KDC accessible to each segment. -* If possible, have at least one replica KDC in a different building - from the primary, 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 primary KDC and -``kerberos-1``, ``kerberos-2``, ... for the replica KDCs. This way, -if you need to swap a machine, you only need to change a DNS entry, -rather than having to change hostnames. - -As of MIT krb5 1.4, clients can locate a realm's KDCs through DNS -using SRV records (:rfc:`2782`), assuming the Kerberos realm name is -also a DNS domain name. These records indicate the hostname and port -number to contact for that service, optionally with weighting and -prioritization. The domain name used in the SRV record name is the -realm name. 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. Normally you should use - port 88. This entry should be omitted if the KDC does not listen - on TCP ports, as was the default prior to release 1.13. -_kerberos-master._udp - This entry should refer to those KDCs, if any, that will - immediately see password changes to the Kerberos database. If a - user is logging in and the password appears to be incorrect, the - client will retry with the primary KDC before failing with 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 primary 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** variable in :ref:`krb5.conf(5)`. -_kerberos-master._tcp - The corresponding TCP port for _kerberos-master._udp, assuming the - primary KDC listens on a TCP port. -_kpasswd._udp - This entry should list port 464 on your primary KDC. It is used - when a user changes her password. If this entry is not defined - but a _kerberos-adm._tcp entry is defined, the client will use the - _kerberos-adm._tcp entry with the port number changed to 464. -_kpasswd._tcp - The corresponding TCP port for _kpasswd._udp. - -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 - -Clients can also be configured with the explicit location of services -using the **kdc**, **master_kdc**, **admin_server**, and -**kpasswd_server** variables in the :ref:`realms` section of -:ref:`krb5.conf(5)`. Even if some clients will be configured with -explicit server locations, providing SRV records will still benefit -unconfigured clients, and be useful for other sites. - -Clients can be configured with the **sitename** realm variable (new in -release 1.22). If a site name is set, the client first attempts SRV -record lookups with ".*sitename*._sites" inserted after the service -and protocol name and before the Kerberos realm. Site-specific -records may indicate servers more proximal to the client, allowing for -faster access. - - -.. _kdc_discovery: - -KDC Discovery -------------- - -As of MIT krb5 1.15, clients can also locate KDCs in DNS through URI -records (:rfc:`7553`). Limitations with the SRV record format may -result in extra DNS queries in situations where a client must failover -to other transport types, or find a primary server. The URI record -can convey more information about a realm's KDCs with a single query. - -The client performs a query for the following URI records: - -* ``_kerberos.REALM`` for finding KDCs. -* ``_kerberos-adm.REALM`` for finding kadmin services. -* ``_kpasswd.REALM`` for finding password services. - -The URI record includes a priority, weight, and a URI string that -consists of case-insensitive colon separated fields, in the form -``scheme:[flags]:transport:residual``. - -* *scheme* defines the registered URI type. It should always be - ``krb5srv``. -* *flags* contains zero or more flag characters. Currently the only - valid flag is ``m``, which indicates that the record is for a - primary server. -* *transport* defines the transport type of the residual URL or - address. Accepted values are ``tcp``, ``udp``, or ``kkdcp`` for the - MS-KKDCP type. -* *residual* contains the hostname, IP address, or URL to be - contacted using the specified transport, with an optional port - extension. The MS-KKDCP transport type uses a HTTPS URL, and can - include a port and/or path extension. - -An example of URI records in a zone file:: - - _kerberos.EXAMPLE.COM URI 10 1 krb5srv:m:tcp:kdc1.example.com - URI 20 1 krb5srv:m:udp:kdc2.example.com:89 - URI 40 1 krb5srv::udp:10.10.0.23 - URI 30 1 krb5srv::kkdcp:https://proxy:89/auth - -URI lookups are enabled by default, and can be disabled by setting -**dns_uri_lookup** in the :ref:`libdefaults` section of -:ref:`krb5.conf(5)` to False. When enabled, URI lookups take -precedence over SRV lookups, falling back to SRV lookups if no URI -records are found. - -The **sitename** variable in the :ref:`realms` section of -:ref:`krb5.conf(5)` applies to URI lookups as well as SRV lookups. - - -.. _db_prop: - -Database propagation --------------------- - -The Kerberos database resides on the primary KDC, and must be -propagated regularly (usually by a cron job) to the replica 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 -replicas, 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 primary KDC propagate the database to -one set of replicas, and then have each of these replicas propagate -the database to additional replicas. - -See also :ref:`incr_db_prop` |