X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=doc%2Fguide%2Fadmin%2Fslapdconfig.sdf;h=7b6bf2464c9e85849190237aca9b42dcf7620428;hb=14745b74d29fe80f2988908b3f3fa3a4532937d9;hp=50031bb554804275d305dae6737cb3c4b299d41c;hpb=9eec05658fdfd7cd3bd21aaa52af8d155803b035;p=openldap diff --git a/doc/guide/admin/slapdconfig.sdf b/doc/guide/admin/slapdconfig.sdf index 50031bb554..7b6bf2464c 100644 --- a/doc/guide/admin/slapdconfig.sdf +++ b/doc/guide/admin/slapdconfig.sdf @@ -1,29 +1,29 @@ # $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 -Once the software has been built and installed, you are ready to configure it -for use at your site. All slapd runtime configuration is accomplished through -the {{I:slapd.conf}}(5) file, normally installed in the +Once the software has been built and installed, you are ready +to configure {{slapd}}(8) for use at your site. The slapd +runtime configuration is primarily accomplished through the +{{slapd.conf}}(5) file, normally installed in the {{EX:/usr/local/etc/openldap}} directory. An alternate configuration file can be specified via a -command-line option to slapd or slurpd (see Sections 5 and 8, -respectively). This section describes the general format of the config file, -followed by a detailed description of each config file directive. - +command-line option to {{slapd}}(8) or {{slurpd}}(8). This chapter +describes the general format of the config file, followed by a +detailed description of commonly used config file directives. H2: Configuration File Format -The {{slapd.conf}}(5) file consists three types of configuration -information: global, backend specific, database specific. Global +The {{slapd.conf}}(5) file consists of three types of configuration +information: global, backend specific, and database specific. Global information is specified first, followed by information associated with a particular backend type, which is then followed by information associated with a particular database instance. Global directives can -be overridden in a backend and/or database directives, backend directives +be overridden in backend and/or database directives, and backend directives can be overridden by database directives. Blank lines and comment lines beginning with a '{{EX:#}}' character @@ -61,7 +61,7 @@ the character should be preceded by a backslash character `{{EX:\}}'. The distribution contains an example configuration file that will be installed in the {{F: /usr/local/etc/openldap}} directory. -A number of files containing schema definition (attribute types +A number of files containing schema definitions (attribute types and object classes) are also provided in the {{F: /usr/local/etc/openldap/schema}} directory. @@ -69,7 +69,7 @@ and object classes) are also provided in the H2: Configuration File Directives This section details commonly used configuration directives. For -a complete list, see {{slapd.conf}}(5) manual page. This section +a complete list, see the {{slapd.conf}}(5) manual page. This section separates the configuration file directives into global, backend-specific and data-specific categories, describing each directive and its default value (if any), and giving an example of @@ -79,41 +79,50 @@ its use. H3: Global Directives -Directives described in this section apply to all backends, -unless specifically overridden in a backend definition. -Arguments to directives should be replaced by actual text are -shown in brackets {{EX:<>}}. +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 +by actual text are shown in brackets {{EX:<>}}. H4: access to [ by ]+ This directive grants access (specified by ) to a set of entries and/or attributes (specified by ) by one or -more requesters (specified by ). See Section 5.3 on -access control for more details and examples. +more requesters (specified by ). +See the {{SECT:Access Control}} section of this chapter for a +summary of basic usage. +!if 0 +More details discussion of this directive can be found in the +{{SECT:Advanced Access Control}} chapter. +!endif -H4: attributetype +Note: If no {{EX:access}} directives are specified, the default +access control policy, {{EX:access to * by * read}}, allows all +both authenticated and anonymous users read access. -This directive defines an attribute type. -H4: defaultaccess { none | compare | search | read | write } +H4: attributetype <{{REF:RFC2252}} Attribute Type Description> -This directive specifies the default access to grant requesters -not matched by any other access line (see Section 5.3). Note -that an access level implies all lesser access levels (e.g., -write access implies read, search and compare). +This directive defines an attribute type. +Please see the {{SECT:Schema Specification}} chapter +for information regarding how to use this directive. -\Default: +H4: idletimeout + +Specify the number of seconds to wait before forcibly closing +an idle client connection. An idletimeout of 0, the default, +disables this feature. -E: defaultaccess read H4: include This directive specifies that slapd should read additional configuration information from the given file before continuing with the next line of the current file. The included file should -follow the normal slapd config file format. +follow the normal slapd config file format. The file is commonly +used to include files containing schema specifications. Note: You should be careful when using this directive - there is no small limit on the number of nested include directives, and no @@ -122,13 +131,13 @@ loop detection is done. H4: loglevel This directive specifies the level at which debugging statements -and operation statistics should be syslogged (currently -logged to the {{syslogd}}(8) LOG_LOCAL4 facility). You must -have compiled slapd with -DLDAP_DEBUG for this to work -(except for the two statistics levels, which are always enabled). -Log levels are additive. To display what numbers correspond -to what kind of debugging, invoke slapd with the ? flag or -consult the table below. The possible values for are: +and operation statistics should be syslogged (currently logged to +the {{syslogd}}(8) {{EX:LOG_LOCAL4}} facility). You must have +configured OpenLDAP {{EX:--enable-debug}} (the default) for this +to work (except for the two statistics levels, which are always +enabled). Log levels are additive. To display what numbers +correspond to what kind of debugging, invoke slapd with {{EX:-?}} +or consult the table below. The possible values for are: !block table; colaligns="RL"; align=Center; \ title="Table 5.1: Debugging Levels" @@ -160,9 +169,13 @@ logged. E: loglevel 256 -H4: objectclass + +H4: objectclass <{{REF:RFC2252}} Object Class Description> This directive defines an object class. +Please see the {{SECT:Schema Specification}} chapter for +information regarding how to use this directive. + H4: referral @@ -179,17 +192,6 @@ query at that server, but note that most of these clients are only going to know how to handle simple LDAP URLs that contain a host part and optionally a distinguished name part. -H4: schemacheck { on | off } - -This directive turns schema checking on or off. If schema -checking is on, entries added or modified through LDAP operations -will be checked to ensure they obey the schema rules implied -by their object class(es) as defined by the corresponding objectclass -directive(s). If schema checking is off this check is not done. - -\Default: - -> schemacheck on H4: sizelimit @@ -201,19 +203,6 @@ from a search operation. > sizelimit 500 -H4: srvtab - -This directive specifies the srvtab file in which slapd can find the -Kerberos keys necessary for authenticating clients using -Kerberos. This directive is only meaningful if you are using -Kerberos authentication, which must be enabled at compile -time by including the appropriate definitions in the -{{EX:Make-common}} file. - -\Default: - -> srvtab /etc/srvtab - H4: timelimit This directive specifies the maximum number of seconds (in real @@ -228,34 +217,60 @@ exceeded timelimit will be returned. H3: General Backend Directives -H3: General Database 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 declaration. +{{EX:}} should be one of the +supported backend types listed in Table 5.2. + +!block table; align=Center; coltags="EX,N"; \ + title="Table 5.2: Database Backends" +Types Description +bdb Berkeley DB transactional backend +dnssrv DNS SRV backend +ldap Lightweight Directory Access Protocol (Proxy) backend +ldbm Lightweight DBM backend +meta Meta Directory backend +monitor Monitor backend +passwd Provides read-only access to {{passwd}}(5) +perl Perl Programmable backend +shell Shell (extern program) backend +sql SQL Programmable backend +!endblock -Directives in this section only apply to the database in which -they are defined. They are supported by every type of database. +\Example: -H4: database +> backend bdb -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. +This marks the beginning of a new {{TERM:BDB}} backend +definition. -\Example: -> database ldbm +H3: General Database Directives -This marks the beginning of a new LDBM backend database -instance definition. +Directives in this section apply only to the database in which +they are defined. They are supported by every type of database. -H4: lastmod { on | off } +H4: database -This directive controls whether slapd will automatically maintain -the modifiersName, modifyTimestamp, creatorsName, and -createTimestamp attributes for entries. +This directive marks the beginning of a database instance +declaration. +{{EX:}} should be one of the +supported backend types listed in Table 5.2. -\Default: +\Example: + +> database bdb + +This marks the beginning of a new {{TERM:BDB}} database instance +declaration. -> lastmod on H4: readonly { on | off } @@ -270,8 +285,11 @@ perform" error. H4: replica > replica host=[:] -> "binddn=" -> [bindmethod={ simple | kerberos }] +> [bindmethod={simple|kerberos|sasl}] +> ["binddn="] +> [saslmech=] +> [authcid=] +> [authzid=] > [credentials=] > [srvtab=] @@ -285,25 +303,35 @@ 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 -updatedn directive in the slave slapd's config file. Since DNs are +{{EX:updatedn}} directive in the slave slapd's config file. Since DNs are likely to contain embedded spaces, the entire {{EX:"binddn="}} string should be enclosed in double quotes. -The {{EX:bindmethod}} is either simple or kerberos, depending on -whether simple password-based authentication or kerberos -authentication is to be used when connecting to the slave -slapd. Simple authentication requires a valid password be -given. Kerberos authentication requires a valid srvtab file. +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. -The {{EX:credentials=}} parameter, which is only required if using -simple authentication, gives the password for {{EX:binddn}} on the -slave slapd. +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. -The {{EX:srvtab=}} parameter, which is only required if using -kerberos, specifies the filename which holds the kerberos key -for the slave slapd. If omitted, {{F:/etc/srvtab}} is used. +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. + +See the chapter entitled {{SECT:Replication with slurpd}} for more +information on how to use this directive. -See Section 10 for more details on replication. H4: replogfile @@ -315,42 +343,49 @@ 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 Section 10 for more details on replication. +See the chapter entitled {{SECT:Replication with slurpd}} for more +information on how to use this directive. + H4: rootdn -This directive specifies the DN of an entry that is not subject to +This directive specifies the DN that is not subject to access control or administrative limit restrictions for -operations on this database. +operations on this database. The DN need not refer to +an entry in this database or even in the directory. The +DN may refer to a SASL identity. -\Example: +Entry-based Example: -> rootdn "cn=Manager, dc=example, dc=com" +> rootdn "cn=Manager,dc=example,dc=com" -H4: rootkrbname +SASL-based Example: -This directive specifies a kerberos name for the DN given above -that will always work, regardless of whether an entry with the -given DN exists or has a {{EX:krbName}} attribute. This directive is -useful when creating a database and also when using slurpd -to provide replication service (see Section 10). +> rootdn "uid=root,cn=example.com,cn=digest-md5,cn=auth" -\Example: +See the {{SECT:SASL Authentication}} section for information on +SASL authentication identities. -> rootkrbname admin@EXAMPLE.COM H4: rootpw -This directive specifies a password for the DN given above that -will always work, regardless of whether an entry with the given -DN exists or has a password. This directive is useful when -creating a database and also when using slurpd to provide -replication service (see Section 10). +This directive can be used to specifies a password for the DN for +the rootdn (when the rootdn is set to a DN within the database). \Example: > rootpw secret +It is also permissible to provide hash of the password in RFC 2307 +form. {{slappasswd}}(8) may be used to generate the password hash. + +\Example: + +> rootpw {SSHA}ZKKuqbEKJfKSXhUbHG3fG8MDn9j1v4QN + +The hash was generated using the command {{EX:slappasswd -s secret}}. + + H4: suffix This directive specifies the DN suffix of queries that will be @@ -360,176 +395,227 @@ 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 +Note: When the backend to pass a query to is selected, slapd looks at the suffix line(s) in each database definition in the 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 +H4: syncrepl + +> syncrepl id= +> provider=ldap[s]://[:port] +> [updatedn=] +> [binddn=] +> [bindmethod=simple|sasl] +> [binddn=] +> [credentials=] +> [saslmech=] +> [secprops=] +> [realm=] +> [authcId=] +> [authzId=] +> [searchbase=] +> [filter=] +> [attrs=] +> [scope=sub|one|base] +> [schemachecking=on|off] +> [type=refreshOnly|refreshAndPersist] +> [interval=dd:hh:mm] + +This directive specifies an LDAP Sync replication between this +database and the specified replication provider site. The id= +parameter identifies the LDAP Sync specification in the database. +The {{EX:provider=}} parameter specifies a replication provider site as +an LDAP URI. + +The LDAP Sync replication specification is based on the search +specification which defines the content of the replica. The replica +consists of the entries matching the search specification. As with +the normal searches, the search specification consists of +{{EX:searchbase}}, {{EX:scope}}, {{EX:filter}}, and EX:attrs}} +parameters. + +The LDAP Sync replication has two types of operating modes. In the +{{EX:refreshOnly}} mode, the next synchronization session is +rescheduled at the interval time after the current session finishes. +The default interval is set to one day. In the {{EX:refreshAndPersist}} +mode, the LDAP Sync search remains persistent in the provider LDAP +server. Further updates to the provider replica will generate +searchResultEntry to the consumer. + +The schema checking can be enforced at the LDAP Sync consumer site +by turning on the {{EX:schemachecking}} parameter. The default is off. + +The {{EX:binddn=}} parameter gives the DN for the LDAP Sync search +to bind as to the provider slapd. The content of the replica will +be subject to the access control privileges of the DN. + +The {{EX:bindmethod}} is {{EX:simple}} or {{EX:sasl}}, depending +on whether simple password-based authentication or SASL authentication +is to be used when connecting to the provider slapd. + +Simple authentication should not be used unless adequate integrity +and data confidential 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. +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 +a proxy authorization identity. + +The LDAP Sync replication is supported in three native backends: +back-bdb, back-hdb, and back-ldbm. + +See the {{SECT:LDAP Sync Replication}} chapter for more information +on how to use this directive. -This directive is only applicable in a slave slapd. It specifies the -DN allowed to make changes to the replica (typically, this is -the DN slurpd binds as when making changes to the replica). +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 DN +{{slurpd}}(8) binds as when making changes to the replica or the DN +associated with a SASL identity. -H3: LDBM Backend-Specific Directives +Entry-based Example: -Directives in this category only apply to the LDBM backend -database. That is, they must follow a "database ldbm" line and -come before any other "database" line. +> updatedn "cn=Update Daemon,dc=example,dc=com" -H4: cachesize +SASL-based Example: -This directive specifies the size in entries of the in-memory -cache maintained by the LDBM backend database instance. +> updatedn "uid=slurpd,cn=example.com,cn=digest-md5,cn=auth" -\Default: +See the {{SECT:Replication with slurpd}} chapter for more information +on how to use this directive. -> cachesize 1000 +H4: updateref +This directive is only applicable in a slave slapd. It +specifies the URL to return to clients which submit update +requests upon the replica. +If specified multiple times, each {{TERM:URL}} is provided. -H4: dbcachesize +\Example: -This directive specifies the size in bytes of the in-memory cache -associated with each open index file. If not supported by the -underlying database method, this directive is ignored without -comment. Increasing this number uses more memory but can -cause a dramatic performance increase, especially during -modifies or when building indexes. +> updateref ldap://master.example.net -\Default: -> dbcachesize 100000 +H3: BDB 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 +subsequent "backend" or "database" line. For a complete reference +of BDB configuration directives, see {{slapd-bdb}}(5). H4: directory -This directive specifies the directory where the LDBM files -containing the database and associated indexes live. +This directive specifies the directory where the BDB files +containing the database and associated indices live. \Default: -> directory /usr/local/var/openldap-ldbm - - -H4: index { | default} [pres,eq,approx,sub,none] - -This directive specifies the indexes to maintain for the given -attribute. If only an is given, all possible indexes are -maintained. +> directory /usr/local/var/openldap-data -\Example: -> index default pres,eq -> index objectClass,uid -> index cn,sn eq,sub,approx +H3: LDBM Database Directives -The first line sets the default to indices to maintain to present -and equality. The second line causes the default (pres,eq) set -of indices to be maintained for objectClass and uid attribute -types. The third line causes equality, substring, and approximate -filters to be maintained for cn and sn attribute types. +Directives in this category only apply to a {{TERM:LDBM}} database. +That is, they must follow a "database ldbm" line and come before +any subsequent "backend" or "database" line. For a complete reference +of LDBM configuration directives, see {{slapd-ldbm}}(5). -H4: mode +H4: cachesize -This directive specifies the file protection mode that newly -created database index files should have. +This directive specifies the size in entries of the in-memory +cache maintained by the LDBM backend database instance. \Default: -> mode 0600 +> cachesize 1000 +H4: dbcachesize -H3: Shell Backend-Specific Directives +This directive specifies the size in bytes of the in-memory cache +associated with each open index file. If not supported by the +underlying database method, this directive is ignored without +comment. Increasing this number uses more memory but can +cause a dramatic performance increase, especially during +modifies or when building indices. -> bind -> unbind -> search -> compare -> modify -> modrdn -> add -> delete -> abandon +\Default: -These directives specify the pathname of the command to -execute in response to the given LDAP operation. The -command given should understand and follow the input/output -conventions described in Appendix B. +> dbcachesize 100000 -\Example: -> search /usr/local/bin/search.sh +H4: dbnolocking -Note that you need only supply those commands you want the -backend to handle. Operations for which a command is not -supplied will be refused with an "unwilling to perform" error. +This option, if present, disables database locking. +Enabling this option may improve performance at the expense +of data security. +H4: dbnosync -H3: Password Backend-Specific Directives +This option causes on-disk database contents to not be immediately +synchronized with in memory changes upon change. Enabling this option +may improve performance at the expense of data integrity. -Directives in this category only apply to the PASSWD backend -database. That is, they must follow a "database passwd" line -and come before any other "database" line. -H4: file +H4: directory -This directive specifies an alternate passwd file to use. +This directive specifies the directory where the LDBM files +containing the database and associated indices live. \Default: -> file /etc/passwd +> directory /usr/local/var/openldap-data +H4: index { | default} [pres,eq,approx,sub,none] -H3: TCL Backend-Specific Directives +This directive specifies the indices to maintain for the given +attribute. If only an {{EX:}} is given, the default +indices are maintained. -H4: scriptpath +\Example: -This is the full path to a file containing the TCL command(s) to handle -the LDAP operations. +> index default pres,eq +> index uid +> index cn,sn pres,eq,sub +> index objectClass eq -H4: Proc specifiers +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. -> bind -> unbind -> search -> compare -> modify -> modrdn -> add -> delete -> abandon +By default, no indices are maintained. It is generally advised +that minimally an equality index upon objectClass be maintained. -These directives specify the name of the proc (function) in the -TCL script specified in {{EX:scriptpath}} to execute in response to -the given LDAP operation. +> index objectClass eq -\Example: -> search proc_search -Note that you need only supply those commands you want the -TCL backend to handle. Operations for which a command is not -supplied will be refused with an "unwilling to perform" error. +H4: mode -H4: tclrealm +This directive specifies the file protection mode that newly +created database index files should have. -This is one of the biggest pluses of using the TCL backend. -The realm let's you group several databases to the same interpretor. -This basically means they share the same global variables and proc -space. So global variables, as well as all the procs are callable -between databases. If no {{EX:tclrealm}} is specified, it is put into the -"default" realm. +\Default: +> mode 0600 H2: Access Control @@ -540,100 +626,143 @@ access line is: > ::= access to > [by ]+ -> ::= * | [ dn[.]=] +> ::= * | +> [dn[.]= | dn.=] > [filter=] [attrs=] -> ::= regex | base | one | subtree | children -> ::= | , +> ::= regex | exact +> ::= base | one | subtree | children +> ::= [val[.]=] | , > ::= | entry | children -> ::= [* | anonymous | users | self | -> dn[.]=] -> [dnattr= ] -> [group[/[/][.]]= ] -> [peername[.]=] -> [sockname[.]=] -> [domain[.]=] -> [sockurl[.]=] +> ::= * | [anonymous | users | self +> | dn[.]= | dn.=] +> [dnattr=] +> [group[/[/][.]]=] +> [peername[.]=] +> [sockname[.]=] +> [domain[.]=] +> [sockurl[.]=] > [set=] > [aci=] -> ::= regex | exact | base | one | subtree | children -> ::= regex | exact > ::= [self]{|} > ::= none | auth | compare | search | read | write > ::= {=|+|-}{w|r|s|c|x}+ > ::= [stop | continue | break] -where the part selects the entries and/or attributes to -which the access applies, the {{EX:}} part specifies which -entities are granted access, and the {{EX:}} part specifies -the access granted. Multiple {{EX: }} triplets -are supported, allowing many entities to be granted different -access to the same set of entries and attributes. +where the part selects the entries and/or attributes to which +the access applies, the {{EX:}} part specifies which entities +are granted access, and the {{EX:}} part specifies the +access granted. Multiple {{EX: }} triplets +are supported, allowing many entities to be granted different access +to the same set of entries and attributes. Not all of these access +control options are described here; for more details see the +{{slapd.access}}(5) man page. H3: What to control access to -The part of an access specification determines the -entries and attributes to which the access control applies. -Entries can be selected in two ways: by a regular expression -matching the entry's distinguished name: +The part of an access specification determines the entries +and attributes to which the access control applies. Entries are +commonly selected in two ways: by DN and by filter. The following +qualifiers select entries by DN: + +> by * +> by dn[.]= +> by dn.= -> 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. The + is a string representation of the Distinguished Name, as +described in {{REF:RFC2253}}. -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". +The scope can be either {{EX:base}}, {{EX:one}}, {{EX:subtree}}, +or {{EX:children}}. Where {{EX:base}} matches only the entry with +provided DN, {{EX:one}} matches the entries whose parent is the +provided DN, {{EX:subtree}} matches all entries in the subtree whose +root is the provided DN, and {{EX:children}} matches all entries +under the DN (but not the entry named by the DN). -Or, entries may be selected by a filter matching some -attribute(s) in the entry: +For example, if the directory contained entries named: -> filter= +> 0: o=suffix +> 1: cn=Manager,o=suffix +> 2: ou=people,o=suffix +> 3: uid=kdz,ou=people,o=suffix +> 4: cn=addresses,uid=kdz,ou=people,o=suffix +> 5: uid=hyc,ou=people,o=suffix + +\Then: +. {{EX:dn.base="ou=people,o=suffix"}} match 2; +. {{EX:dn.one="ou=people,o=suffix"}} match 3, and 5; +. {{EX:dn.subtree="ou=people,o=suffix"}} match 2, 3, 4, and 5; and +. {{EX:dn.children="ou=people,o=suffix"}} match 3, 4, and 5. + + +Entries may also be selected using a filter: + +> by filter= where is a string representation of an LDAP -search filter, as described in RFC 2254. +search filter, as described in {{REF:RFC2254}}. For example: -The special entry selector "*" is used to select any entry, -and is a convenient shorthand for the equivalent "dn=.*" selector. +> by filter=(objectClass=person) -Attributes within an entry are selected by including a -comma-separated list of attribute names in the -selector: +Note that entries may be selected by both DN and filter by +including both qualifiers in the clause. -> attrs= +> by dn.one="ou=people,o=suffix" filter=(objectClass=person) -Access to the entry itself must be granted or denied using the -special attribute name "{{EX:entry}}". Note that giving access to an -attribute is not enough; access to the entry itself through the -{{EX:entry}} attribute is also required. The complete examples at -the end of this section should help clear things up. +Attributes within an entry are selected by including a comma-separated +list of attribute names in the selector: +> attrs= +A specific value of an attribute is selected by using a single +attribute name and also using a value selector: -H2: Who to grant access to +> attrs= val[.