summaryrefslogtreecommitdiff
path: root/src/man/include/ldap_id_mapping.xml
blob: 017edd1068235fff384792b7df5cddefa7ee28ff (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
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>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 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>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: 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>