diff options
author | Greg Hudson <ghudson@mit.edu> | 2020-06-24 20:48:14 -0400 |
---|---|---|
committer | Greg Hudson <ghudson@mit.edu> | 2020-09-07 12:20:16 -0400 |
commit | 10eb93809b1af06e2b1147aee2e3e50058ba1bbd (patch) | |
tree | 179b7b7ebe3174f3a87c530285a11908680dc6ac /doc | |
parent | bfd407703a938573610af3f17aad4d5ebad615fd (diff) | |
download | krb5-10eb93809b1af06e2b1147aee2e3e50058ba1bbd.zip krb5-10eb93809b1af06e2b1147aee2e3e50058ba1bbd.tar.gz krb5-10eb93809b1af06e2b1147aee2e3e50058ba1bbd.tar.bz2 |
Use the term "primary KDC" in source and docs
Where it does not affect program behavior, use the term "primary KDC".
This commit does not change any profile variables, DNS labels,
pathnames, or externally visible identifiers, nor does it change the
term "master key".
ticket: 8921 (new)
Diffstat (limited to 'doc')
-rw-r--r-- | doc/admin/admin_commands/kadmin_local.rst | 2 | ||||
-rw-r--r-- | doc/admin/admin_commands/kadmind.rst | 10 | ||||
-rw-r--r-- | doc/admin/admin_commands/kprop.rst | 4 | ||||
-rw-r--r-- | doc/admin/admin_commands/kpropd.rst | 16 | ||||
-rw-r--r-- | doc/admin/admin_commands/kproplog.rst | 11 | ||||
-rw-r--r-- | doc/admin/advanced/retiring-des.rst | 4 | ||||
-rw-r--r-- | doc/admin/backup_host.rst | 6 | ||||
-rw-r--r-- | doc/admin/conf_files/kdc_conf.rst | 4 | ||||
-rw-r--r-- | doc/admin/conf_files/krb5_conf.rst | 6 | ||||
-rw-r--r-- | doc/admin/database.rst | 58 | ||||
-rw-r--r-- | doc/admin/install_kdc.rst | 122 | ||||
-rw-r--r-- | doc/admin/lockout.rst | 4 | ||||
-rw-r--r-- | doc/admin/realm_config.rst | 43 | ||||
-rw-r--r-- | doc/admin/troubleshoot.rst | 6 | ||||
-rw-r--r-- | doc/build/directory_org.rst | 2 | ||||
-rw-r--r-- | doc/iprop-notes.txt | 24 | ||||
-rw-r--r-- | doc/mitK5features.rst | 10 |
17 files changed, 167 insertions, 165 deletions
diff --git a/doc/admin/admin_commands/kadmin_local.rst b/doc/admin/admin_commands/kadmin_local.rst index 33cf3a9..c6c7795 100644 --- a/doc/admin/admin_commands/kadmin_local.rst +++ b/doc/admin/admin_commands/kadmin_local.rst @@ -55,7 +55,7 @@ it requests a service ticket from the KDC, and uses that service ticket to authenticate to kadmind. Since kadmin.local directly accesses the KDC database, it usually must -be run directly on the master KDC with sufficient permissions to read +be run directly on the primary KDC with sufficient permissions to read the KDC database. If the KDC database uses the LDAP database module, kadmin.local can be run on any host which can access the LDAP server. diff --git a/doc/admin/admin_commands/kadmind.rst b/doc/admin/admin_commands/kadmind.rst index 03a0d6d..7e14826 100644 --- a/doc/admin/admin_commands/kadmind.rst +++ b/doc/admin/admin_commands/kadmind.rst @@ -23,9 +23,9 @@ DESCRIPTION ----------- kadmind starts the Kerberos administration server. kadmind typically -runs on the master Kerberos server, which stores the KDC database. If -the KDC database uses the LDAP module, the administration server and -the KDC server need not run on the same machine. kadmind accepts +runs on the primary Kerberos server, which stores the KDC database. +If the KDC database uses the LDAP module, the administration server +and the KDC server need not run on the same machine. kadmind accepts remote requests from programs such as :ref:`kadmin(1)` and :ref:`kpasswd(1)` to administer the information in these database. @@ -53,8 +53,8 @@ Incremental propagation allows replica KDC servers to receive principal and policy updates incrementally instead of receiving full dumps of the database. This facility can be enabled in the :ref:`kdc.conf(5)` file with the **iprop_enable** option. Incremental -propagation requires the principal ``kiprop/MASTER\@REALM`` (where -MASTER is the master KDC's canonical host name, and REALM the realm +propagation requires the principal ``kiprop/PRIMARY\@REALM`` (where +PRIMARY is the primary KDC's canonical host name, and REALM the realm name). In release 1.13, this principal is automatically created and registered into the datebase. diff --git a/doc/admin/admin_commands/kprop.rst b/doc/admin/admin_commands/kprop.rst index c2b6c79..a118b26 100644 --- a/doc/admin/admin_commands/kprop.rst +++ b/doc/admin/admin_commands/kprop.rst @@ -19,7 +19,7 @@ DESCRIPTION ----------- kprop is used to securely propagate a Kerberos V5 database dump file -from the master Kerberos server to a replica Kerberos server, which is +from the primary Kerberos server to a replica Kerberos server, which is specified by *replica_host*. The dump file must be created by :ref:`kdb5_util(8)`. @@ -28,7 +28,7 @@ OPTIONS ------- **-r** *realm* - Specifies the realm of the master server. + Specifies the realm of the primary server. **-f** *file* Specifies the filename where the dumped principal database file is diff --git a/doc/admin/admin_commands/kpropd.rst b/doc/admin/admin_commands/kpropd.rst index 7f7faa2..797090c 100644 --- a/doc/admin/admin_commands/kpropd.rst +++ b/doc/admin/admin_commands/kpropd.rst @@ -24,12 +24,12 @@ DESCRIPTION The *kpropd* command runs on the replica KDC server. It listens for update requests made by the :ref:`kprop(8)` program. If incremental propagation is enabled, it periodically requests incremental updates -from the master KDC. +from the primary KDC. -When the replica receives a kprop request from the master, kpropd +When the replica receives a kprop request from the primary, kpropd accepts the dumped KDC database and places it in a file, and then runs :ref:`kdb5_util(8)` to load the dumped database into the active -database which is used by :ref:`krb5kdc(8)`. This allows the master +database which is used by :ref:`krb5kdc(8)`. This allows the primary Kerberos server to use :ref:`kprop(8)` to propagate its database to the replica servers. Upon a successful download of the KDC database file, the replica Kerberos server will have an up-to-date KDC @@ -52,10 +52,10 @@ compatibility but does nothing. Incremental propagation may be enabled with the **iprop_enable** variable in :ref:`kdc.conf(5)`. If incremental propagation is -enabled, the replica periodically polls the master KDC for updates, at +enabled, the replica periodically polls the primary KDC for updates, at an interval determined by the **iprop_replica_poll** variable. If the replica receives updates, kpropd updates its log file with any updates -from the master. :ref:`kproplog(8)` can be used to view a summary of +from the primary. :ref:`kproplog(8)` can be used to view a summary of the update entry log on the replica KDC. If incremental propagation is enabled, the principal ``kiprop/replicahostname@REALM`` (where *replicahostname* is the name of the replica KDC host, and *REALM* is @@ -70,11 +70,11 @@ OPTIONS -------- **-r** *realm* - Specifies the realm of the master server. + Specifies the realm of the primary server. **-A** *admin_server* Specifies the server to be contacted for incremental updates; by - default, the master admin server is contacted. + default, the primary admin server is contacted. **-f** *file* Specifies the filename where the dumped principal database file is @@ -95,7 +95,7 @@ OPTIONS **-t** In standalone mode without incremental propagation, exit after one dump file is received. In incremental propagation mode, exit as - soon as the database is up to date, or if the master returns an + soon as the database is up to date, or if the primary returns an error. **-P** diff --git a/doc/admin/admin_commands/kproplog.rst b/doc/admin/admin_commands/kproplog.rst index 44e706d..3b72cfa 100644 --- a/doc/admin/admin_commands/kproplog.rst +++ b/doc/admin/admin_commands/kproplog.rst @@ -16,18 +16,18 @@ DESCRIPTION The kproplog command displays the contents of the KDC database update log to standard output. It can be used to keep track of incremental updates to the principal database. The update log file contains the -update log maintained by the :ref:`kadmind(8)` process on the master +update log maintained by the :ref:`kadmind(8)` process on the primary KDC server and the :ref:`kpropd(8)` process on the replica KDC servers. When updates occur, they are logged to this file. Subsequently any KDC replica configured for incremental updates will -request the current data from the master KDC and update their log file -with any updates returned. +request the current data from the primary KDC and update their log +file with any updates returned. The kproplog command requires read access to the update log file. It will display update entries only for the KDC it runs on. If no options are specified, kproplog displays a summary of the update -log. If invoked on the master, kproplog also displays all of the +log. If invoked on the primary, kproplog also displays all of the update entries. If invoked on a replica KDC server, kproplog displays only a summary of the updates, which includes the serial number of the last update received and the associated time stamp of the last update. @@ -39,7 +39,8 @@ OPTIONS **-R** Reset the update log. This forces full resynchronization. If used on a replica then that replica will request a full resync. - If used on the master then all replicas will request full resyncs. + If used on the primary then all replicas will request full + resyncs. **-h** Display a summary of the update log. This information includes diff --git a/doc/admin/advanced/retiring-des.rst b/doc/admin/advanced/retiring-des.rst index 4a964c1..38f76d3 100644 --- a/doc/admin/advanced/retiring-des.rst +++ b/doc/admin/advanced/retiring-des.rst @@ -140,7 +140,7 @@ existing tickets will still function until their scheduled expiry .. note:: The new ``krbtgt@REALM`` key should be propagated to replica KDCs - immediately so that TGTs issued by the master KDC can be used to + immediately so that TGTs issued by the primary KDC can be used to issue service tickets on replica KDCs. Replica KDCs will refuse requests using the new TGT kvno until the new krbtgt entry has been propagated to them. @@ -326,7 +326,7 @@ The following KDC configuration will not generate DES keys by default: As before, the KDC process must be restarted for this change to take effect. It is best practice to update kdc.conf on all KDCs, not just the - master, to avoid unpleasant surprises should the master fail and a + primary, to avoid unpleasant surprises should the primary fail and a replica need to be promoted. It is now appropriate to remove the legacy single-DES key from the diff --git a/doc/admin/backup_host.rst b/doc/admin/backup_host.rst index 982a2d1..8914551 100644 --- a/doc/admin/backup_host.rst +++ b/doc/admin/backup_host.rst @@ -21,14 +21,14 @@ As with any file, it is possible that your Kerberos database could become corrupted. If this happens on one of the replica KDCs, you might never notice, since the next automatic propagation of the database would install a fresh copy. However, if it happens to the -master KDC, the corrupted database would be propagated to all of the +primary KDC, the corrupted database would be propagated to all of the replicas during the next propagation. For this reason, MIT recommends -that you back up your Kerberos database regularly. Because the master +that you back up your Kerberos database regularly. Because the primary KDC is continuously dumping the database to a file in order to propagate it to the replica KDCs, it is a simple matter to have a cron job periodically copy the dump file to a secure machine elsewhere on your network. (Of course, it is important to make the host where these backups are stored as secure as your KDCs, and to encrypt its transmission across your network.) Then if your database becomes -corrupted, you can load the most recent dump onto the master KDC. +corrupted, you can load the most recent dump onto the primary KDC. (See :ref:`restore_from_dump`.) diff --git a/doc/admin/conf_files/kdc_conf.rst b/doc/admin/conf_files/kdc_conf.rst index 9759756..0ca3d86 100644 --- a/doc/admin/conf_files/kdc_conf.rst +++ b/doc/admin/conf_files/kdc_conf.rst @@ -229,7 +229,7 @@ The following tags may be specified in a [realms] subsection: **iprop_replica_poll** (Delta time string.) Specifies how often the replica KDC polls - for new updates from the master. The default value is ``2m`` + for new updates from the primary. The default value is ``2m`` (that is, two minutes). New in release 1.17. **iprop_slave_poll** @@ -253,7 +253,7 @@ The following tags may be specified in a [realms] subsection: (Port number.) Specifies the port number to be used for incremental propagation. When **iprop_enable** is true, this relation is required in the replica KDC configuration file, and - this relation or **iprop_listen** is required in the master + this relation or **iprop_listen** is required in the primary configuration file, as there is no default port number. Port numbers specified in **iprop_listen** entries will override this port number for the :ref:`kadmind(8)` daemon. diff --git a/doc/admin/conf_files/krb5_conf.rst b/doc/admin/conf_files/krb5_conf.rst index 7f28796..9e831d4 100644 --- a/doc/admin/conf_files/krb5_conf.rst +++ b/doc/admin/conf_files/krb5_conf.rst @@ -400,7 +400,7 @@ following tags may be specified in the realm's subsection: **admin_server** Identifies the host where the administration server is running. - Typically, this is the master Kerberos server. This tag must be + Typically, this is the primary Kerberos server. This tag must be given a value in order to communicate with the :ref:`kadmind(8)` server for the realm. @@ -515,10 +515,10 @@ following tags may be specified in the realm's subsection: host will be tried. **master_kdc** - Identifies the master KDC(s). Currently, this tag is used in only + Identifies the primary KDC(s). Currently, this tag is used in only one case: If an attempt to get credentials fails because of an invalid password, the client software will attempt to contact the - master KDC, in case the user's password has just been changed, and + primary KDC, in case the user's password has just been changed, and the updated database has not been propagated to the replica servers yet. diff --git a/doc/admin/database.rst b/doc/admin/database.rst index ca19a36..1ce74b3 100644 --- a/doc/admin/database.rst +++ b/doc/admin/database.rst @@ -477,20 +477,20 @@ Starting with release 1.7, :ref:`kdb5_util(8)` allows the master key to be changed using a rollover process, with minimal loss of availability. To roll over the master key, follow these steps: -#. On the master KDC, run ``kdb5_util list_mkeys`` to view the current - master key version number (KVNO). If you have never rolled over - the master key before, this will likely be version 1:: +#. On the primary KDC, run ``kdb5_util list_mkeys`` to view the + current master key version number (KVNO). If you have never rolled + over the master key before, this will likely be version 1:: $ kdb5_util list_mkeys Master keys for Principal: K/M@KRBTEST.COM KVNO: 1, Enctype: aes256-cts-hmac-sha384-192, Active on: Thu Jan 01 00:00:00 UTC 1970 * -#. On the master KDC, run ``kdb5_util use_mkey 1`` to ensure that a +#. On the primary KDC, run ``kdb5_util use_mkey 1`` to ensure that a master key activation list is present in the database. This step is unnecessary in release 1.11.4 or later, or if the database was initially created with release 1.7 or later. -#. On the master KDC, run ``kdb5_util add_mkey -s`` to create a new +#. On the primary KDC, run ``kdb5_util add_mkey -s`` to create a new master key and write it to the stash file. Enter a secure password when prompted. If this is the first time you are changing the master key, the new key will have version 2. The new master key @@ -504,17 +504,17 @@ availability. To roll over the master key, follow these steps: the new master key is present, and then ``kdb5_util stash`` to write the new master key to the replica KDC's stash file. -#. On the master KDC, run ``kdb5_util use_mkey 2`` to begin using the +#. On the primary KDC, run ``kdb5_util use_mkey 2`` to begin using the new master key. Replace ``2`` with the version of the new master key, as appropriate. You can optionally specify a date for the new master key to become active; by default, it will become active immediately. Prior to release 1.12, :ref:`kadmind(8)` must be restarted for this change to take full effect. -#. On the master KDC, run ``kdb5_util update_princ_encryption``. This - command will iterate over the database and re-encrypt all keys in - the new master key. If the database is large and uses DB2, the - master KDC will become unavailable while this command runs, but +#. On the primary KDC, run ``kdb5_util update_princ_encryption``. + This command will iterate over the database and re-encrypt all keys + in the new master key. If the database is large and uses DB2, the + primary KDC will become unavailable while this command runs, but clients should fail over to replica KDCs (if any are present) during this time period. In release 1.13 and later, you can instead run ``kdb5_util -x unlockiter update_princ_encryption`` to @@ -525,7 +525,7 @@ availability. To roll over the master key, follow these steps: and until all running KDC and kadmind processes have serviced requests using updated principal entries. -#. On the master KDC, run ``kdb5_util purge_mkeys`` to clean up the +#. On the primary KDC, run ``kdb5_util purge_mkeys`` to clean up the old master key. @@ -784,14 +784,14 @@ Overview At some very large sites, dumping and transmitting the database can take more time than is desirable for changes to propagate from the -master KDC to the replica KDCs. The incremental propagation support +primary KDC to the replica KDCs. The incremental propagation support added in the 1.7 release is intended to address this. -With incremental propagation enabled, all programs on the master KDC +With incremental propagation enabled, all programs on the primary KDC that change the database also write information about the changes to an "update log" file, maintained as a circular buffer of a certain size. A process on each replica KDC connects to a service on the -master KDC (currently implemented in the :ref:`kadmind(8)` server) and +primary KDC (currently implemented in the :ref:`kadmind(8)` server) and periodically requests the changes that have been made since the last check. By default, this check is done every two minutes. @@ -801,41 +801,41 @@ data in the KDC config file (See :ref:`kdc.conf(5)`): ====================== =============== =========================================== iprop_enable *boolean* If *true*, then incremental propagation is enabled, and (as noted below) normal kprop propagation is disabled. The default is *false*. iprop_master_ulogsize *integer* Indicates the number of entries that should be retained in the update log. The default is 1000; the maximum number is 2500. -iprop_replica_poll *time interval* Indicates how often the replica should poll the master KDC for changes to the database. The default is two minutes. -iprop_port *integer* Specifies the port number to be used for incremental propagation. This is required in both master and replica configuration files. +iprop_replica_poll *time interval* Indicates how often the replica should poll the primary KDC for changes to the database. The default is two minutes. +iprop_port *integer* Specifies the port number to be used for incremental propagation. This is required in both primary and replica configuration files. iprop_resync_timeout *integer* Specifies the number of seconds to wait for a full propagation to complete. This is optional on replica configurations. Defaults to 300 seconds (5 minutes). iprop_logfile *file name* Specifies where the update log file for the realm database is to be stored. The default is to use the *database_name* entry from the realms section of the config file :ref:`kdc.conf(5)`, with *.ulog* appended. (NOTE: If database_name isn't specified in the realms section, perhaps because the LDAP database back end is being used, or the file name is specified in the *dbmodules* section, then the hard-coded default for *database_name* is used. Determination of the *iprop_logfile* default value will not use values from the *dbmodules* section.) ====================== =============== =========================================== -Both master and replica sides must have a principal named +Both primary and replica sides must have a principal named ``kiprop/hostname`` (where *hostname* is the lowercase, fully-qualified, canonical name for the host) registered in the Kerberos database, and have keys for that principal stored in the default keytab file (|keytab|). The ``kiprop/hostname`` principal may -have been created automatically for the master KDC, but it must always -be created for replica KDCs. +have been created automatically for the primary KDC, but it must +always be created for replica KDCs. -On the master KDC side, the ``kiprop/hostname`` principal must be +On the primary KDC side, the ``kiprop/hostname`` principal must be listed in the kadmind ACL file :ref:`kadm5.acl(5)`, and given the **p** privilege (see :ref:`privileges`). On the replica KDC side, :ref:`kpropd(8)` should be run. When incremental propagation is enabled, it will connect to the kadmind on -the master KDC and start requesting updates. +the primary KDC and start requesting updates. The normal kprop mechanism is disabled by the incremental propagation support. However, if the replica has been unable to fetch changes -from the master KDC for too long (network problems, perhaps), the log -on the master may wrap around and overwrite some of the updates that +from the primary KDC for too long (network problems, perhaps), the log +on the primary may wrap around and overwrite some of the updates that the replica has not yet retrieved. In this case, the replica will -instruct the master KDC to dump the current database out to a file and -invoke a one-time kprop propagation, with special options to also +instruct the primary KDC to dump the current database out to a file +and invoke a one-time kprop propagation, with special options to also convey the point in the update log at which the replica should resume fetching incremental updates. Thus, all the keytab and ACL setup previously described for kprop propagation is still needed. If an environment has a large number of replicas, it may be desirable -to arrange them in a hierarchy instead of having the master serve +to arrange them in a hierarchy instead of having the primary serve updates to every replica. To do this, run ``kadmind -proponly`` on each intermediate replica, and ``kpropd -A upstreamhostname`` on downstream replicas to direct each one to the appropriate upstream @@ -844,11 +844,11 @@ replica. There are several known restrictions in the current implementation: - The incremental update protocol does not transport changes to policy - objects. Any policy changes on the master will result in full + objects. Any policy changes on the primary will result in full resyncs to all replicas. - The replica's KDB module must support locking; it cannot be using the LDAP KDB module. -- The master and replica must be able to initiate TCP connections in +- The primary and replica must be able to initiate TCP connections in both directions, without an intervening NAT. @@ -869,7 +869,7 @@ service. In the Sun implementation, the service is registered with rpcbind (also known as portmapper) and the client looks up the port number to contact. In the MIT implementation, where interaction with some modern versions of rpcbind doesn't always work well, the port -number must be specified in the config file on both the master and +number must be specified in the config file on both the primary and replica sides. The Sun implementation hard-codes pathnames in ``/var/krb5`` for the diff --git a/doc/admin/install_kdc.rst b/doc/admin/install_kdc.rst index 157c605..4d90172 100644 --- a/doc/admin/install_kdc.rst +++ b/doc/admin/install_kdc.rst @@ -2,23 +2,24 @@ Installing KDCs =============== When setting up Kerberos in a production environment, it is best to -have multiple replica KDCs alongside with a master KDC to ensure the +have multiple replica KDCs alongside with a primary KDC to ensure the continued availability of the Kerberized services. Each KDC contains -a copy of the Kerberos database. The master KDC contains the writable -copy of the realm database, which it replicates to the replica KDCs at -regular intervals. All database changes (such as password changes) -are made on the master KDC. Replica KDCs provide Kerberos -ticket-granting services, but not database administration, when the -master KDC is unavailable. MIT recommends that you install all of -your KDCs to be able to function as either the master or one of the -replicas. This will enable you to easily switch your master KDC with -one of the replicas if necessary (see :ref:`switch_master_replica`). -This installation procedure is based on that recommendation. +a copy of the Kerberos database. The primary KDC contains the +writable copy of the realm database, which it replicates to the +replica KDCs at regular intervals. All database changes (such as +password changes) are made on the primary KDC. Replica KDCs provide +Kerberos ticket-granting services, but not database administration, +when the primary KDC is unavailable. MIT recommends that you install +all of your KDCs to be able to function as either the primary or one +of the replicas. This will enable you to easily switch your primary +KDC with one of the replicas if necessary (see +:ref:`switch_primary_replica`). This installation procedure is based +on that recommendation. .. warning:: - The Kerberos system relies on the availability of correct time - information. Ensure that the master and all replica KDCs have + information. Ensure that the primary and all replica KDCs have properly synchronized clocks. - It is best to install and run KDCs on secured and dedicated @@ -29,8 +30,8 @@ This installation procedure is based on that recommendation. database. -Install and configure the master KDC ------------------------------------- +Install and configure the primary KDC +------------------------------------- Install Kerberos either from the OS-provided packages or from the source (See :ref:`do_build`). @@ -40,7 +41,7 @@ source (See :ref:`do_build`). For the purpose of this document we will use the following names:: - kerberos.mit.edu - master KDC + kerberos.mit.edu - primary KDC kerberos-1.mit.edu - replica KDC ATHENA.MIT.EDU - realm name .k5.ATHENA.MIT.EDU - stash file @@ -148,7 +149,7 @@ your Kerberos realm and server respectively. Create the KDC database ----------------------- -You will use the :ref:`kdb5_util(8)` command on the master KDC to +You will use the :ref:`kdb5_util(8)` command on the primary KDC to create the Kerberos database and the optional :ref:`stash_definition`. .. note:: @@ -172,7 +173,7 @@ substituting the numeral "4" for the word "for", and includes the punctuation mark at the end.) The following is an example of how to create a Kerberos database and -stash file on the master KDC, using the :ref:`kdb5_util(8)` command. +stash file on the primary KDC, using the :ref:`kdb5_util(8)` command. Replace ``ATHENA.MIT.EDU`` with the name of your Kerberos realm:: shell% kdb5_util create -r ATHENA.MIT.EDU -s @@ -224,10 +225,10 @@ are allowed to administer Kerberos database) to the Kerberos database. You *must* add at least one principal now to allow communication between the Kerberos administration daemon kadmind and the kadmin program over the network for further administration. To do this, use -the kadmin.local utility on the master KDC. kadmin.local is designed -to be run on the master KDC host without using Kerberos authentication -to an admin server; instead, it must have read and write access to the -Kerberos database on the local filesystem. +the kadmin.local utility on the primary KDC. kadmin.local is designed +to be run on the primary KDC host without using Kerberos +authentication to an admin server; instead, it must have read and +write access to the Kerberos database on the local filesystem. The administrative principals you create should be the ones you added to the ACL file (see :ref:`admin_acl`). @@ -248,11 +249,11 @@ is created:: .. _start_kdc_daemons: -Start the Kerberos daemons on the master KDC --------------------------------------------- +Start the Kerberos daemons on the primary KDC +--------------------------------------------- At this point, you are ready to start the Kerberos KDC -(:ref:`krb5kdc(8)`) and administrative daemons on the Master KDC. To +(:ref:`krb5kdc(8)`) and administrative daemons on the primary KDC. To do so, type:: shell% krb5kdc @@ -294,9 +295,10 @@ You are now ready to start configuring the replica KDCs. .. note:: Assuming you are setting the KDCs up so that you can easily - switch the master KDC with one of the replicas, you should - perform each of these steps on the master KDC as well as the - replica KDCs, unless these instructions specify otherwise. + switch the primary KDC with one of the replicas, you should + perform each of these steps on the primary KDC as well as + the replica KDCs, unless these instructions specify + otherwise. .. _replica_host_key: @@ -306,11 +308,11 @@ Create host keytabs for replica KDCs Each KDC needs a ``host`` key in the Kerberos database. These keys are used for mutual authentication when propagating the database dump -file from the master KDC to the secondary KDC servers. +file from the primary KDC to the secondary KDC servers. -On the master KDC, connect to administrative interface and create the +On the primary KDC, connect to administrative interface and create the host principal for each of the KDCs' ``host`` services. For example, -if the master KDC were called ``kerberos.mit.edu``, and you had a +if the primary KDC were called ``kerberos.mit.edu``, and you had a replica KDC named ``kerberos-1.mit.edu``, you would type the following:: @@ -323,9 +325,9 @@ following:: No policy specified for "host/kerberos-1.mit.edu@ATHENA.MIT.EDU"; assigning "default" Principal "host/kerberos-1.mit.edu@ATHENA.MIT.EDU" created. -It is not strictly necessary to have the master KDC server in the +It is not strictly necessary to have the primary KDC server in the Kerberos database, but it can be handy if you want to be able to swap -the master KDC with one of the replicas. +the primary KDC with one of the replicas. Next, extract ``host`` random keys for all participating KDCs and store them in each host's default keytab file. Ideally, you should @@ -345,7 +347,7 @@ To extract a keytab directly on a replica KDC called type arcfour-hmac added to keytab FILE:/etc/krb5.keytab. If you are instead extracting a keytab for the replica KDC called -``kerberos-1.mit.edu`` on the master KDC, you should use a dedicated +``kerberos-1.mit.edu`` on the primary KDC, you should use a dedicated temporary keytab file for that machine's keytab:: kadmin: ktadd -k /tmp/kerberos-1.keytab host/kerberos-1.mit.edu @@ -361,10 +363,10 @@ The file ``/tmp/kerberos-1.keytab`` can then be installed as Configure replica KDCs ~~~~~~~~~~~~~~~~~~~~~~ -Database propagation copies the contents of the master's database, but -does not propagate configuration files, stash files, or the kadm5 ACL -file. The following files must be copied by hand to each replica (see -:ref:`mitK5defaults` for the default locations for these files): +Database propagation copies the contents of the primary's database, +but does not propagate configuration files, stash files, or the kadm5 +ACL file. The following files must be copied by hand to each replica +(see :ref:`mitK5defaults` for the default locations for these files): * krb5.conf * kdc.conf @@ -372,11 +374,11 @@ file. The following files must be copied by hand to each replica (see * master key stash file Move the copied files into their appropriate directories, exactly as -on the master KDC. kadm5.acl is only needed to allow a replica to -swap with the master KDC. +on the primary KDC. kadm5.acl is only needed to allow a replica to +swap with the primary KDC. -The database is propagated from the master KDC to the replica KDCs via -the :ref:`kpropd(8)` daemon. You must explicitly specify the +The database is propagated from the primary KDC to the replica KDCs +via the :ref:`kpropd(8)` daemon. You must explicitly specify the principals which are allowed to provide Kerberos dump updates on the replica machine with a new database. Create a file named kpropd.acl in the KDC state directory containing the ``host`` principals for each @@ -387,11 +389,11 @@ of the KDCs:: .. note:: - If you expect that the master and replica KDCs will be + If you expect that the primary and replica KDCs will be switched at some point of time, list the host principals from all participating KDC servers in kpropd.acl files on all of the KDCs. Otherwise, you only need to list the - master KDC's host principal in the kpropd.acl files of the + primary KDC's host principal in the kpropd.acl files of the replica KDCs. Then, add the following line to ``/etc/inetd.conf`` on each KDC @@ -411,10 +413,10 @@ Alternatively, start :ref:`kpropd(8)` as a stand-alone daemon. This is required when incremental propagation is enabled. Now that the replica KDC is able to accept database propagation, -you’ll need to propagate the database from the master server. +you’ll need to propagate the database from the primary server. NOTE: Do not start the replica KDC yet; you still do not have a copy -of the master's database. +of the primary's database. .. _kprop_to_replicas: @@ -422,7 +424,7 @@ of the master's database. Propagate the database to each replica KDC ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -First, create a dump file of the database on the master KDC, as +First, create a dump file of the database on the primary KDC, as follows:: shell% kdb5_util dump /usr/local/var/krb5kdc/replica_datatrans @@ -463,7 +465,7 @@ start the krb5kdc daemon:: shell% krb5kdc -As with the master KDC, you will probably want to add this command to +As with the primary KDC, you will probably want to add this command to the KDCs' ``/etc/rc`` or ``/etc/inittab`` files, so they will start the krb5kdc daemon automatically at boot time. @@ -489,26 +491,26 @@ services into the Kerberos database. This procedure is described fully in :ref:`add_mod_del_princs`. You may occasionally want to use one of your replica KDCs as the -master. This might happen if you are upgrading the master KDC, or if -your master KDC has a disk crash. See the following section for the -instructions. +primary. This might happen if you are upgrading the primary KDC, or +if your primary KDC has a disk crash. See the following section for +the instructions. -.. _switch_master_replica: +.. _switch_primary_replica: -Switching master and replica KDCs ---------------------------------- +Switching primary and replica KDCs +---------------------------------- You may occasionally want to use one of your replica KDCs as the -master. This might happen if you are upgrading the master KDC, or if -your master KDC has a disk crash. +primary. This might happen if you are upgrading the primary KDC, or +if your primary KDC has a disk crash. Assuming you have configured all of your KDCs to be able to function -as either the master KDC or a replica KDC (as this document +as either the primary KDC or a replica KDC (as this document recommends), all you need to do to make the changeover is: -If the master KDC is still running, do the following on the *old* -master KDC: +If the primary KDC is still running, do the following on the *old* +primary KDC: #. Kill the kadmind process. #. Disable the cron job that propagates the database. @@ -516,12 +518,12 @@ master KDC: replicas all have the latest copy of the database (see :ref:`kprop_to_replicas`). -On the *new* master KDC: +On the *new* primary KDC: #. Start the :ref:`kadmind(8)` daemon (see :ref:`start_kdc_daemons`). #. Set up the cron job to propagate the database (see :ref:`kprop_to_replicas`). -#. Switch the CNAMEs of the old and new master KDCs. If you can't do +#. Switch the CNAMEs of the old and new primary KDCs. If you can't do this, you'll need to change the :ref:`krb5.conf(5)` file on every client machine in your Kerberos realm. diff --git a/doc/admin/lockout.rst b/doc/admin/lockout.rst index 97d9b1e..cce4490 100644 --- a/doc/admin/lockout.rst +++ b/doc/admin/lockout.rst @@ -102,11 +102,11 @@ traditional :ref:`kprop(8)` or incremental propagation. Because of this, the number of attempts an attacker can make within a time period is multiplied by the number of KDCs. For instance, if the **maxfailure** parameter on a policy is 10 and there are four KDCs in -the environment (a master and three replicas), an attacker could make +the environment (a primary and three replicas), an attacker could make as many as 40 attempts before the principal is locked out on all four KDCs. -An administrative unlock is propagated from the master to the replica +An administrative unlock is propagated from the primary to the replica KDCs during the next propagation. Propagation of an administrative unlock will cause the counter of failed attempts on each replica to reset to 1 on the next failure. diff --git a/doc/admin/realm_config.rst b/doc/admin/realm_config.rst index 23245ca..caacc70 100644 --- a/doc/admin/realm_config.rst +++ b/doc/admin/realm_config.rst @@ -10,8 +10,8 @@ following issues: * 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 master and replica KDCs. -* How frequently you will propagate the database from the master KDC +* The hostnames of your primary and replica KDCs. +* How frequently you will propagate the database from the primary KDC to the replica KDCs. @@ -98,7 +98,7 @@ Replica KDCs ------------ Replica KDCs provide an additional source of Kerberos ticket-granting -services in the event of inaccessibility of the master KDC. The +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. @@ -109,15 +109,15 @@ 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 master KDC +* 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 master, in case of power outages, fires, or other localized - disasters. + from the primary, in case of power outages, fires, or other + localized disasters. .. _kdc_hostnames: @@ -126,7 +126,7 @@ 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 +(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. @@ -153,22 +153,21 @@ _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 master KDC before failing with an + 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 master KDC. Support for it is + 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)`. -_kpasswd._udp - This should list port 464 on your master 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 749. + _kpasswd._udp This 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 749. The DNS SRV specification requires that the hostnames listed be the canonical names, not aliases. So, for example, you might include the @@ -202,8 +201,8 @@ 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 master server. The URI record can -convey more information about a realm's KDCs with a single query. +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: @@ -218,8 +217,8 @@ consists of case-insensitive colon separated fields, in the form * *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 master - server. + 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. @@ -247,7 +246,7 @@ records are found. Database propagation -------------------- -The Kerberos database resides on the master KDC, and must be +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 @@ -258,7 +257,7 @@ 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 master KDC propagate the database to +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. diff --git a/doc/admin/troubleshoot.rst b/doc/admin/troubleshoot.rst index 6a0c7f8..ade5e1f 100644 --- a/doc/admin/troubleshoot.rst +++ b/doc/admin/troubleshoot.rst @@ -107,7 +107,7 @@ kprop: No route to host while connecting to server .................................................. Make sure that the hostname of the replica KDC (as given to kprop) is -correct, and that any firewalls between the master and the replica +correct, and that any firewalls between the primary and the replica allow a connection on port 754. .. _kprop_con_refused: @@ -128,8 +128,8 @@ kprop: Server rejected authentication (during sendauth exchange) while authentic Make sure that: -#. The time is synchronized between the master and replica KDCs. -#. The master stash file was copied from the master to the expected +#. The time is synchronized between the primary and replica KDCs. +#. The master stash file was copied from the primary to the expected location on the replica. #. The replica has a keytab file in the default location containing a ``host`` principal for the replica's hostname. diff --git a/doc/build/directory_org.rst b/doc/build/directory_org.rst index db0c6c0..109b69a 100644 --- a/doc/build/directory_org.rst +++ b/doc/build/directory_org.rst @@ -11,7 +11,7 @@ clients Kerberos V5 user programs (See :ref:`user_commands`) config Configure scripts config-files Sample Kerberos configuration files include include files needed to build the Kerberos system -kadmin Administrative interface to the Kerberos master database: :ref:`kadmin(1)`, :ref:`kdb5_util(8)`, :ref:`ktutil(1)`. +kadmin Administrative interface to the Kerberos database: :ref:`kadmin(1)`, :ref:`kdb5_util(8)`, :ref:`ktutil(1)`. kdc Kerberos V5 Authentication Service and Key Distribution Center lib_ Libraries for use with/by Kerberos V5 plugins Kerberos plugins directory diff --git a/doc/iprop-notes.txt b/doc/iprop-notes.txt index ac57305..b620773 100644 --- a/doc/iprop-notes.txt +++ b/doc/iprop-notes.txt @@ -3,18 +3,18 @@ install guide. Bugs or issues: -The "full resync" part of the protocol involves the master side firing -off a normal kprop (and going back to servicing requests), and the -replica side stopping all the incremental propagation stuff and -waiting for the kprop. If the connection from the master never comes +The "full resync" part of the protocol involves the primary side +firing off a normal kprop (and going back to servicing requests), and +the replica side stopping all the incremental propagation stuff and +waiting for the kprop. If the connection from the primary never comes in for some reason, the replica side just blocks forever, and never resumes incremental propagation. The protocol does not currently pass policy database changes; this was an intentional decision on Sun's part. The policy database is only -relevant to the master KDC, and is usually fairly static (aside from +relevant to the primary KDC, and is usually fairly static (aside from refcount updates), but not propagating it does mean that a replica -maintained via iprop can't simply be promoted to a master in disaster +maintained via iprop can't simply be promoted to a primary in disaster recovery or other cases without doing a full propagation or restoring a database from backups. @@ -29,8 +29,8 @@ the update log as well; etc. At least initially, we wouldn't treat it as a differently-named database; the installation of the hooks would be done by explicitly checking if iprop is enabled, etc. -The "iprop role" is assumed to be either master or replica. The -master writes a log, and the replica fetches it. But what about a +The "iprop role" is assumed to be either primary or replica. The +primary writes a log, and the replica fetches it. But what about a cascade propagation model where A sends to B which sends to C, perhaps because A's bandwidth is highly limited, or B and C are co-located? In such a case, B would want to operate in both modes. Granted, with @@ -67,10 +67,10 @@ db changes, which locking protocols should deal with anyways, (b) existing acl code, (c) existing server process? The incremental propagation protocol requires an ACL entry on the -master, listing the replica. Since the full-resync part uses normal -kprop, the replica also has to have an ACL entry for the master. If +primary, listing the replica. Since the full-resync part uses normal +kprop, the replica also has to have an ACL entry for the primary. If this is missing, I suspect the behavior will be that every two -minutes, the master side will (at the prompting of the replica) dump +minutes, the primary side will (at the prompting of the replica) dump out the database and attempt a full propagation. Possible optimizations: If an existing dump file has a recent enough @@ -97,7 +97,7 @@ resizing the log because of a too-large log entry. The kprop invocation doesn't specify a realm name, so it'll only work for the default realm. No clean way to specify a port number, either. Would it be overkill to come up with a way to configure host+port for -kpropd on the master? Preferably in a way that'd support cascading +kpropd on the primary? Preferably in a way that'd support cascading propagations. The kadmind process, when it needs to run kprop, extracts the replica diff --git a/doc/mitK5features.rst b/doc/mitK5features.rst index 98c1435..8d6041d 100644 --- a/doc/mitK5features.rst +++ b/doc/mitK5features.rst @@ -146,7 +146,7 @@ Release 1.13 protocol. - Add support for `hierarchical incremental propagation <https://k5wiki.kerberos.org/wiki/Projects/Hierarchical_iprop>`_, - where replicas can act as intermediates between an upstream master + where replicas can act as intermediates between an upstream primary and other downstream replicas. - Add support for configuring GSS mechanisms using ``/etc/gss/mech.d/*.conf`` files in addition to @@ -255,9 +255,9 @@ Release 1.14 * Performance: - - On replica KDCs, poll the master KDC immediately after processing - a full resync, and do not require two full resyncs after the - master KDC's log file is reset. + - On replica KDCs, poll the primary KDC immediately after + processing a full resync, and do not require two full resyncs + after the primary KDC's log file is reset. Release 1.15 @@ -279,7 +279,7 @@ Release 1.15 - Add DNS auto-discovery of KDC and kpasswd servers from URI records, in addition to SRV records. URI records can convey TCP - and UDP servers and master KDC status in a single DNS lookup, and + and UDP servers and primary KDC status in a single DNS lookup, and can also point to HTTPS proxy servers. - Add support for password history to the LDAP back end. |