diff options
Diffstat (limited to 'src/man/include/ldap_id_mapping.xml')
| -rw-r--r-- | src/man/include/ldap_id_mapping.xml | 317 |
1 files changed, 317 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 0000000..25cb6e5 --- /dev/null +++ b/src/man/include/ldap_id_mapping.xml @@ -0,0 +1,317 @@ +<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> |