Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
nslcd.conf(5)		    System Manager's Manual		 nslcd.conf(5)

       nslcd.conf - configuration file for LDAP	nameservice daemon

       The nss-pam-ldapd package allows	LDAP directory servers to be used as a
       primary source of name service information. (Name  service  information
       typically  includes  users, hosts, groups, and other such data histori-
       cally stored in flat files or NIS.)

       The file	nslcd.conf contains the	configuration information for  running
       nslcd  (see  nslcd(8)).	 The  file contains options, one on each line,
       defining	the way	NSS  lookups  and  PAM	actions	 are  mapped  to  LDAP

       threads NUM
	      Specifies	 the  number  of  threads to start that	can handle re-
	      quests and perform LDAP queries.	Each thread opens  a  separate
	      connection  to  the  LDAP	 server.   The	default	 is to start 5

       uid UID
	      This specifies the user id with which the	daemon should be  run.
	      This  can	 be  a numerical id or a symbolic value.  If no	uid is
	      specified	no attempt to change the user will be made.  Note that
	      you should use values that don't need LDAP to resolve.

       gid GID
	      This specifies the group id with which the daemon	should be run.
	      This can be a numerical id or a symbolic value.  If  no  gid  is
	      specified	 no  attempt  to  change the group will	be made.  Note
	      that you should use values that don't need LDAP to resolve.

       log SCHEME [LEVEL]
	      This option controls the way logging is done.  The SCHEME	 argu-
	      ment  may	 either	be none, syslog	or an absolute file name.  The
	      LEVEL argument is	optional and specifies the log level.  The log
	      level  may  be one of: crit, error, warning, notice, info	or de-
	      bug. The default log level is info.  All messages	with the spec-
	      ified  loglevel  or  higher are logged.  This option can be sup-
	      plied multiple times.  If	this option is omitted syslog info  is

       uri URI ...
	      Specifies	 the  LDAP  URI	 of the	server to connect to.  The URI
	      scheme may be ldap, ldapi	or ldaps, specifying  LDAP  over  TCP,
	      ICP or SSL respectively (if supported by the LDAP	library).

	      Alternatively,  the  value  DNS may be used to try to lookup the
	      server using DNS SRV records.  By	default	the current domain  is
	      used  but	 another domain	can be queried by using	the DNS:DOMAIN

	      When using the ldapi  scheme,  %2f  should  be  used  to	escape
	      slashes  (e.g.  ldapi://%2fvar%2frun%2fslapd%2fldapi/), although
	      most of the time this should not be needed.

	      This option may be specified multiple  times  and/or  with  more
	      URIs  on	the line, separated by space. Normally,	only the first
	      server will be used with the following servers as	fall-back (see
	      bind_timelimit below).

	      If  LDAP	lookups	 are  used  for	host name resolution, any host
	      names should be specified	as an IP address or name that  can  be
	      resolved without using LDAP.

       ldap_version VERSION
	      Specifies	 the version of	the LDAP protocol to use.  The default
	      is to use	the maximum version supported by the LDAP library.

       binddn DN
	      Specifies	the distinguished name with which to bind to  the  di-
	      rectory server for lookups.  The default is to bind anonymously.

       bindpw PASSWORD
	      Specifies	 the  credentials  with	which to bind.	This option is
	      only applicable when used	with binddn above.  If	you  set  this
	      option  you  should  consider  changing  the  permissions	of the
	      nslcd.conf file to only grant access to the root user.

       rootpwmoddn DN
	      Specifies	the distinguished name to use when the root user tries
	      to modify	a user's password using	the PAM	module.

	      Note  that  currently  this DN needs to exist as a real entry in
	      the LDAP directory.

       rootpwmodpw PASSWORD
	      Specifies	the credentials	with which to bind if  the  root  user
	      tries to change a	user's password.  This option is only applica-
	      ble when used with rootpwmoddn above.  If	 this  option  is  not
	      specified	the PAM	module prompts the user	for this password.  If
	      you set this option you should consider changing the permissions
	      of the nslcd.conf	file to	only grant access to the root user.

       sasl_mech MECHANISM
	      Specifies	the SASL mechanism to be used when performing SASL au-

       sasl_realm REALM
	      Specifies	the SASL realm to be used when performing SASL authen-

       sasl_authcid AUTHCID
	      Specifies	the authentication identity to be used when performing
	      SASL authentication.

       sasl_authzid AUTHZID
	      Specifies	the authorization identity to be used when  performing
	      SASL  authentication.   Must be specified	in one of the formats:
	      dn:<distinguished	name> or u:<username>.

       sasl_secprops PROPERTIES
	      Specifies	Cyrus SASL security properties.	  Allowed  values  are
	      described	in the ldap.conf(5) manual page.

       sasl_canonicalize yes|no
	      Determines  whether  the LDAP server host	name should be canoni-
	      calised. If this is set to yes the LDAP library will  do	a  re-
	      verse  host  name	lookup.	 By default, it	is left	up to the LDAP
	      library whether this check is performed or not.

       krb5_ccname NAME
	      Set the name for the GSS-API Kerberos credentials	cache.

       base [MAP] DN
	      Specifies	the base distinguished name  (DN)  to  use  as	search
	      base.  This option may be	supplied multiple times	and all	speci-
	      fied bases will be searched.

	      A	global search base may be specified or a MAP-specific one.  If
	      no  MAP-specific	search	bases  are defined the global ones are

	      If, instead of a DN, the value DOMAIN is specified,  the	host's
	      DNS domain is used to construct a	search base.

	      If this value is not defined an attempt is made to look it up in
	      the configured LDAP server. Note that if the LDAP	server is  un-
	      available	during start-up	nslcd will not start.

       scope [MAP] sub[tree]|one[level]|base|children
	      Specifies	 the  search  scope  (subtree, onelevel, base or chil-
	      dren).  The default scope	is subtree; base scope is almost never
	      useful for name service lookups; children	scope is not supported
	      on all servers.

       deref never|searching|finding|always
	      Specifies	the policy for	dereferencing  aliases.	  The  default
	      policy is	to never dereference aliases.

       referrals yes|no
	      Specifies	 whether automatic referral chasing should be enabled.
	      The default behaviour is to chase	referrals.

       filter MAP FILTER
	      The FILTER is an LDAP search filter to use for a	specific  map.
	      The  default filter is a basic search on the objectClass for the
	      map (e.g.	(objectClass=posixAccount)).

	      This option allows for custom attributes to be looked up instead
	      of  the  default RFC 2307	attributes.  The MAP may be one	of the
	      supported	maps below.  The ATTRIBUTE is the one as used  in  RFC
	      2307  (e.g.  userPassword,  ipProtocolNumber, macAddress,	etc.).
	      The NEWATTRIBUTE may be any attribute as it is available in  the

	      If  the NEWATTRIBUTE is presented	in quotes (") it is treated as
	      an expression which will be evaluated to	build  up  the	actual
	      value  used.   See  the section on attribute mapping expressions
	      below for	more details.

	      Only some	attributes for group, passwd and shadow	entries	may be
	      mapped  with an expression (because other	attributes may be used
	      in search	filters).  For group entries only the userPassword at-
	      tribute  may  be	mapped with an expression.  For	passwd entries
	      the following attributes may be mapped with an expression: user-
	      Password,	 gidNumber,  gecos, homeDirectory and loginShell.  For
	      shadow entries the following attributes may be  mapped  with  an
	      expression:  userPassword,  shadowLastChange, shadowMin, shadow-
	      Max, shadowWarning, shadowInactive, shadowExpire and shadowFlag.

	      The uidNumber and	gidNumber attributes in	the passwd  and	 group
	      maps  may	 be mapped to the objectSid followed by	the domain SID
	      to derive	numeric	user and group ids from	the SID	(e.g.  object-

	      By  default  all	userPassword  attributes are mapped to the un-
	      matchable	password ("*") to avoid	accidentally leaking  password

       bind_timelimit SECONDS
	      Specifies	 the time limit	(in seconds) to	use when connecting to
	      the directory server.  This is  distinct	from  the  time	 limit
	      specified	 in timelimit and affects the set-up of	the connection
	      only.  Note that not all LDAP client libraries have support  for
	      setting  the connection time out.	 The default bind_timelimit is
	      10 seconds.

       timelimit SECONDS
	      Specifies	the time limit (in seconds) to	wait  for  a  response
	      from  the	 LDAP  server.	 A value of zero (0), which is the de-
	      fault, is	to wait	indefinitely for searches to be	completed.

       idle_timelimit SECONDS
	      Specifies	the period if inactivity (in seconds) after which  the
	      connection  to  the  LDAP	server will be closed.	The default is
	      not to time out connections.

       reconnect_sleeptime SECONDS
	      Specifies	the number of seconds to sleep when connecting to  all
	      LDAP  servers  fails.  By	default	1 second is waited between the
	      first failure and	the first retry.

       reconnect_retrytime SECONDS
	      Specifies	the time after which the LDAP server is	considered  to
	      be  permanently  unavailable.  Once this time is reached retries
	      will be done only	once per this time period.  The	default	 value
	      is 10 seconds.

       Note  that the reconnect	logic as described above is the	mechanism that
       is used between nslcd and the LDAP server. The  mechanism  between  the
       NSS  and	PAM client libraries on	one end	and nslcd on the other is sim-
       pler with a fixed compiled-in time out of a 10 seconds for  writing  to
       nslcd  and  a time out of 60 seconds for	reading	answers.  nslcd	itself
       has a read time out of 0.5 seconds and a	write time out of 60 seconds.

       ssl on|off|start_tls
	      Specifies	whether	to use SSL/TLS or not (the default is not to).
	      If  start_tls is specified then StartTLS is used rather than raw
	      LDAP over	SSL.  Not all LDAP client libraries support both  SSL,
	      StartTLS and all related configuration options.

       tls_reqcert never|allow|try|demand|hard
	      Specifies	 what  checks to perform on a server-supplied certifi-
	      cate.   The  meaning  of	the  values  is	  described   in   the
	      ldap.conf(5)  manual  page.   At	least one of tls_cacertdir and
	      tls_cacertfile is	required if peer verification is enabled.

       tls_cacertdir PATH
	      Specifies	the directory containing X.509 certificates  for  peer
	      authentication.	This  parameter	 is ignored when using GnuTLS.
	      On Debian	OpenLDAP is linked against GnuTLS.

       tls_cacertfile PATH
	      Specifies	the path to the	X.509 certificate for peer authentica-

       tls_randfile PATH
	      Specifies	 the path to an	entropy	source.	 This parameter	is ig-
	      nored when using GnuTLS.	On Debian OpenLDAP is  linked  against

       tls_ciphers CIPHERS
	      Specifies	 the ciphers to	use for	TLS.  See your TLS implementa-
	      tion's documentation for further information.

       tls_cert	PATH
	      Specifies	the path to the	file containing	the local  certificate
	      for client TLS authentication.

       tls_key PATH
	      Specifies	 the  path  to the file	containing the private key for
	      client TLS authentication.

       pagesize	NUMBER
	      Set this to a number greater than	0  to  request	paged  results
	      from  the	 LDAP  server in accordance with RFC2696.  The default
	      (0) is to	not request paged results.

	      This is useful for LDAP servers that contain a  lot  of  entries
	      (e.g.  more  than	 500) and limit	the number of entries that are
	      returned with one	request.  For OpenLDAP servers you may need to
	      set  sizelimit  size.prtotal=unlimited for allowing more entries
	      to be returned over multiple pages.

       nss_initgroups_ignoreusers user1,user2,...
	      This option prevents group membership lookups through  LDAP  for
	      the  specified users. This can be	useful in case of unavailabil-
	      ity of the LDAP server.  This option may be  specified  multiple

	      Alternatively,  the  value ALLLOCAL may be used. With that value
	      nslcd builds a full list of non-LDAP users on startup.

       nss_min_uid UID
	      This option ensures that LDAP users with a numeric user id lower
	      than  the	 specified  value are ignored. Also requests for users
	      with a lower user	id are ignored.

       nss_uid_offset NUMBER
	      This option specifies an offset that is added to	all  LDAP  nu-
	      meric  user  ids.	  This can be used to avoid user id collisions
	      with local users or, when	using objectSid	attributes,  for  com-
	      patibility reasons.

	      The  value from the nss_min_uid option is	evaluated after	apply-
	      ing the offset.

       nss_gid_offset NUMBER
	      This option specifies an offset that is added to	all  LDAP  nu-
	      meric  group  ids.  This can be used to avoid user id collisions
	      with local groups	or, when using objectSid attributes, for  com-
	      patibility reasons.

       nss_nested_groups yes|no
	      If this option is	set, the member	attribute of a group may point
	      to another group.	 Members of nested groups are also returned in
	      the higher level group and parent	groups are returned when find-
	      ing groups for a specific	user.  The default is not  to  perform
	      extra searches for nested	groups.

       nss_getgrent_skipmembers	yes|no
	      If  this	option	is set,	the group member list is not retrieved
	      when looking up groups.  Lookups for finding which groups	a user
	      belongs  to will remain functional so the	user will likely still
	      get the correct groups assigned on login.

	      This can offer a	speed-up  on  systems  that  have  very	 large
	      groups.	It has the downside of returning inconsistent informa-
	      tion about group membership which	may confuse some applications.
	      This option is not recommended for most configurations.

       nss_disable_enumeration yes|no
	      If  this option is set, functions	which cause all	user/group en-
	      tries to be loaded (getpwent(), getgrent(), setspent()) from the
	      directory	 will  not succeed in doing so.	 Applications that de-
	      pend on being able to sequentially read all users	and/or	groups
	      may fail to operate correctly.

	      This  can	 dramatically  reduce  LDAP  server load in situations
	      where there are a	great number of	users and/or groups.  This  is
	      typically	 used  in situations where user/program	access to enu-
	      merate the entire	directory is undesirable, and changing the be-
	      havior  of the user/program is not possible.  This option	is not
	      recommended for most configurations.

       validnames REGEX
	      This option can be used to specify how user and group names  are
	      verified	within	the  system. This pattern is used to check all
	      user and group names that	are requested and returned from	LDAP.

	      The regular expression should be specified as a  POSIX  extended
	      regular  expression. The expression itself needs to be separated
	      by slash (/) characters and the 'i' flag may be appended at  the
	      end  to indicate that the	match should be	case-insensetive.  The
	      default	   value       is	/^[a-z0-9._@$()]([a-z0-9._@$()

       ignorecase yes|no
	      This  specifies  whether	or  not	to perform searches for	group,
	      netgroup,	passwd,	protocols, rpc,	services and shadow maps using
	      case-insensitive	matching.   Setting  this to yes could open up
	      the system to authorisation bypass vulnerabilities and introduce
	      nscd  cache poisoning vulnerabilities which allow	denial of ser-
	      vice.  The default is to perform case-sensitve filtering of LDAP
	      search results for the above maps.

       pam_authc_ppolicy yes|no
	      This  option  specifies whether password policy controls are re-
	      quested and handled from the LDAP	server	when  performing  user
	      authentication.	By default the controls	are requested and han-
	      dled if available.

       pam_authc_search	FILTER
	      By default nslcd performs	an LDAP	search with the	user's creden-
	      tials after BIND (authentication)	to ensure that the BIND	opera-
	      tion was successful.  The	default	search is a  simple  check  to
	      see if the user's	DN exists.

	      A	search filter can be specified that will be used instead.  The
	      same substitutions as with the pam_authz_search option  will  be
	      performed	and the	search should at least return one entry.

	      The  value  BASE may be used to force the	default	search for the
	      user DN.

	      The value	NONE may be used to indicate that no search should  be
	      performed	after BIND.  Note that some LDAP servers do not	always
	      return a correct error code as a result of a failed BIND	opera-
	      tion (e.g. when an empty password	is supplied).

       pam_authz_search	FILTER
	      This  option  allows  flexible  fine tuning of the authorisation
	      check that should	be performed. The search filter	 specified  is
	      executed	and if any entries match, access is granted, otherwise
	      access is	denied.

	      The search filter	can contain the	following variable references:
	      $username,  $service,  $ruser,  $rhost,  $tty, $hostname,	$fqdn,
	      $dn, and $uid.  These references are substituted in  the	search
	      filter  using the	same syntax as described in the	section	on at-
	      tribute mapping expressions below.

	      For example, to check that the user has a	proper	authorizedSer-
	      vice value if the	attribute is present (this almost emulates the
	      pam_check_service_attr option in PADL's pam_ldap):


	      The pam_check_host_attr option can be emulated with:


	      This option may be specified multiple times  and	all  specified
	      searches	should	at  least  return  one	entry for access to be

       pam_password_prohibit_message "MESSAGE"
	      If this option is	set password modification using	pam_ldap  will
	      be  denied  and  the  specified message will be presented	to the
	      user instead.  The message can be	used to	direct the user	to  an
	      alternative means	of changing their password.

       reconnect_invalidate DB,DB,...
	      If this option is	set, nslcd will	try to flush the specified ex-
	      ternal caches on start-up	and whenever a connection to the  LDAP
	      server is	re-established after an	error.

	      DB  can refer to one of the nsswitch maps, in which case nscd is
	      contacted	to flush its cache for the specified database.	If  DB
	      is nfsidmap, nfsidmap is contacted to clear its cache.

	      Using  this  option  ensures that	external caches	are cleared of
	      incorrect	information (typically the absence of users) that  may
	      be present due to	unavailability of the LDAP server.

       cache CACHE TIME	[TIME]
	      Configure	 the  time  entries are	kept in	the specified internal

	      The first	TIME value specifies the time to keep found entries in
	      the  cache.   The	second TIME value specifies to the time	to re-
	      member that a particular entry was not found.  If	the second pa-
	      rameter is absent, it is assumed to be the same as the first.

	      Time  values are specified as a number followed by an s for sec-
	      onds, m for minutes, h for hours or d for	days.  Use 0 or	off to
	      disable the cache.

	      Currently,  only	the  dn2uid cache is supported that is used to
	      remember DN to username lookups that are used  when  the	member
	      attribute	 is  used.   The  default time value for this cache is

       The following maps are supported. They are referenced as	MAP in the op-
       tions above.

	      Mail  aliases.   Note  that most mail servers do not use the NSS
	      interface	for requesting mail aliases and	parse /etc/aliases  on
	      their own.

	      Ethernet numbers (mac addresses).

       group  Posix groups.

	      Host names.

	      Host and user groups used	for access control.

	      Network numbers.

       passwd Posix users.

	      Protocol definitions (like in /etc/protocols).

       rpc    Remote procedure call names and numbers.

	      Network service names and	numbers.

       shadow Shadow user password information.

       For  some  attributes a mapping expression may be used to construct the
       resulting value.	 This is currently only	possible for  attributes  that
       do not need to be used in search	filters.  The expressions are a	subset
       of the double quoted string expressions in the  Bourne  (POSIX)	shell.
       Instead	of  variable  substitution,  attribute lookups are done	on the
       current entry and the attribute value is	 substituted.	The  following
       expressions are supported:

       ${attr} (or $attr for short)
	      will substitute the value	of the attribute

	      (use default) will substitbute the value of the attribute	or, if
	      the attribute is not set or empty	substitute the word

	      (use alternative)	will substitute	word if	attribute is set, oth-
	      erwise substitute	the empty string

	      will substitute length characters	(actually bytes) starting from
	      position offset (which is	counted	starting at zero); the substi-
	      tuted  string  is	truncated if it	is too long; in	particular, it
	      can be of	length zero (if	length is zero or offset falls out  of
	      the original string)

	      remove  the shortest possible match of word from the left	of the
	      attribute	value

	      remove the longest possible match	of word	from the left  of  the
	      attribute	value (pynslcd only)

	      remove the shortest possible match of word from the right	of the
	      attribute	value (pynslcd only)

	      remove the longest possible match	of word	from the right of  the
	      attribute	value (pynslcd only)

       Only  the # matching expression is supported in nslcd and only with the
       ? wildcard symbol. The pynslcd implementation supports full matching.

       Quote ("), dollar ($) and backslash (\) characters  should  be  escaped
       with a backslash	(\).

       The  expressions	 are  inspected	to automatically fetch the appropriate
       attributes from LDAP.  Some examples to demonstrate how	these  expres-
       sions may be used in attribute mapping:

	      use the shadowFlag attribute, using the value 0 as default

	      use the uid attribute to build a homeDirectory value if that at-
	      tribute is missing

	      if the isDisabled	attribute is set, return 100, otherwise	 leave
	      value empty

	      strip  the  {crypt}  prefix from the userPassword	attribute, re-
	      turning the raw hash value

	      the main configuration file

	      Name Service Switch configuration	file

       nslcd(8), nsswitch.conf(5)

       This manual was written by Arthur de Jong <> and
       is based	on the nss_ldap(5) manual developed by PADL Software Pty Ltd.

Version	0.9.8			   Jun 2017			 nslcd.conf(5)


Want to link to this manual page? Use this URL:

home | help