summaryrefslogtreecommitdiff
path: root/src
diff options
context:
space:
mode:
authorStephen Gallagher <sgallagh@redhat.com>2012-04-24 14:21:40 -0400
committerStephen Gallagher <sgallagh@redhat.com>2012-05-03 14:09:15 -0400
commita23919ed39d212f9f5694d9b103c84641fdb7680 (patch)
treecabdf863367de844c7123a833c39f39263506b0b /src
parentc20a339d54b39120b4051f690ca759e6d079f177 (diff)
downloadsssd-a23919ed39d212f9f5694d9b103c84641fdb7680.tar.gz
sssd-a23919ed39d212f9f5694d9b103c84641fdb7680.tar.bz2
sssd-a23919ed39d212f9f5694d9b103c84641fdb7680.zip
MAN: Add manpage for ID mapping
Diffstat (limited to 'src')
-rw-r--r--src/man/include/ldap_id_mapping.xml192
-rw-r--r--src/man/po/po4a.cfg1
-rw-r--r--src/man/sssd-ldap.5.xml21
3 files changed, 214 insertions, 0 deletions
diff --git a/src/man/include/ldap_id_mapping.xml b/src/man/include/ldap_id_mapping.xml
new file mode 100644
index 00000000..62e5598e
--- /dev/null
+++ b/src/man/include/ldap_id_mapping.xml
@@ -0,0 +1,192 @@
+<refsect1 id='idmap'>
+ <title>ID MAPPING</title>
+ <para>
+ The ID-mapping feature allows SSSD to act as a client of Active
+ Directory without requiring administrators to extend user attributes
+ to support POSIX attributes for user and group identifiers.
+ </para>
+ <para>
+ NOTE: When ID-mapping is enabled, the uidNumber and gidNumber
+ attributes are ignored. This is to avoid the possibility of conflicts
+ between automatically-assigned and manually-assigned values. If you
+ need to use manually-assigned values, ALL values must be
+ manually-assigned.
+ </para>
+
+ <refsect2 id='idmap_algorithm'>
+ <title>Mapping Algorithm</title>
+ <para>
+ Active Directory provides an objectSID for every user and group
+ object in the directory. This objectSID can be broken up into
+ components that represent the Active Directory domain identity and
+ the relative identifier (RID) of the user or group object.
+ </para>
+ <para>
+ The SSSD ID-mapping algorithm takes a range of available UIDs and
+ divides it into equally-sized component sections - called
+ "slices"-. Each slice represents the space available to an Active
+ Directory domain.
+ </para>
+ <para>
+ When a user or group entry for a particular domain is encountered
+ for the first time, the SSSD allocates one of the available slices
+ for that domain. In order to make this slice-assignment repeatable
+ on different client machines, we select the slice based on the
+ following algorithm:
+ </para>
+ <para>
+ The SID string is passed through the murmurhash3 algorithm to
+ convert it to a 32-bit hashed value. We then take the modulus of
+ this value with the total number of available slices to pick the
+ slice.
+ </para>
+ <para>
+ NOTE: It is possible to encounter collisions in the hash and
+ subsequent modulus. In these situations, we will select the next
+ available slice, but it may not be possible to reproduce the same
+ exact set of slices on other machines (since the order that they
+ are encountered will determine their slice). In this situation, it
+ is recommended to either switch to using explicit POSIX attributes
+ in Active Directory (disabling ID-mapping) or configure a default
+ domain to guarantee that at least one is always consistent. See
+ <quote>Configuration</quote> for details.
+ </para>
+ </refsect2>
+
+ <refsect2 id='idmap_config'>
+ <title>Configuration</title>
+ <para>
+ Minimum configuration (in the <quote>[domain/DOMAINNAME]</quote>
+ section):
+ </para>
+ <para>
+<programlisting>
+ldap_id_mapping = True
+ldap_schema = ad
+</programlisting>
+ </para>
+ <para>
+ The default configuration results in configuring 10,000 slices,
+ each capable of holding up to 200,000 IDs, starting from 10,001
+ and going up to 2,000,100,000. This should be sufficient for
+ most deployments.
+ </para>
+ <refsect3 id='idmap_advanced_config'>
+ <title>Advanced Configuration</title>
+ <variablelist>
+ <varlistentry>
+ <term>ldap_idmap_range_min (integer)</term>
+ <listitem>
+ <para>
+ Specifies the lower bound of the range of POSIX IDs to
+ use for mapping Active Directory user and group SIDs.
+ </para>
+ <para>
+ NOTE: This option is different from
+ <quote>id_mn</quote> in that <quote>id_min</quote>
+ acts to filter the output of requests to this domain,
+ whereas this option controls the range of ID
+ assignment. This is a subtle distinction, but the
+ good general advice would be to have
+ <quote>id_min</quote> be less-than or equal to
+ <quote>ldap_idmap_range_min</quote>
+ </para>
+ <para>
+ Default: 10001
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>ldap_idmap_range_max (integer)</term>
+ <listitem>
+ <para>
+ Specifies the upper bound of the range of POSIX IDs to
+ use for mapping Active Directory user and group SIDs.
+ </para>
+ <para>
+ NOTE: This option is different from
+ <quote>id_max</quote> in that <quote>id_max</quote>
+ acts to filter the output of requests to this domain,
+ whereas this option controls the range of ID
+ assignment. This is a subtle distinction, but the
+ good general advice would be to have
+ <quote>id_max</quote> be greater-than or equal to
+ <quote>ldap_idmap_range_max</quote>
+ </para>
+ <para>
+ Default: 2000100000
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>ldap_idmap_range_size (integer)</term>
+ <listitem>
+ <para>
+ Specifies the number of IDs available for each slice.
+ If the range size does not divide evenly into the min
+ and max values, it will create as many complete slices
+ as it can.
+ </para>
+ <para>
+ Default: 200000
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>ldap_idmap_default_domain_sid (string)</term>
+ <listitem>
+ <para>
+ Specify the domain SID of the default domain. This
+ will guarantee that this domain will always be
+ assigned to slice zero in the ID map, bypassing
+ the murmurhash algorithm described above.
+ </para>
+ <para>
+ Default: not set
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>ldap_idmap_default_domain (string)</term>
+ <listitem>
+ <para>
+ Specify the name of the default domain.
+ </para>
+ <para>
+ Default: not set
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>ldap_idmap_autorid_compat (boolean)</term>
+ <listitem>
+ <para>
+ Changes the behavior of the ID-mapping algorithm
+ to behave more similarly to winbind's
+ <quote>idmap_autorid</quote> algorithm.
+ </para>
+ <para>
+ When this option is configured, domains will be
+ allocated starting with slice zero and increasing
+ monatomically with each additional domain.
+ </para>
+ <para>
+ NOTE: This algorithm is non-deterministic (it
+ depends on the order that users and groups are
+ requested). If this mode is required for
+ compatibility with machines running winbind, it
+ is recommended to also use the
+ <quote>ldap_idmap_default_domain_sid</quote>
+ option to guarantee that at least one domain is
+ consistently allocated to slice zero.
+ </para>
+ <para>
+ Default: False
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect3>
+ </refsect2>
+
+</refsect1>
diff --git a/src/man/po/po4a.cfg b/src/man/po/po4a.cfg
index e0f835d4..6d2a4db7 100644
--- a/src/man/po/po4a.cfg
+++ b/src/man/po/po4a.cfg
@@ -23,6 +23,7 @@
[type:docbook] include/service_discovery.xml $lang:$(builddir)/$lang/include/service_discovery.xml opt:"-k 0"
[type:docbook] include/upstream.xml $lang:$(builddir)/$lang/include/upstream.xml opt:"-k 0"
[type:docbook] include/failover.xml $lang:$(builddir)/$lang/include/failover.xml opt:"-k 0"
+[type:docbook] include/ldap_id_mapping.xml $lang:$(builddir)/$lang/include/ldap_id_mapping.xml opt:"-k 0"
[type:docbook] include/param_help.xml $lang:$(builddir)/$lang/include/param_help.xml opt:"-k 0"
[type:docbook] include/debug_levels.xml $lang:$(builddir)/$lang/include/debug_levels.xml opt:"-k 0"
[type:docbook] include/experimental.xml $lang:$(builddir)/$lang/include/experimental.xml opt:"-k 0"
diff --git a/src/man/sssd-ldap.5.xml b/src/man/sssd-ldap.5.xml
index 33f50831..de0fb5f6 100644
--- a/src/man/sssd-ldap.5.xml
+++ b/src/man/sssd-ldap.5.xml
@@ -1315,6 +1315,25 @@
</varlistentry>
<varlistentry>
+ <term>ldap_id_mapping (boolean)</term>
+ <listitem>
+ <para>
+ Specifies that SSSD should attempt to map user and
+ group IDs from the ldap_user_objectsid and
+ ldap_group_objectsid attributes instead of relying
+ on ldap_user_uid_number and ldap_group_gid_number.
+ </para>
+ <para>
+ Currently this feature supports only
+ ActiveDirectory objectSID mapping.
+ </para>
+ <para>
+ Default: false
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term>ldap_sasl_mech (string)</term>
<listitem>
<para>
@@ -2120,6 +2139,8 @@ ldap_access_filter = memberOf=cn=allowedusers,ou=Groups,dc=example,dc=com
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="include/service_discovery.xml" />
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="include/ldap_id_mapping.xml" />
+
<refsect1 id='example'>
<title>EXAMPLE</title>
<para>