svn rev #25406: trunk/doc/rst_source/krb_admins/ conf_files/ database/db_policies/ ...
tsitkova@MIT.EDU
tsitkova at MIT.EDU
Fri Oct 21 19:15:28 EDT 2011
http://src.mit.edu/fisheye/changelog/krb5/?cs=25406
Commit By: tsitkova
Log Message:
Revised KDC propagation section.
Removed rst files that are not used any more.
Changed Files:
D trunk/doc/rst_source/krb_admins/conf_files/salts.rst
D trunk/doc/rst_source/krb_admins/database/db_policies/del_pol.rst
D trunk/doc/rst_source/krb_admins/database/db_princs/delete_princ.rst
U trunk/doc/rst_source/krb_admins/install.rst
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
U 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
D trunk/doc/rst_source/krb_admins/install_kdc/slave_intall_fin.rst
A trunk/doc/rst_source/krb_admins/install_kdc/stash_file_def.rst
U trunk/doc/rst_source/krb_admins/troubleshoot.rst
Modified: trunk/doc/rst_source/krb_admins/install.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/install.rst 2011-10-21 21:14:13 UTC (rev 25405)
+++ trunk/doc/rst_source/krb_admins/install.rst 2011-10-21 23:15:27 UTC (rev 25406)
@@ -4,12 +4,7 @@
.. 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 at 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 @@
#. 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 >_
------------------
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 2011-10-21 21:14:13 UTC (rev 25405)
+++ trunk/doc/rst_source/krb_admins/install_kdc/admins_to_acl.rst 2011-10-21 23:15:27 UTC (rev 25406)
@@ -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.
+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.
+.. 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:
+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 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 "\*".
-==== ==========================================================
+ ==== ==========================================================
+ 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,8 +65,19 @@
*/admin at 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.
+
------------
Feedback:
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 2011-10-21 21:14:13 UTC (rev 25405)
+++ trunk/doc/rst_source/krb_admins/install_kdc/admins_to_db.rst 2011-10-21 23:15:27 UTC (rev 25406)
@@ -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 at ATHENA.MIT.EDU
+
NOTICE: no policy specified for "admin/admin at ATHENA.MIT.EDU";
assigning "default".
Enter password for principal admin/admin at ATHENA.MIT.EDU: <= Enter a password.
Modified: trunk/doc/rst_source/krb_admins/install_kdc/create_db.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/install_kdc/create_db.rst 2011-10-21 21:14:13 UTC (rev 25405)
+++ trunk/doc/rst_source/krb_admins/install_kdc/create_db.rst 2011-10-21 23:15:27 UTC (rev 25406)
@@ -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 at ATHENA.MIT.EDU'
You will be prompted for the database Master Password.
@@ -22,12 +31,14 @@
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`.
Modified: trunk/doc/rst_source/krb_admins/install_kdc/index.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/install_kdc/index.rst 2011-10-21 21:14:13 UTC (rev 25405)
+++ trunk/doc/rst_source/krb_admins/install_kdc/index.rst 2011-10-21 23:15:27 UTC (rev 25406)
@@ -4,16 +4,46 @@
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.
-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
-~~~~~~~~~~~~~~~~~~~~~~~~~
+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.
+
+
+
.. toctree::
:maxdepth: 1
@@ -24,7 +54,6 @@
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,36 +62,18 @@
: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
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+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.
-.. 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.
-
Switching Master and Slave KDCs
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Modified: trunk/doc/rst_source/krb_admins/install_kdc/kadmind_kt.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/install_kdc/kadmind_kt.rst 2011-10-21 21:14:13 UTC (rev 25405)
+++ trunk/doc/rst_source/krb_admins/install_kdc/kadmind_kt.rst 2011-10-21 23:15:27 UTC (rev 25406)
@@ -4,9 +4,15 @@
.. 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/kadmin.local
+ shell% /usr/local/sbin/admin.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 @@
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.
------------
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 2011-10-21 21:14:13 UTC (rev 25405)
+++ trunk/doc/rst_source/krb_admins/install_kdc/kdc_prop_slave.rst 2011-10-21 23:15:27 UTC (rev 25406)
@@ -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,16 +36,30 @@
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.
This will occur if you set restrictive access rules with a firewall, or if *kpropd* did not start upon connection.
@@ -61,42 +73,29 @@
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 */etc/inetd.conf* (see below for *xinetd*), and add the following line to setup the database propagation daemon ::
-Now we should edit *inetd.conf* (see below for *xinetd*), and add this line::
+ kprop stream tcp nowait root /usr/local/sbin/kpropd kpropd
- /etc/inetd.conf
-
- kprop stream tcp nowait root /usr/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 */etc/xinetd.d/kpropd* file ::
-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
-
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,13 +103,15 @@
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:
+
------------
Feedback:
Modified: trunk/doc/rst_source/krb_admins/install_kdc/krb_daemon.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/install_kdc/krb_daemon.rst 2011-10-21 21:14:13 UTC (rev 25405)
+++ trunk/doc/rst_source/krb_admins/install_kdc/krb_daemon.rst 2011-10-21 23:15:27 UTC (rev 25406)
@@ -1,16 +1,22 @@
-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
shell% tail /var/log/kadmin.log
@@ -19,6 +25,13 @@
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:
Modified: trunk/doc/rst_source/krb_admins/install_kdc/mod_conf.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/install_kdc/mod_conf.rst 2011-10-21 21:14:13 UTC (rev 25405)
+++ trunk/doc/rst_source/krb_admins/install_kdc/mod_conf.rst 2011-10-21 23:15:27 UTC (rev 25406)
@@ -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 @@
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:
Modified: trunk/doc/rst_source/krb_admins/install_kdc/slave_install.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/install_kdc/slave_install.rst 2011-10-21 21:14:13 UTC (rev 25405)
+++ trunk/doc/rst_source/krb_admins/install_kdc/slave_install.rst 2011-10-21 23:15:27 UTC (rev 25406)
@@ -1,62 +1,104 @@
.. _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 at ATHENA.MIT.EDU";
- assigning "default"
+ NOTICE: no policy specified for "host/kerberos.mit.edu at ATHENA.MIT.EDU"; assigning "default"
Principal "host/kerberos.mit.edu at ATHENA.MIT.EDU" created.
+
kadmin: addprinc -randkey host/kerberos-1.mit.edu
- NOTICE: no policy specified for "host/kerberos-1.mit.edu at ATHENA.MIT.EDU";
- assigning "default"
+ 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.
- kadmin: addprinc -randkey host/kerberos-2.mit.edu
- NOTICE: no policy specified for "host/kerberos-2.mit.edu at ATHENA.MIT.EDU";
- assigning "default"
- Principal "host/kerberos-2.mit.edu at 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.
+ - 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::
-Extract host keytabs for the KDCs
-=====================================
+ 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.
-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::
+ 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: 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:
+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 at ATHENA.MIT.EDU
- host/kerberos-1.mit.edu at ATHENA.MIT.EDU
- host/kerberos-2.mit.edu at 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,7 +106,11 @@
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.
+
+
------------
Feedback:
Added: trunk/doc/rst_source/krb_admins/install_kdc/stash_file_def.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/install_kdc/stash_file_def.rst (rev 0)
+++ trunk/doc/rst_source/krb_admins/install_kdc/stash_file_def.rst 2011-10-21 23:15:27 UTC (rev 25406)
@@ -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.
+
+
Modified: trunk/doc/rst_source/krb_admins/troubleshoot.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/troubleshoot.rst 2011-10-21 21:14:13 UTC (rev 25405)
+++ trunk/doc/rst_source/krb_admins/troubleshoot.rst 2011-10-21 23:15:27 UTC (rev 25406)
@@ -53,6 +53,14 @@
--------------------------------------------------------------------------------------------
+
+.. include:: ./install_kdc/kdc_prop_slave.rst
+ :start-after: _prop_failed_start:
+ :end-before: _prop_failed_end:
+
+
+--------------------------------------------------------------------------------------------
+
..
------------------
More information about the cvs-krb5
mailing list