1# $OpenLDAP$ 2# Copyright 2005-2021 The OpenLDAP Foundation, All Rights Reserved. 3# COPYING RESTRICTIONS APPLY, see COPYRIGHT. 4 5H1: Configuring slapd 6 7Once the software has been built and installed, you are ready 8to configure {{slapd}}(8) for use at your site. 9 10OpenLDAP 2.3 and later have transitioned to using a dynamic runtime 11configuration engine, {{slapd-config}}(5). {{slapd-config}}(5) 12* is fully LDAP-enabled 13* is managed using the standard LDAP operations 14* stores its configuration data in an {{TERM:LDIF}} database, generally 15in the {{F:/usr/local/etc/openldap/slapd.d}} directory. 16* allows all of slapd's configuration options to be changed on the fly, 17generally without requiring a server restart for the changes 18to take effect. 19 20This chapter describes the general format of the {{slapd-config}}(5) 21configuration system, followed by a detailed description of commonly used 22settings. 23 24The older style {{slapd.conf}}(5) file is still supported, but its use 25is deprecated and support for it will be withdrawn in a future OpenLDAP 26release. Configuring {{slapd}}(8) via {{slapd.conf}}(5) is described in 27the next chapter. 28 29Refer to {{slapd}}(8) for information on how to have slapd automatically 30convert from {{slapd.conf}}(5) to {{slapd-config}}(5). 31 32 33Note: Although the {{slapd-config}}(5) system stores its configuration 34as (text-based) LDIF files, you should {{1:never}} edit any of 35the LDIF files directly. Configuration changes should be performed via LDAP 36operations, e.g. {{ldapadd}}(1), {{ldapdelete}}(1), or {{ldapmodify}}(1). 37For offline modifications (when the server is not running), use {{slapadd}}(8) 38and {{slapmodify}}(8). 39 40 41Note: You will need to continue to use the older {{slapd.conf}}(5) 42configuration system if your OpenLDAP installation requires the use of one 43or more backends or overlays that have not been updated to use the 44{{slapd-config}}(5) system. As of OpenLDAP 2.4.33, all of the official 45backends have been updated. There may be additional contributed or experimental 46overlays that also have not been updated. 47 48 49H2: Configuration Layout 50 51The slapd configuration is stored as a special LDAP directory with 52a predefined schema and DIT. There are specific objectClasses used to 53carry global configuration options, schema definitions, backend and 54database definitions, and assorted other items. A sample config tree 55is shown in Figure 5.1. 56 57!import "config_dit.png"; align="center"; title="Sample configuration tree" 58FT[align="Center"] Figure 5.1: Sample configuration tree. 59 60Other objects may be part of the configuration but were omitted from 61the illustration for clarity. 62 63The {{slapd-config}} configuration tree has a very specific structure. The 64root of the tree is named {{EX:cn=config}} and contains global configuration 65settings. Additional settings are contained in separate child entries: 66* Dynamically loaded modules 67.. These may only be used if the {{EX:--enable-modules}} option was 68used to configure the software. 69* Schema definitions 70.. The {{EX:cn=schema,cn=config}} entry contains the system schema (all 71the schema that is hard-coded in slapd). 72.. Child entries of {{EX:cn=schema,cn=config}} contain user schema as 73loaded from config files or added at runtime. 74* Backend-specific configuration 75* Database-specific configuration 76.. Overlays are defined in children of the Database entry. 77.. Databases and Overlays may also have other miscellaneous children. 78 79The usual rules for LDIF files apply to the configuration information: 80Comment lines beginning with a '{{EX:#}}' character 81are ignored. If a line begins with a single space, it is considered a 82continuation of the previous line (even if the previous line is a 83comment) and the single leading space is removed. Entries are separated by blank lines. 84 85The general layout of the config LDIF is as follows: 86 87> # global configuration settings 88> dn: cn=config 89> objectClass: olcGlobal 90> cn: config 91> <global config settings> 92> 93> # schema definitions 94> dn: cn=schema,cn=config 95> objectClass: olcSchemaConfig 96> cn: schema 97> <system schema> 98> 99> dn: cn={X}core,cn=schema,cn=config 100> objectClass: olcSchemaConfig 101> cn: {X}core 102> <core schema> 103> 104> # additional user-specified schema 105> ... 106> 107> # backend definitions 108> dn: olcBackend=<typeA>,cn=config 109> objectClass: olcBackendConfig 110> olcBackend: <typeA> 111> <backend-specific settings> 112> 113> # database definitions 114> dn: olcDatabase={X}<typeA>,cn=config 115> objectClass: olcDatabaseConfig 116> olcDatabase: {X}<typeA> 117> <database-specific settings> 118> 119> # subsequent definitions and settings 120> ... 121 122Some of the entries listed above have a numeric index {{EX:"{X}"}} in 123their names. While most configuration settings have an inherent ordering 124dependency (i.e., one setting must take effect before a subsequent one 125may be set), LDAP databases are inherently unordered. The numeric index 126is used to enforce a consistent ordering in the configuration database, 127so that all ordering dependencies are preserved. In most cases the index 128does not have to be provided; it will be automatically generated based 129on the order in which entries are created. 130 131Configuration directives are specified as values of individual 132attributes. 133Most of the attributes and objectClasses used in the slapd 134configuration have a prefix of {{EX:"olc"}} (OpenLDAP Configuration) 135in their names. Generally there is a one-to-one correspondence 136between the attributes and the old-style {{EX:slapd.conf}} configuration 137keywords, using the keyword as the attribute name, with the "olc" 138prefix attached. 139 140A configuration directive may take arguments. If so, the arguments are 141separated by whitespace. If an argument contains whitespace, 142the argument should be enclosed in double quotes {{EX:"like this"}}. 143In the descriptions that follow, arguments that should be replaced 144by actual text are shown in brackets {{EX:<>}}. 145 146The distribution contains an example configuration file that will 147be installed in the {{F: /usr/local/etc/openldap}} directory. 148A number of files containing schema definitions (attribute types 149and object classes) are also provided in the 150{{F: /usr/local/etc/openldap/schema}} directory. 151 152 153H2: Configuration Directives 154 155This section details commonly used configuration directives. For 156a complete list, see the {{slapd-config}}(5) manual page. This section 157will treat the configuration directives in a top-down order, starting 158with the global directives in the {{EX:cn=config}} entry. Each 159directive will be described along with its default value (if any) and 160an example of its use. 161 162 163H3: cn=config 164 165Directives contained in this entry generally apply to the server as a whole. 166Most of them are system or connection oriented, not database related. This 167entry must have the {{EX:olcGlobal}} objectClass. 168 169 170H4: olcIdleTimeout: <integer> 171 172Specify the number of seconds to wait before forcibly closing 173an idle client connection. A value of 0, the default, 174disables this feature. 175 176 177H4: olcLogLevel: <level> 178 179This directive specifies the level at which log statements 180and operation statistics should be sent to syslog (currently logged to 181the {{syslogd}}(8) {{EX:LOG_LOCAL4}} facility). You must have 182configured OpenLDAP {{EX:--enable-debug}} (the default) for this 183to work, except for the two statistics levels, which are always 184enabled. Log levels may be specified as integers or by keyword. 185Multiple log levels may be used and the levels are additive. 186The possible values for <level> are: 187 188!block table; colaligns="RL"; align=Center; \ 189 title="Table 5.1: Logging Levels" 190Level Keyword Description 191-1 any enable all debugging 1920 no debugging 1931 (0x1 trace) trace function calls 1942 (0x2 packets) debug packet handling 1954 (0x4 args) heavy trace debugging 1968 (0x8 conns) connection management 19716 (0x10 BER) print out packets sent and received 19832 (0x20 filter) search filter processing 19964 (0x40 config) configuration processing 200128 (0x80 ACL) access control list processing 201256 (0x100 stats) stats log connections/operations/results 202512 (0x200 stats2) stats log entries sent 2031024 (0x400 shell) print communication with shell backends 2042048 (0x800 parse) print entry parsing debugging 20516384 (0x4000 sync) syncrepl consumer processing 20632768 (0x8000 none) only messages that get logged regardless of configured log level 207!endblock 208 209The desired log level can be input as a single integer that 210combines the (ORed) desired levels, both in decimal or in hexadecimal 211notation, as a list of integers (that are ORed internally), or as a list of the names that are shown between brackets, such that 212 213> olcLogLevel 129 214> olcLogLevel 0x81 215> olcLogLevel 128 1 216> olcLogLevel 0x80 0x1 217> olcLogLevel acl trace 218 219are equivalent. 220 221\Examples: 222 223E: olcLogLevel -1 224 225This will enable all log levels. 226 227E: olcLogLevel conns filter 228 229Just log the connection and search filter processing. 230 231E: olcLogLevel none 232 233Log those messages that are logged regardless of the configured loglevel. This 234differs from setting the log level to 0, when no logging occurs. At least the 235{{EX:None}} level is required to have high priority messages logged. 236 237\Default: 238 239E: olcLogLevel stats 240 241Basic stats logging is configured by default. 242 243H4: olcReferral <URI> 244 245This directive specifies the referral to pass back when slapd 246cannot find a local database to handle a request. 247 248\Example: 249 250> olcReferral: ldap://root.openldap.org 251 252This will refer non-local queries to the global root LDAP server 253at the OpenLDAP Project. Smart LDAP clients can re-ask their 254query at that server, but note that most of these clients are 255only going to know how to handle simple LDAP URLs that 256contain a host part and optionally a distinguished name part. 257 258 259H4: Sample Entry 260 261>dn: cn=config 262>objectClass: olcGlobal 263>cn: config 264>olcIdleTimeout: 30 265>olcLogLevel: Stats 266>olcReferral: ldap://root.openldap.org 267 268 269H3: cn=module 270 271If support for dynamically loaded modules was enabled when configuring 272slapd, {{EX:cn=module}} entries may be used to specify sets of modules to load. 273Module entries must have the {{EX:olcModuleList}} objectClass. 274 275 276H4: olcModuleLoad: <filename> 277 278Specify the name of a dynamically loadable module to load. The filename 279may be an absolute path name or a simple filename. Non-absolute names 280are searched for in the directories specified by the {{EX:olcModulePath}} 281directive. 282 283 284H4: olcModulePath: <pathspec> 285 286Specify a list of directories to search for loadable modules. Typically the 287path is colon-separated but this depends on the operating system. 288 289 290H4: Sample Entries 291 292>dn: cn=module{0},cn=config 293>objectClass: olcModuleList 294>cn: module{0} 295>olcModuleLoad: /usr/local/lib/smbk5pwd.la 296> 297>dn: cn=module{1},cn=config 298>objectClass: olcModuleList 299>cn: module{1} 300>olcModulePath: /usr/local/lib:/usr/local/lib/slapd 301>olcModuleLoad: accesslog.la 302>olcModuleLoad: pcache.la 303 304 305H3: cn=schema 306 307The cn=schema entry holds all of the schema definitions that are hard-coded 308in slapd. As such, the values in this entry are generated by slapd so no 309schema values need to be provided in the config file. The entry must still 310be defined though, to serve as a base for the user-defined schema to add 311in underneath. Schema entries must have the {{EX:olcSchemaConfig}} 312objectClass. 313 314 315H4: olcAttributeTypes: <{{REF:RFC4512}} Attribute Type Description> 316 317This directive defines an attribute type. 318Please see the {{SECT:Schema Specification}} chapter 319for information regarding how to use this directive. 320 321 322H4: olcObjectClasses: <{{REF:RFC4512}} Object Class Description> 323 324This directive defines an object class. 325Please see the {{SECT:Schema Specification}} chapter for 326information regarding how to use this directive. 327 328 329H4: Sample Entries 330 331>dn: cn=schema,cn=config 332>objectClass: olcSchemaConfig 333>cn: schema 334> 335>dn: cn=test,cn=schema,cn=config 336>objectClass: olcSchemaConfig 337>cn: test 338>olcAttributeTypes: ( 1.1.1 339> NAME 'testAttr' 340> EQUALITY integerMatch 341> SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 ) 342>olcAttributeTypes: ( 1.1.2 NAME 'testTwo' EQUALITY caseIgnoreMatch 343> SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.44 ) 344>olcObjectClasses: ( 1.1.3 NAME 'testObject' 345> MAY ( testAttr $ testTwo ) AUXILIARY ) 346 347 348H3: Backend-specific Directives 349 350Backend directives apply to all database instances of the 351same type and, depending on the directive, may be overridden 352by database directives. Backend entries must have the 353{{EX:olcBackendConfig}} objectClass. 354 355H4: olcBackend: <type> 356 357This directive names a backend-specific configuration entry. 358{{EX:<type>}} should be one of the 359supported backend types listed in Table 5.2. 360 361!block table; align=Center; coltags="EX,N"; \ 362 title="Table 5.2: Database Backends" 363Types Description 364asyncmeta Asynchronous Metadirectory backend 365config Slapd configuration backend 366dnssrv DNS SRV backend 367ldap Lightweight Directory Access Protocol (Proxy) backend 368ldif Lightweight Data Interchange Format backend 369mdb Memory-Mapped DB backend 370meta Metadirectory backend 371monitor Monitor backend 372ndb MySQL NDB backend 373null Null backend 374passwd Provides read-only access to {{passwd}}(5) 375perl Perl Programmable backend 376relay Relay backend 377sock Socket backend 378sql SQL Programmable backend 379wt WiredTiger backend 380!endblock 381 382\Example: 383 384> olcBackend: mdb 385 386This marks the beginning of a new {{TERM:MDB}} backend 387definition. At present, only back-mdb implements any options 388of this type, so this setting is not needed for any other backends. 389 390 391H4: Sample Entry 392 393> dn: olcBackend=mdb,cn=config 394> objectClass: olcBackendConfig 395> olcBackend: mdb 396> olcBkMdbIdlExp: 16 397 398 399H3: Database-specific Directives 400 401Directives in this section are supported by every type of database. 402Database entries must have the {{EX:olcDatabaseConfig}} objectClass. 403 404H4: olcDatabase: [{<index>}]<type> 405 406This directive names a specific database instance. The numeric {<index>} may 407be provided to distinguish multiple databases of the same type. Usually the 408index can be omitted, and slapd will generate it automatically. 409{{EX:<type>}} should be one of the 410supported backend types listed in Table 5.2 or the {{EX:frontend}} type. 411 412The {{EX:frontend}} is a special database that is used to hold 413database-level options that should be applied to all the other 414databases. Subsequent database definitions may also override some 415frontend settings. 416 417The {{EX:config}} database is also special; both the {{EX:config}} and 418the {{EX:frontend}} databases are always created implicitly even if they 419are not explicitly configured, and they are created before any other 420databases. 421 422\Example: 423 424> olcDatabase: mdb 425 426This marks the beginning of a new {{TERM:MDB}} database instance. 427 428 429H4: olcAccess: to <what> [ by <who> [<accesslevel>] [<control>] ]+ 430 431This directive grants access (specified by <accesslevel>) to a 432set of entries and/or attributes (specified by <what>) by one or 433more requestors (specified by <who>). 434See the {{SECT:Access Control}} section of this guide for basic usage. 435 436!if 0 437More detailed discussion of this directive can be found in the 438{{SECT:Advanced Access Control}} chapter. 439!endif 440 441Note: If no {{EX:olcAccess}} directives are specified, the default 442access control policy, {{EX:to * by * read}}, allows all 443users (both authenticated and anonymous) read access. 444 445Note: Access controls defined in the frontend are appended to all 446other databases' controls. 447 448 449H4: olcReadonly { TRUE | FALSE } 450 451This directive puts the database into "read-only" mode. Any 452attempts to modify the database will return an "unwilling to 453perform" error. If set on a consumer, modifications sent by 454syncrepl will still occur. 455 456\Default: 457 458> olcReadonly: FALSE 459 460 461H4: olcRootDN: <DN> 462 463This directive specifies the DN that is not subject to 464access control or administrative limit restrictions for 465operations on this database. The DN need not refer to 466an entry in this database or even in the directory. The 467DN may refer to a SASL identity. 468 469Entry-based Example: 470 471> olcRootDN: cn=Manager,dc=example,dc=com 472 473SASL-based Example: 474 475> olcRootDN: uid=root,cn=example.com,cn=digest-md5,cn=auth 476 477See the {{SECT:SASL Authentication}} section for information on 478SASL authentication identities. 479 480 481H4: olcRootPW: <password> 482 483This directive can be used to specify a password for the DN for 484the rootdn (when the rootdn is set to a DN within the database). 485 486\Example: 487 488> olcRootPW: secret 489 490It is also permissible to provide a hash of the password in 491{{REF:RFC2307}} form. {{slappasswd}}(8) may be used to generate 492the password hash. 493 494\Example: 495 496> olcRootPW: {SSHA}ZKKuqbEKJfKSXhUbHG3fG8MDn9j1v4QN 497 498The hash was generated using the command {{EX:slappasswd -s secret}}. 499 500 501H4: olcSizeLimit: <integer> 502 503This directive specifies the maximum number of entries to return 504from a search operation. 505 506\Default: 507 508> olcSizeLimit: 500 509 510See the {{SECT:Limits}} section of this guide and slapd-config(5) 511for more details. 512 513 514H4: olcSuffix: <dn suffix> 515 516This directive specifies the DN suffix of queries that will be 517passed to this backend database. Multiple suffix lines can be 518given, and usually at least one is required for each database 519definition. (Some backend types, such as {{EX:frontend}} and 520{{EX:monitor}} use a hard-coded suffix which may not be overridden 521in the configuration.) 522 523\Example: 524 525> olcSuffix: dc=example,dc=com 526 527Queries with a DN ending in "dc=example,dc=com" 528will be passed to this backend. 529 530Note: When the backend to pass a query to is selected, slapd 531looks at the suffix value(s) in each database definition in the 532order in which they were configured. Thus, if one database suffix is a 533prefix of another, it must appear after it in the configuration. 534 535 536H4: olcSyncrepl 537 538> olcSyncrepl: rid=<replica ID> 539> provider=ldap[s]://<hostname>[:port] 540> [type=refreshOnly|refreshAndPersist] 541> [interval=dd:hh:mm:ss] 542> [retry=[<retry interval> <# of retries>]+] 543> searchbase=<base DN> 544> [filter=<filter str>] 545> [scope=sub|one|base] 546> [attrs=<attr list>] 547> [attrsonly] 548> [sizelimit=<limit>] 549> [timelimit=<limit>] 550> [schemachecking=on|off] 551> [bindmethod=simple|sasl] 552> [binddn=<DN>] 553> [saslmech=<mech>] 554> [authcid=<identity>] 555> [authzid=<identity>] 556> [credentials=<passwd>] 557> [realm=<realm>] 558> [secprops=<properties>] 559> [starttls=yes|critical] 560> [tls_cert=<file>] 561> [tls_key=<file>] 562> [tls_cacert=<file>] 563> [tls_cacertdir=<path>] 564> [tls_reqcert=never|allow|try|demand] 565> [tls_cipher_suite=<ciphers>] 566> [tls_crlcheck=none|peer|all] 567> [logbase=<base DN>] 568> [logfilter=<filter str>] 569> [syncdata=default|accesslog|changelog] 570 571 572This directive specifies the current database as a consumer of the 573provider content by establishing the current {{slapd}}(8) as a 574replication consumer site running a syncrepl replication engine. 575The provider database is located at the provider site 576specified by the {{EX:provider}} parameter. The consumer database is 577kept up-to-date with the provider content using the LDAP Content 578Synchronization protocol. See {{REF:RFC4533}} 579for more information on the protocol. 580 581The {{EX:rid}} parameter is used for identification of the current 582{{EX:syncrepl}} directive within the replication consumer server, 583where {{EX:<replica ID>}} uniquely identifies the syncrepl specification 584described by the current {{EX:syncrepl}} directive. {{EX:<replica ID>}} 585is non-negative and is no more than three decimal digits in length. 586 587The {{EX:provider}} parameter specifies the replication provider site 588containing the provider content as an LDAP URI. The {{EX:provider}} 589parameter specifies a scheme, a host and optionally a port where the 590provider slapd instance can be found. Either a domain name or IP 591address may be used for <hostname>. Examples are 592{{EX:ldap://provider.example.com:389}} or {{EX:ldaps://192.168.1.1:636}}. 593If <port> is not given, the standard LDAP port number (389 or 636) is used. 594Note that the syncrepl uses a consumer-initiated protocol, and hence its 595specification is located on the consumer. 596 597The content of the syncrepl consumer is defined using a search 598specification as its result set. The consumer slapd will 599send search requests to the provider slapd according to the search 600specification. The search specification includes {{EX:searchbase}}, 601{{EX:scope}}, {{EX:filter}}, {{EX:attrs}}, {{EX:attrsonly}}, 602{{EX:sizelimit}}, and {{EX:timelimit}} parameters as in the normal 603search specification. The {{EX:searchbase}} parameter has no 604default value and must always be specified. The {{EX:scope}} defaults 605to {{EX:sub}}, the {{EX:filter}} defaults to {{EX:(objectclass=*)}}, 606{{EX:attrs}} defaults to {{EX:"*,+"}} to replicate all user and operational 607attributes, and {{EX:attrsonly}} is unset by default. Both {{EX:sizelimit}} 608and {{EX:timelimit}} default to "unlimited", and only positive integers 609or "unlimited" may be specified. 610 611The {{TERM[expand]LDAP Sync}} protocol has two operation 612types: {{EX:refreshOnly}} and {{EX:refreshAndPersist}}. 613The operation type is specified by the {{EX:type}} parameter. 614In the {{EX:refreshOnly}} operation, the next synchronization search operation 615is periodically rescheduled at an interval time after each 616synchronization operation finishes. The interval is specified 617by the {{EX:interval}} parameter. It is set to one day by default. 618In the {{EX:refreshAndPersist}} operation, a synchronization search 619remains persistent in the provider {{slapd}} instance. Further updates to the 620provider will generate {{EX:searchResultEntry}} to the consumer slapd 621as the search responses to the persistent synchronization search. 622 623If an error occurs during replication, the consumer will attempt to reconnect 624according to the retry parameter which is a list of the <retry interval> 625and <# of retries> pairs. For example, retry="60 10 300 3" lets the consumer 626retry every 60 seconds for the first 10 times and then retry every 300 seconds 627for the next three times before stop retrying. + in <# of retries> means 628indefinite number of retries until success. 629 630The schema checking can be enforced at the LDAP Sync consumer site 631by turning on the {{EX:schemachecking}} parameter. 632If it is turned on, every replicated entry will be checked for its 633schema as the entry is stored on the consumer. 634Every entry in the consumer should contain those attributes 635required by the schema definition. 636If it is turned off, entries will be stored without checking 637schema conformance. The default is off. 638 639The {{EX:binddn}} parameter gives the DN to bind as for the 640syncrepl searches to the provider slapd. It should be a DN 641which has read access to the replication content in the 642provider database. 643 644The {{EX:bindmethod}} is {{EX:simple}} or {{EX:sasl}}, 645depending on whether simple password-based authentication or 646{{TERM:SASL}} authentication is to be used when connecting 647to the provider {{slapd}} instance. 648 649Simple authentication should not be used unless adequate data 650integrity and confidentiality protections are in place (e.g. TLS 651or IPsec). Simple authentication requires specification of {{EX:binddn}} 652and {{EX:credentials}} parameters. 653 654SASL authentication is generally recommended. SASL authentication 655requires specification of a mechanism using the {{EX:saslmech}} parameter. 656Depending on the mechanism, an authentication identity and/or 657credentials can be specified using {{EX:authcid}} and {{EX:credentials}}, 658respectively. The {{EX:authzid}} parameter may be used to specify 659an authorization identity. 660 661The {{EX:realm}} parameter specifies a realm which a certain 662mechanisms authenticate the identity within. The {{EX:secprops}} 663parameter specifies Cyrus SASL security properties. 664 665The {{EX:starttls}} parameter specifies use of the StartTLS extended 666operation to establish a TLS session before authenticating to the provider. 667If the {{EX:critical}} argument is supplied, the session will be aborted 668if the StartTLS request fails. Otherwise the syncrepl session continues 669without TLS. The tls_reqcert setting defaults to {{EX:"demand"}} and the 670other TLS settings default to the same as the main slapd TLS settings. 671 672Rather than replicating whole entries, the consumer can query logs 673of data modifications. This mode of operation is referred to as 674{{delta syncrepl}}. In addition to the above parameters, the 675{{EX:logbase}} and {{EX:logfilter}} parameters must be set appropriately 676for the log that will be used. The {{EX:syncdata}} parameter must 677be set to either {{EX:"accesslog"}} if the log conforms to the 678{{slapo-accesslog}}(5) log format, or {{EX:"changelog"}} if the log 679conforms to the obsolete {{changelog}} format. If the {{EX:syncdata}} 680parameter is omitted or set to {{EX:"default"}} then the log 681parameters are ignored. 682 683The {{syncrepl}} replication mechanism is supported by the {{mdb}} 684backend. 685 686See the {{SECT:LDAP Sync Replication}} chapter of this guide for 687more information on how to use this directive. 688 689 690H4: olcTimeLimit: <integer> 691 692This directive specifies the maximum number of seconds (in real 693time) slapd will spend answering a search request. If a 694request is not finished in this time, a result indicating an 695exceeded timelimit will be returned. 696 697\Default: 698 699> olcTimeLimit: 3600 700 701See the {{SECT:Limits}} section of this guide and slapd-config(5) 702for more details. 703 704 705H4: olcUpdateref: <URL> 706 707This directive is only applicable in a {{replica}} (or {{shadow}}) 708{{slapd}}(8) instance. It 709specifies the URL to return to clients which submit update 710requests upon the replica. 711If specified multiple times, each {{TERM:URL}} is provided. 712 713\Example: 714 715> olcUpdateref: ldap://provider.example.net 716 717 718H4: Sample Entries 719 720>dn: olcDatabase=frontend,cn=config 721>objectClass: olcDatabaseConfig 722>objectClass: olcFrontendConfig 723>olcDatabase: frontend 724>olcReadOnly: FALSE 725> 726>dn: olcDatabase=config,cn=config 727>objectClass: olcDatabaseConfig 728>olcDatabase: config 729>olcRootDN: cn=Manager,dc=example,dc=com 730 731 732H3: MDB Backend Directives 733 734Directives in this category only apply to the {{TERM:MDB}} 735database backend. They will apply to all "database mdb" 736instances in the configuration. For a complete reference 737of MDB backend configuration directives, see {{slapd-mdb}}(5). 738 739H4: olcBkMdbIdlExp <exponent> 740 741Specify a power of 2 for the maximum size of an index slot. 742The default is 16, yielding a maximum slot size of 2^16 or 65536. 743The specified value must be in the range of 16-31. 744 745This setting helps with the case where certain search filters are 746slow to return results due to an index slot having collapsed to a 747range value. This occurs when the number of candidate entries that 748match the filter for the index slot exceed the configured slot size. 749 750If this setting is decreased on a server with existing {{TERM:MDB}} 751databases, each db will immediately need its indices to be rebuilt 752while slapd is offline with the "slapindex -q -t" command. 753 754If this setting is increased on a server with existing {{TERM:MDB}} 755databases, each db will need its indices rebuilt to take advantage 756of the change for indices that have already been converted to ranges. 757 758 759H3: MDB Database Directives 760 761Directives in this category apply to the {{TERM:MDB}} 762database backend. 763They are used in an olcDatabase entry in addition to the generic 764database directives defined above. For a complete reference 765of MDB configuration directives, see {{slapd-mdb}}(5). In 766addition to the {{EX:olcDatabaseConfig}} objectClass, MDB 767database entries must have the {{EX:olcMdbConfig}} objectClass. 768 769 770H4: olcDbDirectory: <directory> 771 772This directive specifies the directory where the MDB files 773containing the database and associated indices live. 774 775\Default: 776 777> olcDbDirectory: /usr/local/var/openldap-data 778 779 780H4: olcDbCheckpoint: <kbyte> <min> 781 782This directive specifies the frequency for flushing the database disk 783buffers. This directive is only needed if the {{olcDbNoSync}} option is 784{{EX:TRUE}}. 785The checkpoint will occur if either <kbyte> data has been written or 786<min> minutes have passed since the last checkpoint. Both arguments default 787to zero, in which case they are ignored. When the <min> argument is 788non-zero, an internal task will run every <min> minutes to perform the 789checkpoint. Note: currently the _kbyte_ setting is unimplemented. 790 791\Example: 792 793> olcDbCheckpoint: 1024 10 794 795 796H4: olcDbEnvFlags: {nosync,nometasync,writemap,mapasync,nordahead} 797 798This option specifies flags for finer-grained control of the LMDB library's 799operation. 800 801* {{F:nosync}}: This is exactly the same as the dbnosync directive. 802 803* {{F:nometasync}}: Flush the data on a commit, but skip the sync of the meta 804page. This mode is slightly faster than doing a full sync, but can 805potentially lose the last committed transaction if the operating system 806crashes. If both nometasync and nosync are set, the nosync flag takes 807precedence. 808 809* {{F:writemap}}: Use a writable memory map instead of just read-only. This 810speeds up write operations but makes the database vulnerable to corruption in 811case any bugs in slapd cause stray writes into the mmap region. 812 813* {{F:mapasync}}: When using a writable memory map and performing flushes on 814each commit, use an asynchronous flush instead of a synchronous flush (the 815default). This option has no effect if writemap has not been set. It also has 816no effect if nosync is set. 817 818* {{F:nordahead}}: Turn off file readahead. Usually the OS performs readahead 819on every read request. This usually boosts read performance but can be 820harmful to random access read performance if the system's memory is full and 821the DB is larger than RAM. This option is not implemented on Windows. 822 823 824H4: olcDbIndex: {<attrlist> | default} [pres,eq,approx,sub,none] 825 826This directive specifies the indices to maintain for the given 827attribute. If only an {{EX:<attrlist>}} is given, the default 828indices are maintained. The index keywords correspond to the 829common types of matches that may be used in an LDAP search filter. 830 831\Example: 832 833> olcDbIndex: default pres,eq 834> olcDbIndex: uid 835> olcDbIndex: cn,sn pres,eq,sub 836> olcDbIndex: objectClass eq 837 838The first line sets the default set of indices to maintain to 839present and equality. The second line causes the default (pres,eq) 840set of indices to be maintained for the {{EX:uid}} attribute type. 841The third line causes present, equality, and substring indices to 842be maintained for {{EX:cn}} and {{EX:sn}} attribute types. The 843fourth line causes an equality index for the {{EX:objectClass}} 844attribute type. 845 846There is no index keyword for inequality matches. Generally these 847matches do not use an index. However, some attributes do support 848indexing for inequality matches, based on the equality index. 849 850A substring index can be more explicitly specified as {{EX:subinitial}}, 851{{EX:subany}}, or {{EX:subfinal}}, corresponding to the three 852possible components 853of a substring match filter. A subinitial index only indexes 854substrings that appear at the beginning of an attribute value. 855A subfinal index only indexes substrings that appear at the end 856of an attribute value, while subany indexes substrings that occur 857anywhere in a value. 858 859Note that by default, setting an index for an attribute also 860affects every subtype of that attribute. E.g., setting an equality 861index on the {{EX:name}} attribute causes {{EX:cn}}, {{EX:sn}}, and every other 862attribute that inherits from {{EX:name}} to be indexed. 863 864By default, no indices are maintained. It is generally advised 865that minimally an equality index upon objectClass be maintained. 866 867> olcDbIndex: objectClass eq 868 869Additional indices should be configured corresponding to the 870most common searches that are used on the database. 871Presence indexing should not be configured for an attribute 872unless the attribute occurs very rarely in the database, and 873presence searches on the attribute occur very frequently during 874normal use of the directory. Most applications don't use presence 875searches, so usually presence indexing is not very useful. 876 877If this setting is changed while slapd is running, an internal task 878will be run to generate the changed index data. All server operations 879can continue as normal while the indexer does its work. If slapd is 880stopped before the index task completes, indexing will have to be 881manually completed using the slapindex tool. 882 883 884H4: olcDbMaxEntrySize: <bytes> 885 886Specify the maximum size of an entry in bytes. Attempts to store 887an entry larger than this size will be rejected with the error 888LDAP_ADMINLIMIT_EXCEEDED. The default is 0, which is unlimited. 889 890 891H4: olcDbMaxReaders: <integer> 892 893This directive specifies the maximum number of threads that may have 894concurrent read access to the database. Tools such as slapcat count as a 895single thread, in addition to threads in any active slapd processes. The 896default is 126. 897 898 899H4: olcDbMaxSize: <bytes> 900 901This directive specifies the maximum size of the database in bytes. A memory 902map of this size is allocated at startup time and the database will not be 903allowed to grow beyond this size. The default is 10485760 bytes (10MB). This 904setting may be changed upward if the configured limit needs to be increased. 905 906Note: It is important to set this to as large a value as possible, (relative 907to anticipated growth of the actual data over time) since growing the size 908later may not be practical when the system is under heavy load. 909 910 911H4: olcDbMode: { <octal> | <symbolic> } 912 913This directive specifies the file protection mode that newly 914created database index files should have. This can be in the form 915{{EX:0600}} or {{EX:-rw-------}} 916 917\Default: 918 919> olcDbMode: 0600 920 921 922H4: olcDbMultival: { <attrlist> | default } <integer> hi,<integer> lo 923 924Specify the number of values for which a multivalued attribute is 925stored in a separate table. Normally entries are stored as a single 926blob inside the database. When an entry gets very large or contains 927attributes with a very large number of values, modifications on that 928entry may get very slow. Splitting the large attributes out to a separate 929table can improve the performance of modification operations. 930The threshold is specified as a pair of integers. If the number of 931values exceeds the hi threshold the values will be split out. If 932a modification deletes enough values to bring an attribute below 933the lo threshold the values will be removed from the separate 934table and merged back into the main entry blob. 935The threshold can be set for a specific list of attributes, or 936the default can be configured for all other attributes. 937The default value for both hi and lo thresholds is UINT_MAX, which keeps 938all attributes in the main blob. 939 940In addition to increasing write performance of operations the use of 941multival can also decrease fragmentation of the primary {{TERM:MDB}} database. 942 943 944H4: olcDbRtxnsize: <entries> 945 946This directive specifies the maximum number of entries to process in a single 947read transaction when executing a large search. Long-lived read transactions 948prevent old database pages from being reused in write transactions, and so 949can cause significant growth of the database file when there is heavy write 950traffic. This setting causes the read transaction in large searches to be 951released and reacquired after the given number of entries has been read, to 952give writers the opportunity to reclaim old database pages. The default is 95310000. 954 955 956H4: olcDbSearchStack: <integer> 957 958Specify the depth of the stack used for search filter evaluation. 959Search filters are evaluated on a stack to accommodate nested {{EX:AND}} / 960{{EX:OR}} clauses. An individual stack is allocated for each server thread. 961The depth of the stack determines how complex a filter can be evaluated 962without requiring any additional memory allocation. Filters that are 963nested deeper than the search stack depth will cause a separate stack to 964be allocated for that particular search operation. These separate allocations 965can have a major negative impact on server performance, but specifying 966too much stack will also consume a great deal of memory. Each search 967uses 512K bytes per level on a 32-bit machine, or 1024K bytes per level 968on a 64-bit machine. The default stack depth is 16, thus 8MB or 16MB 969per thread is used on 32 and 64 bit machines, respectively. Also the 970512KB size of a single stack slot is set by a compile-time constant which 971may be changed if needed; the code must be recompiled for the change 972to take effect. 973 974\Default: 975 976> olcDbSearchStack: 16 977 978 979H4: olcDbNosync: { TRUE | FALSE } 980 981This directive causes on-disk database contents to not be immediately 982synchronized with in memory changes upon change. Setting this option 983to {{EX:TRUE}} may improve performance at the expense of data integrity. 984 985 986H4: Sample Entry 987 988>dn: olcDatabase=mdb,cn=config 989>objectClass: olcDatabaseConfig 990>objectClass: olcMdbConfig 991>olcDatabase: mdb 992>olcSuffix: dc=example,dc=com 993>olcDbDirectory: /usr/local/var/openldap-data 994>olcDbIndex: objectClass eq 995 996 997H2: Configuration Example 998 999The following is an example configuration, interspersed 1000with explanatory text. It defines two databases to handle 1001different parts of the {{TERM:X.500}} tree; both are {{TERM:MDB}} 1002database instances. The line numbers shown are provided for 1003reference only and are not included in the actual file. First, the 1004global configuration section: 1005 1006E: 1. # example config file - global configuration entry 1007E: 2. dn: cn=config 1008E: 3. objectClass: olcGlobal 1009E: 4. cn: config 1010E: 5. olcReferral: ldap://root.openldap.org 1011E: 6. 1012 1013Line 1 is a comment. Lines 2-4 identify this as the global 1014configuration entry. 1015The {{EX:olcReferral:}} directive on line 5 1016means that queries not local to one of the databases defined 1017below will be referred to the LDAP server running on the 1018standard port (389) at the host {{EX:root.openldap.org}}. 1019Line 6 is a blank line, indicating the end of this entry. 1020 1021E: 7. # internal schema 1022E: 8. dn: cn=schema,cn=config 1023E: 9. objectClass: olcSchemaConfig 1024E: 10. cn: schema 1025E: 11. 1026 1027Line 7 is a comment. Lines 8-10 identify this as the root of 1028the schema subtree. The actual schema definitions in this entry 1029are hardcoded into slapd so no additional attributes are specified here. 1030Line 11 is a blank line, indicating the end of this entry. 1031 1032E: 12. # include the core schema 1033E: 13. include: file:///usr/local/etc/openldap/schema/core.ldif 1034E: 14. 1035 1036Line 12 is a comment. Line 13 is an LDIF include directive which 1037accesses the {{core}} schema definitions in LDIF format. Line 14 1038is a blank line. 1039 1040Next comes the database definitions. The first database is the 1041special {{EX:frontend}} database whose settings are applied globally 1042to all the other databases. 1043 1044E: 15. # global database parameters 1045E: 16. dn: olcDatabase=frontend,cn=config 1046E: 17. objectClass: olcDatabaseConfig 1047E: 18. olcDatabase: frontend 1048E: 19. olcAccess: to * by * read 1049E: 20. 1050 1051Line 15 is a comment. Lines 16-18 identify this entry as the global 1052database entry. Line 19 is a global access control. It applies to all 1053entries (after any applicable database-specific access controls). 1054Line 20 is a blank line. 1055 1056The next entry defines the config backend. 1057 1058E: 21. # set a rootpw for the config database so we can bind. 1059E: 22. # deny access to everyone else. 1060E: 23. dn: olcDatabase=config,cn=config 1061E: 24. objectClass: olcDatabaseConfig 1062E: 25. olcDatabase: config 1063E: 26. olcRootPW: {SSHA}XKYnrjvGT3wZFQrDD5040US592LxsdLy 1064E: 27. olcAccess: to * by * none 1065E: 28. 1066 1067Lines 21-22 are comments. Lines 23-25 identify this entry as the config 1068database entry. Line 26 defines the {{super-user}} password for this 1069database. (The DN defaults to {{"cn=config"}}.) Line 27 denies all access 1070to this database, so only the super-user will be able to access it. (This 1071is already the default access on the config database. It is just listed 1072here for illustration, and to reiterate that unless a means to authenticate 1073as the super-user is explicitly configured, the config database will be 1074inaccessible.) 1075 1076Line 28 is a blank line. 1077 1078The next entry defines an MDB backend that will handle queries for things 1079in the "dc=example,dc=com" portion of the tree. Indices are to be maintained 1080for several attributes, and the {{EX:userPassword}} attribute is to be 1081protected from unauthorized access. 1082 1083E: 29. # MDB definition for example.com 1084E: 30. dn: olcDatabase=mdb,cn=config 1085E: 31. objectClass: olcDatabaseConfig 1086E: 32. objectClass: olcMdbConfig 1087E: 33. olcDatabase: mdb 1088E: 34. olcSuffix: dc=example,dc=com 1089E: 35. olcDbDirectory: /usr/local/var/openldap-data 1090E: 36. olcRootDN: cn=Manager,dc=example,dc=com 1091E: 37. olcRootPW: secret 1092E: 38. olcDbIndex: uid pres,eq 1093E: 39. olcDbIndex: cn,sn pres,eq,approx,sub 1094E: 40. olcDbIndex: objectClass eq 1095E: 41. olcAccess: to attrs=userPassword 1096E: 42. by self write 1097E: 43. by anonymous auth 1098E: 44. by dn.base="cn=Admin,dc=example,dc=com" write 1099E: 45. by * none 1100E: 46. olcAccess: to * 1101E: 47. by self write 1102E: 48. by dn.base="cn=Admin,dc=example,dc=com" write 1103E: 49. by * read 1104E: 50. 1105 1106Line 29 is a comment. Lines 30-33 identify this entry as a MDB database 1107configuration entry. Line 34 specifies the DN suffix 1108for queries to pass to this database. Line 35 specifies the directory 1109in which the database files will live. 1110 1111Lines 36 and 37 identify the database {{super-user}} entry and associated 1112password. This entry is not subject to access control or size or 1113time limit restrictions. 1114 1115Lines 38 through 40 indicate the indices to maintain for various 1116attributes. 1117 1118Lines 41 through 49 specify access control for entries in this 1119database. For all applicable entries, the {{EX:userPassword}} attribute is writable 1120by the entry itself and by the "admin" entry. It may be used for 1121authentication/authorization purposes, but is otherwise not readable. 1122All other attributes are writable by the entry and the "admin" 1123entry, but may be read by all users (authenticated or not). 1124 1125Line 50 is a blank line, indicating the end of this entry. 1126 1127The next entry defines another 1128MDB database. This one handles queries involving the 1129{{EX:dc=example,dc=net}} subtree but is managed by the same entity 1130as the first database. Note that without line 60, the read access 1131would be allowed due to the global access rule at line 19. 1132 1133E: 51. # MDB definition for example.net 1134E: 52. dn: olcDatabase=mdb,cn=config 1135E: 53. objectClass: olcDatabaseConfig 1136E: 54. objectClass: olcMdbConfig 1137E: 55. olcDatabase: mdb 1138E: 56. olcSuffix: dc=example,dc=net 1139E: 57. olcDbDirectory: /usr/local/var/openldap-data-net 1140E: 58. olcRootDN: cn=Manager,dc=example,dc=com 1141E: 59. olcDbIndex: objectClass eq 1142E: 60. olcAccess: to * by users read 1143 1144 1145H2: Converting old style {{slapd.conf}}(5) file to {{cn=config}} format 1146 1147Before converting to the {{cn=config}} format you should make sure that the 1148config backend is properly configured in your existing config file. While 1149the config backend is always present inside slapd, by default it is only 1150accessible by its rootDN, and there are no default credentials assigned 1151so unless you explicitly configure a means to authenticate to it, it will be 1152unusable. 1153 1154If you do not already have a {{EX:database config}} section, add something 1155like this to the end of {{EX:slapd.conf}} 1156 1157> database config 1158> rootpw VerySecret 1159 1160Note: Since the config backend can be used to load arbitrary code into the 1161slapd process, it is extremely important to carefully guard whatever 1162credentials are used to access it. Since simple passwords are vulnerable to 1163password guessing attacks, it is usually better to omit the rootpw and only 1164use SASL authentication for the config rootDN. 1165 1166An existing {{slapd.conf}}(5) file can be converted to the new format using 1167{{slaptest}}(8) or any of the slap tools: 1168 1169> slaptest -f /usr/local/etc/openldap/slapd.conf -F /usr/local/etc/openldap/slapd.d 1170 1171Test that you can access entries under {{EX:cn=config}} using the 1172default {{rootdn}} and the {{rootpw}} configured above: 1173 1174> ldapsearch -x -D cn=config -w VerySecret -b cn=config 1175 1176You can then discard the old {{slapd.conf}}(5) file. Make sure to launch 1177{{slapd}}(8) with the {{-F}} option to specify the configuration directory 1178if you are not using the default directory path. 1179 1180Note: When converting from the slapd.conf format to slapd.d format, any 1181included files will also be integrated into the resulting configuration 1182database. 1183 1184 1185H2: Recovering from a broken configuration 1186 1187If the server using {{cn=config}} does not start, either because the 1188configuration does not represent the current version or because it has been 1189corrupted, these actions are available, in the order of decreasing preference. 1190 1191Make sure you have made a backup of the "broken" version before you attempt any 1192of these: 1193 1194 1195H3: Generate an ldif version of the configuration database and reload from that 1196 1197Most of the time, the configuration can be parsed and a text version generated 1198with {{slapcat}}(8): 1199 1200> slapcat -F /usr/local/etc/openldap/slapd.d -n0 -l extracted_config.ldif 1201 1202After you have backed up and removed the old configuration database contents, 1203this output ldif can be hand-edited to adjust or remove the offending entries 1204and imported again: 1205 1206> slapadd -F /usr/local/etc/openldap/slapd.d -l updated_config.ldif 1207> slaptest -F /usr/local/etc/openldap/slapd.d 1208 1209 1210H3: Modify config in-place 1211 1212If the configuration can be parsed and you know exactly what you need to do, 1213you can use {{slapmodify}}(8) to effect the required changes directly: 1214 1215> slapmodify -F /usr/local/etc/openldap/slapd.d 1216> dn: ..., cn=config 1217> changetype: ... 1218> ... 1219 1220 1221H3: Recover with plain back-ldif 1222 1223If the configuration contains items that {{slapd}}(8) cannot process as a 1224{{cn=config}} database at all, the last resort is to disable schema checking 1225and operate on it as a regular back-ldif database. This might cease to work 1226with future versions of OpenLDAP without notice, attempt this only when all of 1227the above fail. 1228 1229First, create a directory to serve as the hosting DB and create the structure: 1230 1231> mkdir ./recovery ./recovery/cn=recovery 1232> cp /usr/local/etc/openldap/slapd.d/cn=config.ldif ./recovery/cn=recovery 1233> cp -r /usr/local/etc/openldap/slapd.d/cn=config ./recovery/cn=recovery 1234 1235Or, if you have already backed up your old configuration, you can symlink it 1236into place: 1237 1238> mkdir ./recovery 1239> ln -s /usr/local/etc/openldap/slapd.d ./recovery/cn=recovery 1240 1241Next, create a trivial {{slapd.conf}}(5) to access the new database: 1242 1243> database ldif 1244> suffix cn=recovery 1245> directory ./recovery/ 1246 1247Note the change of suffix, {{EX:cn=config}} is hardcoded to correspond to an 1248active config database, so we have to home it one level deeper - at 1249{{EX:cn=config,cn=recovery}}. 1250 1251Now you can use {{slapmodify}}(8) to modify the database, it is most likely you 1252will need to run with schema checking disabled: 1253 1254> slapmodify -f ./recovery.conf -s 1255 1256You can test the validity of your config with {{slaptest}}(8): 1257 1258> slaptest -F ./recovery/cn=recovery 1259 1260And generate a full ldif with {{slapcat}}(8): 1261 1262> slapcat -F ./recovery/cn=recovery -n0 1263
