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