Adding upstream version 2.9.4.upstream/2.9.4

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 284 insertions, 0 deletions

diff --git a/src/man/eu/include/ldap_id_mapping.xml b/src/man/eu/include/ldap_id_mapping.xml
new file mode 100644
index 0000000..f80be8d
--- /dev/null
+++ b/src/man/eu/include/ldap_id_mapping.xml
@@ -0,0 +1,284 @@
+<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>
+    <para>
+        Please note that changing the ID mapping related configuration options will
+cause user and group IDs to change. At the moment, SSSD does not support
+changing IDs, so the SSSD database must be removed. Because cached passwords
+are also stored in the database, removing the database should only be
+performed while the authentication servers are reachable, otherwise users
+might get locked out. In order to cache the password, an authentication must
+be performed. It is not sufficient to use <citerefentry>
+<refentrytitle>sss_cache</refentrytitle> <manvolnum>8</manvolnum>
+</citerefentry> to remove the database, rather the process consists of:
+            <itemizedlist>
+                <listitem>
+                    <para>
+                        Making sure the remote servers are reachable
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+                        Stopping the SSSD service
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+                        Removing the database
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+                        Starting the SSSD service
+                    </para>
+                </listitem>
+            </itemizedlist>
+        Moreover, as the change of IDs might necessitate the adjustment of other
+system properties such as file and directory ownership, it's advisable to
+plan ahead and test the ID mapping configuration thoroughly.
+    </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 200,000 and going up to
+2,000,200,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 (inclusive) bound of the range of POSIX IDs to use for
+mapping Active Directory user and group SIDs. It is the first POSIX ID which
+can be used for the mapping.
+                        </para>
+                        <para>
+                            NOTE: This option is different from <quote>min_id</quote> in that
+<quote>min_id</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>min_id</quote> be less-than or equal to
+<quote>ldap_idmap_range_min</quote>
+                        </para>
+                        <para>
+                            Default: 200000
+                        </para>
+                    </listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term>ldap_idmap_range_max (integer)</term>
+                    <listitem>
+                        <para>
+                            Specifies the upper (exclusive) bound of the range of POSIX IDs to use for
+mapping Active Directory user and group SIDs. It is the first POSIX ID which
+cannot be used for the mapping anymore, i.e. one larger than the last one
+which can be used for the mapping.
+                        </para>
+                        <para>
+                            NOTE: This option is different from <quote>max_id</quote> in that
+<quote>max_id</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>max_id</quote> be greater-than or equal to
+<quote>ldap_idmap_range_max</quote>
+                        </para>
+                        <para>
+                            Default: 2000200000
+                        </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>
+                            NOTE: The value of this option must be at least as large as the highest user
+RID planned for use on the Active Directory server. User lookups and login
+will fail for any user whose RID is greater than this value.
+                        </para>
+                        <para>
+                            For example, if your most recently-added Active Directory user has
+objectSid=S-1-5-21-2153326666-2176343378-3404031434-1107,
+<quote>ldap_idmap_range_size</quote> must be at least 1108 as range size is
+equal to maximal SID minus minimal SID plus one (e.g. 1108 = 1107 - 0 + 1).
+                        </para>
+                        <para>
+                            It is important to plan ahead for future expansion, as changing this value
+will result in changing all of the ID mappings on the system, leading to
+users with different local IDs than they previously had.
+                        </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 monotonically 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>
+                <varlistentry>
+                    <term>ldap_idmap_helper_table_size (integer)</term>
+                    <listitem>
+                        <para>
+                          Maximal number of secondary slices that is tried when performing mapping
+from UNIX id to SID.
+                        </para>
+                        <para>
+                          Note: Additional secondary slices might be generated when SID is being
+mapped to UNIX id and RID part of SID is out of range for secondary slices
+generated so far. If value of ldap_idmap_helper_table_size is equal to 0
+then no additional secondary slices are generated.
+                        </para>
+                        <para>
+                            Default: 10
+                        </para>
+                    </listitem>
+                </varlistentry>
+            </variablelist>
+        </refsect3>
+    </refsect2>
+
+    <refsect2 id='well_known_sids'>
+        <title>Well-Known SIDs</title>
+        <para>
+            SSSD supports to look up the names of Well-Known SIDs, i.e. SIDs with a
+special hardcoded meaning. Since the generic users and groups related to
+those Well-Known SIDs have no equivalent in a Linux/UNIX environment no
+POSIX IDs are available for those objects.
+        </para>
+        <para>
+            The SID name space is organized in authorities which can be seen as
+different domains. The authorities for the Well-Known SIDs are
+            <itemizedlist>
+                <listitem><para>Null Authority</para></listitem>
+                <listitem><para>World Authority</para></listitem>
+                <listitem><para>Local Authority</para></listitem>
+                <listitem><para>Creator Authority</para></listitem>
+                <listitem><para>Mandatory Label Authority</para></listitem>
+                <listitem><para>Authentication Authority</para></listitem>
+                <listitem><para>NT Authority</para></listitem>
+                <listitem><para>Built-in</para></listitem>
+            </itemizedlist>
+            The capitalized version of these names are used as domain names when
+returning the fully qualified name of a Well-Known SID.
+        </para>
+        <para>
+            Since some utilities allow to modify SID based access control information
+with the help of a name instead of using the SID directly SSSD supports to
+look up the SID by the name as well. To avoid collisions only the fully
+qualified names can be used to look up Well-Known SIDs. As a result the
+domain names <quote>NULL AUTHORITY</quote>, <quote>WORLD AUTHORITY</quote>,
+<quote>LOCAL AUTHORITY</quote>, <quote>CREATOR AUTHORITY</quote>,
+<quote>MANDATORY LABEL AUTHORITY</quote>, <quote>AUTHENTICATION
+AUTHORITY</quote>, <quote>NT AUTHORITY</quote> and <quote>BUILTIN</quote>
+should not be used as domain names in <filename>sssd.conf</filename>.
+        </para>
+    </refsect2>
+
+</refsect1>