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

FreeBSD Manual Pages

  
 
  

home | help
SLAPD-LDAP(5)		      File Formats Manual		 SLAPD-LDAP(5)

NAME
       slapd-ldap - LDAP backend to slapd

SYNOPSIS
       /usr/local/etc/openldap/slapd.conf

DESCRIPTION
       The LDAP	backend	to slapd(8) is not an actual database; instead it acts
       as a proxy to forward incoming requests to another LDAP	server.	 While
       processing requests it will also	chase referrals, so that referrals are
       fully processed instead of being	returned to the	slapd client.

       Sessions	that explicitly	Bind to	the back-ldap database	always	create
       their  own private connection to	the remote LDAP	server.	Anonymous ses-
       sions will share	a single anonymous connection to  the  remote  server.
       For sessions bound through other	mechanisms, all	sessions with the same
       DN will share the same connection. This connection pooling strategy can
       enhance	the  proxy's efficiency	by reducing the	overhead of repeatedly
       making/breaking multiple	connections.

       The ldap	database can also act as  an  information  service,  i.e.  the
       identity	 of  locally  authenticated  clients is	asserted to the	remote
       server, possibly	in some	modified form.	For this  purpose,  the	 proxy
       binds  to  the remote server with some administrative identity, and, if
       required, authorizes the	asserted identity.  See	the  idassert-*	 rules
       below.  The administrative identity of the proxy, on the	remote server,
       must be allowed to authorize by means of	appropriate authzTo rules; see
       slapd.conf(5) for details.

       The  proxy instance of slapd(8) must contain schema information for the
       attributes and objectClasses used in filters, request DNs and  request-
       related data in general.	 It should also	contain	schema information for
       the data	returned by the	proxied	server.	 It is the  responsibility  of
       the  proxy  administrator to keep the schema of the proxy lined up with
       that of the proxied server.

       Note: When looping back to the same instance of slapd(8), each  connec-
       tion  requires a	new thread; as a consequence, the slapd(8) threads pa-
       rameter may need	some tuning. In	those cases, one  may  consider	 using
       slapd-relay(5) instead, which performs the relayed operation internally
       and thus	reuses the same	connection.

CONFIGURATION
       These slapd.conf	options	apply to the LDAP backend database.  That  is,
       they  must follow a "database ldap" line	and come before	any subsequent
       "backend" or "database" lines.  Other database options are described in
       the slapd.conf(5) manual	page.

       Note: In	early versions of back-ldap it was recommended to always set

	      lastmod  off

       for ldap	and meta databases.  This was required because operational at-
       tributes	related	to entry creation and modification should not be prox-
       ied,  as	they could be mistakenly written to the	target server(s), gen-
       erating an error.  The current implementation automatically sets	 last-
       mod to off, so its use is redundant and should be omitted.

       uri <ldapurl>
	      LDAP  server  to use.  Multiple URIs can be set in a single lda-
	      purl argument, resulting in the underlying library automatically
	      calling the first	server of the list that	responds, e.g.

	      uri "ldap://host/	ldap://backup-host/"

	      The  URI list is space- or comma-separated.  Whenever the	server
	      that responds is not the first one in the	list, the list is  re-
	      arranged and the responsive server is moved to the head, so that
	      it will be first contacted the next time a connection  needs  to
	      be created.

       acl-bind	       bindmethod=simple|sasl	    [binddn=<simple	  DN>]
	      [credentials=<simple    password>]    [saslmech=<SASL	mech>]
	      [secprops=<properties>] [realm=<realm>] [authcId=<authentication
	      ID>]  [authzId=<authorization  ID>]   [starttls=no|yes|critical]
	      [tls_cert=<file>]	     [tls_key=<file>]	   [tls_cacert=<file>]
	      [tls_cacertdir=<path>]	  [tls_reqcert=never|allow|try|demand]
	      [tls_reqsan=never|allow|try|demand] [tls_cipher_suite=<ciphers>]
	      [tls_ecname=<names>]	  [tls_protocol_min=<major>[.<minor>]]
	      [tls_crlcheck=none|peer|all]
	      Allows one to define the parameters of the authentication	method
	      that is internally used by the proxy to collect info related  to
	      access  control,	and  whenever  an  operation  occurs  with the
	      identity of the rootdn of	the LDAP proxy database.  The identity
	      defined	by   this   directive,	according  to  the  properties
	      associated to the	authentication method,	is  supposed  to  have
	      read access on the target	server to attributes used on the proxy
	      for ACL checking.

	      There is no risk of giving away such values; they	are only  used
	      to  check	 permissions.  The default is to use simple bind, with
	      empty binddn and	credentials,  which  means  that  the  related
	      operations  will	be  performed anonymously.  If not set,	and if
	      idassert-bind is defined,	this latter identity is	used  instead.
	      See idassert-bind	for details.

	      The  connection between the proxy	database and the remote	server
	      associated to this identity is cached regardless of the lifespan
	      of the client-proxy connection that first	established it.

	      This  identity  is  not  implicitly  used	 by the	proxy when the
	      client  connects	anonymously.	The   idassert-bind   feature,
	      instead,	in  some  cases	 can  be  crafted  to  implement  that
	      behavior,	which is intrinsically unsafe and should be used  with
	      extreme care.

	      The  TLS	settings  default  to  the  same as the	main slapd TLS
	      settings,	except for tls_reqcert which defaults to "demand", and
	      tls_reqsan which defaults	to "allow".

       cancel {ABANDON|ignore|exop[-discover]}
	      Defines  how  to	handle	operation  cancellation.   By default,
	      abandon is invoked, so the operation is  abandoned  immediately.
	      If set to	ignore,	no action is taken and any further response is
	      ignored; this may	result in  further  response  messages	to  be
	      queued  for  that	 connection,  so  it  is recommended that long
	      lasting connections are timed  out  either  by  idle-timeout  or
	      conn-ttl,	 so that resources eventually get released.  If	set to
	      exop, a cancel operation (RFC 3909) is issued, resulting in  the
	      cancellation  of	the  current  operation;  the cancel operation
	      waits for	 remote	 server	 response,  so	its  use  may  not  be
	      recommended.   If	 set  to  exop-discover, support of the	cancel
	      extended operation is detected by	reading	 the  remote  server's
	      root DSE.

       chase-referrals {YES|no}
	      enable/disable automatic referral	chasing, which is delegated to
	      the underlying libldap, with rebinding eventually	 performed  if
	      the  rebind-as-user  directive is	used.  The default is to chase
	      referrals.

       conn-pool-max <int>
	      This directive  defines  the  maximum  size  of  the  privileged
	      connections pool.

       conn-ttl	<time>
	      This  directive causes a cached connection to be dropped after a
	      given ttl, regardless  of	 being	idle  or  not.	 If  a	client
	      connection  outlives  the	 remote	 connection,  the  client will
	      receive LDAP_UNAVAILABLE when it executes	the next operation.

       idassert-authzFrom <authz-regexp>
	      if defined, selects what	local  identities  are	authorized  to
	      exploit  the  identity  assertion	 feature.   The	string <authz-
	      regexp> mostly follows  the  rules  defined  for	the  authzFrom
	      attribute.   See slapd.conf(5), section related to authz-policy,
	      for details on the syntax	of this	field.	This parameter differs
	      from  the	 documented  behavior in relation to the meaning of *,
	      which in this case allows	anonymous rather than denies.

       idassert-bind	bindmethod=none|simple|sasl    [binddn=<simple	  DN>]
	      [credentials=<simple     password>]    [saslmech=<SASL	mech>]
	      [secprops=<properties>] [realm=<realm>] [authcId=<authentication
	      ID>]  [authzId=<authorization  ID>]  [authz={native|proxyauthz}]
	      [mode=<mode>]	[flags=<flags>]	    [starttls=no|yes|critical]
	      [tls_cert=<file>]	     [tls_key=<file>]	   [tls_cacert=<file>]
	      [tls_cacertdir=<path>]	  [tls_reqcert=never|allow|try|demand]
	      [tls_reqsan=never|allow|try|demand] [tls_cipher_suite=<ciphers>]
	      [tls_ecname=<names>]		  [tls_protocol_min=<version>]
	      [tls_crlcheck=none|peer|all]
	      Allows one to define the parameters of the authentication	method
	      that is internally used by the proxy  to	authorize  connections
	      that  are	 authenticated	by  other databases.  Direct binds are
	      always proxied without any idassert handling.

	      The  identity  defined  by  this	directive,  according  to  the
	      properties  associated to	the authentication method, is supposed
	      to have auth access on the target	server to attributes  used  on
	      the  proxy  for  authentication  and  authorization,  and	 to be
	      allowed  to  authorize  the  users.   This  requires   to	  have
	      proxyAuthz   privileges	on   a	 wide	set   of   DNs,	  e.g.
	      authzTo=dn.subtree:"",   and   the   remote   server   to	  have
	      authz-policy  set	 to to or both.	 See slapd.conf(5) for details
	      on these statements and for remarks and  drawbacks  about	 their
	      usage.  The supported bindmethods	are

	      none|simple|sasl

	      where  none  is  the  default,  i.e.  no	identity  assertion is
	      performed.

	      The authz	parameter is used to instruct the SASL bind to exploit
	      native  SASL  authorization, if available; since connections are
	      cached, this should only be used when authorizing	with  a	 fixed
	      identity	(e.g.  by means	of the authzDN or authzID parameters).
	      Otherwise, the default proxyauthz	is used, i.e.  the  proxyAuthz
	      control  (Proxied	 Authorization,	 RFC  4370)  is	 added	to all
	      operations.

	      The supported modes are:

	      <mode> :=	{legacy|anonymous|none|self}

	      If <mode>	is not present,	and authzId is given, the proxy	always
	      authorizes that identity.	 <authorization	ID> can	be

	      u:<user>

	      [dn:]<DN>

	      The  former  is  supposed	 to  be	 expanded by the remote	server
	      according	to the authz rules; see	slapd.conf(5) for details.  In
	      the  latter  case, whether or not	the dn:	prefix is present, the
	      string must pass DN validation and normalization.

	      The default mode is legacy, which	implies	that  the  proxy  will
	      either  perform  a  simple bind as the authcDN or	a SASL bind as
	      the authcID and assert the client's  identity  when  it  is  not
	      anonymous.   The	other  modes  imply that the proxy will	always
	      either perform a simple bind as the authcDN or a	SASL  bind  as
	      the  authcID, unless restricted by idassert-authzFrom rules (see
	      below), in which case the	operation will	fail;  eventually,  it
	      will  assert  some  other	 identity  according to	<mode>.	 Other
	      identity	assertion  modes  are  anonymous   and	 self,	 which
	      respectively  mean  that the empty or the	client's identity will
	      be asserted; none, which means that no proxyAuthz	 control  will
	      be  used,	 so  the  authcDN  or  the  authcID  identity  will be
	      asserted.	 For all modes that require the	use of the  proxyAuthz
	      control,	on  the	 remote	 server	 the  proxy identity must have
	      appropriate authzTo permissions, or the asserted identities must
	      have appropriate authzFrom permissions.  Note, however, that the
	      ID  assertion  feature  is  mostly  useful  when	the   asserted
	      identities do not	exist on the remote server.

	      Flags can	be

	      override,[non-]prescriptive,proxy-authz-[non-]critical,dn-{authzid|whoami}

	      When the override	flag is	used, identity assertion  takes	 place
	      even  when  the  database	is authorizing for the identity	of the
	      client, i.e. after binding with the provided identity, and  thus
	      authenticating  it,  the	proxy  performs	the identity assertion
	      using the	configured identity and	authentication method.

	      When the prescriptive flag is  used  (the	 default),  operations
	      fail with	inappropriateAuthentication for	those identities whose
	      assertion	is not allowed by the idassert-authzFrom patterns.  If
	      the  non-prescriptive  flag  is  used,  operations are performed
	      anonymously for those identities whose assertion is not  allowed
	      by the idassert-authzFrom	patterns.

	      When  the	 proxy-authz-non-critical  flag	is used	(the default),
	      the proxyAuthz control is	not marked as critical,	 in  violation
	      of RFC 4370.  Use	of proxy-authz-critical	is recommended.

	      When  the	 dn-authzid  flag is used, RFC 3829 LDAP Authorization
	      Identity Controls	is used	to retrieve the	identity associated to
	      the  SASL	 identity;  when  the dn-whoami	flag is	used, RFC 4532
	      LDAP Who am I? Operation is performed after  the	bind  for  the
	      same purpose.

	      The  TLS	settings  default  to  the  same as the	main slapd TLS
	      settings,	except for tls_reqcert which defaults to "demand", and
	      tls_reqsan which defaults	to "allow".

	      The  identity  associated	 to  this  directive  is also used for
	      privileged operations  whenever  idassert-bind  is  defined  and
	      acl-bind is not.	See acl-bind for details.

	      idassert-passthru	<authz-regexp>
		     if	 defined,  selects  what  local	 identities bypass the
		     identity assertion	feature.  Those	identities need	to  be
		     known  by	the  remote  host.   The string	<authz-regexp>
		     follows the rules defined for  the	 authzFrom  attribute.
		     See  slapd.conf(5),  section related to authz-policy, for
		     details on	the syntax of this field.

	      idle-timeout <time>
		     This directive causes a cached connection to  be  dropped
		     after  it	has  been  idle	 for the specified time.  If a
		     client connection outlives	 the  remote  connection,  the
		     client will receive LDAP_UNAVAILABLE when it executes the
		     next operation.

	      keepalive	<idle>:<probes>:<interval>
		     The keepalive parameter sets the values of	idle,  probes,
		     and  interval  used  to  check whether a socket is	alive;
		     idle is the number	 of  seconds  a	 connection  needs  to
		     remain  idle  before TCP starts sending keepalive probes;
		     probes is the maximum  number  of	keepalive  probes  TCP
		     should  send  before dropping the connection; interval is
		     interval in seconds between individual keepalive  probes.
		     Only  some	 systems  support  the	customization of these
		     values; the keepalive parameter is	ignored	otherwise, and
		     system-wide settings are used.

	      tcp-user-timeout <milliseconds>
		     If	 non-zero,  corresponds	to the TCP_USER_TIMEOUT	set on
		     the target	connections, overriding	the  operating	system
		     setting.	Only some systems support the customization of
		     this parameter, it	is ignored otherwise  and  system-wide
		     settings are used.

	      network-timeout <time>
		     Sets    the    network    timeout	 value	 after	 which
		     poll(2)/select(2) following a connect(2) returns in  case
		     of	 no  activity.	The value is in	seconds, and it	can be
		     specified as for idle-timeout.

	      norefs <NO|yes>
		     If	yes, do	not return  search  reference  responses.   By
		     default, they are returned	unless request is LDAPv2.

	      omit-unknown-schema <NO|yes>
		     If	 yes,  do  not return objectClasses or attributes that
		     are not known to the local	server.	  The  default	is  to
		     return all	schema elements.

	      noundeffilter <NO|yes>
		     If	 yes,  return success instead of searching if a	filter
		     is	undefined or contains undefined	portions.  By default,
		     the   search  is  propagated  after  replacing  undefined
		     portions with (!(objectClass=*)),	which  corresponds  to
		     the empty result set.

	      onerr {CONTINUE|stop}
		     This  directive allows one	to select the behavior in case
		     an	error is  returned  by	the  remote  server  during  a
		     search.   The  default,  continue,	 consists in returning
		     success.  If the value is	set  to	 stop,	the  error  is
		     returned to the client.

	      protocol-version {0,2,3}
		     This  directive  indicates	 what protocol version must be
		     used to contact the remote	server.	  If  set  to  0  (the
		     default),	the  proxy uses	the same protocol version used
		     by	the client, otherwise the requested protocol is	 used.
		     The proxy returns unwillingToPerform if an	operation that
		     is	incompatible with the requested	protocol is attempted.

	      proxy-whoami {NO|yes}
		     Turns on proxying of the WhoAmI  extended	operation.  If
		     this  option  is  given,  back-ldap  will replace slapd's
		     original WhoAmI routine with its own. On  slapd  sessions
		     that  were	authenticated by back-ldap, the	WhoAmI request
		     will be  forwarded	 to  the  remote  LDAP	server.	 Other
		     sessions  will  be	handled	by the local slapd, as before.
		     This option is mainly useful in  conjunction  with	 Proxy
		     Authorization.

	      quarantine <interval>,<num>[;<interval>,<num>[...]]
		     Turns    on    quarantine	  of	URIs   that   returned
		     LDAP_UNAVAILABLE, so that an attempt  to  reconnect  only
		     occurs  at	 given	intervals instead of any time a	client
		     requests an operation.  The pattern is: retry only	 after
		     at	least interval seconds elapsed since last attempt, for
		     exactly num times;	then use the next pattern.  If num for
		     the  last	pattern	is "+",	it retries forever; otherwise,
		     no	more retries occur.  The process can be	 restarted  by
		     resetting	the  olcDbQuarantine attribute of the database
		     entry in the configuration	backend.

	      rebind-as-user {NO|yes}
		     If	this option is given, the  client's  bind  credentials
		     are remembered for	rebinds, when trying to	re-establish a
		     broken  connection,  or  when  chasing  a	referral,   if
		     chase-referrals  is  set  to  yes.	  Note,	 however, that
		     connection	is not re-established automatically  after  it
		     was dropped due to	idle-timeout or	conn-ttl .

	      session-tracking-request {NO|yes}
		     Adds  session  tracking  control  for  all	requests.  The
		     client's IP and hostname, and the identity	associated  to
		     each request, if known, are sent to the remote server for
		     informational purposes.  This directive  is  incompatible
		     with setting protocol-version to 2.

	      single-conn {NO|yes}
		     Discards	current	 cached	 connection  when  the	client
		     rebinds.

	      t-f-support {NO|yes|discover}
		     enable if the remote  server  supports  absolute  filters
		     (see  RFC 4526 for	details).  If set to discover, support
		     is	detected by reading the	remote server's	root DSE.

	      timeout [<op>=]<val> [...]
		     This directive allows one to set per-operation  timeouts.
		     Operations	can be

		     <op>  ::=	bind,  add,  delete,  modrdn, modify, compare,
		     search

		     The  overall  duration  of	 the   search	operation   is
		     controlled	 either	 by  the  timelimit  parameter	or  by
		     server-side  enforced  time  limits  (see	timelimit  and
		     limits  in	 slapd.conf(5)	for  details).	 This  timeout
		     parameter	controls  how	long   the   target   can   be
		     irresponsive before the operation is aborted.  Timeout is
		     meaningless for  the  remaining  operations,  unbind  and
		     abandon, which do not imply any response, while it	is not
		     yet   implemented	 in   currently	  supported   extended
		     operations.   If  no  operation is	specified, the timeout
		     val affects all supported operations.

		     Note: if the timelimit  is	 exceeded,  the	 operation  is
		     cancelled	 (according  to	 the  cancel  directive);  the
		     protocol  does  not  provide  any	 means	 to   rollback
		     operations,  so the client	will not be notified about the
		     result of the operation, which may	 eventually  succeeded
		     or	 not.	In  case the timeout is	exceeded during	a bind
		     operation,	the  connection	 is  destroyed,	 according  to
		     RFC4511.

		     Note:  in	some cases, this backend may issue binds prior
		     to	other operations (e.g. to  bind	 anonymously  or  with
		     some  prescribed  identity	according to the idassert-bind
		     directive).  In this case,	the timeout of	the  operation
		     that resulted in the bind is used.

	      tls    {none|[try-]start|[try-]propagate|ldaps}	 [starttls=no]
		     [tls_cert=<file>]	[tls_key=<file>]   [tls_cacert=<file>]
		     [tls_cacertdir=<path>]
		     [tls_reqcert=never|allow|try|demand]
		     [tls_reqsan=never|allow|try|demand]
		     [tls_cipher_suite=<ciphers>]	  [tls_ecname=<names>]
		     [tls_crlcheck=none|peer|all]
		     Specify TLS settings for regular connections.

		     If	the first parameter is not "none" then this configures
		     the TLS settings to be used for regular connections.  The
		     StartTLS	extended   operation   will   be   used	  when
		     establishing the  connection  unless  the	URI  directive
		     protocol  scheme  is ldaps://.  In	that case this keyword
		     may only be set to	"ldaps"	 and  the  StartTLS  operation
		     will not be used.

		     With  propagate,  the proxy issues	the StartTLS operation
		     only if the original connection has a TLS layer  set  up.
		     The   try-	  prefix   instructs  the  proxy  to  continue
		     operations	if the StartTLS	operation failed; its  use  is
		     not recommended.

		     The  TLS  settings	 default to the	same as	the main slapd
		     TLS settings, except for tls_reqcert  which  defaults  to
		     "demand",	tls_reqsan  which  defaults  to	 "allow",  and
		     starttls which is overshadowed by the first  keyword  and
		     thus ignored.

	      use-temporary-conn {NO|yes}
		     when  set	to yes,	create a temporary connection whenever
		     competing with other threads for a	shared one; otherwise,
		     wait until	the shared connection is available.

ACCESS CONTROL
       The  ldap  backend  does	 not  honor  all ACL semantics as described in
       slapd.access(5).	 In general,  access  checking	is  delegated  to  the
       remote  server(s).  Only	read (=r) access to the	entry pseudo-attribute
       and to the other	attribute values of the	entries	returned by the	search
       operation is honored, which is performed	by the frontend.

OVERLAYS
       The  LDAP  backend  provides  basic  proxying  functionalities  to many
       overlays.  The chain overlay,  described	 in  slapo-chain(5),  and  the
       translucent  overlay,  described	 in  slapo-translucent(5),  deserve  a
       special mention.

       Conversely, there are many overlays that	are best used  in  conjunction
       with  the  LDAP backend.	 The proxycache	overlay	allows caching of LDAP
       search requests (queries) in a local database.  See slapo-pcache(5) for
       details.	 The rwm overlay provides DN rewrite and attribute/objectClass
       mapping capabilities to the underlying database.	 See slapo-rwm(5)  for
       details.

FILES
       /usr/local/etc/openldap/slapd.conf
	      default slapd configuration file

SEE ALSO
       slapd.conf(5),	 slapd-config(5),    slapd-meta(5),    slapo-chain(5),
       slapo-pcache(5),	slapo-rwm(5), slapo-translucent(5), slapd(8), ldap(3).

AUTHOR
       Howard Chu, with	enhancements by	Pierangelo Masarati

OpenLDAP 2.6.1			  2022/01/20			 SLAPD-LDAP(5)

NAME | SYNOPSIS | DESCRIPTION | CONFIGURATION | ACCESS CONTROL | OVERLAYS | FILES | SEE ALSO | AUTHOR

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

home | help