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

FreeBSD Manual Pages

  
 
  

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

NAME
       nslcd.conf - configuration file for LDAP	nameservice daemon

DESCRIPTION
       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
       lookups.

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

       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
	      debug. The default log level is info.   All  messages  with  the
	      specified	 loglevel  or  higher  are logged.  This option	can be
	      supplied multiple	times.	If this	option is omitted syslog  info
	      is assumed.

   GENERAL CONNECTION OPTIONS
       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
	      syntax.

	      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
	      directory	 server	 for  lookups.	 The default is	to bind	anony-
	      mously.

       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	AUTHENTICATION OPTIONS
       sasl_mech MECHANISM
	      Specifies	the SASL mechanism to be  used	when  performing  SASL
	      authentication.

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

       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
	      reverse host name	lookup.	 By default, it	is left	up to the LDAP
	      library whether this check is performed or not.

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

   SEARCH/MAPPING OPTIONS
       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
	      used.

	      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
	      unavailable 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)).

       map MAP ATTRIBUTE NEWATTRIBUTE
	      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
	      directory.

	      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
	      attribute	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-
	      Sid:S-1-5-21-3623811015-3361044348-30300820).

	      By  default  all	userPassword  attributes  are  mapped  to  the
	      unmatchable  password  ("*") to avoid accidentally leaking pass-
	      word information.

   TIMING/RECONNECT OPTIONS
       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
	      default, 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/TLS OPTIONS
       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-
	      tion.

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

       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.

   OTHER OPTIONS
       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
	      times.

	      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
	      numeric 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
	      numeric 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
	      entries  to  be loaded (getpwent(), getgrent(), setspent()) from
	      the directory will not succeed in	doing so.   Applications  that
	      depend  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
	      behavior 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._@$()
	      \\~-]*[a-z0-9._@$()~-])?$/i

       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
	      requested	 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
	      attribute	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):

	      (&(objectClass=posixAccount)(uid=$username)(|(authorizedService=$service)(!(authorizedService=*))))

	      The pam_check_host_attr option can be emulated with:

	      (&(objectClass=posixAccount)(uid=$username)(|(host=$hostname)(host=$fqdn)(host=\\*)))

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

       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
	      external	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
	      cache.

	      The first	TIME value specifies the time to keep found entries in
	      the cache.  The second TIME  value  specifies  to	 the  time  to
	      remember	that  a	particular entry was not found.	 If the	second
	      parameter	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
	      15m.

SUPPORTED MAPS
       The  following  maps  are  supported. They are referenced as MAP	in the
       options above.

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

       ether[s]
	      Ethernet numbers (mac addresses).

       group  Posix groups.

       host[s]
	      Host names.

       netgroup
	      Host and user groups used	for access control.

       network[s]
	      Network numbers.

       passwd Posix users.

       protocol[s]
	      Protocol definitions (like in /etc/protocols).

       rpc    Remote procedure call names and numbers.

       service[s]
	      Network service names and	numbers.

       shadow Shadow user password information.

ATTRIBUTE MAPPING EXPRESSIONS
       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

       ${attr:-word}
	      (use default) will substitbute the value of the attribute	or, if
	      the attribute is not set or empty	substitute the word

       ${attr:+word}
	      (use alternative)	will substitute	word if	attribute is set, oth-
	      erwise substitute	the empty string

       ${attr:offset:length}
	      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)

       ${attr#word}
	      remove the shortest possible match of word from the left of  the
	      attribute	value

       ${attr##word}
	      remove  the  longest possible match of word from the left	of the
	      attribute	value (pynslcd only)

       ${attr%word}
	      remove the shortest possible match of word from the right	of the
	      attribute	value (pynslcd only)

       ${attr%%word}
	      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:

       "${shadowFlag:-0}"
	      use the shadowFlag attribute, using the value 0 as default

       "${homeDirectory:-/home/$uid}"
	      use the uid attribute to build a	homeDirectory  value  if  that
	      attribute	is missing

       "${isDisabled:+100}"
	      if  the isDisabled attribute is set, return 100, otherwise leave
	      value empty

       "${userPassword#{crypt\}}"
	      strip  the  {crypt}  prefix  from	 the  userPassword  attribute,
	      returning	the raw	hash value

FILES
       /etc/nslcd.conf
	      the main configuration file

       /etc/nsswitch.conf
	      Name Service Switch configuration	file

SEE ALSO
       nslcd(8), nsswitch.conf(5)

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

Version	0.9.8			   Jun 2017			 nslcd.conf(5)

NAME | DESCRIPTION | OPTIONS | SUPPORTED MAPS | ATTRIBUTE MAPPING EXPRESSIONS | FILES | SEE ALSO | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=nslcd.conf&sektion=5&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help