From a2a313f37fd4381dae9645f8fc5d982fa54d2c06 Mon Sep 17 00:00:00 2001 From: Howard Chu Date: Tue, 10 May 2005 11:32:25 +0000 Subject: [PATCH] Preliminary slapd.d info, very incomplete --- doc/guide/admin/config_dit.gif | Bin 0 -> 4592 bytes doc/guide/admin/master.sdf | 3 + doc/guide/admin/slapdconf2.sdf | 1173 ++++++++++++++++++++++++++++++++ 3 files changed, 1176 insertions(+) create mode 100644 doc/guide/admin/config_dit.gif create mode 100644 doc/guide/admin/slapdconf2.sdf diff --git a/doc/guide/admin/config_dit.gif b/doc/guide/admin/config_dit.gif new file mode 100644 index 0000000000000000000000000000000000000000..c58af04454626a169103bafe88effca1346f394f GIT binary patch literal 4592 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 literal 0 HcmV?d00001 diff --git a/doc/guide/admin/master.sdf b/doc/guide/admin/master.sdf index 07281fc50c..c8d7f046b3 100644 --- a/doc/guide/admin/master.sdf +++ b/doc/guide/admin/master.sdf @@ -36,6 +36,9 @@ PB: !include "install.sdf"; chapter PB: +!include "slapdconf2.sdf"; chapter +PB: + !include "slapdconfig.sdf"; chapter PB: diff --git a/doc/guide/admin/slapdconf2.sdf b/doc/guide/admin/slapdconf2.sdf new file mode 100644 index 0000000000..1e4fe6c12d --- /dev/null +++ b/doc/guide/admin/slapdconf2.sdf @@ -0,0 +1,1173 @@ +# $OpenLDAP$ +# Copyright 2005, The OpenLDAP Foundation, All Rights Reserved. +# COPYING RESTRICTIONS APPLY, see COPYRIGHT. + +H1: Configuring slapd + +Once the software has been built and installed, you are ready +to configure {{slapd}}(8) for use at your site. Unlike previous +OpenLDAP releases, the slapd runtime configuration in 2.3 is +fully LDAP-enabled and can be managed using the standard LDAP +operations with data in LDIF. The LDAP configuration engine +allows all of slapd's configuration options to be changed on the fly, +generally without requiring a server restart for the changes +to take effect. The old style {{slapd.conf}}(5) file is still +supported, but must be converted to the new {{slapd.d}}(5) format +to allow runtime changes to be saved. While the old style +configuration uses a single file, normally installed as +{{F:/usr/local/etc/openldap/slapd.conf}}, the new style +uses a slapd backend database to store the configuration. The +the configuration database normally resides in the +{{F:/usr/local/etc/openldap/slapd.d}} directory. + +An alternate configuration directory (or file) can be specified via a +command-line option to {{slapd}}(8) or {{slurpd}}(8). This chapter +describes the general format of the configuration system , followed by a +detailed description of commonly used config directives. + + +H2: Configuration Layout + +The slapd configuration is stored as a special LDAP directory with +a predefined schema and DIT. There are specific objectClasses used to +carry global configuration options, schema definitions, backend and +database definitions, and assorted other items. A sample config tree +is shown in Figure 5.1. + +!import "config_dit.gif"; align="center"; title="Sample configuration tree" +FT[align="Center"] Figure 5.1: Sample configuration tree. + +Other objects may be part of the configuration but were omitted from +the illustration for clarity. + +The {{slapd.d}} configuration tree has a very specific structure. The +root of the tree is named {{EX:cn=config}} and contains global configuration +settings. Additional settings are contained in separate child entries: +* Include files +.. Usually these are just pathnames left over from a converted +{{EX:slapd.conf}} file. +.. Otherwise use of Include files is deprecated. +* Dynamically loaded modules +.. These may only be used if the {{EX:--enable-modules}} option was +used to configure the software. +* Schema definitions +.. The {{EX:cn=schema,cn=config}} entry contains the system schema (all +the schema that is hard-coded in slapd). +.. Child entries of {{EX:cn=schema,cn=config}} contain user schema as +loaded from config files or added at runtime. +* Backend-specific configuration +* Database-specific configuration +.. Overlays are defined in children of the Database entry. +.. Databases and Overlays may also have other miscellaneous children. + +The usual rules for LDIF files apply to the configuration information: +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 (even if the previous line is a +comment). Entries are separated by blank lines. + +The general layout of the config LDIF is as follows: + +> # global configuration settings +> dn: cn=config +> objectClass: olcGlobal +> cn: config +> +> +> # schema definitions +> dn: cn=schema,cn=config +> objectClass: olcSchemaConfig +> cn: schema +> +> +> dn: cn={X}core,cn=schema,cn=config +> objectClass: olcSchemaConfig +> cn: {X}core +> +> +> # additional user-specified schema +> ... +> +> # backend definitions +> dn: olcBackend={X},cn=config +> objectClass: olcBackendConfig +> olcBackend: {X} +> +> +> # database definitions +> dn: olcDatabase={X},cn=config +> objectClass: olcDatabaseConfig +> olcDatabase: {X} +> +> +> # subsequent definitions and settings +> ... + +Some of the entries listed above have a numeric index {{EX:"{X}"}} in +their names. While most configuration settings have an inherent ordering +dependency (i.e., one setting must take effect before a subsequent one +may be set), LDAP databases are inherently unordered. The numeric index +is used to enforce a consistent ordering in the configuration database, +so that all ordering dependencies are preserved. In most cases the index +does not have to be provided; it will be automatically generated based +on the order in which entries are created. + +A configuration directive may take arguments. If so, they are +separated by white space. If an argument contains white space, +the argument should be enclosed in double quotes {{EX:"like this"}}. If +an argument contains a double quote or a backslash character `{{EX:\}}', +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 definitions (attribute types +and object classes) are also provided in the +{{F: /usr/local/etc/openldap/schema}} directory. + + +H2: Configuration Directives + +This section details commonly used configuration directives. For +a complete list, see the {{slapd.d}}(5) manual page. This section +separates the configuration directives into global, +backend-specific and data-specific categories, describing each +directive and its default value (if any), and giving an example of +its use. + +Most of the attributes and objectClasses used in the slapd +configuration have a prefix of {{EX:"olc"}} (OpenLDAP Configuration) +in their names. + + + +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 +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 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 + +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. + + +H4: attributetype <{{REF:RFC2252}} Attribute Type Description> + +This directive defines an attribute type. +Please see the {{SECT:Schema Specification}} chapter +for information regarding how to use this directive. + +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. + + +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. 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 +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) {{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" +Level Description +-1 enable all debugging +0 no debugging +1 trace function calls +2 debug packet handling +4 heavy trace debugging +8 connection management +16 print out packets sent and received +32 search filter processing +64 configuration file processing +128 access control list processing +256 stats log connections/operations/results +512 stats log entries sent +1024 print communication with shell backends +2048 print entry parsing debugging +!endblock + +\Example: + +E: loglevel -1 + +This will cause lots and lots of debugging information to be +logged. + +\Default: + +E: loglevel 256 + + +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 + +This directive specifies the referral to pass back when slapd +cannot find a local database to handle a request. + +\Example: + +> referral ldap://root.openldap.org + +This will refer non-local queries to the global root LDAP server +at the OpenLDAP Project. Smart LDAP clients can re-ask their +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: sizelimit + +This directive specifies the maximum number of entries to return +from a search operation. + +\Default: + +> sizelimit 500 + + +H4: timelimit + +This directive specifies the maximum number of seconds (in real +time) slapd will spend answering a search request. If a +request is not finished in this time, a result indicating an +exceeded timelimit will be returned. + +\Default: + +> timelimit 3600 + + +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 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 + +\Example: + +> backend bdb + +This marks the beginning of a new {{TERM:BDB}} backend +definition. + + +H3: General Database Directives + +Directives in this section apply only to the database in which +they are defined. They are supported by every type of database. + +H4: database + +This directive marks the beginning of a database instance +declaration. +{{EX:}} should be one of the +supported backend types listed in Table 5.2. + +\Example: + +> database bdb + +This marks the beginning of a new {{TERM:BDB}} database instance +declaration. + + +H4: readonly { on | off } + +This directive puts the database into "read-only" mode. Any +attempts to modify the database will return an "unwilling to +perform" error. + +\Default: + +> readonly off + +H4: replica + +> replica uri=ldap[s]://[:] | host=[:] +> [bindmethod={simple|kerberos|sasl}] +> ["binddn="] +> [saslmech=] +> [authcid=] +> [authzid=] +> [credentials=] +> [srvtab=] + +This directive specifies a replication site for this database. The +{{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 . If is not +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="}} 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 data +integrity and confidentiality 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. + +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. + + +H4: replogfile + +This directive specifies the name of the replication log file to +which slapd will log changes. The replication log is typically +written by slapd and read by slurpd. Normally, this directive is +only used if slurpd is being used to replicate the database. +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 chapter entitled {{SECT:Replication with slurpd}} for more +information on how to use this directive. + + +H4: rootdn + +This directive specifies the DN that is not subject to +access control or administrative limit restrictions for +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. + +Entry-based Example: + +> rootdn "cn=Manager,dc=example,dc=com" + +SASL-based Example: + +> rootdn "uid=root,cn=example.com,cn=digest-md5,cn=auth" + +See the {{SECT:SASL Authentication}} section for information on +SASL authentication identities. + + +H4: rootpw + +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 +passed to this backend database. Multiple suffix lines can be +given, and at least one is required for each database +definition. + +\Example: + +> suffix "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 +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: syncrepl + +> syncrepl rid= +> provider=ldap[s]://[:port] +> [type=refreshOnly|refreshAndPersist] +> [interval=dd:hh:mm:ss] +> [retry=[ <# of retries>]+] +> [searchbase=] +> [filter=] +> [scope=sub|one|base] +> [attrs=] +> [attrsonly] +> [sizelimit=] +> [timelimit=] +> [schemachecking=on|off] +> [bindmethod=simple|sasl] +> [binddn=] +> [saslmech=] +> [authcid=] +> [authzid=] +> [credentials=] +> [realm=] +> [secprops=] + + +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:}} uniquely identifies the syncrepl specification +described by the current {{EX:syncrepl}} directive. {{EX:}} +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 . Examples are +{{EX:ldap://provider.example.com:389}} or {{EX:ldaps://192.168.1.1:636}}. +If 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 +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: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 + +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" + +SASL-based Example: + +> updatedn "uid=slurpd,cn=example.com,cn=digest-md5,cn=auth" + +See the {{SECT:Replication with slurpd}} chapter for more information +on how to use this directive. + +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. + +\Example: + +> updateref ldap://master.example.net + + +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 BDB files +containing the database and associated indices live. + +\Default: + +> directory /usr/local/var/openldap-data + + +H3: LDBM Database Directives + +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: cachesize + +This directive specifies the size in entries of the in-memory +cache maintained by the LDBM backend database instance. + +\Default: + +> cachesize 1000 + + +H4: dbcachesize + +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. + +\Default: + +> dbcachesize 100000 + + +H4: dbnolocking + +This option, if present, disables database locking. +Enabling this option may improve performance at the expense +of data security. + + +H4: dbnosync + +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. + + +H4: directory + +This directive specifies the directory where the LDBM files +containing the database and associated indices live. + +\Default: + +> directory /usr/local/var/openldap-data + + +H4: index { | default} [pres,eq,approx,sub,none] + +This directive specifies the indices to maintain for the given +attribute. If only an {{EX:}} is given, the default +indices are maintained. + +\Example: + +> index default pres,eq +> 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 + + + +H4: mode + +This directive specifies the file protection mode that newly +created database index files should have. + +\Default: + +> mode 0600 + + +H2: Access Control + +Access to slapd entries and attributes is controlled by the +access configuration file directive. The general form of an +access line is: + +> ::= access to +> [by ]+ +> ::= * | +> [dn[.]= | dn.=] +> [filter=] [attrs=] +> ::= regex | exact +> ::= base | one | subtree | children +> ::= [val[.]=] | , +> ::= | entry | children +> ::= * | [anonymous | users | self +> | dn[.]= | dn.=] +> [dnattr=] +> [group[/[/][.]]=] +> [peername[.]=] +> [sockname[.]=] +> [domain[.]=] +> [sockurl[.]=] +> [set=] +> [aci=] +> ::= [self]{|} +> ::= none | auth | compare | search | read | write +> ::= {=|+|-}{w|r|s|c|x|0}+ +> ::= [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. 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 are +commonly selected in two ways: by DN and by filter. The following +qualifiers select entries by DN: + +> to * +> to dn[.]= +> to 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}}. + +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). + +For example, if the directory contained entries named: + +> 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: + +> to filter= + +where is a string representation of an LDAP +search filter, as described in {{REF:RFC2254}}. For example: + +> to filter=(objectClass=person) + +Note that entries may be selected by both DN and filter by +including both qualifiers in the clause. + +> 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 selector: + +> attrs= + +A specific value of an attribute is selected by using a single +attribute name and also using a value selector: + +> attrs= val[.