X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=doc%2Fguide%2Fadmin%2Fslapdconfig.sdf;h=7b6bf2464c9e85849190237aca9b42dcf7620428;hb=14745b74d29fe80f2988908b3f3fa3a4532937d9;hp=1f449bc781f1e7a5ce54396eea5a81d4cd097651;hpb=38135c8fa4654ca7ea749c2c59ff1e957535049f;p=openldap diff --git a/doc/guide/admin/slapdconfig.sdf b/doc/guide/admin/slapdconfig.sdf index 1f449bc781..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 @@ -31,37 +31,37 @@ are ignored. If a line begins with white space, it is considered a continuation of the previous line. The general format of slapd.conf is as follows: -E: # global configuration directives -E: -E: -E: # backend definition -E: backend -E: -E: -E: # first database definition & config directives -E: database -E: -E: -E: # second database definition & config directives -E: database -E: -E: -E: # second database definition & config directives -E: database -E: -E: -E: # subsequent backend & database definitions & config directives -E: ... +> # global configuration directives +> +> +> # backend definition +> backend +> +> +> # first database definition & config directives +> database +> +> +> # second database definition & config directives +> database +> +> +> # second database definition & config directives +> database +> +> +> # subsequent backend & database definitions & config directives +> ... 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 "like this". If -an argument contains a double quote or a backslash character `\', -the character should be preceded by a backslash character `\'. +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 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,50 +131,60 @@ 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 stats 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: - -*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 +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 255 +E: loglevel -1 This will cause lots and lots of debugging information to be -syslogged. +logged. \Default: 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 +H4: referral This directive specifies the referral to pass back when slapd cannot find a local database to handle a request. \Example: -E: referral ldap://root.openldap.org +> 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 @@ -173,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: - -E: schemacheck on H4: sizelimit @@ -192,21 +200,8 @@ from a search operation. \Default: -E: sizelimit 500 - - -H4: srvtab +> sizelimit 500 -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: - -E: srvtab /etc/srvtab H4: timelimit @@ -217,39 +212,65 @@ exceeded timelimit will be returned. \Default: -E: timelimit 3600 +> timelimit 3600 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: -E: 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. -E: lastmod on H4: readonly { on | off } @@ -259,45 +280,58 @@ perform" error. \Default: -E: readonly off +> readonly off H4: replica -.{{EX:replica host=[:]}} -..{{EX:"binddn="}} -..{{EX:bindmethod={ simple | kerberos }}} -..{{EX:[credentials=]}} -..{{EX:[srvtab=]}} +> replica host=[:] +> [bindmethod={simple|kerberos|sasl}] +> ["binddn="] +> [saslmech=] +> [authcid=] +> [authzid=] +> [credentials=] +> [srvtab=] This directive specifies a replication site for this database. The -{{EX: host=}} parameter specifies a host and optionally a port where +{{EX:host=}} parameter specifies 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) is used. -The {{EX: binddn=}} parameter gives the DN to bind as for updates to +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 -"rootdn" in the slave's config file. It must also match the -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 quotes. +{{EX:rootdn}} in the slave's config file. It must also match the +{{EX:updatedn}} directive in the slave slapd's config file. Since DNs are +likely to contain embedded spaces, the entire {{EX:"binddn="}} +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 integrity +and privacy protections are in place (e.g. TLS or IPSEC). Simple +authentication requires specification of {{EX:binddn}} and +{{EX:credentials}} parameters. -{{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. +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: credentials=}} parameter, which is only required if using -simple authentication, gives the password for binddn on the -slave slapd. +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: srvtab=}} parameter, which is only required if using -kerberos, specifies the filename which holds the kerberos key -for the slave slapd. If omitted, {{EX: /etc/srvtab}} is used. +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 @@ -309,41 +343,48 @@ 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: -E: 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. -E: rootkrbname admin@openldap.org 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: -E: rootpw secret +> 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 @@ -354,301 +395,385 @@ definition. \Example: -E: 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. -E: 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: -E: 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: -E: 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: -E: index default pres,eq -E: index objectclass,uid -E: 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. The third -line causes equality, substring, and approximate filters to be -maintained for cn and sn attributes. +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: -E: mode 0600 - +> cachesize 1000 -H3: Shell Backend-Specific Directives - -E: bind - -E: unbind - -E: search - -E: compare - -E: modify - -E: modrdn - -E: add +H4: dbcachesize -E: delete +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. -E: 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: -E: 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: -E: 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. -E: bind +By default, no indices are maintained. It is generally advised +that minimally an equality index upon objectClass be maintained. -E: unbind +> index objectClass eq -E: search -E: compare -E: modify +H4: mode -E: modrdn +This directive specifies the file protection mode that newly +created database index files should have. -E: add +\Default: -E: delete +> mode 0600 -E: abandon -These directives specify the name of the proc (function) in the tcl script -specified in 'scriptpath' to execute in response to the given LDAP -operation. +H2: Access Control -\Example: +Access to slapd entries and attributes is controlled by the +access configuration file directive. The general form of an +access line is: -E: search proc_search +> ::= 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}+ +> ::= [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. -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: tclrealm +H3: What to control access to -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 tclrealm is specified, it is put into the -"default" realm. +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.= +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}}. -H2: Access Control +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). -Access to slapd entries and attributes is controlled by the -access configuration file directive. The general form of an -access line is: +For example, if the directory contained entries named: -E: ::= access to -E: [ by ]+ -E: ::= * | [ dn[.]= ] [ filter= ] -E: [ attrs= ] -E: ::= regex | base | one | subtree | children -E: ::= | , -E: ::= | entry | children -E: ::= [ * | anonymous | users | self | dn[.]= ] -E: [ dnattr= ] -E: [ group[/[/][.]]= ] -E: [ peername[.]= ] [ sockname[.]= ] -E: [ domain[.]= ] [ sockurl[.]= ] -E: [ set= ] -E: [ aci= ] -E: ::= regex | exact | base | one | subtree | children -E: ::= regex | exact -E: ::= [self]{|} -E: ::= none | auth | compare | search | read | write -E: ::= {=|+|-}{w|r|s|c|x}+ -E: ::= [ stop | continue | break ] - -where the part selects the entries and/or attributes to -which the access applies, the part specifies which -entities are granted access, and the part specifies -the access granted. Multiple triplets are -supported, allowing many entities to be granted different -access to the same set of entries and attributes. +> 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. -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: +Entries may also be selected using a filter: -E: dn= +> by filter= -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". +where is a string representation of an LDAP +search filter, as described in {{REF:RFC2254}}. For example: -Or, entries may be selected by a filter matching some -attribute(s) in the entry: +> by filter=(objectClass=person) -E: filter= +Note that entries may be selected by both DN and filter by +including both qualifiers in the clause. -where is a string representation of an LDAP -search filter, as described in RFC 2254. +> by dn.one="ou=people,o=suffix" filter=(objectClass=person) -The special entry selector "*" is used to select any entry, -and is a convenient shorthand for the equivalent "dn=.*" selector. +Attributes within an entry are selected by including a comma-separated +list of attribute names in the selector: -Attributes within an entry are selected by including a -comma-separated list of attribute names in the -selector: +> attrs= -E: attrs= +A specific value of an attribute is selected by using a single +attribute name and also using a value selector: -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. +> attrs= val[.