Document hierarchical iprop

Also remove an outdated caveat, but add a new one about policy changes
causing full resyncs.

ticket: 7855

1 files changed, 13 insertions, 6 deletions

diff --git a/doc/admin/database.rst b/doc/admin/database.rst
index ab134b029f..7e7e8de9a5 100644
--- a/doc/admin/database.rst
+++ b/doc/admin/database.rst
@@ -826,12 +826,19 @@ 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.
+If an environment has a large number of slaves, it may be desirable to
+arrange them in a hierarchy instead of having the master serve updates
+to every slave.  To do this, run ``kadmind -proponly`` on each
+intermediate slave, and ``kpropd -A upstreamhostname`` on downstream
+slaves to direct each one to the appropriate upstream slave.
+
+There are several known restrictions in the current implementation:
+
+- The incremental update protocol does not transport changes to policy
+  objects.  Any policy changes on the master will result in full
+  resyncs to all slaves.
+- The slave's KDB module must support locking; it cannot be using the
+  LDAP KDB module.
 - The master and slave must be able to initiate TCP connections in
   both directions, without an intervening NAT.