s3:docs: update the idmap_tdb manpage to reflect current facts.

Michael
(cherry picked from commit 32be66b19da07983670002d1b2b5bc80cf0c8d16)

Signed-off-by: Michael Adam <obnox@samba.org>
(cherry picked from commit 4145a1de91a18ea9a09b3088f0e5cd054875760b)

1 files changed, 61 insertions, 20 deletions

diff --git a/docs-xml/manpages-3/idmap_tdb.8.xml b/docs-xml/manpages-3/idmap_tdb.8.xml
index e535bf016ec..b9b3e412914 100644
--- a/docs-xml/manpages-3/idmap_tdb.8.xml
+++ b/docs-xml/manpages-3/idmap_tdb.8.xml
@@ -19,9 +19,27 @@
 <refsynopsisdiv>
 	<title>DESCRIPTION</title>
 
-	<para>The idmap_tdb plugin is the default backend used by winbindd
-	for storing SID/uid/gid mapping tables and implements
-	both the &quot;idmap&quot; and &quot;idmap alloc&quot; APIs.
+	<para>
+	The idmap_tdb plugin is the default backend used by winbindd
+	for storing SID/uid/gid mapping tables. In contrast to read only
+	backends like idmap_rid, it is an allocating backend:
+	This means that it needs to allocate new user and group IDs
+	to create new mappings as requests to yet unmapped users are answered.
+	</para>
+
+	<para>
+	Note that in order for this (or any other allocating) backend to
+	function at all, the default backend needs to be writeable.
+	The ranges used for uid and gid allocation are the default ranges
+	configured by &quot;idmap uid&quot; and &quot;idmap gid&quot;.
+	</para>
+
+	<para>
+	Furthermore, since there is only one global allocating backend
+	responsible for all domains using writeable idmap backends,
+	any explicitly configured domain with idmap backend tdb
+	should have the same range as the default range, since it needs
+	to use the global uid / gid allocator. See the example below.
 	</para>
 </refsynopsisdiv>
 
@@ -33,30 +51,53 @@
 		<term>range = low - high</term>
                 <listitem><para>
 			Defines the available matching uid and gid range for which the
-			backend is authoritative.  Note that the range commonly matches
-			the allocation range due to the fact that the same backend will
-			store and retrieve SID/uid/gid mapping entries.  If the parameter
-			is absent, Winbind fail over to use the &quot;idmap uid&quot; and
-			&quot;idmap gid&quot; options from smb.conf.
+			backend is authoritative.
+			If the parameter is absent, Winbind fails over to use
+			the &quot;idmap uid&quot; and &quot;idmap gid&quot; options
+			from smb.conf.
                 </para></listitem>
                 </varlistentry>
 	</variablelist>
 </refsect1>
 
 <refsect1>
-	<title>IDMAP ALLOC OPTIONS</title>
+	<title>EXAMPLES</title>
 
-	<variablelist>
-                <varlistentry>
-		<term>range = low - high</term>
-                <listitem><para>
-			Defines the available matching uid and gid range from which
-			winbindd can allocate for users and groups.  If the parameter
-			is absent, Winbind fail over to use the &quot;idmap uid&quot;
-			and &quot;idmap gid&quot; options from smb.conf.
-                </para></listitem>
-                </varlistentry>
-	</variablelist>
+	<para>
+	This example shows how tdb is used as a the default idmap backend.
+	It configures the idmap range through the global options for all
+	domains encountered. This same range is used for uid/gid allocation.
+	</para>
+
+	<programlisting>
+	[global]
+	# "idmap backend = tdb" is redundant here since it is the default
+	idmap backend = tdb
+	idmap uid = 1000000-2000000
+	idmap gid = 1000000-2000000
+	</programlisting>
+
+	<para>
+	This (rather theoretical) example shows how tdb can be used as the
+	allocating backend while ldap is the default backend used to store
+	the mappings.
+	It adds an explicit configuration for some domain DOM1, that
+	uses the tdb idmap backend. Note that the same range as the
+	default uid/gid range is used, since the allocator has to serve
+	both the default backend and the explicitly configured domain DOM1.
+	</para>
+
+	<programlisting>
+	[global]
+	idmap backend = ldap
+	idmap uid = 1000000-2000000
+	idmap gid = 1000000-2000000
+	# use a different uid/gid allocator:
+	idmap alloc backend = tdb
+
+	idmap config DOM1 : backend = tdb
+	idmap config DOM1 : range = 1000000-2000000
+	</programlisting>
 </refsect1>
 
 <refsect1>