s3:doc: update documentation of the "idmap config FOO : BAR" familiy of parameters

diff --git a/docs-xml/smbdotconf/winbind/idmapconfig.xml b/docs-xml/smbdotconf/winbind/idmapconfig.xml
index f6e97b9d97cb8c94c0056a78e54845f7b2ac489a..69bddf0ebf75fcd2c8d1d8f51dbd163cea3fb7f0 100644 (file)
--- a/docs-xml/smbdotconf/winbind/idmapconfig.xml
+++ b/docs-xml/smbdotconf/winbind/idmapconfig.xml
@@ -6,44 +6,108 @@
 <description>
 
        <para>
-       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:
+       ID mapping in Samba is the mapping between Windows SIDs and Unix user
+       and group IDs. This is performed by Winbindd with a configurable plugin
+       interface. Samba's ID mapping is configured by options starting with the
+       <smbconfoption name="idmap config"/> prefix.
+       An idmap option consists of the <smbconfoption name="idmap config"/>
+       prefix, followed by a domain name or the asterisk character (*),
+       a colon, and the name of an idmap setting for the chosen domain.
        </para>
 
-       <variablelist>  
+       <para>
+       The idmap configuration is hence divided into groups, one group
+       for each domain to be configured, and one group with the the
+       asterisk instead of a proper domain name, which speifies the
+       default configuration that is used to catch all domains that do
+       not have an explicit idmap configuration of their own.
+       </para>
+
+       <para>
+       There are three general options available:
+       </para>
+
+       <variablelist>
                <varlistentry>
                <term>backend = backend_name</term>
                <listitem><para>
-                       Specifies the name of the idmap plugin to use as the 
-                       SID/uid/gid backend for this domain.
+               This specifies the name of the idmap plugin to use as the
+               SID/uid/gid backend for this domain. The standard backends are
+               tdb
+               (<citerefentry><refentrytitle>idmap_tdb</refentrytitle> <manvolnum>8</manvolnum> </citerefentry>),
+               tdb2
+               (<citerefentry><refentrytitle>idmap_tdb2</refentrytitle> <manvolnum>8</manvolnum></citerefentry>),
+               ldap
+               (<citerefentry><refentrytitle>idmap_ldap</refentrytitle> <manvolnum>8</manvolnum></citerefentry>),
+               ,
+               rid
+               (<citerefentry><refentrytitle>idmap_rid</refentrytitle> <manvolnum>8</manvolnum></citerefentry>),
+               ,
+               hash
+               (<citerefentry><refentrytitle>idmap_hash</refentrytitle> <manvolnum>8</manvolnum></citerefentry>),
+               ,
+               autorid
+               (<citerefentry><refentrytitle>idmap_autorid</refentrytitle> <manvolnum>8</manvolnum></citerefentry>),
+               ,
+               ad
+               (<citerefentry><refentrytitle>idmap_ad</refentrytitle> <manvolnum>8</manvolnum></citerefentry>),
+               ,
+               adex
+               (<citerefentry><refentrytitle>idmap_adex</refentrytitle> <manvolnum>8</manvolnum></citerefentry>),
+               ,
+               and nss.
+               (<citerefentry><refentrytitle>idmap_nss</refentrytitle> <manvolnum>8</manvolnum></citerefentry>),
+               The corresponding manual pages contain the details, but
+               here is a summary.
+               </para>
+               <para>
+               The first three of these create mappings of their own using
+               internal unixid counters and store the mappings in a database.
+               These are suitable for use in the default idmap configuration.
+               The rid and hash backends use a pure algorithmic calculation
+               to determine the unixid for a SID. The autorid module is a
+               mixture of the tdb and rid backend. It creates ranges for
+               each domain encountered and then uses the rid algorithm for each
+               of these automatically configured domains individually.
+               The ad and adex
+               backends both use unix IDs stored in Active Directory via
+               the standard schema extensions. The nss backend reverses
+               the standard winbindd setup and gets the unixids via names
+               from nsswitch which can be useful in an ldap setup.
                </para></listitem>
                </varlistentry>
 
                <varlistentry>
                <term>range = low - high</term>
-                <listitem><para>
+               <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>
+               backend is authoritative. For allocating backends, this also
+               defines the start and the end of the range for allocating
+               new unid IDs.
+               </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"/>.
+               authoritative for a unix ID to SID mapping, so it must be set
+               for each individually configured domain and for the default
+               configuration. The configured ranges must be mutually disjoint.
                </para></listitem>
+               </varlistentry>
 
+               <varlistentry>
+               <term>read only = yes|no</term>
+               <listitem><para>
+               This option can be used to turn the writing backends
+               tdb, tdb2, and ldap into read only mode. This can be useful
+               e.g. in cases where a pre-filled database exists that should
+               not be extended automatically.
+               </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> backend 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
@@ -53,9 +117,8 @@
        </para>
 
        <programlisting>
-       idmap backend = tdb
-       idmap uid = 1000000-1999999
-       idmap gid = 1000000-1999999
+       idmap config * : backend = tdb
+       idmap config * : range = 1000000-1999999
 
        idmap config CORP : backend  = ad
        idmap config CORP : range = 1000-999999