diff options
Diffstat (limited to 'doc/man/man5/slapd-config.5')
| -rw-r--r-- | doc/man/man5/slapd-config.5 | 2274 |
1 files changed, 2274 insertions, 0 deletions
diff --git a/doc/man/man5/slapd-config.5 b/doc/man/man5/slapd-config.5 new file mode 100644 index 0000000..d402340 --- /dev/null +++ b/doc/man/man5/slapd-config.5 @@ -0,0 +1,2274 @@ +.TH SLAPD-CONFIG 5 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.\" $OpenLDAP$ +.SH NAME +slapd\-config \- configuration backend to slapd +.SH SYNOPSIS +ETCDIR/slapd.d +.SH DESCRIPTION +The +.B config +backend manages all of the configuration information for the +.BR slapd (8) +daemon. This configuration information is also used by the SLAPD tools +.BR slapacl (8), +.BR slapadd (8), +.BR slapauth (8), +.BR slapcat (8), +.BR slapdn (8), +.BR slapindex (8), +.BR slapmodify (8), +and +.BR slaptest (8). +.LP +The +.B config +backend is backward compatible with the older +.BR slapd.conf (5) +file but provides the ability to change the configuration dynamically +at runtime. If slapd is run with only a +.B slapd.conf +file dynamic changes will be allowed but they will not persist across +a server restart. Dynamic changes are only saved when slapd is running +from a +.B slapd.d +configuration directory. +.LP + +Unlike other backends, there can only be one instance of the +.B config +backend, and most of its structure is predefined. The root of the +database is hardcoded to +.B "cn=config" +and this root entry contains +global settings for slapd. Multiple child entries underneath the +root entry are used to carry various other settings: +.RS +.TP +.B cn=Module +dynamically loaded modules +.TP +.B cn=Schema +schema definitions +.TP +.B olcBackend=xxx +backend-specific settings +.TP +.B olcDatabase=xxx +database-specific settings +.RE + +The +.B cn=Module +entries will only appear in configurations where slapd +was built with support for dynamically loaded modules. There can be +multiple entries, one for each configured module path. Within each +entry there will be values recorded for each module loaded on a +given path. These entries have no children. + +The +.B cn=Schema +entry contains all of the hardcoded schema elements. +The children of this entry contain all user-defined schema elements. +In schema that were loaded from include files, the child entry will +be named after the include file from which the schema was loaded. +Typically the first child in this subtree will be +.BR cn=core,cn=schema,cn=config . + +.B olcBackend +entries are for storing settings specific to a single +backend type (and thus global to all database instances of that type). +At present, only back-mdb implements any options of this type, so this +setting is not needed for any other backends. + +.B olcDatabase +entries store settings specific to a single database +instance. These entries may have +.B olcOverlay +child entries corresponding +to any overlays configured on the database. The olcDatabase and +olcOverlay entries may also have miscellaneous child entries for +other settings as needed. There are two special database entries +that are predefined \- one is an entry for the config database itself, +and the other is for the "frontend" database. Settings in the +frontend database are inherited by the other databases, unless +they are explicitly overridden in a specific database. +.LP +The specific configuration options available are discussed below in the +Global Configuration Options, General Backend Options, and General Database +Options. Options are set by defining LDAP attributes with specific values. +In general the names of the LDAP attributes are the same as the corresponding +.B slapd.conf +keyword, with an "olc" prefix added on. + +The parser for many of these attributes is the same as used for parsing +the slapd.conf keywords. As such, slapd.conf keywords that allow multiple +items to be specified on one line, separated by whitespace, will allow +multiple items to be specified in one attribute value. However, when +reading the attribute via LDAP, the items will be returned as individual +attribute values. + +Backend-specific options are discussed in the +.B slapd\-<backend>(5) +manual pages. Refer to the "OpenLDAP Administrator's Guide" for more +details on configuring slapd. +.SH GLOBAL CONFIGURATION OPTIONS +Options described in this section apply to the server as a whole. +Arguments that should be replaced by +actual text are shown in brackets <>. + +These options may only be specified in the +.B cn=config +entry. This entry must have an objectClass of +.BR olcGlobal . + +.TP +.B olcAllows: <features> +Specify a set of features to allow (default none). +.B bind_v2 +allows acceptance of LDAPv2 bind requests. Note that +.BR slapd (8) +does not truly implement LDAPv2 (RFC 1777), now Historic (RFC 3494). +.B bind_anon_cred +allows anonymous bind when credentials are not empty (e.g. +when DN is empty). +.B bind_anon_dn +allows unauthenticated (anonymous) bind when DN is not empty. +.B update_anon +allows unauthenticated (anonymous) update operations to be processed +(subject to access controls and other administrative limits). +.B proxy_authz_anon +allows unauthenticated (anonymous) proxy authorization control to be processed +(subject to access controls, authorization and other administrative limits). +.TP +.B olcArgsFile: <filename> +The (absolute) name of a file that will hold the +.B slapd +server's command line (program name and options). +.TP +.B olcAttributeOptions: <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. +If you use the +.B olcAttributeOptions +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: +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'. +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'. + +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. +.TP +.B olcAuthIDRewrite: <rewrite\-rule> +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 olcAuthzRegexp +(see below). +The +.B rewrite\-rule +is a set of rules analogous to those described in +.BR slapo\-rwm (5) +for data rewriting (after stripping the \fIrwm\-\fP prefix). +.B olcAuthIDRewrite +and +.B olcAuthzRegexp +should not be intermixed. +.TP +.B olcAuthzPolicy: <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 +and access control purposes. It essentially allows user A to login as user +B, using user A's password. +The +.B none +flag disables proxy authorization. This is the default setting. +The +.B from +flag will use rules in the +.I authzFrom +attribute of the authorization DN. +The +.B to +flag will use rules in the +.I authzTo +attribute of the authentication DN. +The +.B any +flag, an alias for the deprecated value of +.BR both , +will allow any of the above, whatever succeeds first (checked in +.BR to , +.B from +sequence. +The +.B all +flag requires both authorizations to succeed. +.LP +.RS +The rules are mechanisms to specify which identities are allowed +to perform proxy authorization. +The +.I authzFrom +attribute in an entry specifies which other users +are allowed to proxy login to this entry. The +.I authzTo +attribute in +an entry specifies which other users this user can authorize as. Use of +.I authzTo +rules can be easily +abused if users are allowed to write arbitrary values to this attribute. +In general the +.I authzTo +attribute must be protected with ACLs such that +only privileged users can modify it. +The value of +.I authzFrom +and +.I authzTo +describes an +.B identity +or a set of identities; it can take five forms: +.RS +.TP +.B ldap:///<base>??[<scope>]?<filter> +.RE +.RS +.B dn[.<dnstyle>]:<pattern> +.RE +.RS +.B u[.<mech>[<realm>]]:<pattern> +.RE +.RS +.B group[/objectClass[/attributeType]]:<pattern> +.RE +.RS +.B <pattern> +.RE +.RS + +.B <dnstyle>:={exact|onelevel|children|subtree|regex} + +.RE +The first form is a valid LDAP +.B URI +where the +.IR <host>:<port> , +the +.I <attrs> +and the +.I <extensions> +portions must be absent, so that the search occurs locally on either +.I authzFrom +or +.IR authzTo . + +.LP +The second form is a +.BR DN , +with the optional style modifiers +.IR exact , +.IR onelevel , +.IR children , +and +.I subtree +for exact, onelevel, children and subtree matches, which cause +.I <pattern> +to be normalized according to the DN normalization rules, or the special +.I regex +style, which causes the +.I <pattern> +to be treated as a POSIX (''extended'') regular expression, as +discussed in +.BR regex (7) +and/or +.BR re_format (7). +A pattern of +.I * +means any non-anonymous DN. + +.LP +The third form is a SASL +.BR id , +with the optional fields +.I <mech> +and +.I <realm> +that allow to specify a SASL +.BR mechanism , +and eventually a SASL +.BR realm , +for those mechanisms that support one. +The need to allow the specification of a mechanism is still debated, +and users are strongly discouraged to rely on this possibility. + +.LP +The fourth form is a group specification. +It consists of the keyword +.BR group , +optionally followed by the specification of the group +.B objectClass +and +.BR attributeType . +The +.B objectClass +defaults to +.IR groupOfNames . +The +.B attributeType +defaults to +.IR member . +The group with DN +.B <pattern> +is searched with base scope, filtered on the specified +.BR objectClass . +The values of the resulting +.B attributeType +are searched for the asserted DN. + +.LP +The fifth form is provided for backwards compatibility. If no identity +type is provided, i.e. only +.B <pattern> +is present, an +.I exact DN +is assumed; as a consequence, +.B <pattern> +is subjected to DN normalization. + +.LP +Since the interpretation of +.I authzFrom +and +.I authzTo +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 olcAuthzRegexp +statement (see below); significantly, the +.IR URI , +provided it results in exactly one entry, +and the +.I dn.exact:<dn> +forms. +.RE +.TP +.B olcAuthzRegexp: <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 +"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 , +.BR REALM , +and +.B MECHANISM +are taken, when available, and combined into a name of the form +.RS +.RS +.TP +.B UID=<username>[[,CN=<realm>],CN=<mechanism>],CN=auth + +.RE +This name is then compared against the +.B match +POSIX (''extended'') regular expression, and if the match is successful, +the name is replaced with the +.B replace +string. If there are wildcard strings in the +.B match +regular expression that are enclosed in parenthesis, e.g. +.RS +.TP +.B UID=([^,]*),CN=.* + +.RE +then the portion of the name that matched the wildcard will be stored +in the numbered placeholder variable $1. If there are other wildcard strings +in parenthesis, the matching strings will be in $2, $3, etc. up to $9. The +placeholders can then be used in the +.B replace +string, e.g. +.RS +.TP +.B UID=$1,OU=Accounts,DC=example,DC=com + +.RE +The replaced name can be either a DN, i.e. a string prefixed by "dn:", +or an LDAP URI. +If the latter, the server will use the URI to search its own database(s) +and, if the search returns exactly one entry, the name is +replaced by the DN of that entry. The LDAP URI must have no +hostport, attrs, or extensions components, but the filter is mandatory, +e.g. +.RS +.TP +.B ldap:///OU=Accounts,DC=example,DC=com??one?(UID=$1) + +.RE +The protocol portion of the URI must be strictly +.BR ldap . +Note that this search is subject to access controls. Specifically, +the authentication identity must have "auth" access in the subject. + +Multiple +.B olcAuthzRegexp +values can be specified to allow for multiple matching +and replacement patterns. The matching patterns are checked in the order they +appear in the attribute, stopping at the first successful match. + +.\".B Caution: +.\"Because the plus sign + is a character recognized by the regular expression engine, +.\"and it will appear in names that include a REALM, be careful to escape the +.\"plus sign with a backslash \\+ to remove the character's special meaning. +.RE +.TP +.B olcConcurrency: <integer> +Specify a desired level of concurrency. Provided to the underlying +thread system as a hint. The default is not to provide any hint. This setting +is only meaningful on some platforms where there is not a one to one +correspondence between user threads and kernel threads. +.TP +.B olcConnMaxPending: <integer> +Specify the maximum number of pending requests for an anonymous session. +If requests are submitted faster than the server can process them, they +will be queued up to this limit. If the limit is exceeded, the session +is closed. The default is 100. +.TP +.B olcConnMaxPendingAuth: <integer> +Specify the maximum number of pending requests for an authenticated session. +The default is 1000. +.TP +.B olcDisallows: <features> +Specify a set of features to disallow (default none). +.B bind_anon +disables acceptance of anonymous bind requests. Note that this setting +does not prohibit anonymous directory access (See "require authc"). +.B bind_simple +disables simple (bind) authentication. +.B tls_2_anon +disables forcing session to anonymous status (see also +.BR tls_authc ) +upon StartTLS operation receipt. +.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) +with criticality set to FALSE. +.B dontusecopy_non_critical +disables acceptance of the dontUseCopy control (a work in progress) +with criticality set to FALSE. +.TP +.B olcGentleHUP: { TRUE | FALSE } +A SIGHUP signal will only cause a 'gentle' shutdown-attempt: +.B Slapd +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 \- +if it receives a SIGTERM signal. This can be useful if you wish to +terminate the server and start a new +.B slapd +server +.B with another database, +without disrupting the currently active clients. +The default is FALSE. You may wish to use +.B olcIdleTimeout +along with this option. +.TP +.B olcIdleTimeout: <integer> +Specify the number of seconds to wait before forcibly closing +an idle client connection. A setting of 0 disables this +feature. The default is 0. You may also want to set the +.B olcWriteTimeout +option. +.TP +.B olcIndexHash64: { on | off } +Use a 64 bit hash for indexing. The default is to use 32 bit hashes. +These hashes are used for equality and substring indexing. The 64 bit +version may be needed to avoid index collisions when the number of +indexed values exceeds ~64 million. (Note that substring indexing +generates multiple index values per actual attribute value.) +Indices generated with 32 bit hashes are incompatible with the 64 bit +version, and vice versa. Any existing databases must be fully reloaded +when changing this setting. This directive is only supported on 64 bit CPUs. +.TP +.B olcIndexIntLen: <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 olcIndexSubstrIfMaxlen: <integer> +Specify the maximum length for subinitial and subfinal indices. Only +this many characters of an attribute value will be processed by the +indexing functions; any excess characters are ignored. The default is 4. +.TP +.B olcIndexSubstrIfMinlen: <integer> +Specify the minimum length for subinitial and subfinal indices. An +attribute value must have at least this many characters in order to be +processed by the indexing functions. The default is 2. +.TP +.B olcIndexSubstrAnyLen: <integer> +Specify the length used for subany indices. An attribute value must have +at least this many characters in order to be processed. Attribute values +longer than this length will be processed in segments of this length. The +default is 4. The subany index will also be used in subinitial and +subfinal index lookups when the filter string is longer than the +.I olcIndexSubstrIfMaxlen +value. +.TP +.B olcIndexSubstrAnyStep: <integer> +Specify the steps used in subany index lookups. This value sets the offset +for the segments of a filter string that are processed for a subany index +lookup. The default is 2. For example, with the default values, a search +using this filter "cn=*abcdefgh*" would generate index lookups for +"abcd", "cdef", and "efgh". + +.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). + +.TP +.B olcListenerThreads: <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 olcLocalSSF: <SSF> +Specifies the Security Strength Factor (SSF) to be given local LDAP sessions, +such as those to the ldapi:// listener. For a description of SSF values, +see +.BR olcSaslSecProps 's +.B minssf +option description. The default is 71. +.TP +.B olcLogFile: <filename> +Specify a file for recording slapd debug messages. By default these messages +only go to stderr, are not recorded anywhere else, and are unrelated to +messages exposed by the +.B loglevel +configuration parameter. Specifying a logfile copies messages to both stderr +and the logfile. +.TP +.B olcLogLevel: <integer> [...] +Specify the level at which debugging statements and operation +statistics should be syslogged (currently logged to the +.BR syslogd (8) +LOG_LOCAL4 facility). +They must be considered subsystems rather than increasingly verbose +log levels. +Some messages with higher priority are logged regardless +of the configured loglevel as soon as any logging is configured. +Log levels are additive, and available levels are: +.RS +.RS +.PD 0 +.TP +.B 1 +.B (0x1 trace) +trace function calls +.TP +.B 2 +.B (0x2 packets) +debug packet handling +.TP +.B 4 +.B (0x4 args) +heavy trace debugging (function args) +.TP +.B 8 +.B (0x8 conns) +connection management +.TP +.B 16 +.B (0x10 BER) +print out packets sent and received +.TP +.B 32 +.B (0x20 filter) +search filter processing +.TP +.B 64 +.B (0x40 config) +configuration file processing +.TP +.B 128 +.B (0x80 ACL) +access control list processing +.TP +.B 256 +.B (0x100 stats) +connections, LDAP operations, results (recommended) +.TP +.B 512 +.B (0x200 stats2) +stats2 log entries sent +.TP +.B 1024 +.B (0x400 shell) +print communication with shell backends +.TP +.B 2048 +.B (0x800 parse) +entry parsing +\".TP +\".B 4096 +\".B (0x1000 cache) +\"caching (unused) +\".TP +\".B 8192 +\".B (0x2000 index) +\"data indexing (unused) +.TP +.B 16384 +.B (0x4000 sync) +LDAPSync replication +.TP +.B 32768 +.B (0x8000 none) +only messages that get logged whatever log level is set +.PD +.RE +The desired log level can be input as a single integer that combines +the (ORed) desired levels, both in decimal or in hexadecimal notation, +as a list of integers (that are ORed internally), +or as a list of the names that are shown between parenthesis, such that +.LP +.nf + olcLogLevel: 129 + olcLogLevel: 0x81 + olcLogLevel: 128 1 + olcLogLevel: 0x80 0x1 + olcLogLevel: acl trace +.fi +.LP +are equivalent. +The keyword +.B any +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 +that are logged regardless of the configured olcLogLevel to be logged. +In fact, if no olcLogLevel (or a 0 level) is defined, no logging occurs, +so at least the +.B none +level is required to have high priority messages logged. + +Note that the +.BR packets , +.BR BER , +and +.B parse +levels are only available as debug output on stderr, and are not +sent to syslog. + +This setting defaults to \fBstats\fP. +This level should usually also be included when using other loglevels, to +help analyze the logs. +.RE +.TP +.B olcMaxFilterDepth: <integer> +Specify the maximum depth of nested filters in search requests. +The default is 1000. +.TP +.B olcPasswordCryptSaltFormat: <format> +Specify the format of the salt passed to +.BR crypt (3) +when generating {CRYPT} passwords (see +.BR olcPasswordHash ) +during processing of LDAP Password Modify Extended Operations (RFC 3062). + +This string needs to be in +.BR sprintf (3) +format and may include one (and only one) %s conversion. +This conversion will be substituted with a string of random +characters from [A\-Za\-z0\-9./]. For example, "%.2s" +provides a two character salt and "$1$%.8s" tells some +versions of crypt(3) to use an MD5 algorithm and provides +8 random characters of salt. The default is "%s", which +provides 31 characters of salt. +.TP +.B olcPidFile: <filename> +The (absolute) name of a file that will hold the +.B slapd +server's process ID (see +.BR getpid (2)). +.TP +.B olcPluginLogFile: <filename> +The ( absolute ) name of a file that will contain log +messages from +.B SLAPI +plugins. See +.BR slapd.plugin (5) +for details. +.TP +.B olcReferral: <url> +Specify the referral to pass back when +.BR slapd (8) +cannot find a local database to handle a request. +If multiple values are specified, each url is provided. +.TP +.B olcReverseLookup: TRUE | FALSE +Enable/disable client name unverified reverse lookup (default is +.BR FALSE +if compiled with \-\-enable\-rlookups). +.TP +.B olcRootDSE: <file> +Specify the name of an LDIF(5) file containing user defined attributes +for the root DSE. These attributes are returned in addition to the +attributes normally produced by slapd. + +The root DSE is an entry with information about the server and its +capabilities, in operational attributes. +It has the empty DN, and can be read with e.g.: +.ti +4 +ldapsearch \-x \-b "" \-s base "+" +.br +See RFC 4512 section 5.1 for details. +.TP +.B olcSaslAuxprops: <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 olcSaslAuxpropsDontUseCopy: <attr> [...] +Specify which attribute(s) should be subject to the don't use copy control. This +is necessary for some SASL mechanisms such as OTP to work in a replicated +environment. The attribute "cmusaslsecretOTP" is the default value. +.TP +.B olcSaslAuxpropsDontUseCopyIgnore TRUE | FALSE +Used to disable replication of the attribute(s) defined by +olcSaslAuxpropsDontUseCopy and instead use a local value for the attribute. This +allows the SASL mechanism to continue to work if the provider is offline. This can +cause replication inconsistency. Defaults to FALSE. +.TP +.B olcSaslHost: <fqdn> +Used to specify the fully qualified domain name used for SASL processing. +.TP +.B olcSaslRealm: <realm> +Specify SASL realm. Default is empty. +.TP +.B olcSaslCbinding: none | tls-unique | tls-endpoint +Specify the channel-binding type, see also LDAP_OPT_X_SASL_CBINDING. +Default is none. +.TP +.B olcSaslSecProps: <properties> +Used to specify Cyrus SASL security properties. +The +.B none +flag (without any other properties) causes the flag properties +default, "noanonymous,noplain", to be cleared. +The +.B noplain +flag disables mechanisms susceptible to simple passive attacks. +The +.B noactive +flag disables mechanisms susceptible to active attacks. +The +.B nodict +flag disables mechanisms susceptible to passive dictionary attacks. +The +.B noanonymous +flag disables mechanisms which support anonymous login. +The +.B forwardsec +flag require forward secrecy between sessions. +The +.B passcred +require mechanisms which pass client credentials (and allow +mechanisms which can pass credentials to do so). +The +.B minssf=<factor> +property specifies the minimum acceptable +.I security strength factor +as an integer approximate to effective key length used for +encryption. 0 (zero) implies no protection, 1 implies integrity +protection only, 128 allows RC4, Blowfish and other similar ciphers, +256 will require modern ciphers. The default is 0. +The +.B maxssf=<factor> +property specifies the maximum acceptable +.I security strength factor +as an integer (see minssf description). The default is INT_MAX. +The +.B maxbufsize=<size> +property specifies the maximum security layer receive buffer +size allowed. 0 disables security layers. The default is 65536. +.TP +.B olcServerID: <integer> [<URL>] +Specify an integer ID from 0 to 4095 for this server. The ID may also be +specified as a hexadecimal ID by prefixing the value with "0x". +Non-zero IDs are required when using multi-provider replication and each +provider must have a unique non-zero ID. Note that this requirement also +applies to separate providers 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 +of all CSNs generated by the specified server. The default value is zero, which +is only valid for single provider replication. +Example: +.LP +.nf + olcServerID: 1 ldap://ldap1.example.com + olcServerID: 2 ldap://ldap2.example.com +.fi +.TP +.B olcSockbufMaxIncoming: <integer> +Specify the maximum incoming LDAP PDU size for anonymous sessions. +The default is 262143. +.TP +.B olcSockbufMaxIncomingAuth: <integer> +Specify the maximum incoming LDAP PDU size for authenticated sessions. +The default is 4194303. +.TP +.B olcTCPBuffer [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 olcThreads: <integer> +Specify the maximum size of the primary thread pool. +The default is 16; the minimum value is 2. +.TP +.B olcThreadQueues: <integer> +Specify the number of work queues to use for the primary thread pool. +The default is 1 and this is typically adequate for up to 8 CPU cores. +The value should not exceed the number of CPUs in the system. +.TP +.B olcToolThreads: <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. +.TP +.B olcWriteTimeout: <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 setting of 0 disables this +feature. The default is 0. +.SH TLS OPTIONS +If +.B slapd +is built with support for Transport Layer Security, there are more options +you can specify. +.TP +.B olcTLSCipherSuite: <cipher-suite-spec> +Permits configuring what ciphers will be accepted and the preference order. +<cipher-suite-spec> should be a cipher specification for the TLS library +in use (OpenSSL or GnuTLS). +Example: +.RS +.RS +.TP +.I OpenSSL: +olcTLSCipherSuite: HIGH:MEDIUM:+SSLv2 +.TP +.I GnuTLS: +olcTLSCiphersuite: SECURE256:!AES-128-CBC +.RE + +To check what ciphers a given spec selects in OpenSSL, use: + +.nf + openssl ciphers \-v <cipher-suite-spec> +.fi + +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 +.fi +.RE +.TP +.B olcTLSCACertificateFile: <filename> +Specifies the file that contains certificates for all of the Certificate +Authorities that +.B slapd +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 olcTLSCACertificatePath: <path> +Specifies the path of a directory that contains Certificate Authority +certificates in separate individual files. Usually only one of this +or the olcTLSCACertificateFile is defined. If both are specified, both +locations will be used. +.TP +.B olcTLSCertificateFile: <filename> +Specifies the file that contains the +.B slapd +server certificate. + +When using OpenSSL that file may also contain any number of intermediate +certificates after the server certificate. +.TP +.B olcTLSCertificateKeyFile: <filename> +Specifies the file that contains the +.B slapd +server private key that matches the certificate stored in the +.B olcTLSCertificateFile +file. If the private key is protected with a password, the password must +be manually typed in when slapd starts. Usually the private key is not +protected with a password, to allow slapd to start without manual +intervention, so +it is of critical importance that the file is protected carefully. +.TP +.B olcTLSDHParamFile: <filename> +This directive specifies the file that contains parameters for Diffie-Hellman +ephemeral key exchange. This is required in order to use a DSA certificate on +the server, or an RSA certificate missing the "key encipherment" key usage. +Note that setting this option may also enable +Anonymous Diffie-Hellman key exchanges in certain non-default cipher suites. +Anonymous key exchanges should generally be avoided since they provide no +actual client or server authentication and provide no protection against +man-in-the-middle attacks. +You should append "!ADH" to your cipher suites to ensure that these suites +are not used. +.TP +.B olcTLSECName: <name> +Specify the name of the curve(s) to use for Elliptic curve Diffie-Hellman +ephemeral key exchange. This option is only used for OpenSSL. +This option is not used with GnuTLS; the curves may be +chosen in the GnuTLS ciphersuite specification. +.TP +.B olcTLSProtocolMin: <major>[.<minor>] +Specifies minimum SSL/TLS protocol version that will be negotiated. +If the server doesn't support at least that version, +the SSL handshake will fail. +To require TLS 1.x or higher, set this option to 3.(x+1), +e.g., + +.nf + olcTLSProtocolMin: 3.2 +.fi + +would require TLS 1.1. +Specifying a minimum that is higher than that supported by the +OpenLDAP implementation will result in it requiring the +highest level that it does support. +This directive is ignored with GnuTLS. +.TP +.B olcTLSRandFile: <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. +.TP +.B olcTLSVerifyClient: <level> +Specifies what checks to perform on client certificates in an +incoming TLS session, if any. +The +.B <level> +can be specified as one of the following keywords: +.RS +.TP +.B never +This is the default. +.B slapd +will not ask the client for a certificate. +.TP +.B allow +The client certificate is requested. If no certificate is provided, +the session proceeds normally. If a bad certificate is provided, +it will be ignored and the session proceeds normally. +.TP +.B try +The client certificate is requested. If no certificate is provided, +the session proceeds normally. If a bad certificate is provided, +the session is immediately terminated. +.TP +.B demand | hard | true +These keywords are all equivalent, for compatibility reasons. +The client certificate is requested. If no certificate is provided, +or a bad certificate is provided, the session is immediately terminated. + +Note that a valid client certificate is required in order to use the +SASL EXTERNAL authentication mechanism with a TLS session. As such, +a non-default +.B olcTLSVerifyClient +setting must be chosen to enable SASL EXTERNAL authentication. +.RE +.TP +.B olcTLSCRLCheck: <level> +Specifies if the Certificate Revocation List (CRL) of the CA should be +used to verify if the client certificates have not been revoked. This +requires +.B olcTLSCACertificatePath +parameter to be set. This parameter is ignored with GnuTLS. +.B <level> +can be specified as one of the following keywords: +.RS +.TP +.B none +No CRL checks are performed +.TP +.B peer +Check the CRL of the peer certificate +.TP +.B all +Check the CRL for a whole certificate chain +.RE +.TP +.B olcTLSCRLFile: <filename> +Specifies a file containing a Certificate Revocation List to be used +for verifying that certificates have not been revoked. This parameter is +only valid when using GnuTLS. +.SH DYNAMIC MODULE OPTIONS +If +.B slapd +is compiled with \-\-enable\-modules then the module-related entries will +be available. These entries are named +.B cn=module{x},cn=config +and +must have the olcModuleList objectClass. One entry should be created +per +.B olcModulePath. +Normally the config engine generates the "{x}" index in the RDN +automatically, so it can be omitted when initially loading these entries. +.TP +.B olcModuleLoad: <filename> [<arguments>...] +Specify the name of a dynamically loadable module to load and any +additional arguments if supported by the module. The filename +may be an absolute path name or a simple filename. Non-absolute names +are searched for in the directories specified by the +.B olcModulePath +option. +.TP +.B olcModulePath: <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. +.SH SCHEMA OPTIONS +Schema definitions are created as entries in the +.B cn=schema,cn=config +subtree. These entries must have the olcSchemaConfig objectClass. +As noted above, the actual +.B cn=schema,cn=config +entry is predefined and any values specified for it are ignored. + +.HP +.hy 0 +.B olcAttributetypes: "(\ <oid>\ + [NAME\ <name>]\ + [DESC\ <description>]\ + [OBSOLETE]\ + [SUP\ <oid>]\ + [EQUALITY\ <oid>]\ + [ORDERING\ <oid>]\ + [SUBSTR\ <oid>]\ + [SYNTAX\ <oidlen>]\ + [SINGLE\-VALUE]\ + [COLLECTIVE]\ + [NO\-USER\-MODIFICATION]\ + [USAGE\ <attributeUsage>]\ )" +.RS +Specify an attribute type 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 attribute OID and +attribute syntax OID. +(See the +.B olcObjectIdentifier +description.) +.RE + +.HP +.hy 0 +.B olcDitContentRules: "(\ <oid>\ + [NAME\ <name>]\ + [DESC\ <description>]\ + [OBSOLETE]\ + [AUX\ <oids>]\ + [MUST\ <oids>]\ + [MAY\ <oids>]\ + [NOT\ <oids>]\ )" +.RS +Specify an DIT Content Rule 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 attribute OID and +attribute syntax OID. +(See the +.B olcObjectIdentifier +description.) +.RE + +.HP +.hy 0 +.B olcLdapSyntaxes "(\ <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 one to use the +.B olcLdapSyntaxes +attribute 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 one 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 + +.HP +.hy 0 +.B olcObjectClasses: "(\ <oid>\ + [NAME\ <name>]\ + [DESC\ <description>]\ + [OBSOLETE]\ + [SUP\ <oids>]\ + [{ ABSTRACT | STRUCTURAL | AUXILIARY }]\ + [MUST\ <oids>] [MAY\ <oids>] )" +.RS +Specify an objectclass 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 object class OID. +(See the +.B +olcObjectIdentifier +description.) Object classes are "STRUCTURAL" by default. +.RE +.TP +.B olcObjectIdentifier: <name> "{ <oid> | <name>[:<suffix>] }" +Define a string name that equates to the given OID. The string can be used +in place of the numeric OID in objectclass and attribute definitions. The +name can also be used with a suffix of the form ":xx" in which case the +value "oid.xx" will be used. + +.SH GENERAL BACKEND OPTIONS +Options in these entries only apply to the configuration of a single +type of backend. All backends may support this class of options, but +currently only back-mdb does. +The entry must be named +.B olcBackend=<databasetype>,cn=config +and must have the olcBackendConfig objectClass. +<databasetype> +should be one of +.BR asyncmeta , +.BR config , +.BR dnssrv , +.BR ldap , +.BR ldif , +.BR mdb , +.BR meta , +.BR monitor , +.BR ndb , +.BR null , +.BR passwd , +.BR perl , +.BR relay , +.BR sock , +.BR sql , +or +.BR wt . +At present, only back-mdb implements any options of this type, so this +entry should not be used for any other backends. + +.SH DATABASE OPTIONS +Database options are set in entries named +.B olcDatabase={x}<databasetype>,cn=config +and must have the olcDatabaseConfig objectClass. Normally the config +engine generates the "{x}" index in the RDN automatically, so it +can be omitted when initially loading these entries. + +The special frontend database is always numbered "{\-1}" and the config +database is always numbered "{0}". + +.SH GLOBAL DATABASE OPTIONS +Options in this section may be set in the special "frontend" database +and inherited in all the other databases. These options may be altered +by further settings in each specific database. The frontend entry must +be named +.B olcDatabase=frontend,cn=config +and must have the olcFrontendConfig objectClass. +.TP +.B olcAccess: to <what> "[ by <who> <access> <control> ]+" +Grant access (specified by <access>) to a set of entries and/or +attributes (specified by <what>) by one or more requestors (specified +by <who>). +If no access controls are present, the default policy +allows anyone and everyone to read anything but restricts +updates to rootdn. (e.g., "olcAccess: to * by * read"). +See +.BR slapd.access (5) +and the "OpenLDAP Administrator's Guide" for details. + +Access controls set in the frontend are appended to any access +controls set on the specific databases. +The rootdn of a database can always read and write EVERYTHING +in that database. + +Extra special care must be taken with the access controls on the +config database. Unlike other databases, the default policy for the +config database is to only allow access to the rootdn. Regular users +should not have read access, and write access should be granted very +carefully to privileged administrators. + +.TP +.B olcDefaultSearchBase: <dn> +Specify a default search base to use when client submits a +non-base search request with an empty base DN. +Base scoped search requests with an empty base DN are not affected. +This setting is only allowed in the frontend entry. +.TP +.B olcExtraAttrs: <attr> +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 <attr> +is an attribute that is needed for internal purposes +and thus always needs to be collected, even when not explicitly +requested by clients. +This attribute is multi-valued. +.TP +.B olcPasswordHash: <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). +The <hash> must be one of +.BR {SSHA} , +.BR {SHA} , +.BR {SMD5} , +.BR {MD5} , +.BR {CRYPT} , +and +.BR {CLEARTEXT} . +The default is +.BR {SSHA} . + +.B {SHA} +and +.B {SSHA} +use the SHA-1 algorithm (FIPS 160-1), the latter with a seed. + +.B {MD5} +and +.B {SMD5} +use the MD5 algorithm (RFC 1321), the latter with a seed. + +.B {CRYPT} +uses the +.BR crypt (3). + +.B {CLEARTEXT} +indicates that the new password should be +added to userPassword as clear text. + +Note that this option does not alter the normal user applications +handling of userPassword during LDAP Add, Modify, or other LDAP operations. +This setting is only allowed in the frontend entry. +.TP +.B olcReadOnly: TRUE | FALSE +This option puts the database into "read-only" mode. Any attempts to +modify the database will return an "unwilling to perform" error. By +default, olcReadOnly is FALSE. Note that when this option is set +TRUE on the frontend, it cannot be reset without restarting the +server, since further writes to the config database will be rejected. +.TP +.B olcRequires: <conditions> +Specify a set of conditions to require (default none). +The directive may be specified globally and/or per-database; +databases inherit global conditions, so per-database specifications +are additive. +.B bind +requires bind operation prior to directory operations. +.B LDAPv3 +requires session to be using LDAP version 3. +.B authc +requires authentication prior to directory operations. +.B SASL +requires SASL authentication prior to directory operations. +.B strong +requires strong authentication prior to directory operations. +The strong keyword allows protected "simple" authentication +as well as SASL authentication. +.B none +may be used to require no conditions (useful to clear out globally +set conditions within a particular database); it must occur first +in the list of conditions. +.TP +.B olcRestrict: <oplist> +Specify a list of operations that are restricted. +Restrictions on a specific database override any frontend setting. +Operations can be any of +.BR add , +.BR bind , +.BR compare , +.BR delete , +.BR extended[=<OID>] , +.BR modify , +.BR rename , +.BR search , +or the special pseudo-operations +.B read +and +.BR write , +which respectively summarize read and write operations. +The use of +.I restrict write +is equivalent to +.I olcReadOnly: TRUE +(see above). +The +.B extended +keyword allows one to indicate the OID of the specific operation +to be restricted. +.TP +.B olcSchemaDN: <dn> +Specify the distinguished name for the subschema subentry that +controls the entries on this server. The default is "cn=Subschema". +.TP +.B olcSecurity: <factors> +Specify a set of security strength factors (separated by white space) +to require (see +.BR olcSaslSecprops 's +.B minssf +option for a description of security strength factors). +The directive may be specified globally and/or per-database. +.B ssf=<n> +specifies the overall security strength factor. +.B transport=<n> +specifies the transport security strength factor. +.B tls=<n> +specifies the TLS security strength factor. +.B sasl=<n> +specifies the SASL security strength factor. +.B update_ssf=<n> +specifies the overall security strength factor to require for +directory updates. +.B update_transport=<n> +specifies the transport security strength factor to require for +directory updates. +.B update_tls=<n> +specifies the TLS security strength factor to require for +directory updates. +.B update_sasl=<n> +specifies the SASL security strength factor to require for +directory updates. +.B simple_bind=<n> +specifies the security strength factor required for +.I simple +username/password authentication. +Note that the +.B transport +factor is measure of security provided by the underlying transport, +e.g. ldapi:// (and eventually IPSEC). It is not normally used. +.TP +.B olcSizeLimit: {<integer>|unlimited} +.TP +.B olcSizeLimit: size[.{soft|hard}]=<integer> [...] +Specify the maximum number of entries to return from a search operation. +The default size limit is 500. +Use +.B unlimited +to specify no limits. +The second format allows a fine grain setting of the size limits. +If no special qualifiers are specified, both soft and hard limits are set. +Extra args can be added in the same value. +Additional qualifiers are available; see +.BR olcLimits +for an explanation of all of the different flags. +.TP +.B olcSortVals: <attr> [...] +Specify a list of multi-valued attributes whose values will always +be maintained in sorted order. Using this option will allow Modify, +Compare, and filter evaluations on these attributes to be performed +more efficiently. The resulting sort order depends on the +attributes' syntax and matching rules and may not correspond to +lexical order or any other recognizable order. +This setting is only allowed in the frontend entry. +.TP +.B olcTimeLimit: {<integer>|unlimited} +.TP +.B olcTimeLimit: time[.{soft|hard}]=<integer> [...] +Specify the maximum number of seconds (in real time) +.B slapd +will spend answering a search request. The default time limit is 3600. +Use +.B unlimited +to specify no limits. +The second format allows a fine grain setting of the time limits. +Extra args can be added in the same value. See +.BR olcLimits +for an explanation of the different flags. + +.SH GENERAL DATABASE OPTIONS +Options in this section only apply to the specific database for +which they are defined. They are supported by every +type of backend. All of the Global Database Options may also be +used here. +.TP +.B olcAddContentAcl: TRUE | FALSE +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 olcHidden: TRUE | FALSE +Controls whether the database will be used to answer +queries. A database that is hidden will never be +selected to answer any queries, and any suffix configured +on the database will be ignored in checks for conflicts +with other databases. By default, olcHidden is FALSE. +.TP +.B olcLastMod: TRUE | FALSE +Controls whether +.B slapd +will automatically maintain the +modifiersName, modifyTimestamp, creatorsName, and +createTimestamp attributes for entries. It also controls +the entryCSN and entryUUID attributes, which are needed +by the syncrepl provider. By default, olcLastMod is TRUE. +.TP +.B olcLastBind: TRUE | FALSE +Controls whether +.B slapd +will automatically maintain the pwdLastSuccess attribute for +entries. By default, olcLastBind is FALSE. +.TP +.B olcLimits: <selector> <limit> [<limit> [...]] +Specify time and size limits based on the operation's initiator or +base DN. +The argument +.B <selector> +can be any of +.RS +.RS +.TP +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 term +.B users +matches all authenticated clients; +otherwise an +.B exact +dn pattern is assumed unless otherwise specified by qualifying +the (optional) key string +.B dn +with +.B exact +or +.B base +(which are synonyms), to require an exact match; with +.BR onelevel , +to require exactly one level of depth match; with +.BR subtree , +to allow any level of depth match, including the exact match; with +.BR children , +to allow any level of depth match, not including the exact match; +.BR regex +explicitly requires the (default) match based on POSIX (''extended'') +regular expression pattern. +Finally, +.B anonymous +matches unbound operations; the +.B pattern +field is ignored. +The same behavior is obtained by using the +.B anonymous +form of the +.B <selector> +clause. +The term +.BR group , +with the optional objectClass +.B oc +and attributeType +.B at +fields, followed by +.BR pattern , +sets the limits for any DN listed in the values of the +.B at +attribute (default +.BR member ) +of the +.B oc +group objectClass (default +.BR groupOfNames ) +whose DN exactly matches +.BR pattern . + +The currently supported limits are +.B size +and +.BR time . + +The syntax for time limits is +.BR time[.{soft|hard}]=<integer> , +where +.I integer +is the number of seconds slapd will spend answering a search request. +If no time limit is explicitly requested by the client, the +.BR soft +limit is used; if the requested time limit exceeds the +.BR hard +.\"limit, an +.\".I "Administrative limit exceeded" +.\"error is returned. +limit, the value of the limit is used instead. +If the +.BR hard +limit is set to the keyword +.IR soft , +the soft limit is used in either case; if it is set to the keyword +.IR unlimited , +no hard limit is enforced. +Explicit requests for time limits smaller or equal to the +.BR hard +limit are honored. +If no limit specifier is set, the value is assigned to the +.BR soft +limit, and the +.BR hard +limit is set to +.IR soft , +to preserve the original behavior. + +The syntax for size limits is +.BR size[.{soft|hard|unchecked}]=<integer> , +where +.I integer +is the maximum number of entries slapd will return answering a search +request. +If no size limit is explicitly requested by the client, the +.BR soft +limit is used; if the requested size limit exceeds the +.BR hard +.\"limit, an +.\".I "Administrative limit exceeded" +.\"error is returned. +limit, the value of the limit is used instead. +If the +.BR hard +limit is set to the keyword +.IR soft , +the soft limit is used in either case; if it is set to the keyword +.IR unlimited , +no hard limit is enforced. +Explicit requests for size limits smaller or equal to the +.BR hard +limit are honored. +The +.BR unchecked +specifier sets a limit on the number of candidates a search request is allowed +to examine. +The rationale behind it is that searches for non-properly indexed +attributes may result in large sets of candidates, which must be +examined by +.BR slapd (8) +to determine whether they match the search filter or not. +The +.B unchecked +limit provides a means to drop such operations before they are even +started. +If the selected candidates exceed the +.BR unchecked +limit, the search will abort with +.IR "Unwilling to perform" . +If it is set to the keyword +.IR unlimited , +no limit is applied (the default). +If it is set to +.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 +.BR soft +limit, and the +.BR hard +limit is set to +.IR soft , +to preserve the original behavior. + +In case of no match, the global limits are used. +The default values are the same as for +.B olcSizeLimit +and +.BR olcTimeLimit ; +no limit is set on +.BR unchecked . + +If +.B pagedResults +control is requested, the +.B hard +size limit is used by default, because the request of a specific page size +is considered an explicit request for a limitation on the number +of entries to be returned. +However, the size limit applies to the total count of entries returned within +the search, and not to a single page. +Additional size limits may be enforced; the syntax is +.BR size.pr={<integer>|noEstimate|unlimited} , +where +.I integer +is the max page size if no explicit limit is set; the keyword +.I noEstimate +inhibits the server from returning an estimate of the total number +of entries that might be returned +(note: the current implementation does not return any estimate). +The keyword +.I unlimited +indicates that no limit is applied to the pagedResults control page size. +The syntax +.B size.prtotal={<integer>|hard|unlimited|disabled} +allows one to set a limit on the total number of entries that the pagedResults +control will return. +By default it is set to the +.B hard +limit which will use the size.hard value. +When set, +.I integer +is the max number of entries that the whole search with pagedResults control +can return. +Use +.I unlimited +to allow unlimited number of entries to be returned, e.g. to allow +the use of the pagedResults control as a means to circumvent size +limitations on regular searches; the keyword +.I disabled +disables the control, i.e. no paged results can be returned. +Note that the total number of entries returned when the pagedResults control +is requested cannot exceed the +.B hard +size limit of regular searches unless extended by the +.B prtotal +switch. + +The \fBolcLimits\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 \fBolcSyncrepl\fP for details). + +When using subordinate databases, it is necessary for any limits that +are to be applied across the parent and its subordinates to be defined in +both the parent and its subordinates. Otherwise the settings on the +subordinate databases are not honored. +.RE +.TP +.B olcMaxDerefDepth: <depth> +Specifies the maximum number of aliases to dereference when trying to +resolve an entry, used to avoid infinite alias loops. The default is 15. +.TP +.B olcMultiProvider: TRUE | FALSE +This option puts a consumer database into Multi-Provider mode. Update +operations will be accepted from any user, not just the updatedn. The +database must already be configured as a syncrepl consumer +before this keyword may be set. This mode also requires a +.B olcServerID +(see above) to be configured. +By default, this setting is FALSE. +.TP +.B olcMonitoring: TRUE | FALSE +This option enables database-specific monitoring in the entry related +to the current database in the "cn=Databases,cn=Monitor" subtree +of the monitor database, if the monitor database is enabled. +Currently, only the MDB database provides database-specific monitoring. +If monitoring is supported by the backend it defaults to TRUE, otherwise +FALSE. +.TP +.B olcPlugin: <plugin_type> <lib_path> <init_function> [<arguments>] +Configure a SLAPI plugin. See the +.BR slapd.plugin (5) +manpage for more details. +.TP +.B olcRootDN: <dn> +Specify the distinguished name that is not subject to access control +or administrative limit restrictions for operations on this database. +This DN may or may not be associated with an entry. An empty root +DN (the default) specifies no root access is to be granted. It is +recommended that the rootdn only be specified when needed (such as +when initially populating a database). If the rootdn is within +a namingContext (suffix) of the database, a simple bind password +may also be provided using the +.B olcRootPW +directive. Many optional features, including syncrepl, require the +rootdn to be defined for the database. +The +.B olcRootDN +of the +.B cn=config +database defaults to +.B cn=config +itself. +.TP +.B olcRootPW: <password> +Specify a password (or hash of the password) for the rootdn. The +password can only be set if the rootdn is within the namingContext +(suffix) of the database. +This option accepts all RFC 2307 userPassword formats known to +the server (see +.B olcPasswordHash +description) as well as cleartext. +.BR slappasswd (8) +may be used to generate a hash of a password. Cleartext +and \fB{CRYPT}\fP passwords are not recommended. If empty +(the default), authentication of the root DN is by other means +(e.g. SASL). Use of SASL is encouraged. +.TP +.B olcSubordinate: [TRUE | FALSE | advertise] +Specify that the current backend database is a subordinate of another +backend database. A subordinate database may have only one suffix. This +option may be used to glue multiple databases into a single namingContext. +If the suffix of the current database is within the namingContext of a +superior database, searches against the superior database will be +propagated to the subordinate as well. All of the databases +associated with a single namingContext should have identical rootdns. +Behavior of other LDAP operations is unaffected by this setting. In +particular, it is not possible to use moddn to move an entry from +one subordinate to another subordinate within the namingContext. + +If the optional \fBadvertise\fP flag is supplied, the naming context of +this database is advertised in the root DSE. The default is to hide this +database context, so that only the superior context is visible. + +If the slap tools +.BR slapcat (8), +.BR slapadd (8), +.BR slapmodify (8), +or +.BR slapindex (8) +are used on the superior database, any glued subordinates that support +these tools are opened as well. + +Databases that are glued together should usually be configured with the +same indices (assuming they support indexing), even for attributes that +only exist in some of these databases. In general, all of the glued +databases should be configured as similarly as possible, since the intent +is to provide the appearance of a single directory. + +Note that the subordinate functionality is implemented internally +by the \fIglue\fP overlay and as such its behavior will interact with other +overlays in use. By default, the glue overlay is automatically configured as +the last overlay on the superior database. Its position on the database +can be explicitly configured by setting an \fBoverlay glue\fP directive +at the desired position. This explicit configuration is necessary e.g. +when using the \fIsyncprov\fP overlay, which needs to follow \fIglue\fP +in order to work over all of the glued databases. E.g. +.RS +.nf + dn: olcDatabase={1}mdb,cn=config + olcSuffix: dc=example,dc=com + ... + + dn: olcOverlay={0}glue,olcDatabase={1}mdb,cn=config + ... + + dn: olcOverlay={1}syncprov,olcDatabase={1}mdb,cn=config + ... +.fi +.RE +See the Overlays section below for more details. +.TP +.B olcSuffix: <dn suffix> +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 olcSubordinate +attribute. +.TP +.B olcSyncUseSubentry: TRUE | FALSE +Store the syncrepl contextCSN in a subentry instead of the context entry +of the database. The subentry's RDN will be "cn=ldapsync". The default is +FALSE, meaning the contextCSN is stored in the context entry. +.HP +.hy 0 +.B olcSyncrepl: rid=<replica ID> +.B provider=ldap[s]://<hostname>[:port] +.B searchbase=<base DN> +.B [type=refreshOnly|refreshAndPersist] +.B [interval=dd:hh:mm:ss] +.B [retry=[<retry interval> <# of retries>]+] +.B [filter=<filter str>] +.B [scope=sub|one|base|subord] +.B [attrs=<attr list>] +.B [exattrs=<attr list>] +.B [attrsonly] +.B [sizelimit=<limit>] +.B [timelimit=<limit>] +.B [schemachecking=on|off] +.B [network\-timeout=<seconds>] +.B [timeout=<seconds>] +.B [tcp\-user\-timeout=<milliseconds>] +.B [bindmethod=simple|sasl] +.B [binddn=<dn>] +.B [saslmech=<mech>] +.B [authcid=<identity>] +.B [authzid=<identity>] +.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_cacert=<file>] +.B [tls_cacertdir=<path>] +.B [tls_reqcert=never|allow|try|demand] +.B [tls_reqsan=never|allow|try|demand] +.B [tls_cipher_suite=<ciphers>] +.B [tls_ecname=<names>] +.B [tls_crlcheck=none|peer|all] +.B [tls_protocol_min=<major>[.<minor>]] +.B [suffixmassage=<real DN>] +.B [logbase=<base DN>] +.B [logfilter=<filter str>] +.B [syncdata=default|accesslog|changelog] +.B [lazycommit] +.RS +Specify the current database as a consumer which is kept up-to-date with the +provider content by establishing the current +.BR slapd (8) +as a replication consumer site running a +.B syncrepl +replication engine. +The consumer content is kept synchronized to the provider content using +the LDAP Content Synchronization protocol. Refer to the +"OpenLDAP Administrator's Guide" for detailed information on +setting up a replicated +.B slapd +directory service using the +.B syncrepl +replication engine. + +.B rid +identifies the current +.B syncrepl +directive within the replication consumer site. +It is a non-negative integer not greater than 999 (limited +to three decimal digits). + +.B provider +specifies the replication provider site containing the provider content +as an LDAP URI. If <port> is not given, the standard LDAP port number +(389 or 636) is used. + +The content of the +.B syncrepl +consumer is defined using a search +specification as its result set. The consumer +.B slapd +will send search requests to the provider +.B slapd +according to the search specification. The search specification includes +.BR searchbase ", " scope ", " filter ", " attrs ", " attrsonly ", " sizelimit ", " +and +.B timelimit +parameters as in the normal search specification. The +.B exattrs +option may also be used to specify attributes that should be omitted +from incoming entries. +The \fBscope\fP defaults to \fBsub\fP, the \fBfilter\fP defaults to +\fB(objectclass=*)\fP, and there is no default \fBsearchbase\fP. The +\fBattrs\fP list defaults to \fB"*,+"\fP to return all user and operational +attributes, and \fBattrsonly\fP and \fBexattrs\fP are 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; these should be left unchanged +from the default otherwise replication may never succeed. +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 +search operation. + +The LDAP Content Synchronization protocol has two operation types. +In the +.B refreshOnly +operation, the next synchronization search operation +is periodically rescheduled at an interval time (specified by +.B interval +parameter; 1 day by default) +after each synchronization operation finishes. +In the +.B refreshAndPersist +operation, a synchronization search remains persistent in the provider slapd. +Further updates to the provider will generate +.B searchResultEntry +to the consumer slapd as the search responses to the persistent +synchronization search. If the initial search fails due to an error, the +next synchronization search operation is periodically rescheduled at an +interval time (specified by +.B interval +parameter; 1 day by default) + +If an error occurs during replication, the consumer will attempt to +reconnect according to the +.B retry +parameter which is a list of the <retry interval> and <# of retries> pairs. +For example, retry="60 10 300 3" lets the consumer retry every 60 seconds +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 +is 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 \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). +The +.B tcp\-user\-timeout +parameter, if non-zero, corresponds to the +.B 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. + +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. +.B REMEMBER: simple bind credentials must be in cleartext! +A +.B bindmethod +of +.B sasl +requires the option +.B saslmech. +Depending on the mechanism, an authentication identity and/or +credentials can be specified using +.B authcid +and +.B credentials. +The +.B authzid +parameter may be used to specify an authorization identity. +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. +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 allowing 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. +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 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 +to establish a TLS session before Binding to the provider. If the +.B critical +argument is supplied, the session will be aborted if the StartTLS request +fails. Otherwise the syncrepl session continues without TLS. The +.B tls_reqcert +setting defaults to "demand", the +.B tls_reqsan +setting defaults to "allow", 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 +.B logbase +and +.B logfilter +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) +log format, or "changelog" if the log conforms +to the obsolete \fIchangelog\fP format. If the +.B syncdata +parameter is omitted or set to "default" then the log parameters are +ignored. + +The +.B lazycommit +parameter tells the underlying database that it can store changes without +performing a full flush after each change. This may improve performance +for the consumer, while sacrificing safety or durability. +.RE +.TP +.B olcUpdateDN: <dn> +This option is only applicable in a replica +database. +It specifies the DN permitted to update (subject to access controls) +the replica. It is only needed in certain push-mode +replication scenarios. Generally, this DN +.I should not +be the same as the +.B rootdn +used at the provider. +.TP +.B olcUpdateRef: <url> +Specify the referral to pass back when +.BR slapd (8) +is asked to modify a replicated local database. +If multiple values are specified, each url is provided. + +.SH DATABASE-SPECIFIC OPTIONS +Each database may allow specific configuration options; they are +documented separately in the backends' manual pages. See the +.BR slapd.backends (5) +manual page for an overview of available backends. +.SH OVERLAYS +An overlay is a piece of +code that intercepts database operations in order to extend or change +them. Overlays are pushed onto +a stack over the database, and so they will execute in the reverse +of the order in which they were configured and the database itself +will receive control last of all. + +Overlays must be configured as child entries of a specific database. The +entry's RDN must be of the form +.B olcOverlay={x}<overlaytype> +and the entry must have the olcOverlayConfig objectClass. Normally the +config engine generates the "{x}" index in the RDN automatically, so +it can be omitted when initially loading these entries. + +See the +.BR slapd.overlays (5) +manual page for an overview of available overlays. +.SH EXAMPLES +.LP +Here is a short example of a configuration in LDIF suitable for use with +.BR slapadd (8) +: +.LP +.RS +.nf +dn: cn=config +objectClass: olcGlobal +cn: config +olcPidFile: LOCALSTATEDIR/run/slapd.pid +olcAttributeOptions: x\-hidden lang\- + +dn: cn=schema,cn=config +objectClass: olcSchemaConfig +cn: schema + +include: file://SYSCONFDIR/schema/core.ldif + +dn: olcDatabase=frontend,cn=config +objectClass: olcDatabaseConfig +objectClass: olcFrontendConfig +olcDatabase: frontend +# Subtypes of "name" (e.g. "cn" and "ou") with the +# option ";x\-hidden" can be searched for/compared, +# but are not shown. See \fBslapd.access\fP(5). +olcAccess: to attrs=name;x\-hidden by * =cs +# Protect passwords. See \fBslapd.access\fP(5). +olcAccess: to attrs=userPassword by * auth +# Read access to other attributes and entries. +olcAccess: to * by * read + +# set a rootpw for the config database so we can bind. +# deny access to everyone else. +dn: olcDatabase=config,cn=config +objectClass: olcDatabaseConfig +olcDatabase: config +olcRootPW: {SSHA}XKYnrjvGT3wZFQrDD5040US592LxsdLy +olcAccess: to * by * none + +dn: olcDatabase=mdb,cn=config +objectClass: olcDatabaseConfig +objectClass: olcMdbConfig +olcDatabase: mdb +olcSuffix: "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. +olcDbDirectory: LOCALSTATEDIR/openldap\-data +# Indices to maintain +olcDbIndex: objectClass eq +olcDbIndex: cn,sn,mail pres,eq,approx,sub + +# We serve small clients that do not handle referrals, +# so handle remote lookups on their behalf. +dn: olcDatabase=ldap,cn=config +objectClass: olcDatabaseConfig +objectClass: olcLdapConfig +olcDatabase: ldap +olcSuffix: "" +olcDbUri: ldap://ldap.some\-server.com/ +.fi +.RE +.LP +Assuming the above data was saved in a file named "config.ldif" and the +ETCDIR/slapd.d directory has been created, this command will initialize +the configuration: +.RS +.nf +slapadd \-F ETCDIR/slapd.d \-n 0 \-l config.ldif +.fi +.RE + +.LP +"OpenLDAP Administrator's Guide" contains a longer annotated +example of a slapd configuration. + +Alternatively, an existing slapd.conf file can be converted to the new +format using slapd or any of the slap tools: +.RS +.nf +slaptest \-f ETCDIR/slapd.conf \-F ETCDIR/slapd.d +.fi +.RE + +.SH FILES +.TP +ETCDIR/slapd.conf +default slapd configuration file +.TP +ETCDIR/slapd.d +default slapd configuration directory +.SH SEE ALSO +.BR ldap (3), +.BR ldif (5), +.BR gnutls\-cli (1), +.BR slapd.access (5), +.BR slapd.backends (5), +.BR slapd.conf (5), +.BR slapd.overlays (5), +.BR slapd.plugin (5), +.BR slapd (8), +.BR slapacl (8), +.BR slapadd (8), +.BR slapauth (8), +.BR slapcat (8), +.BR slapdn (8), +.BR slapindex (8), +.BR slapmodify (8), +.BR slappasswd (8), +.BR slaptest (8). +.LP +"OpenLDAP Administrator's Guide" (http://www.OpenLDAP.org/doc/admin/) +.SH ACKNOWLEDGEMENTS +.so ../Project |