From 045a8fb8be0843bb6b6cd637380b5006ef59bcce Mon Sep 17 00:00:00 2001 From: Kurt Zeilenga Date: Fri, 14 Jun 2002 21:19:42 +0000 Subject: [PATCH] LDBM->BDB updates --- doc/guide/admin/dbtools.sdf | 6 +- doc/guide/admin/install.sdf | 27 ++++---- doc/guide/admin/intro.sdf | 33 +++++----- doc/guide/admin/quickstart.sdf | 17 +++-- doc/guide/admin/sasl.sdf | 2 +- doc/guide/admin/schema.sdf | 6 +- doc/guide/admin/slapdconfig.sdf | 109 +++++++++++++++++++------------- doc/guide/admin/tls.sdf | 4 +- doc/guide/admin/tuning.sdf | 2 + doc/guide/preamble.sdf | 3 +- 10 files changed, 118 insertions(+), 91 deletions(-) diff --git a/doc/guide/admin/dbtools.sdf b/doc/guide/admin/dbtools.sdf index 8776d57dd5..5e30e75ac2 100644 --- a/doc/guide/admin/dbtools.sdf +++ b/doc/guide/admin/dbtools.sdf @@ -44,7 +44,7 @@ should be created: For example: -> directory /usr/local/var/openldap-ldbm +> directory /usr/local/var/openldap-data You need to create this directory with appropriate permissions such that slapd can write to it. @@ -141,7 +141,7 @@ should be created: For example: -> directory /usr/local/var/openldap-ldbm +> directory /usr/local/var/openldap-data Finally, you need to specify which indexes you want to build. This is done by one or more index options. @@ -190,7 +190,7 @@ Options}} section in {{SECT:Running slapd}}. An optional argument that specifies which database to modify. The first database listed in the configuration file is {{EX:1}}, the -second {{EX:2}}, etc. By default, the first ldbm database in the +second {{EX:2}}, etc. By default, the first database in the configuration file is used. Should not be used in conjunction with {{EX:-b}}. diff --git a/doc/guide/admin/install.sdf b/doc/guide/admin/install.sdf index 515b94e627..a38727bb7d 100644 --- a/doc/guide/admin/install.sdf +++ b/doc/guide/admin/install.sdf @@ -111,26 +111,25 @@ configure detects a usable Cyrus SASL installation. H3: Database Software -OpenLDAP's {{slapd}}(8) primary database backend, {{TERM:LDBM}}, -requires a compatible database package for entry storage. LDBM -is compatible with {{ORG[expand]Sleepycat}}'s {{PRD:BerkeleyDB}} (recommended) -or the {{ORG[expand]FSF}}'s {{PRD:GNU}} Database Manager ({{PRD:GDBM}}). -If neither of these packages are available at configure time, -you will not be able build {{slapd}}(8) with a primary database backend. - -Your operating system may provide one or both of these packages in -the base system or as an optional software component. If not, -you'll have to obtain and install one of these packages yourself. - -{{PRD:BerkeleyDB}} is available from {{ORG[expand]Sleepycat}}'s +OpenLDAP's {{slapd}}(8) primary database backend, {{TERM:BDB}}, +requires {{ORG[expand]Sleepycat}} {{PRD:Berkeley DB}}, version 4. +If not available at configure time, you will not be able build +{{slapd}}(8) with primary database backend. + +Your operating system may provide {{PRD:Berkeley DB}}, version 4, +in the base system or as an optional software component. If not, +you'll have to obtain and install it yourself. + +{{PRD:Berkeley DB}} is available from {{ORG[expand]Sleepycat}}'s download page {{URL: http://www.sleepycat.com/download.html}}. There are several versions available. At the time of this writing, the latest release, version 4.0, is recommended. This package is required if you wish to use the {{TERM:BDB}} database backend. -{{PRD:GDBM}} is available from {{ORG:FSF}}'s download site +OpenLDAP's {{slapd}}(8) LDBM backend supports a variety of data +base managers {{PRD:Berkeley DB}} and {{PRD:GDBM}}. {{PRD:GDBM}} +is available from {{ORG:FSF}}'s download site {{URL: ftp://ftp.gnu.org/pub/gnu/gdbm/}}. -At the time of this writing, version 1.8 is the latest release. H3: Threads diff --git a/doc/guide/admin/intro.sdf b/doc/guide/admin/intro.sdf index d5e9589da8..74a02f0d92 100644 --- a/doc/guide/admin/intro.sdf +++ b/doc/guide/admin/intro.sdf @@ -240,20 +240,20 @@ and other criteria. {{slapd}} supports both {{static}} and {{B:Internationalization}}: {{slapd}} supports Unicode and language tags. -{{B:Choice of databases}}: {{slapd}} comes with a variety of -different backend databases you can choose from. They include -{{TERM:LDBM}}, a high-performance disk-based embedded database; -SHELL, a database interface to arbitrary shell scripts; and PASSWD, -a simple password file database. LDBM utilizes either {{PRD:BerkeleyDB}} -or {{PRD:GDBM}}. There is also a new {{TERM:BDB}} backend database -which uses BerkeleyDB directly, instead of the generic API that -LDBM uses, and delivers even greater performance. +{{B:Choice of databases backends}}: {{slapd}} comes with a variety +of different database backends you can choose from. They include +{{TERM:BDB}}, a high-performance transactional database backend; +{{TERM:LDBM}}, a lightweight DBM based backend; {{SHELL}}, a backend +interface to arbitrary shell scripts; and PASSWD, a simple backend +interface to the {{passwd}}(5) file. BDB utilizes {{ORG:Sleepycat}} +{{PRD:Berkeley DB}}. LDBM utilizes either {{PRD:Berkeley DB}} or +{{PRD:GDBM}}. {{B:Multiple database instances}}: {{slapd}} can be configured to serve multiple databases at the same time. This means that a single {{slapd}} server can respond to requests for many logically different -portions of the LDAP tree, using the same or different backend -databases. +portions of the LDAP tree, using the same or different database +backends. {{B:Generic modules API}}: If you require even more customization, {{slapd}} lets you write your own modules easily. {{slapd}} consists @@ -264,12 +264,13 @@ well-defined {{TERM:C}} {{TERM:API}}, you can write your own customized modules which extend {{slapd}} in numerous ways. Also, a number of {{programmable database}} modules are provided. These allow you to expose external data sources to {{slapd}} using popular -programming languages ({{PRD:Perl}}, {{Shell}}, {{PRD:SQL}}, and +programming languages ({{PRD:Perl}}, {{shell}}, {{PRD:SQL}}, and {{PRD:TCL}}). -{{B:Threads}}: {{slapd}} is threaded for high performance. A single -multi-threaded {{slapd}} process handles all incoming requests, -reducing the amount of system overhead required. +{{B:Threads}}: {{slapd}} is threaded for high performance. A single +multi-threaded {{slapd}} process handles all incoming requests +using a pool of threads. This reduces the amount of system overhead +required while proving high performance. {{B:Replication}}: {{slapd}} can be configured to maintain replica copies of its database. This {{single-master/multiple-slave}} @@ -283,8 +284,8 @@ single configuration file which allows you to change just about everything you'd ever want to change. Configuration options have reasonable defaults, making your job much easier. -{{slapd}} also has its limitations, of course. The main LDBM -database backend does not handle range queries or negation queries +{{slapd}} also has its limitations, of course. The main BDB +backend does not handle range queries or negation queries very well. diff --git a/doc/guide/admin/quickstart.sdf b/doc/guide/admin/quickstart.sdf index 635e7775d6..f3467dad2b 100644 --- a/doc/guide/admin/quickstart.sdf +++ b/doc/guide/admin/quickstart.sdf @@ -136,38 +136,41 @@ whatever installation prefix was used by {{EX:configure}}). . Use your favorite editor to edit the provided {{slapd.conf}}(5) example (usually installed as {{F:/usr/local/etc/openldap/slapd.conf}}) -to contain an LDBM database definition of the form: +to contain an BDB database definition of the form: -..{{EX:database ldbm}} +..{{EX:database bdb}} ..{{EX:suffix "dc=,dc="}} ..{{EX:rootdn "cn=Manager,dc=,dc="}} ..{{EX:rootpw secret}} -..{{EX:directory /usr/local/var/openldap-ldbm}} +..{{EX:directory /usr/local/var/openldap-data}} . Be sure to replace {{EX:}} and {{EX:}} with the appropriate domain components of your domain name. For example, for {{EX:example.com}}, use: -..{{EX:database ldbm}} +..{{EX:database bdb}} ..{{EX:suffix "dc=example,dc=com"}} ..{{EX:rootdn "cn=Manager,dc=example,dc=com"}} ..{{EX:rootpw secret}} -..{{EX:directory /usr/local/var/openldap-ldbm}} +..{{EX:directory /usr/local/var/openldap-data}} .If your domain contains additional components, such as {{EX:eng.uni.edu.eu}}, use: -..{{EX:database ldbm}} +..{{EX:database bdb}} ..{{EX:suffix "dc=eng,dc=uni,dc=edu,dc=eu"}} ..{{EX:rootdn "cn=Manager,dc=eng,dc=uni,dc=edu,dc=eu"}} ..{{EX:rootpw secret}} -..{{EX:directory /usr/local/var/openldap-ldbm}} +..{{EX:directory /usr/local/var/openldap-data}} . Details regarding configuring {{slapd}}(8) can be found in the {{slapd.conf}}(5) manual page and the {{SECT:The slapd Configuration File}} chapter of this document. +Note: the directory specified must exist prior to starting slapd(8). + + .{{S: }} +{{B:Start SLAPD}}. diff --git a/doc/guide/admin/sasl.sdf b/doc/guide/admin/sasl.sdf index 53b886730d..844ebeff58 100644 --- a/doc/guide/admin/sasl.sdf +++ b/doc/guide/admin/sasl.sdf @@ -27,7 +27,7 @@ package (in {{FILE:doc/sysadmin.html}}). Note that in the following text the term {{user}} is used to describe a person or application entity who is connecting to the LDAP server via an LDAP client, such as {{ldapsearch}}(1). That is, the term -{{user}} not ony applies to both an individual using an LDAP client, +{{user}} not only applies to both an individual using an LDAP client, but to an application entity which issues LDAP client operations without direct user control. For example, an e-mail server which uses LDAP operations to access information held in an LDAP server diff --git a/doc/guide/admin/schema.sdf b/doc/guide/admin/schema.sdf index da054d6d8d..57ee01cc92 100644 --- a/doc/guide/admin/schema.sdf +++ b/doc/guide/admin/schema.sdf @@ -477,9 +477,9 @@ E: objectIdentifier { | [:] } The following demonstrates definition of a set of OID macros and their use in defining schema elements: -> objectIdentifier myOrgOID 1.1 -> objectIdentifier myOrgSNMP myOrgOID:1 -> objectIdentifier myOrgLDAP myOrgOID:2 +> objectIdentifier myOID 1.1 +> objectIdentifier mySNMP myOrgOID:1 +> objectIdentifier myLDAP myOrgOID:2 > objectIdentifier myAttributeType myOrgLDAP:1 > objectIdentifier myObjectClass myOrgLDAP:2 > attributetype ( myAttributeType:3 NAME 'myPhotoURI' diff --git a/doc/guide/admin/slapdconfig.sdf b/doc/guide/admin/slapdconfig.sdf index eb867cc928..e11831c3dd 100644 --- a/doc/guide/admin/slapdconfig.sdf +++ b/doc/guide/admin/slapdconfig.sdf @@ -237,9 +237,32 @@ by database directives. H4: backend -This directive marks the beginning of a backend definition. -{{EX:}} should be one of {{EX:ldbm}}, {{EX:shell}}, -{{EX:passwd}}, or other supported backend type. +This directive marks the beginning of a backend declaration. +{{EX:}} should be one of {{EX:bdb}} or one of other +supported backend types listed in Table 5.2. + +!block table; align=Center; coltags="EX,N"; \ + title="Table 5.2: Database Backends" +Types Description +bdb Berkeley DB transactional backend +dnssrv DNS SRV backend +ldbm Lightweight DBM backend +ldap Lightweight Directory Access Protocol (Proxy) backend +meta Meta Directory backend +monitor Monitor backend +passwd Provides read-only access to {{passwd}}(5) +perl Perl Programmable backend +shell Shell (extern program) backend +sql SQL Programmable backend +tcp TCP Programmable backend +!endblock + +\Example: + +> database bdb + +This marks the beginning of a new {{TERM:BDB}} backend +definition. H3: General Database Directives @@ -249,17 +272,17 @@ they are defined. They are supported by every type of database. H4: database -This directive marks the beginning of a new database instance -definition. -{{EX:}} should be one of {{EX:ldbm}}, {{EX:shell}}, -{{EX:passwd}}, or other supported database type. +This directive marks the beginning of a database instance +declaration. +{{EX:}} should be one of {{EX:bdb}} or one of other +supported backend types listed in Table 5.2. \Example: -> database ldbm +> database bdb -This marks the beginning of a new LDBM backend database -instance definition. +This marks the beginning of a new {{TERM:BDB}} database instance +declaration. H4: readonly { on | off } @@ -415,11 +438,27 @@ If specified multiple times, each {{TERM:URL}} is provided. > updateref ldap://master.example.net -H3: LDBM Backend-Specific Directives +H3: BDB Database Directives + +Directives in this category only apply a BDB database. That is, +they must follow a "database bdb" line and come before any +subsequent "backend" or "database" line. + +H4: directory + +This directive specifies the directory where the BDB files +containing the database and associated indexes live. + +\Default: + +> directory /usr/local/var/openldap-data + + +H3: LDBM Database Directives -Directives in this category only apply to the LDBM backend -database. That is, they must follow a "database ldbm" line and -come before any other "database" line. +Directives in this category only apply a LDBM database. That is, +they must follow a "database ldbm" line and come before any +subsequent "backend" or "database" line. H4: cachesize @@ -466,7 +505,7 @@ containing the database and associated indexes live. \Default: -> directory /usr/local/var/openldap-ldbm +> directory /usr/local/var/openldap-data H4: index { | default} [pres,eq,approx,sub,none] @@ -507,24 +546,6 @@ created database index files should have. > mode 0600 - -H3: Other Backend Databases - -{{slapd}}(8) supports a number of backend database types besides the default LDBM. - -!block table; align=Center; coltags="EX,N"; \ - title="Table 5.2: Backend Database Types" -Types Description -ldbm Berkeley or GNU DBM compatible backend -passwd Provides read-only access to {{F:/etc/passwd}} -shell Shell (extern program) backend -sql SQL Programmable backend -!endblock - -See {{slapd.conf}}(5) for details. - - - H2: Access Control Access to slapd entries and attributes is controlled by the @@ -720,7 +741,7 @@ This access directive grants read access to everyone. > by * read This directive allows users to modify their own entries, -allows authenticate, and allows authenticated users to read. +allows authenticate, and allows all others to read. Note that only the first {{EX:by }} clause which matches applies. Hence, the anonymous users are granted {{EX:auth}}, not {{EX:read}}. The last clause could just as well have been "{{EX:by users read}}". @@ -800,7 +821,7 @@ H2: Configuration File Example The following is an example configuration file, interspersed with explanatory text. It defines two databases to handle -different parts of the {{TERM:X.500}} tree; both are {{TERM:LDBM}} +different parts of the {{TERM:X.500}} tree; both are {{TERM:BDB}} database instances. The line numbers shown are provided for reference only and are not included in the actual file. First, the global configuration section: @@ -821,7 +842,7 @@ Line 4 is a global access control. It applies to all entries (after any applicable database-specific access controls). -The next section of the configuration file defines an LDBM +The next section of the configuration file defines an BDB backend that will handle queries for things in the "dc=example,dc=com" portion of the tree. The database is to be replicated to two slave slapds, one on @@ -829,10 +850,10 @@ truelies, the other on judgmentday. Indexes are to be maintained for several attributes, and the {{EX:userPassword}} attribute is to be protected from unauthorized access. -E: 5. # ldbm definition for the example.com -E: 6. database ldbm +E: 5. # BDB definition for the example.com +E: 6. database bdb E: 7. suffix "dc=example,dc=com" -E: 8. directory /usr/local/var/openldap +E: 8. directory /usr/local/var/openldap-data E: 9. rootdn "cn=Manager,dc=example,dc=com" E: 10. rootpw secret E: 11. # replication directives @@ -847,7 +868,7 @@ E: 19. # indexed attribute definitions E: 20. index uid pres,eq E: 21. index cn,sn,uid pres,eq,approx,sub E: 22. index objectClass eq -E: 23. # ldbm access control definitions +E: 23. # database access control definitions E: 24. access to attr=userPassword E: 25. by self write E: 26. by anonymous auth @@ -889,15 +910,15 @@ All other attributes are writable by the entry and the "admin" entry, but may be read by all users (authenticated or not). The next section of the example configuration file defines another -LDBM database. This one handles queries involving the +BDB database. This one handles queries involving the {{EX:dc=example,dc=net}} subtree but is managed by the same entity as the first database. Note that without line 39, the read access would be allowed due to the global access rule at line 4. -E: 33. # ldbm definition for example.net -E: 34. database ldbm +E: 33. # BDB definition for example.net +E: 34. database bdb E: 35. suffix "dc=example,dc=net" -E: 36. directory /usr/local/var/ldbm-example-net +E: 36. directory /usr/local/var/openldap-data-net E: 37. rootdn "cn=Manager,dc=example,dc=com" E: 38. index objectClass eq E: 39. access to * by users read diff --git a/doc/guide/admin/tls.sdf b/doc/guide/admin/tls.sdf index b6e0c90b03..067eebc9be 100644 --- a/doc/guide/admin/tls.sdf +++ b/doc/guide/admin/tls.sdf @@ -4,9 +4,9 @@ H1: Using TLS OpenLDAP clients and servers are capable of using the -Transport Layer Security {{TERM:TLS}} framework to provide +{{TERM[expand]TLS}} ({{TERM:TLS}}) framework to provide integrity and confidentiality protections and to support -LDAP authentication using the SASL EXTERNAL mechanism. +LDAP authentication using the {{TERM:SASL}} EXTERNAL mechanism. TLS uses {{TERM:X.509}} certificates to carry client and server identities. All servers are required to have valid certificates, diff --git a/doc/guide/admin/tuning.sdf b/doc/guide/admin/tuning.sdf index afe821c990..61a4681154 100644 --- a/doc/guide/admin/tuning.sdf +++ b/doc/guide/admin/tuning.sdf @@ -4,6 +4,8 @@ H1: Performance Tuning +Note: this chapter needs to be updated to discuss BDB tuning. + There are several things you can do to tune the performance of slapd for your system. Most of them have to do with the LDBM backend. LDBM uses an index mechanism to store and retrieve diff --git a/doc/guide/preamble.sdf b/doc/guide/preamble.sdf index 30b4b451cc..7e44461710 100644 --- a/doc/guide/preamble.sdf +++ b/doc/guide/preamble.sdf @@ -121,7 +121,7 @@ GNU|GNU Not Unix|http://www.gnu.org/ !block products; data Name|Jump -BerkeleyDB|http://www.sleepycat.com/ +Berkeley DB|http://www.sleepycat.com/ CVS|http://www.cyclic.com/ Cyrus|http://asg.web.cmu.edu/cyrus/ GNU|http://www.gnu.org/software/ @@ -142,6 +142,7 @@ Term|Definition API|Application Program Interface ASN|Abstract Syntax Notation ASN.1|Abstract Syntax Notation 1 +BDB|Berkeley DB BCP|Best Common Practice BDB|Berkeley DB BER|Basic Encoding Rules -- 2.39.5