svn rev #25004: trunk/doc/rst_source/krb_admins/ database/
tsitkova@MIT.EDU
tsitkova at MIT.EDU
Wed Jun 29 16:15:19 EDT 2011
http://src.mit.edu/fisheye/changelog/krb5/?cs=25004
Commit By: tsitkova
Log Message:
Added "UNIX Application Servers" section.
Added the actual source file for "Incremental database propagation" section.
Changed Files:
A trunk/doc/rst_source/krb_admins/database/incr_db_prop.rst
A trunk/doc/rst_source/krb_admins/install_appl_srv.rst
Added: trunk/doc/rst_source/krb_admins/database/incr_db_prop.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/database/incr_db_prop.rst (rev 0)
+++ trunk/doc/rst_source/krb_admins/database/incr_db_prop.rst 2011-06-29 20:15:19 UTC (rev 25004)
@@ -0,0 +1,50 @@
+.. _incr_db_prop_label:
+
+
+
+Incremental database propagation
+====================================
+
+.. 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.
+
+Overview
+----------
+
+At some very large sites, dumping and transmitting the database can take more time than is desirable for changes to propagate from the master KDC to the slave KDCs. The incremental propagation support added in the 1.7 release is intended to address this.
+
+With incremental propagation enabled, all programs on the master KDC that change the database also write information about the changes to an "update log" file, maintained as a circular buffer of a certain size. A process on each slave KDC connects to a service on the master KDC (currently implmented in the kadmind server) and periodically requests the changes that have been made since the last check. By default, this check is done every two minutes. If the database has just been modified in the previous several seconds (currently the threshold is hard-coded at 10 seconds), the slave will not retrieve updates, but instead will pause and try again soon after. This reduces the likelihood that incremental update queries will cause delays for an administrator trying to make a bunch of changes to the database at the same time.
+
+Incremental propagation uses the following entries in the per-realm data in the KDC config file (See :ref:`kdc_conf_label`):
+
+====================== =============== ===========================================
+iprop_enable *boolean* If *true*, then incremental propagation is enabled, and (as noted below) normal kprop propagation is disabled. The default is *false*.
+iprop_master_ulogsize *integer* Indicates the number of entries that should be retained in the update log. The default is 1000; the maximum number is 2500.
+iprop_slave_poll *time interval* Indicates how often the slave should poll the master KDC for changes to the database. The default is two minutes.
+iprop_port *integer* Specifies the port number to be used for incremental propagation. This is required in both master and slave configuration files.
+iprop_logfile *file name* Specifies where the update log file for the realm database is to be stored. The default is to use the *database_name* entry from the realms section of the config file :ref:`kdc_conf_label`, with *.ulog* appended. (NOTE: If database_name isn't specified in the realms section, perhaps because the LDAP database back end is being used, or the file name is specified in the *dbmodules* section, then the hard-coded default for *database_name* is used. Determination of the *iprop_logfile* default value will not use values from the *dbmodules* section.)
+====================== =============== ===========================================
+
+Both master and slave sides must have principals named *kiprop/hostname* (where *hostname* is, as usual, the lower-case, fully-qualified, canonical name for the host) registered and keys stored in the default keytab file (/etc/krb5.keytab).
+
+On the master KDC side, the *kiprop/hostname* principal must be listed in the *kadmind* ACL file *kadm5.acl*, and given the *p* privilege (See :ref:`privileges_label`)
+
+On the slave KDC side, *kpropd* should be run. When incremental propagation is enabled, it will connect to the *kadmind* on the master KDC and start requesting updates.
+
+The normal *kprop* mechanism is disabled by the incremental propagation support. However, if the slave has been unable to fetch changes from the master KDC for too long (network problems, perhaps), the log on the master may wrap around and overwrite some of the updates that the slave has not yet retrieved. In this case, the slave will instruct the master KDC to dump the current database out to a file and invoke a one-time kprop propagation, with special options to also convey the point in the update log at which the slave should resume fetching incremental updates. Thus, all the keytab and ACL setup previously described for kprop propagation is still needed.
+
+There are several known bugs and restrictions in the current implementation:
+
+- The "call out to kprop" mechanism is a bit fragile; if the kprop propagation fails to connect for some reason, the process on the slave may hang waiting for it, and will need to be restarted.
+- The master and slave must be able to initiate TCP connections in both directions, without an intervening NAT. They must also be able to communicate over IPv4, since MIT's kprop and RPC code does not currently support IPv6.
+- Sun/MIT Incremental Propagation Differences:
+
+Sun/MIT incremental propagation differences
+----------------------------------------------
+
+Sun donated the original code for supporting incremental database propagation to MIT. Some changes have been made in the MIT source tree that will be visible to administrators. (These notes are based on Sun's patches. Changes to Sun's implementation since then may not be reflected here.)
+
+The Sun config file support looks for *sunw_dbprop_enable, sunw_dbprop_master_ulogsize,* and *sunw_dbprop_slave_poll*.
+
+The incremental propagation service is implemented as an ONC RPC service. In the Sun implementation, the service is registered with *rpcbind* (also known as portmapper) and the client looks up the port number to contact. In the MIT implementation, where interaction with some modern versions of *rpcbind* doesn't always work well, the port number must be specified in the config file on both the master and slave sides.
+
+The Sun implementation hard-codes pathnames in */var/krb5* for the update log and the per-slave kprop dump files. In the MIT implementation, the pathname for the update log is specified in the config file, and the per-slave dump files are stored in */usr/local/var/krb5kdc/slave_datatrans_hostname*.
Added: trunk/doc/rst_source/krb_admins/install_appl_srv.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/install_appl_srv.rst (rev 0)
+++ trunk/doc/rst_source/krb_admins/install_appl_srv.rst 2011-06-29 20:15:19 UTC (rev 25004)
@@ -0,0 +1,46 @@
+UNIX Application Servers
+================================
+
+An application server is a host that provides one or more services over the network. Application servers can be "secure" or "insecure." A "secure" host is set up to require authentication from every client connecting to it. An "insecure" host will still provide Kerberos authentication, but will also allow unauthenticated clients to connect.
+
+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.
+
+
+The Keytab File
+----------------------
+
+All Kerberos server machines need a *keytab* file, called */etc/krb5.keytab*, to authenticate to the KDC. The keytab file is an encrypted, local, on-disk copy of the host's key. The keytab file, like the stash file (See :ref:`create_db_label`) is a potential point-of-entry for a break-in, and if compromised, would allow unrestricted access to its host. The *keytab* file should be readable only by root, and should exist only on the machine'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 machine's root password itself.
+
+In order to generate a *keytab* for a host, the host must have a principal in the Kerberos database. The procedure for adding hosts to the database is described fully in :ref:`add_mod_princs_label`. (See :ref:`slave_host_key_label` for a brief description.) The *keytab* is generated by running kadmin and issuing the *ktadd* command.
+
+For example, to generate a *keytab* file to allow the host *trillium.mit.edu* to authenticate for the services host, ftp, and pop, the administrator *joeadmin* would issue the command (on *trillium.mit.edu*)::
+
+ trillium% /usr/local/sbin/kadmin
+ kadmin5: ktadd host/trillium.mit.edu ftp/trillium.mit.edu
+ => pop/trillium.mit.edu
+ kadmin: Entry for principal host/trillium.mit.edu at ATHENA.MIT.EDU with
+ kvno 3, encryption type DES-CBC-CRC added to keytab
+ WRFILE:/etc/krb5.keytab.
+ kadmin: Entry for principal ftp/trillium.mit.edu at ATHENA.MIT.EDU with
+ kvno 3, encryption type DES-CBC-CRC added to keytab
+ WRFILE:/etc/krb5.keytab.
+ kadmin: Entry for principal pop/trillium.mit.edu at ATHENA.MIT.EDU with
+ kvno 3, encryption type DES-CBC-CRC added to keytab
+ WRFILE:/etc/krb5.keytab.
+ kadmin5: quit
+ trillium%
+
+
+If you generate the *keytab* file on another host, you need to get a copy of the *keytab* file onto the destination host (*trillium*, in the above example) without sending it unencrypted over the network.
+
+Some Advice about Secure Hosts
+--------------------------------------
+
+Kerberos V5 can protect your host from certain types of break-ins, but it is possible to install Kerberos V5 and still leave your host vulnerable to attack. Obviously an installation guide is not the place to try to include an exhaustive list of countermeasures for every possible attack, but it is worth noting some of the larger holes and how to close them.
+
+We recommend that backups of secure machines exclude the *keytab* file (/etc/krb5.keytab). If this is not possible, the backups should at least be done locally, rather than over a network, and the backup tapes should be physically secured.
+
+The *keytab* file and any programs run by root, including the Kerberos V5 binaries, should be kept on local disk. The *keytab* file should be readable only by root.
+
+
+
More information about the cvs-krb5
mailing list