mirror of
https://git.openldap.org/openldap/openldap.git
synced 2025-03-07 14:18:15 +08:00
Added config keyword descriptions from ITS#966. Minor cleanup.
This commit is contained in:
Howard Chu
parent
4ad033a298
commit
d879fb351b
@ -1,10 +1,10 @@
|
||||
.TH SLAPD-SQL 5 "30 April 2002" "OpenLDAP LDVERSION"
|
||||
.TH SLAPD-SQL 5 "01 May 2002" "OpenLDAP LDVERSION"
|
||||
.\" $OpenLDAP$
|
||||
.SH NAME
|
||||
slapd-sql \- SQL backend to slapd
|
||||
.SH SYNOPSIS
|
||||
ETCDIR/slapd.conf
|
||||
.SH PURPOSE
|
||||
.SH DESCRIPTION
|
||||
The primary purpose of this backend (8) to
|
||||
.BR slapd (8)
|
||||
is to PRESENT information stored in some RDBMS as an LDAP subtree
|
||||
@ -12,14 +12,14 @@ 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 RDBMS, and want to use modern solutions that expect such
|
||||
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 general-purpose backend that uses RDBMS instead
|
||||
of BerkeleyDB (as the standard LDBM backend does), though it can be
|
||||
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
|
||||
@ -40,15 +40,70 @@ 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 CONFIGURATION
|
||||
These
|
||||
.B slapd.conf
|
||||
options apply to the SQL backend database.
|
||||
That is, they must follow a "database sql" 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 dbname <datasource name>
|
||||
The name of the ODBC datasource to use.
|
||||
.TP
|
||||
.B dbhost <hostname>
|
||||
.TP
|
||||
.B dbuser <username>
|
||||
.TP
|
||||
.B dbpasswd <password>
|
||||
These three options are generally unneeded, because this information is already
|
||||
taken from the datasource.
|
||||
Use them if you need to override datasource settings.
|
||||
Also, several RDBMS' drivers tend to require explicit passing of user/password,
|
||||
even if those are given in datasource.
|
||||
.TP
|
||||
.B subtree_cond <SQL expression>
|
||||
Specifies a where-clause template used to form a subtree search condition.
|
||||
It may differ from one SQL dialect to another (see samples).
|
||||
.TP
|
||||
.B oc_query <SQL expression>
|
||||
The default is
|
||||
.B "SELECT id, name, keytbl, keycol, create_proc, delete_proc, expect_return FROM ldap_oc_mappings"
|
||||
.TP
|
||||
.B at_query <SQL expression>
|
||||
The default is
|
||||
.B "SELECT name, sel_expr, from_tbls, join_where, add_proc, delete_proc, param_order, expect_return FROM ldap_attr_mappings WHERE oc_map_id=?"
|
||||
.TP
|
||||
.B insentry_query <SQL expression>
|
||||
The default is
|
||||
.B "INSERT INTO ldap_entries (dn, oc_map_id, parent, keyval) VALUES (?, ?, ?, ?)"
|
||||
.TP
|
||||
.B delentry_query <SQL expression>
|
||||
The default is
|
||||
.B "DELETE FROM ldap_entries WHERE id=?"
|
||||
|
||||
These four 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.
|
||||
.TP
|
||||
.B upper_func <SQL function name>
|
||||
Specifies the name of a function that converts a given value to uppercase.
|
||||
This is used for CIS matching when the RDBMS is case sensitive.
|
||||
|
||||
.SH METAINFORMATION USED
|
||||
.LP
|
||||
Almost everything mentioned later is illustrated in examples located
|
||||
in the
|
||||
.B slapd/back-sql/rdbms_depend/
|
||||
directory in the OpenLDAP source tree, and contains scripts for
|
||||
generating sample database for Oracle,MS SQL Server and mySQL.
|
||||
generating sample database for Oracle, MS SQL Server and mySQL.
|
||||
.LP
|
||||
First thing that one must arrange for himself is what set of LDAP
|
||||
The first thing that one must arrange is what set of LDAP
|
||||
object classes can present your RDBMS information.
|
||||
.LP
|
||||
The easiest way is to create an objectclass for each entity you had in
|
||||
@ -60,11 +115,11 @@ tables of normalized schema.
|
||||
It means that for every attribute of every such instance there is an
|
||||
effective SQL query that loads its values.
|
||||
.LP
|
||||
Also you might want your object classes to conform to some of standard
|
||||
Also you might want your object classes to conform to some of the standard
|
||||
schemas like inetOrgPerson etc.
|
||||
.LP
|
||||
Nevertheless, when you think it out, we must define a way to translate
|
||||
LDAP operation requests to (series of) SQL queries.
|
||||
LDAP operation requests to (a series of) SQL queries.
|
||||
Let us deal with the SEARCH operation.
|
||||
.LP
|
||||
Example:
|
||||
@ -91,9 +146,7 @@ An LDAP objectclass to present such information could look like this:
|
||||
person
|
||||
-------
|
||||
MUST cn
|
||||
MAY telephoneNumber
|
||||
MAY firstName
|
||||
MAY lastName
|
||||
MAY telephoneNumber $ firstName $ lastName
|
||||
...
|
||||
.fi
|
||||
.LP
|
||||
@ -123,12 +176,12 @@ If we wanted to service LDAP requests with filters like
|
||||
.fi
|
||||
.LP
|
||||
So, if we had information about what tables contain values for each
|
||||
attribute, how to join this tables and arrange these values, we could
|
||||
attribute, how to join these tables and arrange these values, we could
|
||||
try to automatically generate such statements, and translate search
|
||||
filters to SQL WHERE clauses.
|
||||
.LP
|
||||
To store such information, we add three more tables to our schema, so
|
||||
that and fill it with data (see samples):
|
||||
To store such information, we add three more tables to our schema
|
||||
and fill it with data (see samples):
|
||||
.LP
|
||||
.nf
|
||||
ldap_oc_mappings (some columns are not listed for clarity)
|
||||
@ -140,12 +193,12 @@ that and fill it with data (see samples):
|
||||
.fi
|
||||
.LP
|
||||
This table defines a mapping between objectclass (its name held in the
|
||||
"name" column), and a table that holds primary key for corresponding
|
||||
"name" column), and a table that holds the primary key for corresponding
|
||||
entities.
|
||||
For instance, in our example, the person entity, which we are trying
|
||||
to present as "person" objectclass, resides in two tables (persons and
|
||||
phones), and is identified by persons.id column (that we will call
|
||||
primary key for this entity).
|
||||
phones), and is identified by the persons.id column (that we will call
|
||||
the primary key for this entity).
|
||||
Keytbl and keycol thus contain "persons" (name of the table), and "id"
|
||||
(name of the column).
|
||||
.LP
|
||||
@ -171,27 +224,27 @@ This table defines mappings between LDAP attributes and SQL queries
|
||||
that load their values.
|
||||
Note that, unlike LDAP schema, these are not
|
||||
.B attribute types
|
||||
- attribute "cn" for "person" objectclass can well
|
||||
have its values in different table than "cn" for other objectclass,
|
||||
- the attribute "cn" for "person" objectclass can
|
||||
have its values in different tables than "cn" for some other objectclass,
|
||||
so attribute mappings depend on objectclass mappings (unlike attribute
|
||||
types in LDAP schema, which are indifferent to objectclasses).
|
||||
Thus, we have oc_map_id column with link to oc_mappings table.
|
||||
.LP
|
||||
Now we cut the SQL query that loads values for given attribute into 3 parts.
|
||||
Now we cut the SQL query that loads values for a given attribute into 3 parts.
|
||||
First goes into sel_expr column - this is the expression we had
|
||||
between SELECT and FROM keywords, which defines WHAT to load.
|
||||
Next is table list - text between FROM and WHERE keywords.
|
||||
It may contain aliases for convenience (see exapmles).
|
||||
The last is part of where clause, which (if exists at all) express the
|
||||
condition for joining the table containing values wich table
|
||||
containing primary key (foreign key equality and such).
|
||||
If values are in the same table with primary key, then this column is
|
||||
It may contain aliases for convenience (see examples).
|
||||
The last is part of the where clause, which (if it exists at all) expresses the
|
||||
condition for joining the table containing values with the table
|
||||
containing the primary key (foreign key equality and such).
|
||||
If values are in the same table as the primary key, then this column is
|
||||
left NULL (as for cn attribute above).
|
||||
.LP
|
||||
Having this information in parts, we are able to not only construct
|
||||
queries that load attribute values by id of entry (for this we could
|
||||
store SQL query as a whole), but to construct queries that load id's
|
||||
of objects that correspond to given search filter (or at least part of
|
||||
of objects that correspond to a given search filter (or at least part of
|
||||
it).
|
||||
See below for examples.
|
||||
.LP
|
||||
@ -211,20 +264,20 @@ It has recursive structure (parent column references id column of the
|
||||
same table), which allows you to add any tree structure(s) to your
|
||||
flat relational data.
|
||||
Having id of objectclass mapping, we can determine table and column
|
||||
for primary key, and keyval stores value of it, thus defining exact
|
||||
tuple corresponding to LDAP entry with this DN.
|
||||
for primary key, and keyval stores value of it, thus defining the exact
|
||||
tuple corresponding to the LDAP entry with this DN.
|
||||
.LP
|
||||
Note that such design (see exact SQL table creation query) implies one
|
||||
important constraint - the key must be integer.
|
||||
But all that I know about well-designed schemas makes me think that it
|
||||
s not very narrow ;) If anyone needs support for different types for
|
||||
important constraint - the key must be an integer.
|
||||
But all that I know about well-designed schemas makes me think that it's
|
||||
not very narrow ;) If anyone needs support for different types for
|
||||
keys - he may want to write a patch, and submit it to OpenLDAP ITS,
|
||||
then I'll include it.
|
||||
.LP
|
||||
Also, several people complained that they don't really need very
|
||||
structured tree, and they don't want to update one more table every
|
||||
time they add or delete instance in relational schema.
|
||||
Those can use a view instead of real table for ldap_entries, something
|
||||
structured trees, and they don't want to update one more table every
|
||||
time they add or delete an instance in the relational schema.
|
||||
Those people can use a view instead of a real table for ldap_entries, something
|
||||
like this (by Robin Elfrink):
|
||||
.LP
|
||||
.nf
|
||||
@ -244,7 +297,7 @@ scope and filter).
|
||||
It tries to do it for each objectclass registered in ldap_objclasses.
|
||||
.LP
|
||||
Example:
|
||||
for our query with filter (telephoneNumber=123*) we would get following
|
||||
for our query with filter (telephoneNumber=123*) we would get the following
|
||||
query generated (which loads candidate IDs)
|
||||
.LP
|
||||
.nf
|
||||
@ -262,7 +315,7 @@ query generated (which loads candidate IDs)
|
||||
or "... AND dn=?" (for BASE search)
|
||||
or "... AND dn LIKE '%?'" (for SUBTREE)
|
||||
.LP
|
||||
Then, for each candidate, we load attributes requested using
|
||||
Then, for each candidate, we load the requested attributes using
|
||||
per-attribute queries like
|
||||
.LP
|
||||
.nf
|
||||
@ -271,54 +324,54 @@ per-attribute queries like
|
||||
WHERE persons.id=? AND phones.pers_id=persons.id
|
||||
.fi
|
||||
.LP
|
||||
Then, we use test_filter() from frontend API to test entry for full
|
||||
Then, we use test_filter() from the frontend API to test the entry for a full
|
||||
LDAP search filter match (since we cannot effectively make sense of
|
||||
SYNTAX of corresponding LDAP schema attribute, we translate the filter
|
||||
into most relaxed SQL condition to filter candidates), and send it to
|
||||
user.
|
||||
into the most relaxed SQL condition to filter candidates), and send it to
|
||||
the user.
|
||||
.LP
|
||||
ADD, DELETE, MODIFY operations also performed on per-attribute
|
||||
ADD, DELETE, MODIFY operations are also performed on per-attribute
|
||||
metainformation (add_proc etc.).
|
||||
In those fields one can specify an SQL statement or stored procedure
|
||||
call which can add, or delete given value of given attribute, using
|
||||
given entry keyval (see examples -- mostly ORACLE and MSSQL - since
|
||||
call which can add, or delete given values of a given attribute, using
|
||||
the given entry keyval (see examples -- mostly ORACLE and MSSQL - since
|
||||
there're no stored procs in mySQL).
|
||||
.LP
|
||||
We just add more columns to oc_mappings and attr_mappings, holding
|
||||
statements to execute (like create_proc, add_proc, del_proc etc.), and
|
||||
flags governing order of parameters passed to those statements.
|
||||
flags governing the order of parameters passed to those statements.
|
||||
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.)
|
||||
First of all, lets remember that among other major differences to
|
||||
First of all, lets remember that among other major differences to the
|
||||
complete LDAP data model, the concept above does not directly support
|
||||
such things as multiple objectclasses for entry, and referrals.
|
||||
such things as multiple objectclasses per entry, and referrals.
|
||||
Fortunately, they are easy to adopt in this scheme.
|
||||
The SQL backend suggests two more tables being added to schema -
|
||||
The SQL backend suggests two more tables being added to the schema -
|
||||
ldap_entry_objectclasses(entry_id,oc_name), and
|
||||
ldap_referrals(entry_id,url).
|
||||
.LP
|
||||
First contains any number of objectclass names that corresponding
|
||||
The first contains any number of objectclass names that corresponding
|
||||
entries will be found by, in addition to that mentioned in
|
||||
mapping.
|
||||
The SQL backend automatically adds attribute mapping for "objectclass"
|
||||
attribute to each objectclass mapping, that loads values from this table.
|
||||
So, you may, for instance, have mapping for inetOrgPerson, and use it
|
||||
The SQL backend automatically adds attribute mapping for the "objectclass"
|
||||
attribute to each objectclass mapping that loads values from this table.
|
||||
So, you may, for instance, have a mapping for inetOrgPerson, and use it
|
||||
for queries for "person" objectclass...
|
||||
.LP
|
||||
Second table contains any number of referrals associated with given entry.
|
||||
The second table contains any number of referrals associated with a given entry.
|
||||
The SQL backend automatically adds attribute mapping for "ref" attribute
|
||||
to each objectclass mapping, that loads values from this table.
|
||||
to each objectclass mapping that loads values from this table.
|
||||
So, if you add objectclass "referral" to this entry, and make one or
|
||||
more tuples in ldap_referrals for this entry (they will be seen as
|
||||
values of "ref" attribute), you will have slapd return referral, as
|
||||
described in Administrators Guide.
|
||||
values of "ref" attribute), you will have slapd return a referral, as
|
||||
described in the Administrators Guide.
|
||||
.LP
|
||||
.SH EXAMPLES
|
||||
There are example SQL modules in the slapd/back-sql/rdbms_depend/
|
||||
direcetory in the OpenLDAP source tree.
|
||||
directory in the OpenLDAP source tree.
|
||||
.SH FILES
|
||||
ETCDIR/slapd.conf
|
||||
.SH SEE ALSO
|
||||
|
||||
Loading…
Reference in New Issue
Block a user