summaryrefslogtreecommitdiff
path: root/server/man/sssd.conf.5.xml
blob: 6c5ce87a32525cb040c4ee94b5e29424ea78902c (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
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DocBook V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<reference>
<title>SSSD Manual pages</title>
<refentry>
    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="include/upstream.xml" />

    <refmeta>
        <refentrytitle>sssd.conf</refentrytitle>
        <manvolnum>5</manvolnum>
        <refmiscinfo class="manual">File Formats and Conventions</refmiscinfo>
    </refmeta>

    <refnamediv id='name'>
        <refname>sssd.conf</refname>
        <refpurpose>the configuration file for SSSD</refpurpose>
    </refnamediv>

    <refsect1 id='file-format'>
        <title>FILE FORMAT</title>

        <para>
            The file has an ini-style syntax and consists of sections and
            parameters. A section begins with the name of the section in
            square brackets and continues until the next section begins. An
            example of section with single and multi-valued parameters:
            <programlisting>
                <replaceable>[section]</replaceable>
                <replaceable>key</replaceable> = <replaceable>value</replaceable>
                <replaceable>key2</replaceable> = <replaceable>value2,value3</replaceable>
            </programlisting>
        </para>

        <para>
            The data types used are string (no quotes needed), integer
            and bool (with values of <quote>TRUE/FALSE</quote>).
        </para>

        <para>
            A line comment starts with a hash sign (<quote>#</quote>) or a
            semicolon (<quote>;</quote>)
        </para>

        <para>
            All sections can have an optional
            <replaceable>description</replaceable> parameter. Its function
            is only as a label for the section.
        </para>
    </refsect1>

    <refsect1 id='special-sections'>
        <title>SPECIAL SECTIONS</title>

        <refsect2 id='services'>
            <title>The [services] section</title>
            <para>
                Individual pieces of SSSD functionality are provided by special
                SSSD services that are started and stopped together with SSSD.
                The services are managed by a special service called
                <quote>monitor</quote>.
                <variablelist>
                    <title>Section parameters</title>
                    <varlistentry>
                        <term>activeServices</term>
                        <listitem>
                            <para>
                                Comma separated list of services that are
                                started when sssd itself starts. Since Data
                                Provider (<quote>dp</quote>) is a required
                                service, it will be started even if omitted.
                            </para>
                            <para>
                                Default: dp
                            </para>
                            <para>
                                Supported services: dp, nss, pam
                            </para>
                        </listitem>
                    </varlistentry>
                    <varlistentry>
                        <term>reconnection_retries</term>
                        <listitem>
                            <para>
                                Number of times services should attempt to
                                reconnect in the event of a Data Provider
                                crash or restart before they give up
                            </para>
                            <para>
                                Default: 3
                            </para>
                        </listitem>
                    </varlistentry>
                </variablelist>
            </para>
        </refsect2>

        <refsect2 id='domains'>
            <title>The [domains] section</title>
            <para>
                A domain is a database containing user information. SSSD can
                use more domains at the same time, but at least one must
                be configured or SSSD won't start.
            </para>
            <variablelist>
                <title>Section parameters</title>
                <varlistentry>
                    <term>domains</term>
                    <listitem>
                        <para>
                            The list of domains in the order you want them
                            to be queried
                        </para>
                    </listitem>
                </varlistentry>
            </variablelist>
        </refsect2>

        <refsect2 id='names'>
            <title>The [names] section</title>
            <para>
                This section allows to configure how a name, or a fully qualified
                name looks like. These settings are used by both the PAM and NSS
                responders.
            </para>
            <variablelist>
                <title>Section parameters</title>
                <varlistentry>
                    <term>re-expression (string)</term>
                    <listitem>
                        <para>
                            Regular expression that describes how to parse the string
                            containing user name and domain into these components.
                        </para>
                        <para>
                            Default: <quote>(?&lt;name&gt;[^@]+)@?(?&lt;domain&gt;[^@]*$)</quote>
                            which translates to "the name is everything up to the
                            <quote>@</quote> sign, the domain everything after that"
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term>full-name-format (string)</term>
                    <listitem>
                        <para>
                            A <citerefentry>
                                <refentrytitle>printf</refentrytitle>
                                <manvolnum>3</manvolnum>
                            </citerefentry>-compatible format that describes how to
                            translate a (name, domain) tuple into a fully qualified
                            name.
                        </para>
                        <para>
                            Default: <quote>%1$s@%2$s</quote>.
                        </para>
                    </listitem>
                </varlistentry>
            </variablelist>
        </refsect2>

        <refsect2 id='user_defaults'>
            <title>The [user_defaults] section</title>
            <para>
                This section contains settings that alter default values used
                when adding a user with SSSD userspace tools (sss_useradd).
            </para>
            <variablelist>
                <title>Section parameters</title>
                <varlistentry>
                    <term>defaultShell (string)</term>
                    <listitem>
                        <para>
                            The default shell for users created
                            with SSSD userspace tools.
                        </para>
                        <para>
                            Default: <filename>/bin/bash</filename>
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term>baseDirectory (string)</term>
                    <listitem>
                        <para>
                            The tools append the login name to
                            <replaceable>baseDirectory</replaceable> and
                            use that as the home directory.
                        </para>
                        <para>
                            Default: <filename>/home</filename>
                        </para>
                    </listitem>
                </varlistentry>
            </variablelist>
        </refsect2>

    </refsect1>

    <refsect1 id='services-sections'>
        <title>SERVICES SECTIONS</title>
        <para>
            Settings that can be used to configure different services
            are described in this section. They should reside in the
            [services/<replaceable>NAME</replaceable>] section, for example,
            for NSS service, the section would be <quote>[services/nss]</quote>
        </para>

        <refsect2 id='general'>
            <title>General service configuration options</title>
            <para>
                These options can be used to configure any service.
            </para>
            <variablelist>
                <varlistentry>
                    <term>debug-level (integer)</term>
                    <listitem>
                        <para>
                            Sets the debug level for the service. The
                            value can be in range from 0 (only critical
                            messages) to 10 (very verbose).
                        </para>
                        <para>
                            Default: 0
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term>reconnection_retries (integer)</term>
                    <listitem>
                        <para>
                            Number of times services should attempt to
                            reconnect in the event of a Data Provider
                            crash or restart before they give up
                        </para>
                        <para>
                            Default: 3
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term>command (string)</term>
                    <listitem>
                        <para>
                            By default, the executable
                            representing this service is called
                            <command>sssd_${service_name}</command>.
                            This directive allows to change the executable
                            name for the service. In the vast majority of
                            configurations, the default values should suffice.
                        </para>
                        <para>
                            Default: <command>sssd_${service_name}</command>
                        </para>
                    </listitem>
                </varlistentry>
            </variablelist>
        </refsect2>

        <refsect2 id='Monitor'>
            <title>Monitor configuration options</title>
            <para>
                Monitor is the central controller of the SSSD. It is
                responsible for running all the other services that provide
                specific pieces of functionality.
            </para>
            <variablelist>
                <varlistentry>
                    <term>sbusAddress (string)</term>
                    <listitem>
                        <para>
                            The services in sssd communicate over an internal
                            wrapper on top of D-Bus called S-Bus. This
                            directive can be used to specify the address
                            to connect to.  The vast majority of configurations
                            will not need to change this setting.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term>sbusTimeout (string)</term>
                    <listitem>
                        <para>
                            Specifies the timeout for messages sent over the SBUS.
                        </para>
                        <para>
                            Default: -1  (implies a reasonable timeout as defined
                            by the D-BUS library)
                        </para>
                    </listitem>
                </varlistentry>
            </variablelist>
        </refsect2>

        <refsect2 id='NSS'>
            <title>NSS configuration options</title>
            <para>
                These options can be used to configure the
                Name Service Switch (NSS) service.
            </para>
            <variablelist>
                <varlistentry>
                    <term>EnumCacheTimeout (integer)</term>
                    <listitem>
                        <para>
                            How long should nss_sss cache enumerations
                            (requests for info about all users)
                        </para>
                        <para>
                            Default: 120
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term>EntryCacheTimeout (integer)</term>
                    <listitem>
                        <para>
                            How long should nss_sss cache positive cache hits
                            (that is, queries for valid database entries) before
                            asking the backend again
                        </para>
                        <para>
                            Default: 600
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term>EntryNegativeTimeout (integer)</term>
                    <listitem>
                        <para>
                            How long should nss_sss cache negative cache hits
                            (that is, queries for invalid database entries, like
                            nonexistent ones) before asking the backend again
                        </para>
                        <para>
                            Default: 15
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term>filterUsers, filterGroups (string)</term>
                    <listitem>
                        <para>
                            Exclude certain users from being fetched from the sss
                            NSS database. This is particulary useful for system
                            accounts like root.
                        </para>
                    </listitem>
                </varlistentry>
            </variablelist>
        </refsect2>
    </refsect1>

    <refsect1 id='domain-sections'>
        <title>DOMAIN SECTIONS</title>
        <para>
            These configuration options can be present in a domain
            configuration section, that is, in a section called
            <quote>[domains/<replaceable>NAME</replaceable>]</quote>
            <variablelist>
                <varlistentry>
                    <term>minId,maxId (integer)</term>
                    <listitem>
                        <para>
                            UID limits for the domain. If a domain contains
                            entry that is outside these limits, it is ignored
                        </para>
                        <para>
                            Default: 0 (no limit)
                        </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>timeout (integer)</term>
                    <listitem>
                        <para>
                            Timeout in seconds for this particular domain.
                            Raising this timeout might prove useful for slower
                            backends like distant LDAP servers.
                        </para>
                        <para>
                            Default: 0 (no timeout)
                        </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>magicPrivateGroups (bool)</term>
                    <listitem>
                        <para>
                            By using the Magic Private Groups option, you
                            are imposing two limitations to the ID space
                            and name space:
                        </para>
                        <para>
                            1. Users and groups in the domain share a common
                            name space. There can never be an explicit group
                            with the same name as a user
                        </para>
                        <para>
                            2. Users and groups share a common ID
                            space, there can never be an explicit group with
                            a same ID as a user
                        </para>
                        <para>
                            Using Magic Private groups bring the benefit of
                            better Windows Interoperability (in Windows,
                            the ID and name spaces are unique) and also
                            avoids creating a group for every user,
                            thus cluttering the group space. Also, for
                            NSS calls, every user is actually returned
                            as user's private group without having to
                            explicitly create the group, thus having the
                            same effect as User Private Groups
                        </para>
                        <para>
                            Default: FALSE
                        </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>enumerate (integer)</term>
                    <listitem>
                        <para>
                            Determines if a domain can be enumerated. This
                            parameter can have one of the following values:
                        </para>
                        <para>
                            0 = No enumeration
                        </para>
                        <para>
                            1 = Enumerate users
                        </para>
                        <para>
                            2 = Enumerate groups
                        </para>
                        <para>
                            3 = Enumerate both
                        </para>
                        <para>
                            Default: 0
                        </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>cache-credentials (bool)</term>
                    <listitem>
                        <para>
                            Determines if user credentials are also cached
                            in the local LDB cache
                        </para>
                        <para>
                            Default: FALSE
                        </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>legacy (bool)</term>
                    <listitem>
                        <para>
                            A legacy domain is a strictly POSIX domain in
                            terms of attributes it supports. Groups in legacy
                            domains can't be nested.
                        </para>
                        <para>
                            Default: FALSE
                        </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>store-legacy-passwords (bool)</term>
                    <listitem>
                        <para>
                            Whether to also store passwords in a legacy domain
                        </para>
                        <para>
                            Default: FALSE
                        </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>provider (string)</term>
                    <listitem>
                        <para>
                            The Data Provider backend to use for this domain.
                        </para>
                        <para>
                            Supported backends:
                        </para>
                        <para>
                            files: traditional UNIX files (<filename>/etc/passwd</filename>)
                        </para>
                        <para>
                            proxy: Support a legacy NSS provider
                        </para>
                        <para>
                            local: SSSD internal local provider
                        </para>
                        <para>
                            ldap:  LDAP provider
                        </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>useFullyQualifiedNames (bool)</term>
                    <listitem>
                        <para>
                            If set to TRUE, all requests to this domain
                            must use fully qualified names. For example,
                            if used in LOCAL domain that contains a "test"
                            user, <command>getent passwd test</command>
                            wouldn't find the user while <command>getent
                            passwd test@LOCAL</command> would.
                        </para>
                        <para>
                            Default: FALSE
                        </para>
                    </listitem>
                </varlistentry>
            </variablelist>
        </para>

        <para>
            Options valid for proxy domains.

            <variablelist>
                <varlistentry>
                    <term>auth-module (string)</term>
                    <listitem>
                        <para>
                            The authentication module used. Two
                            authentication modules are provided -
                            <quote>ldap</quote> for native LDAP authentication
                            and <quote>proxy</quote>, used for relaying
                            authentication to some other PAM target.
                        </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>pam-target (string)</term>
                    <listitem>
                        <para>
                            The proxy target PAM proxies to.
                        </para>
                        <para>
                            Default: sssd_pam_proxy_default
                        </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>libName (string)</term>
                    <listitem>
                        <para>
                            The name of the NSS library to use in proxy
                            domains. The NSS functions searched for in the
                            library are in the form of
                            _nss_$(libName)_$(function), for example
                            _nss_files_getpwent.
                        </para>
                    </listitem>
                </varlistentry>
            </variablelist>
        </para>
    </refsect1>

    <refsect1 id='example'>
        <title>EXAMPLE</title>
        <para>
            The following example shows a typical SSSD config. It does
            not describe configuration of the domains themselves - refer to
            documentation on configuring domains for more details.
<programlisting>
[services]
description =  Local Service Configuration
activeServices = nss, pam
reconnection_retries = 3

[services/nss]
description = NSS Responder Configuration
filterGroups = root
filterUsers = root
debug-level = 4

[services/dp]
description = Data Provider Configuration
debug-level = 4

[services/pam]
description = PAM Responder Configuration

[services/monitor]
description = Service Monitor Configuration

[domains]
description = Domains served by SSSD
domains = LOCAL,FILES

[domains/LOCAL]
description = LOCAL Users domain
enumerate = 3
minId = 5000
maxId = 30000
legacy = FALSE
magicPrivateGroups = TRUE
provider = local

[domains/FILES]
description = Users stored in UNIX files
enumerate = 3
minId = 500
maxId = 4999
provider = files
</programlisting>
        </para>
    </refsect1>

    <refsect1 id='see_also'>
        <title>SEE ALSO</title>
        <para>
            <citerefentry>
                <refentrytitle>sssd.conf</refentrytitle><manvolnum>5</manvolnum>
            </citerefentry>,
            <citerefentry>
                <refentrytitle>sss_groupadd</refentrytitle><manvolnum>8</manvolnum>
            </citerefentry>,
            <citerefentry>
                <refentrytitle>sss_groupdel</refentrytitle><manvolnum>8</manvolnum>
            </citerefentry>,
            <citerefentry>
                <refentrytitle>sss_groupmod</refentrytitle><manvolnum>8</manvolnum>
            </citerefentry>,
            <citerefentry>
                <refentrytitle>sss_useradd</refentrytitle><manvolnum>8</manvolnum>
            </citerefentry>,
            <citerefentry>
                <refentrytitle>sss_userdel</refentrytitle><manvolnum>8</manvolnum>
            </citerefentry>,
            <citerefentry>
                <refentrytitle>sss_usermod</refentrytitle><manvolnum>8</manvolnum>
            </citerefentry>.
        </para>
    </refsect1>
</refentry>
</reference>