-.TH SLAPD.ACCESS 5 "28 Oct 2001" "OpenLDAP LDVERSION"
-.\" Copyright 1998-2002 The OpenLDAP Foundation All Rights Reserved.
+.TH SLAPD.ACCESS 5 "RELEASEDATE" "OpenLDAP LDVERSION"
+.\" Copyright 1998-2003 The OpenLDAP Foundation All Rights Reserved.
.\" Copying restrictions apply. See COPYRIGHT/LICENSE.
.SH NAME
slapd.access \- access configuration for slapd, the stand-alone LDAP daemon
...
.fi
.LP
-Both the global configuration and each backend-specific section can contain
-access information.
-Backend-specific access control directives are used for those entries
-that belong to the backend, according to their naming context.
-In case no access control directives are defined for a backend,
-the appropriate directives from the global configuration section
-are used.
+Both the global configuration and each backend-specific section can
+contain access information. Backend-specific access control
+directives are used for those entries that belong to the backend,
+according to their naming context. In case no access control
+directives are defined for a backend or those which are defined are
+not applicable, the directives from the global configuration section
+are then used.
.LP
-Arguments that should be replaced by actual text are shown in brackets <>.
-The structure of the access control directives is
+For entries not held in any backend (such as a root DSE), the
+directives of the first backend (and any global directives) are
+used.
+.LP
+Arguments that should be replaced by actual text are shown in
+brackets <>. The structure of the access control directives is
.TP
-.B access to <what> [ by <who> <access> [ <control> ] ]+
+.B access to <what> "[ by <who> <access> [ <control> ] ]+"
Grant access (specified by
.BR <access> )
to a set of entries and/or attributes (specified by
.LP
.nf
*
- [dn[.<dnstyle>]=<pattern>]
+ [dn[.<dnstyle>]=<DN>]
[filter=<ldapfilter>]
[attrs=<attrlist>]
.fi
stands for all the entries.
.LP
The statement
-.B dn=<pattern>
+.B dn=<DN>
selects the entries based on their naming context.
-The optional style qualificator
-.B <dnstyle>
-can be
-.BR regex ,
-which implies a regular expression pattern, as detailed in
-.BR regex (7),
-will be used (the default),
-.B base
+The pattern is a string representation of the entry's DN.
+.BR base ,
+the default,
or
.B exact
(an alias of
.BR base )
-for an exact match of the entry,
+indicates the entry whose DN is equal to the pattern.
.B one
-to indicate all the entries immediately below the
+indicates all the entries immediately below the
.BR pattern ,
-.B sub
-to indicate all the subentries of an entry including the entry itself,
+.B subtree
+indicates all entries in the subtree at the pattern,
.B children
-to indicate all the subentries of an entry not including the entry itself.
-Note that
-.B dn=".*"
-is equivalent to
-.BR * .
-The regex form of the pattern does not support UTF-8 (7) yet.
+indicates all the entries below (subordinate to) the pattern.
+.LP
+If the
+.B <dnstyle>
+qualifier is
+.BR regex ,
+then the value is a regular expression pattern,
+as detailed in
+.BR regex (7),
+matching a normalized string representation of the entry's DN.
+The regex form of the pattern does not (yet) support UTF-8.
.LP
The statement
.B filter=<ldapfilter>
users
self
- dn[.<dnstyle>[,<modifier>]]=<pattern>
+ dn[.<dnstyle>[,<modifier>]]=<DN>
dnattr=<attrname>
group[/<objectclass>[/<attrname>]]
- [.<style>]=<pattern>
- peername[.<style>]=<pattern>
- sockname[.<style>]=<pattern>
- domain[.<domainstyle>[,<modifier>]]=<pattern>
- sockurl[.<style>]=<pattern>
+ [.<style>]=<group>
+ peername[.<style>]=<peername>
+ sockname[.<style>]=<sockname>
+ domain[.<domainstyle>[,<modifier>]]=<domain>
+ sockurl[.<style>]=<sockurl>
set[.<style>]=<pattern>
ssf=<n>
.LP
The keyword
.B anonymous
-means access is granted to unauthenticated users; it is moslty used
+means access is granted to unauthenticated clients; it is mostly used
to limit access to authentication resources (e.g. the
.B userPassword
-attribute) to unauthenticated users for authentication purposes.
+attribute) to unauthenticated clients for authentication purposes.
.LP
The keyword
.B users
-means access is granted to authenticated users.
+means access is granted to authenticated clients.
.LP
The keyword
.B self
being accessed and the requesting entry must be the same).
.LP
The statement
-.B dn=<pattern>
-means that access is granted to the matching dn.
-The optional style qualificator
+.B dn=<DN>
+means that access is granted to the matching DN.
+The optional style qualifier
.B dnstyle
allows the same choices of the dn form of the
.B <what>
-field.
-In detail, the
+field. In addition, the
.B regex
-form of
-.B pattern
-can exploit substring substitution of submatches in the
+style can exploit substring substitution of submatches in the
.B <what>
-dn by using the form
+dn.regex clause by using the form
.BR $<digit> ,
with
.B digit
.LP
The statement
.B dnattr=<attrname>
-means that access is granted to requests whose dn is listed in the
+means that access is granted to requests whose DN is listed in the
entry being accessed under the
.B attrname
attribute.
.LP
The statement
-.B group=<pattern>
-means that access is granted to requests whose dn is listed
-in the group entry whose dn is given by
-.BR pattern .
+.B group=<group>
+means that access is granted to requests whose DN is listed
+in the group entry whose DN is given by
+.BR group .
The optional parameters
.B objectclass
and
.B attrname
define the objectClass and the member attributeType of the group entry.
-The optional style qualificator
+The optional style qualifier
.B style
can be
.BR regex ,
.B exact
(an alias of
.BR base ),
-which means that an exact match will be used.
+which means that exact match will be used.
.LP
The statements
-.BR peername=<pattern> ,
-.BR sockname=<pattern> ,
-.BR domain=<pattern> ,
+.BR peername=<peername> ,
+.BR sockname=<sockname> ,
+.BR domain=<domain> ,
and
-.BR sockurl=<pattern>
+.BR sockurl=<sockurl>
mean that the contacting host IP for
.BR peername ,
the named pipe file name for
exactly matches the
.BR domain
pattern.
+The
+.B domain
+of the contacting host is determined by performing a DNS reverse lookup.
+As this lookup can easily be spoofed, use of the
+.B domain
+statement is strongly discouraged. By default, reverse lookups are disabled.
.LP
The statement
.B set=<pattern>
authentication/authorization operations (e.g.
.BR bind )
with no other access.
-This is useful to grant unauthenticated users the least possible
+This is useful to grant unauthenticated clients the least possible
access level to critical resources, like passwords.
.LP
The
.fi
.LP
which allows search and compare privileges to everybody under
-the "dc=example,dc=com" tree, with the seconf rule allowing
+the "dc=example,dc=com" tree, with the second rule allowing
also read in the "ou=People" subtree,
or the (even more silly) example
.LP
.fi
.LP
which grants everybody search and compare privileges, and adds read
-privileges to authenticated users.
+privileges to authenticated clients.
+.SH CAVEATS
+It is strongly recommended to explicitly use the most appropriate
+DN
+.BR style ,
+to avoid possible incorrect specifications of the access rules as well
+as for performance (avoid unrequired regex matching when an exact
+match suffices) reasons.
+.LP
+An adminisistrator might create a rule of the form:
+.LP
+.nf
+ access to dn.regex="dc=example,dc=com"
+ by ...
+.fi
+.LP
+expecting it to match all entries in the subtree "dc=example,dc=com".
+However, this rule actually matches any DN which contains anywhere
+the substring "dc=example,dc=com". That is, the rule matches both
+"uid=joe,dc=example,dc=com" and "dc=example,dc=com,uid=joe".
+.LP
+To match the desired subtree, the rule would be more precisely
+written:
+.LP
+.nf
+ access to dn.regex="^(.+,)?dc=example,dc=com$$"
+ by ...
+.fi
+.LP
+For performance reasons, it would be better to use the subtree style.
+.LP
+.nf
+ access to dn.subtree="dc=example,dc=com"
+ by ...
+.fi
+.LP
.SH FILES
+.TP
ETCDIR/slapd.conf
+default slapd configuration file
.SH SEE ALSO
.BR slapd (8),
.LP