Adding upstream version 2.4.57+dfsg.upstream/2.4.57+dfsgupstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 589 insertions, 0 deletions

diff --git a/doc/guide/admin/backends.sdf b/doc/guide/admin/backends.sdf
new file mode 100644
index 0000000..83c8866
--- /dev/null
+++ b/doc/guide/admin/backends.sdf
@@ -0,0 +1,589 @@
+# $OpenLDAP$
+# Copyright 2007-2021 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 {{hdb}} backend, you would configure
+
+>	moduleload back_hdb.la
+
+H2: Berkeley DB Backends
+
+
+H3: Overview
+
+The {{hdb}} backend to {{slapd}}(8) is a backend for a 
+normal {{slapd}} database.  It uses the Oracle Berkeley DB ({{TERM:BDB}}) 
+package to store data. It makes extensive use of indexing and caching 
+(see the {{SECT:Tuning}} section) to speed data access.
+
+{{hdb}} is a variant of the original {{bdb}} backend which was first written for use with BDB.
+{{hdb}} uses a hierarchical database layout which supports subtree renames.
+It is otherwise identical to the {{bdb}}
+behavior, and all the same configuration options apply.
+
+Note: An {{hdb}} database needs a large {{idlcachesize}} for good search performance, 
+typically three times the {{cachesize}} (entry cache size) or larger.
+
+Note: The {{hdb}} backend has superseded the {{bdb}} backend, and both will
+soon be deprecated in favor of the new {{mdb}} backend. See below.
+
+H3: back-bdb/back-hdb Configuration
+
+MORE LATER
+
+H3: Further Information
+
+{{slapd-bdb}}(5)
+
+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: MirrorMode 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 is intended to replace the Berkeley DB backends.
+
+It supports indexing like the BDB backends, but it uses no caching and requires
+no tuning to deliver maximum search performance.  Like {{hdb}}, it is also
+fully hierarchical and supports subtree renames in constant time.
+
+H3: back-mdb Configuration
+
+Unlike the BDB backends, 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/Shell
+
+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.
+
+The Shell backend to {{slapd}}(8) executes external programs to implement 
+operations, and is designed to make it easy to tie an existing database to the 
+slapd front-end. This backend is primarily intended to be used in prototypes.
+
+H3: back-perl/back-shell Configuration
+
+LATER
+
+H3: Further Information
+
+{{slapd-shell}}(5) and {{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 
+BerkeleyDB (as the standard BDB 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.
+
+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.
+
+H3: Further Information
+
+{{slapd-sql}}(5) and {{F: servers/slapd/back-sql/rdbms_depend/README}}