summaryrefslogtreecommitdiffstats
path: root/doc/guide/admin/backends.sdf
blob: 37b4d3eede8e8669cda3d139c63d1248d26adbf4 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
# $OpenLDAP$
# Copyright 2007-2022 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.

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 {{mdb}} backend, you would configure

>	moduleload back_mdb.la

H2: LDAP


H3: Overview

The LDAP backend to {{slapd}}(8) is not an actual database; instead it acts 
as a proxy to forward incoming requests to another LDAP server. While 
processing requests it will also chase referrals, so that referrals are fully
processed instead of being returned to the {{slapd}} client.

Sessions that explicitly {{Bind}} to the {{back-ldap}} database always create 
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 
efficiency by reducing the overhead of repeatedly making/breaking multiple 
connections.

The ldap database can also act as an information service, i.e. the identity 
of locally authenticated clients is asserted to the remote server, possibly 
in some modified form. For this purpose, the proxy binds to the remote server 
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

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: Mirror mode replication}}.

H3: Further Information

{{slapd-ldap}}(5)

H2: LDIF


H3: Overview

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.

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

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: LMDB


H3: Overview

The {{mdb}} backend to {{slapd}}(8) is the recommended primary backend for a
normal {{slapd}} database.  It uses OpenLDAP's own
Lightning Memory-Mapped Database ({{TERM:LMDB}})
library to store data and replaces the BerkeleyDB backends used in older
OpenLDAP releases.

It supports indexing, it uses no caching, and requires no tuning to deliver
maximum search performance.  It is fully hierarchical and supports subtree
renames in constant time.

H3: back-mdb Configuration

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: Overview

The meta backend to {{slapd}}(8) performs basic LDAP proxying with respect 
to a set of remote LDAP servers, called "targets". The information contained 
in these servers can be presented as belonging to a single Directory Information 
Tree ({{TERM:DIT}}).

A basic knowledge of the functionality of the {{slapd-ldap}}(5) backend is 
recommended. This backend has been designed as an enhancement of the ldap 
backend. The two backends share many features (actually they also share portions
 of code). While the ldap backend is intended to proxy operations directed 
 to a single server, the meta backend is mainly intended for proxying of 
 multiple servers and possibly naming context  masquerading.

These features, although useful in many scenarios, may result in excessive 
overhead for some applications, so its use should be carefully considered.


H3: back-meta Configuration

LATER

H3: Further Information

{{slapd-meta}}(5)

H2: Monitor


H3: Overview

The monitor backend to {{slapd}}(8) is not an actual database; if enabled, 
it is automatically generated and dynamically maintained by slapd with 
information about the running status of the daemon.

To inspect all monitor information, issue a subtree search with base {{cn=Monitor}}, 
requesting that attributes "+" and "*" are returned. The monitor backend produces 
mostly operational attributes, and LDAP only returns operational attributes 
that are explicitly requested.  Requesting attribute "+" is an extension which 
requests all operational attributes.

See the {{SECT:Monitoring}} section.

H3: back-monitor Configuration

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

{{slapd-monitor}}(5)

H2: Null


H3: Overview

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.

Inspired by the {{F:/dev/null}} device.

H3: back-null Configuration

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

{{slapd-null}}(5)

H2: Passwd


H3: Overview

The PASSWD backend to {{slapd}}(8) serves up the user account information 
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

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

{{slapd-passwd}}(5)

H2: Perl

H3: Overview

The Perl backend to {{slapd}}(8) works by embedding a {{perl}}(1) interpreter 
into {{slapd}}(8). Any perl database section of the configuration file 
{{slapd.conf}}(5) must then specify what Perl module to use. Slapd then creates 
a new Perl object that handles all the requests for that particular instance of the backend.

H3: back-perl Configuration

LATER

H3: Further Information

{{slapd-perl}}(5)

H2: Relay


H3: Overview

The primary purpose of this {{slapd}}(8) backend is to map a naming context 
defined in a database running in the same {{slapd}}(8) instance into a 
virtual naming context, with attributeType and objectClass manipulation, if
required. It requires the rwm overlay.

This backend and the above mentioned overlay are experimental.

H3: back-relay Configuration

LATER

H3: Further Information

{{slapd-relay}}(5)

H2: SQL


H3: Overview

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 ;).

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 
(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...

It is {{B:NOT}} designed as a general-purpose backend that uses RDBMS instead of 
LMDB (as the standard back-mdb backend does), though it can be used as such with
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 
it without any modifications. This allows SQL and LDAP applications to interoperate 
without replication, and exchange data as needed.

The SQL backend is designed to be tunable to virtually any relational schema without 
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 environments.

This backend is experimental and deprecated.

H3: back-sql Configuration

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 and deprecated.

H3: Further Information

{{slapd-sql}}(5) and {{F: servers/slapd/back-sql/rdbms_depend/README}}