.TH SLAPD.CONF 5 "RELEASEDATE" "OpenLDAP LDVERSION"
-.\" Copyright 1998-2009 The OpenLDAP Foundation All Rights Reserved.
+.\" Copyright 1998-2012 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 authid\-rewrite<cmd> <args>
+Used by the authentication framework to convert simple user names
+to an LDAP DN used for authorization purposes.
+Its purpose is analogous to that of
+.BR authz-regexp
+(see below).
+The prefix \fIauthid\-\fP is followed by a set of rules analogous
+to those described in
+.BR slapo\-rwm (5)
+for data rewriting (replace the \fIrwm\-\fP prefix with \fIauthid\-\fP).
+.B authid\-rewrite<cmd>
+and
+.B authz\-regexp
+rules should not be intermixed.
+.TP
+.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
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
.IR URI ,
provided it results in exactly one entry,
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, or extracted from certificates
in case of cert-based SASL EXTERNAL, or provided within the RFC 4370
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.
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
.hy 0
.B ldapsyntax "(\ <oid>\
[DESC\ <description>]\
- [X-SUBST <substitute\-syntax>]\ )"
+ [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
.B objectidentifier
description.)
The slapd parser also honors the
-.B X-SUBST
+.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 ,
+.IR substitute-syntax ,
as its temporary replacement.
The
-.I substitute\-syntax
+.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
+.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 listener-threads <integer>
+Specify the number of threads to use for the connection manager.
+The default is 1 and this is typically adequate for up to 16 CPU cores.
+The value should be set to a power of 2.
.TP
.B localSSF <SSF>
Specifies the Security Strength Factor (SSF) to be given local LDAP sessions,
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. Note that this requirement also applies to separate masters
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
.TP
.B TLSCipherSuite <cipher-suite-spec>
Permits configuring what ciphers will be accepted and the preference order.
-<cipher-suite-spec> should be a cipher specification for OpenSSL. Example:
-
+<cipher-suite-spec> should be a cipher specification for the TLS library
+in use (OpenSSL, GnuTLS, or Mozilla NSS).
+Example:
+.RS
+.RS
+.TP
+.I OpenSSL:
TLSCipherSuite HIGH:MEDIUM:+SSLv2
+.TP
+.I GnuTLS:
+TLSCiphersuite SECURE256:!AES-128-CBC
+.RE
-To check what ciphers a given spec selects, use:
+To check what ciphers a given spec selects in OpenSSL, use:
.nf
- openssl ciphers -v <cipher-suite-spec>
+ openssl ciphers \-v <cipher-suite-spec>
.fi
-To obtain the list of ciphers in GNUtls use:
+With GnuTLS the available specs can be found in the manual page of
+.BR gnutls\-cli (1)
+(see the description of the
+option
+.BR \-\-priority ).
+
+In older versions of GnuTLS, where gnutls\-cli does not support the option
+\-\-priority, you can obtain the \(em more limited \(em list of ciphers by calling:
.nf
- gnutls-cli -l
+ gnutls\-cli \-l
.fi
+When using Mozilla NSS, the OpenSSL cipher suite specifications are used and
+translated into the format used internally by Mozilla NSS. There isn't an easy
+way to list the cipher suites from the command line. The authoritative list
+is in the source code for Mozilla NSS in the file sslinfo.c in the structure
+.nf
+ static const SSLCipherSuiteInfo suiteInfo[]
+.fi
+.RE
.TP
.B TLSCACertificateFile <filename>
Specifies the file that contains certificates for all of the Certificate
Authorities that
.B slapd
-will recognize.
+will recognize. The certificate for
+the CA that signed the server certificate must be included among
+these certificates. If the signing CA was not a top-level (root) CA,
+certificates for the entire sequence of CA's from the signing CA to
+the top-level CA should be present. Multiple certificates are simply
+appended to the file; the order is not significant.
.TP
.B TLSCACertificatePath <path>
Specifies the path of a directory that contains Certificate Authority
certificates in separate individual files. Usually only one of this
or the TLSCACertificateFile is used. This directive is not supported
-when using GNUtls.
+when using GnuTLS.
+
+When using Mozilla NSS, <path> may contain a Mozilla NSS cert/key
+database. If <path> contains a Mozilla NSS cert/key database and
+CA cert files, OpenLDAP will use the cert/key database and will
+ignore the CA cert files.
.TP
.B TLSCertificateFile <filename>
Specifies the file that contains the
.B slapd
server certificate.
+
+When using Mozilla NSS, if using a cert/key database (specified with
+TLSCACertificatePath), TLSCertificateFile specifies
+the name of the certificate to use:
+.nf
+ TLSCertificateFile Server-Cert
+.fi
+If using a token other than the internal built in token, specify the
+token name first, followed by a colon:
+.nf
+ TLSCertificateFile my hardware device:Server-Cert
+.fi
+Use certutil -L to list the certificates by name:
+.nf
+ certutil -d /path/to/certdbdir -L
+.fi
.TP
.B TLSCertificateKeyFile <filename>
Specifies the file that contains the
.B TLSCertificateFile
file. Currently, the private key must not be protected with a password, so
it is of critical importance that it is protected carefully.
+
+When using Mozilla NSS, TLSCertificateKeyFile specifies the name of
+a file that contains the password for the key for the certificate specified with
+TLSCertificateFile. The modutil command can be used to turn off password
+protection for the cert/key database. For example, if TLSCACertificatePath
+specifes /etc/openldap/certdb as the location of the cert/key database, use
+modutil to change the password to the empty string:
+.nf
+ modutil -dbdir /etc/openldap/certdb -changepw 'NSS Certificate DB'
+.fi
+You must have the old password, if any. Ignore the WARNING about the running
+browser. Press 'Enter' for the new password.
.TP
.B TLSDHParamFile <filename>
This directive specifies the file that contains parameters for Diffie-Hellman
Anonymous Diffie-Hellman key exchanges in certain non-default cipher suites.
You should append "!ADH" to your cipher suites if you have changed them
from the default, otherwise no certificate exchanges or verification will
-be done. When using GNUtls these parameters are always generated randomly so
-this directive is ignored.
+be done. When using GnuTLS these parameters are always generated randomly so
+this directive is ignored. This directive is ignored when using Mozilla NSS.
.TP
.B TLSRandFile <filename>
Specifies the file to obtain random bits from when /dev/[u]random
is not available. Generally set to the name of the EGD/PRNGD socket.
The environment variable RANDFILE can also be used to specify the filename.
-This directive is ignored with GNUtls.
+This directive is ignored with GnuTLS and Mozilla NSS.
.TP
.B TLSVerifyClient <level>
Specifies what checks to perform on client certificates in an
used to verify if the client certificates have not been revoked. This
requires
.B TLSCACertificatePath
-parameter to be set. This directive is ignored with GNUtls.
+parameter to be set. This directive is ignored with GnuTLS and Mozilla NSS.
.B <level>
can be specified as one of the following keywords:
.RS
.B TLSCRLFile <filename>
Specifies a file containing a Certificate Revocation List to be used
for verifying that certificates have not been revoked. This directive is
-only valid when using GNUtls.
+only valid when using GnuTLS and Mozilla NSS.
.SH GENERAL BACKEND OPTIONS
Options in this section only apply to the configuration file section
for the specified backend. They are supported by every
manual page for more details on ACL requirements for
Add operations.
.TP
+.B extra_attrs <attrlist>
+Lists what attributes need to be added to search requests.
+Local storage backends return the entire entry to the frontend.
+The frontend takes care of only returning the requested attributes
+that are allowed by ACLs.
+However, features like access checking and so may need specific
+attributes that are not automatically returned by remote storage
+backends, like proxy backends and so on.
+.B <attrlist>
+is a list of attributes that are needed for internal purposes
+and thus always need to be collected, even when not explicitly
+requested by clients.
+.TP
.B hidden on | off
Controls whether the database will be used to answer
queries. A database that is hidden will never be
(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
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 [network\-timeout=<seconds>]
.B [timeout=<seconds>]
.B [bindmethod=simple|sasl]
.B [binddn=<dn>]
.B [credentials=<passwd>]
.B [realm=<realm>]
.B [secprops=<properties>]
+.B [keepalive=<idle>:<probes>:<interval>]
.B [starttls=yes|critical]
.B [tls_cert=<file>]
.B [tls_key=<file>]
.B [tls_reqcert=never|allow|try|demand]
.B [tls_ciphersuite=<ciphers>]
.B [tls_crlcheck=none|peer|all]
+.B [suffixmassage=<real DN>]
.B [logbase=<base DN>]
.B [logfilter=<filter str>]
.B [syncdata=default|accesslog|changelog]
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
replication is used.
The
-.B network-timeout
+.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 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
in the consumer's configuration (see \fBsizelimit\fP and \fBlimits\fP
for details).
+The
+.B keepalive
+parameter sets the values of \fIidle\fP, \fIprobes\fP, and \fIinterval\fP
+used to check whether a socket is alive;
+.I idle
+is the number of seconds a connection needs to remain idle before TCP
+starts sending keepalive probes;
+.I probes
+is the maximum number of keepalive probes TCP should send before dropping
+the connection;
+.I interval
+is interval in seconds between individual keepalive probes.
+Only some systems support the customization of these values;
+the
+.B keepalive
+parameter is ignored otherwise, and system-wide settings are used.
+
The
.B starttls
parameter specifies use of the StartTLS extended operation
tls_reqcert setting defaults to "demand" and the other TLS settings
default to the same as the main slapd TLS settings.
+The
+.B suffixmassage
+parameter allows the consumer to pull entries from a remote directory
+whose DN suffix differs from the local directory. The portion of the
+remote entries' DNs that matches the \fIsearchbase\fP will be replaced
+with the suffixmassage DN.
+
Rather than replicating whole entries, the consumer can query logs of
data modifications. This mode of operation is referred to as \fIdelta
syncrepl\fP. In addition to the above parameters, the
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
default slapd configuration file
.SH SEE ALSO
.BR ldap (3),
+.BR gnutls\-cli (1),
.BR slapd\-config (5),
.BR slapd.access (5),
.BR slapd.backends (5),
projects / openldap / blobdiff