From 4f24ebbb8d36be48c484daa4befa10df2f64f550 Mon Sep 17 00:00:00 2001 From: Pierangelo Masarati Date: Thu, 2 May 2002 16:35:16 +0000 Subject: [PATCH] 3rd step at updating docs by hallvard Furuseth (with minor changes in slapd-meta.5) --- doc/man/man5/slapd-ldap.5 | 31 +++- doc/man/man5/slapd-meta.5 | 311 ++++++++++++++++++------------------ doc/man/man5/slapd-null.5 | 10 +- doc/man/man5/slapd-passwd.5 | 11 +- doc/man/man5/slapd-perl.5 | 9 +- doc/man/man5/slapd-shell.5 | 115 +++++++++++-- doc/man/man5/slapd-sql.5 | 20 +-- doc/man/man5/slapd-tcl.5 | 197 ++++++++++++----------- doc/man/man5/slapd.conf.5 | 36 ++++- 9 files changed, 443 insertions(+), 297 deletions(-) diff --git a/doc/man/man5/slapd-ldap.5 b/doc/man/man5/slapd-ldap.5 index ea33da20ca..e22d94479b 100644 --- a/doc/man/man5/slapd-ldap.5 +++ b/doc/man/man5/slapd-ldap.5 @@ -1,4 +1,4 @@ -.TH SLAPD-LDAP 5 "30 April 2002" "OpenLDAP LDVERSION" +.TH SLAPD-LDAP 5 "2 May 2002" "OpenLDAP LDVERSION" .\" Copyright 1998-2002 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .\" $OpenLDAP$ @@ -22,6 +22,19 @@ subsequent "backend" or "database" lines. Other database options are described in the .BR slapd.conf (5) manual page. +.LP +Note: It is strongly recommended to set +.RS +lastmod off +.RE +for every +.B ldap +and +.B meta +database. +This is because operational attributes related to entry creation and +modification should not be used, as they could be passed to the target +servers, generating an error. .TP .B uri LDAP server to use. @@ -71,20 +84,24 @@ manual page. This maps the OpenLDAP objectclass `groupOfNames' to the Active Directory objectclass `group': .LP +.RS .nf - map objectclass groupOfNames group +map objectclass groupOfNames group .fi +.RE .LP This presents a limited attribute set from the foreign server: .LP +.RS .nf - map attribute cn * - map attribute sn * - map attribute manager * - map attribute description * - map attribute * +map attribute cn * +map attribute sn * +map attribute manager * +map attribute description * +map attribute * .fi +.RE .LP These lines map cn, sn, manager, and description to themselves, and any other attribute gets "removed" from the object before it is sent diff --git a/doc/man/man5/slapd-meta.5 b/doc/man/man5/slapd-meta.5 index 26a1085b31..e5e279af54 100644 --- a/doc/man/man5/slapd-meta.5 +++ b/doc/man/man5/slapd-meta.5 @@ -1,4 +1,4 @@ -.TH SLAPD_META 5 "30 April 2002" "OpenLDAP LDVERSION" +.TH SLAPD_META 5 "2 May 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. @@ -61,11 +61,9 @@ 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 -.LP -.nf - lastmod off -.fi -.LP +.RS +lastmod off +.RE for every .B ldap and @@ -108,10 +106,12 @@ The part is mandatory. It must end with one of the naming contexts defined for the backend, e.g.: .LP +.RS .nf - suffix "\fBdc=foo,dc=com\fP" - uri "ldap://x.foo.com/dc=x,\fBdc=foo,dc=com\fP" +suffix "\fBdc=foo,dc=com\fP" +uri "ldap://x.foo.com/dc=x,\fBdc=foo,dc=com\fP" .fi +.RE .LP The part doesn't need to be unique across the targets; it may also match one of the values of the "suffix" directive. @@ -185,12 +185,14 @@ Consider a couple of scenarios first. say "dc=a,dc=foo,dc=com" and "dc=b,dc=foo,dc=com". Then, an unambiguous Meta database can be configured as: .LP +.RS .nf - 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" +database meta +suffix "\fBdc=foo,dc=com\fP" +uri "ldap://a.foo.com/dc=a,\fBdc=foo,dc=com\fP" +uri "ldap://b.foo.com/dc=b,\fBdc=foo,dc=com\fP" .fi +.RE .LP Operations directed to a specific target can be easily resolved because there are no ambiguities. @@ -208,16 +210,18 @@ 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: .LP +.RS .nf - 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" +database meta +suffix "dc=foo,dc=com" + +uri "ldap://a.bar.com/\fBdc=a,dc=foo,dc=com\fP" +suffixmassage "\fBdc=a,dc=foo,dc=com\fP" "dc=bar,dc=org" + +uri "ldap://b.foo.com/\fBdc=b,dc=foo,dc=com\fP" +suffixmassage "\fBdc=b,dc=foo,dc=com\fP" "o=Foo,c=US" .fi +.RE .LP Again, operations can be resolved without ambiguity, although some rewriting is required. @@ -243,16 +247,18 @@ is not altered. 2b) Consider the above reported scenario with the two servers sharing the same naming context: .LP +.RS .nf - 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" +database meta +suffix "\fBdc=foo,dc=com\fP" + +uri "ldap://a.bar.com/\fBdc=foo,dc=com\fP" +suffixmassage "\fBdc=foo,dc=com\fP" "dc=bar,dc=org" + +uri "ldap://b.foo.com/\fBdc=foo,dc=com\fP" +suffixmassage "\fBdc=foo,dc=com\fP" "o=Foo,c=US" .fi +.RE .LP All the previous considerations hold, except that now there is no way to unambiguously resolve a DN. @@ -283,11 +289,13 @@ slapd except a special subtle case (please drop me a note if you can find other exceptions: ). The rule .LP +.RS .nf - access to dn="" attr= - by dnattr= read - by * none +access to dn="" attr= + by dnattr= read + by * none .fi +.RE .LP cannot be matched iff the attribute that is being requested, , is NOT , and the attribute that determines membership, @@ -367,30 +375,8 @@ More flags (mainly Action Flags) will be added as needed. .SH "Pattern matching:" See .BR regex (7). -.SH "String Substitution:" -The string substitution happens according to a substitution pattern. -.TP -.B - -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 `\e{ddd}' should be fine if there is any need to -use a higher number of possible submatches. -.TP -.B - -variable substitution will be allowed (at least when I figure out -which kind of variable could be proficiently substituted) -.TP -.B - -map lookup will be allowed (map lookup of substring matches in gdbm, -ldap(!), math(?) and so on maps `a la sendmail'. -.TP -.B - -subroutine invocation will make it possible to rewrite a submatch in -terms of the output of another rewriteContext. .SH "Substitution Pattern Syntax:" -everything starting with `%' requires substitution; +Everything starting with `%' requires substitution; .LP the only obvious exception is `%%', which is left as is; .LP @@ -401,16 +387,18 @@ the basic substitution is `%d', where `d' is a digit; a `%' followed by a `{' invokes an advanced substitution. The pattern is: .LP -.nf - `%' `{' [ ] `(' `)' `}' -.fi +.RS +`%' `{' [ ] `(' `)' `}' +.RE .LP where must be a legal name for the map, i.e. .LP +.RS .nf - ::= [a-z][a-z0-9]* (case insensitive) - ::= `>' `|' `&' `&&' `*' `**' `$' + ::= [a-z][a-z0-9]* (case insensitive) + ::= `>' `|' `&' `&&' `*' `**' `$' .fi +.RE .LP and must be a legal substitution pattern, with no limits on the nesting level. @@ -482,26 +470,33 @@ server \-> client rewriting. .LP client -> server: .LP +.RS .nf - (default) if defined and no specific context - is available - bindDn bind - searchBase search - searchFilter search - compareDn compare - addDn add - modifyDn modify - modrDn modrdn - newSuperiorDn modrdn - deleteDn delete +(default) if defined and no specific context + is available +bindDn bind +searchBase search +searchFilter search +compareDn compare +addDn add +modifyDn modify +modrDn modrdn +newSuperiorDn modrdn +deleteDn delete .fi +.RE .LP server -> client: .LP +.RS .nf - searchResult search (only if defined; no default) - matchedDn all ops (only if defined; no default; NOT IMPL.) +searchResult search (only if defined; no default; + acts on DN and DN-syntax attributes + of search results) +matchedDn all ops (only if defined; no default; + NOT IMPL. except in search) .fi +.RE .LP .SH "Basic configuration syntax" .TP @@ -537,103 +532,107 @@ 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 - rewriteEngine on - - # Everything defined here goes into the `default' context. - # This rule changes the naming context of anything sent - # to `dc=home,dc=net' to `dc=OpenLDAP, dc=org' - - rewriteRule "(.*)dc=home,[ ]?dc=net" - "%1dc=OpenLDAP, dc=org" ":" +# set to `off' to disable rewriting +rewriteEngine on - # since a pretty/normalized DN does not include spaces - # after rdn separators, e.g. `,', this rule suffices: +# Everything defined here goes into the `default' context. +# This rule changes the naming context of anything sent +# to `dc=home,dc=net' to `dc=OpenLDAP, dc=org' - rewriteRule "(.*)dc=home,dc=net" - "%1dc=OpenLDAP,dc=org" ":" +rewriteRule "(.*)dc=home,[ ]?dc=net" + "%1dc=OpenLDAP, dc=org" ":" - # Start a new context (ends input of the previous one). - # This rule adds blanks between DN parts if not present. - rewriteContext addBlanks - rewriteRule "(.*),([^ ].*)" "%1, %2" +# since a pretty/normalized DN does not include spaces +# after rdn separators, e.g. `,', this rule suffices: - # This one eats blanks - rewriteContext eatBlanks - rewriteRule "(.*),[ ](.*)" "%1,%2" +rewriteRule "(.*)dc=home,dc=net" + "%1dc=OpenLDAP,dc=org" ":" - # Here control goes back to the default rewrite - # context; rules are appended to the existing ones. - # anything that gets here is piped into rule `addBlanks' - rewriteContext default - rewriteRule ".*" "%{>addBlanks(%0)}" ":" +# Start a new context (ends input of the previous one). +# This rule adds blanks between DN parts if not present. +rewriteContext addBlanks +rewriteRule "(.*),([^ ].*)" "%1, %2" - # Anything with `uid=username' is looked up in - # /etc/passwd for gecos (I know it's nearly useless, - # 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:" +# This one eats blanks +rewriteContext eatBlanks +rewriteRule "(.*),[ ](.*)" "%1,%2" - # Finally, in a bind, if one uses a `uid=username' DN, - # it is rewritten in `cn=name surname' if possible. - rewriteContext bindDn - rewriteRule ".*" "%{>addBlanks(%{>uid2Gecos(%0)})}" ":" +# Here control goes back to the default rewrite +# context; rules are appended to the existing ones. +# anything that gets here is piped into rule `addBlanks' +rewriteContext default +rewriteRule ".*" "%{>addBlanks(%0)}" ":" - # Rewrite the search base according to `default' rules. - rewriteContext searchBase alias default +.\" # Anything with `uid=username' is looked up in +.\" # /etc/passwd for gecos (I know it's nearly useless, +.\" # 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:" +.\" +.\" # Finally, in a bind, if one uses a `uid=username' DN, +.\" # it is rewritten in `cn=name surname' if possible. +.\" rewriteContext bindDn +.\" 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 - # `dc=home,dc=net' naming context, with spaces eaten. - rewriteContext searchResult - rewriteRule "(.*[^ ]?)[ ]?dc=OpenLDAP,[ ]?dc=org" - "%{>eatBlanks(%1)}dc=home,dc=net" ":" +# 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" + "%{>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 appended by the ldap map substitution): - rewriteMap ldap attr2dn "ldap://host/dc=my,dc=org?dn?sub" +# Bind with email instead of full DN: we first need +# an ldap map that turns attributes into a DN (the +# argument used when invoking the map is appended to +# the URI and acts as the filter portion) +rewriteMap ldap attr2dn "ldap://host/dc=my,dc=org?dn?sub" - # Then we need to detect emails; note that the rule - # in case of match stops rewriting; in case of error, - # it is ignored. In case we are mapping virtual - # to real naming contexts, we also need to rewrite - # regular DNs, because the definition of a bindDn - # rewrite context overrides the default definition. - rewriteContext bindDn - rewriteRule "^mail=[^,]+@[^,]+$" "%{attr2dn(%0)}" "@I" +# Then we need to detect DN made up of a single email, +# e.g. `mail=someone@example.com'; note that the rule +# in case of match stops rewriting; in case of error, +# it is ignored. In case we are mapping virtual +# to real naming contexts, we also need to rewrite +# regular DNs, because the definition of a bindDn +# rewrite context overrides the default definition. +rewriteContext bindDn +rewriteRule "^mail=[^,]+@[^,]+$" "%{attr2dn(%0)}" "@I" - # 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: - rewriteContext bindDn - rewriteRule ".+" "%{&&binddn(%0)}%0" ":" +# 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, which is +# stored in a variable called `binddn' with session scope, +# and left in place to allow regular binding: +rewriteContext bindDn +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 - # 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 - # refers to an entry in the `ou=admin' subtree, the - # filter is rewritten OR-ing the `uid=' with - # `cn='; otherwise it is left as is. This could be - # useful, for instance, to allow apache's auth_ldap-1.4 - # module to authenticate users with both `uid' and - # `cn', but only if the request comes from a possible - # `dn: cn=Web auth, ou=admin, dc=home, dc=net' user. - rewriteContext searchFilter - 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}" ":" +# 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 +# dereferenced, while the filter is decomposed in a +# prefix, in the value of the `uid=' AVA, and +# in a suffix. A tag `<>' is appended to the DN. +# If the DN refers to an entry in the `ou=admin' subtree, +# the filter is rewritten OR-ing the `uid=' with +# `cn='; otherwise it is left as is. This could be +# useful, for instance, to allow apache's auth_ldap-1.4 +# module to authenticate users with both `uid' and +# `cn', but only if the request comes from a possible +# `cn=Web auth,ou=admin,dc=home,dc=net' user. +rewriteContext searchFilter +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}" ":" .fi .SH "LDAP Proxy resolution (a possible evolution of slapd\-ldap(5)):" In case the rewritten DN is an LDAP URI, the operation is initiated diff --git a/doc/man/man5/slapd-null.5 b/doc/man/man5/slapd-null.5 index d215b370b3..b9d7908b00 100644 --- a/doc/man/man5/slapd-null.5 +++ b/doc/man/man5/slapd-null.5 @@ -1,4 +1,4 @@ -.TH SLAPD-NULL 5 "30 April 2002" "OpenLDAP LDVERSION" +.TH SLAPD-NULL 5 "2 May 2002" "OpenLDAP LDVERSION" .\" $OpenLDAP$ .SH NAME slapd-null \- Null backend to slapd @@ -35,11 +35,13 @@ The default is "off". .SH EXAMPLE Here is a possible slapd.conf extract using the Null backend: .LP +.RS .nf - database null - suffix "cn=Nothing" - bind on +database null +suffix "cn=Nothing" +bind on .fi +.RE .SH FILES ETCDIR/slapd.conf .SH SEE ALSO diff --git a/doc/man/man5/slapd-passwd.5 b/doc/man/man5/slapd-passwd.5 index 98f94e88fa..20456f1845 100644 --- a/doc/man/man5/slapd-passwd.5 +++ b/doc/man/man5/slapd-passwd.5 @@ -1,4 +1,4 @@ -.TH SLAPD-PASSWD 5 "30 April 2002" "OpenLDAP LDVERSION" +.TH SLAPD-PASSWD 5 "2 May 2002" "OpenLDAP LDVERSION" .\" Copyright 1998-2002 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .\" $OpenLDAP$ @@ -12,11 +12,14 @@ The PASSWD backend to serves up the user account information listed in the system .BR passwd (5) file. +The DN of each entry is "uid=,". +Note that non-base searches scan the the entire passwd file, and +are best suited for hosts with small passwd files. .SH CONFIGURATION -These +This .B slapd.conf -options apply to the PASSWD backend database. -That is, they must follow a "database passwd" line and come before any +option applies to the PASSWD backend database. +That is, it must follow a "database passwd" line and come before any subsequent "backend" or "database" lines. Other database options are described in the .BR slapd.conf (5) diff --git a/doc/man/man5/slapd-perl.5 b/doc/man/man5/slapd-perl.5 index 36a87b3a4e..0c83dceee8 100644 --- a/doc/man/man5/slapd-perl.5 +++ b/doc/man/man5/slapd-perl.5 @@ -1,4 +1,4 @@ -.TH SLAPD-PERL 5 "30 April 2002" "OpenLDAP LDVERSION" +.TH SLAPD-PERL 5 "2 May 2002" "OpenLDAP LDVERSION" .\" $OpenLDAP$ .SH NAME slapd-perl \- Perl backend to slapd @@ -63,7 +63,7 @@ It arguments are as follows: * time limit * filter string * attributes only flag (1 for yes) - * list of attributes that are to be returned (may be empty). + * list of attributes to return (may be empty) .fi .LP Return value: (resultcode, ldif-entry, ldif-entry, ...) @@ -85,7 +85,8 @@ Its arguments are as follows. * object reference * dn * a list formatted as follows - { "ADD" | "DELETE" | "REPLACE" }, attributetype, value..., ... + ({ "ADD" | "DELETE" | "REPLACE" }, + attributetype, value...)... .fi .LP .TP @@ -94,7 +95,7 @@ This method is called when a add request comes from a client. Its arguments are as follows. .nf * object reference - * entry in string format. + * entry in string format .fi .LP .TP diff --git a/doc/man/man5/slapd-shell.5 b/doc/man/man5/slapd-shell.5 index 8248db5fc7..af039f984a 100644 --- a/doc/man/man5/slapd-shell.5 +++ b/doc/man/man5/slapd-shell.5 @@ -1,4 +1,4 @@ -.TH SLAPD-SHELL 5 "30 April 2002" "OpenLDAP LDVERSION" +.TH SLAPD-SHELL 5 "2 May 2002" "OpenLDAP LDVERSION" .\" Copyright 1998-2002 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .\" $OpenLDAP$ @@ -22,32 +22,121 @@ subsequent "backend" or "database" lines. Other database options are described in the .BR slapd.conf (5) manual page. +.LP +These options specify the pathname and arguments of the program to +execute in response to the given LDAP operation. +Each option is followed by the input lines that the program receives: .TP -.B bind +.B abandon ... +.nf +ABANDON +msgid: + }> +.fi .TP -.B unbind +.B add ... +.nf +ADD +msgid: + }> + +.fi .TP -.B search +.B bind ... +.nf +BIND +msgid: + }> +dn: +method: +credlen: > +cred: +.fi .TP -.B compare +.B compare ... +.nf +COMPARE +msgid: + }> +dn: +: +.fi .TP -.B modify +.B delete ... +.nf +DELETE +msgid: + }> +dn: +.fi .TP -.B modrdn +.B modify ... +.nf +MODIFY +msgid: + }> +dn: +: + : }> + - +}> +.fi .TP -.B add +.B modrdn ... +.nf +MODRDN +msgid: + }> +dn: +newrdn: +deleteoldrdn: <0 or 1> +"> +.fi .TP -.B delete +.B search ... +.nf +SEARCH +msgid: + }> +base: +scope: <0-2, see ldap.h> +deref: <0-3, see ldap.h> +sizelimit: +timelimit: