From a23919ed39d212f9f5694d9b103c84641fdb7680 Mon Sep 17 00:00:00 2001 From: Stephen Gallagher Date: Tue, 24 Apr 2012 14:21:40 -0400 Subject: MAN: Add manpage for ID mapping --- src/man/include/ldap_id_mapping.xml | 192 ++++++++++++++++++++++++++++++++++++ src/man/po/po4a.cfg | 1 + src/man/sssd-ldap.5.xml | 21 ++++ 3 files changed, 214 insertions(+) create mode 100644 src/man/include/ldap_id_mapping.xml diff --git a/src/man/include/ldap_id_mapping.xml b/src/man/include/ldap_id_mapping.xml new file mode 100644 index 000000000..62e5598eb --- /dev/null +++ b/src/man/include/ldap_id_mapping.xml @@ -0,0 +1,192 @@ + + ID MAPPING + + 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. + + + 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. + + + + Mapping Algorithm + + 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. + + + 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. + + + 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: + + + 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. + + + 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 + Configuration for details. + + + + + Configuration + + Minimum configuration (in the [domain/DOMAINNAME] + section): + + + +ldap_id_mapping = True +ldap_schema = ad + + + + 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. + + + Advanced Configuration + + + ldap_idmap_range_min (integer) + + + Specifies the lower bound of the range of POSIX IDs to + use for mapping Active Directory user and group SIDs. + + + NOTE: This option is different from + id_mn in that id_min + 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 + id_min be less-than or equal to + ldap_idmap_range_min + + + Default: 10001 + + + + + ldap_idmap_range_max (integer) + + + Specifies the upper bound of the range of POSIX IDs to + use for mapping Active Directory user and group SIDs. + + + NOTE: This option is different from + id_max in that id_max + 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 + id_max be greater-than or equal to + ldap_idmap_range_max + + + Default: 2000100000 + + + + + ldap_idmap_range_size (integer) + + + 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. + + + Default: 200000 + + + + + ldap_idmap_default_domain_sid (string) + + + 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. + + + Default: not set + + + + + ldap_idmap_default_domain (string) + + + Specify the name of the default domain. + + + Default: not set + + + + + ldap_idmap_autorid_compat (boolean) + + + Changes the behavior of the ID-mapping algorithm + to behave more similarly to winbind's + idmap_autorid algorithm. + + + When this option is configured, domains will be + allocated starting with slice zero and increasing + monatomically with each additional domain. + + + 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 + ldap_idmap_default_domain_sid + option to guarantee that at least one domain is + consistently allocated to slice zero. + + + Default: False + + + + + + + + diff --git a/src/man/po/po4a.cfg b/src/man/po/po4a.cfg index e0f835d4c..6d2a4db7c 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 33f50831f..de0fb5f61 100644 --- a/src/man/sssd-ldap.5.xml +++ b/src/man/sssd-ldap.5.xml @@ -1314,6 +1314,25 @@ + + ldap_id_mapping (boolean) + + + 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. + + + Currently this feature supports only + ActiveDirectory objectSID mapping. + + + Default: false + + + + ldap_sasl_mech (string) @@ -2120,6 +2139,8 @@ ldap_access_filter = memberOf=cn=allowedusers,ou=Groups,dc=example,dc=com + + EXAMPLE -- cgit