Added LDAP_FILTER_EXT case to filter_free()

[openldap] / doc / guide / admin / slapdconfig.sdf

diff --git a/doc/guide/admin/slapdconfig.sdf b/doc/guide/admin/slapdconfig.sdf
index c75d7b59667c50e9d5b4a6b4bcd87cd0ad070888..c37150ff616d586f582f9927701800c642160459 100644 (file)
--- a/doc/guide/admin/slapdconfig.sdf
+++ b/doc/guide/admin/slapdconfig.sdf
@@ -81,7 +81,7 @@ H3: Global Directives
 
 Directives described in this section apply to all backends
 and databases unless specifically overridden in a backend or
 
 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
+database definition.  Arguments that should be replaced

 by actual text are shown in brackets {{EX:<>}}.
 
 
 by actual text are shown in brackets {{EX:<>}}.
 
 


@@ -229,17 +229,30 @@ exceeded timelimit will be returned.
 
 H3: General Backend Directives
 
 
 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 definition.
+{{EX:<type>}} should be one of {{EX:ldbm}}, {{EX:shell}},
+{{EX:passwd}}, or other supported backend type.
+
+

 H3: General Database Directives
 
 H3: General Database Directives
 

-Directives in this section only apply to the database in which
+Directives in this section apply only to the database in which

 they are defined. They are supported by every type of database.
 
 they are defined. They are supported by every type of database.
 

-H4: database <databasetype>
+H4: database <type>

 
 This directive marks the beginning of a new database instance
 
 This directive marks the beginning of a new database instance

-definition. <databasetype> should be one of ldbm, shell, or
-passwd, depending on which backend will serve the
-database.
+definition.
+{{EX:<type>}} should be one of {{EX:ldbm}}, {{EX:shell}},
+{{EX:passwd}}, or other supported database type.

 
 \Example:
 
 
 \Example:
 


@@ -295,7 +308,7 @@ authentication requires specification of {{EX:binddn}} and
 {{EX:credentials}} parameters.
 
 Kerberos authentication is deprecated in favor of SASL authentication
 {{EX:credentials}} parameters.
 
 Kerberos authentication is deprecated in favor of SASL authentication

-mechanisms, in particular the {EX:KERBEROS_V4}} and {{EX:GSSAPI}}
+mechanisms, in particular the {{EX:KERBEROS_V4}} and {{EX:GSSAPI}}

 mechanisms.  Kerberos authentication requires {{EX:binddn}} and
 {{EX:srvtab}} parameters.
 
 mechanisms.  Kerberos authentication requires {{EX:binddn}} and
 {{EX:srvtab}} parameters.
 


@@ -306,8 +319,8 @@ credentials can be specified using {{EX:authcid}} and {{EX:credentials}}
 respectively.  The {{EX:authzid}} parameter may be used to specify
 an authorization identity.
 
 respectively.  The {{EX:authzid}} parameter may be used to specify
 an authorization identity.
 

-See the {{SECT:Replication}} chapter for more information on how to
-use this directive.
+See the chapter entitled {{SECT:Replication with slurpd}} for more
+information on how to use this directive.

 
 
 H4: replogfile <filename>
 
 
 H4: replogfile <filename>


@@ -320,8 +333,8 @@ However, you can also use it to generate a transaction log, if
 slurpd is not running. In this case, you will need to periodically
 truncate the file, since it will grow indefinitely otherwise.
 
 slurpd is not running. In this case, you will need to periodically
 truncate the file, since it will grow indefinitely otherwise.
 

-See the {{SECT:Replication}} chapter for more information on how to
-use this directive.
+See the chapter entitled {{SECT:Replication with slurpd}} for more
+information on how to use this directive.

 
 
 H4: rootdn <dn>
 
 
 H4: rootdn <dn>


@@ -334,7 +347,7 @@ identity.
 
 Entry-based Example:
 
 
 Entry-based Example:
 

->      rootdn "cn=Manager, dc=example, dc=com"
+>      rootdn "cn=Manager,dc=example,dc=com"

 
 SASL-based Example:
 
 
 SASL-based Example:
 


@@ -362,9 +375,9 @@ definition.
 
 \Example:
 
 
 \Example:
 

->      suffix "dc=example, dc=com"
+>      suffix "dc=example,dc=com"

 
 

-Queries with a DN ending in "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
 will be passed to this backend.
 
 Note: When the backend to pass a query to is selected, slapd


@@ -374,14 +387,14 @@ prefix of another, it must appear after it in the config file.
 
 H4: updatedn <dn>
 
 
 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
-the DN slurpd binds as when making changes to the replica or
-the DN associated with a SASL identity.
+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
+{{slurpd}}(8) binds as when making changes to the replica or the DN
+associated with a SASL identity.

 
 Entry-based Example:
 
 
 Entry-based Example:
 

->      updatedn "cn=Update Daemon, dc=example, dc=com"
+>      updatedn "cn=Update Daemon,dc=example,dc=com"

 
 SASL-based Example:
 
 
 SASL-based Example:
 


@@ -399,7 +412,7 @@ If specified multiple times, each {{TERM:URL}} is provided.
 
 \Example:
 
 
 \Example:
 

->      update  ldap://master.example.net
+>      updateref       ldap://master.example.net

 
 
 H3: LDBM Backend-Specific Directives
 
 
 H3: LDBM Backend-Specific Directives


@@ -462,18 +475,27 @@ This directive specifies the indexes to maintain for the given
 attribute. If only an {{EX:<attrlist>}} is given, the default
 indexes are maintained.
 
 attribute. If only an {{EX:<attrlist>}} is given, the default
 indexes are maintained.
 

-

 \Example:
 
 >      index default pres,eq
 \Example:
 
 >      index default pres,eq

->      index objectClass,uid
->      index cn,sn eq,sub,approx
+>      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.
+
+By default, no indices are maintained.  It is generally advised
+that minimally an equality index upon objectClass be maintained.
+
+>      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 {{EX:objectClass}} and {{EX:uid}} attribute
-types.  The third line causes equality, substring, and approximate
-indices to be maintained for {{EX:cn}} and {{EX:sn}} attribute types.

 
 H4: mode <integer>
 
 
 H4: mode <integer>
 


@@ -550,12 +572,12 @@ matching the entry's distinguished name:
 
 >      dn=<regular expression>
 
 
 >      dn=<regular expression>
 

-Note: The DN pattern specified should be "normalized",
-meaning that there should be no extra spaces, and commas
-should be used to separate components. An example
-normalized DN is "cn=Babs Jensen,dc=example,dc=com".
-An example of a non-normalized DN is
-"cn=Babs Jensen; dc=example, dc=com".
+Note: The DN pattern specified should be "normalized" to the RFC2253
+restricted DN form.  In particular, there should be no extra spaces
+and commas should be used to separate components.  An example
+normalized DN is "{{EX:cn=Babs Jensen,dc=example,dc=com}}".  An
+example of a non-normalized DN is "{{EX:cn=Babs Jensen; dc=example;
+dc=com}}".

 
 Or, entries may be selected by a filter matching some
 attribute(s) in the entry:
 
 Or, entries may be selected by a filter matching some
 attribute(s) in the entry:


@@ -609,9 +631,8 @@ separate RDN components.
 
 Other control factors are also supported.
 For example, a {{EX:<what>}} can be restricted by a
 
 Other control factors are also supported.
 For example, a {{EX:<what>}} can be restricted by a

-regular expression matching the client's IP address or domain name:
+regular expression matching the client's domain name:

 
 

->      addr=<regular expression>

 >      domain=<regular expression>
 
 or by an entry listed in a DN-valued attribute in the entry to
 >      domain=<regular expression>
 
 or by an entry listed in a DN-valued attribute in the entry to


@@ -651,36 +672,35 @@ to grant specific permissions.
 
 H3: Access Control Evaluation
 
 
 H3: Access Control Evaluation
 

-When evaluating whether some requester should be given
-access to an entry and/or attribute, slapd compares the entry
-and/or attribute to the {{EX:<what>}} selectors given in the
-configuration file. Access directives local to the current
-database are examined first, followed by global access
-directives. Within this priority, access directives are
-examined in the order in which they appear in the config file.
-Slapd stops with the first {{EX:<what>}} selector that matches the
-entry and/or attribute. The corresponding access directive is
-the one slapd will use to evaluate access.
-
-Next, slapd compares the entity requesting access to the
-{{EX:<who>}} selectors within the access directive selected above
-in the order in which they appear. It stops with the first {{EX:<who>}}
-selector that matches the requester. This determines the
-access the entity requesting access has to the entry and/or
-attribute.
+When evaluating whether some requester should be given access to
+an entry and/or attribute, slapd compares the entry and/or attribute
+to the {{EX:<what>}} selectors given in the configuration file.
+For each entry, access control provided in the database which holds
+the entry (or the first database if not held in any database) apply
+first, followed by the global access directivies.  Within this
+priority, access directives are examined in the order in which they
+appear in the config file.  Slapd stops with the first {{EX:<what>}}
+selector that matches the entry and/or attribute. The corresponding
+access directive is the one slapd will use to evaluate access.
+
+Next, slapd compares the entity requesting access to the {{EX:<who>}}
+selectors within the access directive selected above in the order
+in which they appear. It stops with the first {{EX:<who>}} selector
+that matches the requester. This determines the access the entity
+requesting access has to the entry and/or attribute.

 
 Finally, slapd compares the access granted in the selected
 
 Finally, slapd compares the access granted in the selected

-{{EX:<access>}} clause to the access requested by the client. If it
-allows greater or equal access, access is granted. Otherwise,
+{{EX:<access>}} clause to the access requested by the client. If
+it allows greater or equal access, access is granted. Otherwise,

 access is denied.
 
 access is denied.
 

-The order of evaluation of access directives makes their
-placement in the configuration file important. If one access
-directive is more specific than another in terms of the entries
-it selects, it should appear first in the config file. Similarly, if
-one {{EX:<who>}} selector is more specific than another it should
-come first in the access directive. The access control
-examples given below should help make this clear.
+The order of evaluation of access directives makes their placement
+in the configuration file important. If one access directive is
+more specific than another in terms of the entries it selects, it
+should appear first in the config file. Similarly, if one {{EX:<who>}}
+selector is more specific than another it should come first in the
+access directive. The access control examples given below should
+help make this clear.

 
 
 
 
 
 


@@ -743,10 +763,10 @@ to a specific attribute and various {{EX:<who>}} selectors.
 >              by dn=".*,dc=example,dc=com" search
 >              by anonymous auth
 
 >              by dn=".*,dc=example,dc=com" search
 >              by anonymous auth
 

-This example applies to entries in the "{{EX:dc=example, dc=com}}"
+This example applies to entries in the "{{EX:dc=example,dc=com}}"

 subtree. To all attributes except {{EX:homePhone}}, the entry itself
 can write them, other {{EX:example.com}} entries can search by them,
 subtree. To all attributes except {{EX:homePhone}}, the entry itself
 can write them, other {{EX:example.com}} entries can search by them,

-anybody else has no access ((implicit {{EX:by * none}}) excepting for
+anybody else has no access (implicit {{EX:by * none}}) excepting for

 authentication/authorization (which is always done anonymously).
 The {{EX:homePhone}} attribute is writable by the entry, searchable
 by other {{EX:example.com}} entries, readable by clients connecting
 authentication/authorization (which is always done anonymously).
 The {{EX:homePhone}} attribute is writable by the entry, searchable
 by other {{EX:example.com}} entries, readable by clients connecting


@@ -797,10 +817,9 @@ 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}}.
 
 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 is used only if
-no database access controls match or when the target
-objects are not under the control of any database (such as
-the Root DSE).
+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 an LDBM
 backend that will handle queries for things in the
 
 The next section of the configuration file defines an LDBM
 backend that will handle queries for things in the


@@ -812,17 +831,17 @@ attribute is to be protected from unauthorized access.
 
 E:  5. # ldbm definition for the example.com
 E:  6. database ldbm
 
 E:  5. # ldbm definition for the example.com
 E:  6. database ldbm

-E:  7. suffix "dc=example, dc=com"
+E:  7. suffix "dc=example,dc=com"

 E:  8. directory /usr/local/var/openldap
 E:  8. directory /usr/local/var/openldap

-E:  9. rootdn "cn=Manager, dc=example, dc=com"
+E:  9. rootdn "cn=Manager,dc=example,dc=com"

 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: 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: 14.         binddn="cn=Replicator, dc=example, dc=com"
+E: 14.         binddn="cn=Replicator,dc=example,dc=com"

 E: 15.         bindmethod=simple credentials=secret
 E: 16. replica host=slave2.example.com
 E: 15.         bindmethod=simple credentials=secret
 E: 16. replica host=slave2.example.com

-E: 17.         binddn="cn=Replicator, dc=example, dc=com"
+E: 17.         binddn="cn=Replicator,dc=example,dc=com"

 E: 18.         bindmethod=simple credentials=secret
 E: 19. # indexed attribute definitions
 E: 20. index uid pres,eq
 E: 18.         bindmethod=simple credentials=secret
 E: 19. # indexed attribute definitions
 E: 20. index uid pres,eq


@@ -836,50 +855,49 @@ E: 27.            by dn="cn=Admin,dc=example,dc=com" write
 E: 28.         by * none
 E: 29. access to *
 E: 30.         by self write
 E: 28.         by * none
 E: 29. access to *
 E: 30.         by self write

-E: 31.         by anonymous auth
-E: 32.         by dn="cn=Admin,dc=example,dc=com" write
-E: 33.         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 11 through 18 are for replication. Line 11 specifies the
-replication log file (where changes to the database are logged
-\- this file is written by slapd and read by slurpd). Lines 12 
-through 14 specify the hostname and port for a replicated
-host, the DN to bind as when performing updates, the bind
-method (simple) and the credentials (password) for the
-binddn. Lines 15 through 18 specify a second replication site.
-See the {{SECT:Replication with slurpd}} chapter for more
-information on these directives.
-
-Lines 20 through 22 indicate the indexes to maintain for
-various attributes.
-
-Lines 24 through 33 specify access control for entries in the
-database. For all 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, may be used for 
-authentication/authorization purposes, but may be read by 
-authenticated users.
-
-The next section of the example configuration file defines
-another LDBM database. This one handles queries involving
-the {{EX:dc=example,dc=net}} subtree.  Note that without
-line 38, the read access would be allowed due to the
-global access rule at line 4.
+E: 31.         by dn="cn=Admin,dc=example,dc=com" write
+E: 32.         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 11 through 18 are for replication. Line 12 specifies the
+replication log file (where changes to the database are logged \-
+this file is written by slapd and read by slurpd). Lines 13 through
+15 specify the hostname and port for a replicated host, the DN to
+bind as when performing updates, the bind method (simple) and the
+credentials (password) for the binddn. Lines 16 through 18 specify
+a second replication site.  See the {{SECT:Replication with slurpd}}
+chapter for more information on these directives.
+
+Lines 20 through 22 indicate the indexes to maintain for various
+attributes.
+
+Lines 24 through 32 specify access control for entries in the this
+database.  As this is the first database, the controls also apply
+to entries not held in any database (such as the Root DSE).  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
+LDBM 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. # ldbm definition for example.net
 E: 34. database ldbm
 
 E: 33. # ldbm definition for example.net
 E: 34. database ldbm

-E: 35. suffix "dc=example, dc=net"
+E: 35. suffix "dc=example,dc=net"

 E: 36. directory /usr/local/var/ldbm-example-net
 E: 36. directory /usr/local/var/ldbm-example-net

-E: 37. rootdn "cn=Manager, dc=example, dc=com"
-E: 38. access to * by users read
+E: 37. rootdn "cn=Manager,dc=example,dc=com"
+E: 38. index objectClass eq
+E: 39. access to * by users read