2 # Copyright 2007-2012 The OpenLDAP Foundation, All Rights Reserved.
3 # COPYING RESTRICTIONS APPLY, see COPYRIGHT.
7 Backends do the actual work of storing or retrieving data in response
8 to LDAP requests. Backends may be compiled statically into {{slapd}},
9 or when module support is enabled, they may be dynamically loaded.
11 If your installation uses dynamic modules, you may need to add the
12 relevant {{moduleload}} directives to the examples that follow. The
13 name of the module for a backend is usually of the form:
15 > back_<backend name>.la
17 So for example, if you need to load the {{hdb}} backend, you would configure
19 > moduleload back_hdb.la
21 H2: Berkeley DB Backends
26 The {{bdb}} backend to {{slapd}}(8) is the recommended primary backend for a
27 normal {{slapd}} database. It uses the Oracle Berkeley DB ({{TERM:BDB}})
28 package to store data. It makes extensive use of indexing and caching
29 (see the {{SECT:Tuning}} section) to speed data access.
31 {{hdb}} is a variant of the {{bdb}} backend that uses a hierarchical database
32 layout which supports subtree renames. It is otherwise identical to the {{bdb}}
33 behavior, and all the same configuration options apply.
35 Note: An {{hdb}} database needs a large {{idlcachesize}} for good search performance,
36 typically three times the {{cachesize}} (entry cache size) or larger.
38 H3: back-bdb/back-hdb Configuration
42 H3: Further Information
51 The LDAP backend to {{slapd}}(8) is not an actual database; instead it acts
52 as a proxy to forward incoming requests to another LDAP server. While
53 processing requests it will also chase referrals, so that referrals are fully
54 processed instead of being returned to the {{slapd}} client.
56 Sessions that explicitly {{Bind}} to the {{back-ldap}} database always create
57 their own private connection to the remote LDAP server. Anonymous sessions
58 will share a single anonymous connection to the remote server. For sessions
59 bound through other mechanisms, all sessions with the same DN will share the
60 same connection. This connection pooling strategy can enhance the proxy's
61 efficiency by reducing the overhead of repeatedly making/breaking multiple
64 The ldap database can also act as an information service, i.e. the identity
65 of locally authenticated clients is asserted to the remote server, possibly
66 in some modified form. For this purpose, the proxy binds to the remote server
67 with some administrative identity, and, if required, authorizes the asserted
70 It is heavily used by a lot of other {{SECT: Backends}} and {{SECT: Overlays}}.
72 H3: back-ldap Configuration
74 As previously mentioned, {{slapd-ldap(5)}} is used behind the scenes by many
75 other {{SECT: Backends}} and {{SECT: Overlays}}. Some of them merely provide a
76 few configuration directive themselves, but have available to the administrator
77 the whole of the {{slapd-ldap(5)}} options.
79 For example, the {{SECT: Translucent Proxy}}, which retrieves entries from a
80 remote LDAP server that can be partially overridden by the defined database, has
81 only four specific {{translucent-}} directives, but can be configured using any
82 of the normal {{slapd-ldap(5)}} options. See {[slapo-translucent(5)}} for details.
84 Other {{SECT: Overlays}} allow you to tag directives in front of a normal
85 {{slapd-ldap(5)}} directive. For example, the {{slapo-chain(5)}} overlay does
88 {{"There are very few chain overlay specific directives; however, directives
89 related to the instances of the ldap backend that may be implicitly instantiated
90 by the overlay may assume a special meaning when used in conjunction with this
91 overlay. They are described in slapd-ldap(5), and they also need to be prefixed
94 You may have also seen the {{slapd-ldap(5)}} backend used and described in the
95 {{SECT: Push Based}} {{SECT: Replication}} section of the guide.
97 It should therefore be obvious that the {{slapd-ldap(5)}} backend is extremely
98 flexible and heavily used throughout the OpenLDAP Suite.
100 The following is a very simple example, but already the power of the {{slapd-ldap(5)}}
101 backend is seen by use of a {{uri list}}:
104 > suffix "dc=suretecsystems,dc=com"
105 > rootdn "cn=slapd-ldap"
106 > uri ldap://localhost/ ldap://remotehost ldap://remotehost2
108 The URI list is space or comma-separated. Whenever the server that responds
109 is not the first one in the list, the list is rearranged and the responsive
110 server is moved to the head, so that it will be first contacted the next time
111 a connection needs be created.
113 This feature can be used to provide a form of load balancing when using
114 {{SECT: MirrorMode replication}}.
116 H3: Further Information
125 The LDIF backend to {{slapd}}(8) is a basic storage backend that stores
126 entries in text files in LDIF format, and exploits the filesystem to create
127 the tree structure of the database. It is intended as a cheap, low performance
130 When using the {{cn=config}} dynamic configuration database with persistent
131 storage, the configuration data is stored using this backend. See {{slapd-config}}(5)
134 H3: back-ldif Configuration
136 Like many other backends, the LDIF backend can be instantiated with very few
139 > include ./schema/core.schema
143 > suffix "dc=suretecsystems,dc=com"
144 > rootdn "cn=LDIF,dc=suretecsystems,dc=com"
147 If we add the {{dcObject}} for {{dc=suretecsystems,dc=com}}, you can see how this
148 is added behind the scenes on the file system:
150 > dn: dc=suretecsystems,dc=com
151 > objectClass: dcObject
152 > objectClass: organization
154 > o: Suretec Systems Ltd
156 Now we add it to the directory:
158 > ldapadd -x -H ldap://localhost:9011 -f suretec.ldif -D "cn=LDIF,dc=suretecsystems,dc=com" -w LDIF
159 > adding new entry "dc=suretecsystems,dc=com"
161 And inside {{F: ./ldif}} we have:
164 > dc=suretecsystems,dc=com.ldif
166 which again contains:
168 > cat ldif/dc\=suretecsystems\,dc\=com.ldif
170 > dn: dc=suretecsystems
171 > objectClass: dcObject
172 > objectClass: organization
174 > o: Suretec Systems Ltd.
175 > structuralObjectClass: organization
176 > entryUUID: 2134b714-e3a1-102c-9a15-f96ee263886d
177 > creatorsName: cn=LDIF,dc=suretecsystems,dc=com
178 > createTimestamp: 20080711142643Z
179 > entryCSN: 20080711142643.661124Z#000000#000#000000
180 > modifiersName: cn=LDIF,dc=suretecsystems,dc=com
181 > modifyTimestamp: 20080711142643Z
183 This is the complete format you would get when exporting your directory using
186 H3: Further Information
195 The {{mdb}} backend to {{slapd}}(8) is the upcoming primary backend for a
196 normal {{slapd}} database. It uses OpenLDAP's own Memory-Mapped Database ({{TERM:MDB}})
197 library to store data and is intended to replace the Berkeley DB backends.
199 It supports indexing like the BDB backends, but it uses no caching and requires
200 no tuning to deliver maximum search performance. Like {{hdb}}, it is also
201 fully hierarchical and supports subtree renames in constant time.
203 H3: back-mdb Configuration
205 Unlike the BDB backends, the MDB backend can be instantiated with very few
208 > include ./schema/core.schema
212 > suffix "dc=suretecsystems,dc=com"
213 > rootdn "cn=mdb,dc=suretecsystems,dc=com"
217 In addition to the usual parameters that a minimal configuration requires, the MDB
218 backend requires a maximum size to be set. This should be the largest that
219 the database is ever anticipated to grow (in bytes). The filesystem must also
220 provide enough free space to accommodate this size.
222 H3: Further Information
231 The meta backend to {{slapd}}(8) performs basic LDAP proxying with respect
232 to a set of remote LDAP servers, called "targets". The information contained
233 in these servers can be presented as belonging to a single Directory Information
236 A basic knowledge of the functionality of the {{slapd-ldap}}(5) backend is
237 recommended. This backend has been designed as an enhancement of the ldap
238 backend. The two backends share many features (actually they also share portions
239 of code). While the ldap backend is intended to proxy operations directed
240 to a single server, the meta backend is mainly intended for proxying of
241 multiple servers and possibly naming context masquerading.
243 These features, although useful in many scenarios, may result in excessive
244 overhead for some applications, so its use should be carefully considered.
247 H3: back-meta Configuration
251 H3: Further Information
260 The monitor backend to {{slapd}}(8) is not an actual database; if enabled,
261 it is automatically generated and dynamically maintained by slapd with
262 information about the running status of the daemon.
264 To inspect all monitor information, issue a subtree search with base {{cn=Monitor}},
265 requesting that attributes "+" and "*" are returned. The monitor backend produces
266 mostly operational attributes, and LDAP only returns operational attributes
267 that are explicitly requested. Requesting attribute "+" is an extension which
268 requests all operational attributes.
270 See the {{SECT:Monitoring}} section.
272 H3: back-monitor Configuration
274 The monitor database can be instantiated only once, i.e. only one occurrence
275 of "database monitor" can occur in the {{slapd.conf(5)}} file. Also the suffix
276 is automatically set to {{"cn=Monitor"}}.
278 You can however set a {{rootdn}} and {{rootpw}}. The following is all that is
279 needed to instantiate a monitor backend:
281 > include ./schema/core.schema
284 > rootdn "cn=monitoring,cn=Monitor"
287 You can also apply Access Control to this database like any other database, for
290 > access to dn.subtree="cn=Monitor"
291 > by dn.exact="uid=Admin,dc=my,dc=org" write
295 Note: The {{F: core.schema}} must be loaded for the monitor database to work.
297 A small example of the data returned via {{ldapsearch}} would be:
299 > ldapsearch -x -H ldap://localhost:9011 -b 'cn=Monitor'
303 > # base <cn=Monitor> with scope subtree
304 > # filter: (objectclass=*)
310 > objectClass: monitorServer
312 > description: This subtree contains monitoring/managing objects.
313 > description: This object contains information about this server.
314 > description: Most of the information is held in operational attributes, which
315 > must be explicitly requested.
317 > # Backends, Monitor
318 > dn: cn=Backends,cn=Monitor
319 > objectClass: monitorContainer
321 > description: This subsystem contains information about available backends.
323 Please see the {{SECT: Monitoring}} section for complete examples of information
324 available via this backend.
326 H3: Further Information
335 The Null backend to {{slapd}}(8) is surely the most useful part of slapd:
337 * Searches return success but no entries.
338 * Compares return compareFalse.
339 * Updates return success (unless readonly is on) but do nothing.
340 * Binds other than as the rootdn fail unless the database option "bind on" is given.
341 * The slapadd(8) and slapcat(8) tools are equally exciting.
343 Inspired by the {{F:/dev/null}} device.
345 H3: back-null Configuration
347 This has to be one of the shortest configurations you'll ever do. In order to
348 test this, your {{F: slapd.conf}} file would look like:
351 > suffix "cn=Nothing"
356 {{"Allow binds as any DN in this backend's suffix, with any password. The default is "off"."}}
358 To test this backend with {{ldapsearch}}:
360 > ldapsearch -x -H ldap://localhost:9011 -D "uid=none,cn=Nothing" -w testing -b 'cn=Nothing'
364 > # base <cn=Nothing> with scope subtree
365 > # filter: (objectclass=*)
376 H3: Further Information
385 The PASSWD backend to {{slapd}}(8) serves up the user account information
386 listed in the system {{passwd}}(5) file (defaulting to {{F: /etc/passwd}}).
388 This backend is provided for demonstration purposes only. The DN of each entry
389 is "uid=<username>,<suffix>".
391 H3: back-passwd Configuration
393 The configuration using {{F: slapd.conf}} a slightly longer, but not much. For
396 > include ./schema/core.schema
401 Again, testing this with {{ldapsearch}} would result in something like:
403 > ldapsearch -x -H ldap://localhost:9011 -b 'cn=passwd'
407 > # base <cn=passwd> with scope subtree
408 > # filter: (objectclass=*)
415 > objectClass: organizationalUnit
418 > dn: uid=root,cn=passwd
419 > objectClass: person
420 > objectClass: uidObject
427 H3: Further Information
435 The Perl backend to {{slapd}}(8) works by embedding a {{perl}}(1) interpreter
436 into {{slapd}}(8). Any perl database section of the configuration file
437 {{slapd.conf}}(5) must then specify what Perl module to use. Slapd then creates
438 a new Perl object that handles all the requests for that particular instance of the backend.
440 The Shell backend to {{slapd}}(8) executes external programs to implement
441 operations, and is designed to make it easy to tie an existing database to the
442 slapd front-end. This backend is is primarily intended to be used in prototypes.
444 H3: back-perl/back-shell Configuration
448 H3: Further Information
450 {{slapd-shell}}(5) and {{slapd-perl}}(5)
457 The primary purpose of this {{slapd}}(8) backend is to map a naming context
458 defined in a database running in the same {{slapd}}(8) instance into a
459 virtual naming context, with attributeType and objectClass manipulation, if
460 required. It requires the rwm overlay.
462 This backend and the above mentioned overlay are experimental.
464 H3: back-relay Configuration
468 H3: Further Information
477 The primary purpose of this {{slapd}}(8) backend is to PRESENT information
478 stored in some RDBMS as an LDAP subtree without any programming (some SQL and
479 maybe stored procedures can't be considered programming, anyway ;).
481 That is, for example, when you (some ISP) have account information you use in
482 an RDBMS, and want to use modern solutions that expect such information in LDAP
483 (to authenticate users, make email lookups etc.). Or you want to synchronize or
484 distribute information between different sites/applications that use RDBMSes
485 and/or LDAP. Or whatever else...
487 It is {{B:NOT}} designed as a general-purpose backend that uses RDBMS instead of
488 BerkeleyDB (as the standard BDB backend does), though it can be used as such with
489 several limitations. Please see {{SECT: LDAP vs RDBMS}} for discussion.
491 The idea is to use some meta-information to translate LDAP queries to SQL queries,
492 leaving relational schema untouched, so that old applications can continue using
493 it without any modifications. This allows SQL and LDAP applications to interoperate
494 without replication, and exchange data as needed.
496 The SQL backend is designed to be tunable to virtually any relational schema without
497 having to change source (through that meta-information mentioned). Also, it uses
498 ODBC to connect to RDBMSes, and is highly configurable for SQL dialects RDBMSes
499 may use, so it may be used for integration and distribution of data on different
500 RDBMSes, OSes, hosts etc., in other words, in highly heterogeneous environments.
502 This backend is experimental.
504 H3: back-sql Configuration
506 This backend has to be one of the most abused and complex backends there is.
507 Therefore, we will go through a simple, small example that comes with the
508 OpenLDAP source and can be found in {{F: servers/slapd/back-sql/rdbms_depend/README}}
510 For this example we will be using PostgreSQL.
512 First, we add to {{F: /etc/odbc.ini}} a block of the form:
515 > Description = Example for OpenLDAP's back-sql
516 > Driver = PostgreSQL
518 > Database = example <===
519 > Servername = localhost
520 > UserName = manager <===
521 > Password = secret <===
526 > ShowSystemTables = No
531 The relevant information for our test setup is highlighted with '<===' on the
534 Next, we add to {{F: /etc/odbcinst.ini}} a block of the form:
537 > Description = ODBC for PostgreSQL
538 > Driver = /usr/lib/libodbcpsql.so
539 > Setup = /usr/lib/libodbcpsqlS.so
543 We will presume you know how to create a database and user in PostgreSQL and
544 how to set a password. Also, we'll presume you can populate the 'example'
545 database you've just created with the following files, as found in {{F: servers/slapd/back-sql/rdbms_depend/pgsql }}
547 > backsql_create.sql, testdb_create.sql, testdb_data.sql, testdb_metadata.sql
549 Lastly, run the test:
551 > [root@localhost]# cd $SOURCES/tests
552 > [root@localhost]# SLAPD_USE_SQL=pgsql ./run sql-test000
554 Briefly, you should see something like (cut short for space):
556 > Cleaning up test run directory leftover from previous run.
557 > Running ./scripts/sql-test000-read...
559 > Starting slapd on TCP/IP port 9011...
560 > Testing SQL backend read operations...
561 > Waiting 5 seconds for slapd to start...
562 > Testing correct bind... dn:cn=Mitya Kovalev,dc=example,dc=com
563 > Testing incorrect bind (should fail)... ldap_bind: Invalid credentials (49)
567 > Filtering original ldif...
568 > Comparing filter output...
569 > >>>>> Test succeeded
571 The test is basically readonly; this can be performed by all RDBMSes
574 There is another test, sql-test900-write, which is currently enabled
575 only for PostgreSQL and IBM db2.
577 Using {{F: sql-test000}}, files in {{F: servers/slapd/back-sql/rdbms_depend/pgsql/}}
578 and the man page, you should be set.
580 Note: This backend is experimental.
582 H3: Further Information
584 {{slapd-sql}}(5) and {{F: servers/slapd/back-sql/rdbms_depend/README}}