summaryrefslogtreecommitdiffstats
path: root/doc/guide/admin/slapdconf2.sdf
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--doc/guide/admin/slapdconf2.sdf1264
1 files changed, 1264 insertions, 0 deletions
diff --git a/doc/guide/admin/slapdconf2.sdf b/doc/guide/admin/slapdconf2.sdf
new file mode 100644
index 0000000..e2bc162
--- /dev/null
+++ b/doc/guide/admin/slapdconf2.sdf
@@ -0,0 +1,1264 @@
+# $OpenLDAP$
+# Copyright 2005-2022 The OpenLDAP Foundation, All Rights Reserved.
+# COPYING RESTRICTIONS APPLY, see COPYRIGHT.
+
+H1: Configuring slapd
+
+Once the software has been built and installed, you are ready
+to configure {{slapd}}(8) for use at your site.
+
+OpenLDAP 2.3 and later have transitioned to using a dynamic runtime
+configuration engine, {{slapd-config}}(5). {{slapd-config}}(5)
+* is fully LDAP-enabled
+* is managed using the standard LDAP operations
+* stores its configuration data in an {{TERM:LDIF}} database, generally
+in the {{F:/usr/local/etc/openldap/slapd.d}} directory.
+* allows all of slapd's configuration options to be changed on the fly,
+generally without requiring a server restart for the changes
+to take effect.
+
+This chapter describes the general format of the {{slapd-config}}(5)
+configuration system, followed by a detailed description of commonly used
+settings.
+
+The older style {{slapd.conf}}(5) file is still supported, but its use
+is deprecated and support for it will be withdrawn in a future OpenLDAP
+release. Configuring {{slapd}}(8) via {{slapd.conf}}(5) is described in
+the next chapter.
+
+Refer to {{slapd}}(8) for information on how to have slapd automatically
+convert from {{slapd.conf}}(5) to {{slapd-config}}(5).
+
+
+Note: Although the {{slapd-config}}(5) system stores its configuration
+as (text-based) LDIF files, you should {{1:never}} edit any of
+the LDIF files directly. Configuration changes should be performed via LDAP
+operations, e.g. {{ldapadd}}(1), {{ldapdelete}}(1), or {{ldapmodify}}(1).
+For offline modifications (when the server is not running), use {{slapadd}}(8)
+and {{slapmodify}}(8).
+
+
+Note: You will need to continue to use the older {{slapd.conf}}(5)
+configuration system if your OpenLDAP installation requires the use of one
+or more backends or overlays that have not been updated to use the
+{{slapd-config}}(5) system. As of OpenLDAP 2.4.33, all of the official
+backends have been updated. There may be additional contributed or experimental
+overlays that also have not been updated.
+
+
+H2: Configuration Layout
+
+The slapd configuration is stored as a special LDAP directory with
+a predefined schema and DIT. There are specific objectClasses used to
+carry global configuration options, schema definitions, backend and
+database definitions, and assorted other items. A sample config tree
+is shown in Figure 5.1.
+
+!import "config_dit.png"; align="center"; title="Sample configuration tree"
+FT[align="Center"] Figure 5.1: Sample configuration tree.
+
+Other objects may be part of the configuration but were omitted from
+the illustration for clarity.
+
+The {{slapd-config}} configuration tree has a very specific structure. The
+root of the tree is named {{EX:cn=config}} and contains global configuration
+settings. Additional settings are contained in separate child entries:
+* Dynamically loaded modules
+.. These may only be used if the {{EX:--enable-modules}} option was
+used to configure the software.
+* Schema definitions
+.. The {{EX:cn=schema,cn=config}} entry contains the system schema (all
+the schema that is hard-coded in slapd).
+.. Child entries of {{EX:cn=schema,cn=config}} contain user schema as
+loaded from config files or added at runtime.
+* Backend-specific configuration
+* Database-specific configuration
+.. Overlays are defined in children of the Database entry.
+.. Databases and Overlays may also have other miscellaneous children.
+
+The usual rules for LDIF files apply to the configuration information:
+Comment lines beginning with a '{{EX:#}}' character
+are ignored. If a line begins with a single space, it is considered a
+continuation of the previous line (even if the previous line is a
+comment) and the single leading space is removed. Entries are separated by blank lines.
+
+The general layout of the config LDIF is as follows:
+
+> # global configuration settings
+> dn: cn=config
+> objectClass: olcGlobal
+> cn: config
+> <global config settings>
+>
+> # schema definitions
+> dn: cn=schema,cn=config
+> objectClass: olcSchemaConfig
+> cn: schema
+> <system schema>
+>
+> dn: cn={X}core,cn=schema,cn=config
+> objectClass: olcSchemaConfig
+> cn: {X}core
+> <core schema>
+>
+> # additional user-specified schema
+> ...
+>
+> # backend definitions
+> dn: olcBackend=<typeA>,cn=config
+> objectClass: olcBackendConfig
+> olcBackend: <typeA>
+> <backend-specific settings>
+>
+> # database definitions
+> dn: olcDatabase={X}<typeA>,cn=config
+> objectClass: olcDatabaseConfig
+> olcDatabase: {X}<typeA>
+> <database-specific settings>
+>
+> # subsequent definitions and settings
+> ...
+
+Some of the entries listed above have a numeric index {{EX:"{X}"}} in
+their names. While most configuration settings have an inherent ordering
+dependency (i.e., one setting must take effect before a subsequent one
+may be set), LDAP databases are inherently unordered. The numeric index
+is used to enforce a consistent ordering in the configuration database,
+so that all ordering dependencies are preserved. In most cases the index
+does not have to be provided; it will be automatically generated based
+on the order in which entries are created.
+
+Configuration directives are specified as values of individual
+attributes.
+Most of the attributes and objectClasses used in the slapd
+configuration have a prefix of {{EX:"olc"}} (OpenLDAP Configuration)
+in their names. Generally there is a one-to-one correspondence
+between the attributes and the old-style {{EX:slapd.conf}} configuration
+keywords, using the keyword as the attribute name, with the "olc"
+prefix attached.
+
+A configuration directive may take arguments. If so, the arguments are
+separated by whitespace. If an argument contains whitespace,
+the argument should be enclosed in double quotes {{EX:"like this"}}.
+In the descriptions that follow, arguments that should be replaced
+by actual text are shown in brackets {{EX:<>}}.
+
+The distribution contains an example configuration file that will
+be installed in the {{F: /usr/local/etc/openldap}} directory.
+A number of files containing schema definitions (attribute types
+and object classes) are also provided in the
+{{F: /usr/local/etc/openldap/schema}} directory.
+
+
+H2: Configuration Directives
+
+This section details commonly used configuration directives. For
+a complete list, see the {{slapd-config}}(5) manual page. This section
+will treat the configuration directives in a top-down order, starting
+with the global directives in the {{EX:cn=config}} entry. Each
+directive will be described along with its default value (if any) and
+an example of its use.
+
+
+H3: cn=config
+
+Directives contained in this entry generally apply to the server as a whole.
+Most of them are system or connection oriented, not database related. This
+entry must have the {{EX:olcGlobal}} objectClass.
+
+
+H4: olcIdleTimeout: <integer>
+
+Specify the number of seconds to wait before forcibly closing
+an idle client connection. A value of 0, the default,
+disables this feature.
+
+
+H4: olcLogLevel: <level>
+
+This directive specifies the level at which log statements
+and operation statistics should be sent to syslog (currently logged to
+the {{syslogd}}(8) {{EX:LOG_LOCAL4}} facility). You must have
+configured OpenLDAP {{EX:--enable-debug}} (the default) for this
+to work, except for the two statistics levels, which are always
+enabled. Log levels may be specified as integers or by keyword.
+Multiple log levels may be used and the levels are additive.
+The possible values for <level> are:
+
+!block table; colaligns="RL"; align=Center; \
+ title="Table 5.1: Logging Levels"
+Level Keyword Description
+-1 any enable all debugging
+0 no debugging
+1 (0x1 trace) trace function calls
+2 (0x2 packets) debug packet handling
+4 (0x4 args) heavy trace debugging
+8 (0x8 conns) connection management
+16 (0x10 BER) print out packets sent and received
+32 (0x20 filter) search filter processing
+64 (0x40 config) configuration processing
+128 (0x80 ACL) access control list processing
+256 (0x100 stats) stats log connections/operations/results
+512 (0x200 stats2) stats log entries sent
+1024 (0x400 shell) print communication with shell backends
+2048 (0x800 parse) print entry parsing debugging
+16384 (0x4000 sync) syncrepl consumer processing
+32768 (0x8000 none) only messages that get logged regardless of configured log level
+!endblock
+
+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 brackets, such that
+
+> olcLogLevel 129
+> olcLogLevel 0x81
+> olcLogLevel 128 1
+> olcLogLevel 0x80 0x1
+> olcLogLevel acl trace
+
+are equivalent.
+
+\Examples:
+
+E: olcLogLevel -1
+
+This will enable all log levels.
+
+E: olcLogLevel conns filter
+
+Just log the connection and search filter processing.
+
+E: olcLogLevel none
+
+Log those messages that are logged regardless of the configured loglevel. This
+differs from setting the log level to 0, when no logging occurs. At least the
+{{EX:None}} level is required to have high priority messages logged.
+
+\Default:
+
+E: olcLogLevel stats
+
+Basic stats logging is configured by default.
+
+H4: olcReferral <URI>
+
+This directive specifies the referral to pass back when slapd
+cannot find a local database to handle a request.
+
+\Example:
+
+> olcReferral: ldap://root.openldap.org
+
+This will refer non-local queries to the global root LDAP server
+at the OpenLDAP Project. Smart LDAP clients can re-ask their
+query at that server, but note that most of these clients are
+only going to know how to handle simple LDAP URLs that
+contain a host part and optionally a distinguished name part.
+
+
+H4: Sample Entry
+
+>dn: cn=config
+>objectClass: olcGlobal
+>cn: config
+>olcIdleTimeout: 30
+>olcLogLevel: Stats
+>olcReferral: ldap://root.openldap.org
+
+
+H3: cn=module
+
+If support for dynamically loaded modules was enabled when configuring
+slapd, {{EX:cn=module}} entries may be used to specify sets of modules to load.
+Module entries must have the {{EX:olcModuleList}} objectClass.
+
+
+H4: olcModuleLoad: <filename>
+
+Specify the name of a dynamically loadable module to load. The filename
+may be an absolute path name or a simple filename. Non-absolute names
+are searched for in the directories specified by the {{EX:olcModulePath}}
+directive.
+
+
+H4: 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.
+
+
+H4: Sample Entries
+
+>dn: cn=module{0},cn=config
+>objectClass: olcModuleList
+>cn: module{0}
+>olcModuleLoad: /usr/local/lib/smbk5pwd.la
+>
+>dn: cn=module{1},cn=config
+>objectClass: olcModuleList
+>cn: module{1}
+>olcModulePath: /usr/local/lib:/usr/local/lib/slapd
+>olcModuleLoad: accesslog.la
+>olcModuleLoad: pcache.la
+
+
+H3: cn=schema
+
+The cn=schema entry holds all of the schema definitions that are hard-coded
+in slapd. As such, the values in this entry are generated by slapd so no
+schema values need to be provided in the config file. The entry must still
+be defined though, to serve as a base for the user-defined schema to add
+in underneath. Schema entries must have the {{EX:olcSchemaConfig}}
+objectClass.
+
+
+H4: olcAttributeTypes: <{{REF:RFC4512}} Attribute Type Description>
+
+This directive defines an attribute type.
+Please see the {{SECT:Schema Specification}} chapter
+for information regarding how to use this directive.
+
+
+H4: olcObjectClasses: <{{REF:RFC4512}} Object Class Description>
+
+This directive defines an object class.
+Please see the {{SECT:Schema Specification}} chapter for
+information regarding how to use this directive.
+
+
+H4: Sample Entries
+
+>dn: cn=schema,cn=config
+>objectClass: olcSchemaConfig
+>cn: schema
+>
+>dn: cn=test,cn=schema,cn=config
+>objectClass: olcSchemaConfig
+>cn: test
+>olcAttributeTypes: ( 1.1.1
+> NAME 'testAttr'
+> EQUALITY integerMatch
+> SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 )
+>olcAttributeTypes: ( 1.1.2 NAME 'testTwo' EQUALITY caseIgnoreMatch
+> SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.44 )
+>olcObjectClasses: ( 1.1.3 NAME 'testObject'
+> MAY ( testAttr $ testTwo ) AUXILIARY )
+
+
+H3: Backend-specific Directives
+
+Backend directives apply to all database instances of the
+same type and, depending on the directive, may be overridden
+by database directives. Backend entries must have the
+{{EX:olcBackendConfig}} objectClass.
+
+H4: olcBackend: <type>
+
+This directive names a backend-specific configuration entry.
+{{EX:<type>}} should be one of the
+supported backend types listed in Table 5.2.
+
+!block table; align=Center; coltags="EX,N"; \
+ title="Table 5.2: Database Backends"
+Types Description
+asyncmeta Asynchronous Metadirectory backend
+config Slapd configuration backend
+dnssrv DNS SRV backend
+ldap Lightweight Directory Access Protocol (Proxy) backend
+ldif Lightweight Data Interchange Format backend
+mdb Memory-Mapped DB backend
+meta Metadirectory backend
+monitor Monitor backend
+ndb MySQL NDB backend
+null Null backend
+passwd Provides read-only access to {{passwd}}(5)
+perl Perl Programmable backend
+relay Relay backend
+sock Socket backend
+sql SQL Programmable backend
+wt WiredTiger backend
+!endblock
+
+\Example:
+
+> olcBackend: mdb
+
+This marks the beginning of a new {{TERM:MDB}} backend
+definition. At present, only back-mdb implements any options
+of this type, so this setting is not needed for any other backends.
+
+
+H4: Sample Entry
+
+> dn: olcBackend=mdb,cn=config
+> objectClass: olcBackendConfig
+> olcBackend: mdb
+> olcBkMdbIdlExp: 16
+
+
+H3: Database-specific Directives
+
+Directives in this section are supported by every type of database.
+Database entries must have the {{EX:olcDatabaseConfig}} objectClass.
+
+H4: olcDatabase: [{<index>}]<type>
+
+This directive names a specific database instance. The numeric {<index>} may
+be provided to distinguish multiple databases of the same type. Usually the
+index can be omitted, and slapd will generate it automatically.
+{{EX:<type>}} should be one of the
+supported backend types listed in Table 5.2 or the {{EX:frontend}} type.
+
+The {{EX:frontend}} is a special database that is used to hold
+database-level options that should be applied to all the other
+databases. Subsequent database definitions may also override some
+frontend settings.
+
+The {{EX:config}} database is also special; both the {{EX:config}} and
+the {{EX:frontend}} databases are always created implicitly even if they
+are not explicitly configured, and they are created before any other
+databases.
+
+\Example:
+
+> olcDatabase: mdb
+
+This marks the beginning of a new {{TERM:MDB}} database instance.
+
+
+H4: olcAccess: to <what> [ by <who> [<accesslevel>] [<control>] ]+
+
+This directive grants access (specified by <accesslevel>) to a
+set of entries and/or attributes (specified by <what>) by one or
+more requestors (specified by <who>).
+See the {{SECT:Access Control}} section of this guide for basic usage.
+
+!if 0
+More detailed discussion of this directive can be found in the
+{{SECT:Advanced Access Control}} chapter.
+!endif
+
+Note: If no {{EX:olcAccess}} directives are specified, the default
+access control policy, {{EX:to * by * read}}, allows all
+users (both authenticated and anonymous) read access.
+
+Note: Access controls defined in the frontend are appended to all
+other databases' controls.
+
+
+H4: olcReadonly { TRUE | FALSE }
+
+This directive puts the database into "read-only" mode. Any
+attempts to modify the database will return an "unwilling to
+perform" error. If set on a consumer, modifications sent by
+syncrepl will still occur.
+
+\Default:
+
+> olcReadonly: FALSE
+
+
+H4: olcRootDN: <DN>
+
+This directive specifies the DN that is not subject to
+access control or administrative limit restrictions for
+operations on this database. The DN need not refer to
+an entry in this database or even in the directory. The
+DN may refer to a SASL identity.
+
+Entry-based Example:
+
+> olcRootDN: cn=Manager,dc=example,dc=com
+
+SASL-based Example:
+
+> olcRootDN: uid=root,cn=example.com,cn=digest-md5,cn=auth
+
+See the {{SECT:SASL Authentication}} section for information on
+SASL authentication identities.
+
+
+H4: olcRootPW: <password>
+
+This directive can be used to specify a password for the DN for
+the rootdn (when the rootdn is set to a DN within the database).
+
+\Example:
+
+> olcRootPW: secret
+
+It is also permissible to provide a hash of the password in
+{{REF:RFC2307}} form. {{slappasswd}}(8) may be used to generate
+the password hash.
+
+\Example:
+
+> olcRootPW: {SSHA}ZKKuqbEKJfKSXhUbHG3fG8MDn9j1v4QN
+
+The hash was generated using the command {{EX:slappasswd -s secret}}.
+
+
+H4: olcSizeLimit: <integer>
+
+This directive specifies the maximum number of entries to return
+from a search operation.
+
+\Default:
+
+> olcSizeLimit: 500
+
+See the {{SECT:Limits}} section of this guide and slapd-config(5)
+for more details.
+
+
+H4: olcSuffix: <dn suffix>
+
+This directive specifies the DN suffix of queries that will be
+passed to this backend database. Multiple suffix lines can be
+given, and usually at least one is required for each database
+definition. (Some backend types, such as {{EX:frontend}} and
+{{EX:monitor}} use a hard-coded suffix which may not be overridden
+in the configuration.)
+
+\Example:
+
+> olcSuffix: dc=example,dc=com
+
+Queries with a DN ending in "dc=example,dc=com"
+will be passed to this backend.
+
+Note: When the backend to pass a query to is selected, slapd
+looks at the suffix value(s) in each database definition in the
+order in which they were configured. Thus, if one database suffix is a
+prefix of another, it must appear after it in the configuration.
+
+
+H4: olcSyncrepl
+
+> olcSyncrepl: rid=<replica ID>
+> provider=ldap[s]://<hostname>[:port]
+> [type=refreshOnly|refreshAndPersist]
+> [interval=dd:hh:mm:ss]
+> [retry=[<retry interval> <# of retries>]+]
+> searchbase=<base DN>
+> [filter=<filter str>]
+> [scope=sub|one|base]
+> [attrs=<attr list>]
+> [exattrs=<attr list>]
+> [attrsonly]
+> [sizelimit=<limit>]
+> [timelimit=<limit>]
+> [schemachecking=on|off]
+> [bindmethod=simple|sasl]
+> [binddn=<DN>]
+> [saslmech=<mech>]
+> [authcid=<identity>]
+> [authzid=<identity>]
+> [credentials=<passwd>]
+> [realm=<realm>]
+> [secprops=<properties>]
+> [starttls=yes|critical]
+> [tls_cert=<file>]
+> [tls_key=<file>]
+> [tls_cacert=<file>]
+> [tls_cacertdir=<path>]
+> [tls_reqcert=never|allow|try|demand]
+> [tls_cipher_suite=<ciphers>]
+> [tls_crlcheck=none|peer|all]
+> [logbase=<base DN>]
+> [logfilter=<filter str>]
+> [syncdata=default|accesslog|changelog]
+
+
+This directive specifies the current database as a consumer of the
+provider content by establishing the current {{slapd}}(8) as a
+replication consumer site running a syncrepl replication engine.
+The provider database is located at the provider site
+specified by the {{EX:provider}} parameter. The consumer database is
+kept up-to-date with the provider content using the LDAP Content
+Synchronization protocol. See {{REF:RFC4533}}
+for more information on the protocol.
+
+The {{EX:rid}} parameter is used for identification of the current
+{{EX:syncrepl}} directive within the replication consumer server,
+where {{EX:<replica ID>}} uniquely identifies the syncrepl specification
+described by the current {{EX:syncrepl}} directive. {{EX:<replica ID>}}
+is non-negative and is no more than three decimal digits in length.
+
+The {{EX:provider}} parameter specifies the replication provider site
+containing the provider content as an LDAP URI. The {{EX:provider}}
+parameter specifies a scheme, a host and optionally a port where the
+provider slapd instance can be found. Either a domain name or IP
+address may be used for <hostname>. Examples are
+{{EX:ldap://provider.example.com:389}} or {{EX:ldaps://192.168.1.1:636}}.
+If <port> is not given, the standard LDAP port number (389 or 636) is used.
+Note that the syncrepl uses a consumer-initiated protocol, and hence its
+specification is located on the consumer.
+
+The content of the syncrepl consumer is defined using a search
+specification as its result set. The consumer slapd will
+send search requests to the provider slapd according to the search
+specification. The search specification includes {{EX:searchbase}},
+{{EX:scope}}, {{EX:filter}}, {{EX:attrs}}, {{EX:exattrs}}, {{EX:attrsonly}},
+{{EX:sizelimit}}, and {{EX:timelimit}} parameters as in the normal
+search specification. The {{EX:searchbase}} parameter has no
+default value and must always be specified. The {{EX:scope}} defaults
+to {{EX:sub}}, the {{EX:filter}} defaults to {{EX:(objectclass=*)}},
+{{EX:attrs}} defaults to {{EX:"*,+"}} to replicate all user and operational
+attributes, and {{EX:attrsonly}} is unset by default. Both {{EX:sizelimit}}
+and {{EX:timelimit}} default to "unlimited", and only positive integers
+or "unlimited" may be specified. The {{EX:exattrs}} option may also be used
+to specify attributes that should be omitted from incoming entries.
+
+The {{TERM[expand]LDAP Sync}} protocol has two operation
+types: {{EX:refreshOnly}} and {{EX:refreshAndPersist}}.
+The operation type is specified by the {{EX:type}} parameter.
+In the {{EX:refreshOnly}} operation, the next synchronization search operation
+is periodically rescheduled at an interval time after each
+synchronization operation finishes. The interval is specified
+by the {{EX:interval}} parameter. It is set to one day by default.
+In the {{EX:refreshAndPersist}} operation, a synchronization search
+remains persistent in the provider {{slapd}} instance. Further updates to the
+provider will generate {{EX:searchResultEntry}} to the consumer slapd
+as the search responses to the persistent synchronization search.
+
+If an error occurs during replication, the consumer will attempt to reconnect
+according to the 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 three times before stop retrying. + in <# of retries> means
+indefinite number of retries until success.
+
+The schema checking can be enforced at the LDAP Sync consumer site
+by turning on the {{EX:schemachecking}} parameter.
+If it is turned on, every replicated entry will be checked for its
+schema as the entry is stored on the consumer.
+Every entry in the consumer should contain those attributes
+required by the schema definition.
+If it is turned off, entries will be stored without checking
+schema conformance. The default is off.
+
+The {{EX:binddn}} parameter gives the DN to bind as for the
+syncrepl searches to the provider slapd. It should be a DN
+which has read access to the replication content in the
+provider database.
+
+The {{EX:bindmethod}} is {{EX:simple}} or {{EX:sasl}},
+depending on whether simple password-based authentication or
+{{TERM:SASL}} authentication is to be used when connecting
+to the provider {{slapd}} instance.
+
+Simple authentication should not be used unless adequate data
+integrity and confidentiality protections are in place (e.g. TLS
+or IPsec). Simple authentication requires specification of {{EX:binddn}}
+and {{EX:credentials}} parameters.
+
+SASL authentication is generally recommended. SASL authentication
+requires specification of a mechanism using the {{EX:saslmech}} parameter.
+Depending on the mechanism, an authentication identity and/or
+credentials can be specified using {{EX:authcid}} and {{EX:credentials}},
+respectively. The {{EX:authzid}} parameter may be used to specify
+an authorization identity.
+
+The {{EX:realm}} parameter specifies a realm which a certain
+mechanisms authenticate the identity within. The {{EX:secprops}}
+parameter specifies Cyrus SASL security properties.
+
+The {{EX:starttls}} parameter specifies use of the StartTLS extended
+operation to establish a TLS session before authenticating to the provider.
+If the {{EX:critical}} argument is supplied, the session will be aborted
+if the StartTLS request fails. Otherwise the syncrepl session continues
+without TLS. The tls_reqcert setting defaults to {{EX:"demand"}} and the
+other TLS settings default to the same as the main slapd TLS settings.
+
+Rather than replicating whole entries, the consumer can query logs
+of data modifications. This mode of operation is referred to as
+{{delta syncrepl}}. In addition to the above parameters, the
+{{EX:logbase}} and {{EX:logfilter}} parameters must be set appropriately
+for the log that will be used. The {{EX:syncdata}} parameter must
+be set to either {{EX:"accesslog"}} if the log conforms to the
+{{slapo-accesslog}}(5) log format, or {{EX:"changelog"}} if the log
+conforms to the obsolete {{changelog}} format. If the {{EX:syncdata}}
+parameter is omitted or set to {{EX:"default"}} then the log
+parameters are ignored.
+
+The {{syncrepl}} replication mechanism is supported by the {{mdb}}
+backend.
+
+See the {{SECT:LDAP Sync Replication}} chapter of this guide for
+more information on how to use this directive.
+
+
+H4: olcTimeLimit: <integer>
+
+This directive specifies the maximum number of seconds (in real
+time) slapd will spend answering a search request. If a
+request is not finished in this time, a result indicating an
+exceeded timelimit will be returned.
+
+\Default:
+
+> olcTimeLimit: 3600
+
+See the {{SECT:Limits}} section of this guide and slapd-config(5)
+for more details.
+
+
+H4: olcUpdateref: <URL>
+
+This directive is only applicable in a {{replica}} (or {{shadow}})
+{{slapd}}(8) instance. It
+specifies the URL to return to clients which submit update
+requests upon the replica.
+If specified multiple times, each {{TERM:URL}} is provided.
+
+\Example:
+
+> olcUpdateref: ldap://provider.example.net
+
+
+H4: Sample Entries
+
+>dn: olcDatabase=frontend,cn=config
+>objectClass: olcDatabaseConfig
+>objectClass: olcFrontendConfig
+>olcDatabase: frontend
+>olcReadOnly: FALSE
+>
+>dn: olcDatabase=config,cn=config
+>objectClass: olcDatabaseConfig
+>olcDatabase: config
+>olcRootDN: cn=Manager,dc=example,dc=com
+
+
+H3: MDB Backend Directives
+
+Directives in this category only apply to the {{TERM:MDB}}
+database backend. They will apply to all "database mdb"
+instances in the configuration. For a complete reference
+of MDB backend configuration directives, see {{slapd-mdb}}(5).
+
+H4: olcBkMdbIdlExp <exponent>
+
+Specify a power of 2 for the maximum size of an index slot.
+The default is 16, yielding a maximum slot size of 2^16 or 65536.
+The specified value must be in the range of 16-30.
+
+This setting helps with the case where certain search filters are
+slow to return results due to an index slot having collapsed to a
+range value. This occurs when the number of candidate entries that
+match the filter for the index slot exceed the configured slot size.
+
+If this setting is decreased on a server with existing {{TERM:MDB}}
+databases, each db will immediately need its indices to be rebuilt
+while slapd is offline with the "slapindex -q -t" command.
+
+If this setting is increased on a server with existing {{TERM:MDB}}
+databases, each db will need its indices rebuilt to take advantage
+of the change for indices that have already been converted to ranges.
+
+
+H3: MDB Database Directives
+
+Directives in this category apply to the {{TERM:MDB}}
+database backend.
+They are used in an olcDatabase entry in addition to the generic
+database directives defined above. For a complete reference
+of MDB configuration directives, see {{slapd-mdb}}(5). In
+addition to the {{EX:olcDatabaseConfig}} objectClass, MDB
+database entries must have the {{EX:olcMdbConfig}} objectClass.
+
+
+H4: olcDbDirectory: <directory>
+
+This directive specifies the directory where the MDB files
+containing the database and associated indices live.
+
+\Default:
+
+> olcDbDirectory: /usr/local/var/openldap-data
+
+
+H4: olcDbCheckpoint: <kbyte> <min>
+
+This directive specifies the frequency for flushing the database disk
+buffers. This directive is only needed if the {{olcDbNoSync}} option is
+{{EX:TRUE}}.
+The checkpoint will occur if either <kbyte> data has been written or
+<min> minutes have passed since the last checkpoint. Both arguments default
+to zero, in which case they are ignored. When the <min> argument is
+non-zero, an internal task will run every <min> minutes to perform the
+checkpoint. Note: currently the _kbyte_ setting is unimplemented.
+
+\Example:
+
+> olcDbCheckpoint: 1024 10
+
+
+H4: olcDbEnvFlags: {nosync,nometasync,writemap,mapasync,nordahead}
+
+This option specifies flags for finer-grained control of the LMDB library's
+operation.
+
+* {{F:nosync}}: This is exactly the same as the dbnosync directive.
+
+* {{F:nometasync}}: Flush the data on a commit, but skip the sync of the meta
+page. This mode is slightly faster than doing a full sync, but can
+potentially lose the last committed transaction if the operating system
+crashes. If both nometasync and nosync are set, the nosync flag takes
+precedence.
+
+* {{F:writemap}}: Use a writable memory map instead of just read-only. This
+speeds up write operations but makes the database vulnerable to corruption in
+case any bugs in slapd cause stray writes into the mmap region.
+
+* {{F:mapasync}}: When using a writable memory map and performing flushes on
+each commit, use an asynchronous flush instead of a synchronous flush (the
+default). This option has no effect if writemap has not been set. It also has
+no effect if nosync is set.
+
+* {{F:nordahead}}: Turn off file readahead. Usually the OS performs readahead
+on every read request. This usually boosts read performance but can be
+harmful to random access read performance if the system's memory is full and
+the DB is larger than RAM. This option is not implemented on Windows.
+
+
+H4: olcDbIndex: {<attrlist> | default} [pres,eq,approx,sub,none]
+
+This directive specifies the indices to maintain for the given
+attribute. If only an {{EX:<attrlist>}} is given, the default
+indices are maintained. The index keywords correspond to the
+common types of matches that may be used in an LDAP search filter.
+
+\Example:
+
+> olcDbIndex: default pres,eq
+> olcDbIndex: uid
+> olcDbIndex: cn,sn pres,eq,sub
+> olcDbIndex: objectClass eq
+
+The first line sets the default set of indices to maintain to
+present and equality. The second line causes the default (pres,eq)
+set of indices to be maintained for the {{EX:uid}} attribute type.
+The third line causes present, equality, and substring indices to
+be maintained for {{EX:cn}} and {{EX:sn}} attribute types. The
+fourth line causes an equality index for the {{EX:objectClass}}
+attribute type.
+
+There is no index keyword for inequality matches. Generally these
+matches do not use an index. However, some attributes do support
+indexing for inequality matches, based on the equality index.
+
+A substring index can be more explicitly specified as {{EX:subinitial}},
+{{EX:subany}}, or {{EX:subfinal}}, corresponding to the three
+possible components
+of a substring match filter. A subinitial index only indexes
+substrings that appear at the beginning of an attribute value.
+A subfinal index only indexes substrings that appear at the end
+of an attribute value, while subany indexes substrings that occur
+anywhere in a value.
+
+Note that by default, setting an index for an attribute also
+affects every subtype of that attribute. E.g., setting an equality
+index on the {{EX:name}} attribute causes {{EX:cn}}, {{EX:sn}}, and every other
+attribute that inherits from {{EX:name}} to be indexed.
+
+By default, no indices are maintained. It is generally advised
+that minimally an equality index upon objectClass be maintained.
+
+> olcDbIndex: objectClass eq
+
+Additional indices should be configured corresponding to the
+most common searches that are used on the database.
+Presence indexing should not be configured for an attribute
+unless the attribute occurs very rarely in the database, and
+presence searches on the attribute occur very frequently during
+normal use of the directory. Most applications don't use presence
+searches, so usually presence indexing is not very useful.
+
+If this setting is changed while slapd is running, an internal task
+will be run to generate the changed index data. All server operations
+can continue as normal while the indexer does its work. If slapd is
+stopped before the index task completes, indexing will have to be
+manually completed using the slapindex tool.
+
+
+H4: olcDbMaxEntrySize: <bytes>
+
+Specify the maximum size of an entry in bytes. Attempts to store
+an entry larger than this size will be rejected with the error
+LDAP_ADMINLIMIT_EXCEEDED. The default is 0, which is unlimited.
+
+
+H4: olcDbMaxReaders: <integer>
+
+This directive specifies the maximum number of threads that may have
+concurrent read access to the database. Tools such as slapcat count as a
+single thread, in addition to threads in any active slapd processes. The
+default is 126.
+
+
+H4: olcDbMaxSize: <bytes>
+
+This directive specifies the maximum size of the database in bytes. A memory
+map of this size is allocated at startup time and the database will not be
+allowed to grow beyond this size. The default is 10485760 bytes (10MB). This
+setting may be changed upward if the configured limit needs to be increased.
+
+Note: It is important to set this to as large a value as possible, (relative
+to anticipated growth of the actual data over time) since growing the size
+later may not be practical when the system is under heavy load.
+
+
+H4: olcDbMode: { <octal> | <symbolic> }
+
+This directive specifies the file protection mode that newly
+created database index files should have. This can be in the form
+{{EX:0600}} or {{EX:-rw-------}}
+
+\Default:
+
+> olcDbMode: 0600
+
+
+H4: olcDbMultival: { <attrlist> | default } <integer> hi,<integer> lo
+
+Specify the number of values for which a multivalued attribute is
+stored in a separate table. Normally entries are stored as a single
+blob inside the database. When an entry gets very large or contains
+attributes with a very large number of values, modifications on that
+entry may get very slow. Splitting the large attributes out to a separate
+table can improve the performance of modification operations.
+The threshold is specified as a pair of integers. If the number of
+values exceeds the hi threshold the values will be split out. If
+a modification deletes enough values to bring an attribute below
+the lo threshold the values will be removed from the separate
+table and merged back into the main entry blob.
+The threshold can be set for a specific list of attributes, or
+the default can be configured for all other attributes.
+The default value for both hi and lo thresholds is UINT_MAX, which keeps
+all attributes in the main blob.
+
+In addition to increasing write performance of operations the use of
+multival can also decrease fragmentation of the primary {{TERM:MDB}} database.
+
+
+H4: olcDbRtxnsize: <entries>
+
+This directive specifies the maximum number of entries to process in a single
+read transaction when executing a large search. Long-lived read transactions
+prevent old database pages from being reused in write transactions, and so
+can cause significant growth of the database file when there is heavy write
+traffic. This setting causes the read transaction in large searches to be
+released and reacquired after the given number of entries has been read, to
+give writers the opportunity to reclaim old database pages. The default is
+10000.
+
+
+H4: olcDbSearchStack: <integer>
+
+Specify the depth of the stack used for search filter evaluation.
+Search filters are evaluated on a stack to accommodate nested {{EX:AND}} /
+{{EX:OR}} clauses. An individual stack is allocated for each server thread.
+The depth of the stack determines how complex a filter can be evaluated
+without requiring any additional memory allocation. Filters that are
+nested deeper than the search stack depth will cause a separate stack to
+be allocated for that particular search operation. These separate allocations
+can have a major negative impact on server performance, but specifying
+too much stack will also consume a great deal of memory. Each search
+uses 512K bytes per level on a 32-bit machine, or 1024K bytes per level
+on a 64-bit machine. The default stack depth is 16, thus 8MB or 16MB
+per thread is used on 32 and 64 bit machines, respectively. Also the
+512KB size of a single stack slot is set by a compile-time constant which
+may be changed if needed; the code must be recompiled for the change
+to take effect.
+
+\Default:
+
+> olcDbSearchStack: 16
+
+
+H4: olcDbNosync: { TRUE | FALSE }
+
+This directive causes on-disk database contents to not be immediately
+synchronized with in memory changes upon change. Setting this option
+to {{EX:TRUE}} may improve performance at the expense of data integrity.
+
+
+H4: Sample Entry
+
+>dn: olcDatabase=mdb,cn=config
+>objectClass: olcDatabaseConfig
+>objectClass: olcMdbConfig
+>olcDatabase: mdb
+>olcSuffix: dc=example,dc=com
+>olcDbDirectory: /usr/local/var/openldap-data
+>olcDbIndex: objectClass eq
+
+
+H2: Configuration Example
+
+The following is an example configuration, interspersed
+with explanatory text. It defines two databases to handle
+different parts of the {{TERM:X.500}} tree; both are {{TERM:MDB}}
+database instances. The line numbers shown are provided for
+reference only and are not included in the actual file. First, the
+global configuration section:
+
+E: 1. # example config file - global configuration entry
+E: 2. dn: cn=config
+E: 3. objectClass: olcGlobal
+E: 4. cn: config
+E: 5. olcReferral: ldap://root.openldap.org
+E: 6.
+
+Line 1 is a comment. Lines 2-4 identify this as the global
+configuration entry.
+The {{EX:olcReferral:}} directive on line 5
+means that queries not local to one of the databases defined
+below will be referred to the LDAP server running on the
+standard port (389) at the host {{EX:root.openldap.org}}.
+Line 6 is a blank line, indicating the end of this entry.
+
+E: 7. # internal schema
+E: 8. dn: cn=schema,cn=config
+E: 9. objectClass: olcSchemaConfig
+E: 10. cn: schema
+E: 11.
+
+Line 7 is a comment. Lines 8-10 identify this as the root of
+the schema subtree. The actual schema definitions in this entry
+are hardcoded into slapd so no additional attributes are specified here.
+Line 11 is a blank line, indicating the end of this entry.
+
+E: 12. # include the core schema
+E: 13. include: file:///usr/local/etc/openldap/schema/core.ldif
+E: 14.
+
+Line 12 is a comment. Line 13 is an LDIF include directive which
+accesses the {{core}} schema definitions in LDIF format. Line 14
+is a blank line.
+
+Next comes the database definitions. The first database is the
+special {{EX:frontend}} database whose settings are applied globally
+to all the other databases.
+
+E: 15. # global database parameters
+E: 16. dn: olcDatabase=frontend,cn=config
+E: 17. objectClass: olcDatabaseConfig
+E: 18. olcDatabase: frontend
+E: 19. olcAccess: to * by * read
+E: 20.
+
+Line 15 is a comment. Lines 16-18 identify this entry as the global
+database entry. Line 19 is a global access control. It applies to all
+entries (after any applicable database-specific access controls).
+Line 20 is a blank line.
+
+The next entry defines the config backend.
+
+E: 21. # set a rootpw for the config database so we can bind.
+E: 22. # deny access to everyone else.
+E: 23. dn: olcDatabase=config,cn=config
+E: 24. objectClass: olcDatabaseConfig
+E: 25. olcDatabase: config
+E: 26. olcRootPW: {SSHA}XKYnrjvGT3wZFQrDD5040US592LxsdLy
+E: 27. olcAccess: to * by * none
+E: 28.
+
+Lines 21-22 are comments. Lines 23-25 identify this entry as the config
+database entry. Line 26 defines the {{super-user}} password for this
+database. (The DN defaults to {{"cn=config"}}.) Line 27 denies all access
+to this database, so only the super-user will be able to access it. (This
+is already the default access on the config database. It is just listed
+here for illustration, and to reiterate that unless a means to authenticate
+as the super-user is explicitly configured, the config database will be
+inaccessible.)
+
+Line 28 is a blank line.
+
+The next entry defines an MDB backend that will handle queries for things
+in the "dc=example,dc=com" portion of the tree. Indices are to be maintained
+for several attributes, and the {{EX:userPassword}} attribute is to be
+protected from unauthorized access.
+
+E: 29. # MDB definition for example.com
+E: 30. dn: olcDatabase=mdb,cn=config
+E: 31. objectClass: olcDatabaseConfig
+E: 32. objectClass: olcMdbConfig
+E: 33. olcDatabase: mdb
+E: 34. olcSuffix: dc=example,dc=com
+E: 35. olcDbDirectory: /usr/local/var/openldap-data
+E: 36. olcRootDN: cn=Manager,dc=example,dc=com
+E: 37. olcRootPW: secret
+E: 38. olcDbIndex: uid pres,eq
+E: 39. olcDbIndex: cn,sn pres,eq,approx,sub
+E: 40. olcDbIndex: objectClass eq
+E: 41. olcAccess: to attrs=userPassword
+E: 42. by self write
+E: 43. by anonymous auth
+E: 44. by dn.base="cn=Admin,dc=example,dc=com" write
+E: 45. by * none
+E: 46. olcAccess: to *
+E: 47. by self write
+E: 48. by dn.base="cn=Admin,dc=example,dc=com" write
+E: 49. by * read
+E: 50.
+
+Line 29 is a comment. Lines 30-33 identify this entry as a MDB database
+configuration entry. Line 34 specifies the DN suffix
+for queries to pass to this database. Line 35 specifies the directory
+in which the database files will live.
+
+Lines 36 and 37 identify the database {{super-user}} entry and associated
+password. This entry is not subject to access control or size or
+time limit restrictions.
+
+Lines 38 through 40 indicate the indices to maintain for various
+attributes.
+
+Lines 41 through 49 specify access control for entries in this
+database. For all applicable entries, the {{EX:userPassword}} attribute is writable
+by the entry itself and by the "admin" entry. It may be used for
+authentication/authorization purposes, but is otherwise not readable.
+All other attributes are writable by the entry and the "admin"
+entry, but may be read by all users (authenticated or not).
+
+Line 50 is a blank line, indicating the end of this entry.
+
+The next entry defines another
+MDB database. This one handles queries involving the
+{{EX:dc=example,dc=net}} subtree but is managed by the same entity
+as the first database. Note that without line 60, the read access
+would be allowed due to the global access rule at line 19.
+
+E: 51. # MDB definition for example.net
+E: 52. dn: olcDatabase=mdb,cn=config
+E: 53. objectClass: olcDatabaseConfig
+E: 54. objectClass: olcMdbConfig
+E: 55. olcDatabase: mdb
+E: 56. olcSuffix: dc=example,dc=net
+E: 57. olcDbDirectory: /usr/local/var/openldap-data-net
+E: 58. olcRootDN: cn=Manager,dc=example,dc=com
+E: 59. olcDbIndex: objectClass eq
+E: 60. olcAccess: to * by users read
+
+
+H2: Converting old style {{slapd.conf}}(5) file to {{cn=config}} format
+
+Before converting to the {{cn=config}} format you should make sure that the
+config backend is properly configured in your existing config file. While
+the config backend is always present inside slapd, by default it is only
+accessible by its rootDN, and there are no default credentials assigned
+so unless you explicitly configure a means to authenticate to it, it will be
+unusable.
+
+If you do not already have a {{EX:database config}} section, add something
+like this to the end of {{EX:slapd.conf}}
+
+> database config
+> rootpw VerySecret
+
+Note: Since the config backend can be used to load arbitrary code into the
+slapd process, it is extremely important to carefully guard whatever
+credentials are used to access it. Since simple passwords are vulnerable to
+password guessing attacks, it is usually better to omit the rootpw and only
+use SASL authentication for the config rootDN.
+
+An existing {{slapd.conf}}(5) file can be converted to the new format using
+{{slaptest}}(8) or any of the slap tools:
+
+> slaptest -f /usr/local/etc/openldap/slapd.conf -F /usr/local/etc/openldap/slapd.d
+
+Test that you can access entries under {{EX:cn=config}} using the
+default {{rootdn}} and the {{rootpw}} configured above:
+
+> ldapsearch -x -D cn=config -w VerySecret -b cn=config
+
+You can then discard the old {{slapd.conf}}(5) file. Make sure to launch
+{{slapd}}(8) with the {{-F}} option to specify the configuration directory
+if you are not using the default directory path.
+
+Note: When converting from the slapd.conf format to slapd.d format, any
+included files will also be integrated into the resulting configuration
+database.
+
+
+H2: Recovering from a broken configuration
+
+If the server using {{cn=config}} does not start, either because the
+configuration does not represent the current version or because it has been
+corrupted, these actions are available, in the order of decreasing preference.
+
+Make sure you have made a backup of the "broken" version before you attempt any
+of these:
+
+
+H3: Generate an ldif version of the configuration database and reload from that
+
+Most of the time, the configuration can be parsed and a text version generated
+with {{slapcat}}(8):
+
+> slapcat -F /usr/local/etc/openldap/slapd.d -n0 -l extracted_config.ldif
+
+After you have backed up and removed the old configuration database contents,
+this output ldif can be hand-edited to adjust or remove the offending entries
+and imported again:
+
+> slapadd -F /usr/local/etc/openldap/slapd.d -l updated_config.ldif
+> slaptest -F /usr/local/etc/openldap/slapd.d
+
+
+H3: Modify config in-place
+
+If the configuration can be parsed and you know exactly what you need to do,
+you can use {{slapmodify}}(8) to effect the required changes directly:
+
+> slapmodify -F /usr/local/etc/openldap/slapd.d
+> dn: ..., cn=config
+> changetype: ...
+> ...
+
+
+H3: Recover with plain back-ldif
+
+If the configuration contains items that {{slapd}}(8) cannot process as a
+{{cn=config}} database at all, the last resort is to disable schema checking
+and operate on it as a regular back-ldif database. This might cease to work
+with future versions of OpenLDAP without notice, attempt this only when all of
+the above fail.
+
+First, create a directory to serve as the hosting DB and create the structure:
+
+> mkdir ./recovery ./recovery/cn=recovery
+> cp /usr/local/etc/openldap/slapd.d/cn=config.ldif ./recovery/cn=recovery
+> cp -r /usr/local/etc/openldap/slapd.d/cn=config ./recovery/cn=recovery
+
+Or, if you have already backed up your old configuration, you can symlink it
+into place:
+
+> mkdir ./recovery
+> ln -s /usr/local/etc/openldap/slapd.d ./recovery/cn=recovery
+
+Next, create a trivial {{slapd.conf}}(5) to access the new database:
+
+> database ldif
+> suffix cn=recovery
+> directory ./recovery/
+
+Note the change of suffix, {{EX:cn=config}} is hardcoded to correspond to an
+active config database, so we have to home it one level deeper - at
+{{EX:cn=config,cn=recovery}}.
+
+Now you can use {{slapmodify}}(8) to modify the database, it is most likely you
+will need to run with schema checking disabled:
+
+> slapmodify -f ./recovery.conf -s
+
+You can test the validity of your config with {{slaptest}}(8):
+
+> slaptest -F ./recovery/cn=recovery
+
+And generate a full ldif with {{slapcat}}(8):
+
+> slapcat -F ./recovery/cn=recovery -n0