X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=doc%2Fguide%2Fadmin%2Fslapdconfig.sdf;h=7b6bf2464c9e85849190237aca9b42dcf7620428;hb=14745b74d29fe80f2988908b3f3fa3a4532937d9;hp=739475bbb8d2e89f82feef9f3f1121b6e52b9ca5;hpb=3149fc4f41bc53ea96d62c3e46681ea76f1a6b22;p=openldap diff --git a/doc/guide/admin/slapdconfig.sdf b/doc/guide/admin/slapdconfig.sdf index 739475bbb8..7b6bf2464c 100644 --- a/doc/guide/admin/slapdconfig.sdf +++ b/doc/guide/admin/slapdconfig.sdf @@ -1,5 +1,5 @@ # $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 @@ -7,7 +7,7 @@ H1: The slapd Configuration File 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 -{{I:slapd.conf}}(5) file, normally installed in the +{{slapd.conf}}(5) file, normally installed in the {{EX:/usr/local/etc/openldap}} directory. An alternate configuration file can be specified via a @@ -18,12 +18,12 @@ 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 @@ -80,8 +80,8 @@ its use. H3: Global Directives Directives described in this section apply to all backends -and databases, unless specifically overridden in a backend or -database definition. Arguments to directives should be replaced +and databases unless specifically overridden in a backend or +database definition. Arguments that should be replaced by actual text are shown in brackets {{EX:<>}}. @@ -92,11 +92,16 @@ 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> @@ -104,27 +109,10 @@ This directive defines an attribute type. Please see the {{SECT:Schema Specification}} chapter for information regarding how to use this directive. -H4: defaultaccess { none | compare | search | read | write } - -This directive specifies the default access to grant requesters -when no {{EX:access}} directives have been specified. Access -levels implies all lesser access levels (e.g., read access -implies search and compare but no write). - -Note: It is recommend that the {{EX:access}} directive be used -to specify access control. See the {{SECT:Access Control}} -section of this chapter for information regarding the {{EX:access}} -directive. - -\Default: - -E: defaultaccess read - - H4: idletimeout Specify the number of seconds to wait before forcibly closing -an idle client connections. A idletimeout of 0, the default, +an idle client connection. An idletimeout of 0, the default, disables this feature. @@ -143,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" @@ -229,24 +217,59 @@ exceeded timelimit will be returned. H3: General Backend Directives +Directives in this section apply only to the backend in which +they are defined. They are supported by every type of backend. +Backend directives apply to all databases instances of the +same type and, depending on the directive, may be overridden +by database directives. + +H4: backend + +This directive marks the beginning of a backend 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 only apply to the database in which +Directives in this section apply only to the database in which they are defined. They are supported by every type of database. -H4: database +H4: database -This directive marks the beginning of a new database instance -definition. should be one of ldbm, shell, or -passwd, depending on which backend will serve the -database. +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 ldbm +> database bdb -This marks the beginning of a new LDBM backend database -instance definition. +This marks the beginning of a new {{TERM:BDB}} database instance +declaration. H4: readonly { on | off } @@ -262,8 +285,11 @@ perform" error. H4: replica > replica host=[:] -> "binddn=" -> [bindmethod={ simple | kerberos }] +> [bindmethod={simple|kerberos|sasl}] +> ["binddn="] +> [saslmech=] +> [authcid=] +> [authzid=] > [credentials=] > [srvtab=] @@ -277,26 +303,34 @@ 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. -The {{EX:credentials=}} parameter, which is only required if using -simple authentication, gives the password for {{EX:binddn}} on the -slave slapd. Simple authentication is deprecated in favor of -SASL based authentication services. +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:srvtab=}} parameter is deprecated in favor of SASL -based authentication services. +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. -See the {{SECT:Replication}} chapter for more information on how to -use this directive. +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 @@ -309,8 +343,8 @@ However, you can also use it to generate a transaction log, if slurpd is not running. In this case, you will need to periodically truncate the file, since it will grow indefinitely otherwise. -See the {{SECT:Replication}} chapter for more information on how to -use this directive. +See the chapter entitled {{SECT:Replication with slurpd}} for more +information on how to use this directive. H4: rootdn @@ -318,29 +352,39 @@ 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 the directory. The DN may refer to a SASL -identity. +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" +> rootdn "cn=Manager,dc=example,dc=com" SASL-based Example: -> rootdn "uid=root@EXAMPLE.COM" +> 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 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 deprecated in favor of SASL based authentication. +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 @@ -351,33 +395,106 @@ 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: 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. + + H4: updatedn -This directive is only applicable in a slave slapd. It specifies the -DN allowed to make changes to the replica. This may be the -the DN slurpd binds as when making changes to the replica or -the DN associated with a SASL identity. +This directive is only applicable in a slave slapd. It specifies +the DN allowed to make changes to the replica. This may be the DN +{{slurpd}}(8) binds as when making changes to the replica or the DN +associated with a SASL identity. Entry-based Example: -> updatedn "cn=Update Daemon, dc=example, dc=com" +> updatedn "cn=Update Daemon,dc=example,dc=com" SASL-based Example: -> updatedn "uid=slurpd@EXAMPLE.COM" +> updatedn "uid=slurpd,cn=example.com,cn=digest-md5,cn=auth" -See the {{SECT:Replication}} chapter for more information on how to -use this directive. +See the {{SECT:Replication with slurpd}} chapter for more information +on how to use this directive. H4: updateref @@ -388,14 +505,32 @@ If specified multiple times, each {{TERM:URL}} is provided. \Example: -> update ldap://master.example.net +> 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 Backend-Specific Directives +H3: LDBM Database Directives -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. +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 @@ -414,7 +549,7 @@ 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. +modifies or when building indices. \Default: @@ -430,39 +565,48 @@ of data security. H4: dbnosync -This option causes on-disk database contents not be immediately +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 security. +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 indexes live. +containing the database and associated indices live. \Default: -> directory /usr/local/var/openldap-ldbm +> directory /usr/local/var/openldap-data H4: index { | default} [pres,eq,approx,sub,none] -This directive specifies the indexes to maintain for the given +This directive specifies the indices to maintain for the given attribute. If only an {{EX:}} is given, the default -indexes are maintained. - +indices are maintained. \Example: > index default pres,eq -> index objectClass,uid -> index cn,sn eq,sub,approx +> index uid +> index cn,sn pres,eq,sub +> index objectClass eq + +The first line sets the default set of indices to maintain to +present and equality. The second line causes the default (pres,eq) +set of indices to be maintained for the {{EX:uid}} attribute type. +The third line causes present, equality, and substring indices to +be maintained for {{EX:cn}} and {{EX:sn}} attribute types. The +fourth line causes an equality index for the {{EX:objectClass}} +attribute type. + +By default, no indices are maintained. It is generally advised +that minimally an equality index upon objectClass be maintained. + +> index objectClass eq + -The first line sets the default to indices to maintain to present -and equality. The second line causes the default (pres,eq) set -of indices to be maintained for {{EX:objectClass}} and {{EX:uid}} attribute -types. The third line causes equality, substring, and approximate -filters to be maintained for {{EX:cn}} and {{EX:sn}} attribute types. H4: mode @@ -474,23 +618,6 @@ created database index files should have. > mode 0600 - -H3: Other Backend and Databases - -{{slapd}}(8) supports a number of other backend database types. - -!block table; align=Center; coltags="EX,N"; \ - title="Table 5.2: Backend Database Types" -Types Description -passwd Provides read-only access to {{F:/etc/passwd}} -shell Shell (extern program) backend -sql SQL Programmable backend -!endblock - -See {{slapd.conf}}(5) for details. - - - H2: Access Control Access to slapd entries and attributes is controlled by the @@ -499,73 +626,117 @@ 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: -> dn= +> by * +> by dn[.]= +> by dn.= -Note: The DN pattern specified should be "normalized", -meaning that there should be no extra spaces, and commas -should be used to separate components. An example -normalized DN is "cn=Babs Jensen,dc=example,dc=com". -An example of a non-normalized DN is -"cn=Babs Jensen; dc=example, dc=com". +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}}. -Or, entries may be selected by a filter matching some -attribute(s) in the entry: +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). -> filter= +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: + +> by filter= where is a string representation of an LDAP -search filter, as described in {{REF:RFC2254}}. +search filter, as described in {{REF:RFC2254}}. For example: -Attributes within an entry are selected by including a -comma-separated list of attribute names in the -selector: +> by filter=(objectClass=person) + +Note that entries may be selected by both DN and filter by +including both qualifiers in the clause. + +> by 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= -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. +A specific value of an attribute is selected by using a single +attribute name and also using a value selector: + +> attrs= val[.