diff options
Diffstat (limited to 'doc/guide/admin/slapdconf2.sdf')
| -rw-r--r-- | doc/guide/admin/slapdconf2.sdf | 1264 |
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 |