From: Pierangelo Masarati Date: Wed, 1 May 2002 16:38:30 +0000 (+0000) Subject: second round at ITS#1749 X-Git-Tag: OPENLDAP_REL_ENG_2_MP~129 X-Git-Url: https://git.sur5r.net/?a=commitdiff_plain;h=1aa96af216b8b7be1beaa0b42d6a49c9bda020f9;p=openldap second round at ITS#1749 --- diff --git a/doc/man/man5/slapd-bdb.5 b/doc/man/man5/slapd-bdb.5 index 519b1311e9..630aecb545 100644 --- a/doc/man/man5/slapd-bdb.5 +++ b/doc/man/man5/slapd-bdb.5 @@ -1,4 +1,4 @@ -.TH SLAPD-BDB 5 "28 April 2002" "OpenLDAP LDVERSION" +.TH SLAPD-BDB 5 "30 April 2002" "OpenLDAP LDVERSION" .\" Copyright 1998-2002 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .\" $OpenLDAP$ @@ -13,11 +13,14 @@ is the recommended backend for a normal slapd database. It uses the Sleepycat BerkelyDB package to store data. It makes extensive use of indexing and caching to speed data access. .SH CONFIGURATION -The -.BR slapd.conf (5) -options in this category apply to the BDB databases. +These +.B slapd.conf +options apply to the BDB backend database. That is, they must follow a "database bdb" line and come before any subsequent "backend" or "database" lines. +Other database options are described in the +.BR slapd.conf (5) +manual page. .TP .B cachesize Specify the size in entries of the in-memory cache maintained @@ -91,6 +94,8 @@ The default is the same as Specify the file protection mode that newly created database index files should have. The default is 0600. +.SH FILES +ETCDIR/slapd.conf .SH SEE ALSO .BR slapd.conf (5), .BR slapd (8), diff --git a/doc/man/man5/slapd-ldbm.5 b/doc/man/man5/slapd-ldbm.5 index 95ca923d0a..6affd08585 100644 --- a/doc/man/man5/slapd-ldbm.5 +++ b/doc/man/man5/slapd-ldbm.5 @@ -1,4 +1,4 @@ -.TH SLAPD-LDBM 5 "28 April 2002" "OpenLDAP LDVERSION" +.TH SLAPD-LDBM 5 "30 April 2002" "OpenLDAP LDVERSION" .\" Copyright 1998-2002 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .\" $OpenLDAP$ @@ -9,18 +9,18 @@ ETCDIR/slapd.conf .SH DESCRIPTION The LDBM backend to .BR slapd (8) -is a database that makes -extensive use of indexing and caching to speed data access. -.\" .SH LDBM BACKEND-SPECIFIC OPTIONS -.\" Options in this category only apply to the LDBM backend. -.\" That is, they must follow "backend ldbm" line and come before -.\" any subsequent "backend" or "database" lines. +is a database which uses one of BerkelyDB, Gnu DBM, MDBM or NDBM to +store data. +It makes extensive use of indexing and caching to speed data access. .SH CONFIGURATION -The -.BR slapd.conf (5) -options in this category apply to the LDBM databases. +These +.B slapd.conf +options apply to the LDBM backend database. That is, they must follow a "database ldbm" line and come before any subsequent "backend" or "database" lines. +Other database options are described in the +.BR slapd.conf (5) +manual page. .TP .B cachesize Specify the size in entries of the in-memory cache maintained @@ -114,6 +114,8 @@ Note: changing index settings requires rebuilding indices, see Specify the file protection mode that newly created database index files should have. The default is 0600. +.SH FILES +ETCDIR/slapd.conf .SH SEE ALSO .BR slapd.conf (5), .BR slapd (8), diff --git a/doc/man/man5/slapd-meta.5 b/doc/man/man5/slapd-meta.5 index b739849907..26a1085b31 100644 --- a/doc/man/man5/slapd-meta.5 +++ b/doc/man/man5/slapd-meta.5 @@ -1,4 +1,4 @@ -.TH SLAPD_META 5 "28 April 2002" "OpenLDAP LDVERSION" +.TH SLAPD_META 5 "30 April 2002" "OpenLDAP LDVERSION" .\" Copyright 1998-2002 The OpenLDAP Foundation, All Rights Reserved. .\" Copying restrictions apply. See the COPYRIGHT file. .\" Copyright 2001, Pierangelo Masarati, All rights reserved. @@ -41,11 +41,14 @@ In the examples section, some typical scenarios will be discussed. There are examples in various places in this document, as well as in the slapd/back-meta/data/ directory in the OpenLDAP source tree. .SH CONFIGURATION -The -.BR slapd.conf (5) -options in this category apply to the META backend database. +These +.B slapd.conf +options apply to the META backend database. That is, they must follow a "database meta" line and come before any subsequent "backend" or "database" lines. +Other database options are described in the +.BR slapd.conf (5) +manual page. .LP Note: as with the .B ldap @@ -68,7 +71,7 @@ for every and .B meta backend. -.SH "SPECIAL CONFIGURATION DIRECTIVES" +.SH SPECIAL CONFIGURATION DIRECTIVES Target configuration starts with the "uri" directive. All the configuration directives that are not specific to targets should be defined first for clarity, including those that are common @@ -87,12 +90,12 @@ This directive can also be used when processing targets to mark a specific target as default. .TP .B dncache-ttl {forever|disabled|} -This directive sets the time-to-live of the dn cache. -This caches the target that holds a given dn to speed up target +This directive sets the time-to-live of the DN cache. +This caches the target that holds a given DN to speed up target selection in case multiple targets would result from an uncached -search; forever means cache never expires; disabled means no dn +search; forever means cache never expires; disabled means no DN caching; otherwise a valid ( > 0 ) ttl in seconds is required. -.SH "TARGET SPECIFICATION" +.SH TARGET SPECIFICATION Target specification starts with a "uri" directive: .TP .B uri ://[[:]]/ @@ -100,14 +103,14 @@ The "server" directive that was allowed in the LDAP backend (although deprecated) has been discarded in the Meta backend. The part can be anything ldap_initialize(3) accepts ({ldap|ldaps|ldapi} and variants); and may be omitted, -defaulting to whatever is set in /etc/ldap.conf +defaulting to whatever is set in /etc/ldap.conf. The part is mandatory. It must end with one of the naming contexts defined for the backend, e.g.: .LP .nf - suffix "dc=foo,dc=com" - uri "ldap://x.foo.com/dc=x,dc=foo,dc=com" + suffix "\fBdc=foo,dc=com\fP" + uri "ldap://x.foo.com/dc=x,\fBdc=foo,dc=com\fP" .fi .LP The part doesn't need to be unique across the targets; @@ -120,8 +123,8 @@ The optional number marks target as the default one, starting from 1. Target must be defined. .TP -.B binddn -This directive, as in the LDAP backend, allows to define the dn that is +.B binddn "" +This directive, as in the LDAP backend, allows to define the DN that is used to query the target server for acl checking; it should have read access on the target server to attributes used on the proxy for acl checking. @@ -132,16 +135,16 @@ check permissions. This directive sets the password for acl checking in conjunction with the above mentioned "binddn" directive. .TP -.B pseudorootdn -This directive, if present, sets the dn that will be substituted to -the bind dn if a bind with the backend's "rootdn" succeeds. +.B pseudorootdn "" +This directive, if present, sets the DN that will be substituted to +the bind DN if a bind with the backend's "rootdn" succeeds. The true "rootdn" of the target server ought not be used; an arbitrary -administrative dn should used instead. +administrative DN should used instead. .TP -.B pseudorootpw +.B pseudorootpw "" This directive sets the credential that will be used in case a bind with the backend's "rootdn" succeeds, and the bind is propagated to -the target using the "pseudorootdn" dn. +the target using the "pseudorootdn" DN. .LP Note: cleartext credentials must be supplied here; as a consequence, using the pseudorootdn/pseudorootpw directives is inherently unsafe. @@ -149,7 +152,7 @@ using the pseudorootdn/pseudorootpw directives is inherently unsafe. .B rewrite* ... The rewrite options are described in the "REWRITING" section. .TP -.B suffixmassage +.B suffixmassage "" "" All the directives starting with "rewrite" refer to the rewrite engine that has been added to slapd. The "suffixmassage" directive was introduced in the LDAP backend to @@ -170,7 +173,7 @@ See the "REWRITING" section. This maps object classes and attributes as in the LDAP backend. See .BR slapd-ldap (5). -.SH "SCENARIOS" +.SH SCENARIOS A powerful (and in some sense dangerous) rewrite engine has been added to both the LDAP and Meta backends. While the former can gain limited beneficial effects from rewriting @@ -199,7 +202,8 @@ spawning two searches to the targets. but they'd present as a single DIT [Caveat: uniqueness of (massaged) entries among the two servers is assumed; integrity checks risk to incur in excessive overhead and have -not been implemented]. Say we have "dc=bar,dc=org" and "o=Foo,c=US", +not been implemented]. +Say we have "dc=bar,dc=org" and "o=Foo,c=US", and we'd like them to appear as branches of "dc=foo,dc=com", say "dc=a,dc=foo,dc=com" and "dc=b,dc=foo,dc=com". Then we need to configure our Meta backend as: @@ -253,7 +257,7 @@ sharing the same naming context: All the previous considerations hold, except that now there is no way to unambiguously resolve a DN. In this case, all the operations that require an unambiguous target -selection will fail unless the dn is already cached or a default +selection will fail unless the DN is already cached or a default target has been set. .SH ACLs Note on ACLs: at present you may add whatever ACL rule you desire @@ -367,11 +371,11 @@ See The string substitution happens according to a substitution pattern. .TP .B - -substring substitution is allowed with the syntax `\\d' where `d' is a +substring substitution is allowed with the syntax `\ed' where `d' is a digit ranging 0-9 (0 is the full match). I see that 0-9 digit expansion is a widely accepted practise; however there is no technical reason to use such a strict limit. -A syntax of the form `\\{ddd}' should be fine if there is any need to +A syntax of the form `\e{ddd}' should be fine if there is any need to use a higher number of possible submatches. .TP .B - @@ -385,43 +389,20 @@ ldap(!), math(?) and so on maps `a la sendmail'. .B - subroutine invocation will make it possible to rewrite a submatch in terms of the output of another rewriteContext. -.Sh "Old syntax:" -.TP -.B `\\' {0-9} [ `{' [ `(' `)' ] `}' ] -where is the name of a built-in map, and are optional -arguments to the map, if the map requires them. -The following experimental maps have been implemented: -.TP -.B \\n{xpasswd} -maps the n-th substring match as uid to the gecos field in -/etc/passwd; -.TP -.B \\n{xfile(/absolute/path)} -maps the n-th substring match to a `key value' style plain text file. -.TP -.B \\n{xldap(ldap://url/with?%0?in?filter) -maps the n-th substring match to an attribute retrieved by means of an -LDAP url with substitution of %0 in the filter (NOT IMPL.) -.SH "New scheme:" -everything starting with `\\' requires substitution; -.LP -the only obvious exception is `\\\\', which is left as is; +.SH "Substitution Pattern Syntax:" +everything starting with `%' requires substitution; .LP -the basic substitution is `\\d', where `d' is a digit; -0 means the whole string, while 1-9 is a submatch; +the only obvious exception is `%%', which is left as is; .LP -in the outdated schema, the digit may be optionally -followed by a `{', which means pipe the submatch into -the map described by the string up to the following `}'; +the basic substitution is `%d', where `d' is a digit; +0 means the whole string, while 1-9 is a submatch, as discussed in +.BR regex (7); .LP -the output of the map is used instead of the submatch; -.LP -in the new schema, a `\\' followed by a `{' invokes an -advanced substitution scheme. +a `%' followed by a `{' invokes an advanced substitution. The pattern is: .LP .nf - `\\' `{' [{ }] `(' `)' `}' + `%' `{' [ ] `(' `)' `}' .fi .LP where must be a legal name for the map, i.e. @@ -431,8 +412,8 @@ where must be a legal name for the map, i.e. ::= `>' `|' `&' `&&' `*' `**' `$' .fi .LP -and must be a legal substitution -schema, with no limits on the nesting level. +and must be a legal substitution +pattern, with no limits on the nesting level. .LP The operators are: .TP @@ -446,32 +427,47 @@ defined command name (NOT IMPL.) .TP .B & variable assignment; defines a variable in the running -operation structure which can be dereferenced later (NOT IMPL.) +operation structure which can be dereferenced later; operator +.B & +assigns a variable in the rewrite context scope; operator +.B && +assigns a variable that scopes the entire session, e.g. its value +can be derefenced later by other rewrite contexts .TP .B * variable dereferencing; must refer to a variable that is -defined and assigned for the running operation (NOT IMPL.) +defined and assigned for the running operation; operator +.B * +dereferences a variable scoping the rewrite context; operator +.B ** +dereferences a variable scoping the whole session, e.g. the value +is passed across rewrite contexts .TP .B $ parameter dereferencing; must refer to an existing parameter; the idea is to make some run-time parameters set by the system -available to the rewrite engine, as the client host name, the bind dn -if any, constant parameters initialized at config time, and so on (NOT -IMPL.) -.LP -Note: as the slapd parsing routines escape backslashes ('\\'), -a double backslash is required inside substitution patterns. -To overcome the resulting heavy notation, the substitution escaping -has been delegated to the `%' symbol, which should be used -instead of `\\' in string substitution patterns. -The symbol can be altered at will by redefining the related macro in -"rewrite-int.h". -In the current snapshot, all the `\\' on the left side of each rule -(the regex pattern) must be converted in `\\\\'; all the `\\' on the -right side of the rule (the substitution pattern) must be turned into -`%'. -In the following examples, the original (more readable) syntax is -used. +available to the rewrite engine, as the client host name, the bind DN +if any, constant parameters initialized at config time, and so on; +no parameter is currently set by either +.B back\-ldap +or +.BR back\-meta , +but constant parameters can be defined in the configuration file +by using the +.B rewriteParam +directive. +.LP +Substitution escaping has been delegated to the `%' symbol, +which is used instead of `\e' in string substitution patterns +because `\e' is already escaped by slapd's low level parsing routines; +as a consequence, +.BR regex (7) +escaping requires two `\e' symbols, e.g. `\fB.*\e.foo\e.bar\fP' must +be written as `\fB.*\e\e.foo\e\e.bar\fP'. +.\" +.\" The symbol can be altered at will by redefining the related macro in +.\" "rewrite-int.h". +.\" .SH "Rewrite context:" A rewrite context is a set of rules which are applied in sequence. The basic idea is to have an application initialize a rewrite @@ -480,17 +476,15 @@ contexts; when string rewriting is required, one invokes the appropriate rewrite context with the input string and obtains the newly rewritten one if no errors occur. .LP -An interesting application, in the LDAP backend or in slapd itself, -could associate each basic server operation to a rewrite context -(most of them possibly aliasing the default one). -Then, DN rewriting could take place at any invocation of a backend -operation. +Each basic server operation is associated to a rewrite context; +they are divided in two main groups: client \-> server and +server \-> client rewriting. .LP client -> server: .LP .nf - default if defined and no specific - context is available + (default) if defined and no specific context + is available bindDn bind searchBase search searchFilter search @@ -506,6 +500,7 @@ server -> client: .LP .nf searchResult search (only if defined; no default) + matchedDn all ops (only if defined; no default; NOT IMPL.) .fi .LP .SH "Basic configuration syntax" @@ -515,7 +510,7 @@ If `on', the requested rewriting is performed; if `off', no rewriting takes place (an easy way to stop rewriting without altering too much the configuration file). .TP -.B rewriteContext [ alias ] +.B rewriteContext "[ alias ]" is the name that identifies the context, i.e. the name used by the application to refer to the set of rules it contains. It is used also to reference sub contexts in string rewriting. @@ -523,23 +518,23 @@ A context may aliase another one. In this case the alias context contains no rule, and any reference to it will result in accessing the aliased one. .TP -.B rewriteRule [ ] +.B rewriteRule "" "" "[ ]" Determines how a tring can be rewritten if a pattern is matched. Examples are reported below. .SH "Additional configuration syntax:" .TP -.B rewriteMap [ ] +.B rewriteMap "" "" "[ ]" Allows to define a map that transforms substring rewriting into something else. The map is referenced inside the substitution pattern of a rule. .TP .B rewriteParam Sets a value with global scope, that can be dereferenced by the -command `\\{$paramName}'. +command `%{$paramName}'. .TP .B rewriteMaxPasses -Sets the maximum number of total rewriting passes taht can be -performed in a signle rewriting operation (to avoid loops). +Sets the maximum number of total rewriting passes that can be +performed in a single rewrite operation (to avoid loops). .SH "Configuration examples:" .nf # set to `off' to disable rewriting @@ -550,50 +545,57 @@ performed in a signle rewriting operation (to avoid loops). # to `dc=home,dc=net' to `dc=OpenLDAP, dc=org' rewriteRule "(.*)dc=home,[ ]?dc=net" - "\\1dc=OpenLDAP, dc=org" ":" + "%1dc=OpenLDAP, dc=org" ":" + + # since a pretty/normalized DN does not include spaces + # after rdn separators, e.g. `,', this rule suffices: + + rewriteRule "(.*)dc=home,dc=net" + "%1dc=OpenLDAP,dc=org" ":" # Start a new context (ends input of the previous one). - # This rule adds blancs between dn parts if not present. - rewriteContext addBlancs - rewriteRule "(.*),([^ ].*)" "\\1, \\2" + # This rule adds blanks between DN parts if not present. + rewriteContext addBlanks + rewriteRule "(.*),([^ ].*)" "%1, %2" - # This one eats blancs - rewriteContext eatBlancs - rewriteRule "(.*),[ ](.*)" "\\1,\\2" + # This one eats blanks + rewriteContext eatBlanks + rewriteRule "(.*),[ ](.*)" "%1,%2" # Here control goes back to the default rewrite # context; rules are appended to the existing ones. - # anything that gets here is piped into rule `addBlancs' + # anything that gets here is piped into rule `addBlanks' rewriteContext default - rewriteRule ".*" "\\{>addBlancs(\\0)}" ":" + rewriteRule ".*" "%{>addBlanks(%0)}" ":" # Anything with `uid=username' is looked up in # /etc/passwd for gecos (I know it's nearly useless, - # but it is there just to test something fancy!). Note - # the `I' flag that leaves `uid=username' in place if - # `username' does not have a valid account, and the + # but it is there just as a guideline to implementing + # custom maps). + # Note the `I' flag that leaves `uid=username' in place + # if `username' does not have a valid account, and the # `:' that forces the rule to be processed exactly once. rewriteContext uid2Gecos rewriteRule "(.*)uid=([a-z0-9]+),(.+)" - "\\1cn=\\2{xpasswd},\\3" "I:" + "%1cn=%2{xpasswd},%3" "I:" - # Finally, in a bind, if one uses a `uid=username' dn, + # Finally, in a bind, if one uses a `uid=username' DN, # it is rewritten in `cn=name surname' if possible. rewriteContext bindDn - rewriteRule ".*" "\\{>addBlancs(\\{>uid2Gecos(\\0)})}" ":" + rewriteRule ".*" "%{>addBlanks(%{>uid2Gecos(%0)})}" ":" # Rewrite the search base according to `default' rules. rewriteContext searchBase alias default - # Search results with OpenLDAP dn are rewritten back with + # Search results with OpenLDAP DN are rewritten back with # `dc=home,dc=net' naming context, with spaces eaten. rewriteContext searchResult rewriteRule "(.*[^ ]?)[ ]?dc=OpenLDAP,[ ]?dc=org" - "\\{>eatBlancs(\\1)}dc=home,dc=net" ":" + "%{>eatBlanks(%1)}dc=home,dc=net" ":" - # Bind with email instead of full dn: we first need - # an ldap map that turns attributes into a dn (the - # filter is provided by the substitution string): + # Bind with email instead of full DN: we first need + # an ldap map that turns attributes into a DN (the + # filter is appended by the ldap map substitution): rewriteMap ldap attr2dn "ldap://host/dc=my,dc=org?dn?sub" # Then we need to detect emails; note that the rule @@ -603,18 +605,18 @@ performed in a signle rewriting operation (to avoid loops). # regular DNs, because the definition of a bindDn # rewrite context overrides the default definition. rewriteContext bindDn - rewriteRule "(mail=[^,]+@[^,]+)" "\\{attr2dn(\\1)}" "@I" + rewriteRule "^mail=[^,]+@[^,]+$" "%{attr2dn(%0)}" "@I" - # This is a rather sophisticate example. It massages a + # This is a rather sophisticated example. It massages a # search filter in case who performs the search has # administrative privileges. First we need to keep - # track of the bind dn of the incoming request: + # track of the bind DN of the incoming request: rewriteContext bindDn - rewriteRule ".+" "\\{**&binddn(\\0)}" ":" + rewriteRule ".+" "%{&&binddn(%0)}%0" ":" # A search filter containing `uid=' is rewritten only - # if an appropriate dn is bound. - # To do this, in the first rule the bound dn is + # if an appropriate DN is bound. + # To do this, in the first rule the bound DN is # dereferenced, while the filter is decomposed in a # prefix, the argument of the `uid=', and in a # suffix. A tag `<>' is appended to the DN. If the DN @@ -626,35 +628,37 @@ performed in a signle rewriting operation (to avoid loops). # `cn', but only if the request comes from a possible # `dn: cn=Web auth, ou=admin, dc=home, dc=net' user. rewriteContext searchFilter - rewriteRule "(.*\\()uid=([a-z0-9_]+)(\\).*)" - "\\{**binddn}<>\\{&prefix(\\1)}\\{&arg(\\2)}\\{&suffix(\\3)}" + rewriteRule "(.*\e\e()uid=([a-z0-9_]+)(\e\e).*)" + "%{**binddn}<>%{&prefix(%1)}%{&arg(%2)}%{&suffix(%3)}" ":I" - rewriteRule "[^,]+,[ ]?ou=admin,[ ]?dc=home,[ ]?dc=net" - "\\{*prefix}|(uid=\\{*arg})(cn=\\{*arg})\\{*suffix}" "@I" - rewriteRule ".*<>" "\\{*prefix}uid=\\{*arg}\\{*suffix}" + rewriteRule "[^,]+,ou=admin,dc=home,dc=net" + "%{*prefix}|(uid=%{*arg})(cn=%{*arg})%{*suffix}" "@I" + rewriteRule ".*<>" "%{*prefix}uid=%{*arg}%{*suffix}" ":" .fi -.SH "LDAP Proxy resolution (a possible evolution of slapd-ldap(5):" -In case the rewritten dn is an LDAP URL, the operation is initiated -towards the host[:port] indicated in the url, if it does not refer +.SH "LDAP Proxy resolution (a possible evolution of slapd\-ldap(5)):" +In case the rewritten DN is an LDAP URI, the operation is initiated +towards the host[:port] indicated in the uri, if it does not refer to the local server. E.g.: .LP .nf - rewriteRule \'^cn=root,.*\' \'\\0\' \'G{3}\' - rewriteRule \'^cn=[a-l].*\' \'ldap://ldap1.my.org/\\0\' \'@\' - rewriteRule \'^cn=[m-z].*\' \'ldap://ldap2.my.org/\\0\' \'@\' - rewriteRule \'.*\' \'ldap://ldap3.my.org/\\0\' \'@\' + rewriteRule '^cn=root,.*' '%0' 'G{3}' + rewriteRule '^cn=[a-l].*' 'ldap://ldap1.my.org/%0' '@' + rewriteRule '^cn=[m-z].*' 'ldap://ldap2.my.org/%0' '@' + rewriteRule '.*' 'ldap://ldap3.my.org/%0' '@' .fi .LP (Rule 1 is simply there to illustrate the `G{n}' action; it could have been written: .LP .nf - rewriteRule \'^cn=root,.*\' \'ldap://ldap3.my.org/\\0\' \'@\' + rewriteRule '^cn=root,.*' 'ldap://ldap3.my.org/%0' '@' .fi .LP with the advantage of saving one rewrite pass ...) -.SH "SEE ALSO" +.SH FILES +ETCDIR/slapd.conf +.SH SEE ALSO .BR slapd.conf (5), .BR slapd\-ldap (5), .BR slapd (8), diff --git a/doc/man/man5/slapd-null.5 b/doc/man/man5/slapd-null.5 index 350b7dbb3a..d215b370b3 100644 --- a/doc/man/man5/slapd-null.5 +++ b/doc/man/man5/slapd-null.5 @@ -1,4 +1,4 @@ -.TH SLAPD-NULL 5 "25 April 2002" "OpenLDAP LDVERSION" +.TH SLAPD-NULL 5 "30 April 2002" "OpenLDAP LDVERSION" .\" $OpenLDAP$ .SH NAME slapd-null \- Null backend to slapd @@ -20,9 +20,9 @@ is surely the most useful part of .br Inspired by the /dev/null device. .SH CONFIGURATION -The -.BR slapd.conf (5) -option in this category applies to the NULL backend database. +This +.B slapd.conf +option applies to the NULL backend database. That is, it must follow a "database null" line and come before any subsequent "database" lines. Other database options are described in the @@ -40,7 +40,8 @@ Here is a possible slapd.conf extract using the Null backend: suffix "cn=Nothing" bind on .fi -.LP +.SH FILES +ETCDIR/slapd.conf .SH SEE ALSO .BR slapd.conf (5), .BR slapd (8). diff --git a/doc/man/man5/slapd-passwd.5 b/doc/man/man5/slapd-passwd.5 index 1cf6bf6d42..98f94e88fa 100644 --- a/doc/man/man5/slapd-passwd.5 +++ b/doc/man/man5/slapd-passwd.5 @@ -1,4 +1,4 @@ -.TH SLAPD-PASSWD 5 "25 April 2002" "OpenLDAP LDVERSION" +.TH SLAPD-PASSWD 5 "30 April 2002" "OpenLDAP LDVERSION" .\" Copyright 1998-2002 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .\" $OpenLDAP$ @@ -13,9 +13,9 @@ serves up the user account information listed in the system .BR passwd (5) file. .SH CONFIGURATION -The -.BR slapd.conf (5) -options in this category apply to the PASSWD backend database. +These +.B slapd.conf +options apply to the PASSWD backend database. That is, they must follow a "database passwd" line and come before any subsequent "backend" or "database" lines. Other database options are described in the @@ -26,6 +26,10 @@ manual page. Specifies an alternate passwd file to use. The default is .BR /etc/passwd . +.SH FILES +ETCDIR/slapd.conf +.br +/etc/passwd .SH SEE ALSO .BR slapd.conf (5), .BR slapd (8), diff --git a/doc/man/man5/slapd-perl.5 b/doc/man/man5/slapd-perl.5 index 16117d1254..36a87b3a4e 100644 --- a/doc/man/man5/slapd-perl.5 +++ b/doc/man/man5/slapd-perl.5 @@ -1,4 +1,4 @@ -.TH SLAPD-PERL 5 "25 April 2002" "OpenLDAP LDVERSION" +.TH SLAPD-PERL 5 "30 April 2002" "OpenLDAP LDVERSION" .\" $OpenLDAP$ .SH NAME slapd-perl \- Perl backend to slapd @@ -139,9 +139,9 @@ Its argument is as follows. .LP Return value: nonzero if initialization failed. .SH CONFIGURATION -The -.BR slapd.conf (5) -options in this category apply to the PERL backend database. +These +.B slapd.conf +options apply to the PERL backend database. That is, they must follow a "database perl" line and come before any subsequent "backend" or "database" lines. Other database options are described in the @@ -164,6 +164,8 @@ direcetory in the OpenLDAP source tree. .SH WARNING The interface of this backend to the perl module MAY change. Any suggestions would greatly be appreciated. +.SH FILES +ETCDIR/slapd.conf .SH SEE ALSO .BR slapd.conf (5), .BR slapd (8), diff --git a/doc/man/man5/slapd-shell.5 b/doc/man/man5/slapd-shell.5 index 7a9d4a568e..8248db5fc7 100644 --- a/doc/man/man5/slapd-shell.5 +++ b/doc/man/man5/slapd-shell.5 @@ -1,4 +1,4 @@ -.TH SLAPD-SHELL 5 "25 April 2002" "OpenLDAP LDVERSION" +.TH SLAPD-SHELL 5 "30 April 2002" "OpenLDAP LDVERSION" .\" Copyright 1998-2002 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .\" $OpenLDAP$ @@ -14,39 +14,43 @@ make it easy to tie an existing database to the .B slapd front-end. .SH CONFIGURATION -The -.BR slapd.conf (5) -options in this category apply to the SHELL backend database. +These +.B slapd.conf +options apply to the SHELL backend database. That is, they must follow a "database shell" line and come before any subsequent "backend" or "database" lines. -.LP -These options specify the pathname of the command to execute in response -to the given LDAP operation. -Note that you need only supply configuration lines for 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. +Other database options are described in the +.BR slapd.conf (5) +manual page. .TP -.B bind +.B bind .TP -.B unbind +.B unbind .TP -.B search +.B search .TP -.B compare +.B compare .TP -.B modify +.B modify .TP -.B modrdn +.B modrdn .TP -.B add +.B add .TP -.B delete +.B delete .TP -.B abandon +.B abandon +These options specify the pathname of the command to execute in response +to the given LDAP operation. +Note that you need only supply configuration lines for 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. .SH EXAMPLE There is a skeleton search script in the slapd/back-shell/ directory in the OpenLDAP source tree. +.SH FILES +ETCDIR/slapd.conf .SH SEE ALSO .BR slapd.conf (5), .BR slapd (8), diff --git a/doc/man/man5/slapd-sql.5 b/doc/man/man5/slapd-sql.5 index f40659fc2b..50860c1908 100644 --- a/doc/man/man5/slapd-sql.5 +++ b/doc/man/man5/slapd-sql.5 @@ -1,4 +1,4 @@ -.TH SLAPD-SQL 5 "25 April 2002" "OpenLDAP LDVERSION" +.TH SLAPD-SQL 5 "30 April 2002" "OpenLDAP LDVERSION" .\" $OpenLDAP$ .SH NAME slapd-sql \- SQL backend to slapd @@ -40,7 +40,7 @@ Also, it uses ODBC to connect to RDBMSes, and is highly configurable for SQL dialects RDBMSes may use, so it may be used for integration and distribution of data on different RDBMSes, OSes, hosts etc., in other words, in highly heterogeneous environment. -.SH "METAINFORMATION USED" +.SH METAINFORMATION USED .LP Almost everything mentioned later is illustrated in examples located in the @@ -101,7 +101,7 @@ To fetch all values for cn attribute given person ID, we construct the query: .LP .nf - SELECT CONCAT(persons.first_name,\' \',persons.last_name) + SELECT CONCAT(persons.first_name,' ',persons.last_name) AS cn FROM persons WHERE persons.id=? .fi .LP @@ -119,7 +119,7 @@ If we wanted to service LDAP requests with filters like SELECT ... FROM persons,phones WHERE persons.id=phones.pers.id AND persons.id=? - AND phones.phone like \'123%\' + AND phones.phone like '123%' .fi .LP So, if we had information about what tables contain values for each @@ -155,7 +155,7 @@ Keytbl and keycol thus contain "persons" (name of the table), and "id" id=1 oc_id=1 name="cn" - sel_expr="CONCAT(persons.first_name,\' \',persons.last_name)" + sel_expr="CONCAT(persons.first_name,' ',persons.last_name)" from_tbls="persons" join_where=NULL ************ @@ -230,14 +230,14 @@ like this (by Robin Elfrink): .nf CREATE VIEW ldap_entries (id, dn, oc_map_id, parent, keyval) AS SELECT (1000000000+userid), - UPPER(CONCAT(CONCAT(\'cn=\',gecos),\',o=MyCompany,c=NL\')), + UPPER(CONCAT(CONCAT('cn=',gecos),',o=MyCompany,c=NL')), 1, 0, userid FROM unixusers UNION SELECT (2000000000+groupnummer), - UPPER(CONCAT(CONCAT(\'cn=\',groupnaam),\',o=MyCompany,c=NL\')), + UPPER(CONCAT(CONCAT('cn=',groupnaam),',o=MyCompany,c=NL')), 2, 0, groupnummer FROM groups; .fi .LP -.SH "Typical SQL backend operation" +.SH Typical SQL backend operation Having metainformation loaded, the SQL backend uses these tables to determine a set of primary keys of candidates (depending on search scope and filter). @@ -248,19 +248,19 @@ for our query with filter (telephoneNumber=123*) we would get following query generated (which loads candidate IDs) .LP .nf - SELECT ldap_entries.id,persons.id, \'person\' AS objectClass, + SELECT ldap_entries.id,persons.id, 'person' AS objectClass, ldap_entries.dn AS dn FROM ldap_entries,persons,phones WHERE persons.id=ldap_entries.keyval AND ldap_entries.objclass=? AND ldap_entries.parent=? AND phones.pers_id=persons.id - AND (phones.phone LIKE \'123%\') + AND (phones.phone LIKE '123%') .fi .LP (for ONELEVEL search) or "... AND dn=?" (for BASE search) -or "... AND dn LIKE \'%?\'" (for SUBTREE) +or "... AND dn LIKE '%?'" (for SUBTREE) .LP Then, for each candidate, we load attributes requested using per-attribute queries like @@ -291,7 +291,7 @@ Please see samples to find out what are the parameters passed, and other information on this matter - they are self-explanatory for those familiar with concept expressed above. .LP -.SH "common techniques (referrals, multiclassing etc.)" +.SH common techniques (referrals, multiclassing etc.) First of all, lets remember that among other major differences to complete LDAP data model, the concept above does not directly support such things as multiple objectclasses for entry, and referrals. @@ -319,6 +319,8 @@ described in Administrators Guide. .SH EXAMPLES There are example SQL modules in the slapd/back-sql/rdbms_depend/ direcetory in the OpenLDAP source tree. +.SH FILES +ETCDIR/slapd.conf .SH SEE ALSO .BR slapd.conf (5), .BR slapd (8). diff --git a/doc/man/man5/slapd-tcl.5 b/doc/man/man5/slapd-tcl.5 index 3b9d1ae0e7..2d71bd6f8b 100644 --- a/doc/man/man5/slapd-tcl.5 +++ b/doc/man/man5/slapd-tcl.5 @@ -1,4 +1,4 @@ -.TH SLAPD-TCL 5 "28 April 2002" "OpenLDAP LDVERSION" +.TH SLAPD-TCL 5 "30 April 2002" "OpenLDAP LDVERSION" .\" $OpenLDAP$ .SH NAME slapd-tcl \- Tcl backend to slapd @@ -15,9 +15,9 @@ Any tcl database section of the configuration file .BR slapd.conf (5) must then specify what Tcl script to use. .SH CONFIGURATION -The -.BR slapd.conf (5) -options in this category apply to the TCL backend database. +These +.B slapd.conf +options apply to the TCL backend database. That is, they must follow a "database tcl" line and come before any subsequent "backend" or "database" lines. Other database options are described in the @@ -25,25 +25,29 @@ Other database options are described in the manual page. .TP .B scriptpath -The full path to the tcl script used for this database -.TP +The full path to the tcl script used for this database. +.\" +.\" There must be a .TP before this list, otherwise the .in doesn't work. +.\" +.LP .B search -.TP +.br .B add -.TP +.br .B delete -.TP +.br .B modify -.TP +.br .B bind -.TP +.br .B unbind -.TP +.br .B modrdn -.TP +.br .B compare -.TP +.br .B abandon +.in The procs for each ldap function. This is similar to how the .BR slapd-shell (5) @@ -56,7 +60,7 @@ The realm lets you group several databases to the same interpreter. 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. -.SH "Variables passed to the procs" +.SH Variables passed to the procs .TP .B abandon { action msgid suffix } .nf @@ -67,7 +71,7 @@ If no tclrealm is specified, it is put into the "default" realm. formatted list (surrounded by {}'s). .fi .TP -.B add { action msgid suffix entry } +.B add "{ action msgid suffix entry }" .nf action - Always equal to ADD. msgid - The msgid of this ldap operation. @@ -76,7 +80,7 @@ If no tclrealm is specified, it is put into the "default" realm. an element in a tcl formatted list. .fi .TP -.B bind { action msgid suffix dn method cred_len cred } +.B bind "{ action msgid suffix dn method cred_len cred }" .nf action - Always equal to BIND. msgid - The msgid of this ldap operation. @@ -90,7 +94,7 @@ If no tclrealm is specified, it is put into the "default" realm. bind (??) .fi .TP -.B compare { action msgid suffix dn ava_type ava_value } +.B compare "{ action msgid suffix dn ava_type ava_value }" .nf action - Always equal to COMPARE. msgid - The msgid of this ldap operation. @@ -100,7 +104,7 @@ If no tclrealm is specified, it is put into the "default" realm. ava_value - Value to compare. .fi .TP -.B delete { action msgid suffix dn } +.B delete "{ action msgid suffix dn }" .nf action - Always equal to DELETE. msgid - The msgid of this ldap operation. @@ -108,7 +112,7 @@ If no tclrealm is specified, it is put into the "default" realm. dn - DN to delete. .fi .TP -.B modify { action msgid suffix dn mods } +.B modify "{ action msgid suffix dn mods }" .nf action - Always equal to MODIFY. msgid - The msgid of this ldap operation. @@ -129,7 +133,7 @@ If no tclrealm is specified, it is put into the "default" realm. (ADD, DELETE, REPLACE). .fi .TP -.B modrdn { action msgid suffix dn newrdn deleteoldrdn } +.B modrdn "{ action msgid suffix dn newrdn deleteoldrdn }" .nf action - Always equal to MODRDN. msgid - The msgid of this ldap operation. @@ -140,7 +144,9 @@ If no tclrealm is specified, it is put into the "default" realm. old RDN should be removed after being renamed. .fi .TP -.B search { action msgid suffix base scope deref sizelimit timelimit filterstr attrsonly attrlist } +.B +search { action msgid suffix base scope deref \ +sizelimit timelimit filterstr attrsonly attrlist } .nf action - Always equal to SEARCH. msgid - The msgid of this ldap operation. @@ -156,7 +162,7 @@ If no tclrealm is specified, it is put into the "default" realm. attrlist - Tcl list if to retrieve. .fi .TP -.B unbind { action msgid suffix dn } +.B unbind "{ action msgid suffix dn }" .nf action - Always equal to UNBIND. msgid - The msgid of this ldap operation. @@ -164,7 +170,7 @@ If no tclrealm is specified, it is put into the "default" realm. dn - DN to unbind. .fi .LP -.SH "Return Method and Syntax" +.SH Return Method and Syntax There are only 2 return types. All procs must return a result to show status of the operation. The result is in this form: @@ -231,12 +237,14 @@ Here is some example code again, showing a full search proc example. NOTE: Newlines in the return value is acceptable in search entries (i.e. when returning base64 encoded binary entries). .LP -.SH "Builtin Commands and Variables" +.SH Builtin Commands and Variables .TP .B ldap:debug Allows you to send debug messages through OpenLDAP's native debugging system, this is sent as a LDAP_DEBUG_ANY and will be logged. Useful for debugging scripts or logging bind failures. +.SH FILES +ETCDIR/slapd.conf .SH SEE ALSO .BR slapd.conf (5), .BR slapd (8), diff --git a/doc/man/man5/slapd.access.5 b/doc/man/man5/slapd.access.5 index 1e2f396489..6be551c1cd 100644 --- a/doc/man/man5/slapd.access.5 +++ b/doc/man/man5/slapd.access.5 @@ -1,4 +1,4 @@ -.TH SLAPD.ACCESS 5 "28 Oct 2001" "OpenLDAP LDVERSION" +.TH SLAPD.ACCESS 5 "30 April 2002" "OpenLDAP LDVERSION" .\" Copyright 1998-2002 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME @@ -51,7 +51,7 @@ are used. Arguments that should be replaced by actual text are shown in brackets <>. The structure of the access control directives is .TP -.B access to [ by [ ] ]+ +.B access to "[ by [ ] ]+" Grant access (specified by .BR ) to a set of entries and/or attributes (specified by diff --git a/doc/man/man5/slapd.conf.5 b/doc/man/man5/slapd.conf.5 index 1ad79e0041..d2e0525d85 100644 --- a/doc/man/man5/slapd.conf.5 +++ b/doc/man/man5/slapd.conf.5 @@ -1,4 +1,4 @@ -.TH SLAPD.CONF 5 "28 April 2002" "OpenLDAP LDVERSION" +.TH SLAPD.CONF 5 "30 April 2002" "OpenLDAP LDVERSION" .\" Copyright 1998-2002 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .\" $OpenLDAP$ @@ -66,11 +66,13 @@ Options described in this section apply to all backends, unless specifically overridden in a backend definition. Arguments that should be replaced by actual text are shown in brackets <>. .TP -.B access to [ by ]+ +.B access to "[ by ]+" Grant access (specified by ) to a set of entries and/or attributes (specified by ) by one or more requestors (specified by ). -See the "OpenLDAP's Administrator's Guide" for details. +See +.BR slapd.access (5) +and the "OpenLDAP's Administrator's Guide" for details. .TP .B allow Specify a set of features (separated by white space) to @@ -90,11 +92,11 @@ server's command line options if started without the debugging command line option. .HP .hy 0 -.B attributetype (\ [NAME\ ] [OBSOLETE]\ +.B attributetype "(\ [NAME\ ] [OBSOLETE]\ [DESC\ ]\ [SUP\ ] [EQUALITY\ ] [ORDERING\ ]\ [SUBSTR\ ] [SYNTAX\ ] [SINGLE\-VALUE] [COLLECTIVE]\ - [NO\-USER\-MODIFICATION] [USAGE\ ]\ ) + [NO\-USER\-MODIFICATION] [USAGE\ ]\ )" .RS Specify an attribute type using the LDAPv3 syntax defined in RFC 2252. The slapd parser extends the RFC 2252 definition by allowing string @@ -401,9 +403,9 @@ option are only usable if slapd was compiled with --enable-modules. Specify a list of directories to search for loadable modules. Typically the path is colon-separated but this depends on the operating system. .HP -.B objectclass ( [NAME ] [DESC [NAME ] [DESC ] [{ ABSTRACT | STRUCTURAL | AUXILIARY }] [MUST ]\ - [MAY ] ) + [MAY ] )" .RS Specify an objectclass using the LDAPv3 syntax defined in RFC 2252. The slapd parser extends the RFC 2252 definition by allowing string @@ -414,7 +416,7 @@ objectidentifier description.) Object classes are "STRUCTURAL" by default. .RE .TP -.B objectidentifier { | [:] } +.B objectidentifier "{ | [:] }" Define a string name that equates to the given OID. The string can be used in place of the numeric OID in objectclass and attribute definitions. The name can also be used with a suffix of the form ":xx" in which case the @@ -945,11 +947,10 @@ Specify the referral to pass back when is asked to modify a replicated local database. If specified multiple times, each url is provided. .SH DATABASE-SPECIFIC OPTIONS -Each database may allow specific configuration options; they will be +Each database may allow specific configuration options; they are documented separately in the -.B slapd-(5) -manual pakges since most of these databases are very specific -or experimental. +.BR slapd- (5) +manual pages. .SH EXAMPLE "OpenLDAP Administrator's Guide" contains an annotated example of a configuration file. @@ -958,6 +959,7 @@ ETCDIR/slapd.conf .SH SEE ALSO .BR ldap (3), .BR slapd-bdb (5), +.BR slapd-ldap (5), .BR slapd-ldbm (5), .BR slapd-meta (5), .BR slapd-null (5), diff --git a/servers/slapd/back-meta/Documentation b/servers/slapd/back-meta/Documentation index 2a17d2fbc7..2971614a61 100644 --- a/servers/slapd/back-meta/Documentation +++ b/servers/slapd/back-meta/Documentation @@ -1,308 +1 @@ -Copyright 1998-2002 The OpenLDAP Foundation, All Rights Reserved. -COPYING RESTRICTIONS APPLY, see COPYRIGHT file - -Copyright 2001, Pierangelo Masarati, All rights reserved. - - - - Metadirectory backend. - -This is a brief introduction to the core functionalities of back-meta. - - - - - Introduction. - -Back-meta implements a backend for OpenLDAP's slapd. It performs basic -LDAP proxying with respect to a set of remote LDAP servers, called -"targets". The information contained in these servers can be presented -as belonging to a single Directory Information Tree (DIT). - -A basic knowledge of the functionality of back-ldap is recommended. -This backend has been designed as an enhancement of back-ldap. -The two backends share many features (actually they also share portions -of code). While back-ldap is intended to proxy operations directed -to a single server, back-meta is mainly intended for proxying -of multiple servers and possibly naming context masquerading. -These features, although useful in many scenarios, may result in -excessive overhead for some applications, so its use should be -carefully considered. - -In the examples section, some typical scenarios will be discussed. - - - - - Common configuration directives - -The backend uses most of the common configuration directives. Its -configuration block starts with the "database" directive: - - database meta - -At least a "suffix" directive is required. - -Note: as with back-ldap, operational attributes related to entry -creation/modification should not be used, as they would be passed -to the target servers, generating an error. Moreover, it makes -little sense to use such attributes in proxying, as the proxy -server doesn't actually store data, so it should have no knowledge -of such attributes. While code to strip the modification attributes -has been put in place (and #ifdef'd), it implies unmotivated overhead. -So it is strongly recommended to set - - lastmod off - -for every back-ldap/back-meta backend. - - - - - Special configuration directives - -Target configuration starts with the "uri" directive. All the -configuration directives that are not specific to targets should -be defined first for clarity, including those that are common to -all backends. They are: - - default-target none - -This directive forces the backend to reject all those operations -that must resolve to a single target in case none or multiple -targets are selected. They include: add, delete, modify, modrdn; -compare is not included, as well as bind since, as they don't -alter entries, in case of multiple matches an attempt is made -to perform the operation on any candidate target, with the -constraint that at most on must succeed. This directive can also -be used when processing targets to mark a specific target as default. - - dncache-ttl {forever|disabled|} - -This directive sets the time-to-live of the dn cache. This caches -the target that holds a given dn to speed up target selection -in case multiple targets would result from an uncached search; -forever means cache never expires; disabled means no dn caching; -otherwise a valid ( > 0 ) ttl in seconds is required. - - - - - Target specification - -Target specification starts with a "uri" directive: - - uri ://[[:]]/ - -The "server" directive that was allowed in back-ldap (although deprecated) -has been discarded in back-meta. The part can be anything -ldap_initialize(3) accepts ({ldap|ldaps|ldapi} and variants); -and may be omitted, defaulting to whatever is set in -/etc/ldap.conf (correct me!?!). -The part is mandatory. It must end with one of the -naming contexts defined for the backend, e.g.: - - suffix "dc=foo,dc=com" - uri "ldap://x.foo.com/dc=x,dc=foo,dc=com" - -The part doesn't need to be unique across the targets; -it may also match one of the values of the "suffix" directive. - - default-target [] - -the "default-target" directive can also be used during target -specification. With no arguments it marks the current target as -the default. The optional number marks target as the -default one, starting from 1. Target must be defined. - - binddn - -This directive, as in back-ldap, allows to define the dn that is -used to query the target server for acl checking; it should have -read access on the target server to attributes used on the proxy -for acl checking. There is no risk of giving away such values; -they are only used to check permissions. - - bindpw - -This directive sets the password for acl checking in conjunction -with the above mentioned "binddn" directive. - - pseudorootdn - -This directive, if present, sets the dn that will be substituted -to the bind dn if a bind with the backend's "rootdn" succeeds. The true -"rootdn" of the target server ought not be used; an arbitrary administrative -dn should used instead. - - pseudorootpw - -This directive sets the credential that will be used in case a bind -with the backend's "rootdn" succeeds, and the bind is propagated to -the target using the "pseudorootdn" dn. - - rewrite* ... - - suffixmassage - -All the directives starting with "rewrite" refer to the rewrite engine -that has been added to slapd. The "suffixmassage" directive was -introduced in back-ldap to allow suffix massaging while proxying. -It has been obsoleted by the rewriting tools. However, both for -backward compatibility and for ease of configuration when simple -suffix massage is required, it has been preserved. It wraps the -basic rewriting instructions that perform suffix massaging. - -Note: this also fixes a flaw in suffix massaging, which operated -on (case insensitive) DNs instead of normalized DNs, -so "dc=foo, dc=com" would not match "dc=foo,dc=com". - -See the "rewrite" section. - - map {objectClass|attribute} {|*} [|*] - -objectClass/attribute mapping stuff. This has been inherited from -the work made by Mark Valence on the back-ldap backend. -See the mapping section. - - - - - Scenarios - -A powerful (and in some sense dangerous) rewrite engine has been added -to both back-ldap and back-meta. While the former can gain limited -beneficial effects from rewriting stuff, the latter can become -an amazingly powerful tool. - -Consider a couple of scenarios first. - -1) Two directory servers share two levels of naming context; -say "dc=a,dc=foo,dc=com" and "dc=b,dc=foo,dc=com". Then, an -unambiguous back-meta can be configured as: - - database meta - suffix "dc=foo,dc=com" - - uri "ldap://a.foo.com/dc=a,dc=foo,dc=com" - - uri "ldap://b.foo.com/dc=b,dc=foo,dc=com" - -Operations directed to a specific target can be easily resolved -because there are no ambiguities. The only operation that may -resolve to multiple targets is a search with base "dc=foo,dc=com" -and scope at least "one", which results in spawning two searches -to the targets. - -2a) Two directory servers don't share any portion of naming context, -but they'd present as a single DIT. [Caveat: uniqueness of -(massaged) entries among the two servers is assumed; integrity -checks risk to incurr in excessive overhead and have not been implemented.] -Say we have "dc=bar,dc=org" and "o=Foo,c=US", and we'd like them to -appear as branches of "dc=foo,dc=com", say "dc=a,dc=foo,dc=com" -and "dc=b,dc=foo,dc=com". Then we need to configure our back-meta as: - - database meta - suffix "dc=foo,dc=com" - - uri "ldap://a.bar.com/dc=a,dc=foo,dc=com" - suffixmassage "dc=a,dc=foo,dc=com" "dc=bar,dc=org" - - uri "ldap://b.foo.com/dc=b,dc=foo,dc=com" - suffixmassage "dc=b,dc=foo,dc=com" "o=Foo,c=US" - -Again, operations can be resolved without ambiguity, although -some rewriting is required. Notice that the virtual naming context -of each target is a branch of the database's naming context; it -is rewritten back and forth when operations are performed towards -the target servers. What "back and forth" means will be clarified -later. - -When a search with base "dc=foo,dc=com" is attempted, if the -scope is "base" it fails with "no such object"; in fact, the -common root of the two targets (prior to massaging) does not -exist. If the scope is "one", both targets are contacted with -the base replaced by each target's base; the scope is derated -to "base". In general, a scope "one" search is honored, -and the scope is derated, only when the incoming base is -at most one level lower of a target's naming context (prior -to massaging). -Finally, if the scope is "sub" the incoming base is replaced -by each target's unmassaged naming context, and the scope -is not altered. - -2b) Consider the above reported scenario with the two servers -sharing the same naming context: - - database meta - suffix "dc=foo,dc=com" - - uri "ldap://a.bar.com/dc=foo,dc=com" - suffixmassage "dc=foo,dc=com" "dc=bar,dc=org" - - uri "ldap://b.foo.com/dc=foo,dc=com" - suffixmassage "dc=foo,dc=com" "o=Foo,c=US" - -All the previous considerations hold, except that now there is -no way to unambiguously resolve a dn. In this case, all the -operations that require an unambiguous target selection will -fail unless the dn is already cached or a default target has -been set. - - - - - Rewriting - -This part of the document is being prepared. At present you may consult -the RATIONALE in libraries/librewrite. - - - - - Objectclass/attribute mapping - -This part of the document is being prepared. At present you may stick with - -http://www.openldap.org/lists/openldap-devel/200102/msg00006.html - - - - - ACL -Note on ACLs: at present you may add whatever ACL rule you desire -to back-meta (as well as to back-ldap). However, the meaning of an ACL -on a proxy may require some considerations. Two philosophies may be -considered: - -a) the remote server dictates the permissions; the proxy simply passes -back what it gets from the remote server. - -b) the remote server unveils "everything"; the proxy is responsible -for protecting data from unauthorized access. - -Of course the latter sounds unreasonable, but it is not. It is possible -to imagine scenarios in which a remote host discloses data that can -be considered "public" inside an intranet, and a proxy that connects it -to the internet may impose additional constraints. To this purpose, the -proxy should be able to comply with all the ACL matching criteria that -the server supports. This has been achieved with regard to all the -criteria supported by slapd except a special subtle case (please drop -me a note if you can find other exceptions: ). -The rule - -access to dn="" attr= - by dnattr= read - by * none - -cannot be matched IFF: -- the attribute that is being requested, , is NOT , and -- the attribute that determines membership, , has not - been requested (e.g. in a search) - -In fact this ACL is resolved by slapd using the portion of entry it retrieved -from the remote server without requiring any further intervention of the -backend, so, if the attribute has not been fetched, the match -cannot be assessed because the attribute is not present, not because -no value matches the requirement! - - -Note on ACLS and attribute mapping: ACLs are applied to the mapped -attributes; for instance, if the attribute locally known as "foo" -is mapped to "bar" on a remote server, then local ACLs apply to -attribute "foo" and are totally unaware of its remote name. The -remote server will check permissions for "bar", and the local server -will possibly enforce additional restrictions to "foo". - +The Meta Backend is described in the slapd-meta(5) manual page. diff --git a/servers/slapd/back-null/README b/servers/slapd/back-null/README index a2d8cb11fd..300afd9703 100644 --- a/servers/slapd/back-null/README +++ b/servers/slapd/back-null/README @@ -1,14 +1 @@ -Null Backend Interface for OpenLDAP - -The Null backend is surely the most useful part of slapd: -- Searches return success but no entries. -- Compares return compareFalse. -- Updates return success (unless readonly is on) but do nothing. -- Binds fail unless the database option "bind on" is given. - The "bind" option is "off" by default. -Inspired by the /dev/null device. - -slapd.conf example: - database null - suffix "cn=Nothing" - bind on +The Null Backend is described in the slapd-null(5) manual page.