diff options
Diffstat (limited to 'doc/guide/admin/slapdconfig.sdf')
| -rw-r--r-- | doc/guide/admin/slapdconfig.sdf | 923 |
1 files changed, 923 insertions, 0 deletions
diff --git a/doc/guide/admin/slapdconfig.sdf b/doc/guide/admin/slapdconfig.sdf new file mode 100644 index 0000000..e9fc5d3 --- /dev/null +++ b/doc/guide/admin/slapdconfig.sdf @@ -0,0 +1,923 @@ +# $OpenLDAP$ +# Copyright 1999-2022 The OpenLDAP Foundation, All Rights Reserved. +# COPYING RESTRICTIONS APPLY, see COPYRIGHT. + +H1: The slapd Configuration File + +This chapter describes configuring {{slapd}}(8) via the {{slapd.conf}}(5) +configuration file. {{slapd.conf}}(5) has been deprecated and should +only be used if your site requires one of the backends that hasn't yet +been updated to work with the newer {{slapd-config}}(5) system. Configuring +{{slapd}}(8) via {{slapd-config}}(5) is described in the previous chapter. + +The {{slapd.conf}}(5) file is normally installed in the +{{EX:/usr/local/etc/openldap}} directory. An alternate configuration +file location can be specified via a command-line option to {{slapd}}(8). + + +H2: Configuration File Format + +The {{slapd.conf}}(5) file consists of three types of configuration +information: global, backend specific, and database specific. Global +information is specified first, followed by information associated +with a particular backend type, which is then followed by information +associated with a particular database instance. Global directives can +be overridden in backend and/or database directives, and backend directives +can be overridden by database directives. + +Blank lines and comment lines beginning with a '{{EX:#}}' character +are ignored. If a line begins with whitespace, it is considered a +continuation of the previous line (even if the previous line is a +comment). + +The general format of slapd.conf is as follows: + +> # global configuration directives +> <global config directives> +> +> # backend definition +> backend <typeA> +> <backend-specific directives> +> +> # first database definition & config directives +> database <typeA> +> <database-specific directives> +> +> # second database definition & config directives +> database <typeB> +> <database-specific directives> +> +> # second database definition & config directives +> database <typeA> +> <database-specific directives> +> +> # subsequent backend & database definitions & config directives +> ... + +A configuration directive may take arguments. If so, they are +separated by whitespace. If an argument contains whitespace, +the argument should be enclosed in double quotes {{EX:"like this"}}. If +an argument contains a double quote or a backslash character `{{EX:\}}', +the character should be preceded by a backslash character `{{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 File Directives + +This section details commonly used configuration directives. For +a complete list, see the {{slapd.conf}}(5) manual page. This section +separates the configuration file directives into global, +backend-specific and data-specific categories, describing each +directive and its default value (if any), and giving an example of +its use. + + + +H3: Global Directives + +Directives described in this section apply to all backends +and databases unless specifically overridden in a backend or +database definition. Arguments that should be replaced +by actual text are shown in brackets {{EX:<>}}. + + +H4: access 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 details discussion of this directive can be found in the +{{SECT:Advanced Access Control}} chapter. +!endif + +Note: If no {{EX:access}} directives are specified, the default +access control policy, {{EX:access to * by * read}}, allows all +both authenticated and anonymous users read access. + + +H4: attributetype <{{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: idletimeout <integer> + +Specify the number of seconds to wait before forcibly closing +an idle client connection. An idletimeout of 0, the default, +disables this feature. + + +H4: include <filename> + +This directive specifies that slapd should read additional +configuration information from the given file before continuing +with the next line of the current file. The included file should +follow the normal slapd config file format. The file is commonly +used to include files containing schema specifications. + +Note: You should be careful when using this directive - there is +no small limit on the number of nested include directives, and no +loop detection is done. + +H4: loglevel <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 <integer> are: + +!block table; colaligns="RL"; align=Center; \ + title="Table 6.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 + +> loglevel 129 +> loglevel 0x81 +> loglevel 128 1 +> loglevel 0x80 0x1 +> loglevel acl trace + +are equivalent. + +\Examples: + +E: loglevel -1 + +This will enable all log levels. + +E: loglevel conns filter + +Just log the connection and search filter processing. + +E: loglevel 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: loglevel stats + +Basic stats logging is configured by default. + +H4: objectclass <{{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: referral <URI> + +This directive specifies the referral to pass back when slapd +cannot find a local database to handle a request. + +\Example: + +> referral 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: sizelimit <integer> + +This directive specifies the maximum number of entries to return +from a search operation. + +\Default: + +> sizelimit 500 + +See the {{SECT:Limits}} section of this guide and {{slapd.conf}}(5) +for more details. + +H4: timelimit <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: + +> timelimit 3600 + +See the {{SECT:Limits}} section of this guide and {{slapd.conf}}(5) +for more details. + + +H3: General Backend Directives + +Directives in this section apply only to the backend in which +they are defined. They are supported by every type of backend. +Backend directives apply to all databases instances of the +same type and, depending on the directive, may be overridden +by database directives. + +H4: backend <type> + +This directive marks the beginning of a backend declaration. +{{EX:<type>}} should be one of the +supported backend types listed in Table 6.2. + +!block table; align=Center; coltags="EX,N"; \ + title="Table 6.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: + +> backend mdb +> idlexp 16 + +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. + + +H3: General Database Directives + +Directives in this section apply only to the database in which +they are defined. They are supported by every type of database. + +H4: database <type> + +This directive marks the beginning of a database instance +declaration. +{{EX:<type>}} should be one of the +supported backend types listed in Table 6.2. + +\Example: + +> database mdb + +This marks the beginning of a new {{TERM:MDB}} database instance +declaration. + + +H4: limits <selector> <limit> [<limit> [...]] + +Specify time and size limits based on the operation's initiator or base +DN. + +See the {{SECT:Limits}} section of this guide and {{slapd.conf}}(5) +for more details. + + +H4: readonly { on | off } + +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: + +> readonly off + + +H4: rootdn <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: + +> rootdn "cn=Manager,dc=example,dc=com" + +SASL-based Example: + +> rootdn "uid=root,cn=example.com,cn=digest-md5,cn=auth" + +See the {{SECT:SASL Authentication}} section for information on +SASL authentication identities. + + +H4: rootpw <password> + +This directive can be used to specifies a password for the DN for +the rootdn (when the rootdn is set to a DN within the database). + +\Example: + +> rootpw secret + +It is also permissible to provide hash of the password in {{REF:RFC2307}} +form. {{slappasswd}}(8) may be used to generate the password hash. + +\Example: + +> rootpw {SSHA}ZKKuqbEKJfKSXhUbHG3fG8MDn9j1v4QN + +The hash was generated using the command {{EX:slappasswd -s secret}}. + + +H4: suffix <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 at least one is required for each database +definition. + +\Example: + +> suffix "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 line(s) in each database definition in the +order they appear in the file. Thus, if one database suffix is a +prefix of another, it must appear after it in the config file. + + +H4: syncrepl + +> syncrepl rid=<replica ID> +> provider=ldap[s]://<hostname>[:port] +> searchbase=<base DN> +> [type=refreshOnly|refreshAndPersist] +> [interval=dd:hh:mm:ss] +> [retry=[<retry interval> <# of retries>]+] +> [filter=<filter str>] +> [scope=sub|one|base] +> [attrs=<attr list>] +> [exattrs=<attr list>] +> [attrsonly] +> [sizelimit=<limit>] +> [timelimit=<limit>] +> [schemachecking=on|off] +> [network-timeout=<seconds>] +> [timeout=<seconds>] +> [bindmethod=simple|sasl] +> [binddn=<DN>] +> [saslmech=<mech>] +> [authcid=<identity>] +> [authzid=<identity>] +> [credentials=<passwd>] +> [realm=<realm>] +> [secprops=<properties>] +> [keepalive=<idle>:<probes>:<interval>] +> [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] +> [tls_protocol_min=<major>[.<minor>]] +> [suffixmassage=<real DN>] +> [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 replication 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:network-timeout}} parameter sets how long the consumer will +wait to establish a network connection to the provider. Once a +connection is established, the {{EX:timeout}} parameter determines how +long the consumer will wait for the initial Bind request to complete. The +defaults for these parameters come from {{ldap.conf}}(5). + +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:keepalive}} parameter sets the values of idle, probes, and interval +used to check whether a socket is alive; idle is the number of seconds a +connection needs to remain idle before TCP starts sending keepalive probes; +probes is the maximum number of keepalive probes TCP should send before +dropping the connection; interval is interval in seconds between individual +keepalive probes. Only some systems support the customization of these +values; the keepalive parameter is ignored otherwise, and system-wide +settings are used. For example, keepalive="240:10:30" will send a keepalive +probe 10 times, every 30 seconds, after 240 seconds of idle activity. If +no response to the probes is received, the connection will be dropped. + +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. + +The {{EX:suffixmassage}} parameter allows the consumer to pull entries +from a remote directory whose DN suffix differs from the local directory. +The portion of the remote entries' DNs that matches the searchbase will +be replaced with the suffixmassage DN. + +Rather than replicating whole entries, the consumer can query logs +of data modifications. This mode of operation is referred to as +{{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: updateref <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: + +> updateref ldap://provider.example.net + + +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: idlexp <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 only apply to the {{TERM:MDB}} +database backend. +That is, they must follow a "database mdb" line +and come before any subsequent "backend" or "database" lines. +For a complete reference of MDB configuration directives, see {{slapd-mdb}}(5). + +H4: directory <directory> + +This directive specifies the directory where the MDB files +containing the database and associated indices live. + +\Default: + +> directory /usr/local/var/openldap-data + +H4: checkpoint <kbyte> <min> + +This directive specifies the frequency for flushing the database disk +buffers. This directive is only needed if the {{dbnosync}} 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: + +> checkpoint: 1024 10 + +H4: dbnosync: { 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: envflags: {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: index: {<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: + +> index: default pres,eq +> index: uid +> index: cn,sn pres,eq,sub +> index: 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. + +> index: 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. + + +H4: maxentrysize: <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: maxreaders: <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: maxsize: <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: mode: { <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: + +> mode: 0600 + + +H4: multival: { <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: rtxnsize: <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: searchstack: <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: + +> searchstack: 16 + + +H4: Sample Entry + +>database mdb +>suffix: "dc=example,dc=com" +>directory: /usr/local/var/openldap-data +>index: objectClass eq + + +H2: Configuration File Example + +The following is an example configuration file, 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 section +E: 2. include /usr/local/etc/schema/core.schema +E: 3. referral ldap://root.openldap.org +E: 4. access to * by * read + +Line 1 is a comment. Line 2 includes another config file +which contains {{core}} schema definitions. +The {{EX:referral}} directive on line 3 +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 4 is a global access control. It applies to all +entries (after any applicable database-specific access +controls). + +The next section of the configuration file defines a MDB +backend that will handle queries for things in the +"dc=example,dc=com" portion of the tree. The +database is to be replicated to two replica slapds, one on +truelies, the other on judgmentday. Indices are to be +maintained for several attributes, and the {{EX:userPassword}} +attribute is to be protected from unauthorized access. + +E: 5. # MDB definition for the example.com +E: 6. database mdb +E: 7. suffix "dc=example,dc=com" +E: 8. directory /usr/local/var/openldap-data +E: 9. rootdn "cn=Manager,dc=example,dc=com" +E: 10. rootpw secret +E: 11. # indexed attribute definitions +E: 12. index uid pres,eq +E: 13. index cn,sn pres,eq,approx,sub +E: 14. index objectClass eq +E: 15. # database access control definitions +E: 16. access to attrs=userPassword +E: 17. by self write +E: 18. by anonymous auth +E: 19. by dn.base="cn=Admin,dc=example,dc=com" write +E: 20. by * none +E: 21. access to * +E: 22. by self write +E: 23. by dn.base="cn=Admin,dc=example,dc=com" write +E: 24. by * read + +Line 5 is a comment. The start of the database definition is marked +by the database keyword on line 6. Line 7 specifies the DN suffix +for queries to pass to this database. Line 8 specifies the directory +in which the database files will live. + +Lines 9 and 10 identify the database {{super-user}} entry and associated +password. This entry is not subject to access control or size or +time limit restrictions. + +Lines 12 through 14 indicate the indices to maintain for various +attributes. + +Lines 16 through 24 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). + +The next section of the example configuration file 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 39, the read access +would be allowed due to the global access rule at line 4. + +E: 33. # MDB definition for example.net +E: 34. database mdb +E: 35. suffix "dc=example,dc=net" +E: 36. directory /usr/local/var/openldap-data-net +E: 37. rootdn "cn=Manager,dc=example,dc=com" +E: 38. index objectClass eq +E: 39. access to * by users read |