[PATCH] Check idmap config with testparm

[Alexander Bokovoy]

On ma, 12 joulu 2016, Andreas Schneider wrote:
> > > Updated patch attached. I added an example from idmap_rid documentation
> > > to this section to show use of the options and keep it slightly
> > > different from the example in 'idmap config' option, for the benefit of
> > > showing more examples.
> > 
> > Sorry, missed an opening tag for citerefentry in the last reference in
> > the patch.
> 
> That looks good. But please use much bigger ranges.
> 
> 
> +	idmap config * : backend        = tdb
> +	idmap config * : range          = 1000000-1999999
> +
> +	idmap config MAIN : backend     = rid
> +	idmap config MAIN : range       = 5000000-5999999
> +
> +	idmap config TRUSTED : backend  = rid
> +	idmap config TRUSTED : range    = 6000000-6999999
> 
> 
> Customers tend to do copy and paste and if we use to small ranges they might 
> run into issues we really want to avoid. So better make them big enough :)
> 
> If you change this: RB+
Updated and your RB+ added. Please push. :)

-- 
/ Alexander Bokovoy
-------------- next part --------------
>From 338c9d1a2a012c455f05aa4fca2c1bab48c0c6d4 Mon Sep 17 00:00:00 2001
From: Alexander Bokovoy <ab at samba.org>
Date: Thu, 8 Dec 2016 10:21:53 +0200
Subject: [PATCH] smb.conf: add identity mapping section

Add a generic identity mapping section that points out to the other
resources in Samba documentation about idmap modules and their
configuration.

This should help users to discover corresponding documentation easily.

Signed-off-by: Alexander Bokovoy <ab at samba.org>
Reviewed-by: Andrea Schneider <asn at samba.org>
---
 docs-xml/manpages/smb.conf.5.xml | 60 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 60 insertions(+)

diff --git a/docs-xml/manpages/smb.conf.5.xml b/docs-xml/manpages/smb.conf.5.xml
index 10c1fb4..d67b8f1 100644
--- a/docs-xml/manpages/smb.conf.5.xml
+++ b/docs-xml/manpages/smb.conf.5.xml
@@ -754,6 +754,66 @@ chmod 1770 /usr/local/samba/lib/usershares
 
 </refsect1>
 
+<refsect1 ID="IDMAPCONSIDERATIONS">
+	<title>IDENTITY MAPPING CONSIDERATIONS</title>
+
+	<para>
+	In the SMB protocol, users, groups, and machines are represented by their security identifiers (SIDs).
+	On POSIX system Samba processes need to run under corresponding POSIX user identities and
+	with supplemental POSIX groups to allow access to the files owned by those users and groups.
+	The process of mapping SIDs to POSIX users and groups is called <emphasis>IDENTITY MAPPING</emphasis>
+	or, in short, <emphasis>ID MAPPING</emphasis>.
+	</para>
+
+	<para>
+	Samba supports multiple ways to map SIDs to POSIX users and groups. The configuration is driven by
+	the <smbconfoption name="idmap config DOMAIN : OPTION"/> option which allows one to specify identity
+	mapping (idmap) options for each domain	separately.
+	</para>
+
+	<para>
+	Identity mapping modules implement different strategies for mapping of SIDs to POSIX user and group
+	identities. They are applicable to different use cases and scenarios. It is advised to read the documentation
+	of the individual identity mapping modules before choosing a specific scenario to use. Each identity
+	management module is documented in a separate manual page. The standard idmap 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>),
+	nss (<citerefentry><refentrytitle>idmap_nss</refentrytitle> <manvolnum>8</manvolnum></citerefentry>), and
+	rfc2307 (<citerefentry><refentrytitle>idmap_rfc2307</refentrytitle> <manvolnum>8</manvolnum></citerefentry>).
+	</para>
+
+	<para>
+	Overall, ID mapping configuration should be decided carefully. Changes to the already deployed ID mapping
+	configuration may create the risk of losing access to the data or disclosing the data to the wrong parties.
+	</para>
+
+	<para>
+	This example shows how to configure two domains with <citerefentry><refentrytitle>idmap_rid</refentrytitle>
+	<manvolnum>8</manvolnum> </citerefentry>, the principal domain and a trusted domain,
+	leaving the default id mapping scheme at tdb.
+	</para>
+
+	<programlisting>
+	[global]
+	security = domain
+	workgroup = MAIN
+
+	idmap config * : backend        = tdb
+	idmap config * : range          = 1000000-1999999
+
+	idmap config MAIN : backend     = rid
+	idmap config MAIN : range       = 5000000-5999999
+
+	idmap config TRUSTED : backend  = rid
+	idmap config TRUSTED : range    = 6000000-6999999
+	</programlisting>
+</refsect1>
+
 <refsect1>
 	<title>EXPLANATION OF EACH PARAMETER</title>
 	
-- 
2.9.3