# $OpenLDAP$
-# Copyright 2007 The OpenLDAP Foundation, All Rights Reserved.
+# Copyright 2007-2012 The OpenLDAP Foundation, All Rights Reserved.
# COPYING RESTRICTIONS APPLY, see COPYRIGHT.
H1: Backends
+Backends do the actual work of storing or retrieving data in response
+to LDAP requests. Backends may be compiled statically into {{slapd}},
+or when module support is enabled, they may be dynamically loaded.
-H2: Berkley DB Backends
+If your installation uses dynamic modules, you may need to add the
+relevant {{moduleload}} directives to the examples that follow. The
+name of the module for a backend is usually of the form:
+
+> back_<backend name>.la
+
+So for example, if you need to load the {{hdb}} backend, you would configure
+
+> moduleload back_hdb.la
+
+H2: Berkeley DB Backends
H3: Overview
The {{bdb}} backend to {{slapd}}(8) is the recommended primary backend for a
normal {{slapd}} database. It uses the Oracle Berkeley DB ({{TERM:BDB}})
package to store data. It makes extensive use of indexing and caching
-(see {{SECT:Tuning}}) to speed data access.
+(see the {{SECT:Tuning}} section) to speed data access.
{{hdb}} is a variant of the {{bdb}} backend that uses a hierarchical database
layout which supports subtree renames. It is otherwise identical to the {{bdb}}
their own private connection to the remote LDAP server. Anonymous sessions
will share a single anonymous connection to the remote server. For sessions
bound through other mechanisms, all sessions with the same DN will share the
-same connection. This connection pooling strategy can enhance the proxy’s
+same connection. This connection pooling strategy can enhance the proxy's
efficiency by reducing the overhead of repeatedly making/breaking multiple
connections.
with some administrative identity, and, if required, authorizes the asserted
identity.
+It is heavily used by a lot of other {{SECT: Backends}} and {{SECT: Overlays}}.
+
H3: back-ldap Configuration
-LATER
+As previously mentioned, {{slapd-ldap(5)}} is used behind the scenes by many
+other {{SECT: Backends}} and {{SECT: Overlays}}. Some of them merely provide a
+few configuration directive themselves, but have available to the administrator
+the whole of the {{slapd-ldap(5)}} options.
+
+For example, the {{SECT: Translucent Proxy}}, which retrieves entries from a
+remote LDAP server that can be partially overridden by the defined database, has
+only four specific {{translucent-}} directives, but can be configured using any
+of the normal {{slapd-ldap(5)}} options. See {[slapo-translucent(5)}} for details.
+
+Other {{SECT: Overlays}} allow you to tag directives in front of a normal
+{{slapd-ldap(5)}} directive. For example, the {{slapo-chain(5)}} overlay does
+this:
+
+{{"There are very few chain overlay specific directives; however, directives
+related to the instances of the ldap backend that may be implicitly instantiated
+by the overlay may assume a special meaning when used in conjunction with this
+overlay. They are described in slapd-ldap(5), and they also need to be prefixed
+by chain-."}}
+
+You may have also seen the {{slapd-ldap(5)}} backend used and described in the
+{{SECT: Push Based}} {{SECT: Replication}} section of the guide.
+
+It should therefore be obvious that the {{slapd-ldap(5)}} backend is extremely
+flexible and heavily used throughout the OpenLDAP Suite.
+
+The following is a very simple example, but already the power of the {{slapd-ldap(5)}}
+backend is seen by use of a {{uri list}}:
+
+> database ldap
+> suffix "dc=suretecsystems,dc=com"
+> rootdn "cn=slapd-ldap"
+> uri ldap://localhost/ ldap://remotehost ldap://remotehost2
+
+The URI list is space or comma-separated. Whenever the server that responds
+is not the first one in the list, the list is rearranged and the responsive
+server is moved to the head, so that it will be first contacted the next time
+a connection needs be created.
+
+This feature can be used to provide a form of load balancing when using
+{{SECT: MirrorMode replication}}.
H3: Further Information
The LDIF backend to {{slapd}}(8) is a basic storage backend that stores
entries in text files in LDIF format, and exploits the filesystem to create
the tree structure of the database. It is intended as a cheap, low performance
-easy to use backend, and it is exploited by higher-level internal structures
-to provide a permanent storage.
+easy to use backend.
-When using Dynamic configuration over LDAP via {{cn=config}}, this is where all
-configuration is stored if {{slapd}}(8) if started with {{-F}}. See {{slapd-config.5}](5)
+When using the {{cn=config}} dynamic configuration database with persistent
+storage, the configuration data is stored using this backend. See {{slapd-config}}(5)
for more information
H3: back-ldif Configuration
-LATER
+Like many other backends, the LDIF backend can be instantiated with very few
+configuration lines:
+
+> include ./schema/core.schema
+>
+> database ldif
+> directory ./ldif
+> suffix "dc=suretecsystems,dc=com"
+> rootdn "cn=LDIF,dc=suretecsystems,dc=com"
+> rootpw LDIF
+
+If we add the {{dcObject}} for {{dc=suretecsystems,dc=com}}, you can see how this
+is added behind the scenes on the file system:
+
+> dn: dc=suretecsystems,dc=com
+> objectClass: dcObject
+> objectClass: organization
+> dc: suretecsystems
+> o: Suretec Systems Ltd
+
+Now we add it to the directory:
+
+> ldapadd -x -H ldap://localhost:9011 -f suretec.ldif -D "cn=LDIF,dc=suretecsystems,dc=com" -w LDIF
+> adding new entry "dc=suretecsystems,dc=com"
+
+And inside {{F: ./ldif}} we have:
+
+> ls ./ldif
+> dc=suretecsystems,dc=com.ldif
+
+which again contains:
+
+> cat ldif/dc\=suretecsystems\,dc\=com.ldif
+>
+> dn: dc=suretecsystems
+> objectClass: dcObject
+> objectClass: organization
+> dc: suretecsystems
+> o: Suretec Systems Ltd.
+> structuralObjectClass: organization
+> entryUUID: 2134b714-e3a1-102c-9a15-f96ee263886d
+> creatorsName: cn=LDIF,dc=suretecsystems,dc=com
+> createTimestamp: 20080711142643Z
+> entryCSN: 20080711142643.661124Z#000000#000#000000
+> modifiersName: cn=LDIF,dc=suretecsystems,dc=com
+> modifyTimestamp: 20080711142643Z
+
+This is the complete format you would get when exporting your directory using
+{{F: slapcat}} etc.
H3: Further Information
{{slapd-ldif}}(5)
+H2: MDB
+
+
+H3: Overview
+
+The {{mdb}} backend to {{slapd}}(8) is the upcoming primary backend for a
+normal {{slapd}} database. It uses OpenLDAP's own Memory-Mapped Database ({{TERM:MDB}})
+library to store data and is intended to replace the Berkeley DB backends.
+
+It supports indexing like the BDB backends, but it uses no caching and requires
+no tuning to deliver maximum search performance. Like {{hdb}}, it is also
+fully hierarchical and supports subtree renames in constant time.
+
+H3: back-mdb Configuration
+
+Unlike the BDB backends, the MDB backend can be instantiated with very few
+configuration lines:
+
+> include ./schema/core.schema
+>
+> database mdb
+> directory ./mdb
+> suffix "dc=suretecsystems,dc=com"
+> rootdn "cn=mdb,dc=suretecsystems,dc=com"
+> rootpw mdb
+> maxsize 1073741824
+
+In addition to the usual parameters that a minimal configuration requires, the MDB
+backend requires a maximum size to be set. This should be the largest that
+the database is ever anticipated to grow (in bytes). The filesystem must also
+provide enough free space to accommodate this size.
+
+H3: Further Information
+
+{{slapd-mdb}}(5)
+
H2: Metadirectory
H3: back-monitor Configuration
-LATER
+The monitor database can be instantiated only once, i.e. only one occurrence
+of "database monitor" can occur in the {{slapd.conf(5)}} file. Also the suffix
+is automatically set to {{"cn=Monitor"}}.
+
+You can however set a {{rootdn}} and {{rootpw}}. The following is all that is
+needed to instantiate a monitor backend:
+
+> include ./schema/core.schema
+>
+> database monitor
+> rootdn "cn=monitoring,cn=Monitor"
+> rootpw monitoring
+
+You can also apply Access Control to this database like any other database, for
+example:
+
+> access to dn.subtree="cn=Monitor"
+> by dn.exact="uid=Admin,dc=my,dc=org" write
+> by users read
+> by * none
+
+Note: The {{F: core.schema}} must be loaded for the monitor database to work.
+
+A small example of the data returned via {{ldapsearch}} would be:
+
+> ldapsearch -x -H ldap://localhost:9011 -b 'cn=Monitor'
+> # extended LDIF
+> #
+> # LDAPv3
+> # base <cn=Monitor> with scope subtree
+> # filter: (objectclass=*)
+> # requesting: ALL
+> #
+>
+> # Monitor
+> dn: cn=Monitor
+> objectClass: monitorServer
+> cn: Monitor
+> description: This subtree contains monitoring/managing objects.
+> description: This object contains information about this server.
+> description: Most of the information is held in operational attributes, which
+> must be explicitly requested.
+>
+> # Backends, Monitor
+> dn: cn=Backends,cn=Monitor
+> objectClass: monitorContainer
+> cn: Backends
+> description: This subsystem contains information about available backends.
+
+Please see the {{SECT: Monitoring}} section for complete examples of information
+available via this backend.
H3: Further Information
The Null backend to {{slapd}}(8) 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 other than as the rootdn fail unless the database option "bind on" is given.
-- The slapadd(8) and slapcat(8) tools are equally exciting.
+* Searches return success but no entries.
+* Compares return compareFalse.
+* Updates return success (unless readonly is on) but do nothing.
+* Binds other than as the rootdn fail unless the database option "bind on" is given.
+* The slapadd(8) and slapcat(8) tools are equally exciting.
Inspired by the {{F:/dev/null}} device.
H3: back-null Configuration
-LATER
+This has to be one of the shortest configurations you'll ever do. In order to
+test this, your {{F: slapd.conf}} file would look like:
+
+> database null
+> suffix "cn=Nothing"
+> bind on
+
+{{bind on}} means:
+
+{{"Allow binds as any DN in this backend's suffix, with any password. The default is "off"."}}
+
+To test this backend with {{ldapsearch}}:
+
+> ldapsearch -x -H ldap://localhost:9011 -D "uid=none,cn=Nothing" -w testing -b 'cn=Nothing'
+> # extended LDIF
+> #
+> # LDAPv3
+> # base <cn=Nothing> with scope subtree
+> # filter: (objectclass=*)
+> # requesting: ALL
+> #
+>
+> # search result
+> search: 2
+> result: 0 Success
+>
+> # numResponses: 1
+
H3: Further Information
H3: Overview
The PASSWD backend to {{slapd}}(8) serves up the user account information
-listed in the system {{passwd}}(5) file.
+listed in the system {{passwd}}(5) file (defaulting to {{F: /etc/passwd}}).
This backend is provided for demonstration purposes only. The DN of each entry
is "uid=<username>,<suffix>".
H3: back-passwd Configuration
-LATER
+The configuration using {{F: slapd.conf}} a slightly longer, but not much. For
+example:
+
+> include ./schema/core.schema
+>
+> database passwd
+> suffix "cn=passwd"
+
+Again, testing this with {{ldapsearch}} would result in something like:
+
+> ldapsearch -x -H ldap://localhost:9011 -b 'cn=passwd'
+> # extended LDIF
+> #
+> # LDAPv3
+> # base <cn=passwd> with scope subtree
+> # filter: (objectclass=*)
+> # requesting: ALL
+> #
+>
+> # passwd
+> dn: cn=passwd
+> cn: passwd
+> objectClass: organizationalUnit
+>
+> # root, passwd
+> dn: uid=root,cn=passwd
+> objectClass: person
+> objectClass: uidObject
+> uid: root
+> cn: root
+> sn: root
+> description: root
+
H3: Further Information
The primary purpose of this {{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 ;).
+maybe stored procedures can't be considered programming, anyway ;).
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
distribute information between different sites/applications that use RDBMSes
and/or LDAP. Or whatever else...
-It is NOT designed as a general-purpose backend that uses RDBMS instead of
+It is {{B: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 {{URL: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.
+several limitations. Please see {{SECT: LDAP vs RDBMS}} for discussion.
The idea is to use some meta-information to translate LDAP queries to SQL queries,
leaving relational schema untouched, so that old applications can continue using
having to change source (through that meta-information 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.
+RDBMSes, OSes, hosts etc., in other words, in highly heterogeneous environments.
This backend is experimental.
H3: back-sql Configuration
-LATER
+This backend has to be one of the most abused and complex backends there is.
+Therefore, we will go through a simple, small example that comes with the
+OpenLDAP source and can be found in {{F: servers/slapd/back-sql/rdbms_depend/README}}
+
+For this example we will be using PostgreSQL.
+
+First, we add to {{F: /etc/odbc.ini}} a block of the form:
+
+> [example] <===
+> Description = Example for OpenLDAP's back-sql
+> Driver = PostgreSQL
+> Trace = No
+> Database = example <===
+> Servername = localhost
+> UserName = manager <===
+> Password = secret <===
+> Port = 5432
+> ;Protocol = 6.4
+> ReadOnly = No
+> RowVersioning = No
+> ShowSystemTables = No
+> ShowOidColumn = No
+> FakeOidIndex = No
+> ConnSettings =
+
+The relevant information for our test setup is highlighted with '<===' on the
+right above.
+
+Next, we add to {{F: /etc/odbcinst.ini}} a block of the form:
+
+> [PostgreSQL]
+> Description = ODBC for PostgreSQL
+> Driver = /usr/lib/libodbcpsql.so
+> Setup = /usr/lib/libodbcpsqlS.so
+> FileUsage = 1
+
+
+We will presume you know how to create a database and user in PostgreSQL and
+how to set a password. Also, we'll presume you can populate the 'example'
+database you've just created with the following files, as found in {{F: servers/slapd/back-sql/rdbms_depend/pgsql }}
+
+> backsql_create.sql, testdb_create.sql, testdb_data.sql, testdb_metadata.sql
+
+Lastly, run the test:
+
+> [root@localhost]# cd $SOURCES/tests
+> [root@localhost]# SLAPD_USE_SQL=pgsql ./run sql-test000
+
+Briefly, you should see something like (cut short for space):
+
+> Cleaning up test run directory leftover from previous run.
+> Running ./scripts/sql-test000-read...
+> running defines.sh
+> Starting slapd on TCP/IP port 9011...
+> Testing SQL backend read operations...
+> Waiting 5 seconds for slapd to start...
+> Testing correct bind... dn:cn=Mitya Kovalev,dc=example,dc=com
+> Testing incorrect bind (should fail)... ldap_bind: Invalid credentials (49)
+>
+> ......
+>
+> Filtering original ldif...
+> Comparing filter output...
+> >>>>> Test succeeded
+
+The test is basically readonly; this can be performed by all RDBMSes
+(listed above).
+
+There is another test, sql-test900-write, which is currently enabled
+only for PostgreSQL and IBM db2.
+
+Using {{F: sql-test000}}, files in {{F: servers/slapd/back-sql/rdbms_depend/pgsql/}}
+and the man page, you should be set.
+
+Note: This backend is experimental.
H3: Further Information
-{{slapd-sql}}(5)
+{{slapd-sql}}(5) and {{F: servers/slapd/back-sql/rdbms_depend/README}}
projects / openldap / blobdiff