# $OpenLDAP$
-# Copyright 1999-2000, The OpenLDAP Foundation, All Rights Reserved.
+# Copyright 1999-2007 The OpenLDAP Foundation, All Rights Reserved.
# COPYING RESTRICTIONS APPLY, see COPYRIGHT.
H1: The slapd Configuration File
Blank lines and comment lines beginning with a '{{EX:#}}' character
are ignored. If a line begins with white space, it is considered a
-continuation of the previous line. The general format of slapd.conf is
-as follows:
+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>
Types Description
bdb Berkeley DB transactional backend
dnssrv DNS SRV backend
+hdb Hierarchical variant of bdb backend
ldap Lightweight Directory Access Protocol (Proxy) backend
ldbm Lightweight DBM backend
meta Meta Directory backend
H4: replica
-> replica host=<hostname>[:<port>]
-> [bindmethod={ simple | kerberos | sasl }]
+> replica
uri=ldap[s]://<hostname>[:<port>] | host=<hostname>[:<port>]
+> [bindmethod={simple|sasl}]
> ["binddn=<DN>"]
-> [mech=<mech>]
+> [saslmech=<mech>]
> [authcid=<identity>]
> [authzid=<identity>]
> [credentials=<password>]
-> [srvtab=<filename>]
This directive specifies a replication site for this database. The
-{{EX:host=}} parameter specifies a host and optionally a port where
+{{EX:uri=}} parameter specifies a scheme, a host and optionally a port where
the slave slapd instance can be found. Either a domain name
or IP address may be used for <hostname>. If <port> is not
-given, the standard LDAP port number (389) is used.
-
-The {{EX:binddn=}} parameter gives the DN to bind as for updates to
-the slave slapd. It should be a DN which has read/write
-access to the slave slapd's database, typically given as a
-{{EX:rootdn}} in the slave's config file. It must also match the
-{{EX:updatedn}} directive in the slave slapd's config file. Since DNs are
-likely to contain embedded spaces, the entire {{EX:"binddn=<DN>"}}
-string should be enclosed in double quotes.
-
-The {{EX:bindmethod}} is {{EX:simple}} or {{EX:kerberos}} or {{EX:sasl}},
-depending on whether simple password-based authentication or Kerberos
-authentication or {{TERM:SASL}} authentication is to be used when connecting
-to the slave slapd.
-
-Simple authentication should not be used unless adequate integrity
-and privacy protections are in place (e.g. TLS or IPSEC). Simple
-authentication requires specification of {{EX:binddn}} and
-{{EX:credentials}} parameters.
-
-Kerberos authentication is deprecated in favor of SASL authentication
-mechanisms, in particular the {{EX:KERBEROS_V4}} and {{EX:GSSAPI}}
-mechanisms. Kerberos authentication requires {{EX:binddn}} and
-{{EX:srvtab}} parameters.
+given, the standard LDAP port number (389 or 636) is used.
+
+{{EX:host}} is deprecated in favor of the {{EX:uri}} parameter.
+
+{{EX:uri}} allows the replica LDAP server to be specified as an LDAP
+URI such as {{EX:ldap://slave.example.com:389}} or
+{{EX:ldaps://slave.example.com:636}}.
+
+The {{EX:binddn=}} parameter gives the DN to bind as for updates
+to the slave slapd. It should be a DN which has read/write access
+to the slave slapd's database. It must also match the {{EX:updatedn}}
+directive in the slave slapd's config file. Generally, this DN
+{{should not}} be the same as the {{EX:rootdn}} of the master
+database. Since DNs are likely to contain embedded spaces, the
+entire {{EX:"binddn=<DN>"}} string should be enclosed in double
+quotes.
+
+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 slave slapd.
+
+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:mech}} parameter.
+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
information on how to use this directive.
-H4: rootdn <dn>
+H4: rootdn <DN>
This directive specifies the DN that is not subject to
access control or administrative limit restrictions for
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: updatedn <dn>
+
+H4: syncrepl
+
+> syncrepl 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>]
+> [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>]
+
+
+This directive specifies the current database as a replica of the
+master content by establishing the current {{slapd}}(8) as a
+replication consumer site running a syncrepl replication engine.
+The master database is located at the replication provider site
+specified by the {{EX:provider}} parameter. The replica database is
+kept up-to-date with the master content using the LDAP Content
+Synchronization protocol. See {{EX:draft-zeilenga-ldup-sync-xx.txt}}
+({{a work in progress}}) 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 master 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 at the consumer site, whereas the {{EX:replica}}
+specification is located at the provider site. {{EX:syncrepl}} and
+{{EX:replica}} directives define two independent replication
+mechanisms. They do not represent the replication peers of each other.
+
+The content of the syncrepl replica 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: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 integers
+or "unlimited" may be specified.
+
+The LDAP Content Synchronization 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. Further updates to the
+master replica 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 into the replica content.
+Every entry in the replica 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
+master 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.
+
+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 syncrepl replication mechanism is supported by the
+three native backends: back-bdb, back-hdb, and back-ldbm.
+
+See the {{SECT:LDAP Sync Replication}} chapter of the admin guide
+for more information on how to use this directive.
+
+
+H4: updatedn <DN>
This directive is only applicable in a slave slapd. It specifies
the DN allowed to make changes to the replica. This may be the DN
> updateref ldap://master.example.net
-H3: BDB Database Directives
+H3: BDB and HDB Database Directives
-Directives in this category only apply to a {{TERM:BDB}} database.
-That is, they must follow a "database bdb" line and come before any
+Directives in this category only apply to both the {{TERM:BDB}}
+and the {{TERM:HDB}} database.
+That is, they must follow a "database bdb" or "database hdb" line
+and come before any
subsequent "backend" or "database" line. For a complete reference
-of BDB configuration directives, see {{slapd-bdb}}(5).
+of BDB/HDB configuration directives, see {{slapd-bdb}}(5).
+
H4: directory <directory>
> [filter=<ldapfilter>] [attrs=<attrlist>]
> <basic-style> ::= regex | exact
> <scope-style> ::= base | one | subtree | children
-> <attrlist> ::= <attr> | <attr> , <attrlist>
+> <attrlist> ::= <attr>
[val[.<basic-style>]=<regex>] | <attr> , <attrlist>
> <attr> ::= <attrname> | entry | children
> <who> ::= * | [anonymous | users | self
> | dn[.<basic-style>]=<regex> | dn.<scope-style>=<DN>]
> [aci=<attrname>]
> <access> ::= [self]{<level>|<priv>}
> <level> ::= none | auth | compare | search | read | write
-> <priv> ::= {=|+|-}{w|r|s|c|x}+
+> <priv> ::= {=|+|-}{w|r|s|c|x|0}+
> <control> ::= [stop | continue | break]
where the <what> part selects the entries and/or attributes to which
commonly selected in two ways: by DN and by filter. The following
qualifiers select entries by DN:
-> by *
-> by dn[.<basic-style>]=<regex>
-> by dn.<scope-style>=<DN>
+> to *
+> to dn[.<basic-style>]=<regex>
+> to dn.<scope-style>=<DN>
The first form is used to select all entries. The second form may
be used to select entries by matching a regular expression against
Entries may also be selected using a filter:
-> by filter=<ldap filter>
+> to filter=<ldap filter>
where <ldap filter> is a string representation of an LDAP
search filter, as described in {{REF:RFC2254}}. For example:
-> by filter=(objectClass=person)
+> to filter=(objectClass=person)
-Note that entries by be select by both DN and filter by
-include both qualifiers in the <what> clause.
+Note that entries may be selected by both DN and filter by
+including both qualifiers in the <what> clause.
-> by dn.one="ou=people,o=suffix" filter=(objectClass=person)
+> to dn.one="ou=people,o=suffix" filter=(objectClass=person)
Attributes within an entry are selected by including a comma-separated
list of attribute names in the <what> selector:
> attrs=<attribute list>
-There are two special {{psuedo}} attributes {{EX:entry}} and
-{{EX:children}}. To read (and hence return) an target entry, the
+A specific value of an attribute is selected by using a single
+attribute name and also using a value selector:
+
+> attrs=<attribute> val[.<style>]=<regex>
+
+There are two special {{pseudo}} attributes {{EX:entry}} and
+{{EX:children}}. To read (and hence return) a target entry, the
subject must have {{EX:read}} access to the target's {{entry}}
attribute. To add or delete an entry, the subject must have
{{EX:write}} access to the entry's {{EX:entry}} attribute AND must
The DN specifier behaves much like <what> clause DN specifiers.
-Other control factors are also supported.
-For example, a {{EX:<who>}} can be restricted by a
-regular expression matching the client's domain name:
-
-> domain=<regular expression>
-
-or by an entry listed in a DN-valued attribute in the entry to
-which the access applies:
+Other control factors are also supported. For example, a {{EX:<who>}}
+can be restricted by an entry listed in a DN-valued attribute in
+the entry to which the access applies:
> dnattr=<dn-valued attribute name>
access to a group entry to whoever is listed as the owner of
the group entry).
+Some factors may not be appropriate in all environments (or any).
+For example, the domain factor relies on IP to domain name lookups.
+As these can easily spoofed, the domain factor should not be avoided.
+
H3: The access to grant
!block table; colaligns="LRL"; coltags="EX,EX,N"; align=Center; \
title="Table 5.4: Access Levels"
Level Privileges Description
-none no access
+none =0 no access
auth =x needed to bind
compare =cx needed to compare
search =scx needed to apply search filters
H3: Access Control Examples
-The access control facility described above is quite powerful.
-This section shows some examples of its use. First, some
-simple examples:
+The access control facility described above is quite powerful. This
+section shows some examples of its use for descriptive purposes.
+
+A simple example:
> access to * by * read
> by anonymous auth
> by * read
-This directive allows users to modify their own entries, allows
-authenticate, and allows all others to read. Note that only the
-first {{EX:by <who>}} clause which matches applies. Hence, the
-anonymous users are granted {{EX:auth}}, not {{EX:read}}. The last
-clause could just as well have been "{{EX:by users read}}".
+This directive allows the user to modify their entry, allows anonymous
+to authentication against these entries, and allows all others to
+read these entries. Note that only the first {{EX:by <who>}} clause
+which matches applies. Hence, the anonymous users are granted
+{{EX:auth}}, not {{EX:read}}. The last clause could just as well
+have been "{{EX:by users read}}".
It is often desirable to restrict operations based upon the level
of protection in place. The following shows how security strength
This directive allows users to modify their own entries if security
protections have of strength 128 or better have been established,
-allows simple authentication and read access when 64 or better
-security protections have been established.
+allows authentication access to anonymous users, and read access
+when 64 or better security protections have been established. If
+client has not establish sufficient security protections, the
+implicit {{EX:by * none}} clause would be applied.
-The following example shows the use of a regular expression
-to select the entries by DN in two access directives where
-ordering is significant.
+The following example shows the use of a style specifiers to select
+the entries by DN in two access directives where ordering is
+significant.
> access to dn.children="dc=example,dc=com"
> by * search
shows the use of an attribute selector to grant access to a specific
attribute and various {{EX:<who>}} selectors.
-> access to dn.subtree="dc=example,dc=com" attr=homePhone
+> access to dn.subtree="dc=example,dc=com" attrs=homePhone
> by self write
-> by dn.children=dc=example,dc=com" search
-> by domain=.*\.example\.com read
+> by dn.children="dc=example,dc=com" search
+> by peername.regex=IP:10\..+ read
> access to dn.subtree="dc=example,dc=com"
> by self write
> by dn.children="dc=example,dc=com" search
excepting for authentication/authorization (which is always done
anonymously). The {{EX:homePhone}} attribute is writable by the
entry, searchable by entries under {{EX:example.com}}, readable by
-clients connecting from somewhere in the {{EX:example.com}} domain,
-and otherwise not readable (implicit {{EX:by * none}}). All other
-access is denied by the implicit {{EX:access to * by * none}}.
+clients connecting from network 10, and otherwise not readable
+(implicit {{EX:by * none}}). All other access is denied by the
+implicit {{EX:access to * by * none}}.
Sometimes it is useful to permit a particular DN to add or
remove itself from an attribute. For example, if you would like to
their own DN from the member attribute, you could accomplish
it with an access directive like this:
-> access to attr=member,entry
+> access to attrs=member,entry
> by dnattr=member selfwrite
The dnattr {{EX:<who>}} selector says that the access applies to
E: 10. rootpw secret
E: 11. # replication directives
E: 12. replogfile /usr/local/var/openldap/slapd.replog
-E: 13. replica host=slave1.example.com:389
+E: 13. replica uri=ldap://slave1.example.com:389
E: 14. binddn="cn=Replicator,dc=example,dc=com"
E: 15. bindmethod=simple credentials=secret
-E: 16. replica host=slave2.example.com
+E: 16. replica uri=ldaps://slave2.example.com:636
E: 17. binddn="cn=Replicator,dc=example,dc=com"
E: 18. bindmethod=simple credentials=secret
E: 19. # indexed attribute definitions
E: 21. index cn,sn,uid pres,eq,approx,sub
E: 22. index objectClass eq
E: 23. # database access control definitions
-E: 24. access to attr=userPassword
+E: 24. access to attrs=userPassword
E: 25. by self write
E: 26. by anonymous auth
E: 27. by dn.base="cn=Admin,dc=example,dc=com" write
projects / openldap / blobdiff