Revised KDC propagation section.
authorZhanna Tsitkov <tsitkova@mit.edu>
Fri, 21 Oct 2011 23:15:27 +0000 (23:15 +0000)
committerZhanna Tsitkov <tsitkova@mit.edu>
Fri, 21 Oct 2011 23:15:27 +0000 (23:15 +0000)
Removed rst files that are not used any more.

git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@25406 dc483132-0cff-0310-8789-dd5450dbe970

16 files changed:
doc/rst_source/krb_admins/conf_files/salts.rst [deleted file]
doc/rst_source/krb_admins/database/db_policies/del_pol.rst [deleted file]
doc/rst_source/krb_admins/database/db_princs/delete_princ.rst [deleted file]
doc/rst_source/krb_admins/install.rst
doc/rst_source/krb_admins/install_kdc/admins_to_acl.rst
doc/rst_source/krb_admins/install_kdc/admins_to_db.rst
doc/rst_source/krb_admins/install_kdc/create_db.rst
doc/rst_source/krb_admins/install_kdc/index.rst
doc/rst_source/krb_admins/install_kdc/kadmind_kt.rst
doc/rst_source/krb_admins/install_kdc/kdc_prop_slave.rst
doc/rst_source/krb_admins/install_kdc/krb_daemon.rst
doc/rst_source/krb_admins/install_kdc/mod_conf.rst
doc/rst_source/krb_admins/install_kdc/slave_install.rst
doc/rst_source/krb_admins/install_kdc/slave_intall_fin.rst [deleted file]
doc/rst_source/krb_admins/install_kdc/stash_file_def.rst [new file with mode: 0644]
doc/rst_source/krb_admins/troubleshoot.rst

diff --git a/doc/rst_source/krb_admins/conf_files/salts.rst b/doc/rst_source/krb_admins/conf_files/salts.rst
deleted file mode 100644 (file)
index d391702..0000000
+++ /dev/null
@@ -1,23 +0,0 @@
-.. _salts_label:
-
-Salts
-=========
-
-Your Kerberos key is derived from your password. To ensure that people who happen to pick the same password do not have the same key, Kerberos 5 incorporates more information into the key using something called a salt. The supported values for salts are as follows.
-
-================= ============================================
-normal            default for Kerberos Version 5
-v4                the only type used by Kerberos Version 4, no salt
-norealm           same as the default, without using realm information
-onlyrealm         uses only realm information as the salt
-afs3              AFS version 3, only used for compatibility with Kerberos 4 in AFS
-special           only used in very special cases; not fully supported 
-================= ============================================
-
---------------
-
-Feedback:
-
-Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___conf_files
-
-
diff --git a/doc/rst_source/krb_admins/database/db_policies/del_pol.rst b/doc/rst_source/krb_admins/database/db_policies/del_pol.rst
deleted file mode 100644 (file)
index 97e3e65..0000000
+++ /dev/null
@@ -1,27 +0,0 @@
-Deleting policies
-========================
-
-To delete a policy, use the kadmin *delete_policy* command, which requires the "delete" administrative privilege. The syntax is::
-
-     delete_policy [-force] policy_name
-     
-
-The *delete_policy* command has the alias **delpol**. It prompts for confirmation before deletion. 
-
-For example::
-
-     kadmin: delete_policy guests
-     Are you sure you want to delete the policy "guests"?
-     (yes/no): yes
-     kadmin:
-     
-.. note::  You must cancel the policy from *all* principals before deleting it. The *delete_policy* command will fail if it is in use by any principals. 
-
-
-     
-------------
-
-Feedback:
-
-Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___db_policies
-
diff --git a/doc/rst_source/krb_admins/database/db_princs/delete_princ.rst b/doc/rst_source/krb_admins/database/db_princs/delete_princ.rst
deleted file mode 100644 (file)
index b656115..0000000
+++ /dev/null
@@ -1,9 +0,0 @@
-Deleting principals
-==============================
-
-To delete a principal, use the kadmin *delete_principal* command, which requires the "delete" administrative privilege. The syntax is::
-
-     delete_principal [-force] principal
-
-See :ref:`delete_principal` for details.
-     
index aed062c089c4f79c45795318372497c10a94aa07..05d10297678225364adf39b0bf13416aa9881f5e 100644 (file)
@@ -4,11 +4,6 @@ Installation guide
 .. note:: This document was copied from **Kerberos V5 Installation Guide** with minor changes. Currently it is under review. Please, send your feedback, corrections and additions to krb5-bugs@mit.edu. Your contribution is greatly appreciated.
 
 
-The sections of this chapter describe procedures for installing Kerberos V5 on:
-
-#. The KDCs
-#. UNIX client machines
-#. UNIX Application Servers 
 
 Contents
 ---------
@@ -27,6 +22,7 @@ Additional references
 
 
 #. Debian Setting up of Kerberos <http://techpubs.spinlocksolutions.com/dklar/kerberos.html>_
+#. Solaris Configuring the Kerberos Service <http://download.oracle.com/docs/cd/E19253-01/816-4557/6maosrjv2/index.html >_
 
 ------------------
 
index 8c805de7ef608495a8e72261391480ad8bf6ebef..1d16bb5403f391fd70c9d8be91cf8a524b00b3da 100644 (file)
@@ -3,49 +3,51 @@
 Add administrators to the ACL file
 ======================================
 
-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 kadmind daemon to control which principals may view and make privileged modifications to the Kerberos database files. The filename should match the value you have set for "acl_file" (see :ref:`kdc_realms`) in your kdc.conf file. The default file name is /usr/local/var/krb5kdc/kadm5.acl.
+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 *kadmind* daemon to control which principals may view and make privileged modifications to the Kerberos database files. 
+The filename should match the value you have set for "acl_file" (see :ref:`kdc_realms`) in your *kdc.conf* file. 
+The default file name is /usr/local/var/krb5kdc/kadm5.acl (See :ref:`mitK5defaults`).
 
-The format of the file is:
+The format of the file is::
 
-     Kerberos_principal      permissions     [target_principal]        [restrictions]
+     kerberos_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. target_principal can also include backreferences to Kerberos_principal, in which "\*number" matches the component number in the Kerberos_principal.
-
-Note: a common use of an admin instance is so you can grant separate permissions (such as administrator access to the Kerberos database) to a separate Kerberos principal. For example, the user *joeadmin* might have a principal for his administrative use, called *joeadmin/admin*. This way, *joeadmin* would obtain *joeadmin/admin* tickets only when he actually needs to use those permissions.
-
-The permissions are represented by single letters; UPPER-CASE letters represent negative permissions. The permissions are:
-
-==== ==========================================================
-a    allows the addition of principals or policies in the database. 
-A    disallows the addition of principals or policies in the database. 
-c    allows the changing of passwords for principals in the database. 
-C    disallows the changing of passwords for principals in the database. 
-d    allows the deletion of principals or policies in the database. 
-D    disallows the deletion of principals or policies in the database. 
-i    allows inquiries to the database. 
-I    disallows inquiries to the database. 
-l    allows the listing of principals or policies in the database. 
-L    disallows the listing of principals or policies in the database. 
-m    allows the modification of principals or policies in the database. 
-M    disallows the modification of principals or policies in the database. 
-s    allows the explicit setting of the key for a principal 
-S    disallows the explicit setting of the key for a principal 
-\*   All privileges (admcil). 
-x    All privileges (admcil); identical to "\*". 
-==== ==========================================================
+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. 
+*target_principal* can also include backreferences to *kerberos_principal*, in which "\*number" matches the component number in the *kerberos_principal*.
+
+.. note::  A common use of an admin instance is so you can grant separate permissions 
+           (such as administrator access to the Kerberos database) to a separate *kerberos principal*. 
+           For example, the user *joeadmin* might have a principal for his administrative use, called *joeadmin/admin*. 
+           This 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 permissions are:
+
+   ==== ==========================================================
+   a    [Dis]allows the addition of principals or policies in the database. 
+   c    [Dis]allows the changing of passwords for principals in the database. 
+   d    [Dis]allows the deletion of principals or policies in the database. 
+   i    [Dis]allows inquiries to the database. 
+   l    [Dis]allows the listing of principals or policies in the database. 
+   m    [Dis]allows the modification of principals or policies in the database. 
+   s    [Dis]allows the explicit setting of the key for a principal 
+   \*   All privileges (admcil). 
+   x    All privileges (admcil); identical to "\*". 
+   ==== ==========================================================
 
 The 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 *addprinc* and *modprinc* commands. 
--clearpolicy          policy is forced to clear 
--policy *pol*         policy is forced to be *pol* 
-expire *time*
-pwexpire *time*
-maxlife *time*
-maxrenewlife *time*    associated value will be forced to MIN(*time*, requested value) 
-==================== ===============================
+   ====================== ===============================
+   [+\|-]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. 
+   -clearpolicy            policy is forced to clear 
+   -policy *pol*           policy is forced to be *pol* 
+   expire *time*           associated value will be forced to MIN(*time*, requested value)
+   pwexpire *time*         associated value will be forced to MIN(*time*, requested value)
+   maxlife *time*          associated value will be forced to MIN(*time*, requested value) 
+   maxrenewlife *time*     associated value will be forced to MIN(*time*, requested value) 
+   ====================== ===============================
 
 The above flags act as restrictions on any add or modify operation which is allowed due to that ACL line.
 
@@ -63,7 +65,18 @@ Here is an example of a *kadm5.acl* file.
      */admin@EXAMPLE.COM * -maxlife 9h -postdateable
      
 
-In the above file, any principal in the *ATHENA.MIT.EDU* realm with an admin instance has all administrative privileges. The user *joeadmin* has all permissions with his admin instance, *joeadmin\/admin\@ATHENA.MIT.EDU* (matches the first line). He has no permissions at all with his null instance, *joeadmin\@ATHENA.MIT.EDU* (matches the second line). His root instance has inquire and list permissions with any other principal that has the instance root. Any principal in *ATHENA.MIT.EDU* can inquire, list, or change the password of their admin instance, but not any other admin instance. Any principal in the realm *ATHENA.MIT.EDU* (except for *joeadmin\@ATHENA.MIT.EDU*, as mentioned above) has inquire privileges. Finally, any principal with an admin instance in *EXAMPLE.COM* has all permissions, but any principal that they create or modify will not be able to get postdateable tickets or tickets with a life of longer than 9 hours. 
+In the above file, any principal in the *ATHENA.MIT.EDU* realm with an *admin* instance has *all* administrative privileges. 
+
+The user *joeadmin* has *all* permissions with his *admin* instance, *joeadmin\/admin\@ATHENA.MIT.EDU* (matches the first line). 
+He has no permissions at all with his *null* instance, *joeadmin\@ATHENA.MIT.EDU* (matches the second line). 
+His root instance has *inquire* and *list* permissions with any other principal that has the instance root. 
+
+Any principal in *ATHENA.MIT.EDU* can *inquire, list*, or *change the password* of their *admin* instance, but not any other admin instance. 
+
+Any principal in the realm *ATHENA.MIT.EDU* (except for *joeadmin\@ATHENA.MIT.EDU*, as mentioned above) has *inquire* privileges. 
+
+Finally, any principal with an *admin* instance in *EXAMPLE.COM* has *all* permissions, 
+but any principal that they create or modify will not be able to get *postdateable* tickets or tickets with a life of longer than 9 hours. 
 
 ------------
 
index 754d767ae42f74b677c88c56ddd032de2ce8647b..51f652555ad99871bc5a18b36e25dfa2eb3cc096 100644 (file)
@@ -1,10 +1,24 @@
 Add administrators to the Kerberos database
 ===============================================
 
-Next you need to add administrative principals to the Kerberos database. (You must add at least one now.) To do this, use *kadmin.local* on the master KDC. The administrative principals you create should be the ones you added to the ACL file. (See :ref:`admin_acl_label`.) In the following example, the administration principal *admin/admin* is created::
+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.)
+
+The administrative principals you create should be the ones you added to the ACL file. (See :ref:`admin_acl_label`.) 
+
+In the following example, the administrative principal *admin/admin* is created::
 
      shell% /usr/local/sbin/kadmin.local
+
      kadmin.local: addprinc admin/admin@ATHENA.MIT.EDU
+
      NOTICE: no policy specified for "admin/admin@ATHENA.MIT.EDU";
      assigning "default".
      Enter password for principal admin/admin@ATHENA.MIT.EDU:  <= Enter a password.
index 31932f469da37203a4c2820fa12b8e7642558105..b271a7696155e23f6f5b90ec9cd3e88d82f90a43 100644 (file)
@@ -3,16 +3,25 @@
 Create the database
 =========================
 
-You will use the :ref:`kdb5_util(8)` command on the master KDC to create the Kerberos database and the optional stash file.
-The stash file is a local copy of the master key that resides in encrypted form on the KDC's local disk. The stash file is used to authenticate the KDC to itself automatically before starting the *kadmind* and *krb5kdc* daemons (e.g., as part of the machine's boot sequence). The stash file, like the keytab file (see :ref:`kt_file_label` for more information) is a potential point-of-entry for a break-in, and if compromised, would allow unrestricted access to the Kerberos database. If you choose to install a stash file, it should be readable only by root, and should exist only on the KDC's local disk. The file should not be part of any backup of the machine, unless access to the backup data is secured as tightly as access to the master password itself.
+You will use the :ref:`kdb5_util(8)` command on the master KDC to create the Kerberos database and the optional :ref:`stash_definition`.
 
-.. note:: If you choose not to install a stash file, the KDC will prompt you for the master key each time it starts up. This means that the KDC will not be able to start automatically, such as after a system reboot.
+.. note:: If you choose not to install a stash file, the KDC will prompt you for the master key each time it starts up. 
+          This means that the KDC will not be able to start automatically, such as after a system reboot.
 
-Note that kdb5_util 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.)
+Note that *kdb5_util* 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.)
 
-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::
+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::
 
      shell% /usr/local/sbin/kdb5_util create -r ATHENA.MIT.EDU -s
+
      Initializing database '/usr/local/var/krb5kdc/principal' for realm 'ATHENA.MIT.EDU',
      master key name 'K/M@ATHENA.MIT.EDU'
      You will be prompted for the database Master Password.
@@ -22,12 +31,14 @@ The following is an example of how to create a Kerberos database and stash file
      shell%
      
 
-This will create five files in the directory specified in your *kdc.conf* file (The default location is */usr/local/var/krb5kdc* directory): 
+This will create five files in the directory specified in your *kdc.conf* 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 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. 
+- 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. 
 
 For more information on administrating Kerberos database see :ref:`db_operations_label`.
 
index 43ec43872c56aa8d9cd1571263e453b96478fc2f..e6ef8e16000cd2340a1c68d26b0ee7040a7714cb 100644 (file)
@@ -4,15 +4,45 @@
 Installing KDCs
 ======================
 
-The Key Distribution Centers (KDCs) issue Kerberos tickets. Each KDC contains a copy of the Kerberos database. The master KDC contains the master copy of the database, which it propagates to the slave KDCs at regular intervals. All database changes (such as password changes) are made on the master KDC.
+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. 
 
-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. 
+.. warning:: 
+          - The Kerberos system heavily relies on the timestamps, so all Kerberos exchange participants should be rather well synchronized.
 
+          - 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.
+
+
+
+Install and configure the master KDC
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Install Kerberos either from the OS-provided packages or from the source (See :ref:`do_build`).
+
+.. note:: For the purpose of this document we will use the following names
+          ::
+
+          - 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
+  
+          See :ref:`mitK5defaults` for the default names and locations of the relevant to this topic files.
+          Adjust the names and paths to your system environment.
 
-The installation procedure will require you to go back and forth a couple of times between the master KDC and each of the slave KDCs. The first few steps must be done on the master KDC. 
 
-Install the Master KDC
-~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. toctree::
    :maxdepth: 1
@@ -24,7 +54,6 @@ Install the Master KDC
    kadmind_kt.rst
    krb_daemon.rst
 
-You are now ready to start configuring the slave KDCs. 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. 
 
 Install the Slave KDCs
 ~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -33,35 +62,17 @@ Install the Slave KDCs
    :maxdepth: 1
 
    slave_install.rst
-
-
-Now that the slave KDCs are able to accept database propagation, you'll need to propagate the database to each of them
-
-Back on the Master KDC
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. toctree::
-   :maxdepth: 1
-
    kdc_prop_slave.rst
 
+Once your KDCs are set up and running, you are ready to use kadmin 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_label`. 
+The keytab is generated by running kadmin and issuing the :ref:`ktadd` command. 
 
-Now that the slave KDCs have copies of the Kerberos database, you can create stash files for them and start the krb5kdc daemon. 
-
-Finish installing the Slave KDCs
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. toctree::
-   :maxdepth: 1
-
-   slave_intall_fin.rst
-
-Once your KDCs are set up and running, you are ready to use kadmin 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_label`. The keytab is generated by running kadmin and issuing the ktadd command. 
-
-
-.. note:: To limit the possibility that your Kerberos database could be compromised, MIT recommends that each KDC be a dedicated host, 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. 
 
-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 master KDC has a disk crash. See the following section for the instructions.
+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 master KDC has a disk crash. 
+See the following section for the instructions.
 
 Switching Master and Slave KDCs
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
index 4f98baac98e5a0eb1903ce4f0bba939dd14dc55f..2891396508c73cc9619457ef4e54a23e9ce9a8ad 100644 (file)
@@ -4,9 +4,15 @@ Create a kadmind keytab
 .. note:: This operation is optional.
 
 
-The *kadmind keytab* is the key that the legacy admininstration daemons *kadmind4* and *v5passwdd* will use to decrypt administrators' or clients' Kerberos tickets to determine whether or not they should have access to the database. You need to create the kadmin keytab with entries for the principals *kadmin/admin* and *kadmin/changepw*. (These principals are placed in the Kerberos database automatically when you create it.) To create the kadmin keytab, run *kadmin.local* and use the :ref:`ktadd` command, as in the following example::
+The *kadmind keytab* is the key that the legacy admininstration daemons *kadmind4* and *v5passwdd* 
+will use to decrypt administrators' or clients' Kerberos tickets to determine whether or not 
+they should have access to the database. 
+You need to create the kadmin keytab with entries for the principals *kadmin/admin* and *kadmin/changepw*. 
+(These principals are placed in the Kerberos database automatically when you create it.) 
+To create the *kadmin* keytab, run *kadmin.local* and use the :ref:`ktadd` command, as in the following example::
+
+     shell% /usr/local/sbin/admin.local
 
-     shell% /usr/local/sbin/kadmin.local
      kadmin.local: ktadd -k /usr/local/var/krb5kdc/kadm5.keytab kadmin/admin kadmin/changepw
       Entry for principal kadmin/admin with kvno 5, encryption
        type Triple DES cbc mode with HMAC/sha1 added to keytab
@@ -21,10 +27,10 @@ The *kadmind keytab* is the key that the legacy admininstration daemons *kadmind
        encryption type DES cbc mode with CRC-32 added to keytab
        WRFILE:/usr/local/var/krb5kdc/kadm5.keytab.
      kadmin.local: quit
-     shell%
      
 
-As specified in the *-k* argument, :ref:`ktadd` will save the extracted keytab as */usr/local/var/krb5kdc/kadm5.keytab* (This is also the default location for the admin keytab). The filename you use must be the one specified in your *kdc.conf* file. 
+As specified in the *-k* argument, :ref:`ktadd` will save the extracted keytab as */usr/local/var/krb5kdc/kadm5.keytab* 
+(This is also the default location for the admin keytab). The filename you use must be the one specified in your *kdc.conf* file. 
 
 
 ------------
index aaf9441b311320c488e218e6b29acfe43ef00d83..8dc712ab5071911e7fa855e87acbc1e98db35f9f 100644 (file)
@@ -1,20 +1,18 @@
 Propagate the database to each slave KDC
 ===========================================
 
-First, create a dump of the database on the master KDC, as follows::
+First, stop the *kadmin* service.
 
-     shell% /usr/local/sbin/kdb5_util dump /usr/local/var/krb5kdc/slave_datatrans
-     shell%
-     
+Next, create a dump file of the database on the master KDC, as follows::
 
-Next, you need to manually propagate the database to each slave KDC, as in the following example::
+      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 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
 
-     shell% /usr/local/sbin/kprop -f /usr/local/var/krb5kdc/slave_datatrans kerberos-2.mit.edu
-     Database propagation to kerberos-2.mit.edu: SUCCEEDED
-     
 
 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. 
 
@@ -38,15 +36,29 @@ You will need to set up a cron job to run this script at the intervals you decid
 The dump can also be used as a save file. 
 Once the operation succeeded, connect to slaves and start thier KDCs.
 
+Now that the slave KDC has a copy of the Kerberos database, you can start the *krb5kdc* daemon::
+
+    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 kadmin 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_label`. 
+The keytab is generated by running kadmin and issuing the ktadd command.
 
 
 Propagation failed?
 ------------------------
 
 
-If propagation failed with a loud::
+If propagation failed with a loud:
    
-     kprop: Connection refused in call to connect while opening connection
+.. _prop_failed_start: 
+
+.. error:: kprop: Connection refused in call to connect while opening connection
 
 it means that *kprop* did not manage to contact *kpropd* on the remote slave KDC.
 
@@ -61,42 +73,29 @@ or register *kprop* as a potential services to *inetd*.
 To register *kpropd*, it depends on whether your are using inetd or its more sophisticated equivalent *xinetd*.
 First, edit */etc/services*, and look for *kprop* service; the line should look like this::
 
-   /etc/services
-
    kprop 754/tcp
 
 If you did not find it, please add it to the bottom of the file. Save and close.
 
 
-inetd.conf
-~~~~~~~~~~~~~~~
-
-Now we should edit *inetd.conf* (see below for *xinetd*), and add this line::
+Now we should edit */etc/inetd.conf* (see below for *xinetd*), and add the following line to setup the database propagation daemon ::
 
-    /etc/inetd.conf
-
-    kprop stream tcp nowait root /usr/sbin/kpropd kpropd
+    kprop stream tcp nowait root /usr/local/sbin/kpropd kpropd
 
 Please note that the path to executable may vary from one system to another. Save and close *inetd.conf*, and restart *inetd*::
 
+    \# /etc/rc.d/inetd restart
 
-    # /etc/rc.d/inetd restart
-
-xinetd.conf
-~~~~~~~~~~~~~~~~~
 
-All config file for *xinetd* resides in the */etc/xinetd.d* directory. We must add the *kprop* config file, so that *xinetd* knows its existence::
-
-Create and edit the *kpropd* file */etc/xinetd.d/kpropd* ::
-
-    /etc/xinetd.d/kpropd
+All config file for *xinetd* resides in the */etc/xinetd.d* directory. We must add the *kprop* config file, so that *xinetd* knows its existence.
+Create and edit the */etc/xinetd.d/kpropd* file ::
 
     service kprop
     {
     socket_type = stream
     wait = no
     user = root
-    server = /usr/sbin/kpropd
+    server = /usr/local/sbin/kpropd
     only_from = 0.0.0.0 # Allow anybody to connect to it. Restrictions may apply here.
     log_on_success = PID HOST EXIT DURATION
     log_on_failure = PID HOST
@@ -104,11 +103,13 @@ Create and edit the *kpropd* file */etc/xinetd.d/kpropd* ::
 
 Save and close the file, and restart *xinetd*::
 
-    # /etc/init.d/xinetd restart
+    \# /etc/init.d/xinetd restart
 
 You should now be able to propagate the dumps from master to slave.
 
 
+.. _prop_failed_end: 
+
 
 
 ------------
index 1d0f038ee260e20ee8719c17aa49b98378e97e62..c368fcf2218f163967cdb605d6e6b06c77b044a3 100644 (file)
@@ -1,15 +1,21 @@
-Start the Kerberos daemons on the Master KDC
+Start the Kerberos daemons on the master KDC
 ===============================================
 
-At this point, you are ready to start the Kerberos daemons on the Master KDC. To do so, type::
+At this point, you are ready to start the Kerberos KDC and administrative daemons on the Master KDC. To do so, type::
 
      shell% /usr/local/sbin/krb5kdc
      shell% /usr/local/sbin/kadmind
      
 
-Each daemon will fork and run in the background. Assuming you want these daemons to start up automatically at boot time, you can add them to the KDC's */etc/rc* or */etc/inittab* file. You need to have a stash file in order to do this.
+Each server daemon will fork and run in the background. 
 
-You can verify that they started properly by checking for their startup messages in the logging locations you defined in */etc/krb5.conf*. (See :ref:`logging`) For example::
+.. note:: Assuming you want these daemons to start up automatically at boot time, 
+          you can add them to the KDC's */etc/rc* or */etc/inittab* file. 
+          You need to have a :ref:`stash_definition` in order to do this.
+
+You can verify that they started properly by checking for their startup messages in the logging locations 
+you defined in */etc/krb5.conf*. (See :ref:`logging`).
+For example::
 
      shell% tail /var/log/krb5kdc.log
      Dec 02 12:35:47 beeblebrox krb5kdc[3187](info): commencing operation
@@ -19,6 +25,13 @@ You can verify that they started properly by checking for their startup messages
 
 Any errors the daemons encounter while starting will also be listed in the logging output. 
 
+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:
index 474cae16f0c797f98560cfd1a6956a37d5f31813..2e0e1d20f216b4640465115f068f9f60a1d9cc6b 100644 (file)
@@ -1,17 +1,29 @@
 Edit the configuration files
 ==================================
 
-Modify the configuration files, */etc/krb5.conf* and */usr/local/var/krb5kdc/kdc.conf* to reflect the correct information (such as the hostnames and realm name) for your realm. MIT recommends that you keep *krb5.conf* in */etc*.
+Modify the configuration files, *krb5.conf* and *kdc.conf* to reflect the correct information
+(such as domain-realm mappings and Kerberos servers names) for your realm. 
+(See :ref:`mitK5defaults` for the recommended default locations for these files). 
 
-Most of the tags in the configuration have default values that will work well for most sites. There are some tags in the *krb5.conf* file whose values must be specified, and this section will explain those. For more information on Kerberos V5 configuration files see :ref:`krb5.conf` and :ref:`kdc.conf`.
+Most of the tags in the configuration have default values that will work well for most sites. 
+There are some tags in the *krb5.conf* file whose values must be specified, 
+and this section will explain those. 
+For more information on Kerberos V5 configuration files see :ref:`krb5.conf` and :ref:`kdc.conf`.
 
 *krb5.conf*
 -------------
 
-If you are not using DNS TXT records (see :ref:`mapping_hn_label`), you must specify the *default_realm* in the :ref:`libdefaults` section. If you are not using DNS SRV records (see :ref:`kdc_hn_label`), you must include the *kdc* tag for each *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 *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 the KDC and kadmind will generate logging output.
+If you are not using DNS TXT records (see :ref:`mapping_hn_label`), you must specify the *default_realm* in the :ref:`libdefaults` section.
+If you are not using DNS SRV records (see :ref:`kdc_hn_label`), you must include the *kdc* tag for each *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 the KDC and *kadmind* will generate logging output.
+
 
 An example krb5.conf file::
 
+
      [libdefaults]
          default_realm = ATHENA.MIT.EDU
      
@@ -21,13 +33,31 @@ An example krb5.conf file::
                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
      
+
+An example kdc.conf file::
+
+     [kdcdefaults]
+         kdc_ports = 88,750
+     
+     [realms]
+         ATHENA.MIT.EDU = {
+             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
+         }
+     
+
+Replace *ATHENA.MIT.EDU* and *kerberos.mit.edu*  with the name of your Kerberos realm and server respectively.
+
 ------------
 
 Feedback:
index 58192dd65ce369452bfec266db16da79fdc1f667..e831d5d00963e3d8756b307e59c5895be3b2db5d 100644 (file)
 .. _slave_host_key_label:
 
-Create host keys for the Slave KDCs
+
+
+Setting up slave KDCs
 ========================================
 
-Each KDC needs a host principal in the Kerberos database. You can enter these from any host, once the *kadmind* daemon is running. For example, if your master KDC were called *kerberos.mit.edu*, and you had two KDC slaves named *kerberos-1.mit.edu* and *kerberos-2.mit.edu*, you would type the following::
+Prep work on the master side.
+-------------------------------------------
+
+Each KDC needs a *host* keys 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::
 
      shell% /usr/local/sbin/kadmin
      kadmin: addprinc -randkey host/kerberos.mit.edu
-     NOTICE: no policy specified for "host/kerberos.mit.edu@ATHENA.MIT.EDU";
-     assigning "default"
+     NOTICE: no policy specified for "host/kerberos.mit.edu@ATHENA.MIT.EDU"; assigning "default"
      Principal "host/kerberos.mit.edu@ATHENA.MIT.EDU" created.
+
      kadmin: addprinc -randkey host/kerberos-1.mit.edu
-     NOTICE: no policy specified for "host/kerberos-1.mit.edu@ATHENA.MIT.EDU";
-     assigning "default"
+     NOTICE: no policy specified for "host/kerberos-1.mit.edu@ATHENA.MIT.EDU"; assigning "default"
      Principal "host/kerberos-1.mit.edu@ATHENA.MIT.EDU" created.
-     kadmin: addprinc -randkey host/kerberos-2.mit.edu
-     NOTICE: no policy specified for "host/kerberos-2.mit.edu@ATHENA.MIT.EDU";
-     assigning "default"
-     Principal "host/kerberos-2.mit.edu@ATHENA.MIT.EDU" created.
-     kadmin:
-     
-
-It is not actually necessary to have the master KDC server in the Kerberos database, but it can be handy if:
 
-- 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. 
 
+It is not actually necessary to have the master KDC server in the Kerberos database, but it can be handy if:
 
-Extract host keytabs for the KDCs
-=====================================
+   - 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. 
 
-Each KDC (including the master) needs a keytab 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::
+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::
 
      kadmin: ktadd host/kerberos.mit.edu
      kadmin: Entry for principal host/kerberos.mit.edu@ATHENA.MIT.EDU with
-          kvno 1, encryption type DES-CBC-CRC added to keytab
-          WRFILE:/etc/krb5.keytab.
+          kvno 1, encryption type DES-CBC-CRC added to keytab WRFILE:/etc/krb5.keytab.
+
+     kadmin: ktadd -k /tmp/krb5.keytab host/kerberos-1.mit.edu
+     kadmin: Entry for principal host/kerberos-1.mit.edu@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. 
 
-.. note:: Principal must exist in the Kerberos database in order to extract the keytab.
 
-Set Up the Slave KDCs for Database Propagation
-=================================================
+Configuring the slave
+-------------------------
 
-The database is propagated from the master KDC to the slave KDCs via the kpropd daemon. To set up propagation, create a file on each KDC, named */usr/local/var/krb5kdc/kpropd.acl*, containing the principals for each of the KDCs. For example, if the master KDC were *kerberos.mit.edu*, the slave KDCs were *kerberos-1.mit.edu* and *kerberos-2.mit.edu*, and the realm were *ATHENA.MIT.EDU*, then the file's contents would be::
+By default, the propagation is done on the entire content of the master's database. 
+That is, even special principals (like *K/M\@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):
+
+   • 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).
+
+You will now initialize the slave database::
+
+      kdb5_util create
+
+Caution: you will use :ref:`kdb5_util(8)` but without exporting the stash file (-s argument), i
+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::
 
      host/kerberos.mit.edu@ATHENA.MIT.EDU
-     host/kerberos-1.mit.edu@ATHENA.MIT.EDU
-     host/kerberos-2.mit.edu@ATHENA.MIT.EDU
-     
 
-Then, add the following line to */etc/inetd.conf* file on each KDC::
+.. 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.  
+
+
+Then, add the following line to */etc/inetd.conf* file on each KDC (Adjust the path to *kpropd*)::
 
      krb5_prop stream tcp nowait root /usr/local/sbin/kpropd kpropd
      
 
-You also need to add the following lines to */etc/services* on each KDC::
+You also need to add the following lines to */etc/services* on each KDC (assuming that default ports are used)::
 
      kerberos        88/udp      kdc       # Kerberos authentication (udp)
      kerberos        88/tcp      kdc       # Kerberos authentication (tcp)
@@ -64,6 +106,10 @@ You also need to add the following lines to */etc/services* on each KDC::
      kerberos-adm    749/tcp               # Kerberos 5 admin/changepw (tcp)
      kerberos-adm    749/udp               # Kerberos 5 admin/changepw (udp)
      
+.. note:: Do not start slave KDC -  you still do not have a copy of the master's database.
+
+Now that the slave KDC is able to accept database propagation, you’ll need to propagate the database from the master server.
+
 
 ------------
 
diff --git a/doc/rst_source/krb_admins/install_kdc/slave_intall_fin.rst b/doc/rst_source/krb_admins/install_kdc/slave_intall_fin.rst
deleted file mode 100644 (file)
index 179bfef..0000000
+++ /dev/null
@@ -1,30 +0,0 @@
-Create stash files on the Slave KDCs
-======================================
-
-Create stash files, by issuing the following commands on each slave KDC::
-
-     shell% kdb5_util stash
-     kdb5_util: Cannot find/read stored master key while reading master key
-     kdb5_util: Warning: proceeding without master key
-     Enter KDC database master key:  <= Enter the database master key.
-     shell%
-     
-
-As mentioned above, the stash file is necessary for your KDCs to be able authenticate to themselves, such as when they reboot. You could run your KDCs without stash files, but you would then need to type in the Kerberos database master key by hand every time you start a KDC daemon.
-
-Start the *krb5kdc* daemon on each KDC
-=========================================
-
-The final step in configuing your slave KDCs is to run the KDC daemon::
-
-     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. 
-
-------------
-
-Feedback:
-
-Please, provide your feedback or suggest a new topic at krb5-bugs@mit.edu?subject=Documentation___install_kdc
-
diff --git a/doc/rst_source/krb_admins/install_kdc/stash_file_def.rst b/doc/rst_source/krb_admins/install_kdc/stash_file_def.rst
new file mode 100644 (file)
index 0000000..4e2ee83
--- /dev/null
@@ -0,0 +1,18 @@
+.. _stash_definition:
+
+
+stash file
+============
+
+The stash file is a local copy of the master key that resides in encrypted form on the KDC's local disk. 
+The stash file is used to authenticate the KDC to itself automatically before starting the *kadmind* and *krb5kdc* daemons
+(e.g., as part of the machine's boot sequence). 
+The stash file, like the keytab file (see :ref:`kt_file_label` for more information) is a potential point-of-entry for a break-in,
+and if compromised, would allow unrestricted access to the Kerberos database. 
+If you choose to install a stash file, it should be readable only by root, and should exist only on the KDC's local disk. 
+The file should not be part of any backup of the machine, unless access to the backup data is secured as tightly as access to the master password itself.
+
+.. note:: If you choose not to install a stash file, the KDC will prompt you for the master key each time it starts up. 
+          This means that the KDC will not be able to start automatically, such as after a system reboot.
+
+
index ed2559719f75b3627ef0ea727306d0f67bd66a9c..1e9908f822e67fe971ad45f518c284c81a8be8b3 100644 (file)
@@ -53,6 +53,14 @@ Seen in:  ssh
 
 --------------------------------------------------------------------------------------------
 
+
+.. include:: ./install_kdc/kdc_prop_slave.rst
+   :start-after:  _prop_failed_start:
+   :end-before: _prop_failed_end:
+
+
+--------------------------------------------------------------------------------------------
+
 ..
 
 ------------------