1SSSD.CONF(5) File Formats and Conventions SSSD.CONF(5)
2
6 sssd.conf - the configuration file for SSSD
7
9 The file has an ini-style syntax and consists of sections and
10 parameters. A section begins with the name of the section in square
11 brackets and continues until the next section begins. An example of
12 section with single and multi-valued parameters:
13 [section]
15 key = value
16 key2 = value2,value3
17 The data types used are string (no quotes needed), integer and bool
20 (with values of “TRUE/FALSE”).
21 A line comment starts with a hash sign (“#”) or a semicolon (“;”)
23 All sections can have an optional description parameter. Its function
25 is only as a label for the section.
26 sssd.conf must be a regular file, owned by root and only root may read
28 from or write to the file.
29
31 The [sssd] section
32 Individual pieces of SSSD functionality are provided by special SSSD
33 services that are started and stopped together with SSSD. The services
34 are managed by a special service frequently called “monitor”. The
35 “[sssd]” section is used to configure the monitor as well as some other
36 important options like the identity domains.
37 Section parameters
39 config_file_version (integer)
41 Indicates what is the syntax of the config file. SSSD 0.6.0 and
42 later use version 2.
43 services
45 Comma separated list of services that are started when sssd itself
46 starts.
47 Supported services: nss, pam
49 reconnection_retries (integer)
51 Number of times services should attempt to reconnect in the event
52 of a Data Provider crash or restart before they give up
53 Default: 3
55 domains
57 A domain is a database containing user information. SSSD can use
58 more domains at the same time, but at least one must be configured
59 or SSSD won't start. This parameter described the list of domains
60 in the order you want them to be queried.
61 re_expression (string)
63 Regular expression that describes how to parse the string
64 containing user name and domain into these components.
65 Default: “(?P<name>[^@]+)@?(?P<domain>[^@]*$)” which translates to
67 "the name is everything up to the “@” sign, the domain everything
68 after that"
69 PLEASE NOTE: the support for non-unique named subpatterns is not
71 available on all platforms (e.g. RHEL5 and SLES10). Only platforms
72 with libpcre version 7 or higher can support non-unique named
73 subpatterns.
74 PLEASE NOTE ALSO: older version of libpcre only support the Python
76 syntax (?P<name>) to label subpatterns.
77 full_name_format (string)
79 A printf(3)-compatible format that describes how to translate a
80 (name, domain) tuple into a fully qualified name.
81 Default: “%1$s@%2$s”.
83 try_inotify (boolean)
85 SSSD monitors the state of resolv.conf to identify when it needs to
86 update its internal DNS resolver. By default, we will attempt to
87 use inotify for this, and will fall back to polling resolv.conf
88 every five seconds if inotify cannot be used.
89 There are some limited situations where it is preferred that we
91 should skip even trying to use inotify. In these rare cases, this
92 option should be set to 'false'
93 Default: true on platforms where inotify is supported. False on
95 other platforms.
96 Note: this option will have no effect on platforms where inotify is
98 unavailable. On these platforms, polling will always be used.
99
101 Settings that can be used to configure different services are described
102 in this section. They should reside in the [$NAME] section, for
103 example, for NSS service, the section would be “[nss]”
104 General service configuration options
106 These options can be used to configure any service.
107 debug_level (integer)
109 Sets the debug level for the service. The value can be in range
110 from 0 (only critical messages) to 10 (very verbose).
111 Default: 0
113 debug_timestamps (bool)
115 Add a timestamp to the debug messages
116 Default: true
118 reconnection_retries (integer)
120 Number of times services should attempt to reconnect in the event
121 of a Data Provider crash or restart before they give up
122 Default: 3
124 command (string)
126 By default, the executable representing this service is called
127 sssd_${service_name}. This directive allows to change the
128 executable name for the service. In the vast majority of
129 configurations, the default values should suffice.
130 Default: sssd_${service_name}
132 NSS configuration options
134 These options can be used to configure the Name Service Switch (NSS)
135 service.
136 enum_cache_timeout (integer)
138 How many seconds should nss_sss cache enumerations (requests for
139 info about all users)
140 Default: 120
142 entry_cache_nowait_percentage (integer)
144 The entry cache can be set to automatically update entries in the
145 background if they are requested beyond a percentage of the
146 entry_cache_timeout value for the domain.
147 For example, if the domain's entry_cache_timeout is set to 30s and
149 entry_cache_nowait_percentage is set to 50 (percent), entries that
150 come in after 15 seconds past the last cache update will be
151 returned immediately, but the SSSD will go and update the cache on
152 its own, so that future requests will not need to block waiting for
153 a cache update.
154 Valid values for this option are 0-99 and represent a percentage of
156 the entry_cache_timeout for each domain. For performance reasons,
157 this percentage will never reduce the nowait timeout to less than
158 10 seconds. (0 disables this feature)
159 Default: 0
161 entry_negative_timeout (integer)
163 Specifies for how many seconds nss_sss should cache negative cache
164 hits (that is, queries for invalid database entries, like
165 nonexistent ones) before asking the back end again.
166 Default: 15
168 filter_users, filter_groups (string)
170 Exclude certain users from being fetched from the sss NSS database.
171 This is particularly useful for system accounts. This option can
172 also be set per-domain or include fully-qualified names to filter
173 only users from the particular domain.
174 Default: root
176 filter_users_in_groups (bool)
178 If you want filtered user still be group members set this option to
179 false.
180 Default: true
182 override_homedir (string)
184 Override the user's home directory. You can either provide an
185 absolute value or a template. In the template, the following
186 sequences are substituted:
187 %u
189 login name
190 %U
192 UID number
193 %d
195 domain name
196 %f
198 fully qualified user name (user@domain)
199 %%
201 a literal '%'
202 This option can also be set per-domain.
204 allowed_shells (string)
206 Restrict user shell to one of the listed values. The order of
207 evaluation is:
208 1. If the shell is present in “/etc/shells”, it is used.
210 2. If the shell is in the allowed_shells list but not in
212 “/etc/shells”, use the value of the shell_fallback parameter.
213 3. If the shell is not in the allowed_shells list and not in
215 “/etc/shells”, a nologin shell is used.
216 An empty string for shell is passed as-is to libc.
218 The “/etc/shells” is only read on SSSD start up, which means that a
220 restart of the SSSD is required in case a new shell is installed.
221 Default: Not set. The user shell is automatically used.
223 vetoed_shells (string)
225 Replace any instance of these shells with the shell_fallback
226 shell_fallback (string)
228 The default shell to use if an allowed shell is not installed on
229 the machine.
230 Default: /bin/sh
232 PAM configuration options
234 These options can be used to configure the Pluggable Authentication
235 Module (PAM) service.
236 offline_credentials_expiration (integer)
238 If the authentication provider is offline, how long should we allow
239 cached logins (in days since the last successful online login).
240 Default: 0 (No limit)
242 offline_failed_login_attempts (integer)
244 If the authentication provider is offline, how many failed login
245 attempts are allowed.
246 Default: 0 (No limit)
248 offline_failed_login_delay (integer)
250 The time in minutes which has to pass after
251 offline_failed_login_attempts has been reached before a new login
252 attempt is possible.
253 If set to 0 the user cannot authenticate offline if
255 offline_failed_login_attempts has been reached. Only a successful
256 online authentication can enable enable offline authentication
257 again.
258 Default: 5
260 pam_verbosity (integer)
262 Controls what kind of messages are shown to the user during
263 authentication. The higher the number to more messages are
264 displayed.
265 Currently sssd supports the following values:
267 0: do not show any message
270 1: show only important messages
273 2: show informational messages
276 3: show all messages and debug information
279 Default: 1
281 pam_id_timeout (integer)
283 For any PAM request while SSSD is online, the SSSD will attempt to
284 immediately update the cached identity information for the user in
285 order to ensure that authentication takes place with the latest
286 information.
287 A complete PAM conversation may perform multiple PAM requests, such
289 as account management and session opening. This option controls (on
290 a per-client-application basis) how long (in seconds) we can cache
291 the identity information to avoid excessive round-trips to the
292 identity provider.
293 Default: 5
295 pam_pwd_expiration_warning (integer)
297 Display a warning N days before the password expires.
298 Please note that the backend server has to provide information
300 about the expiration time of the password. If this information is
301 missing, sssd cannot display a warning.
302 Default: 7
304
306 These configuration options can be present in a domain configuration
307 section, that is, in a section called “[domain/NAME]”
308 min_id,max_id (integer)
310 UID and GID limits for the domain. If a domain contains an entry
311 that is outside these limits, it is ignored.
312 For users, this affects the primary GID limit. The user will not be
314 returned to NSS if either the UID or the primary GID is outside the
315 range. For non-primary group memberships, those that are in range
316 will be reported as expected.
317 Default: 1 for min_id, 0 (no limit) for max_id
319 timeout (integer)
321 Timeout in seconds between heartbeats for this domain. This is used
322 to ensure that the backend process is alive and capable of
323 answering requests.
324 Default: 10
326 enumerate (bool)
328 Determines if a domain can be enumerated. This parameter can have
329 one of the following values:
330 TRUE = Users and groups are enumerated
332 FALSE = No enumerations for this domain
334 Default: FALSE
336 Note: Enabling enumeration has a moderate performance impact on
338 SSSD while enumeration is running. It may take up to several
339 minutes after SSSD startup to fully complete enumerations. During
340 this time, individual requests for information will go directly to
341 LDAP, though it may be slow, due to the heavy enumeration
342 processing.
343 While the first enumeration is running, requests for the complete
345 user or group lists may return no results until it completes.
346 Further, enabling enumeration may increase the time necessary to
348 detect network disconnection, as longer timeouts are required to
349 ensure that enumeration lookups are completed successfully. For
350 more information, refer to the man pages for the specific
351 id_provider in use.
352 entry_cache_timeout (integer)
354 How many seconds should nss_sss consider entries valid before
355 asking the backend again
356 Default: 5400
358 cache_credentials (bool)
360 Determines if user credentials are also cached in the local LDB
361 cache
362 Default: FALSE
364 account_cache_expiration (integer)
366 Number of days entries are left in cache after last successful
367 login before being removed during a cleanup of the cache. 0 means
368 keep forever. The value of this parameter must be greater than or
369 equal to offline_credentials_expiration.
370 Default: 0 (unlimited)
372 id_provider (string)
374 The Data Provider identity backend to use for this domain.
375 Supported backends:
377 proxy: Support a legacy NSS provider
379 local: SSSD internal local provider
381 ldap: LDAP provider
383 use_fully_qualified_names (bool)
385 If set to TRUE, all requests to this domain must use fully
386 qualified names. For example, if used in LOCAL domain that contains
387 a "test" user, getent passwd test wouldn't find the user while
388 getent passwd test@LOCAL would.
389 Default: FALSE
391 auth_provider (string)
393 The authentication provider used for the domain. Supported auth
394 providers are:
395 “ldap” for native LDAP authentication. See sssd-ldap(5) for more
398 information on configuring LDAP.
399 “krb5” for Kerberos authentication. See sssd-krb5(5) for more
402 information on configuring Kerberos.
403 “proxy” for relaying authentication to some other PAM target.
406 “none” disables authentication explicitly.
409 Default: “id_provider” is used if it is set and can handle
411 authentication requests.
412 access_provider (string)
414 The access control provider used for the domain. There are two
415 built-in access providers (in addition to any included in installed
416 backends) Internal special providers are:
417 “permit” always allow access.
420 “deny” always deny access.
423 “simple” access control based on access or deny lists. See sssd-
426 simple(5) for more information on configuring the simple access
427 module.
428 Default: “permit”
430 chpass_provider (string)
432 The provider which should handle change password operations for the
433 domain. Supported change password providers are:
434 “ipa” to change a password stored in an IPA server. See sssd-ipa(5)
437 for more information on configuring IPA.
438 “ldap” to change a password stored in a LDAP server. See sssd-
441 ldap(5) for more information on configuring LDAP.
442 “krb5” to change the Kerberos password. See sssd-krb5(5) for more
445 information on configuring Kerberos.
446 “proxy” for relaying password changes to some other PAM target.
449 “none” disallows password changes explicitly.
452 Default: “auth_provider” is used if it is set and can handle change
454 password requests.
455 lookup_family_order (string)
457 Provides the ability to select preferred address family to use when
458 performing DNS lookups.
459 Supported values:
461 ipv4_first: Try looking up IPv4 address, if that fails, try IPv6
463 ipv4_only: Only attempt to resolve hostnames to IPv4 addresses.
465 ipv6_first: Try looking up IPv6 address, if that fails, try IPv4
467 ipv6_only: Only attempt to resolve hostnames to IPv6 addresses.
469 Default: ipv4_first
471 dns_resolver_timeout (integer)
473 Defines the amount of time (in seconds) to wait for a reply from
474 the DNS resolver before assuming that it is unreachable. If this
475 timeout is reached, the domain will continue to operate in offline
476 mode.
477 Default: 5
479 dns_discovery_domain (string)
481 If service discovery is used in the back end, specifies the domain
482 part of the service discovery DNS query.
483 Default: Use the domain part of machine's hostname
485 override_gid (integer)
487 Override the primary GID value with the one specified.
488 Options valid for proxy domains.
490 proxy_pam_target (string)
492 The proxy target PAM proxies to.
493 Default: not set by default, you have to take an existing pam
495 configuration or create a new one and add the service name here.
496 proxy_lib_name (string)
498 The name of the NSS library to use in proxy domains. The NSS
499 functions searched for in the library are in the form of
500 _nss_$(libName)_$(function), for example _nss_files_getpwent.
501 The local domain section
503 This section contains settings for domain that stores users and groups
504 in SSSD native database, that is, a domain that uses id_provider=local.
505 Section parameters
507 default_shell (string)
509 The default shell for users created with SSSD userspace tools.
510 Default: /bin/bash
512 base_directory (string)
514 The tools append the login name to base_directory and use that as
515 the home directory.
516 Default: /home
518 create_homedir (bool)
520 Indicate if a home directory should be created by default for new
521 users. Can be overridden on command line.
522 Default: TRUE
524 remove_homedir (bool)
526 Indicate if a home directory should be removed by default for
527 deleted users. Can be overridden on command line.
528 Default: TRUE
530 homedir_umask (integer)
532 Used by sss_useradd(8) to specify the default permissions on a
533 newly created home directory.
534 Default: 077
536 skel_dir (string)
538 The skeleton directory, which contains files and directories to be
539 copied in the user's home directory, when the home directory is
540 created by sss_useradd(8)
541 Default: /etc/skel
543 mail_dir (string)
545 The mail spool directory. This is needed to manipulate the mailbox
546 when its corresponding user account is modified or deleted. If not
547 specified, a default value is used.
548 Default: /var/mail
550 userdel_cmd (string)
552 The command that is run after a user is removed. The command us
553 passed the username of the user being removed as the first and only
554 parameter. The return code of the command is not taken into
555 account.
556 Default: None, no command is run
558
560 The following example shows a typical SSSD config. It does not describe
561 configuration of the domains themselves - refer to documentation on
562 configuring domains for more details.
563 [sssd]
565 domains = LDAP
566 services = nss, pam
567 config_file_version = 2
568 [nss]
570 filter_groups = root
571 filter_users = root
572 [pam]
574 [domain/LDAP]
576 id_provider = ldap
577 ldap_uri = ldap://ldap.example.com
578 ldap_search_base = dc=example,dc=com
579 auth_provider = krb5
581 krb5_server = kerberos.example.com
582 krb5_realm = EXAMPLE.COM
583 cache_credentials = true
584 min_id = 10000
586 max_id = 20000
587 enumerate = False
588
591 sssd-ldap(5), sssd-krb5(5), sss_groupadd(8), sss_groupdel(8),
592 sss_groupmod(8), sss_useradd(8), sss_userdel(8), sss_usermod(8),
593 pam_sss(8).
594
596 The SSSD upstream - http://fedorahosted.org/sssd
597SSSD 08/05/2011 SSSD.CONF(5)