diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/copyright.texinfo | 17 | ||||
| -rw-r--r-- | doc/install.texinfo | 130 | ||||
| -rw-r--r-- | doc/iprop-notes.txt | 120 |
3 files changed, 265 insertions, 2 deletions
diff --git a/doc/copyright.texinfo b/doc/copyright.texinfo index 5d239b5..cc6b577 100644 --- a/doc/copyright.texinfo +++ b/doc/copyright.texinfo @@ -1,4 +1,4 @@ -Copyright @copyright{} 1985-2007 by the Massachusetts Institute of Technology. +Copyright @copyright{} 1985-2008 by the Massachusetts Institute of Technology. @quotation Export of software employing encryption from the United States of @@ -309,6 +309,21 @@ lib/gssapi/spnego/gssapiP_spnego.h lib/gssapi/spnego/spnego_mech.c @end smallexample +and the initial implementation of incremental propagation, including +the following new or changed files: + +@smallexample + include/iprop_hdr.h + kadmin/server/ipropd_svc.c + lib/kdb/iprop.x + lib/kdb/kdb_convert.c + lib/kdb/kdb_log.c + lib/kdb/kdb_log.h + lib/krb5/error_tables/kdb5_err.et + slave/kpropd_rpc.c + slave/kproplog.c +@end smallexample + are subject to the following license: @quotation diff --git a/doc/install.texinfo b/doc/install.texinfo index 64cdac7..54f183d 100644 --- a/doc/install.texinfo +++ b/doc/install.texinfo @@ -363,6 +363,7 @@ procedure is based on that recommendation. * Add Kerberos Principals to the Database:: * Limit Access to the KDCs:: * Switching Master and Slave KDCs:: +* Incremental Database Propagation:: @end menu @node Install the Master KDC, Install the Slave KDCs, Installing KDCs, Installing KDCs @@ -950,7 +951,7 @@ eklogin stream tcp nowait root @value{ROOTDIR}/sbin/klogind @end group @end smallexample -@node Switching Master and Slave KDCs, , Limit Access to the KDCs, Installing KDCs +@node Switching Master and Slave KDCs, Incremental Database Propagation, Limit Access to the KDCs, Installing KDCs @subsection Switching Master and Slave KDCs You may occasionally want to use one of your slave KDCs as the master. @@ -1001,6 +1002,133 @@ machine in your Kerberos realm.) @end enumerate +@node Incremental Database Propagation, , Switching Master and Slave KDCs, Installing KDCs +@subsection Incremental Database Propagation + +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 @code{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: + +@table @asis +@item @code{iprop_enable} (boolean) +If this is set to @code{true}, then incremental propagation is +enabled, and (as noted below) normal @code{kprop} propagation is +disabled. The default is @code{false}. + +@item @code{iprop_master_ulogsize} (integer) +This indicates the number of entries that should be retained in the +update log. The default is 1000; the maximum number is 2500. + +@item @code{iprop_slave_poll} (time interval) +This indicates how often the slave should poll the master KDC for +changes to the database. The default is two minutes. + +@item @code{iprop_port} (integer) +This specifies the port number to be used for incremental +propagation. This is required in both master and slave configuration +files. + +@item @code{iprop_logfile} (file name) +This specifies where the update log file for the realm database is to +be stored. The default is to use the @code{database_name} entry from +the @code{realms} section of the config file, with @file{.ulog} appended. +(NOTE: If @code{database_name} isn't specified in the @code{realms} +section, perhaps because the LDAP database back end is being used, or +the file name is specified in the @code{dbmodules} section, then the +hard-coded default for @code{database_name} is used. Determination of +the @code{iprop_logfile} default value will not use values from the +@code{dbmodules} section.) +@end table + +Both master and slave sides must have principals named +@code{kiprop/@var{hostname}} (where @var{hostname} is, as usual, the +lower-case, fully-qualified, canonical name for the host) registered +and keys stored in the default keytab file (@file{/etc/krb5.keytab}). +@c XXX: I think the master side, at least, might be able to read the +@c key out of the database. Test and document this. + +On the master KDC side, the @code{kiprop/@var{hostname}} principal +must be listed in the @code{kadmind} ACL file @code{kadm5.acl}, and +given the @code{p} privilege. + +On the slave KDC side, @code{kpropd} should be run. When incremental +propagation is enabled, it will connect to the @code{kadmind} on the +master KDC and start requesting updates. + +The normal @code{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 @code{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 @code{kprop} propagation is still +needed. + +There are several known bugs and restrictions in the current +implementation: +@itemize +@item +The ``call out to @code{kprop}'' mechanism is a bit fragile; if the +@code{kprop} propagation fails to connect for some reason, the process +on the slave may hang waiting for it, and will need to be restarted. +@item +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 RPC code does not currently +support IPv6. +@end itemize + +@menu +* Sun/MIT Incremental Propagation Differences:: +@end menu + +@node Sun/MIT Incremental Propagation Differences, , Incremental Database Propagation, Incremental Database Propagation +@subsubsection 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 @code{sunw_dbprop_enable}, +@code{sunw_dbprop_master_ulogsize}, and @code{sunw_dbprop_slave_poll}. + +The incremental propagation service is implemented as an ONC RPC +service. In the Sun implementation, the service is registered with +@code{rpcbind} (also known as @code{portmapper}) and the client looks +up the port number to contact. In the MIT implementation, where +interaction with some modern versions of @code{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 @file{/var/krb5} for +the update log and the per-slave @code{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 +@code{@value{ROOTDIR}/var/krb5kdc/slave_datatrans_@var{hostname}}. + @node Installing and Configuring UNIX Client Machines, UNIX Application Servers, Installing KDCs, Installing Kerberos V5 @section Installing and Configuring UNIX Client Machines diff --git a/doc/iprop-notes.txt b/doc/iprop-notes.txt new file mode 100644 index 0000000..2b1ee43 --- /dev/null +++ b/doc/iprop-notes.txt @@ -0,0 +1,120 @@ +Some (intentional) changes from Sun's submission are noted in the +install guide. + +Bugs or issues: + +The "full resync" part of the protocol involves the master side firing +off a normal kprop (and going back to servicing requests), and the +slave side stopping all the incremental propagation stuff and waiting +for the kprop. If the connection from the master never comes in for +some reason, the slave side just blocks forever, and never resumes +incremental propagation. + +Shawn had a good suggestion after I started the integration work, and +which I haven't had a chance to implement: Make the update-log code +fit in as a sort of pseudo-database layer via the DAL, being called +through the standard DAL methods, and doing its work around calls +through to the real database back end again through the DAL methods. +So for example, creating a "iprop+db2" database would create an update +log and the real db2 database; storing a principal entry would update +the update log as well; etc. At least initially, we wouldn't treat it +as a differently-named database; the installation of the hooks would +be done by explicitly checking if iprop is enabled, etc. + +The "iprop role" is assumed to be either master or slave. The master +writes a log, and the slave fetches it. But what about a cascade +propagation model where A sends to B which sends to C, perhaps because +A's bandwidth is highly limited, or B and C are co-located? In such a +case, B would want to operate in both modes. Granted, with iprop the +bandwidth issues should be less important, but there may still be +reasons one may wish to run in such a configuration. + +The propagation of changes does not happen in real time. It's not a +"push" protocol; the slaves poll periodically for changes. Perhaps a +future revision of the protocol could address that. + +kadmin/cli/kadmin.c call to kadm5_init_iprop - is this needed in +client-side program? Should it be done in libkadm5srv instead as part +of the existing kadm5_init* so that database-accessing applications +that don't get updated at the source level will automatically start +changing the update log as needed? + +Locking: Currently DAL exports the DB locking interface to the caller; +we want to slip the iprop code in between -- run it plus the DB update +operation with the DB lock held, whether or not the caller grabbed the +lock. (Does the caller always grab the lock before making changes?) +Currently we're using a file lock on the update log itself; this will +be independent of whether the DB back end implements locking (which +may be a good thing or a bad thing, depending). + +Various logging calls with odd format strings like "<null>" should be +fixed. + +Why are different principal names used, when incremental propagation +requires that normal kprop (which uses host principals) be possible +anyways? + +Why is this tied to kadmind, aside from (a) wanting to prevent other +db changes, which locking protocols should deal with anyways, (b) +existing acl code, (c) existing server process? + +The incremental propagation protocol requires an ACL entry on the +master, listing the slave. Since the full-resync part uses normal +kprop, the slave also has to have an ACL entry for the master. If +this is missing, I suspect the behavior will be that every two +minutes, the master side will (at the prompting of the slave) dump out +the database and attempt a full propagation. + +Possible optimizations: If an existing dump file has a recent enough +serial number, just send it, without dumping again? Use just one dump +file instead of one per slave? + +Requiring normal kprop means the slave still can't be behind a NAT or +firewall without special configuration. The incremental parts can +work in such a configuration, so long as outgoing TCP connections are +allowed. + +Still limited to IPv4 because of limitations in MIT's version of the +RPC code. (This could be fixed for kprop, if IPv6 sites want to do +full propagation only. Doing incremental propagation over IPv6 will +take work on the RPC library, and probably introduce +backwards-incompatible ABI changes.) + +Overflow checks for ulogentries times block size? + +If file can't be made the size indicated by ulogentries, shoud we +truncate or error out? If we error out, this could blow out when +resizing the log because of a too-large log entry. + +The kprop invocation doesn't specify a realm name, so it'll only work +for the default realm. No clean way to specify a port number, either. +Would it be overkill to come up with a way to configure host+port for +kpropd on the master? Preferably in a way that'd support cascading +propagations. + +The kadmind process, when it needs to run kprop, extracts the slave +host name from the client principal name. It assumes that the +principal name will be of the form foo/hostname@REALM, and looks +specifically for the "/" and "@" to chop up the string form of the +name. If looking up that name won't give a working IPv4 address for +the slave, kprop will fail (and kpropd will keep waiting, incremental +updates will stop, etc). + +Mapping between file offsets and structure addresses, we should be +careful about alignment. We're probably okay on current platforms, +but if we break log-format compatibility with Sun at some point, use +the chance to make the kdb_ent_header_t offsets be more strictly +aligned in the file. (16 or 32 bytes?) + +Not thread safe! The kdb5.c code will get a lock on the update log +file while making changes, but the lock is per-process. Currently +there are no processes I know of that use multiple threads and change +the database. (There's the Novell patch to make the KDC +multithreaded, but the kdc-kdb-update option doesn't currently +compile.) + +Logging in kpropd is poor to useless. If there are any problems, run +it in debug mode ("-d"). You'll still lose all output from the +invocation of kdb5_util dump and kprop run out of kadmind. + +Other man page updates needed: Anything with new -x options. |