2 # Copyright 2007-2013 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 {{hdb}} 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 original {{bdb}} backend which was first written for use with BDB.
32 {{hdb}} uses a hierarchical database layout which supports subtree renames.
33 It is otherwise identical to the {{bdb}}
34 behavior, and all the same configuration options apply.
36 Note: An {{hdb}} database needs a large {{idlcachesize}} for good search performance,
37 typically three times the {{cachesize}} (entry cache size) or larger.
39 Note: The {{hdb}} backend has superseded the {{bdb}} backend, and both will
40 soon be deprecated in favor of the new {{mdb}} backend. See below.
42 H3: back-bdb/back-hdb Configuration
46 H3: Further Information
55 The LDAP backend to {{slapd}}(8) is not an actual database; instead it acts
56 as a proxy to forward incoming requests to another LDAP server. While
57 processing requests it will also chase referrals, so that referrals are fully
58 processed instead of being returned to the {{slapd}} client.
60 Sessions that explicitly {{Bind}} to the {{back-ldap}} database always create
61 their own private connection to the remote LDAP server. Anonymous sessions
62 will share a single anonymous connection to the remote server. For sessions
63 bound through other mechanisms, all sessions with the same DN will share the
64 same connection. This connection pooling strategy can enhance the proxy's
65 efficiency by reducing the overhead of repeatedly making/breaking multiple
68 The ldap database can also act as an information service, i.e. the identity
69 of locally authenticated clients is asserted to the remote server, possibly
70 in some modified form. For this purpose, the proxy binds to the remote server
71 with some administrative identity, and, if required, authorizes the asserted
74 It is heavily used by a lot of other {{SECT: Backends}} and {{SECT: Overlays}}.
76 H3: back-ldap Configuration
78 As previously mentioned, {{slapd-ldap(5)}} is used behind the scenes by many
79 other {{SECT: Backends}} and {{SECT: Overlays}}. Some of them merely provide a
80 few configuration directive themselves, but have available to the administrator
81 the whole of the {{slapd-ldap(5)}} options.
83 For example, the {{SECT: Translucent Proxy}}, which retrieves entries from a
84 remote LDAP server that can be partially overridden by the defined database, has
85 only four specific {{translucent-}} directives, but can be configured using any
86 of the normal {{slapd-ldap(5)}} options. See {[slapo-translucent(5)}} for details.
88 Other {{SECT: Overlays}} allow you to tag directives in front of a normal
89 {{slapd-ldap(5)}} directive. For example, the {{slapo-chain(5)}} overlay does
92 {{"There are very few chain overlay specific directives; however, directives
93 related to the instances of the ldap backend that may be implicitly instantiated
94 by the overlay may assume a special meaning when used in conjunction with this
95 overlay. They are described in slapd-ldap(5), and they also need to be prefixed
98 You may have also seen the {{slapd-ldap(5)}} backend used and described in the
99 {{SECT: Push Based}} {{SECT: Replication}} section of the guide.
101 It should therefore be obvious that the {{slapd-ldap(5)}} backend is extremely
102 flexible and heavily used throughout the OpenLDAP Suite.
104 The following is a very simple example, but already the power of the {{slapd-ldap(5)}}
105 backend is seen by use of a {{uri list}}:
108 > suffix "dc=suretecsystems,dc=com"
109 > rootdn "cn=slapd-ldap"
110 > uri ldap://localhost/ ldap://remotehost ldap://remotehost2
112 The URI list is space or comma-separated. Whenever the server that responds
113 is not the first one in the list, the list is rearranged and the responsive
114 server is moved to the head, so that it will be first contacted the next time
115 a connection needs be created.
117 This feature can be used to provide a form of load balancing when using
118 {{SECT: MirrorMode replication}}.
120 H3: Further Information
129 The LDIF backend to {{slapd}}(8) is a basic storage backend that stores
130 entries in text files in LDIF format, and exploits the filesystem to create
131 the tree structure of the database. It is intended as a cheap, low performance
134 When using the {{cn=config}} dynamic configuration database with persistent
135 storage, the configuration data is stored using this backend. See {{slapd-config}}(5)
138 H3: back-ldif Configuration
140 Like many other backends, the LDIF backend can be instantiated with very few
143 > include ./schema/core.schema
147 > suffix "dc=suretecsystems,dc=com"
148 > rootdn "cn=LDIF,dc=suretecsystems,dc=com"
151 If we add the {{dcObject}} for {{dc=suretecsystems,dc=com}}, you can see how this
152 is added behind the scenes on the file system:
154 > dn: dc=suretecsystems,dc=com
155 > objectClass: dcObject
156 > objectClass: organization
158 > o: Suretec Systems Ltd
160 Now we add it to the directory:
162 > ldapadd -x -H ldap://localhost:9011 -f suretec.ldif -D "cn=LDIF,dc=suretecsystems,dc=com" -w LDIF
163 > adding new entry "dc=suretecsystems,dc=com"
165 And inside {{F: ./ldif}} we have:
168 > dc=suretecsystems,dc=com.ldif
170 which again contains:
172 > cat ldif/dc\=suretecsystems\,dc\=com.ldif
174 > dn: dc=suretecsystems
175 > objectClass: dcObject
176 > objectClass: organization
178 > o: Suretec Systems Ltd.
179 > structuralObjectClass: organization
180 > entryUUID: 2134b714-e3a1-102c-9a15-f96ee263886d
181 > creatorsName: cn=LDIF,dc=suretecsystems,dc=com
182 > createTimestamp: 20080711142643Z
183 > entryCSN: 20080711142643.661124Z#000000#000#000000
184 > modifiersName: cn=LDIF,dc=suretecsystems,dc=com
185 > modifyTimestamp: 20080711142643Z
187 This is the complete format you would get when exporting your directory using
190 H3: Further Information
199 The {{mdb}} backend to {{slapd}}(8) is the upcoming primary backend for a
200 normal {{slapd}} database. It uses OpenLDAP's own
201 Lightning Memory-Mapped Database ({{TERM:LMDB}})
202 library to store data and is intended to replace the Berkeley DB backends.
204 It supports indexing like the BDB backends, but it uses no caching and requires
205 no tuning to deliver maximum search performance. Like {{hdb}}, it is also
206 fully hierarchical and supports subtree renames in constant time.
208 H3: back-mdb Configuration
210 Unlike the BDB backends, the {{mdb}} backend can be instantiated with very few
213 > include ./schema/core.schema
217 > suffix "dc=suretecsystems,dc=com"
218 > rootdn "cn=mdb,dc=suretecsystems,dc=com"
222 In addition to the usual parameters that a minimal configuration requires, the {{mdb}}
223 backend requires a maximum size to be set. This should be the largest that
224 the database is ever anticipated to grow (in bytes). The filesystem must also
225 provide enough free space to accommodate this size.
227 H3: Further Information
236 The meta backend to {{slapd}}(8) performs basic LDAP proxying with respect
237 to a set of remote LDAP servers, called "targets". The information contained
238 in these servers can be presented as belonging to a single Directory Information
241 A basic knowledge of the functionality of the {{slapd-ldap}}(5) backend is
242 recommended. This backend has been designed as an enhancement of the ldap
243 backend. The two backends share many features (actually they also share portions
244 of code). While the ldap backend is intended to proxy operations directed
245 to a single server, the meta backend is mainly intended for proxying of
246 multiple servers and possibly naming context masquerading.
248 These features, although useful in many scenarios, may result in excessive
249 overhead for some applications, so its use should be carefully considered.
252 H3: back-meta Configuration
256 H3: Further Information
265 The monitor backend to {{slapd}}(8) is not an actual database; if enabled,
266 it is automatically generated and dynamically maintained by slapd with
267 information about the running status of the daemon.
269 To inspect all monitor information, issue a subtree search with base {{cn=Monitor}},
270 requesting that attributes "+" and "*" are returned. The monitor backend produces
271 mostly operational attributes, and LDAP only returns operational attributes
272 that are explicitly requested. Requesting attribute "+" is an extension which
273 requests all operational attributes.
275 See the {{SECT:Monitoring}} section.
277 H3: back-monitor Configuration
279 The monitor database can be instantiated only once, i.e. only one occurrence
280 of "database monitor" can occur in the {{slapd.conf(5)}} file. Also the suffix
281 is automatically set to {{"cn=Monitor"}}.
283 You can however set a {{rootdn}} and {{rootpw}}. The following is all that is
284 needed to instantiate a monitor backend:
286 > include ./schema/core.schema
289 > rootdn "cn=monitoring,cn=Monitor"
292 You can also apply Access Control to this database like any other database, for
295 > access to dn.subtree="cn=Monitor"
296 > by dn.exact="uid=Admin,dc=my,dc=org" write
300 Note: The {{F: core.schema}} must be loaded for the monitor database to work.
302 A small example of the data returned via {{ldapsearch}} would be:
304 > ldapsearch -x -H ldap://localhost:9011 -b 'cn=Monitor'
308 > # base <cn=Monitor> with scope subtree
309 > # filter: (objectclass=*)
315 > objectClass: monitorServer
317 > description: This subtree contains monitoring/managing objects.
318 > description: This object contains information about this server.
319 > description: Most of the information is held in operational attributes, which
320 > must be explicitly requested.
322 > # Backends, Monitor
323 > dn: cn=Backends,cn=Monitor
324 > objectClass: monitorContainer
326 > description: This subsystem contains information about available backends.
328 Please see the {{SECT: Monitoring}} section for complete examples of information
329 available via this backend.
331 H3: Further Information
340 The Null backend to {{slapd}}(8) is surely the most useful part of slapd:
342 * Searches return success but no entries.
343 * Compares return compareFalse.
344 * Updates return success (unless readonly is on) but do nothing.
345 * Binds other than as the rootdn fail unless the database option "bind on" is given.
346 * The slapadd(8) and slapcat(8) tools are equally exciting.
348 Inspired by the {{F:/dev/null}} device.
350 H3: back-null Configuration
352 This has to be one of the shortest configurations you'll ever do. In order to
353 test this, your {{F: slapd.conf}} file would look like:
356 > suffix "cn=Nothing"
361 {{"Allow binds as any DN in this backend's suffix, with any password. The default is "off"."}}
363 To test this backend with {{ldapsearch}}:
365 > ldapsearch -x -H ldap://localhost:9011 -D "uid=none,cn=Nothing" -w testing -b 'cn=Nothing'
369 > # base <cn=Nothing> with scope subtree
370 > # filter: (objectclass=*)
381 H3: Further Information
390 The PASSWD backend to {{slapd}}(8) serves up the user account information
391 listed in the system {{passwd}}(5) file (defaulting to {{F: /etc/passwd}}).
393 This backend is provided for demonstration purposes only. The DN of each entry
394 is "uid=<username>,<suffix>".
396 H3: back-passwd Configuration
398 The configuration using {{F: slapd.conf}} a slightly longer, but not much. For
401 > include ./schema/core.schema
406 Again, testing this with {{ldapsearch}} would result in something like:
408 > ldapsearch -x -H ldap://localhost:9011 -b 'cn=passwd'
412 > # base <cn=passwd> with scope subtree
413 > # filter: (objectclass=*)
420 > objectClass: organizationalUnit
423 > dn: uid=root,cn=passwd
424 > objectClass: person
425 > objectClass: uidObject
432 H3: Further Information
440 The Perl backend to {{slapd}}(8) works by embedding a {{perl}}(1) interpreter
441 into {{slapd}}(8). Any perl database section of the configuration file
442 {{slapd.conf}}(5) must then specify what Perl module to use. Slapd then creates
443 a new Perl object that handles all the requests for that particular instance of the backend.
445 The Shell backend to {{slapd}}(8) executes external programs to implement
446 operations, and is designed to make it easy to tie an existing database to the
447 slapd front-end. This backend is is primarily intended to be used in prototypes.
449 H3: back-perl/back-shell Configuration
453 H3: Further Information
455 {{slapd-shell}}(5) and {{slapd-perl}}(5)
462 The primary purpose of this {{slapd}}(8) backend is to map a naming context
463 defined in a database running in the same {{slapd}}(8) instance into a
464 virtual naming context, with attributeType and objectClass manipulation, if
465 required. It requires the rwm overlay.
467 This backend and the above mentioned overlay are experimental.
469 H3: back-relay Configuration
473 H3: Further Information
482 The primary purpose of this {{slapd}}(8) backend is to PRESENT information
483 stored in some RDBMS as an LDAP subtree without any programming (some SQL and
484 maybe stored procedures can't be considered programming, anyway ;).
486 That is, for example, when you (some ISP) have account information you use in
487 an RDBMS, and want to use modern solutions that expect such information in LDAP
488 (to authenticate users, make email lookups etc.). Or you want to synchronize or
489 distribute information between different sites/applications that use RDBMSes
490 and/or LDAP. Or whatever else...
492 It is {{B:NOT}} designed as a general-purpose backend that uses RDBMS instead of
493 BerkeleyDB (as the standard BDB backend does), though it can be used as such with
494 several limitations. Please see {{SECT: LDAP vs RDBMS}} for discussion.
496 The idea is to use some meta-information to translate LDAP queries to SQL queries,
497 leaving relational schema untouched, so that old applications can continue using
498 it without any modifications. This allows SQL and LDAP applications to interoperate
499 without replication, and exchange data as needed.
501 The SQL backend is designed to be tunable to virtually any relational schema without
502 having to change source (through that meta-information mentioned). Also, it uses
503 ODBC to connect to RDBMSes, and is highly configurable for SQL dialects RDBMSes
504 may use, so it may be used for integration and distribution of data on different
505 RDBMSes, OSes, hosts etc., in other words, in highly heterogeneous environments.
507 This backend is experimental.
509 H3: back-sql Configuration
511 This backend has to be one of the most abused and complex backends there is.
512 Therefore, we will go through a simple, small example that comes with the
513 OpenLDAP source and can be found in {{F: servers/slapd/back-sql/rdbms_depend/README}}
515 For this example we will be using PostgreSQL.
517 First, we add to {{F: /etc/odbc.ini}} a block of the form:
520 > Description = Example for OpenLDAP's back-sql
521 > Driver = PostgreSQL
523 > Database = example <===
524 > Servername = localhost
525 > UserName = manager <===
526 > Password = secret <===
531 > ShowSystemTables = No
536 The relevant information for our test setup is highlighted with '<===' on the
539 Next, we add to {{F: /etc/odbcinst.ini}} a block of the form:
542 > Description = ODBC for PostgreSQL
543 > Driver = /usr/lib/libodbcpsql.so
544 > Setup = /usr/lib/libodbcpsqlS.so
548 We will presume you know how to create a database and user in PostgreSQL and
549 how to set a password. Also, we'll presume you can populate the 'example'
550 database you've just created with the following files, as found in {{F: servers/slapd/back-sql/rdbms_depend/pgsql }}
552 > backsql_create.sql, testdb_create.sql, testdb_data.sql, testdb_metadata.sql
554 Lastly, run the test:
556 > [root@localhost]# cd $SOURCES/tests
557 > [root@localhost]# SLAPD_USE_SQL=pgsql ./run sql-test000
559 Briefly, you should see something like (cut short for space):
561 > Cleaning up test run directory leftover from previous run.
562 > Running ./scripts/sql-test000-read...
564 > Starting slapd on TCP/IP port 9011...
565 > Testing SQL backend read operations...
566 > Waiting 5 seconds for slapd to start...
567 > Testing correct bind... dn:cn=Mitya Kovalev,dc=example,dc=com
568 > Testing incorrect bind (should fail)... ldap_bind: Invalid credentials (49)
572 > Filtering original ldif...
573 > Comparing filter output...
574 > >>>>> Test succeeded
576 The test is basically readonly; this can be performed by all RDBMSes
579 There is another test, sql-test900-write, which is currently enabled
580 only for PostgreSQL and IBM db2.
582 Using {{F: sql-test000}}, files in {{F: servers/slapd/back-sql/rdbms_depend/pgsql/}}
583 and the man page, you should be set.
585 Note: This backend is experimental.
587 H3: Further Information
589 {{slapd-sql}}(5) and {{F: servers/slapd/back-sql/rdbms_depend/README}}