X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=doc%2Fguide%2Fadmin%2Fslapdconfig.sdf;h=c37150ff616d586f582f9927701800c642160459;hb=50277c6abea63db90cf374b538215b4a63ae549e;hp=c75d7b59667c50e9d5b4a6b4bcd87cd0ad070888;hpb=87b26b8f89fa90b251d2c68a3dacefc08faa2954;p=openldap diff --git a/doc/guide/admin/slapdconfig.sdf b/doc/guide/admin/slapdconfig.sdf index c75d7b5966..c37150ff61 100644 --- 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 -database definition. Arguments that should be replaced +database definition. Arguments that should be replaced by actual text are shown in brackets {{EX:<>}}. @@ -229,17 +229,30 @@ exceeded timelimit will be returned. 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 + +This directive marks the beginning of a backend definition. +{{EX:}} should be one of {{EX:ldbm}}, {{EX:shell}}, +{{EX:passwd}}, or other supported backend type. + + 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. -H4: database +H4: database This directive marks the beginning of a new database instance -definition. should be one of ldbm, shell, or -passwd, depending on which backend will serve the -database. +definition. +{{EX:}} should be one of {{EX:ldbm}}, {{EX:shell}}, +{{EX:passwd}}, or other supported database type. \Example: @@ -295,7 +308,7 @@ 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, in particular the {{EX:KERBEROS_V4}} and {{EX:GSSAPI}} 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. -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 @@ -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. -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 @@ -334,7 +347,7 @@ identity. Entry-based Example: -> rootdn "cn=Manager, dc=example, dc=com" +> rootdn "cn=Manager,dc=example,dc=com" SASL-based Example: @@ -362,9 +375,9 @@ definition. \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 @@ -374,14 +387,14 @@ prefix of another, it must appear after it in the config file. H4: updatedn -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: -> updatedn "cn=Update Daemon, dc=example, dc=com" +> updatedn "cn=Update Daemon,dc=example,dc=com" SASL-based Example: @@ -399,7 +412,7 @@ If specified multiple times, each {{TERM:URL}} is provided. \Example: -> update ldap://master.example.net +> updateref ldap://master.example.net H3: LDBM Backend-Specific Directives @@ -462,18 +475,27 @@ This directive specifies the indexes to maintain for the given attribute. If only an {{EX:}} is given, the default indexes are maintained. - \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 @@ -550,12 +572,12 @@ matching the entry's distinguished name: > dn= -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: @@ -609,9 +631,8 @@ separate RDN components. Other control factors are also supported. For example, a {{EX:}} 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= > domain= 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 -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:}} 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:}} 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:}} selectors within the access directive selected above -in the order in which they appear. It stops with the first {{EX:}} -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:}} 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:}} +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:}} +selectors within the access directive selected above in the order +in which they appear. It stops with the first {{EX:}} 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 -{{EX:}} clause to the access requested by the client. If it -allows greater or equal access, access is granted. Otherwise, +{{EX:}} clause to the access requested by the client. If +it allows greater or equal access, access is granted. Otherwise, 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:}} 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:}} +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:}} selectors. > 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, -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 @@ -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}}. -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 @@ -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: 7. suffix "dc=example, dc=com" +E: 7. suffix "dc=example,dc=com" 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: 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: 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 @@ -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: 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: 35. suffix "dc=example, dc=net" +E: 35. suffix "dc=example,dc=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