svn rev #25005: trunk/doc/rst_source/krb_admins/ conf_files/ database/db_operations/ ...
tsitkova@MIT.EDU
tsitkova at MIT.EDU
Thu Jun 30 12:13:45 EDT 2011
http://src.mit.edu/fisheye/changelog/krb5/?cs=25005
Commit By: tsitkova
Log Message:
Added Install KDC section from the Kerberos V5 Installation Guide.
Updated some cross-referencing.
Changed Files:
U trunk/doc/rst_source/krb_admins/conf_files/kdc_conf.rst
U trunk/doc/rst_source/krb_admins/conf_files/krb5_conf.rst
U trunk/doc/rst_source/krb_admins/database/db_operations/index.rst
U trunk/doc/rst_source/krb_admins/index.rst
U trunk/doc/rst_source/krb_admins/install.rst
U trunk/doc/rst_source/krb_admins/install_appl_srv.rst
A trunk/doc/rst_source/krb_admins/install_clients/
A trunk/doc/rst_source/krb_admins/install_clients/index.rst
A trunk/doc/rst_source/krb_admins/install_kdc/
A trunk/doc/rst_source/krb_admins/install_kdc/admins_to_acl.rst
A trunk/doc/rst_source/krb_admins/install_kdc/admins_to_db.rst
A trunk/doc/rst_source/krb_admins/install_kdc/create_db.rst
A trunk/doc/rst_source/krb_admins/install_kdc/index.rst
A trunk/doc/rst_source/krb_admins/install_kdc/kadmind_kt.rst
A trunk/doc/rst_source/krb_admins/install_kdc/kdc_prop_slave.rst
A trunk/doc/rst_source/krb_admins/install_kdc/krb_daemon.rst
A trunk/doc/rst_source/krb_admins/install_kdc/mod_conf.rst
A trunk/doc/rst_source/krb_admins/install_kdc/slave_install.rst
A trunk/doc/rst_source/krb_admins/install_kdc/slave_intall_fin.rst
A trunk/doc/rst_source/krb_admins/install_kdc/switch_master_slave.rst
U trunk/doc/rst_source/krb_admins/realm_config/db_prop.rst
Modified: trunk/doc/rst_source/krb_admins/conf_files/kdc_conf.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/conf_files/kdc_conf.rst 2011-06-29 20:15:19 UTC (rev 25004)
+++ trunk/doc/rst_source/krb_admins/conf_files/kdc_conf.rst 2011-06-30 16:13:44 UTC (rev 25005)
@@ -10,11 +10,11 @@
The kdc.conf file is set up in the same format as the :ref:`krb5_conf_label` file. The kdc.conf file may contain any or all of the following three sections:
-================== ================================
-kdcdefaults_ Contains default values for overall behavior of the KDC.
-realms_ Contains subsections keyed by Kerberos realm names. Each subsection describes realm-specific information, including where to find the Kerberos servers for that realm.
-logging_ Contains relations which determine how Kerberos programs are to perform logging.
-================== ================================
+==================== ================================
+:ref:`kdcdefaults` Contains default values for overall behavior of the KDC.
+:ref:`kdc_realms` Contains subsections keyed by Kerberos realm names. Each subsection describes realm-specific information, including where to find the Kerberos servers for that realm.
+:ref:`kdc_logging` Contains relations which determine how Kerberos programs are to perform logging.
+==================== ================================
Sections
-------------
@@ -23,6 +23,7 @@
.. _kdcdefaults:
**[kdcdefaults]**
+~~~~~~~~~~~~~~~~~~~~~~~
The following relation is defined in the [kdcdefaults] section:
@@ -35,9 +36,10 @@
restrict_anonymous_to_tgt
This flag determines the default value of restrict_anonymous_to_tgt for realms. The default value is false.
-.. _realms:
+.. _kdc_realms:
**[realms]**
+~~~~~~~~~~~~~~~
Each tag in the [realms] section of the file names a Kerberos realm. The value of the tag is a subsection where the relations in that subsection define KDC parameters for that particular realm.
@@ -117,11 +119,12 @@
A boolean value (true, false). If set to true, the KDC will reject ticket requests from anonymous principals to service principals other than the realm's ticket-granting service. This option allows anonymous PKINIT to be enabled for use as FAST armor tickets without allowing anonymous authentication to services. By default, the value of restrict_anonymous_to_tgt as specified in the [kdcdefaults] section is used.
-.. _logging:
+.. _kdc_logging:
**[logging]**
+~~~~~~~~~~~~~~~~~~~~
-See *[logging]* section in :ref:`krb5_conf_label`
+See :ref:`logging` section in :ref:`krb5_conf_label`
PKINIT options
@@ -129,7 +132,7 @@
.. note:: The following are pkinit-specific options. Note that these values may be specified in [kdcdefaults] as global defaults, or within a realm-specific subsection of [realms]. Also note that a realm-specific value over-rides, does not add to, a generic [kdcdefaults] specification. The search order is:
- 1. realm-specific subsection of realms_
+ 1. realm-specific subsection of [realms]
[realms]
EXAMPLE.COM = {
@@ -138,7 +141,7 @@
}
- 2. generic value in the kdcdefaults_ section.
+ 2. generic value in the [kdcdefaults] section.
[kdcdefaults]
pkinit_anchors = DIR\:/usr/local/generic_trusted_cas/
Modified: trunk/doc/rst_source/krb_admins/conf_files/krb5_conf.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/conf_files/krb5_conf.rst 2011-06-29 20:15:19 UTC (rev 25004)
+++ trunk/doc/rst_source/krb_admins/conf_files/krb5_conf.rst 2011-06-30 16:13:44 UTC (rev 25005)
@@ -59,6 +59,7 @@
.. _libdefaults:
**[libdefaults]**
+~~~~~~~~~~~~~~~~~~~
The libdefaults section may contain any of the following relations:
@@ -147,6 +148,7 @@
.. _appdefaults:
**[appdefaults]**
+~~~~~~~~~~~~~~~~~~~~~~~~~
Each tag in the [appdefaults] section names a Kerberos V5 application or an option that is used by some Kerberos V5 application[s]. The value of the tag defines the default behaviors for that application.
@@ -175,6 +177,7 @@
.. _login:
**[login]**
+~~~~~~~~~~~~~~~
Each tag in the [login] section of the file is an option for *login.krb5*. This section may contain any of the following relations:
@@ -190,6 +193,7 @@
.. _realms:
**[realms]**
+~~~~~~~~~~~~~~~~~
Each tag in the [realms] section of the file is the name of a Kerberos realm. The value of the tag is a subsection with relations that define the properties of that particular realm. For each realm, the following tags may be specified in the realm's subsection:
@@ -239,6 +243,7 @@
.. _domain_realm:
**[domain_realm]**
+~~~~~~~~~~~~~~~~~~~~~
The [domain_realm] section provides a translation from a domain name or hostname to a Kerberos realm name. The tag name can be a host name, or a domain name, where domain names are indicated by a prefix of a period (.). The value of the relation is the Kerberos realm name for that particular host or domain. Host names and domain names should be in lower case.
@@ -256,6 +261,7 @@
.. _logging:
**[logging]**
+~~~~~~~~~~~~~~~~~~~~~~~
The [logging] section indicates how a particular entity is to perform its logging. The relations in this section assign one or more values to the entity name. Currently, the following entities are used:
@@ -300,6 +306,7 @@
.. _capaths:
**[capaths]**
+~~~~~~~~~~~~~~~~~~~~~~`
In order to perform direct (non-hierarchical) cross-realm authentication, a database is needed to construct the authentication paths between the realms. This section defines that database.
@@ -364,6 +371,7 @@
.. _dbdefaults:
**[dbdefaults]**
+~~~~~~~~~~~~~~~~~~~~~~~~
The [dbdefaults] section provides default values for the database specific parameters. It can also specify the configuration section under dbmodules_ section for database specific parameters used by the database library.
@@ -387,6 +395,7 @@
.. _dbmodules:
**[dbmodules]**
+~~~~~~~~~~~~~~~~~~
Contains database specific parameters used by the database library. Each tag in the [dbmodules] section of the file names a configuration section for database specific parameters that can be referred to by a realm. The value of the tag is a subsection where the relations in that subsection define the database specific parameters.
@@ -454,12 +463,12 @@
kadm5_hook interface
~~~~~~~~~~~~~~~~~~~~~~~~
-The kadm5_hook interface provides plugins with information on principal creation, modification, password changes and deletion. This interface can be used to write a plugin to synchronize MIT Kerberos with another database such as Active Directory. No plugins are built in for this interface.
+The **kadm5_hook** interface provides plugins with information on principal creation, modification, password changes and deletion. This interface can be used to write a plugin to synchronize MIT Kerberos with another database such as Active Directory. No plugins are built in for this interface.
clpreauth and kdcpreauth interfaces
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The clpreauth and kdcpreauth interfaces allow plugin modules to provide client and KDC preauthentication mechanisms. The following built-in modules exist for these interfaces:
+The **clpreauth** and **kdcpreauth** interfaces allow plugin modules to provide client and KDC preauthentication mechanisms. The following built-in modules exist for these interfaces:
pkinit
This module implements the PKINIT preauthentication mechanism.
Modified: trunk/doc/rst_source/krb_admins/database/db_operations/index.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/database/db_operations/index.rst 2011-06-29 20:15:19 UTC (rev 25004)
+++ trunk/doc/rst_source/krb_admins/database/db_operations/index.rst 2011-06-30 16:13:44 UTC (rev 25005)
@@ -1,3 +1,5 @@
+.. _db_operations_label:
+
Operations on the Kerberos database
=============================================
Modified: trunk/doc/rst_source/krb_admins/index.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/index.rst 2011-06-29 20:15:19 UTC (rev 25004)
+++ trunk/doc/rst_source/krb_admins/index.rst 2011-06-30 16:13:44 UTC (rev 25005)
@@ -1,19 +1,16 @@
For administrators
============================
-::
- A collection of documents how to setup Kerberos in various environments.
- Simple admin tasks
- Installation
- Configuration
- Trobleshooting (errors etc)
- Advanced topics
-
Contents:
---------
.. toctree::
+ :maxdepth: 1
+
+ install.rst
+
+.. toctree::
:maxdepth: 2
conf_files/index.rst
@@ -30,7 +27,6 @@
troubleshoot.rst
advanced/index.rst
- install.rst
various_envs.rst
Modified: trunk/doc/rst_source/krb_admins/install.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/install.rst 2011-06-29 20:15:19 UTC (rev 25004)
+++ trunk/doc/rst_source/krb_admins/install.rst 2011-06-30 16:13:44 UTC (rev 25005)
@@ -1,12 +1,36 @@
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 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
+---------
+
+.. toctree::
+ :maxdepth: 2
+
+ install_kdc/index.rst
+ install_clients/index.rst
+ install_appl_srv.rst
+
+
+
+Additional references
+----------------------
+
+
#. Debian Setting up of Kerberos <http://techpubs.spinlocksolutions.com/dklar/kerberos.html>_
-..
+------------------
Feedback
-------------------
Please, provide your feedback on this document at krb5-bugs at mit.edu?subject=Documentation___install_guide
Modified: trunk/doc/rst_source/krb_admins/install_appl_srv.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/install_appl_srv.rst 2011-06-29 20:15:19 UTC (rev 25004)
+++ trunk/doc/rst_source/krb_admins/install_appl_srv.rst 2011-06-30 16:13:44 UTC (rev 25005)
@@ -5,7 +5,9 @@
If you have Kerberos V5 installed on all of your client machines, MIT recommends that you make your hosts secure, to take advantage of the security that Kerberos authentication affords. However, if you have some clients that do not have Kerberos V5 installed, you can run an insecure server, and still take advantage of Kerberos V5's single sign-on capability.
+.. _kt_file_label:
+
The Keytab File
----------------------
Added: trunk/doc/rst_source/krb_admins/install_clients/index.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/install_clients/index.rst (rev 0)
+++ trunk/doc/rst_source/krb_admins/install_clients/index.rst 2011-06-30 16:13:44 UTC (rev 25005)
@@ -0,0 +1,4 @@
+Installing and Configuring UNIX Client Machines
+=====================================================
+
+
Added: trunk/doc/rst_source/krb_admins/install_kdc/admins_to_acl.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/install_kdc/admins_to_acl.rst (rev 0)
+++ trunk/doc/rst_source/krb_admins/install_kdc/admins_to_acl.rst 2011-06-30 16:13:44 UTC (rev 25005)
@@ -0,0 +1,74 @@
+.. _admin_acl_label:
+
+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.
+
+The format of the file is:
+
+ 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 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)
+==================== ===============================
+
+The above flags act as restrictions on any add or modify operation which is allowed due to that ACL line.
+
+Here is an example of a *kadm5.acl* file.
+
+.. warning:: The order is important; permissions are determined by the first matching entry.
+
+::
+
+ */admin at ATHENA.MIT.EDU *
+ joeadmin at ATHENA.MIT.EDU ADMCIL
+ joeadmin/*@ATHENA.MIT.EDU il */root at ATHENA.MIT.EDU
+ *@ATHENA.MIT.EDU cil *1/admin at ATHENA.MIT.EDU
+ */*@ATHENA.MIT.EDU i
+ */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.
+
+------------
+
+Feedback:
+
+Please, provide your feedback or suggest a new topic at krb5-bugs at mit.edu?subject=Documentation___install_kdc
+
+
Added: trunk/doc/rst_source/krb_admins/install_kdc/admins_to_db.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/install_kdc/admins_to_db.rst (rev 0)
+++ trunk/doc/rst_source/krb_admins/install_kdc/admins_to_db.rst 2011-06-30 16:13:44 UTC (rev 25005)
@@ -0,0 +1,21 @@
+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::
+
+ 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.
+ Re-enter password for principal admin/admin at ATHENA.MIT.EDU: <= Type it again.
+ Principal "admin/admin at ATHENA.MIT.EDU" created.
+ kadmin.local:
+
+------------
+
+Feedback:
+
+Please, provide your feedback or suggest a new topic at krb5-bugs at mit.edu?subject=Documentation___install_kdc
+
+
Added: trunk/doc/rst_source/krb_admins/install_kdc/create_db.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/install_kdc/create_db.rst (rev 0)
+++ trunk/doc/rst_source/krb_admins/install_kdc/create_db.rst 2011-06-30 16:13:44 UTC (rev 25005)
@@ -0,0 +1,41 @@
+.. _create_db_label:
+
+Create the database
+=========================
+
+You will use the *kdb5_util* 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.
+
+.. 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.)
+
+The following is an example of how to create a Kerberos database and stash file on the master KDC, using the kdb5_util command. (The line that begins with => is a continuation of the previous line.) 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.
+ It is important that you NOT FORGET this password.
+ Enter KDC database master key: <= Type the master password.
+ Re-enter KDC database master key to verify: <= Type it again.
+ shell%
+
+
+This will create five files in the directory specified in your *kdc.conf* file:
+
+- two Kerberos database files, *principal.db*, and *principal.ok*;
+- the Kerberos administrative database file, *principal.kadm5*;
+- the administrative database lock file, *principal.kadm5.lock*;
+- the stash file, *.k5stash*. (The default directory is */usr/local/var/krb5kdc*.) 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`.
+
+
+------------
+
+Feedback:
+
+Please, provide your feedback or suggest a new topic at krb5-bugs at mit.edu?subject=Documentation___install_kdc
+
+
Added: trunk/doc/rst_source/krb_admins/install_kdc/index.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/install_kdc/index.rst (rev 0)
+++ trunk/doc/rst_source/krb_admins/install_kdc/index.rst 2011-06-30 16:13:44 UTC (rev 25005)
@@ -0,0 +1,87 @@
+.. 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.
+
+
+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.
+
+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.
+
+
+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
+
+ mod_conf.rst
+ create_db.rst
+ admins_to_acl.rst
+ admins_to_db.rst
+ 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
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. toctree::
+ :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
+
+
+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_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
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. toctree::
+ :maxdepth: 2
+
+ switch_master_slave.rst
+
+Incremental database propagation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. toctree::
+ :maxdepth: 1
+
+ ../database/incr_db_prop.rst
+
+------------
+
+Feedback:
+
+Please, provide your feedback or suggest a new topic at krb5-bugs at mit.edu?subject=Documentation___install_kdc
+
Added: trunk/doc/rst_source/krb_admins/install_kdc/kadmind_kt.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/install_kdc/kadmind_kt.rst (rev 0)
+++ trunk/doc/rst_source/krb_admins/install_kdc/kadmind_kt.rst 2011-06-30 16:13:44 UTC (rev 25005)
@@ -0,0 +1,37 @@
+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 *ktadd* command, as in the following example. (The line beginning with => is a continuation of the previous line.)::
+
+ 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
+ WRFILE:/usr/local/var/krb5kdc/kadm5.keytab.
+ Entry for principal kadmin/admin with kvno 5, encryption type DES cbc mode
+ with CRC-32 added to keytab
+ WRFILE:/usr/local/var/krb5kdc/kadm5.keytab.
+ Entry for principal kadmin/changepw with kvno 5, encryption
+ type Triple DES cbc mode with HMAC/sha1 added to keytab
+ WRFILE:/usr/local/var/krb5kdc/kadm5.keytab.
+ Entry for principal kadmin/changepw with kvno 5,
+ 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, *ktadd* will save the extracted keytab as */usr/local/var/krb5kdc/kadm5.keytab*. The filename you use must be the one specified in your *kdc.conf* file.
+
+
+------------
+
+Feedback:
+
+Please, provide your feedback or suggest a new topic at krb5-bugs at mit.edu?subject=Documentation___install_kdc
+
+
Added: trunk/doc/rst_source/krb_admins/install_kdc/kdc_prop_slave.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/install_kdc/kdc_prop_slave.rst (rev 0)
+++ trunk/doc/rst_source/krb_admins/install_kdc/kdc_prop_slave.rst 2011-06-30 16:13:44 UTC (rev 25005)
@@ -0,0 +1,44 @@
+Propagate the database to each Slave KDC
+===========================================
+
+First, create a dump of the database on the master KDC, as follows::
+
+ shell% /usr/local/sbin/kdb5_util dump /usr/local/var/krb5kdc/slave_datatrans
+ shell%
+
+
+Next, you need to manually propagate the database to each slave KDC, as in the following example. (The lines beginning with => are continuations of the previous line.)::
+
+ /usr/local/sbin/kprop -f /usr/local/var/krb5kdc/slave_datatrans
+ => kerberos-1.mit.edu
+ /usr/local/sbin/kprop -f /usr/local/var/krb5kdc/slave_datatrans
+ => kerberos-2.mit.edu
+
+
+You will need a script to dump and propagate the database. The following is an example of a bourne shell script that will do this. (Note that the line that begins with => is a continuation of the previous line.)
+
+.. note:: Remember that you need to replace */usr/local* with the name of the directory in which you installed Kerberos V5.
+
+::
+
+ #!/bin/sh
+
+ kdclist = "kerberos-1.mit.edu kerberos-2.mit.edu"
+
+ /usr/local/sbin/kdb5_util "dump
+ => /usr/local/var/krb5kdc/slave_datatrans"
+
+ for kdc in $kdclist
+ do
+ /usr/local/sbin/kprop -f /usr/local/var/krb5kdc/slave_datatrans $kdc
+ done
+
+
+You will need to set up a cron job to run this script at the intervals you decided on earlier (See :ref:`db_prop_label` and :ref:`incr_db_prop_label`.)
+
+------------
+
+Feedback:
+
+Please, provide your feedback or suggest a new topic at krb5-bugs at mit.edu?subject=Documentation___install_kdc
+
Added: trunk/doc/rst_source/krb_admins/install_kdc/krb_daemon.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/install_kdc/krb_daemon.rst (rev 0)
+++ trunk/doc/rst_source/krb_admins/install_kdc/krb_daemon.rst 2011-06-30 16:13:44 UTC (rev 25005)
@@ -0,0 +1,28 @@
+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::
+
+ 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.
+
+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
+ Dec 02 12:35:52 beeblebrox kadmind[3189](info): starting
+
+
+Any errors the daemons encounter while starting will also be listed in the logging output.
+
+------------
+
+Feedback:
+
+Please, provide your feedback or suggest a new topic at krb5-bugs at mit.edu?subject=Documentation___install_kdc
+
+
Added: trunk/doc/rst_source/krb_admins/install_kdc/mod_conf.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/install_kdc/mod_conf.rst (rev 0)
+++ trunk/doc/rst_source/krb_admins/install_kdc/mod_conf.rst 2011-06-30 16:13:44 UTC (rev 25005)
@@ -0,0 +1,36 @@
+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*.
+
+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_label` and :ref:`kdc_conf_label`.
+
+*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.
+
+An example krb5.conf file::
+
+ [libdefaults]
+ default_realm = ATHENA.MIT.EDU
+
+ [realms]
+ ATHENA.MIT.EDU = {
+ kdc = kerberos.mit.edu
+ kdc = kerberos-1.mit.edu
+ kdc = kerberos-2.mit.edu
+ admin_server = kerberos.mit.edu
+ {
+
+ [logging]
+ kdc = FILE:/var/log/krb5kdc.log
+ admin_server = FILE:/var/log/kadmin.log
+ default = FILE:/var/log/krb5lib.log
+
+------------
+
+Feedback:
+
+Please, provide your feedback or suggest a new topic at krb5-bugs at mit.edu?subject=Documentation___install_kdc
+
Added: trunk/doc/rst_source/krb_admins/install_kdc/slave_install.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/install_kdc/slave_install.rst (rev 0)
+++ trunk/doc/rst_source/krb_admins/install_kdc/slave_install.rst 2011-06-30 16:13:44 UTC (rev 25005)
@@ -0,0 +1,76 @@
+.. _slave_host_key_label:
+
+Create host keys for the 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::
+
+ 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"
+ 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"
+ 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.
+
+
+Extract host keytabs for the KDCs
+=====================================
+
+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 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:
+
+
+.. note:: Principal must exist in the Kerberos database in order to extract the keytab.
+
+Set Up the Slave KDCs for Database Propagation
+=================================================
+
+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::
+
+ 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::
+
+ 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::
+
+ kerberos 88/udp kdc # Kerberos authentication (udp)
+ kerberos 88/tcp kdc # Kerberos authentication (tcp)
+ krb5_prop 754/tcp # Kerberos slave propagation
+ kerberos-adm 749/tcp # Kerberos 5 admin/changepw (tcp)
+ kerberos-adm 749/udp # Kerberos 5 admin/changepw (udp)
+
+
+------------
+
+Feedback:
+
+Please, provide your feedback or suggest a new topic at krb5-bugs at mit.edu?subject=Documentation___install_kdc
+
+
+
+
Added: trunk/doc/rst_source/krb_admins/install_kdc/slave_intall_fin.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/install_kdc/slave_intall_fin.rst (rev 0)
+++ trunk/doc/rst_source/krb_admins/install_kdc/slave_intall_fin.rst 2011-06-30 16:13:44 UTC (rev 25005)
@@ -0,0 +1,30 @@
+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 at mit.edu?subject=Documentation___install_kdc
+
Added: trunk/doc/rst_source/krb_admins/install_kdc/switch_master_slave.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/install_kdc/switch_master_slave.rst (rev 0)
+++ trunk/doc/rst_source/krb_admins/install_kdc/switch_master_slave.rst 2011-06-30 16:13:44 UTC (rev 25005)
@@ -0,0 +1,29 @@
+.. _switch_master_slave:
+
+Switching Master and 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.
+
+Assuming you have configured all of your KDCs to be able to function as either the master KDC or a slave KDC (as this document recommends), all you need to do to make the changeover is:
+
+If the master KDC is still running, do the following on the *old* master KDC:
+
+#. Kill the kadmind process.
+#. Disable the cron job that propagates the database.
+#. Run your database propagation script manually, to ensure that the slaves all have the latest copy of the database. (See Propagate the Database to Each Slave KDC.) If there is a need to preserve per-principal policy information from the database, you should do a "kdb5_util dump -ov" in order to preserve that information and propogate that dump file securely by some means to the slave so that its database has the correct state of the per-principal policy information.
+
+On the *new* master KDC:
+
+#. Create a database keytab. (See Create a kadmind Keytab (optional).)
+#. Start the kadmind daemon. (See Start the Kerberos Daemons.)
+#. Set up the cron job to propagate the database. (See Propagate the Database to Each Slave KDC.)
+#. Switch the CNAMEs of the old and new master KDCs. (If you don't do this, you'll need to change the krb5.conf file on every client machine in your Kerberos realm.)
+
+
+------------
+
+Feedback:
+
+Please, provide your feedback or suggest a new topic at krb5-bugs at mit.edu?subject=Documentation___install_kdc
+
Modified: trunk/doc/rst_source/krb_admins/realm_config/db_prop.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/realm_config/db_prop.rst 2011-06-29 20:15:19 UTC (rev 25004)
+++ trunk/doc/rst_source/krb_admins/realm_config/db_prop.rst 2011-06-30 16:13:44 UTC (rev 25005)
@@ -1,3 +1,5 @@
+.. _db_prop_label:
+
Database propagation
=========================
More information about the cvs-krb5
mailing list