.TH SLAPD.CONF 5 "RELEASEDATE" "OpenLDAP LDVERSION"
-.\" Copyright 1998-2007 The OpenLDAP Foundation All Rights Reserved.
+.\" Copyright 1998-2009 The OpenLDAP Foundation All Rights Reserved.
.\" Copying restrictions apply. See COPYRIGHT/LICENSE.
.\" $OpenLDAP$
.SH NAME
The specific configuration options available are discussed below in the
Global Configuration Options, General Backend Options, and General Database
Options. Backend-specific options are discussed in the
-.B slapd-<backend>(5)
+.B slapd\-<backend>(5)
manual pages. Refer to the "OpenLDAP Administrator's Guide" for more
details on the slapd configuration file.
.SH GLOBAL CONFIGURATION OPTIONS
(subject to access controls, authorization and other administrative limits).
.TP
.B argsfile <filename>
-The ( absolute ) name of a file that will hold the
+The (absolute) name of a file that will hold the
.B slapd
-server's command line options
-if started without the debugging command line option.
+server's command line (program name and options).
.TP
.B attributeoptions [option-name]...
Define tagging attribute options or option tag/range prefixes.
-Options must not end with `-', prefixes must end with `-'.
-The `lang-' prefix is predefined.
+Options must not end with `\-', prefixes must end with `\-'.
+The `lang\-' prefix is predefined.
If you use the
.B attributeoptions
-directive, `lang-' will no longer be defined and you must specify it
+directive, `lang\-' will no longer be defined and you must specify it
explicitly if you want it defined.
An attribute description with a tagging option is a subtype of that
attribute description without the option.
Except for that, options defined this way have no special semantics.
-Prefixes defined this way work like the `lang-' options:
+Prefixes defined this way work like the `lang\-' options:
They define a prefix for tagging options starting with the prefix.
-That is, if you define the prefix `x-foo-', you can use the option
-`x-foo-bar'.
+That is, if you define the prefix `x\-foo\-', you can use the option
+`x\-foo\-bar'.
Furthermore, in a search or compare, a prefix or range name (with
-a trailing `-') matches all options starting with that name, as well
-as the option with the range name sans the trailing `-'.
-That is, `x-foo-bar-' matches `x-foo-bar' and `x-foo-bar-baz'.
+a trailing `\-') matches all options starting with that name, as well
+as the option with the range name sans the trailing `\-'.
+That is, `x\-foo\-bar\-' matches `x\-foo\-bar' and `x\-foo\-bar\-baz'.
-RFC 4520 reserves options beginning with `x-' for private experiments.
+RFC 4520 reserves options beginning with `x\-' for private experiments.
Other options should be registered with IANA, see RFC 4520 section 3.5.
OpenLDAP also has the `binary' option built in, but this is a transfer
option, not a tagging option.
description.)
.RE
.TP
-.B authz-policy <policy>
+.B authz\-policy <policy>
Used to specify which rules to use for Proxy Authorization. Proxy
authorization allows a client to authenticate to the server using one
user's credentials, but specify a different identity to use for authorization
.B dn[.<dnstyle>]:<pattern>
.RE
.RS
-.B u[<mech>[<realm>]]:<pattern>
+.B u[.<mech>[/<realm>]]:<pattern>
.RE
.RS
.B group[/objectClass[/attributeType]]:<pattern>
can impact security, users are strongly encouraged
to explicitly set the type of identity specification that is being used.
A subset of these rules can be used as third arg in the
-.B authz-regexp
+.B authz\-regexp
statement (see below); significantly, the
-.I URI
+.IR URI ,
+provided it results in exactly one entry,
and the
.I dn.exact:<dn>
forms.
.RE
.TP
-.B authz-regexp <match> <replace>
+.B authz\-regexp <match> <replace>
Used by the authentication framework to convert simple user names,
-such as provided by SASL subsystem, to an LDAP DN used for
-authorization purposes. Note that the resultant DN need not refer
+such as provided by SASL subsystem, or extracted from certificates
+in case of cert-based SASL EXTERNAL, or provided within the RFC 4370
+"proxied authorization" control, to an LDAP DN used for
+authorization purposes. Note that the resulting DN need not refer
to an existing entry to be considered valid. When an authorization
request is received from the SASL subsystem, the SASL
.BR USERNAME ,
the authentication identity must have "auth" access in the subject.
Multiple
-.B authz-regexp
+.B authz\-regexp
options can be given in the configuration file to allow for multiple matching
and replacement patterns. The matching patterns are checked in the order they
appear in the file, stopping at the first successful match.
.B tls_authc
disallows the StartTLS operation if authenticated (see also
.BR tls_2_anon ).
+.B proxy_authz_non_critical
+disables acceptance of the proxied authorization control (RFC4370)
+when criticality is FALSE.
+.B dontusecopy_non_critical
+disables acceptance of the dontUseCopy control (a work in progress)
+when criticality is FALSE.
.HP
.hy 0
.B ditcontentrule "(\ <oid>\
will stop listening for new connections, but will not close the
connections to the current clients. Future write operations return
unwilling-to-perform, though. Slapd terminates when all clients
-have closed their connections (if they ever do), or \- as before \-
+have closed their connections (if they ever do), or - as before -
if it receives a SIGTERM signal. This can be useful if you wish to
terminate the server and start a new
.B slapd
.B idletimeout <integer>
Specify the number of seconds to wait before forcibly closing
an idle client connection. A idletimeout of 0 disables this
-feature. The default is 0.
+feature. The default is 0. You may also want to set the
+.B writetimeout
+option.
.TP
.B include <filename>
Read additional configuration information from the given file before
continuing with the next line of the current file.
.TP
+.B index_intlen <integer>
+Specify the key length for ordered integer indices. The most significant
+bytes of the binary integer will be used for index keys. The default
+value is 4, which provides exact indexing for 31 bit values.
+A floating point representation is used to index too large values.
+.TP
.B index_substr_if_minlen <integer>
Specify the minimum length for subinitial and subfinal indices. An
attribute value must have at least this many characters in order to be
using this filter "cn=*abcdefgh*" would generate index lookups for
"abcd", "cdef", and "efgh".
-Note: Indexing support depends on the particular backend in use.
+.LP
+Note: Indexing support depends on the particular backend in use. Also,
+changing these settings will generally require deleting any indices that
+depend on these parameters and recreating them with
+.BR slapindex (8).
+
+.HP
+.hy 0
+.B ldapsyntax "(\ <oid>\
+ [DESC\ <description>]\
+ [X\-SUBST <substitute-syntax>]\ )"
+.RS
+Specify an LDAP syntax using the LDAPv3 syntax defined in RFC 4512.
+The slapd parser extends the RFC 4512 definition by allowing string
+forms as well as numeric OIDs to be used for the syntax OID.
+(See the
+.B objectidentifier
+description.)
+The slapd parser also honors the
+.B X\-SUBST
+extension (an OpenLDAP-specific extension), which allows to use the
+.B ldapsyntax
+statement to define a non-implemented syntax along with another syntax,
+the extension value
+.IR substitute-syntax ,
+as its temporary replacement.
+The
+.I substitute-syntax
+must be defined.
+This allows to define attribute types that make use of non-implemented syntaxes
+using the correct syntax OID.
+Unless
+.B X\-SUBST
+is used, this configuration statement would result in an error,
+since no handlers would be associated to the resulting syntax structure.
+.RE
.TP
.B localSSF <SSF>
are equivalent.
The keyword
.B any
-can be used as a shortcut to enable logging at all levels (equivalent to -1).
+can be used as a shortcut to enable logging at all levels (equivalent to \-1).
The keyword
.BR none ,
or the equivalent integer representation, causes those messages
.B modulepath
option. This option and the
.B modulepath
-option are only usable if slapd was compiled with --enable-modules.
+option are only usable if slapd was compiled with \-\-enable\-modules.
.TP
.B modulepath <pathspec>
Specify a list of directories to search for loadable modules. Typically
the path is colon-separated but this depends on the operating system.
+The default is MODULEDIR, which is where the standard OpenLDAP install
+will place its modules.
.HP
.hy 0
.B objectclass "(\ <oid>\
name can also be used with a suffix of the form ":xx" in which case the
value "oid.xx" will be used.
.TP
-.B password-hash <hash> [<hash>...]
+.B password\-hash <hash> [<hash>...]
This option configures one or more hashes to be used in generation of user
passwords stored in the userPassword attribute during processing of
LDAP Password Modify Extended Operations (RFC 3062).
provides 31 characters of salt.
.TP
.B pidfile <filename>
-The ( absolute ) name of a file that will hold the
+The (absolute) name of a file that will hold the
.B slapd
-server's process ID ( see
-.BR getpid (2)
-) if started without the debugging command line option.
+server's process ID (see
+.BR getpid (2)).
.TP
.B referral <url>
Specify the referral to pass back when
set conditions within a particular database); it must occur first
in the list of conditions.
.TP
-.B reverse-lookup on | off
+.B reverse\-lookup on | off
Enable/disable client name unverified reverse lookup (default is
.BR off
-if compiled with --enable-rlookups).
+if compiled with \-\-enable\-rlookups).
.TP
.B rootDSE <file>
Specify the name of an LDIF(5) file containing user defined attributes
capabilities, in operational attributes.
It has the empty DN, and can be read with e.g.:
.ti +4
-ldapsearch -x -b "" -s base "+"
+ldapsearch \-x \-b "" \-s base "+"
.br
See RFC 4512 section 5.1 for details.
.TP
-.B sasl-host <fqdn>
+.B sasl\-auxprops <plugin> [...]
+Specify which auxprop plugins to use for authentication lookups. The
+default is empty, which just uses slapd's internal support. Usually
+no other auxprop plugins are needed.
+.TP
+.B sasl\-host <fqdn>
Used to specify the fully qualified domain name used for SASL processing.
.TP
-.B sasl-realm <realm>
+.B sasl\-realm <realm>
Specify SASL realm. Default is empty.
.TP
-.B sasl-secprops <properties>
+.B sasl\-secprops <properties>
Used to specify Cyrus SASL security properties.
The
.B none
.B security <factors>
Specify a set of security strength factors (separated by white space)
to require (see
-.BR sasl-secprops 's
+.BR sasl\-secprops 's
.B minssf
option for a description of security strength factors).
The directive may be specified globally and/or per-database.
.TP
.B serverID <integer> [<URL>]
Specify an integer ID from 0 to 4095 for this server (limited
-to 3 hexadecimal digits).
+to 3 hexadecimal digits). The ID may also be specified as a
+hexadecimal ID by prefixing the value with "0x".
These IDs are
required when using multimaster replication and each master must have a
-unique ID. If the URL is provided, this directive may be specified
+unique ID. Note that this requirement also applies to separate masters
+contributing to a glued set of databases.
+If the URL is provided, this directive may be specified
multiple times, providing a complete list of participating servers
and their IDs. The fully qualified hostname of each server should be
used in the supplied URLs. The IDs are used in the "replica id" field
attributes' syntax and matching rules and may not correspond to
lexical order or any other recognizable order.
.TP
+.B tcp-buffer [listener=<URL>] [{read|write}=]<size>
+Specify the size of the TCP buffer.
+A global value for both read and write TCP buffers related to any listener
+is defined, unless the listener is explicitly specified,
+or either the read or write qualifiers are used.
+See
+.BR tcp (7)
+for details.
+Note that some OS-es implement automatic TCP buffer tuning.
+.TP
.B threads <integer>
Specify the maximum size of the primary thread pool.
The default is 16; the minimum value is 2.
.BR limits
for an explanation of the different flags.
.TP
-.B tool-threads <integer>
+.B tool\-threads <integer>
Specify the maximum number of threads to use in tool mode.
This should not be greater than the number of CPUs in the system.
The default is 1.
.\".B ucdata-path <path>
.\"Specify the path to the directory containing the Unicode character
.\"tables. The default path is DATADIR/ucdata.
+.TP
+.B writetimeout <integer>
+Specify the number of seconds to wait before forcibly closing
+a connection with an outstanding write. This allows recovery from
+various network hang conditions. A writetimeout of 0 disables this
+feature. The default is 0.
.SH TLS OPTIONS
If
.B slapd
To check what ciphers a given spec selects, use:
.nf
- openssl ciphers -v <cipher-suite-spec>
+ openssl ciphers \-v <cipher-suite-spec>
.fi
To obtain the list of ciphers in GNUtls use:
.nf
- gnutls-cli -l
+ gnutls-cli \-l
.fi
.TP
or
.BR sql ,
depending on which backend will serve the database.
+
+LDAP operations, even subtree searches, normally access only one
+database.
+That can be changed by gluing databases together with the
+.B subordinate
+keyword.
+Access controls and some overlays can also involve multiple databases.
+.TP
+.B add_content_acl on | off
+Controls whether Add operations will perform ACL checks on
+the content of the entry being added. This check is off
+by default. See the
+.BR slapd.access (5)
+manual page for more details on ACL requirements for
+Add operations.
.TP
.B hidden on | off
Controls whether the database will be used to answer
the entryCSN and entryUUID attributes, which are needed
by the syncrepl provider. By default, lastmod is on.
.TP
-.B limits <who> <limit> [<limit> [...]]
-Specify time and size limits based on who initiated an operation.
+.B limits <selector> <limit> [<limit> [...]]
+Specify time and size limits based on the operation's initiator or
+base DN.
The argument
-.B who
+.B <selector>
can be any of
.RS
.RS
.TP
-anonymous | users | [dn[.<style>]=]<pattern> | group[/oc[/at]]=<pattern>
+anonymous | users | [<dnspec>=]<pattern> | group[/oc[/at]]=<pattern>
.RE
with
.RS
.TP
+<dnspec> ::= dn[.<type>][.<style>]
+.TP
+<type> ::= self | this
+.TP
<style> ::= exact | base | onelevel | subtree | children | regex | anonymous
.RE
+DN type
+.B self
+is the default and means the bound user, while
+.B this
+means the base DN of the operation.
The term
.B anonymous
matches all unauthenticated clients.
The same behavior is obtained by using the
.B anonymous
form of the
-.B who
+.B <selector>
clause.
The term
.BR group ,
.IR unlimited ,
no limit is applied (the default).
If it is set to
-.IR disable ,
+.IR disabled ,
the search is not even performed; this can be used to disallow searches
for a specific set of users.
If no limit specifier is set, the value is assigned to the
to preserve the original behavior.
In case of no match, the global limits are used.
-The default values are the same of
+The default values are the same as for
.B sizelimit
and
.BR timelimit ;
size limit of regular searches unless extended by the
.B prtotal
switch.
+
+The \fBlimits\fP statement is typically used to let an unlimited
+number of entries be returned by searches performed
+with the identity used by the consumer for synchronization purposes
+by means of the RFC 4533 LDAP Content Synchronization protocol
+(see \fBsyncrepl\fP for details).
.RE
.TP
.B maxderefdepth <depth>
This option puts the database into "read-only" mode. Any attempts to
modify the database will return an "unwilling to perform" error. By
default, readonly is off.
-.HP
-.hy 0
-.B replica uri=ldap[s]://<hostname>[:port]|host=<hostname>[:port]
-.B [starttls=yes|critical]
-.B [suffix=<suffix> [...]]
-.B bindmethod=simple|sasl [binddn=<simple DN>] [credentials=<simple password>]
-.B [saslmech=<SASL mech>] [secprops=<properties>] [realm=<realm>]
-.B [authcId=<authentication ID>] [authzId=<authorization ID>]
-.B [attrs[!]=<attr list>]
-.RS
-Specify a replication site for this database. Refer to the "OpenLDAP
-Administrator's Guide" for detailed information on setting up a replicated
-.B slapd
-directory service. Zero or more
-.B suffix
-instances can be used to select the subtrees that will be replicated
-(defaults to all the database).
-.B host
-is deprecated in favor of the
-.B uri
-option.
-.B uri
-allows the replica LDAP server to be specified as an LDAP URI.
-A
-.B bindmethod
-of
-.B simple
-requires the options
-.B binddn
-and
-.B credentials
-and should only be used when adequate security services
-(e.g TLS or IPSEC) are in place. A
-.B bindmethod
-of
-.B sasl
-requires the option
-.B saslmech.
-Specific security properties (as with the
-.B sasl-secprops
-keyword above) for a SASL bind can be set with the
-.B secprops
-option. A non-default SASL realm can be set with the
-.B realm
-option.
-If the
-.B mechanism
-will use Kerberos, a kerberos instance should be given in
-.B authcId.
-An
-.B attr list
-can be given after the
-.B attrs
-keyword to allow the selective replication of the listed attributes only;
-if the optional
-.B !
-mark is used, the list is considered exclusive, i.e. the listed attributes
-are not replicated.
-If an objectClass is listed, all the related attributes
-are (are not) replicated.
-.RE
.TP
.B restrict <oplist>
Specify a whitespace separated list of operations that are restricted.
(suffix) of the database.
This option accepts all RFC 2307 userPassword formats known to
the server (see
-.B password-hash
+.B password\-hash
description) as well as cleartext.
.BR slappasswd (8)
may be used to generate a hash of a password. Cleartext
Specify the DN suffix of queries that will be passed to this
backend database. Multiple suffix lines can be given and at least one is
required for each database definition.
+
If the suffix of one database is "inside" that of another, the database
with the inner suffix must come first in the configuration file.
+You may also want to glue such databases together with the
+.B subordinate
+keyword.
.TP
.B subordinate [advertise]
Specify that the current backend database is a subordinate of another
overlay syncprov
.fi
.RE
+.TP
+.B sync_use_subentry
+Store the syncrepl contextCSN in a subentry instead of the context entry
+of the database. The subentry's RDN will be "cn=ldapsync". By default
+the contextCSN is stored in the context entry.
.HP
.hy 0
.B syncrepl rid=<replica ID>
.B [sizelimit=<limit>]
.B [timelimit=<limit>]
.B [schemachecking=on|off]
+.B [network\-timeout=<seconds>]
+.B [timeout=<seconds>]
.B [bindmethod=simple|sasl]
.B [binddn=<dn>]
.B [saslmech=<mech>]
identifies the current
.B syncrepl
directive within the replication consumer site.
-It is a non-negative integer not greater than 4095 (limited
-to three hexadecimal digits).
+It is a non-negative integer not greater than 999 (limited
+to three decimal digits).
.B provider
specifies the replication provider site containing the master content
will send search requests to the provider
.B slapd
according to the search specification. The search specification includes
-.B searchbase, scope, filter, attrs, attrsonly, sizelimit,
+.BR searchbase ", " scope ", " filter ", " attrs ", " attrsonly ", " sizelimit ", "
and
.B timelimit
parameters as in the normal search specification.
The \fBscope\fP defaults to \fBsub\fP, the \fBfilter\fP defaults to
-\fB(objectclass=*)\fP, and there is no default \fBsearchbase\fP. The
+\fB(objectclass=*)\fP, while there is no default \fBsearchbase\fP. The
\fBattrs\fP list defaults to \fB"*,+"\fP to return all user and operational
attributes, and \fBattrsonly\fP is unset by default.
The \fBsizelimit\fP and \fBtimelimit\fP only
accept "unlimited" and positive integers, and both default to "unlimited".
+The \fBsizelimit\fP and \fBtimelimit\fP parameters define
+a consumer requested limitation on the number of entries that can be returned
+by the LDAP Content Synchronization operation; as such, it is intended
+to implement partial replication based on the size of the replicated database
+and on the time required by the synchronization.
Note, however, that any provider-side limits for the replication identity
will be enforced by the provider regardless of the limits requested
by the LDAP Content Synchronization operation, much like for any other
for the first 10 times and then retry every 300 seconds for the next 3
times before stop retrying. The `+' in <# of retries> means indefinite
number of retries until success.
+If no
+.B retry
+was specified, by default syncrepl retries every hour forever.
The schema checking can be enforced at the LDAP Sync
consumer site by turning on the
.B schemachecking
-parameter. The default is off.
+parameter. The default is \fBoff\fP.
+Schema checking \fBon\fP means that replicated entries must have
+a structural objectClass, must obey to objectClass requirements
+in terms of required/allowed attributes, and that naming attributes
+and distinguished values must be present.
+As a consequence, schema checking should be \fBoff\fP when partial
+replication is used.
+
+The
+.B network\-timeout
+parameter sets how long the consumer will wait to establish a
+network connection to the provider. Once a connection is
+established, the
+.B timeout
+parameter determines how long the consumer will wait for the initial
+Bind request to complete. The defaults for these parameters come
+from
+.BR ldap.conf (5).
A
.B bindmethod
.B authzid
parameter may be used to specify an authorization identity.
Specific security properties (as with the
-.B sasl-secprops
+.B sasl\-secprops
keyword above) for a SASL bind can be set with the
.B secprops
option. A non default SASL realm can be set with the
.B realm
option.
+The identity used for synchronization by the consumer should be allowed
+to receive an unlimited number of entries in response to a search request.
The provider, other than allow authentication of the syncrepl identity,
should grant that identity appropriate access privileges to the data
that is being replicated (\fBaccess\fP directive), and appropriate time
-and size limits (\fBlimits\fP directive).
-
+and size limits.
+This can be accomplished by either allowing unlimited \fBsizelimit\fP
+and \fBtimelimit\fP, or by setting an appropriate \fBlimits\fP statement
+in the consumer's configuration (see \fBsizelimit\fP and \fBlimits\fP
+for details).
The
.B starttls
parameters must be set appropriately for the log that will be used. The
.B syncdata
parameter must be set to either "accesslog" if the log conforms to the
-.BR slapo-accesslog (5)
+.BR slapo\-accesslog (5)
log format, or "changelog" if the log conforms
to the obsolete \fIchangelog\fP format. If the
.B syncdata
pidfile LOCALSTATEDIR/run/slapd.pid
# Subtypes of "name" (e.g. "cn" and "ou") with the
-# option ";x-hidden" can be searched for/compared,
+# option ";x\-hidden" can be searched for/compared,
# but are not shown. See \fBslapd.access\fP(5).
-attributeoptions x-hidden lang-
-access to attrs=name;x-hidden by * =cs
+attributeoptions x\-hidden lang\-
+access to attrs=name;x\-hidden by * =cs
# Protect passwords. See \fBslapd.access\fP(5).
access to attrs=userPassword by * auth
access to * by * read
database bdb
-suffix "dc=our-domain,dc=com"
+suffix "dc=our\-domain,dc=com"
# The database directory MUST exist prior to
# running slapd AND should only be accessible
# by the slapd/tools. Mode 0700 recommended.
-directory LOCALSTATEDIR/openldap-data
+directory LOCALSTATEDIR/openldap\-data
# Indices to maintain
index objectClass eq
index cn,sn,mail pres,eq,approx,sub
# so handle remote lookups on their behalf.
database ldap
suffix ""
-uri ldap://ldap.some-server.com/
+uri ldap://ldap.some\-server.com/
lastmod off
.fi
.RE