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