slapd-sql.5

OpenLdap是LDAP的开源项目

.TH SLAPD-SQL 5 "RELEASEDATE" "OpenLDAP LDVERSION"
.\" $OpenLDAP: pkg/ldap/doc/man/man5/slapd-sql.5,v 1.16.2.8 2007/08/22 09:01:17 ando Exp $
.SH NAME
slapd-sql \- SQL backend to slapd
.SH SYNOPSIS
ETCDIR/slapd.conf
.SH DESCRIPTION
The primary purpose of this
.BR slapd (8)
backend is to PRESENT information stored in some RDBMS as an LDAP subtree
without any programming (some SQL and maybe stored procedures can't be
considered programming, anyway ;).
.LP
That is, for example, when you (some ISP) have account information you
use in an RDBMS, and want to use modern solutions that expect such
information in LDAP (to authenticate users, make email lookups etc.).
Or you want to synchronize or distribute information between different
sites/applications that use RDBMSes and/or LDAP.
Or whatever else...
.LP
It is NOT designed as a general-purpose backend that uses RDBMS instead
of BerkeleyDB (as the standard BDB backend does), though it can be
used as such with several limitations.
You can take a look at
.B http://www.openldap.org/faq/index.cgi?file=378 
(OpenLDAP FAQ-O-Matic/General LDAP FAQ/Directories vs. conventional
databases) to find out more on this point.
.LP
The idea (detailed below) is to use some metainformation to translate
LDAP queries to SQL queries, leaving relational schema untouched, so
that old applications can continue using it without any
modifications.
This allows SQL and LDAP applications to inter-operate without
replication, and exchange data as needed.
.LP
The SQL backend is designed to be tunable to virtually any relational
schema without having to change source (through that metainformation
mentioned).
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.
.LP
This backend is \fIexperimental\fP.
.SH CONFIGURATION
These
.B slapd.conf
options apply to the SQL backend database, which means that 
they must follow a "database sql" line and come before any
subsequent "backend" or "database" lines.
Other database options not specific to this backend are described 
in the
.BR slapd.conf (5)
manual page.
.SH DATA SOURCE CONFIGURATION

.TP
.B dbname <datasource name>
The name of the ODBC datasource to use.
.LP
.B dbhost <hostname>
.br
.B dbpasswd <password>
.br
.B dbuser <username>
.RS
The three above options are generally unneeded, because this information
is taken from the datasource specified by the
.B dbname
directive.
They allow to override datasource settings.
Also, several RDBMS' drivers tend to require explicit passing of user/password,
even if those are given in datasource (Note:
.B dbhost
is currently ignored).
.RE
.SH SCOPING CONFIGURATION
These options specify SQL query templates for scoping searches.

.TP
.B subtree_cond <SQL expression>
Specifies a where-clause template used to form a subtree search condition
(dn="(.+,)?<dn>$").
It may differ from one SQL dialect to another (see samples).
By default, it is constructed based on the knowledge about
how to normalize DN values (e.g.
\fB"<upper_func>(ldap_entries.dn) LIKE CONCAT('%',?)"\fP);
see \fBupper_func\fP, \fBupper_needs_cast\fP, \fBconcat_pattern\fP
and \fBstrcast_func\fP in "HELPER CONFIGURATION" for details.

.TP
.B children_cond <SQL expression>
Specifies a where-clause template used to form a children search condition
(dn=".+,<dn>$").
It may differ from one SQL dialect to another (see samples).
By default, it is constructed based on the knowledge about
how to normalize DN values (e.g.
\fB"<upper_func>(ldap_entries.dn) LIKE CONCAT('%,',?)"\fP);
see \fBupper_func\fP, \fBupper_needs_cast\fP, \fBconcat_pattern\fP
and \fBstrcast_func\fP in "HELPER CONFIGURATION" for details.

.TP
.B use_subtree_shortcut { YES | no }
Do not use the subtree condition when the searchBase is the database
suffix, and the scope is subtree; rather collect all entries.

.RE
.SH STATEMENT CONFIGURATION
These options specify SQL query templates for loading schema mapping
metainformation, adding and deleting entries to ldap_entries, etc.
All these and subtree_cond should have the given default values.
For the current value it is recommended to look at the sources,
or in the log output when slapd starts with "-d 5" or greater.
Note that the parameter number and order must not be changed.

.TP
.B oc_query <SQL expression>
The query that is used to collect the objectClass mapping data
from table \fIldap_oc_mappings\fP; see "METAINFORMATION USED" for details.
The default is
\fB"SELECT id, name, keytbl, keycol, create_proc, delete_proc, expect_return
FROM ldap_oc_mappings"\fP.

.TP
.B at_query <SQL expression>
The query that is used to collect the attributeType mapping data
from table \fIldap_attr_mappings\fP; see "METAINFORMATION USED" for details.
The default is
\fB"SELECT name, sel_expr, from_tbls, join_where, add_proc, delete_proc,
param_order, expect_return FROM ldap_attr_mappings WHERE oc_map_id=?"\fP.

.TP
.B id_query <SQL expression>
The query that is used to map a DN to an entry
in table \fIldap_entries\fP; see "METAINFORMATION USED" for details.
The default is
\fB"SELECT id,keyval,oc_map_id,dn FROM ldap_entries WHERE <DN match expr>"\fP,
where \fB<DN match expr>\fP is constructed based on the knowledge about
how to normalize DN values (e.g. \fB"dn=?"\fP if no means to uppercase
strings are available; typically, \fB"<upper_func>(dn)=?"\fP is used);
see \fBupper_func\fP, \fBupper_needs_cast\fP, \fBconcat_pattern\fP
and \fBstrcast_func\fP in "HELPER CONFIGURATION" for details.

.TP
.B insentry_stmt <SQL expression>
The statement that is used to insert a new entry
in table \fIldap_entries\fP; see "METAINFORMATION USED" for details.
The default is
\fB"INSERT INTO ldap_entries (dn, oc_map_id, parent, keyval) VALUES
(?, ?, ?, ?)"\fP.

.TP
.B delentry_stmt <SQL expression>
The statement that is used to delete an existing entry
from table \fIldap_entries\fP; see "METAINFORMATION USED" for details.
The default is
\fB"DELETE FROM ldap_entries WHERE id=?"\fP.

.TP
.B delobjclasses_stmt <SQL expression>
The statement that is used to delete an existing entry's ID
from table \fIldap_objclasses\fP; see "METAINFORMATION USED" for details.
The default is
\fB"DELETE FROM ldap_entry_objclasses WHERE entry_id=?"\fP.

.RE
.SH HELPER CONFIGURATION
These statements are used to modify the default behavior of the backend
according to issues of the dialect of the RDBMS.
The first options essentially refer to string and DN normalization
when building filters.
LDAP normalization is more than upper- (or lower-)casing everything;
however, as a reasonable trade-off, for case-sensitive RDBMSes the backend
can be instructed to uppercase strings and DNs by providing
the \fBupper_func\fP directive.
Some RDBMSes, to use functions on arbitrary data types, e.g. string
constants, requires a cast, which is triggered
by the \fBupper_needs_cast\fP directive.
If required, a string cast function can be provided as well,
by using the \fBstrcast_func\fP directive.
Finally, a custom string concatenation pattern may be required;
it is provided by the \fBconcat_pattern\fP directive.

.TP
.B upper_func <SQL function name>
Specifies the name of a function that converts a given value to uppercase.
This is used for case insensitive matching when the RDBMS is case sensitive.
It may differ from one SQL dialect to another (e.g. \fBUCASE\fP, \fBUPPER\fP
or whatever; see samples).  By default, none is used, i.e. strings are not
uppercased, so matches may be case sensitive.

.TP
.B upper_needs_cast { NO | yes }
Set this directive to 
.B yes
if 
.B upper_func
needs an explicit cast when applied to literal strings.
A cast in the form
.B CAST (<arg> AS VARCHAR(<max DN length>))
is used, where
.B <max DN length>
is builtin in back-sql; see macro
.B BACKSQL_MAX_DN_LEN
(currently 255; note that slapd's builtin limit, in macro
.BR SLAP_LDAPDN_MAXLEN ,
is set to 8192).
This is \fIexperimental\fP and may change in future releases.

.TP
.B strcast_func <SQL function name>
Specifies the name of a function that converts a given value to a string
for appropriate ordering.  This is used in "SELECT DISTINCT" statements
for strongly typed RDBMSes with little implicit casting (like PostgreSQL),
when a literal string is specified.
This is \fIexperimental\fP and may change in future releases.

.TP
.B concat_pattern <pattern>
This statement defines the
.B pattern 
that is used to concatenate strings.  The
.B pattern
MUST contain two question marks, '?', that will be replaced 
by the two strings that must be concatenated.  The default value is
.BR "CONCAT(?,?)";
a form that is known to be highly portable (IBM db2, PostgreSQL) is 
.BR "?||?",
but an explicit cast may be required when operating on literal strings:
.BR "CAST(?||? AS VARCHAR(<length>))".
On some RDBMSes (IBM db2, MSSQL) the form
.B "?+?"
is known to work as well.
Carefully check the documentation of your RDBMS or stay with the examples
for supported ones.
This is \fIexperimental\fP and may change in future releases.

.TP
.B aliasing_keyword <string>
Define the aliasing keyword.  Some RDBMSes use the word "\fIAS\fP"
(the default), others don't use any.

.TP
.B aliasing_quote <string>
Define the quoting char of the aliasing keyword.  Some RDBMSes 
don't require any (the default), others may require single 
or double quotes.

.TP
.B has_ldapinfo_dn_ru { NO | yes }
Explicitly inform the backend whether the dn_ru column
(DN in reverse uppercased form) is present in table \fIldap_entries\fP.
Overrides automatic check (this is required, for instance,
by PostgreSQL/unixODBC).
This is \fIexperimental\fP and may change in future releases.

.TP
.B fail_if_no_mapping { NO | yes }
When set to
.B yes
it forces \fIattribute\fP write operations to fail if no appropriate
mapping between LDAP attributes and SQL data is available.
The default behavior is to ignore those changes that cannot be mapped.
It has no impact on objectClass mapping, i.e. if the
.I structuralObjectClass
of an entry cannot be mapped to SQL by looking up its name 
in ldap_oc_mappings, an 
.I add
operation will fail regardless of the
.B fail_if_no_mapping
switch; see section "METAINFORMATION USED" for details.
This is \fIexperimental\fP and may change in future releases.

.TP
.B allow_orphans { NO | yes }
When set to 
.B yes
orphaned entries (i.e. without the parent entry in the database)
can be added.  This option should be used with care, possibly 
in conjunction with some special rule on the RDBMS side that
dynamically creates the missing parent.

.TP
.B baseObject [ <filename> ]
Instructs the database to create and manage an in-memory baseObject
entry instead of looking for one in the RDBMS.
If the (optional) 
.B <filename>
argument is given, the entry is read from that file in
.BR LDIF (5)
format; otherwise, an entry with objectClass \fBextensibleObject\fP
is created based on the contents of the RDN of the \fIbaseObject\fP.
This is particularly useful when \fIldap_entries\fP
information is stored in a view rather than in a table, and 
.B union
is not supported for views, so that the view can only specify
one rule to compute the entry structure for one objectClass.
This topic is discussed further in section "METAINFORMATION USED".
This is \fIexperimental\fP and may change in future releases.

.TP
.B create_needs_select { NO | yes }
Instructs the database whether or not entry creation
in table \fIldap_entries\fP needs a subsequent select to collect 
the automatically assigned ID, instead of being returned 
by a stored procedure.

.LP
.B fetch_attrs <attrlist>
.br
.B fetch_all_attrs { NO | yes }
.RS
The first statement allows to provide a list of attributes that
must always be fetched in addition to those requested by any specific
operation, because they are required for the proper usage of the
backend.  For instance, all attributes used in ACLs should be listed
here.  The second statement is a shortcut to require all attributes 
to be always loaded.  Note that the dynamically generated attributes,
e.g. \fIhasSubordinates\fP, \fIentryDN\fP and other implementation
dependent attributes are \fBNOT\fP generated at this point, for
consistency with the rest of slapd.  This may change in the future.
.RE

.TP
.B check_schema { YES | no }
Instructs the database to check schema adherence of entries after
modifications, and structural objectClass chain when entries are built.
By default it is set to 
.BR yes .

.TP
.B sqllayer <name> [...]
Loads the layer \fB<name>\fP onto a stack of helpers that are used 
to map DNs from LDAP to SQL representation and vice-versa.
Subsequent args are passed to the layer configuration routine.
This is \fIhighly experimental\fP and should be used with extreme care.
The API of the layers is not frozen yet, so it is unpublished.

.SH METAINFORMATION USED
.LP
Almost everything mentioned later is illustrated in examples located
in the
.B servers/slapd/back-sql/rdbms_depend/
directory in the OpenLDAP source tree, and contains scripts for
generating sample database for Oracle, MS SQL Server, mySQL and more
(including PostgreSQL and IBM db2).
.LP
The first thing that one must arrange is what set of LDAP
object classes can present your RDBMS information.