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

FreeBSD Manual Pages

  
 
  

home | help
nss_ldap(5)		      File Formats Manual		   nss_ldap(5)

NAME
       nss_ldap	- LDAP nameservice provider

DESCRIPTION
       The nss_ldap module is a	set of C library extensions which allows X.500
       and LDAP	directory servers to be	used as	a primary source of name  ser-
       vice  information.  (Name service information typically includes	users,
       hosts, groups, and other	such data historically stored in flat files or
       NIS.)

       Features	 of  the PADL nss_ldap module include support for both the RFC
       2307 and	RFC 2307bis schema, a common  implementation  across  multiple
       platforms,  Kerberos and	SSL security, configurable schema mapping, and
       configuration file compatibility	with the pam_ldap(5) module.

       Because LDAP is a hierarchical directory	service,  one  can  distribute
       the  information	 in  a manner which reflects organizational structure.
       This contrasts with the flat, single domain policy  of  NIS.  LDAP  has
       many  of	 the advantages	of NIS+	(security and scalability) without the
       complexity.

       nss_ldap	will work alongside existing NIS, NIS+,	DNS and	flat file name
       services.  More	importantly, because it	builds as a shared library, it
       is not necessary	to recompile any applications  to  take	 advantage  of
       LDAP.

       The  present  version of	nss_ldap supports AIX 4.3.3 and	above, FreeBSD
       5.1, HP-UX 11i, Linux and Solaris 2.6 and above.	Many  vendors  provide
       their  own LDAP nameservice providers, often also called	nss_ldap. This
       manual page applies to the PADL nss_ldap	module only. If	you are	 using
       a vendor	provided module, consult the relevant documentation instead.

       The features supported by the version of	nss_ldap depend	on which flags
       were enabled when the software was built. Most features are enabled  in
       the  configuration file,	described below. (The location of the configu-
       ration file is configurable  at	compile	 time;	the  default  path  is
       /usr/local/etc/nss_ldap.conf.)	Also, some features may	be unavailable
       on certain operating systems or with certain LDAP libraries.  For  more
       information, consult your vendor.

CONFIGURATION
       nss_ldap	 stores	 its configuration in the ldap.conf file, the location
       of which	is configurable	at compile time.  (It  should  be  noted  that
       some  LDAP client libraries, such as OpenLDAP, also use a configuration
       file of the same	name.  nss_ldap	supports many of the  same  configura-
       tion file options as OpenLDAP, but it adds several that are specific to
       the functionality it provides.  Additionally, it	is not guaranteed that
       nss_ldap	 will  continue	 to  match the configuration file semantics of
       OpenLDAP.  You may wish to use different	files.)

       Configuration file options consist of a keyword followed	by a space and
       any arguments. The following options are	supported by both nss_ldap and
       the PADL	pam_ldap module:

       host <name:port ...>
	      Specifies	the name(s) or IP address(es) of the LDAP server(s) to
	      connect to. In the case that nss_ldap is used for	host name res-
	      olution, each server should be specified as  an  IP  address  or
	      name  that can be	resolved without using LDAP.  Multiple servers
	      may be specified,	each separated by a space.  The	failover  time
	      depends on whether the LDAP client library supports configurable
	      network or connect timeouts (see bind_timelimit below).

       base <base>
	      Specifies	the default base distinguished name (DN)  to  use  for
	      searches.

       uri <ldap[is]://[name[:port]] ...>
	      For  LDAP	client libraries that support it, specifies the	URI(s)
	      of the LDAP server(s) to connect to. The URI scheme may be ldap,
	      ldapi,  or  ldaps, specifying LDAP over TCP, IPC and SSL respec-
	      tively. If applicable, a	port  number  can  be  specified;  the
	      default  port  number for	the selected protocol is used if omit-
	      ted. This	option takes precedence	over the host  option;	it  is
	      not possible to combine the two.

       ldap_version <version>
	      Specifies	 the  version  of  the LDAP protocol to	use. Presently
	      version must be 2	or 3. The default is to	use the	 maximum  ver-
	      sion supported by	the client library.

       binddn <binddn>
	      Specifies	 the  distinguished  name  with	 which	to bind	to the
	      directory	server(s). This	option is optional; the	default	is  to
	      bind anonymously.

       bindpw <bindpw>
	      Specifies	 the  cleartext	 credentials  with which to bind. This
	      option is	only applicable	 when  used  with  binddn  above.  The
	      default  is  no credential (anonymous bind). When	binding	to the
	      directory	using SASL or other  authentication  mechanisms	 apart
	      from simple binds, this option is	not used.

       rootbinddn <binddn>
	      This  option has the same	syntax and effect as the binddn	option
	      above, except it applies when the	effective user ID is zero.  If
	      not  specified,  then  the  identity specified in	binddn is used
	      instead. Because the configuration file may be readable by  many
	      users,   the   root  bind	 DN  credentials  are  stored  in  the
	      ldap.secret file instead.	This  file  is	usually	 in  the  same
	      directory	as the configuration file.

       port <port>
	      Specifies	 the  port to connect to; this option is used with the
	      host option, and is ignored with the uri option.

       scope <sub|one|base>
	      Specifies	the search scope (subtree, one level or	base  object).
	      The  default scope is subtree; base scope	is almost never	useful
	      for nameservice lookups.

       deref <never|searching|finding|always>
	      Specifies	the policy for dereferencing aliases. The default pol-
	      icy is to	never dereference aliases.

       timelimit <timelimit>
	      Specifies	 the  time  limit  (in seconds)	to use when performing
	      searches.	A value	of zero	(0), which is the default, is to  wait
	      indefinitely for searches	to be completed.

       bind_timelimit <timelimit>
	      Specifies	 the time limit	(in seconds) to	use when connecting to
	      the directory server. This is distinct from the time limit spec-
	      ified  in	 timelimit  and	 affects the initial server connection
	      only. (Server connections	are otherwise cached.) Only some  LDAP
	      client  libraries	have the underlying functionality necessary to
	      support this option. The default bind timelimit is 30 seconds.

       referrals <yes|no>
	      Specifies	whether	automatic referral chasing should be  enabled.
	      The default behaviour is specifed	by the LDAP client library.

       restart <yes|no>
	      Specifies	 whether  the  LDAP client library should restart the
	      select(2)	system call when interrupted. This feature is not sup-
	      ported by	all client libraries.

       logdir <directory>
	      Specifies	 the  directory	 used  for  logging by the LDAP	client
	      library. This feature is not supported by	all client libraries.

       debug <level>
	      Specifies	the debug level	used for logging by  the  LDAP	client
	      library.	This feature is	not supported by all client libraries,
	      and does not apply to the	nss_ldap and  pam_ldap	modules	 them-
	      selves  (debugging, if any, is configured	separately and usually
	      at compile time).

       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
	      and StartTLS, and	all related configuration options.

       sslpath <cert7_path>
	      For  the	Netscape  and Mozilla LDAP client libraries only, this
	      specifies	the path to the	X.509 certificate database.

       tls_checkpeer <yes|no>
	      Specifies	whether	to require and verify the  server  certificate
	      or  not,	when  using  SSL/TLS with the OpenLDAP client library.
	      The default is to	 use  the  default  behaviour  of  the	client
	      library;	for  OpenLDAP 2.0 and earlier it is "no", for OpenLDAP
	      2.1 and later it is "yes". At least  one	of  tls_cacertdir  and
	      tls_cacertfile is	required if peer verification is enabled.

       tls_cacertdir <certificate_dir>
	      Specifies	 the  directory	containing X.509 certificates for peer
	      authentication.

       tls_cacertfile <certificate_file>
	      Specifies	the path to the	X.509 certificate for peer authentica-
	      tion.

       tls_randfile <entropy_file>
	      Specifies	the path to an entropy source.

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

       tls_cert	<certificate_file>
	      Specifies	the path to the	file containing	the local  certificate
	      for client TLS authentication.

       tls_key <key_file>
	      Specifies	 the  path  to the file	containing the private key for
	      client TLS authentication.

       The following configuration options apply to nss_ldap only:

       bind_policy <hard_open|hard_init|soft>
	      Specifies	the policy to use for reconnecting to  an  unavailable
	      LDAP server. The default is hard_open, which reconnects if open-
	      ing the connection to the	directory server failed. By  contrast,
	      hard_init	reconnects if initializing the connection failed. Ini-
	      tializing	may not	actually contact the directory server, and  it
	      is  possible  that  a  malformed configuration file will trigger
	      reconnection. If soft is specified, then	nss_ldap  will	return
	      immediately  on  server  failure.	 All "hard" reconnect policies
	      block with exponential backoff before retrying.

       nss_connect_policy <persist|oneshot>
	      Determines whether nss_ldap persists connections.	The default is
	      for  the	connection to the LDAP server to remain	open after the
	      first request.

       idle_timelimit <timelimit>
	      Specifies	the time (in seconds) after which nss_ldap will	 close
	      connections  to the directory server. The	default	is not to time
	      out connections.

       sasl_authid <authid>
	      Specifies	the authorization identity to be used when  performing
	      SASL authentication.

       rootsasl_auth_id	<authid>
	      Specifies	 the authorization identity to be used when performing
	      SASL authentication as root  (when  the  effective  user	ID  is
	      zero).

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

       rootuse_sasl <yes|no>
	      Specifies	whether	SASL authentication should be  used  when  the
	      effective	user ID	is zero.

       krb5_ccname <PREFIX:args>
	      If nss_ldap is built with	configurable GSS-API credentials cache
	      name support, specifies the Kerberos credentials cache to	use.

       nss_paged_results <yes|no>
	       Enables support for paged results.

       pagesize	<pagesize>
	      When paged results are enabled (see above), specifies the	number
	      of entries to return in a	single page. The default is 1000.

       nss_base_<map> <basedn?scope?filter>
	      Specify  the  search  base, scope	and filter to be used for spe-
	      cific maps. (Note	that map forms part of the configuration  file
	      keyword  and  is	one of passwd, shadow, group, hosts, services,
	      networks,	protocols, rpc,	ethers,	netmasks, bootparams,  aliases
	      and  netgroup.)	The syntax of basedn and scope are the same as
	      for the configuration file options of the	same  name,  with  the
	      addition	of  being able to omit the trailing suffix of the base
	      DN (in which case	the global base	DN will	be appended  instead).
	      The  filter is a search filter to	be added to the	default	search
	      filter for a specific map, such that the effective filter	is the
	      logical  intersection  of	the two. The base DN, scope and	filter
	      are separated with literal question marks	(?)  as	 given	above;
	      this  is	for  compatibility  with the DUA configuration profile
	      schema and the ldapprofile tool. This option  may	 be  specified
	      multiple times.

       nss_map_attribute <from_attribute> <to_attribute>
	      This  option  may	 be  specified	multiple  times,  and  directs
	      nss_ldap to use the attribute to_attribute instead  of  the  RFC
	      2307  attribute  from_attribute in all lookups.  If nss_ldap was
	      built without  schema  mapping  support,	then  this  option  is
	      ignored.

       nss_map_objectclass <from_objectclass> <to_objectclass>
	      This  option  may	 be  specified	multiple  times,  and  directs
	      nss_ldap to use the object class to_objectclass instead  of  the
	      RFC  2307	 object	 class	from_objectclass  in  all lookups.  If
	      nss_ldap was built without schema	 mapping  support,  then  this
	      option is	ignored.

       nss_default_attribute_value <attribute> <value>
	      Specifies	 the  default  value  to use for entries that lack the
	      specified	attribute.  This  option  may  be  specified  multiple
	      times,  for different attributes.	 If nss_ldap was built without
	      schema mapping support, then this	option is ignored.

       nss_override_attribute_value <attribute>	<value>
	      Specifies	a value	to use for the specified attribute in  prefer-
	      ence  to	that contained in the actual entry. This option	may be
	      specified	multiple times,	for different attributes.  If nss_ldap
	      was  built  without  schema mapping support, then	this option is
	      ignored.

       nss_schema <rfc2307bis|rfc2307>
	      If the value of this option is  rfc2307bis then support for  the
	      RFC2307bis  schema  (distinguished  names	 in  groups)  will  be
	      enabled.

       nss_initgroups <backlink>
	      This option directs the nss_ldap implementation of initgroups(3)
	      to  determine  a user's group membership by reading the memberOf
	      attribute	of their directory entry (and of any  nested  groups),
	      rather than querying on uniqueMember. This may provide increased
	      performance with certain directory servers  that	have  peculiar
	      indexing	configurations.	  If  RFC2307bis  support is disabled,
	      then this	option is ignored.

       nss_initgroups_ignoreusers <user1,user2,...,userN>
	      This option directs the nss_ldap implementation of initgroups(3)
	      to  return  NSS_STATUS_NOTFOUND if called	with a listed users as
	      its argument.

       nss_getgrent_skipmembers	<yes|no>
	      Specifies	whether	or not to populate the	members	 list  in  the
	      group  structure	for  group  lookups.  If very large groups are
	      present, enabling	this option will greatly increase  perforance,
	      at  the  cost  of	 some lost functionality. You should verify no
	      local applications rely on this information before enabling this
	      on a production system.

       nss_srv_domain <domain>
	      This  option  determines	the DNS	domain used for	performing SRV
	      lookups.

AUTHOR
       The  nss_ldap  module  was  developed  by   PADL	  Software   Pty   Ltd
       (www.padl.com).

FILES
       /usr/local/etc/nss_ldap.conf, /usr/local/etc/nss_ldap.secret, /etc/nss-
       witch.conf

SEE ALSO
       nsswitch.conf(5)

								   nss_ldap(5)

NAME | DESCRIPTION | CONFIGURATION | AUTHOR | FILES | SEE ALSO

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

home | help