xref: /netbsd-src/external/bsd/openldap/dist/doc/guide/admin/backends.sdf (revision e670fd5c413e99c2f6a37901bb21c537fcd322d2)
1# $OpenLDAP$
2# Copyright 2007-2021 The OpenLDAP Foundation, All Rights Reserved.
3# COPYING RESTRICTIONS APPLY, see COPYRIGHT.
4
5H1: Backends
6
7Backends do the actual work of storing or retrieving data in response
8to LDAP requests. Backends may be compiled statically into {{slapd}},
9or when module support is enabled, they may be dynamically loaded.
10
11If your installation uses dynamic modules, you may need to add the
12relevant {{moduleload}} directives to the examples that follow. The
13name of the module for a backend is usually of the form:
14
15>	back_<backend name>.la
16
17So for example, if you need to load the {{mdb}} backend, you would configure
18
19>	moduleload back_mdb.la
20
21H2: LDAP
22
23
24H3: Overview
25
26The LDAP backend to {{slapd}}(8) is not an actual database; instead it acts
27as a proxy to forward incoming requests to another LDAP server. While
28processing requests it will also chase referrals, so that referrals are fully
29processed instead of being returned to the {{slapd}} client.
30
31Sessions that explicitly {{Bind}} to the {{back-ldap}} database always create
32their own private connection to the remote LDAP server. Anonymous sessions
33will share a single anonymous connection to the remote server. For sessions
34bound through other mechanisms, all sessions with the same DN will share the
35same connection. This connection pooling strategy can enhance the proxy's
36efficiency by reducing the overhead of repeatedly making/breaking multiple
37connections.
38
39The ldap database can also act as an information service, i.e. the identity
40of locally authenticated clients is asserted to the remote server, possibly
41in some modified form. For this purpose, the proxy binds to the remote server
42with some administrative identity, and, if required, authorizes the asserted
43identity.
44
45It is heavily used by a lot of other {{SECT: Backends}} and {{SECT: Overlays}}.
46
47H3: back-ldap Configuration
48
49As previously mentioned, {{slapd-ldap(5)}} is used behind the scenes by many
50other {{SECT: Backends}} and {{SECT: Overlays}}. Some of them merely provide a
51few configuration directive themselves, but have available to the administrator
52the whole of the {{slapd-ldap(5)}} options.
53
54For example, the {{SECT: Translucent Proxy}}, which retrieves entries from a
55remote LDAP server that can be partially overridden by the defined database, has
56only four specific {{translucent-}} directives, but can be configured using any
57of the normal {{slapd-ldap(5)}} options. See {[slapo-translucent(5)}} for details.
58
59Other {{SECT: Overlays}} allow you to tag directives in front of a normal
60{{slapd-ldap(5)}} directive. For example, the {{slapo-chain(5)}} overlay does
61this:
62
63{{"There are very few chain overlay specific directives; however, directives
64related to the instances of the ldap backend that may be implicitly instantiated
65by the overlay may assume a special meaning when used in conjunction with this
66overlay.  They are described in slapd-ldap(5), and they also need to be prefixed
67by chain-."}}
68
69You may have also seen the {{slapd-ldap(5)}} backend used and described in the
70{{SECT: Push Based}} {{SECT: Replication}} section of the guide.
71
72It should therefore be obvious that the {{slapd-ldap(5)}} backend is extremely
73flexible and heavily used throughout the OpenLDAP Suite.
74
75The following is a very simple example, but already the power of the {{slapd-ldap(5)}}
76backend is seen by use of a {{uri list}}:
77
78>	database        ldap
79>	suffix          "dc=suretecsystems,dc=com"
80>	rootdn          "cn=slapd-ldap"
81>	uri             ldap://localhost/ ldap://remotehost ldap://remotehost2
82
83The URI list is space or comma-separated. Whenever the server that responds
84is not the first one in the list, the list is rearranged and the responsive
85server is moved to the head, so that it will be first contacted the next time
86a connection needs be created.
87
88This feature can be used to provide a form of load balancing when using
89{{SECT: Mirror mode replication}}.
90
91H3: Further Information
92
93{{slapd-ldap}}(5)
94
95H2: LDIF
96
97
98H3: Overview
99
100The LDIF backend to {{slapd}}(8) is a basic storage backend that stores
101entries in text files in LDIF format, and exploits the filesystem to create
102the tree structure of the database. It is intended as a cheap, low performance
103easy to use backend.
104
105When using the {{cn=config}} dynamic configuration database with persistent
106storage, the configuration data is stored using this backend. See {{slapd-config}}(5)
107for more information
108
109H3: back-ldif Configuration
110
111Like many other backends, the LDIF backend can be instantiated with very few
112configuration lines:
113
114>	include ./schema/core.schema
115>
116>	database  ldif
117>	directory ./ldif
118>	suffix    "dc=suretecsystems,dc=com"
119>	rootdn    "cn=LDIF,dc=suretecsystems,dc=com"
120>	rootpw    LDIF
121
122If we add the {{dcObject}} for {{dc=suretecsystems,dc=com}}, you can see how this
123is added behind the scenes on the file system:
124
125>   dn: dc=suretecsystems,dc=com
126>   objectClass: dcObject
127>   objectClass: organization
128>   dc: suretecsystems
129>   o: Suretec Systems Ltd
130
131Now we add it to the directory:
132
133>   ldapadd -x -H ldap://localhost:9011 -f suretec.ldif -D "cn=LDIF,dc=suretecsystems,dc=com" -w LDIF
134>   adding new entry "dc=suretecsystems,dc=com"
135
136And inside {{F: ./ldif}} we have:
137
138>   ls ./ldif
139>   dc=suretecsystems,dc=com.ldif
140
141which again contains:
142
143>   cat ldif/dc\=suretecsystems\,dc\=com.ldif
144>
145>   dn: dc=suretecsystems
146>   objectClass: dcObject
147>   objectClass: organization
148>   dc: suretecsystems
149>   o: Suretec Systems Ltd.
150>   structuralObjectClass: organization
151>   entryUUID: 2134b714-e3a1-102c-9a15-f96ee263886d
152>   creatorsName: cn=LDIF,dc=suretecsystems,dc=com
153>   createTimestamp: 20080711142643Z
154>   entryCSN: 20080711142643.661124Z#000000#000#000000
155>   modifiersName: cn=LDIF,dc=suretecsystems,dc=com
156>   modifyTimestamp: 20080711142643Z
157
158This is the complete format you would get when exporting your directory using
159{{F: slapcat}} etc.
160
161H3: Further Information
162
163{{slapd-ldif}}(5)
164
165H2: LMDB
166
167
168H3: Overview
169
170The {{mdb}} backend to {{slapd}}(8) is the recommended primary backend for a
171normal {{slapd}} database.  It uses OpenLDAP's own
172Lightning Memory-Mapped Database ({{TERM:LMDB}})
173library to store data and replaces the BerkeleyDB backends used in older
174OpenLDAP releases.
175
176It supports indexing, it uses no caching, and requires no tuning to deliver
177maximum search performance.  It is fully hierarchical and supports subtree
178renames in constant time.
179
180H3: back-mdb Configuration
181
182The {{mdb}} backend can be instantiated with very few configuration lines:
183
184>	include ./schema/core.schema
185>
186>	database  mdb
187>	directory ./mdb
188>	suffix    "dc=suretecsystems,dc=com"
189>	rootdn    "cn=mdb,dc=suretecsystems,dc=com"
190>	rootpw    mdb
191>	maxsize   1073741824
192
193In addition to the usual parameters that a minimal configuration requires, the {{mdb}}
194backend requires a maximum size to be set. This should be the largest that
195the database is ever anticipated to grow (in bytes). The filesystem must also
196provide enough free space to accommodate this size.
197
198H3: Further Information
199
200{{slapd-mdb}}(5)
201
202H2: Metadirectory
203
204
205H3: Overview
206
207The meta backend to {{slapd}}(8) performs basic LDAP proxying with respect
208to a set of remote LDAP servers, called "targets". The information contained
209in these servers can be presented as belonging to a single Directory Information
210Tree ({{TERM:DIT}}).
211
212A basic knowledge of the functionality of the {{slapd-ldap}}(5) backend is
213recommended. This backend has been designed as an enhancement of the ldap
214backend. The two backends share many features (actually they also share portions
215 of code). While the ldap backend is intended to proxy operations directed
216 to a single server, the meta backend is mainly intended for proxying of
217 multiple servers and possibly naming context  masquerading.
218
219These features, although useful in many scenarios, may result in excessive
220overhead for some applications, so its use should be carefully considered.
221
222
223H3: back-meta Configuration
224
225LATER
226
227H3: Further Information
228
229{{slapd-meta}}(5)
230
231H2: Monitor
232
233
234H3: Overview
235
236The monitor backend to {{slapd}}(8) is not an actual database; if enabled,
237it is automatically generated and dynamically maintained by slapd with
238information about the running status of the daemon.
239
240To inspect all monitor information, issue a subtree search with base {{cn=Monitor}},
241requesting that attributes "+" and "*" are returned. The monitor backend produces
242mostly operational attributes, and LDAP only returns operational attributes
243that are explicitly requested.  Requesting attribute "+" is an extension which
244requests all operational attributes.
245
246See the {{SECT:Monitoring}} section.
247
248H3: back-monitor Configuration
249
250The monitor database can be instantiated only once, i.e. only one occurrence
251of "database monitor" can occur in the {{slapd.conf(5)}} file.  Also the suffix
252is automatically set to {{"cn=Monitor"}}.
253
254You can however set a {{rootdn}} and {{rootpw}}. The following is all that is
255needed to instantiate a monitor backend:
256
257>	include ./schema/core.schema
258>
259>	database monitor
260>	rootdn "cn=monitoring,cn=Monitor"
261>	rootpw monitoring
262
263You can also apply Access Control to this database like any other database, for
264example:
265
266>	access to dn.subtree="cn=Monitor"
267>	     by dn.exact="uid=Admin,dc=my,dc=org" write
268>	     by users read
269>	     by * none
270
271Note: The {{F: core.schema}} must be loaded for the monitor database to work.
272
273A small example of the data returned via {{ldapsearch}} would be:
274
275>	ldapsearch -x -H ldap://localhost:9011 -b 'cn=Monitor'
276>	# extended LDIF
277>	#
278>	# LDAPv3
279>	# base <cn=Monitor> with scope subtree
280>	# filter: (objectclass=*)
281>	# requesting: ALL
282>	#
283>
284>	# Monitor
285>	dn: cn=Monitor
286>	objectClass: monitorServer
287>	cn: Monitor
288>	description: This subtree contains monitoring/managing objects.
289>	description: This object contains information about this server.
290>	description: Most of the information is held in operational attributes, which
291>	 must be explicitly requested.
292>
293>	# Backends, Monitor
294>	dn: cn=Backends,cn=Monitor
295>	objectClass: monitorContainer
296>	cn: Backends
297>	description: This subsystem contains information about available backends.
298
299Please see the {{SECT: Monitoring}} section for complete examples of information
300available via this backend.
301
302H3: Further Information
303
304{{slapd-monitor}}(5)
305
306H2: Null
307
308
309H3: Overview
310
311The Null backend to {{slapd}}(8) is surely the most useful part of slapd:
312
313* Searches return success but no entries.
314* Compares return compareFalse.
315* Updates return success (unless readonly is on) but do nothing.
316* Binds other than as the rootdn fail unless the database option "bind on" is given.
317* The slapadd(8) and slapcat(8) tools are equally exciting.
318
319Inspired by the {{F:/dev/null}} device.
320
321H3: back-null Configuration
322
323This has to be one of the shortest configurations you'll ever do. In order to
324test this, your {{F: slapd.conf}} file would look like:
325
326>	database null
327>	suffix "cn=Nothing"
328>	bind on
329
330{{bind on}} means:
331
332{{"Allow binds as any DN in this backend's suffix, with any password. The default is "off"."}}
333
334To test this backend with {{ldapsearch}}:
335
336>	ldapsearch -x -H ldap://localhost:9011 -D "uid=none,cn=Nothing" -w testing -b 'cn=Nothing'
337>	# extended LDIF
338>	#
339>	# LDAPv3
340>	# base <cn=Nothing> with scope subtree
341>	# filter: (objectclass=*)
342>	# requesting: ALL
343>	#
344>
345>	# search result
346>	search: 2
347>	result: 0 Success
348>
349>	# numResponses: 1
350
351
352H3: Further Information
353
354{{slapd-null}}(5)
355
356H2: Passwd
357
358
359H3: Overview
360
361The PASSWD backend to {{slapd}}(8) serves up the user account information
362listed in the system {{passwd}}(5) file (defaulting to {{F: /etc/passwd}}).
363
364This backend is provided for demonstration purposes only. The DN of each entry
365is "uid=<username>,<suffix>".
366
367H3: back-passwd Configuration
368
369The configuration using {{F: slapd.conf}} a slightly longer, but not much. For
370example:
371
372>	include ./schema/core.schema
373>
374>	database passwd
375>	suffix "cn=passwd"
376
377Again, testing this with {{ldapsearch}} would result in something like:
378
379>	ldapsearch -x -H ldap://localhost:9011 -b 'cn=passwd'
380>	# extended LDIF
381>	#
382>	# LDAPv3
383>	# base <cn=passwd> with scope subtree
384>	# filter: (objectclass=*)
385>	# requesting: ALL
386>	#
387>
388>	# passwd
389>	dn: cn=passwd
390>	cn: passwd
391>	objectClass: organizationalUnit
392>
393>	# root, passwd
394>	dn: uid=root,cn=passwd
395>	objectClass: person
396>	objectClass: uidObject
397>	uid: root
398>	cn: root
399>	sn: root
400>	description: root
401
402
403H3: Further Information
404
405{{slapd-passwd}}(5)
406
407H2: Perl
408
409H3: Overview
410
411The Perl backend to {{slapd}}(8) works by embedding a {{perl}}(1) interpreter
412into {{slapd}}(8). Any perl database section of the configuration file
413{{slapd.conf}}(5) must then specify what Perl module to use. Slapd then creates
414a new Perl object that handles all the requests for that particular instance of the backend.
415
416H3: back-perl Configuration
417
418LATER
419
420H3: Further Information
421
422{{slapd-perl}}(5)
423
424H2: Relay
425
426
427H3: Overview
428
429The primary purpose of this {{slapd}}(8) backend is to map a naming context
430defined in a database running in the same {{slapd}}(8) instance into a
431virtual naming context, with attributeType and objectClass manipulation, if
432required. It requires the rwm overlay.
433
434This backend and the above mentioned overlay are experimental.
435
436H3: back-relay Configuration
437
438LATER
439
440H3: Further Information
441
442{{slapd-relay}}(5)
443
444H2: SQL
445
446
447H3: Overview
448
449The primary purpose of this {{slapd}}(8) backend is to PRESENT information
450stored in some RDBMS as an LDAP subtree without any programming (some SQL and
451maybe stored procedures can't be considered programming, anyway ;).
452
453That is, for example, when you (some ISP) have account information you use in
454an RDBMS, and want to use modern solutions that expect such information in LDAP
455(to authenticate users, make email lookups etc.). Or you want to synchronize or
456distribute information between different sites/applications that use RDBMSes
457and/or LDAP. Or whatever else...
458
459It is {{B:NOT}} designed as a general-purpose backend that uses RDBMS instead of
460LMDB (as the standard back-mdb backend does), though it can be used as such with
461several limitations. Please see {{SECT: LDAP vs RDBMS}} for discussion.
462
463The idea is to use some meta-information to translate LDAP queries to SQL queries,
464leaving relational schema untouched, so that old applications can continue using
465it without any modifications. This allows SQL and LDAP applications to interoperate
466without replication, and exchange data as needed.
467
468The SQL backend is designed to be tunable to virtually any relational schema without
469having to change source (through that meta-information mentioned). Also, it uses
470ODBC to connect to RDBMSes, and is highly configurable for SQL dialects RDBMSes
471may use, so it may be used for integration and distribution of data on different
472RDBMSes, OSes, hosts etc., in other words, in highly heterogeneous environments.
473
474This backend is experimental and deprecated.
475
476H3: back-sql Configuration
477
478This backend has to be one of the most abused and complex backends there is.
479Therefore, we will go through a simple, small example that comes with the
480OpenLDAP source and can be found in {{F: servers/slapd/back-sql/rdbms_depend/README}}
481
482For this example we will be using PostgreSQL.
483
484First, we add to {{F: /etc/odbc.ini}} a block of the form:
485
486>	[example]                        <===
487>	Description         = Example for OpenLDAP's back-sql
488>	Driver              = PostgreSQL
489>	Trace               = No
490>	Database            = example    <===
491>	Servername          = localhost
492>	UserName            = manager    <===
493>	Password            = secret     <===
494>	Port                = 5432
495>	;Protocol            = 6.4
496>	ReadOnly            = No
497>	RowVersioning       = No
498>	ShowSystemTables    = No
499>	ShowOidColumn       = No
500>	FakeOidIndex        = No
501>	ConnSettings        =
502
503The relevant information for our test setup is highlighted with '<===' on the
504right above.
505
506Next, we add to {{F: /etc/odbcinst.ini}} a block of the form:
507
508>	[PostgreSQL]
509>	Description     = ODBC for PostgreSQL
510>	Driver          = /usr/lib/libodbcpsql.so
511>	Setup           = /usr/lib/libodbcpsqlS.so
512>	FileUsage       = 1
513
514
515We will presume you know how to create a database and user in PostgreSQL and
516how to set a password. Also, we'll presume you can populate the 'example'
517database you've just created with the following files, as found in {{F: servers/slapd/back-sql/rdbms_depend/pgsql }}
518
519>	backsql_create.sql, testdb_create.sql, testdb_data.sql, testdb_metadata.sql
520
521Lastly, run the test:
522
523>	[root@localhost]# cd $SOURCES/tests
524>	[root@localhost]# SLAPD_USE_SQL=pgsql ./run sql-test000
525
526Briefly, you should see something like (cut short for space):
527
528>	Cleaning up test run directory leftover from previous run.
529>	Running ./scripts/sql-test000-read...
530>	running defines.sh
531>	Starting slapd on TCP/IP port 9011...
532>	Testing SQL backend read operations...
533>	Waiting 5 seconds for slapd to start...
534>	Testing correct bind... dn:cn=Mitya Kovalev,dc=example,dc=com
535>	Testing incorrect bind (should fail)... ldap_bind: Invalid credentials (49)
536>
537>	......
538>
539>	Filtering original ldif...
540>	Comparing filter output...
541>	>>>>> Test succeeded
542
543The test is basically readonly; this can be performed by all RDBMSes
544(listed above).
545
546There is another test, sql-test900-write, which is currently enabled
547only for PostgreSQL and IBM db2.
548
549Using {{F: sql-test000}}, files in {{F: servers/slapd/back-sql/rdbms_depend/pgsql/}}
550and the man page, you should be set.
551
552Note: This backend is experimental and deprecated.
553
554H3: Further Information
555
556{{slapd-sql}}(5) and {{F: servers/slapd/back-sql/rdbms_depend/README}}
557