1nslcd.conf(5)               System Manager's Manual              nslcd.conf(5)
2
3
4

NAME

6       nslcd.conf - configuration file for LDAP nameservice daemon
7

DESCRIPTION

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
14       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

OPTIONS

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
27       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
33       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
39       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
49   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
55              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
60              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
64              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
69              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
73       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
77       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
82       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
88       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
92              Note that currently this DN needs to exist as a  real  entry  in
93              the LDAP directory.
94
95       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
103   SASL AUTHENTICATION OPTIONS
104       sasl_mech MECHANISM
105              Specifies the SASL mechanism to be  used  when  performing  SASL
106              authentication.
107
108       sasl_realm REALM
109              Specifies the SASL realm to be used when performing SASL authen‐
110              tication.
111
112       sasl_authcid AUTHCID
113              Specifies the authentication identity to be used when performing
114              SASL authentication.
115
116       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
121       sasl_secprops PROPERTIES
122              Specifies  Cyrus  SASL  security properties.  Allowed values are
123              described in the ldap.conf(5) manual page.
124
125       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
131   KERBEROS AUTHENTICATION OPTIONS
132       krb5_ccname NAME
133              Set the name for the GSS-API Kerberos credentials cache.
134
135   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
141              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
145              If,  instead  of a DN, the value DOMAIN is specified, the host's
146              DNS domain is used to construct a search base.
147
148              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
152       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
158       deref never|searching|finding|always
159              Specifies  the  policy  for  dereferencing aliases.  The default
160              policy is to never dereference aliases.
161
162       referrals yes|no
163              Specifies whether automatic referral chasing should be  enabled.
164              The default behaviour is to chase referrals.
165
166       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
171       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
179              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
184              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
194              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
199              By  default  all  userPassword  attributes  are  mapped  to  the
200              unmatchable  password  ("*") to avoid accidentally leaking pass‐
201              word information.
202
203   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
212       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
217       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
222       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
227       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
233       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
240   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
247       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
253       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
258       tls_cacertfile PATH
259              Specifies the path to the X.509 certificate for peer authentica‐
260              tion.
261
262       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
267       tls_ciphers CIPHERS
268              Specifies the ciphers to use for TLS.  See your TLS  implementa‐
269              tion's documentation for further information.
270
271       tls_cert PATH
272              Specifies  the path to the file containing the local certificate
273              for client TLS authentication.
274
275       tls_key PATH
276              Specifies the path to the file containing the  private  key  for
277              client TLS authentication.
278
279   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
285              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
291       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
297              Alternatively, the value ALLLOCAL may be used. With  that  value
298              nslcd builds a full list of non-LDAP users on startup.
299
300       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
305       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
311              The value from the nss_min_uid option is evaluated after  apply‐
312              ing the offset.
313
314       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
320       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
327       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
333              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
338       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
345              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
352       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
357              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
364       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
373       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
379       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
385              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
389              The value BASE may be used to force the default search  for  the
390              user DN.
391
392              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
397       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
403              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
409              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
413              (&(objectClass=posixAccount)(uid=$username)(|(authorizedService=$service)(!(authorizedService=*))))
414
415              The pam_check_host_attr option can be emulated with:
416
417              (&(objectClass=posixAccount)(uid=$username)(|(host=$hostname)(host=$fqdn)(host=\\*)))
418
419              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
423       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
429       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
434              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
438              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
442       cache CACHE TIME [TIME]
443              Configure the time entries are kept in  the  specified  internal
444              cache.
445
446              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
451              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
455              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

SUPPORTED MAPS

461       The  following  maps  are  supported. They are referenced as MAP in the
462       options above.
463
464       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
469       ether[s]
470              Ethernet numbers (mac addresses).
471
472       group  Posix groups.
473
474       host[s]
475              Host names.
476
477       netgroup
478              Host and user groups used for access control.
479
480       network[s]
481              Network numbers.
482
483       passwd Posix users.
484
485       protocol[s]
486              Protocol definitions (like in /etc/protocols).
487
488       rpc    Remote procedure call names and numbers.
489
490       service[s]
491              Network service names and numbers.
492
493       shadow Shadow user password information.
494

ATTRIBUTE MAPPING EXPRESSIONS

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
504       ${attr} (or $attr for short)
505              will substitute the value of the attribute
506
507       ${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
511       ${attr:+word}
512              (use alternative) will substitute word if attribute is set, oth‐
513              erwise substitute the empty string
514
515       ${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
522       ${attr#word}
523              remove the shortest possible match of word from the left of  the
524              attribute value
525
526       ${attr##word}
527              remove  the  longest possible match of word from the left of the
528              attribute value (pynslcd only)
529
530       ${attr%word}
531              remove the shortest possible match of word from the right of the
532              attribute value (pynslcd only)
533
534       ${attr%%word}
535              remove  the longest possible match of word from the right of the
536              attribute value (pynslcd only)
537
538       Only the # matching expression is supported in nslcd and only with  the
539       ? wildcard symbol. The pynslcd implementation supports full matching.
540
541       Quote  ("),  dollar  ($) and backslash (\) characters should be escaped
542       with a backslash (\).
543
544       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
548       "${shadowFlag:-0}"
549              use the shadowFlag attribute, using the value 0 as default
550
551       "${homeDirectory:-/home/$uid}"
552              use the uid attribute to build a  homeDirectory  value  if  that
553              attribute is missing
554
555       "${isDisabled:+100}"
556              if  the isDisabled attribute is set, return 100, otherwise leave
557              value empty
558
559       "${userPassword#{crypt\}}"
560              strip  the  {crypt}  prefix  from  the  userPassword  attribute,
561              returning the raw hash value
562

FILES

564       /etc/nslcd.conf
565              the main configuration file
566
567       /etc/nsswitch.conf
568              Name Service Switch configuration file
569

SEE ALSO

571       nslcd(8), nsswitch.conf(5)
572

AUTHOR

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.
576
577
578
579Version 0.9.10                     Sep 2018                      nslcd.conf(5)
Impressum