]> git.sur5r.net Git - openldap/blob - doc/guide/admin/backends.sdf
Merge remote-tracking branch 'origin/mdb.master'
[openldap] / doc / guide / admin / backends.sdf
1 # $OpenLDAP$
2 # Copyright 2007-2012 The OpenLDAP Foundation, All Rights Reserved.
3 # COPYING RESTRICTIONS APPLY, see COPYRIGHT.
4
5 H1: Backends
6
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.
10
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:
14
15 >       back_<backend name>.la
16
17 So for example, if you need to load the {{hdb}} backend, you would configure
18
19 >       moduleload back_hdb.la
20
21 H2: Berkeley DB Backends
22
23
24 H3: Overview
25
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.
30
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.
34
35 Note: An {{hdb}} database needs a large {{idlcachesize}} for good search performance, 
36 typically three times the {{cachesize}} (entry cache size) or larger.
37
38 H3: back-bdb/back-hdb Configuration
39
40 MORE LATER
41
42 H3: Further Information
43
44 {{slapd-bdb}}(5)
45
46 H2: LDAP
47
48
49 H3: Overview
50
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.
55
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 
62 connections.
63
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 
68 identity. 
69
70 It is heavily used by a lot of other {{SECT: Backends}} and {{SECT: Overlays}}.
71
72 H3: back-ldap Configuration
73
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. 
78
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.
83
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 
86 this:
87
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 
92 by chain-."}}
93
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.
96
97 It should therefore be obvious that the {{slapd-ldap(5)}} backend is extremely
98 flexible and heavily used throughout the OpenLDAP Suite.
99
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}}:
102
103 >       database        ldap
104 >       suffix          "dc=suretecsystems,dc=com"
105 >       rootdn          "cn=slapd-ldap"
106 >       uri             ldap://localhost/ ldap://remotehost ldap://remotehost2
107
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.
112
113 This feature can be used to provide a form of load balancing when using 
114 {{SECT: MirrorMode replication}}.
115
116 H3: Further Information
117
118 {{slapd-ldap}}(5)
119
120 H2: LDIF
121
122
123 H3: Overview
124
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 
128 easy to use backend.
129
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)
132 for more information
133
134 H3: back-ldif Configuration
135
136 Like many other backends, the LDIF backend can be instantiated with very few
137 configuration lines:
138
139 >       include ./schema/core.schema
140 >       
141 >       database  ldif
142 >       directory "./ldif"
143 >       suffix    "dc=suretecsystems,dc=com"
144 >       rootdn    "cn=LDIF,dc=suretecsystems,dc=com"
145 >       rootpw    LDIF
146
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:
149
150 >   dn: dc=suretecsystems,dc=com
151 >   objectClass: dcObject
152 >   objectClass: organization
153 >   dc: suretecsystems
154 >   o: Suretec Systems Ltd
155
156 Now we add it to the directory:
157
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"
160
161 And inside {{F: ./ldif}} we have:
162
163 >   ls ./ldif
164 >   dc=suretecsystems,dc=com.ldif
165
166 which again contains:
167
168 >   cat ldif/dc\=suretecsystems\,dc\=com.ldif 
169 >   
170 >   dn: dc=suretecsystems
171 >   objectClass: dcObject
172 >   objectClass: organization
173 >   dc: suretecsystems
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
182
183 This is the complete format you would get when exporting your directory using
184 {{F: slapcat}} etc.
185
186 H3: Further Information
187
188 {{slapd-ldif}}(5)
189
190 H2: Metadirectory
191
192
193 H3: Overview
194
195 The meta backend to {{slapd}}(8) performs basic LDAP proxying with respect 
196 to a set of remote LDAP servers, called "targets". The information contained 
197 in these servers can be presented as belonging to a single Directory Information 
198 Tree ({{TERM:DIT}}).
199
200 A basic knowledge of the functionality of the {{slapd-ldap}}(5) backend is 
201 recommended. This backend has been designed as an enhancement of the ldap 
202 backend. The two backends share many features (actually they also share portions
203  of code). While the ldap backend is intended to proxy operations directed 
204  to a single server, the meta backend is mainly intended for proxying of 
205  multiple servers and possibly naming context  masquerading.
206
207 These features, although useful in many scenarios, may result in excessive 
208 overhead for some applications, so its use should be carefully considered.
209
210
211 H3: back-meta Configuration
212
213 LATER
214
215 H3: Further Information
216
217 {{slapd-meta}}(5)
218
219 H2: Monitor
220
221
222 H3: Overview
223
224 The monitor backend to {{slapd}}(8) is not an actual database; if enabled, 
225 it is automatically generated and dynamically maintained by slapd with 
226 information about the running status of the daemon.
227
228 To inspect all monitor information, issue a subtree search with base {{cn=Monitor}}, 
229 requesting that attributes "+" and "*" are returned. The monitor backend produces 
230 mostly operational attributes, and LDAP only returns operational attributes 
231 that are explicitly requested.  Requesting attribute "+" is an extension which 
232 requests all operational attributes.
233
234 See the {{SECT:Monitoring}} section.
235
236 H3: back-monitor Configuration
237
238 The monitor database can be instantiated only once, i.e. only one occurrence 
239 of "database monitor" can occur in the {{slapd.conf(5)}} file.  Also the suffix 
240 is automatically set to {{"cn=Monitor"}}.
241
242 You can however set a {{rootdn}} and {{rootpw}}. The following is all that is
243 needed to instantiate a monitor backend:
244
245 >       include ./schema/core.schema
246 >       
247 >       database monitor
248 >       rootdn "cn=monitoring,cn=Monitor"
249 >       rootpw monitoring
250
251 You can also apply Access Control to this database like any other database, for 
252 example:
253
254 >       access to dn.subtree="cn=Monitor"
255 >            by dn.exact="uid=Admin,dc=my,dc=org" write
256 >            by users read
257 >            by * none
258
259 Note: The {{F: core.schema}} must be loaded for the monitor database to work. 
260
261 A small example of the data returned via {{ldapsearch}} would be:
262
263 >       ldapsearch -x -H ldap://localhost:9011 -b 'cn=Monitor'
264 >       # extended LDIF
265 >       #
266 >       # LDAPv3
267 >       # base <cn=Monitor> with scope subtree
268 >       # filter: (objectclass=*)
269 >       # requesting: ALL
270 >       #
271 >       
272 >       # Monitor
273 >       dn: cn=Monitor
274 >       objectClass: monitorServer
275 >       cn: Monitor
276 >       description: This subtree contains monitoring/managing objects.
277 >       description: This object contains information about this server.
278 >       description: Most of the information is held in operational attributes, which 
279 >        must be explicitly requested.
280 >       
281 >       # Backends, Monitor
282 >       dn: cn=Backends,cn=Monitor
283 >       objectClass: monitorContainer
284 >       cn: Backends
285 >       description: This subsystem contains information about available backends.
286
287 Please see the {{SECT: Monitoring}} section for complete examples of information
288 available via this backend.
289
290 H3: Further Information
291
292 {{slapd-monitor}}(5)
293
294 H2: Null
295
296
297 H3: Overview
298
299 The Null backend to {{slapd}}(8) is surely the most useful part of slapd:
300
301 * Searches return success but no entries.
302 * Compares return compareFalse.
303 * Updates return success (unless readonly is on) but do nothing.
304 * Binds other than as the rootdn fail unless the database option "bind on" is given.
305 * The slapadd(8) and slapcat(8) tools are equally exciting.
306
307 Inspired by the {{F:/dev/null}} device.
308
309 H3: back-null Configuration
310
311 This has to be one of the shortest configurations you'll ever do. In order to 
312 test this, your {{F: slapd.conf}} file would look like:
313
314 >       database null
315 >       suffix "cn=Nothing"
316 >       bind on
317
318 {{bind on}} means:
319
320 {{"Allow binds as any DN in this backend's suffix, with any password. The default is "off"."}}
321
322 To test this backend with {{ldapsearch}}:
323
324 >       ldapsearch -x -H ldap://localhost:9011 -D "uid=none,cn=Nothing" -w testing -b 'cn=Nothing'
325 >       # extended LDIF
326 >       #
327 >       # LDAPv3
328 >       # base <cn=Nothing> with scope subtree
329 >       # filter: (objectclass=*)
330 >       # requesting: ALL
331 >       #
332 >       
333 >       # search result
334 >       search: 2
335 >       result: 0 Success
336 >       
337 >       # numResponses: 1
338
339
340 H3: Further Information
341
342 {{slapd-null}}(5)
343
344 H2: Passwd
345
346
347 H3: Overview
348
349 The PASSWD backend to {{slapd}}(8) serves up the user account information 
350 listed in the system {{passwd}}(5) file (defaulting to {{F: /etc/passwd}}).
351
352 This backend is provided for demonstration purposes only. The DN of each entry 
353 is "uid=<username>,<suffix>".
354
355 H3: back-passwd Configuration
356
357 The configuration using {{F: slapd.conf}} a slightly longer, but not much. For 
358 example:
359
360 >       include ./schema/core.schema
361 >       
362 >       database passwd
363 >       suffix "cn=passwd"
364
365 Again, testing this with {{ldapsearch}} would result in something like:
366
367 >       ldapsearch -x -H ldap://localhost:9011 -b 'cn=passwd'
368 >       # extended LDIF
369 >       #
370 >       # LDAPv3
371 >       # base <cn=passwd> with scope subtree
372 >       # filter: (objectclass=*)
373 >       # requesting: ALL
374 >       #
375 >       
376 >       # passwd
377 >       dn: cn=passwd
378 >       cn: passwd
379 >       objectClass: organizationalUnit
380 >       
381 >       # root, passwd
382 >       dn: uid=root,cn=passwd
383 >       objectClass: person
384 >       objectClass: uidObject
385 >       uid: root
386 >       cn: root
387 >       sn: root
388 >       description: root
389
390
391 H3: Further Information
392
393 {{slapd-passwd}}(5)
394
395 H2: Perl/Shell
396
397 H3: Overview
398
399 The Perl backend to {{slapd}}(8) works by embedding a {{perl}}(1) interpreter 
400 into {{slapd}}(8). Any perl database section of the configuration file 
401 {{slapd.conf}}(5) must then specify what Perl module to use. Slapd then creates 
402 a new Perl object that handles all the requests for that particular instance of the backend.
403
404 The Shell backend to {{slapd}}(8) executes external programs to implement 
405 operations, and is designed to make it easy to tie an existing database to the 
406 slapd front-end. This backend is is primarily intended to be used in prototypes.
407
408 H3: back-perl/back-shell Configuration
409
410 LATER
411
412 H3: Further Information
413
414 {{slapd-shell}}(5) and {{slapd-perl}}(5)
415
416 H2: Relay
417
418
419 H3: Overview
420
421 The primary purpose of this {{slapd}}(8) backend is to map a naming context 
422 defined in a database running in the same {{slapd}}(8) instance into a 
423 virtual naming context, with attributeType and objectClass manipulation, if
424 required. It requires the rwm overlay.
425
426 This backend and the above mentioned overlay are experimental.
427
428 H3: back-relay Configuration
429
430 LATER
431
432 H3: Further Information
433
434 {{slapd-relay}}(5)
435
436 H2: SQL
437
438
439 H3: Overview
440
441 The primary purpose of this {{slapd}}(8) backend is to PRESENT information 
442 stored in some RDBMS as an LDAP subtree without any programming (some SQL and 
443 maybe stored procedures can't be considered programming, anyway ;).
444
445 That is, for example, when you (some ISP) have account information you use in 
446 an RDBMS, and want to use modern solutions that expect such information in LDAP 
447 (to authenticate users, make email lookups etc.). Or you want to synchronize or 
448 distribute information between different sites/applications that use RDBMSes 
449 and/or LDAP. Or whatever else...
450
451 It is {{B:NOT}} designed as a general-purpose backend that uses RDBMS instead of 
452 BerkeleyDB (as the standard BDB backend does), though it can be used as such with 
453 several limitations. Please see {{SECT: LDAP vs RDBMS}} for discussion.
454
455 The idea is to use some meta-information to translate LDAP queries to SQL queries, 
456 leaving relational schema untouched, so that old applications can continue using 
457 it without any modifications. This allows SQL and LDAP applications to interoperate 
458 without replication, and exchange data as needed.
459
460 The SQL backend is designed to be tunable to virtually any relational schema without 
461 having to change source (through that meta-information mentioned). Also, it uses 
462 ODBC to connect to RDBMSes, and is highly configurable for SQL dialects RDBMSes 
463 may use, so it may be used for integration and distribution of data on different 
464 RDBMSes, OSes, hosts etc., in other words, in highly heterogeneous environments.
465
466 This backend is experimental.
467
468 H3: back-sql Configuration
469
470 This backend has to be one of the most abused and complex backends there is. 
471 Therefore, we will go through a simple, small example that comes with the 
472 OpenLDAP source and can be found in {{F: servers/slapd/back-sql/rdbms_depend/README}}
473
474 For this example we will be using PostgreSQL.
475
476 First, we add to {{F: /etc/odbc.ini}} a block of the form:
477
478 >       [example]                        <===
479 >       Description         = Example for OpenLDAP's back-sql
480 >       Driver              = PostgreSQL
481 >       Trace               = No
482 >       Database            = example    <===
483 >       Servername          = localhost
484 >       UserName            = manager    <===
485 >       Password            = secret     <===
486 >       Port                = 5432
487 >       ;Protocol            = 6.4
488 >       ReadOnly            = No
489 >       RowVersioning       = No
490 >       ShowSystemTables    = No
491 >       ShowOidColumn       = No
492 >       FakeOidIndex        = No
493 >       ConnSettings        =
494
495 The relevant information for our test setup is highlighted with '<===' on the 
496 right above.
497
498 Next, we add to {{F: /etc/odbcinst.ini}} a block of the form:
499
500 >       [PostgreSQL]
501 >       Description     = ODBC for PostgreSQL
502 >       Driver          = /usr/lib/libodbcpsql.so
503 >       Setup           = /usr/lib/libodbcpsqlS.so
504 >       FileUsage       = 1
505
506
507 We will presume you know how to create a database and user in PostgreSQL and 
508 how to set a password. Also, we'll presume you can populate the 'example'
509 database you've just created with the following files, as found in {{F: servers/slapd/back-sql/rdbms_depend/pgsql }} 
510
511 >       backsql_create.sql, testdb_create.sql, testdb_data.sql, testdb_metadata.sql
512
513 Lastly, run the test:
514
515 >       [root@localhost]# cd $SOURCES/tests
516 >       [root@localhost]# SLAPD_USE_SQL=pgsql ./run sql-test000
517
518 Briefly, you should see something like (cut short for space):
519
520 >       Cleaning up test run directory leftover from previous run.
521 >       Running ./scripts/sql-test000-read...
522 >       running defines.sh
523 >       Starting slapd on TCP/IP port 9011...
524 >       Testing SQL backend read operations...
525 >       Waiting 5 seconds for slapd to start...
526 >       Testing correct bind... dn:cn=Mitya Kovalev,dc=example,dc=com
527 >       Testing incorrect bind (should fail)... ldap_bind: Invalid credentials (49)
528 >       
529 >       ......
530 >       
531 >       Filtering original ldif...
532 >       Comparing filter output...
533 >       >>>>> Test succeeded
534
535 The test is basically readonly; this can be performed by all RDBMSes 
536 (listed above). 
537
538 There is another test, sql-test900-write, which is currently enabled
539 only for PostgreSQL and IBM db2.
540
541 Using {{F: sql-test000}}, files in {{F: servers/slapd/back-sql/rdbms_depend/pgsql/}}
542 and the man page, you should be set.
543
544 Note: This backend is experimental.
545
546 H3: Further Information
547
548 {{slapd-sql}}(5) and {{F: servers/slapd/back-sql/rdbms_depend/README}}