svn rev #25717: trunk/doc/rst_source/krb_admins/install_kdc/

ghudson@MIT.EDU ghudson at MIT.EDU
Mon Feb 27 18:29:09 EST 2012


http://src.mit.edu/fisheye/changelog/krb5/?cs=25717
Commit By: ghudson
Log Message:
Edit RST install guide for clarity and accuracy

Notable changes include:

* In the example config files, configure logging in kdc.conf rather
  than krb5.conf.

* It is no longer necessary to create a dummy database on slaves
  before propagating the master DB with kprop; remove that step from
  the instructions.

* The admin keytab file is no longer required or used.


Changed Files:
U   trunk/doc/rst_source/krb_admins/install_kdc/admins_to_acl.rst
U   trunk/doc/rst_source/krb_admins/install_kdc/admins_to_db.rst
U   trunk/doc/rst_source/krb_admins/install_kdc/create_db.rst
U   trunk/doc/rst_source/krb_admins/install_kdc/index.rst
D   trunk/doc/rst_source/krb_admins/install_kdc/kadmind_kt.rst
U   trunk/doc/rst_source/krb_admins/install_kdc/kdc_prop_slave.rst
U   trunk/doc/rst_source/krb_admins/install_kdc/krb_daemon.rst
U   trunk/doc/rst_source/krb_admins/install_kdc/mod_conf.rst
U   trunk/doc/rst_source/krb_admins/install_kdc/slave_install.rst
U   trunk/doc/rst_source/krb_admins/install_kdc/switch_master_slave.rst
Modified: trunk/doc/rst_source/krb_admins/install_kdc/admins_to_acl.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/install_kdc/admins_to_acl.rst	2012-02-27 18:31:50 UTC (rev 25716)
+++ trunk/doc/rst_source/krb_admins/install_kdc/admins_to_acl.rst	2012-02-27 23:29:09 UTC (rev 25717)
@@ -3,7 +3,7 @@
 Add administrators to the ACL file
 ==================================
 
-Next, you need create an Access Control List (ACL) file, and put the
+Next, you need create an Access Control List (ACL) file and put the
 Kerberos principal of at least one of the administrators into it.
 This file is used by the :ref:`kadmind(8)` daemon to control which
 principals may view and make privileged modifications to the Kerberos
@@ -14,15 +14,15 @@
 
 The format of the file is::
 
-    kerberos_principal      permissions     [target_principal]  [restrictions]
+    client_principal      permissions     [target_principal]  [restrictions]
 
-The *kerberos_principal* (and optional *target_principal*) can include
-the "*" wildcard, so if you want any principal with the instance
-"admin" to have full permissions on the database, you could use the
-principal "\*\/admin\@REALM" where "REALM" is your Kerberos realm.
+The *client_principal* (and optional *target_principal*) can include
+the ``*`` wildcard, so if you want any principal with the instance
+``admin`` to have full permissions on the database, you could use the
+principal ``*/admin at REALM`` where *REALM* is your Kerberos realm.
 *target_principal* can also include backreferences to
-*kerberos_principal*, in which "\*number" matches the component number
-in the *kerberos_principal*.
+*client_principal*, in which ``*number`` matches the component number
+in *client_principal*.
 
 .. note:: A common use of an admin instance is so you can grant
           separate permissions (such as administrator access to the
@@ -32,9 +32,9 @@
           way, ``joeadmin`` would obtain ``joeadmin/admin`` tickets
           only when he actually needs to use those permissions.
 
-The permissions are represented by single letters.  The lower-case
-charecter specifies that operation can be performed by the principal,
-while its UPPER-CASE counterparts represent negative permissions.  The
+The permissions are represented by single letters.  A lowercase
+character specifies that operation can be performed by the principal,
+while its uppercase counterpart indicates negative permission.  The
 permissions are:
 
     ==== ==========================================================
@@ -49,7 +49,7 @@
     x    All privileges (admcil); identical to "\*"
     ==== ==========================================================
 
-The restrictions are a string of flags. Allowed restrictions are:
+*Restrictions* are a string of flags. Allowed restrictions are:
 
     ====================== ===============================
     [+\|-]flagname          flag is forced to indicated value.  The permissible flags are the same as the + and - flags for the kadmin :ref:`add_principal` and :ref:`modify_principal` commands.
@@ -66,8 +66,8 @@
 
 Here is an example of a kadm5.acl file.
 
-.. warning:: The order is important; permissions are determined by the
-             first matching entry.
+.. warning:: The order of lines is important; permissions are
+             determined by the first matching entry.
 
 ::
 

Modified: trunk/doc/rst_source/krb_admins/install_kdc/admins_to_db.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/install_kdc/admins_to_db.rst	2012-02-27 18:31:50 UTC (rev 25716)
+++ trunk/doc/rst_source/krb_admins/install_kdc/admins_to_db.rst	2012-02-27 23:29:09 UTC (rev 25717)
@@ -6,13 +6,12 @@
 Next you need to add administrative principals (i.e. principals who
 are allowed to administer Kerberos database) to the Kerberos database.
 You *must* add at least one principal now to allow communication
-between Kerberos administration daemon kadmind and kadmin program over
-the network for the further Kerberos administration.  To do this, use
-kadmin.local utility on the master KDC.  Note, that kadmin.local is
-designed to be ran on the same host as the primary KDC without using
-the Kerberos authentication to its database.  (However, one needs
-administrative privileges on the local filesystem to access database
-files for this command to succeed.)
+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 its database; 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`).

Modified: trunk/doc/rst_source/krb_admins/install_kdc/create_db.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/install_kdc/create_db.rst	2012-02-27 18:31:50 UTC (rev 25716)
+++ trunk/doc/rst_source/krb_admins/install_kdc/create_db.rst	2012-02-27 23:29:09 UTC (rev 25717)
@@ -11,23 +11,22 @@
           means that the KDC will not be able to start automatically,
           such as after a system reboot.
 
-Note that :ref:`kdb5_util(8)` will prompt you for the master key for
-the Kerberos database.  This key can be any string.  A good key is one
-you can remember, but that no one else can guess.  Examples of bad
-keys are words that can be found in a dictionary, any common or
-popular name, especially a famous person (or cartoon character), your
-username in any form (e.g., forward, backward, repeated twice, etc.),
-and any of the sample keys that appear in this manual.  One example of
-a key which might be good if it did not appear in this manual is
-"MITiys4K5!", which represents the sentence "MIT is your source for
-Kerberos 5!"  (It's the first letter of each word, substituting the
-numeral "4" for the word "for", and includes the punctuation mark at
-the end.)
+:ref:`kdb5_util(8)` will prompt you for the master password for the
+Kerberos database.  This password can be any string.  A good password
+is one you can remember, but that no one else can guess.  Examples of
+bad passwords are words that can be found in a dictionary, any common
+or popular name, especially a famous person (or cartoon character),
+your username in any form (e.g., forward, backward, repeated twice,
+etc.), and any of the sample passwords that appear in this manual.
+One example of a password which might be good if it did not appear in
+this manual is "MITiys4K5!", which represents the sentence "MIT is
+your source for Kerberos 5!"  (It's the first letter of each word,
+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. Replace ``ATHENA.MIT.EDU`` with the name of your Kerberos
-realm::
+stash file on the master KDC, using the :ref:`kdb5_util(8)` command.
+Replace ``ATHENA.MIT.EDU`` with the name of your Kerberos realm::
 
     shell% /usr/local/sbin/kdb5_util create -r ATHENA.MIT.EDU -s
 
@@ -40,13 +39,13 @@
     shell%
 
 This will create five files in the directory specified in your
-:ref:`kdc.conf(5)` file (The default location is
-``/usr/local/var/krb5kdc`` directory. See :ref:`mitK5defaults`):
+:ref:`kdc.conf(5)` file (the default location is
+``/usr/local/var/krb5kdc`` directory; see :ref:`mitK5defaults`):
 
-- two Kerberos database files, ``principal``, and ``principal.ok``;
-- the Kerberos administrative database file, ``principal.kadm5``;
-- the administrative database lock file, ``principal.kadm5.lock``;
-- the stash file, in this example ``.k5.ATHENA.MIT.EDU`` (by default
+* two Kerberos database files, ``principal``, and ``principal.ok``
+* the Kerberos administrative database file, ``principal.kadm5``
+* the administrative database lock file, ``principal.kadm5.lock``
+* the stash file, in this example ``.k5.ATHENA.MIT.EDU`` (by default
   it is ``.k5.`` prefix followed by the realm name of the database).
   If you do not want a stash file, run the above command without the
   **-s** option.

Modified: trunk/doc/rst_source/krb_admins/install_kdc/index.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/install_kdc/index.rst	2012-02-27 18:31:50 UTC (rev 25716)
+++ trunk/doc/rst_source/krb_admins/install_kdc/index.rst	2012-02-27 23:29:09 UTC (rev 25717)
@@ -8,32 +8,31 @@
 Installing KDCs
 ===============
 
-When setting up Kerberos in a production environment it is recommended
-to have multiple secondary (slave) KDCs alongside with a primary
-(master) 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 slave KDCs at regular intervals.  All database
-changes (such as password changes) are made on the master KDC.  Slave
-KDCs provide Kerberos ticket-granting services, but not database
-administration.  This allows clients to continue to obtain tickets
-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 slaves.  This will enable you to easily switch your master KDC
-with one of the slaves if necessary. (See :ref:`switch_master_slave`.)
-This installation procedure is based on that recommendation.
+When setting up Kerberos in a production environment, it is best to
+have multiple slave KDCs alongside with a master 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 slave KDCs at
+regular intervals.  All database changes (such as password changes)
+are made on the master KDC.  Slave 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
+slaves.  This will enable you to easily switch your master KDC with
+one of the slaves if necessary (see :ref:`switch_master_slave`).  This
+installation procedure is based on that recommendation.
 
 .. warning::
-    - The Kerberos system heavily relies on the timestamps, so all
-      Kerberos exchange participants should be rather well
-      synchronized.
+    - The Kerberos system relies on the availability of correct time
+      information.  Ensure that the master and all slave KDCs have
+      properly synchronized clocks.
 
-    - It is recomended to install and run KDCs on the secured and
-      dedicated solely to KDC hardware with limited access.  If your
-      KDC is also a file server, FTP server, Web server, or even just
-      a client machine, someone who obtained root access through a
-      security hole in any of those areas could gain access to the
-      Kerberos database.
+    - It is best to install and run KDCs on secured and dedicated
+      hardware with limited access.  If your KDC is also a file
+      server, FTP server, Web server, or even just a client machine,
+      someone who obtained root access through a security hole in any
+      of those areas could potentially gain access to the Kerberos
+      database.
 
 
 Install and configure the master KDC
@@ -47,7 +46,6 @@
 
              kerberos.mit.edu    - master KDC
              kerberos-1.mit.edu  - slave KDC
-             mit.edu             - domain name
              ATHENA.MIT.EDU      - realm name
              .k5.ATHENA.MIT.EDU  - stash file
              admin/admin         - admin principal
@@ -63,13 +61,19 @@
    create_db.rst
    admins_to_acl.rst
    admins_to_db.rst
-   kadmind_kt.rst
    krb_daemon.rst
 
 
 Install the Slave KDCs
 ----------------------
 
+You are now ready to start configuring the slave KDCs.
+
+.. note:: Assuming you are setting the KDCs up so that you can easily
+          switch the master KDC with one of the slaves, you should
+          perform each of these steps on the master KDC as well as the
+          slave KDCs, unless these instructions specify otherwise.
+
 .. toctree::
    :maxdepth: 1
 
@@ -79,8 +83,7 @@
 Once your KDCs are set up and running, you are ready to use
 :ref:`kadmin(1)` to load principals for your users, hosts, and other
 services into the Kerberos database.  This procedure is described
-fully in the :ref:`add_mod_del_princs`.  The keytab is generated by
-running kadmin and issuing the :ref:`ktadd` command.
+fully in :ref:`add_mod_del_princs`.
 
 You may occasionally want to use one of your slave KDCs as the master.
 This might happen if you are upgrading the master KDC, or if your
@@ -92,7 +95,7 @@
 -------------------------------
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    switch_master_slave.rst
 

Modified: trunk/doc/rst_source/krb_admins/install_kdc/kdc_prop_slave.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/install_kdc/kdc_prop_slave.rst	2012-02-27 18:31:50 UTC (rev 25716)
+++ trunk/doc/rst_source/krb_admins/install_kdc/kdc_prop_slave.rst	2012-02-27 23:29:09 UTC (rev 25717)
@@ -1,38 +1,25 @@
+.. _kprop_to_slaves:
+
 Propagate the database to each slave KDC
-===========================================
+========================================
 
-First, stop the kadmin service.
-
-Next, create a dump file of the database on the master KDC, as
+First, create a dump file of the database on the master KDC, as
 follows::
 
     shell% /usr/local/sbin/kdb5_util dump /usr/local/var/krb5kdc/slave_datatrans
 
-Finally, manually propagate the database to each slave KDC, as in the
+Then, manually propagate the database to each slave KDC, as in the
 following example::
 
     shell% /usr/local/sbin/kprop -f /usr/local/var/krb5kdc/slave_datatrans kerberos-1.mit.edu
 
     Database propagation to kerberos-1.mit.edu: SUCCEEDED
 
-Just in case you need an additional confirmation of the successful
-propagation, do the following on the slave:
-
-* make sure that only this slave's kdc is listed in the
-  :ref:`krb5.conf(5)` file, then
-* start :ref:`krb5kdc(8)` on the slave server and
-* run ``kinit admin/admin at ATHENA.MIT.EDU`` which should succeed once
-  the correct password (i.e. password that was entered on the master
-  server for this principal) is provided.
-* now :ref:`klist(1)` should display the message similar to ``Default
-  principal: admin/admin at ATHENA.MIT.EDU``
-
 You will need a script to dump and propagate the database. The
-following is an example of a bourne shell script that will do this.
+following is an example of a Bourne shell script that will do this.
 
-.. note:: Remember that you need to replace ``/usr/local/var`` with
-          the name of the directory in which you installed Kerberos
-          V5.
+.. note:: Remember that you need to replace ``/usr/local/var/krb5kdc``
+          with the name of the KDC state directory.
 
 ::
 
@@ -40,66 +27,60 @@
 
     kdclist = "kerberos-1.mit.edu kerberos-2.mit.edu"
 
-    /usr/local/sbin/kdb5_util "dump /usr/local/var/krb5kdc/slave_datatrans"
+    /usr/local/sbin/kdb5_util dump /usr/local/var/krb5kdc/slave_datatrans
 
     for kdc in $kdclist
     do
-    /usr/local/sbin/kprop -f /usr/local/var/krb5kdc/slave_datatrans $kdc
+        /usr/local/sbin/kprop -f /usr/local/var/krb5kdc/slave_datatrans $kdc
     done
 
 You will need to set up a cron job to run this script at the intervals
-you decided on earlier (See :ref:`db_prop` and :ref:`incr_db_prop`.)
-The dump can also be used as a save file.  Once the operation
-succeeded, connect to slaves and start thier KDCs.
+you decided on earlier (see :ref:`db_prop`).
 
 Now that the slave KDC has a copy of the Kerberos database, you can
 start the krb5kdc daemon::
 
-    shell% usr/local/sbin/krb5kdc
+    shell% /usr/local/sbin/krb5kdc
 
 As with the master 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.
 
-Once your KDCs are set up and running, you are ready to use
-:ref:`kadmin(1)` to load principals for your users, hosts, and other
-services into the Kerberos database.  This procedure is described
-fully in the :ref:`add_mod_del_princs`.  The keytab is generated by
-running kadmin and issuing the ktadd command.
 
-
 Propagation failed?
 -------------------
 
 .. _prop_failed_start:
 
-.. error:: kprop: No route to host in call to connect while opening
-           connection
+.. error:: kprop: No route to host while connecting to server
 
-           kprop: Connection refused in call to connect while opening
+Make sure that the hostname of the slave (as given to kprop) is
+correct, and that any firewalls beween the master and the slave allow
+a connection on port 754.
+
+.. error:: kprop: Connection refused in call to connect while opening
            connection
 
-           kprop: Server rejected authentication (during sendauth
-           exchange) while authenticating to server
+If the slave is intended to run kpropd out of inetd, make sure that
+inetd is configured to accept krb5_prop connections.  inetd may need
+to be restarted or sent a SIGHUP to recognize the new configuration.
+If the slave is intended to run kpropd in standalone mode, make sure
+that it is running.
 
+.. error:: kprop: Server rejected authentication while authenticating
+           to server
+
 Make sure that:
 
-#. the time is syncronized between the master-slaves participants;
-#. master stash and keytab files (e.g. ``.k5.ATHENA.MIT.EDU`` and
-   ``host/kerberos-1.mit.edu at ATHENA.MIT.EDU``) are copied from the
-   master to the expected location on the slaves;
-#. Kerberos database was created on the slaves prior the propagation
-   from the master.
-#. if :ref:`kpropd(8)` is invoked from inetd (or its equivalent
-   xinetd), the inetd daemon was restarted after the configuration
-   files ``/etc/inetd.conf`` and ``/etc/services`` were updated;
-#. kpropd is running on the slave server;
-#. if the locations of the configuration/keytab files differ from the
-   default ones, provide the proper environment variables and/or
-   options to the programs;
+#. The time is syncronized between the master and slave KDCs.
+#. The master stash file was copied from the master to the expected
+   location on the slave.
+#. The slave has a keytab file in the default location containing a
+   ``host`` principal for the slave's hostname.
 
 .. _prop_failed_end:
 
+
 Feedback
 --------
 

Modified: trunk/doc/rst_source/krb_admins/install_kdc/krb_daemon.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/install_kdc/krb_daemon.rst	2012-02-27 18:31:50 UTC (rev 25716)
+++ trunk/doc/rst_source/krb_admins/install_kdc/krb_daemon.rst	2012-02-27 23:29:09 UTC (rev 25717)
@@ -1,8 +1,10 @@
+.. _start_kdc_daemons:
+
 Start the Kerberos daemons on the master 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 Master KDC.  To
 do so, type::
 
     shell% /usr/local/sbin/krb5kdc
@@ -29,18 +31,11 @@
 
 As an additional verification, check if :ref:`kinit(1)` succeeds
 against the principals that you have created on the previous step
-(:ref:`addadmin_kdb`). Run::
+(:ref:`addadmin_kdb`).  Run::
 
     shell% /usr/local/bin/kinit admin/admin at ATHENA.MIT.EDU
 
-You are now ready to start configuring the slave KDCs.
 
-.. note:: Assuming you are setting the KDCs up so that you can easily
-          switch the master KDC with one of the slaves, you should
-          perform each of these steps on the master KDC as well as the
-          slave KDCs, unless these instructions specify otherwise.
-
-
 Feedback
 --------
 

Modified: trunk/doc/rst_source/krb_admins/install_kdc/mod_conf.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/install_kdc/mod_conf.rst	2012-02-27 18:31:50 UTC (rev 25716)
+++ trunk/doc/rst_source/krb_admins/install_kdc/mod_conf.rst	2012-02-27 23:29:09 UTC (rev 25717)
@@ -31,32 +31,28 @@
 *realm* in the :ref:`realms` section.  To communicate with the kadmin
 server in each realm, the **admin_server** tag must be set in the
 :ref:`realms` section.  If your domain name and realm name are not the
-same, you must provide a translation in :ref:`domain_realm`.  It is
-also higly recommeneded that you create a :ref:`logging` stanza if the
-computer will be functioning as a KDC so that :ref:`krb5kdc(8)` and
-:ref:`kadmind(8)` will generate logging output.
+same, you must provide a translation in :ref:`domain_realm`.
 
 An example krb5.conf file::
 
     [libdefaults]
         default_realm = ATHENA.MIT.EDU
-        # if the default location does not suit your setup,
-        # explicitly configure the keytab location:
-        #    default_keytab_name = FILE:/var/krb5kdc/krb5.keytab
 
     [realms]
         ATHENA.MIT.EDU = {
             kdc = kerberos.mit.edu
             kdc = kerberos-1.mit.edu
-            kdc = kerberos-2.mit.edu
             admin_server = kerberos.mit.edu
         }
 
-    [logging]
-        kdc = FILE:/var/log/krb5kdc.log
-        admin_server = FILE:/var/log/kadmin.log
-        default = FILE:/var/log/krb5lib.log
 
+kdc.conf
+--------
+
+The kdc.conf file can be used to control the listening ports of the
+KDC and kadmind, as well as realm-specific defaults, the database type
+and location, and logging.
+
 An example kdc.conf file::
 
     [kdcdefaults]
@@ -67,9 +63,9 @@
             kadmind_port = 749
             max_life = 12h 0m 0s
             max_renewable_life = 7d 0h 0m 0s
-            master_key_type = des3-hmac-sha1
-            supported_enctypes = des3-hmac-sha1:normal aes128-cts-hmac-sha1-96:normal
-            # if the default location does not suit your setup,
+            master_key_type = aes256-cts
+            supported_enctypes = aes256-cts:normal aes128-cts:normal
+            # If the default location does not suit your setup,
             # explicitly configure the following four values:
             #    database_name = /var/krb5kdc/principal
             #    key_stash_file = /var/krb5kdc/.k5.ATHENA.MIT.EDU
@@ -77,6 +73,13 @@
             #    acl_file = /var/krb5kdc/kadm5.acl
         }
 
+    [logging]
+        # By default, the KDC and kadmind will log output using
+        # syslog.  You can instead send log output to files like this:
+        kdc = FILE:/var/log/krb5kdc.log
+        admin_server = FILE:/var/log/kadmin.log
+        default = FILE:/var/log/krb5lib.log
+
 Replace ``ATHENA.MIT.EDU`` and ``kerberos.mit.edu`` with the name of
 your Kerberos realm and server respectively.
 

Modified: trunk/doc/rst_source/krb_admins/install_kdc/slave_install.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/install_kdc/slave_install.rst	2012-02-27 18:31:50 UTC (rev 25716)
+++ trunk/doc/rst_source/krb_admins/install_kdc/slave_install.rst	2012-02-27 23:29:09 UTC (rev 25717)
@@ -6,14 +6,14 @@
 Prep work on the master side
 ----------------------------
 
-Each KDC needs a ``host`` keys in the Kerberos database.  These keys
+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.
 
-On the master KDC connect to administrative interface and create the
-new principals for each of the KDCs ``host`` service.  For example, if
-the master KDC were called ``kerberos.mit.edu``, and you had slave KDC
-named ``kerberos-1.mit.edu``, you would type the following::
+On the master 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
+slave KDC named ``kerberos-1.mit.edu``, you would type the following::
 
     shell% /usr/local/bin/kadmin
     kadmin: addprinc -randkey host/kerberos.mit.edu
@@ -24,119 +24,83 @@
     NOTICE: no policy specified for "host/kerberos-1.mit.edu at ATHENA.MIT.EDU"; assigning "default"
     Principal "host/kerberos-1.mit.edu at ATHENA.MIT.EDU" created.
 
-It is not actually necessary to have the master KDC server in the
-Kerberos database, but it can be handy if:
+It is not strictly necessary to have the master 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 slaves.
 
-   - anyone will be logging into the machine as something other than
-     root
-   - you want to be able to swap the master KDC with one of the slaves
-     if necessary.
-
 Next, extract ``host`` random keys for all participating KDCs and
-store them in the default keytab file which is needed to decrypt
-tickets.  Ideally, you should extract each keytab locally on its own
-KDC.  If this is not feasible, you should use an encrypted session to
-send them across the network.  To extract a keytab on a KDC called
-``kerberos.mit.edu``, you would execute the following command::
+store them in each host's default keytab file.  Ideally, you should
+extract each keytab locally on its own KDC.  If this is not feasible,
+you should use an encrypted session to send them across the network.
+To extract a keytab on a slave KDC called ``kerberos-1.mit.edu``, you
+would execute the following command::
 
-    kadmin: ktadd host/kerberos.mit.edu
-    kadmin: Entry for principal host/kerberos.mit.edu at ATHENA.MIT.EDU with
-         kvno 1, encryption type DES-CBC-CRC added to keytab WRFILE:/etc/krb5.keytab.
+    kadmin: ktadd host/kerberos-1.mit.edu
+    Entry for principal host/kerberos-1.mit.edu with kvno 2, encryption
+        type aes256-cts-hmac-sha1-96 added to keytab FILE:/etc/krb5.keytab.
+    Entry for principal host/kerberos-1.mit.edu with kvno 2, encryption
+        type aes128-cts-hmac-sha1-96 added to keytab FILE:/etc/krb5.keytab.
+    Entry for principal host/kerberos-1.mit.edu with kvno 2, encryption
+        type des3-cbc-sha1 added to keytab FILE:/etc/krb5.keytab.
+    Entry for principal host/kerberos-1.mit.edu with kvno 2, encryption
+        type arcfour-hmac added to keytab FILE:/etc/krb5.keytab.
 
-    kadmin: ktadd -k /tmp/krb5.keytab host/kerberos-1.mit.edu
-    kadmin: Entry for principal host/kerberos-1.mit.edu at ATHENA.MIT.EDU with
-         kvno 1, encryption type DES-CBC-CRC added to keytab WRFILE:/tmp/krb5.keytab.
 
-    kadmin:
-
-Move the file /tmp/krb5.keytab (via scp) onto the slave KDC
-(``kerberos-1.mit.edu``) into exactly the same location as on the
-master (default is ``/etc/krb5.keytab``).  Remove the temporary copy
-``/tmp/krb5.keytab`` from the master.
-
-
 Configuring the slave
 ---------------------
 
-By default, the propagation is done on the entire content of the
-master's database.  That is, even special principals (like
-``K/M at FOOBAR.COM``) will be dumped and copied to the slave KDCs.  Pay
-attention there: it means that configuration files, as also specific
-files (like ACLs and :ref:`stash_definition`) must be copied to the
-slave hosts too.  Copying only a part of it will result in a bulky
-situation.  If you forget to copy the stash file for example, the KDC
-daemon on the slave host will not be able to access the propagated
-database because of missing master key.  Before connecting to the
-slave, you will copy all minimum required files from the master for
-the slave system to work.  Initially, it concerns (See
-:ref:`mitK5defaults` for the recommended default locations for these
-files):
+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 slave (see
+:ref:`mitK5defaults` for the default locations for these files):
 
-   • krb5.conf
-   • kdc.conf
-   • kadm5.acl
-   • master key stash file
+* krb5.conf
+* kdc.conf
+* kadm5.acl
+* master key stash file
 
-Connect to the slave, *kerberos-1.mit.edu*. Move the copied files into
-their appropriate directories (exactly like on the master KDC).
+Move the copied files into their appropriate directories, exactly as
+on the master KDC.  kadm5.acl is only needed to allow a slave to swap
+with the master KDC.
 
-You will now initialize the slave database::
-
-    shell% /usr/local/sbin/kdb5_util create
-
-.. caution:: You will use :ref:`kdb5_util(8)` but without exporting
-             the stash file (-s argument), thus avoiding the
-             obliteration of the one you just copied from the master.
-
-When asking for the database Master Password, type in anything you
-want.  The whole dummy database will be erased upon the first
-propagation from master.
-
 The database is propagated from the master KDC to the slave KDCs via
-the :ref:`kpropd(8)` daemon.  You must explicitly specify the clients
-that are allowed to provide Kerberos dump updates on the slave machine
-with a new database.  The kpropd.acl file serves as the access control
-list for the kpropd service.  This file is typically resides in
-krb5kdc local directory.  Since in our case the updates should only
-come from ``kerberos.mit.edu`` server, then the file's contents would
-be::
+the :ref:`kpropd(8)` daemon.  You must explicitly specify the
+principals which are allowed to provide Kerberos dump updates on the
+slave machine with a new database.  Create a file named kpropd.acl in
+the KDC state directory containing the ``host`` principals for each of
+the KDCs:
 
-     host/kerberos.mit.edu at ATHENA.MIT.EDU
+    host/kerberos.mit.edu at ATHENA.MIT.EDU
+    host/kerberos-1.mit.edu at ATHENA.MIT.EDU
 
-.. note:: If you expect that the primary and secondary KDCs will be
-          switched at some point of time, it is recommended to list
-          the host principals from *all* participating KDC servers in
-          kpropd.acl files on *all* of these servers.
+.. note:: If you expect that the master and slave 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
+          slave KDCs.
 
-Then, add the following line to ``/etc/inetd.conf`` file on each KDC
+Then, add the following line to ``/etc/inetd.conf`` on each KDC
 (Adjust the path to kpropd)::
 
     krb5_prop stream tcp nowait root /usr/local/sbin/kpropd kpropd
-    eklogin stream tcp nowait root  /usr/local/sbin/klogind klogind -5 -c -e
 
-You also need to add the following lines to ``/etc/services`` on each
-KDC (assuming that default ports are used)::
+You also need to add the following line to ``/etc/services`` on each
+KDC, if it is not already present (assuming that the default port is
+used)::
 
-    kerberos        88/udp      kdc       # Kerberos authentication (udp)
-    kerberos        88/tcp      kdc       # Kerberos authentication (tcp)
     krb5_prop       754/tcp               # Kerberos slave propagation
-    kerberos-adm    749/tcp               # Kerberos 5 admin/changepw (tcp)
-    kerberos-adm    749/udp               # Kerberos 5 admin/changepw (udp)
 
 Restart inetd daemon.
 
-Alternatively, start :ref:`kpropd(8)` as a stand-alone daemon "kpropd
--S" or, if the default locations must be overridden::
+Alternatively, start :ref:`kpropd(8)` as a stand-alone daemon with
+``kpropd -S``.
 
-    shell% /usr/local/sbin/kpropd -S -a path-to-kpropd.acl -r ATHENA.MIT.EDU -f /var/krb5kdc/from_master
-
-    waiting for a kprop connection
-
 Now that the slave KDC is able to accept database propagation, you’ll
 need to propagate the database from the master server.
 
-NOTE: Do not start slave KDC - you still do not have a copy of the
-master's database.
+NOTE: Do not start the slave KDC yet; you still do not have a copy of
+the master's database.
 
 
 Feedback

Modified: trunk/doc/rst_source/krb_admins/install_kdc/switch_master_slave.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/install_kdc/switch_master_slave.rst	2012-02-27 18:31:50 UTC (rev 25716)
+++ trunk/doc/rst_source/krb_admins/install_kdc/switch_master_slave.rst	2012-02-27 23:29:09 UTC (rev 25717)
@@ -17,24 +17,17 @@
 #. Kill the kadmind process.
 #. Disable the cron job that propagates the database.
 #. Run your database propagation script manually, to ensure that the
-   slaves all have the latest copy of the database.  (See Propagate
-   the Database to Each Slave KDC.)  If there is a need to preserve
-   per-principal policy information from the database, you should do a
-   "kdb5_util dump -ov" in order to preserve that information and
-   propogate that dump file securely by some means to the slave so
-   that its database has the correct state of the per-principal policy
-   information.
+   slaves all have the latest copy of the database (see
+   :ref:`kprop_to_slaves`).
 
 On the *new* master KDC:
 
-#. Create a database keytab.  (See Create a kadmind Keytab (optional).)
-#. Start the :ref:`kadmind(8)` daemon.  (See Start the Kerberos
-   Daemons.)
-#. Set up the cron job to propagate the database.  (See Propagate the
-   Database to Each Slave KDC.)
-#. Switch the CNAMEs of the old and new master KDCs.  (If you don't do
+#. Start the :ref:`kadmind(8)` daemon (see :ref:`start_kdc_daemons`).
+#. Set up the cron job to propagate the database (see
+   :ref:`kprop_to_slaves`).
+#. Switch the CNAMEs of the old and new master 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.)
+   client machine in your Kerberos realm.
 
 
 Feedback



More information about the cvs-krb5 mailing list