1nslcd.conf(5) System Manager's Manual nslcd.conf(5)
2
6 nslcd.conf - configuration file for LDAP nameservice daemon
7
9 The nss-pam-ldapd package allows LDAP directory servers to be used as a
10 primary source of name service information. (Name service information
11 typically includes users, hosts, groups, and other such data histori‐
12 cally stored in flat files or NIS.)
13 The file nslcd.conf contains the configuration information for running
15 nslcd (see nslcd(8)). The file contains options, one on each line,
16 defining the way NSS lookups and PAM actions are mapped to LDAP
17 lookups.
18
20 RUNTIME OPTIONS
21 threads NUM
22 Specifies the number of threads to start that can handle
23 requests and perform LDAP queries. Each thread opens a separate
24 connection to the LDAP server. The default is to start 5
25 threads.
26 uid UID
28 This specifies the user id with which the daemon should be run.
29 This can be a numerical id or a symbolic value. If no uid is
30 specified no attempt to change the user will be made. Note that
31 you should use values that don't need LDAP to resolve.
32 gid GID
34 This specifies the group id with which the daemon should be run.
35 This can be a numerical id or a symbolic value. If no gid is
36 specified no attempt to change the group will be made. Note
37 that you should use values that don't need LDAP to resolve.
38 log SCHEME [LEVEL]
40 This option controls the way logging is done. The SCHEME argu‐
41 ment may either be none, syslog or an absolute file name. The
42 LEVEL argument is optional and specifies the log level. The log
43 level may be one of: crit, error, warning, notice, info or
44 debug. The default log level is info. All messages with the
45 specified loglevel or higher are logged. This option can be
46 supplied multiple times. If this option is omitted syslog info
47 is assumed.
48 GENERAL CONNECTION OPTIONS
50 uri URI ...
51 Specifies the LDAP URI of the server to connect to. The URI
52 scheme may be ldap, ldapi or ldaps, specifying LDAP over TCP,
53 ICP or SSL respectively (if supported by the LDAP library).
54 Alternatively, the value DNS may be used to try to lookup the
56 server using DNS SRV records. By default the current domain is
57 used but another domain can be queried by using the DNS:DOMAIN
58 syntax.
59 When using the ldapi scheme, %2f should be used to escape
61 slashes (e.g. ldapi://%2fvar%2frun%2fslapd%2fldapi/), although
62 most of the time this should not be needed.
63 This option may be specified multiple times and/or with more
65 URIs on the line, separated by space. Normally, only the first
66 server will be used with the following servers as fall-back (see
67 bind_timelimit below).
68 If LDAP lookups are used for host name resolution, any host
70 names should be specified as an IP address or name that can be
71 resolved without using LDAP.
72 ldap_version VERSION
74 Specifies the version of the LDAP protocol to use. The default
75 is to use the maximum version supported by the LDAP library.
76 binddn DN
78 Specifies the distinguished name with which to bind to the
79 directory server for lookups. The default is to bind anony‐
80 mously.
81 bindpw PASSWORD
83 Specifies the credentials with which to bind. This option is
84 only applicable when used with binddn above. If you set this
85 option you should consider changing the permissions of the
86 nslcd.conf file to only grant access to the root user.
87 rootpwmoddn DN
89 Specifies the distinguished name to use when the root user tries
90 to modify a user's password using the PAM module.
91 Note that currently this DN needs to exist as a real entry in
93 the LDAP directory.
94 rootpwmodpw PASSWORD
96 Specifies the credentials with which to bind if the root user
97 tries to change a user's password. This option is only applica‐
98 ble when used with rootpwmoddn above. If this option is not
99 specified the PAM module prompts the user for this password. If
100 you set this option you should consider changing the permissions
101 of the nslcd.conf file to only grant access to the root user.
102 SASL AUTHENTICATION OPTIONS
104 sasl_mech MECHANISM
105 Specifies the SASL mechanism to be used when performing SASL
106 authentication.
107 sasl_realm REALM
109 Specifies the SASL realm to be used when performing SASL authen‐
110 tication.
111 sasl_authcid AUTHCID
113 Specifies the authentication identity to be used when performing
114 SASL authentication.
115 sasl_authzid AUTHZID
117 Specifies the authorization identity to be used when performing
118 SASL authentication. Must be specified in one of the formats:
119 dn:<distinguished name> or u:<username>.
120 sasl_secprops PROPERTIES
122 Specifies Cyrus SASL security properties. Allowed values are
123 described in the ldap.conf(5) manual page.
124 sasl_canonicalize yes|no
126 Determines whether the LDAP server host name should be canoni‐
127 calised. If this is set to yes the LDAP library will do a
128 reverse host name lookup. By default, it is left up to the LDAP
129 library whether this check is performed or not.
130 KERBEROS AUTHENTICATION OPTIONS
132 krb5_ccname NAME
133 Set the name for the GSS-API Kerberos credentials cache.
134 SEARCH/MAPPING OPTIONS
136 base [MAP] DN
137 Specifies the base distinguished name (DN) to use as search
138 base. This option may be supplied multiple times and all speci‐
139 fied bases will be searched.
140 A global search base may be specified or a MAP-specific one. If
142 no MAP-specific search bases are defined the global ones are
143 used.
144 If, instead of a DN, the value DOMAIN is specified, the host's
146 DNS domain is used to construct a search base.
147 If this value is not defined an attempt is made to look it up in
149 the configured LDAP server. Note that if the LDAP server is
150 unavailable during start-up nslcd will not start.
151 scope [MAP] sub[tree]|one[level]|base|children
153 Specifies the search scope (subtree, onelevel, base or chil‐
154 dren). The default scope is subtree; base scope is almost never
155 useful for name service lookups; children scope is not supported
156 on all servers.
157 deref never|searching|finding|always
159 Specifies the policy for dereferencing aliases. The default
160 policy is to never dereference aliases.
161 referrals yes|no
163 Specifies whether automatic referral chasing should be enabled.
164 The default behaviour is to chase referrals.
165 filter MAP FILTER
167 The FILTER is an LDAP search filter to use for a specific map.
168 The default filter is a basic search on the objectClass for the
169 map (e.g. (objectClass=posixAccount)).
170 map MAP ATTRIBUTE NEWATTRIBUTE
172 This option allows for custom attributes to be looked up instead
173 of the default RFC 2307 attributes. The MAP may be one of the
174 supported maps below. The ATTRIBUTE is the one as used in RFC
175 2307 (e.g. userPassword, ipProtocolNumber, macAddress, etc.).
176 The NEWATTRIBUTE may be any attribute as it is available in the
177 directory.
178 If the NEWATTRIBUTE is presented in quotes (") it is treated as
180 an expression which will be evaluated to build up the actual
181 value used. See the section on attribute mapping expressions
182 below for more details.
183 Only some attributes for group, passwd and shadow entries may be
185 mapped with an expression (because other attributes may be used
186 in search filters). For group entries only the userPassword
187 attribute may be mapped with an expression. For passwd entries
188 the following attributes may be mapped with an expression: user‐
189 Password, gidNumber, gecos, homeDirectory and loginShell. For
190 shadow entries the following attributes may be mapped with an
191 expression: userPassword, shadowLastChange, shadowMin, shadow‐
192 Max, shadowWarning, shadowInactive, shadowExpire and shadowFlag.
193 The uidNumber and gidNumber attributes in the passwd and group
195 maps may be mapped to the objectSid followed by the domain SID
196 to derive numeric user and group ids from the SID (e.g. object‐
197 Sid:S-1-5-21-3623811015-3361044348-30300820).
198 By default all userPassword attributes are mapped to the
200 unmatchable password ("*") to avoid accidentally leaking pass‐
201 word information.
202 TIMING/RECONNECT OPTIONS
204 bind_timelimit SECONDS
205 Specifies the time limit (in seconds) to use when connecting to
206 the directory server. This is distinct from the time limit
207 specified in timelimit and affects the set-up of the connection
208 only. Note that not all LDAP client libraries have support for
209 setting the connection time out. The default bind_timelimit is
210 10 seconds.
211 timelimit SECONDS
213 Specifies the time limit (in seconds) to wait for a response
214 from the LDAP server. A value of zero (0), which is the
215 default, is to wait indefinitely for searches to be completed.
216 idle_timelimit SECONDS
218 Specifies the period if inactivity (in seconds) after which the
219 connection to the LDAP server will be closed. The default is
220 not to time out connections.
221 reconnect_sleeptime SECONDS
223 Specifies the number of seconds to sleep when connecting to all
224 LDAP servers fails. By default 1 second is waited between the
225 first failure and the first retry.
226 reconnect_retrytime SECONDS
228 Specifies the time after which the LDAP server is considered to
229 be permanently unavailable. Once this time is reached retries
230 will be done only once per this time period. The default value
231 is 10 seconds.
232 Note that the reconnect logic as described above is the mechanism that
234 is used between nslcd and the LDAP server. The mechanism between the
235 NSS and PAM client libraries on one end and nslcd on the other is sim‐
236 pler with a fixed compiled-in time out of a 10 seconds for writing to
237 nslcd and a time out of 60 seconds for reading answers. nslcd itself
238 has a read time out of 0.5 seconds and a write time out of 60 seconds.
239 SSL/TLS OPTIONS
241 ssl on|off|start_tls
242 Specifies whether to use SSL/TLS or not (the default is not to).
243 If start_tls is specified then StartTLS is used rather than raw
244 LDAP over SSL. Not all LDAP client libraries support both SSL,
245 StartTLS and all related configuration options.
246 tls_reqcert never|allow|try|demand|hard
248 Specifies what checks to perform on a server-supplied certifi‐
249 cate. The meaning of the values is described in the
250 ldap.conf(5) manual page. At least one of tls_cacertdir and
251 tls_cacertfile is required if peer verification is enabled.
252 tls_cacertdir PATH
254 Specifies the directory containing X.509 certificates for peer
255 authentication. This parameter is ignored when using GnuTLS.
256 On Debian OpenLDAP is linked against GnuTLS.
257 tls_cacertfile PATH
259 Specifies the path to the X.509 certificate for peer authentica‐
260 tion.
261 tls_randfile PATH
263 Specifies the path to an entropy source. This parameter is
264 ignored when using GnuTLS. On Debian OpenLDAP is linked against
265 GnuTLS.
266 tls_ciphers CIPHERS
268 Specifies the ciphers to use for TLS. See your TLS implementa‐
269 tion's documentation for further information.
270 tls_cert PATH
272 Specifies the path to the file containing the local certificate
273 for client TLS authentication.
274 tls_key PATH
276 Specifies the path to the file containing the private key for
277 client TLS authentication.
278 OTHER OPTIONS
280 pagesize NUMBER
281 Set this to a number greater than 0 to request paged results
282 from the LDAP server in accordance with RFC2696. The default
283 (0) is to not request paged results.
284 This is useful for LDAP servers that contain a lot of entries
286 (e.g. more than 500) and limit the number of entries that are
287 returned with one request. For OpenLDAP servers you may need to
288 set sizelimit size.prtotal=unlimited for allowing more entries
289 to be returned over multiple pages.
290 nss_initgroups_ignoreusers user1,user2,...
292 This option prevents group membership lookups through LDAP for
293 the specified users. This can be useful in case of unavailabil‐
294 ity of the LDAP server. This option may be specified multiple
295 times.
296 Alternatively, the value ALLLOCAL may be used. With that value
298 nslcd builds a full list of non-LDAP users on startup.
299 nss_min_uid UID
301 This option ensures that LDAP users with a numeric user id lower
302 than the specified value are ignored. Also requests for users
303 with a lower user id are ignored.
304 nss_uid_offset NUMBER
306 This option specifies an offset that is added to all LDAP
307 numeric user ids. This can be used to avoid user id collisions
308 with local users or, when using objectSid attributes, for com‐
309 patibility reasons.
310 The value from the nss_min_uid option is evaluated after apply‐
312 ing the offset.
313 nss_gid_offset NUMBER
315 This option specifies an offset that is added to all LDAP
316 numeric group ids. This can be used to avoid user id collisions
317 with local groups or, when using objectSid attributes, for com‐
318 patibility reasons.
319 nss_nested_groups yes|no
321 If this option is set, the member attribute of a group may point
322 to another group. Members of nested groups are also returned in
323 the higher level group and parent groups are returned when find‐
324 ing groups for a specific user. The default is not to perform
325 extra searches for nested groups.
326 nss_getgrent_skipmembers yes|no
328 If this option is set, the group member list is not retrieved
329 when looking up groups. Lookups for finding which groups a user
330 belongs to will remain functional so the user will likely still
331 get the correct groups assigned on login.
332 This can offer a speed-up on systems that have very large
334 groups. It has the downside of returning inconsistent informa‐
335 tion about group membership which may confuse some applications.
336 This option is not recommended for most configurations.
337 nss_disable_enumeration yes|no
339 If this option is set, functions which cause all user/group
340 entries to be loaded (getpwent(), getgrent(), setspent()) from
341 the directory will not succeed in doing so. Applications that
342 depend on being able to sequentially read all users and/or
343 groups may fail to operate correctly.
344 This can dramatically reduce LDAP server load in situations
346 where there are a great number of users and/or groups. This is
347 typically used in situations where user/program access to enu‐
348 merate the entire directory is undesirable, and changing the
349 behavior of the user/program is not possible. This option is
350 not recommended for most configurations.
351 validnames REGEX
353 This option can be used to specify how user and group names are
354 verified within the system. This pattern is used to check all
355 user and group names that are requested and returned from LDAP.
356 The regular expression should be specified as a POSIX extended
358 regular expression. The expression itself needs to be separated
359 by slash (/) characters and the 'i' flag may be appended at the
360 end to indicate that the match should be case-insensetive. The
361 default value is /^[a-z0-9._@$()]([a-z0-9._@$()
362 \\~-]*[a-z0-9._@$()~-])?$/i
363 ignorecase yes|no
365 This specifies whether or not to perform searches for group,
366 netgroup, passwd, protocols, rpc, services and shadow maps using
367 case-insensitive matching. Setting this to yes could open up
368 the system to authorisation bypass vulnerabilities and introduce
369 nscd cache poisoning vulnerabilities which allow denial of ser‐
370 vice. The default is to perform case-sensitve filtering of LDAP
371 search results for the above maps.
372 pam_authc_ppolicy yes|no
374 This option specifies whether password policy controls are
375 requested and handled from the LDAP server when performing user
376 authentication. By default the controls are requested and han‐
377 dled if available.
378 pam_authc_search FILTER
380 By default nslcd performs an LDAP search with the user's creden‐
381 tials after BIND (authentication) to ensure that the BIND opera‐
382 tion was successful. The default search is a simple check to
383 see if the user's DN exists.
384 A search filter can be specified that will be used instead. The
386 same substitutions as with the pam_authz_search option will be
387 performed and the search should at least return one entry.
388 The value BASE may be used to force the default search for the
390 user DN.
391 The value NONE may be used to indicate that no search should be
393 performed after BIND. Note that some LDAP servers do not always
394 return a correct error code as a result of a failed BIND opera‐
395 tion (e.g. when an empty password is supplied).
396 pam_authz_search FILTER
398 This option allows flexible fine tuning of the authorisation
399 check that should be performed. The search filter specified is
400 executed and if any entries match, access is granted, otherwise
401 access is denied.
402 The search filter can contain the following variable references:
404 $username, $service, $ruser, $rhost, $tty, $hostname, $fqdn,
405 $domain, $dn, and $uid. These references are substituted in the
406 search filter using the same syntax as described in the section
407 on attribute mapping expressions below.
408 For example, to check that the user has a proper authorizedSer‐
410 vice value if the attribute is present (this almost emulates the
411 pam_check_service_attr option in PADL's pam_ldap):
412 (&(objectClass=posixAccount)(uid=$username)(|(authorizedService=$service)(!(authorizedService=*))))
414 The pam_check_host_attr option can be emulated with:
416 (&(objectClass=posixAccount)(uid=$username)(|(host=$hostname)(host=$fqdn)(host=\\*)))
418 This option may be specified multiple times and all specified
420 searches should at least return one entry for access to be
421 granted.
422 pam_password_prohibit_message "MESSAGE"
424 If this option is set password modification using pam_ldap will
425 be denied and the specified message will be presented to the
426 user instead. The message can be used to direct the user to an
427 alternative means of changing their password.
428 reconnect_invalidate DB,DB,...
430 If this option is set, nslcd will try to flush the specified
431 external caches on start-up and whenever a connection to the
432 LDAP server is re-established after an error.
433 DB can refer to one of the nsswitch maps, in which case nscd is
435 contacted to flush its cache for the specified database. If DB
436 is nfsidmap, nfsidmap is contacted to clear its cache.
437 Using this option ensures that external caches are cleared of
439 incorrect information (typically the absence of users) that may
440 be present due to unavailability of the LDAP server.
441 cache CACHE TIME [TIME]
443 Configure the time entries are kept in the specified internal
444 cache.
445 The first TIME value specifies the time to keep found entries in
447 the cache. The second TIME value specifies to the time to
448 remember that a particular entry was not found. If the second
449 parameter is absent, it is assumed to be the same as the first.
450 Time values are specified as a number followed by an s for sec‐
452 onds, m for minutes, h for hours or d for days. Use 0 or off to
453 disable the cache.
454 Currently, only the dn2uid cache is supported that is used to
456 remember DN to username lookups that are used when the member
457 attribute is used. The default time value for this cache is
458 15m.
459
461 The following maps are supported. They are referenced as MAP in the
462 options above.
463 alias[es]
465 Mail aliases. Note that most mail servers do not use the NSS
466 interface for requesting mail aliases and parse /etc/aliases on
467 their own.
468 ether[s]
470 Ethernet numbers (mac addresses).
471 group Posix groups.
473 host[s]
475 Host names.
476 netgroup
478 Host and user groups used for access control.
479 network[s]
481 Network numbers.
482 passwd Posix users.
484 protocol[s]
486 Protocol definitions (like in /etc/protocols).
487 rpc Remote procedure call names and numbers.
489 service[s]
491 Network service names and numbers.
492 shadow Shadow user password information.
494
496 For some attributes a mapping expression may be used to construct the
497 resulting value. This is currently only possible for attributes that
498 do not need to be used in search filters. The expressions are a subset
499 of the double quoted string expressions in the Bourne (POSIX) shell.
500 Instead of variable substitution, attribute lookups are done on the
501 current entry and the attribute value is substituted. The following
502 expressions are supported:
503 ${attr} (or $attr for short)
505 will substitute the value of the attribute
506 ${attr:-word}
508 (use default) will substitbute the value of the attribute or, if
509 the attribute is not set or empty substitute the word
510 ${attr:+word}
512 (use alternative) will substitute word if attribute is set, oth‐
513 erwise substitute the empty string
514 ${attr:offset:length}
516 will substitute length characters (actually bytes) starting from
517 position offset (which is counted starting at zero); the substi‐
518 tuted string is truncated if it is too long; in particular, it
519 can be of length zero (if length is zero or offset falls out of
520 the original string)
521 ${attr#word}
523 remove the shortest possible match of word from the left of the
524 attribute value
525 ${attr##word}
527 remove the longest possible match of word from the left of the
528 attribute value (pynslcd only)
529 ${attr%word}
531 remove the shortest possible match of word from the right of the
532 attribute value (pynslcd only)
533 ${attr%%word}
535 remove the longest possible match of word from the right of the
536 attribute value (pynslcd only)
537 Only the # matching expression is supported in nslcd and only with the
539 ? wildcard symbol. The pynslcd implementation supports full matching.
540 Quote ("), dollar ($) and backslash (\) characters should be escaped
542 with a backslash (\).
543 The expressions are inspected to automatically fetch the appropriate
545 attributes from LDAP. Some examples to demonstrate how these expres‐
546 sions may be used in attribute mapping:
547 "${shadowFlag:-0}"
549 use the shadowFlag attribute, using the value 0 as default
550 "${homeDirectory:-/home/$uid}"
552 use the uid attribute to build a homeDirectory value if that
553 attribute is missing
554 "${isDisabled:+100}"
556 if the isDisabled attribute is set, return 100, otherwise leave
557 value empty
558 "${userPassword#{crypt\}}"
560 strip the {crypt} prefix from the userPassword attribute,
561 returning the raw hash value
562
564 /etc/nslcd.conf
565 the main configuration file
566 /etc/nsswitch.conf
568 Name Service Switch configuration file
569
571 nslcd(8), nsswitch.conf(5)
572
574 This manual was written by Arthur de Jong <arthur@arthurdejong.org> and
575 is based on the nss_ldap(5) manual developed by PADL Software Pty Ltd.
576Version 0.9.10 Sep 2018 nslcd.conf(5)