# $OpenLDAP$
-# Copyright 1999-2000, The OpenLDAP Foundation, All Rights Reserved.
+# Copyright 1999-2003, 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>
H4: replica
-> replica host=<hostname>[:<port>]
-> [bindmethod={ simple | kerberos | sasl }]
+> replica
uri=ldap[s]://<hostname>[:<port>] | host=<hostname>[:<port>]
+> [bindmethod={simple|kerberos|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.
+given, the standard LDAP port number (389 or 636) is used.
+
+{{EX:host}} is deprecated in favor of the {{EX:uri}} parameter.
-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.
+{{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:kerberos}} or {{EX:sasl}},
depending on whether simple password-based authentication or Kerberos
{{EX:srvtab}} 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]
+> [updatedn=<DN>]
+> [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 syncrepl search specification has
+the same value syntax and the same default values as in the
+{{ldapsearch}}(1) client search tool.
+
+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 5 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:updatedn}} parameter specifies the DN in the consumer site
+which is allowed to make changes to the replica. This DN is used
+locally by the syncrepl engine when updating the replica with the
+entries received from the provider site by using the internal
+operation mechanism. The update of the replica content is subject
+to the access control privileges of the DN. The DN should have
+read/write access to the replica database. Generally, this DN
+{{should not}} be the same as {{EX:rootdn}}.
+
+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 integrity
+and privacy 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
subsequent "backend" or "database" line. For a complete reference
of BDB configuration directives, see {{slapd-bdb}}(5).
+
H4: directory <directory>
This directive specifies the directory where the BDB files
> directory /usr/local/var/openldap-data
+H4: sessionlog <sid> <limit>
+
+This directive specifies a session log store in the syncrepl
+replication provider server which contains information on
+the entries that have been scoped out of the replication
+content identified by {{EX:<sid>}}.
+The first syncrepl search request having the same {{EX:<sid>}} value
+in the cookie establishes the session log store in the provider server.
+The number of the entries in the session log store is limited
+by {{EX:<limit>}}. Excessive entries are removed from the store
+in the FIFO order. Both {{EX:<sid>}} and {{EX:<limit>}} are
+non-negative integers. {{EX:<sid>}} has no more than three decimal digits.
+
+The LDAP Content Synchronization operation that falls into a pre-existing
+session can use the session log store in order to reduce the amount
+of synchronization traffic. If the replica is not so outdated that
+it can be made up-to-date by the information in the session store,
+the provider slapd will send the consumer slapd the identities of the
+scoped-out entries together with the in-scope entries added to or
+modified within the replication content. If the replica status is
+outdated too much and beyond the coverage of the history store,
+then the provider slapd will send the identities of the unchanged
+in-scope entries along with the changed in-scope entries.
+The consumer slapd will then remove those entries in the replica
+which are not identified as present in the provider content.
+
+
H3: LDBM Database Directives
Directives in this category only apply to a {{TERM:LDBM}} database.
> [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
the target entry's {{normalized DN}}. (The second form is not
discussed further in this document.) The third form is used to
-select entries which are within the requested scope of DN.
+select entries which are within the requested scope of DN. The
+<DN> is a string representation of the Distinguished Name, as
+described in {{REF:RFC2253}}.
The scope can be either {{EX:base}}, {{EX:one}}, {{EX:subtree}},
or {{EX:children}}. Where {{EX:base}} matches only the entry with
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 parent's {{EX:children}} attribute.
-To rename an entry, the subject must have {{EX:write}} access to
-both the old parent's and new parent's {{EX:children}} attributes.
-The complete examples at the end of this section should help clear
-things up.
+{{EX:write}} access to the entry's {{EX:entry}} attribute AND must
+have {{EX:write}} access to the entry's parent's {{EX:children}}
+attribute. To rename an entry, the subject must have {{EX:write}}
+access to entry's {{EX:entry}} attribute AND have {{EX:write}}
+access to both the old parent's and new parent's {{EX:children}}
+attributes. The complete examples at the end of this section should
+help clear things up.
Lastly, there is a special entry selector {{EX:"*"}} that is used to
select any entry. It is used when no other {{EX:<what>}}
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
> access to dn.subtree="dc=example,dc=com" attr=homePhone
> by self write
> by dn.children=dc=example,dc=com" search
-> by domain=.*\.example\.com read
+> 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
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
projects / openldap / blobdiff