Document idmap rewrite

(This used to be commit 4b9132e8bd1b2bc397b657ef07796f44d55f33da)

13 files changed, 115 insertions, 158 deletions

diff --git a/docs-xml/manpages-3/idmap_ad.8.xml b/docs-xml/manpages-3/idmap_ad.8.xml
index 766eb850902..fb0792eb9e7 100644
--- a/docs-xml/manpages-3/idmap_ad.8.xml
+++ b/docs-xml/manpages-3/idmap_ad.8.xml
@@ -68,13 +68,12 @@
 
 	<programlisting>
 	[global]
-	idmap domains = ALLDOMAINS
-	idmap config ALLDOMAINS:backend      = ad
-	idmap config ALLDOMAINS:default      = yes
-	idmap config ALLDOMAINS:range        = 10000 - 300000000
+	idmap backend = tdb
+	idmap uid = 1000000-1999999
+	idmap gid = 1000000-1999999
 
-	idmap alloc backend = tdb
-	idmap alloc config:range        = 5000 - 9999
+	idmap config CORP : backend  = ad
+	idmap config CORP : range = 1000-999999
 	</programlisting>
 </refsect1>
 
diff --git a/docs-xml/manpages-3/idmap_ldap.8.xml b/docs-xml/manpages-3/idmap_ldap.8.xml
index ea7def3a0c1..c09c141bb49 100644
--- a/docs-xml/manpages-3/idmap_ldap.8.xml
+++ b/docs-xml/manpages-3/idmap_ldap.8.xml
@@ -99,16 +99,6 @@
 			should be used.
 		</para></listitem>
 		</varlistentry>
-
-                <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>
 </refsect1>
 
@@ -116,27 +106,20 @@
 	<title>EXAMPLES</title>
 
 	<para>
-	The follow sets of a LDAP configuration which uses a slave server
-	running on localhost for fast fetching SID/gid/uid mappings, it
-	implies correct configuration of referrals.
-	The idmap alloc backend is pointed directly to the master to skip
-	the referral (and consequent reconnection to the master) that the
-	slave would return as allocation requires writing on the master.
+	The follow sets of a LDAP configuration which uses two LDAP
+	directories, one for storing the ID mappings and one for retrieving
+	new IDs.
 	</para>
 
 	<programlisting>
 	[global]
-	    idmap domains = ALLDOMAINS
-	    idmap config ALLDOMAINS:default      = yes
-	    idmap config ALLDOMAINS:backend      = ldap
-	    idmap config ALLDOMAINS:ldap_base_dn = ou=idmap,dc=example,dc=com
-	    idmap config ALLDOMAINS:ldap_url     = ldap://localhost/
-	    idmap config ALLDOMAINS:range        = 10000 - 50000
-
-	    idmap alloc backend = ldap
-	    idmap alloc config:ldap_base_dn = ou=idmap,dc=example,dc=com
-	    idmap alloc config:ldap_url     = ldap://master.example.com/
-	    idmap alloc config:range        = 10000 - 50000
+	idmap backend = ldap:ldap://localhost/
+	idmap uid = 1000000-1999999
+	idmap gid = 1000000-1999999
+
+	idmap alloc backend = ldap
+	idmap alloc config : ldap_url	= ldap://id-master/
+	idmap alloc config : ldap_base_dn = ou=idmap,dc=example,dc=com
 	</programlisting>
 </refsect1>
 
diff --git a/docs-xml/manpages-3/idmap_nss.8.xml b/docs-xml/manpages-3/idmap_nss.8.xml
index 063ce73748e..7d3503bcd1c 100644
--- a/docs-xml/manpages-3/idmap_nss.8.xml
+++ b/docs-xml/manpages-3/idmap_nss.8.xml
@@ -38,17 +38,12 @@
 
 	<programlisting>
 	[global]
-	    idmap domains = SAMBA TRUSTEDDOMAINS
+	idmap backend = tdb
+	idmap uid = 1000000-1999999
+	idmap gid = 1000000-1999999
 
-	    idmap config SAMBA:backend  = nss
-	    idmap config SAMBA:readonly = yes
-
-	    idmap config TRUSTEDDOMAINS:default = yes
-	    idmap config TRUSTEDDOMAINS:backend = tdb
-	    idmap config TRUSTEDDOMAINS:range   = 10000 - 50000
-
-	    idmap alloc backend      = tdb
-	    idmap alloc config:range = 10000 - 50000
+	idmap config SAMBA : backend  = nss
+	idmap config SAMBA : range = 1000-999999
 	</programlisting>
 </refsect1>
 
diff --git a/docs-xml/manpages-3/idmap_rid.8.xml b/docs-xml/manpages-3/idmap_rid.8.xml
index 1d80bf3a0eb..5eba356a7df 100644
--- a/docs-xml/manpages-3/idmap_rid.8.xml
+++ b/docs-xml/manpages-3/idmap_rid.8.xml
@@ -47,6 +47,9 @@
 			by default start at 1000 (512 hexadecimal), this means a good value
 			for base_rid can be 1000 as the resulting ID is calculated this way:
 			ID = RID - BASE_RID + LOW RANGE ID.
+		</para>
+		<para>
+			Use of this parameter is deprecated.
 		</para></listitem>
 		</varlistentry>
 	</variablelist>
@@ -54,19 +57,16 @@
 
 <refsect1>
 	<title>EXAMPLES</title>
-	<para>This example shows how to configure 2 domains with idmap_rid</para>
+	<para>This example shows how to configure a domain with idmap_rid</para>
 
 	<programlisting>
 	[global]
-	    idmap domains = MAIN TRUSTED1
+	idmap backend = tdb
+	idmap uid = 1000000-1999999
+	idmap gid = 1000000-1999999
 
-	    idmap config MAIN:backend      = rid
-	    idmap config MAIN:base_rid     = 0
-	    idmap config MAIN:range        = 10000 - 49999
-
-	    idmap config TRUSTED1:backend  = rid
-	    idmap config TRUSTED1:base_rid = 1000
-	    idmap config TRUSTED1:range    = 50000 - 99999
+	idmap config TRUSTED : backend  = rid
+	idmap config TRUSTED : range    = 50000 - 99999
 	</programlisting>
 </refsect1>
 
diff --git a/docs-xml/manpages-3/idmap_tdb.8.xml b/docs-xml/manpages-3/idmap_tdb.8.xml
index 2caba1e6cb3..4258d95ac67 100644
--- a/docs-xml/manpages-3/idmap_tdb.8.xml
+++ b/docs-xml/manpages-3/idmap_tdb.8.xml
@@ -60,26 +60,6 @@
 </refsect1>
 
 <refsect1>
-	<title>EXAMPLES</title>
-
-	<para>
-	The following example is equivalent to the pre-3.0.25 default idmap
-	configuration using the &quot;idmap backend = tdb&quot; setting.
-	</para>
-
-	<programlisting>
-	[global]
-	    idmap domains = ALLDOMAINS
-	    idmap config ALLDOMAINS:default = yes
-	    idmap config ALLDOMAINS:backend = tdb
-	    idmap config ALLDOMAINS:range   = 10000 - 50000
-
-	    idmap alloc backend = tdb
-	    idmap alloc config:range = 10000 - 50000
-	</programlisting>
-</refsect1>
-
-<refsect1>
 	<title>AUTHOR</title>
 
 	<para>
diff --git a/docs-xml/manpages-3/winbindd.8.xml b/docs-xml/manpages-3/winbindd.8.xml
index a4490968ef2..7721bd480ef 100644
--- a/docs-xml/manpages-3/winbindd.8.xml
+++ b/docs-xml/manpages-3/winbindd.8.xml
@@ -230,9 +230,6 @@ hosts:		files wins
 	determine which user and group ids correspond to Windows NT user
 	and group rids. </para>
 
-        <para>See the <smbconfoption name="idmap domains"/> or the old <smbconfoption name="idmap backend"/> parameters in
-        <filename>smb.conf</filename> for options for sharing this
-        database, such as via LDAP.</para>
 </refsect1>
 
 
diff --git a/docs-xml/smbdotconf/winbind/idmapallocbackend.xml b/docs-xml/smbdotconf/winbind/idmapallocbackend.xml
index 60e20b82d5e..e06bcd43a8e 100644
--- a/docs-xml/smbdotconf/winbind/idmapallocbackend.xml
+++ b/docs-xml/smbdotconf/winbind/idmapallocbackend.xml
@@ -6,18 +6,26 @@
 <description>
 	<para>
 	The idmap alloc backend provides a plugin interface for Winbind to use
-	when allocating Unix uids/gids for Windows SIDs.  This option is
-	to be used in conjunction with the <smbconfoption name="idmap domains"/> 
-	parameter and refers to the name of the idmap module which will provide
-	the id allocation functionality.  Please refer to the man page 
-	for each idmap plugin to determine whether or not the module implements
-	the allocation feature.  The most common plugins are the tdb (<citerefentry>
-        <refentrytitle>idmap_tdb</refentrytitle><manvolnum>8</manvolnum></citerefentry>)
-        and ldap (<citerefentry><refentrytitle>idmap_ldap</refentrytitle>
-        <manvolnum>8</manvolnum></citerefentry>) libraries.
+	when allocating Unix uids/gids for Windows SIDs. This option refers
+	to the name of the idmap module which will provide the id allocation
+	functionality. Please refer to the man page for each idmap plugin to
+	determine whether or not the module implements the allocation feature.
+	The most common plugins are the tdb (<citerefentry>
+	<refentrytitle>idmap_tdb</refentrytitle><manvolnum>8</manvolnum></citerefentry>)
+	and ldap (<citerefentry><refentrytitle>idmap_ldap</refentrytitle>
+	<manvolnum>8</manvolnum></citerefentry>) libraries.
 	</para>
 
-	<para>Also refer to the <smbconfoption name="idmap alloc config"/> option.
+	<para>
+	This parameter defaults to the value <smbconfoption name="idmap
+	backend"/> was set to, so by default winbind will allocate Unix IDs
+	from the default backend. You will only need to set this parameter
+	explicitly if you have an external source for Unix IDs, like a central
+	database service somewhere in your company.
+	</para>
+
+	<para>
+	Also refer to the <smbconfoption name="idmap alloc config"/> option.
 	</para>
 </description>
 
diff --git a/docs-xml/smbdotconf/winbind/idmapbackend.xml b/docs-xml/smbdotconf/winbind/idmapbackend.xml
index 10c4cb30a40..b5e86945b8a 100644
--- a/docs-xml/smbdotconf/winbind/idmapbackend.xml
+++ b/docs-xml/smbdotconf/winbind/idmapbackend.xml
@@ -6,14 +6,37 @@
 <description>
 	<para>
 	The idmap backend provides a plugin interface for Winbind to use
-	varying backends to store SID/uid/gid mapping tables.  This
-	option is mutually exclusive with the newer and more flexible
-	<smbconfoption name="idmap domains"/> parameter. The main difference
-	between the &quot;idmap backend&quot; and the &quot;idmap domains&quot;
-	is that the former only allows one backend for all domains while the
-	latter supports configuring backends on a per domain basis.
+	varying backends to store SID/uid/gid mapping tables.
 	</para>
 
+	<para>
+	This option specifies the default backend that is used when no special
+	configuration set by <smbconfoption name="idmap config"/> matches the
+	specific request.
+	</para>
+
+	<para>
+	This default backend also specifies the place where winbind-generated
+	idmap entries will be stored. So it is highly recommended that you
+	specify a writable backend like <citerefentry>
+	<refentrytitle>idmap_tdb</refentrytitle> <manvolnum>8</manvolnum>
+	</citerefentry> or <citerefentry>
+	<refentrytitle>idmap_ldap</refentrytitle> <manvolnum>8</manvolnum>
+	</citerefentry> as the idmap backend. The <citerefentry>
+	<refentrytitle>idmap_rid</refentrytitle> <manvolnum>8</manvolnum>
+	</citerefentry> and <citerefentry>
+	<refentrytitle>idmap_ad</refentrytitle> <manvolnum>8</manvolnum>
+	</citerefentry> backends are not writable and thus will generate
+	unexpected results if set as idmap backend.
+	</para>
+
+	<para>
+	To use the rid and ad backends, please specify them via the
+	<smbconfoption name="idmap config"/> parameter, possibly also for the
+	domain your machine is member of, specified by <smbconfoption
+	name="workgroup">.
+	<para>
+
 	<para>Examples of SID/uid/gid backends include tdb (<citerefentry>
 	<refentrytitle>idmap_tdb</refentrytitle><manvolnum>8</manvolnum></citerefentry>),
 	ldap (<citerefentry><refentrytitle>idmap_ldap</refentrytitle>
diff --git a/docs-xml/smbdotconf/winbind/idmapconfig.xml b/docs-xml/smbdotconf/winbind/idmapconfig.xml
index 08297d704cd..b43c186dca2 100644
--- a/docs-xml/smbdotconf/winbind/idmapconfig.xml
+++ b/docs-xml/smbdotconf/winbind/idmapconfig.xml
@@ -4,13 +4,14 @@
                  advanced="1" developer="1" hide="1"
                  xmlns:samba="http://www.samba.org/samba/DTD/samba-doc">
 <description>
+
 	<para>
-	The idmap config prefix provides a means of managing each domain 
-	defined by the <smbconfoption name="idmap domains"/> option using Samba's
-	parametric option support. The idmap config prefix should be
-	followed by the name of the domain, a colon, and a setting specific to 
-	the chosen backend. There are three options available for all domains:
+	The idmap config prefix provides a means of managing each trusted
+        domain separately. The idmap config prefix should be followed by the
+        name of the domain, a colon, and a setting specific to the chosen
+        backend. There are three options available for all domains:
 	</para>
+
 	<variablelist>  
 		<varlistentry>
 		<term>backend = backend_name</term>
@@ -21,45 +22,43 @@
 		</varlistentry>
 
 		<varlistentry>
-		<term>default = [yes|no]</term>
-		<listitem><para>
-			The default domain/backend will be used for searching for 
-			users and groups not belonging to one of the explicitly
-			listed domains (matched by comparing the account SID and the 
-			domain SID).
-		</para></listitem>
-		</varlistentry>
+		<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.
+                </para>
+		<para>
+		winbind uses this parameter to find the backend that is
+                authoritative for a unix ID to SID mapping, so it must be set
+                for each individually configured domain, and it must be
+                disjoint from the ranges set via <smbconfoption name="idmap
+                uid"> and <smbconfoption name="idmap gid">.
+		<para></listitem>
 
-		<varlistentry>
-		<term>readonly = [yes|no]</term>
-		<listitem><para>
-			Mark the domain as readonly which means that no attempts to
-			allocate a uid or gid (by the <smbconfoption name="idmap alloc 
-			backend"/>) for any user or group in that domain
-			will be attempted.
-		</para></listitem>
 		</varlistentry>
 	</variablelist>
 
 	<para>
 	The following example illustrates how to configure the <citerefentry>
-	<refentrytitle>idmap_ad</refentrytitle><manvolnum>8</manvolnum></citerefentry> 
-	for the CORP domain and the <citerefentry><refentrytitle>idmap_tdb</refentrytitle>
-	<manvolnum>8</manvolnum></citerefentry> backend for all other domains. The
-	TRUSTEDDOMAINS string is simply an arbitrary key used to reference the &quot;idmap
-	config&quot; settings and does not represent the actual name of a domain.
-	It is a catchall domain backend for any domain not explicitly listed.
+	<refentrytitle>idmap_ad</refentrytitle> <manvolnum>8</manvolnum>
+	</citerefentry> for the CORP domain and the
+	<citerefentry><refentrytitle>idmap_tdb</refentrytitle>
+	<manvolnum>8</manvolnum></citerefentry> backend for all other
+	domains. This configuration assumes that the admin of CORP assigns
+	unix ids below 1000000 via the SFU extensions, and winbind is supposed
+	to use the next million entries for its own mappings from trusted
+	domains and for local groups for example.
 	</para>
 
 	<programlisting>
-	idmap domains = CORP TRUSTEDDOMAINS
-
-	idmap config CORP:backend  = ad
-	idmap config CORP:readonly = yes
+	idmap backend = tdb
+	idmap uid = 1000000-1999999
+	idmap gid = 1000000-1999999
 
-	idmap config TRUSTEDDOMAINS:backend = tdb
-	idmap config TRUSTEDDOMAINS:default = yes
-	idmap config TRUSTEDDOMAINS:range   = 1000 - 9999
+	idmap config CORP : backend  = ad
+	idmap config CORP : range = 1000-999999
 	</programlisting>
 	
 </description>
diff --git a/docs-xml/smbdotconf/winbind/idmapdomains.xml b/docs-xml/smbdotconf/winbind/idmapdomains.xml
deleted file mode 100644
index 131b9e8167b..00000000000
--- a/docs-xml/smbdotconf/winbind/idmapdomains.xml
+++ /dev/null
@@ -1,27 +0,0 @@
-<samba:parameter name="idmap domains"
-                 context="G"
-		 type="string"
-                 advanced="1" developer="1" hide="1"
-                 xmlns:samba="http://www.samba.org/samba/DTD/samba-doc">
-<description>
-	<para>
-	The idmap domains option defines a list of Windows domains which will each
-	have a separately configured backend for managing Winbind's SID/uid/gid
-	tables.  This parameter is mutually exclusive with the older <smbconfoption 
-	name="idmap backend"/> option.
-	</para>
-
-	<para>
-	Values consist of the short domain name for Winbind's primary or collection
-	of trusted domains.  You may also use an arbitrary string to represent a catchall
-	domain backend for any domain not explicitly listed.
-	</para>
-
-	<para>
-	Refer to the <smbconfoption name="idmap config"/> for details about
-	managing the SID/uid/gid backend for each domain.
-	</para>
-</description>
-
-<value type="example">default AD CORP</value>
-</samba:parameter>
diff --git a/docs-xml/smbdotconf/winbind/idmapgid.xml b/docs-xml/smbdotconf/winbind/idmapgid.xml
index 28d88b51b0d..ef3ae4fde11 100644
--- a/docs-xml/smbdotconf/winbind/idmapgid.xml
+++ b/docs-xml/smbdotconf/winbind/idmapgid.xml
@@ -11,9 +11,10 @@
 	existing local or NIS groups within it as strange conflicts can 
 	occur otherwise.</para>
 
-	<para>See also the <smbconfoption name="idmap backend"/>, <smbconfoption 
-	name="idmap domains"/>, and <smbconfoption name="idmap config"/> options.
+	<para>See also the <smbconfoption name="idmap backend"/>, and
+	<smbconfoption name="idmap config"/> options.
 	</para>
+
 </description>
 
 <value type="default"></value>
diff --git a/docs-xml/smbdotconf/winbind/idmapuid.xml b/docs-xml/smbdotconf/winbind/idmapuid.xml
index de4074cfa4c..2c53817375e 100644
--- a/docs-xml/smbdotconf/winbind/idmapuid.xml
+++ b/docs-xml/smbdotconf/winbind/idmapuid.xml
@@ -11,8 +11,8 @@
 	range of ids should have no existing local
 	or NIS users within it as strange conflicts can occur otherwise.</para>
 
-	<para>See also the <smbconfoption name="idmap backend"/>, <smbconfoption 
-	name="idmap domains"/>, and <smbconfoption name="idmap config"/> options.
+	<para>See also the <smbconfoption name="idmap backend"/> and
+	<smbconfoption name="idmap config"/> options.
 	</para>
 </description>
 
diff --git a/docs-xml/smbdotconf/winbind/winbindtrusteddomainsonly.xml b/docs-xml/smbdotconf/winbind/winbindtrusteddomainsonly.xml
index 6ca229cfe92..3b1896ffece 100644
--- a/docs-xml/smbdotconf/winbind/winbindtrusteddomainsonly.xml
+++ b/docs-xml/smbdotconf/winbind/winbindtrusteddomainsonly.xml
@@ -14,8 +14,7 @@
 
 	<para>
 	This parameter is now deprecated in favor of the newer idmap_nss backend.
-	Refer to the <smbconfoption name="idmap domains"/> smb.conf option and
-	the <citerefentry><refentrytitle>idmap_nss</refentrytitle>
+	Refer to the <citerefentry><refentrytitle>idmap_nss</refentrytitle>
 	<manvolnum>8</manvolnum></citerefentry> man page for more information.
 	</para>
 </description>