--- /dev/null
+H1: The Big Picture - Configuration Choices
+
+This section gives a brief overview of various LDAP directory
+configurations, and how your LDAP server (either {{I:slapd}} or
+{{I:ldapd}}) fits in with the rest of the world.
+
+
+
+H2: LDAP as a local service only
+
+In this configuration, you run a {{I:slapd}} which provides directory service
+for your local domain only. It does not interact with other directory
+servers in any way. This configuration is shown in Figure 2.
+
+!import "figure_2.gif"; align="center"; title="Local service via slapd configuration"
+FT: Figure 2: Local service via slapd configuration.
+
+Use this configuration if you are just starting out (it's the one the
+quick-start guide makes for you) or if you want to provide a local
+service and are not interested in connecting to the rest of the world.
+It's easy to upgrade to another configuration later if you want.
+
+
+
+H2: Local service with X.500 referrals
+
+In this configuration, you run a slapd which provides directory service
+for your local domain and an ldapd which provides access to the
+X.500 world (you don't have to run the ldapd yourself - you can just
+point to somebody else who does and doesn't mind you pointing to
+their service). This configuration is shown in Figure 3.
+
+!import "figure_3.gif"; align="center"; title="Local service via slapd + X.500 referrals configuration"
+FT: Figure 3: Local service via slapd + X.500 referrals configuration
+
+Use this configuration if you want to provide local service but still want
+to be connected to the rest of the X.500 world. Remember, you don't
+necessarily have to be running the ldapd in this picture; you just need
+to find one you can point to.
+
+
+
+H2: LDAP as a front end to X.500
+
+In this configuration, you run an X.500 service which provides
+directory service for your local domain and gatewaying service to the
+rest of the X.500 world. LDAP clients gain access to the directory
+through an ldapd which runs at your site. This configuration is shown
+in Figure 4.
+
+!import "figure_4.gif"; align="center"; title="Local service via X.500 and ldapd configuration"
+FT: Figure 4: Local service via X.500 and ldapd configuration
+
+Use this configuration if you are already running an X.500 service.
+Slapd is not involved in this configuration, so you can probably stop
+reading this guide.
+
+
+
+H2: Replicated slapd service
+
+The slurpd daemon is used to propagate changes from a master slapd
+to one or more slave slapds. An example master-slave configuration
+is shown in figure 5.
+
+!import "figure_5.gif"; align="center"; title="Master slapd with two slaves replicated with slurpd"
+FT: Figure 5: Master slapd with two slaves replicated with slurpd
+
+This configuration can be used in conjunction with the first two
+configurations in situations where a single slapd does not provide the
+required reliability or availability.
+
+PB:
+
+
+
--- /dev/null
+H1: Database Creation and Maintenance Tools
+
+This section tells you how to create a slapd database from
+scratch, and how to do trouble shooting if you run into
+problems. There are two ways to create a database. First,
+you can create the database on-line using LDAP. With this
+method, you simply start up slapd and add entries using the
+LDAP client of your choice. This method is fine for relatively
+small databases (a few hundred or thousand entries,
+depending on your requirements).
+
+The second method of database creation is to do it off-line,
+using the index generation tools. This method is best if you
+have many thousands of entries to create, which would take
+an unacceptably long time using the LDAP method, or if you
+want to ensure the database is not accessed while it is
+being created.
+
+
+
+H2: Creating a database over LDAP
+
+
+
+With this method, you use the LDAP client of your choice
+(e.g., the ldapadd(1) tool) to add entries, just like you would
+once the database is created. You should be sure to set the
+following configuration options before starting slapd:
+
+E: suffix <dn>
+
+As described in the preceding section, this option says what
+entries are to be held by this database. You should set this
+to the DN of the root of the subtree you are trying to create.
+For example
+
+E: suffix "o=University of Michigan, c=US"
+
+You should be sure to specify a directory where the index
+files should be created:
+
+E: directory <directory>
+
+For example:
+
+E: directory /usr/local/openldap/slapd
+
+You need to make it so you can connect to slapd as
+somebody with permission to add entries. This is done
+through the following two options in the database definition:
+
+E: rootdn <dn>
+E: rootpw <passwd>
+
+These options specify a DN and password that can be used
+to authenticate as the "superuser" entry of the database (i.e.,
+the entry allowed to do anything). The DN and password
+specified here will always work, regardless of whether the
+entry named actually exists or has the password given. This
+solves the chicken-and-egg problem of how to authenticate
+and add entries before any entries yet exist.
+
+Finally, you should make sure that the database definition
+contains the index definitions you want:
+
+E: index {<attrlist> | default} [pres,eq,approx,sub,none]
+
+For example, to index the cn, sn, uid and objectclass
+attributes the following index configuration lines could be
+used.
+
+E: index cn,sn,uid
+E: index objectclass pres,eq
+E: index default none
+
+See Section 4 on the configuration file for more details on
+this option. Once you have configured things to your liking,
+start up slapd, connect with your LDAP client, and start
+adding entries. For example, to add a the U of M entry
+followed by a Postmaster entry using the {{I:ldapadd}} tool, you
+could create a file called {{EX:/tmp/newentry}} with the contents:
+
+
+E: o=University of Michigan, c=US
+E: objectClass=organization
+E: o=University of Michigan
+E: description=University of Michigan at Ann Arbor
+E: cn=Postmaster, o=University of Michigan, c=US
+E: objectClass=organizationalRole
+E: cn=Postmaster
+E: description=U of M postmaster - postmaster@umich.edu
+
+and then use a command like this to actually create the
+entry:
+
+E: ldapadd -f /tmp/newentry -D "cn=Manager, o=University of
+E: Michigan, c=US" -w secret
+
+The above command assumes that you have set {{EX: rootdn}} to
+"cn=Manager, o=University of Michigan, c=US" and {{EX: rootpw}}
+to "secret".
+
+H2: Creating a database off-line
+
+The second method of database creation is to do it off-line,
+using the index generation tools described below. This
+method is best if you have many thousands of entries to
+create, which would take an unacceptably long time using
+the LDAP method described above. These tools read the
+slapd configuration file and an input file containing a text
+representation of the entries to add. They produce the LDBM
+index files directly. There are several important configuration
+options you will want to be sure and set in the config file
+database definition first:
+
+E: suffix <dn>
+
+As described in the preceding section, this option says what
+entries are to be held by this database. You should set this
+to the DN of the root of the subtree you are trying to create.
+For example
+
+E: suffix "o=University of Michigan, c=US"
+
+You should be sure to specify a directory where the index
+files should be created:
+
+E: directory <directory>
+
+For example:
+
+E: directory /usr/local/openldap-slapd
+
+Next, you probably want to increase the size of the in-core
+cache used by each open index file. For best performance
+during index creation, the entire index should fit in memory. If
+your data is too big for this, or your memory too small, you
+can still make it pretty big and let the paging system do the
+work. This size is set with the following option:
+
+E: dbcachesize <integer>
+
+For example:
+
+E: dbcachesize 50000000
+
+This would create a cache 50 MB big, which is pretty big (at
+U-M, our database has about 125K entries, and our biggest
+index file is about 45 MB). Experiment with this number a bit,
+and the degree of parallelism (explained below), to see what
+works best for your system. Remember to turn this number
+back down once your index files are created and before you
+run slapd.
+
+Finally, you need to specify which indexes you want to build.
+This is done by one or more index options.
+
+E: index {<attrlist> | default} [pres,eq,approx,sub,none]
+
+For example:
+
+E: index cn,sn,uid pres,eq,approx
+E: index default none
+
+This would create presence, equality and approximate
+indexes for the cn, sn, and uid attributes, and no indexes for
+any other attributes. See the configuration file section for
+more information on this option.
+
+H3: The {{EX: ldif2ldbm}} program
+
+Once you've configured things to your liking, you create the
+indexes by running the ldif2ldbm program:
+
+E: ldif2ldbm -i <inputfile> -f <slapdconfigfile>
+E: [-d <debuglevel>] [-j <integer>]
+E: [-n <databasenumber>] [-e <etcdir>]
+
+The arguments have the following meanings:
+
+E: -i <inputfile>
+
+Specifies the LDIF input file containing the entries to add in
+text form (described below in Section 8.3).
+
+E: -f <slapdconfigfile>
+
+Specifies the slapd configuration file that tells where to
+create the indexes, what indexes to create, etc.
+
+E: -d <debuglevel>
+
+Turn on debugging, as specified by {{EX: <debuglevel>}}. The
+debug levels are the same as for slapd (see Section 6.1).
+
+E: -j <integer>
+
+An optional argument that specifies that at most {{EX: <integer>}}
+processes should be started in parallel when building the
+indexes. The default is 1. If set to a value greater than one,
+{{I: ldif2ldbm}} will create at most that many subprocesses at a
+time when building the indexes. A separate subprocess is
+created to build each attribute index. Running these
+processes in parallel can speed things up greatly, but
+beware of creating too many processes, all competing for
+memory and disk resources.
+
+E: -n <databasenumber>
+
+An optional argument that specifies the configuration file
+database for which to build indices. The first database listed
+is "1", the second "2", etc. By default, the first ldbm database
+in the configuration file is used.
+
+E: -e <etcdir>
+
+An optional argument that specifies the directory where
+{{EX: ldif2ldbm}} can find the other database conversion tools it
+needs to execute ({{EX: ldif2index}} and friends). The default is the
+installation {{EX: ETCDIR}}.
+
+The next sections describe the programs invoked by
+{{I: ldif2ldbm}} when it is building indexes. Normally, these
+programs are invoked for you, but occasionally you may
+want to invoke them yourself.
+
+
+
+H3: The {{EX: ldif2index}} program
+
+Sometimes it may be necessary to create a new attribute
+index file without disturbing the rest of the database. This is
+possible using the {{EX: ldif2index}} program. {{EX: ldif2index}} is invoked
+like this
+
+E: ldif2index -i <inputfile> -f <slapdconfigfile>
+E: [-d <debuglevel>] [-n <databasenumber>] <attr>
+
+Where the -i, -f, -d, and -n options are the same as for the
+{{I: ldif2ldbm}} program. {{EX: <attr>}} is the attribute to build an index for.
+Which indexes are built (e.g., equality, substring, etc.) is
+controlled by the corresponding index line in the slapd
+configuration file.
+
+You can use the ldbmcat program to create a suitable LDIF
+input file from an existing LDBM database.
+
+
+
+H3: The {{EX: ldif2id2entry}} program
+
+The {{EX: ldif2id2entry}} program is normally invoked from {{EX: ldif2ldbm}}.
+It is used to convert an LDIF text file into an {{EX: id2entry}} index.
+It is unlikely that you would need to invoke it yourself, but if
+you do it works like this
+
+E: ldif2id2entry -i <inputfile> -f <slapdconfigfile>
+E: [-d <debuglevel>] [-n <databasenumber>]
+
+The arguments are the same as for the {{EX: ldif2ldbm}} program.
+
+
+
+H3: The {{EX: ldif2id2children}} program
+
+The {{EX: ldif2id2children}} program is normally invoked from
+{{EX: ldif2ldbm}}. It is used to convert an LDIF text file into
+{{EX: id2children}} and {{EX: dn2id}} indexes. Occasionally, it may be
+necessary to run this program yourself, for example if one of
+these indexes has become corrupted. {{EX: ldif2id2children}} is
+invoked like this
+
+E: ldif2id2children -i <inputfile> -f <slapdconfigfile>
+E: [-d <debuglevel>] [-n <databasenumber>]
+
+The arguments are the same as for the {{EX: ldif2ldbm}} program.
+You can use the ldbmcat program to create a suitable LDIF
+input file from an existing LDBM database.
+
+
+
+H3: The {{EX: ldbmcat}} program
+
+The {{EX: ldbmcat}} program is used to convert an {{EX: id2entry}} index
+back into its LDIF text format. This can be useful when you
+want to make a human-readable backup of your database,
+or as an intermediate step in creating a new index using the
+{{EX: ldif2index}} program. The program is invoked like this:
+
+E: ldbmcat [-n] <filename>
+
+where {{EX: <filename>}} is the name of the {{EX: id2entry}} index file. The
+corresponding LDIF output is written to standard output.
+
+The -n option can be used to prevent the printing of entry
+IDs in the LDIF format. If you are creating an LDIF format for
+use as input to {{EX: ldif2index}} or anything by {{EX: ldif2ldbm}}, you
+should not use the -n option (because the entry IDs must
+match those already in the id2entry file). If you are just
+making a backup of your data, you can use the -n option to
+save space.
+
+
+
+H3: The {{EX: ldif}} program
+
+The ldif program is used to convert arbitrary data values to
+LDIF format. This can be useful when writing a program or
+script to create the LDIF file you will feed into the ldif2ldbm
+program, or when writing a SHELL backend. ldif takes an
+attribute name as an argument, and reads the attribute
+value(s) from standard input. It produces the LDIF formatted
+attribute line(s) on standard output. The usage is:
+
+E: ldif [-b] <attrname>
+
+where {{EX: <attrname>}} is the name of the attribute. Without the
+-b option, ldif considers each line of standard input to be a
+separate value of the attribute.
+
+The -b option can be used to force ldif to interpret its input
+as a single raw binary value. This option is useful when
+converting binary data such as a {{EX: jpegPhoto}} or {{EX: audio}}
+attribute.
+
+
+H2: The LDIF text entry format
+
+The LDAP Data Interchange Format (LDIF) is used to
+represent LDAP entries in a simple text format. The basic
+form of an entry is:
+
+E: [<id>]
+E: dn: <distinguished name>
+E: <attrtype>: <attrvalue>
+E: <attrtype>: <attrvalue>
+E:
+E: ...
+
+where {{EX: <id>}} is the optional entry ID (a positive decimal
+number). Normally, you would not supply the {{EX: <id>}}, allowing
+the database creation tools to do that for you. The ldbmcat
+program, however, produces an LDIF format that includes
+{{EX: <id>}} so that new indexes created will be consistent.
+
+A line may be continued by starting the next line with a
+single space or tab character. e.g.,
+
+E: dn: cn=Barbara J Jensen, o=University of Michigan, c=US
+
+Multiple attribute values are specified on separate lines. e.g.,
+
+E: cn: Barbara J Jensen
+E: cn: Babs Jensen
+
+If an {{EX: <attrvalue>}} contains a non-printing character, or
+begins with a space or a colon `:', the {{EX: <attrtype>}} is followed
+by a double colon and the value is encoded in base 64
+notation. e.g., the value " begins with a space" would be
+encoded like this:
+
+E: cn:: IGJlZ2lucyB3aXRoIGEgc3BhY2U=
+
+Multiple entries within the same LDIF file are separated by
+blank lines. Here's an example of an LDIF file containing
+three entries.
+
+E: dn: cn=Barbara J Jensen, o=University of Michigan, c=US
+E: cn: Barbara J Jensen
+E: cn: Babs Jensen
+E: objectclass: person
+E: sn: Jensen
+E:
+E:
+E: dn: cn=Bjorn J Jensen, o=University of Michigan, c=US
+E: cn: Bjorn J Jensen
+E: cn: Bjorn Jensen
+E: objectclass: person
+E: sn: Jensen
+E:
+E: dn: cn=Jennifer J Jensen, o=University of Michigan, c=US
+E: cn: Jennifer J Jensen
+E: cn: Jennifer Jensen
+E: objectclass: person
+E: sn: Jensen
+E: jpegPhoto:: /9j/4AAQSkZJRgABAAAAAQABAAD/2wBDABALD
+E: A4MChAODQ4SERATGCgaGBYWGDEjJR0oOjM9PDkzODdASFxOQ
+E: ERXRTc4UG1RV19iZ2hnPk1xeXBkeFxlZ2P/2wBDARESEhgVG
+E:
+E: ...
+
+Notice that the {{EX: jpegPhoto}} in Jennifer Jensen's entry is
+encoded using base 64. The {{EX: ldif}} program (described in
+Section 8.2.6) can be used to produce the LDIF format.
+
+Note: Trailing spaces are not trimmed from values in an
+LDIF file. Nor are multiple internal spaces compressed. If
+you don't want them in your data, don't put them there.
+
+
+H2: Converting from QUIPU EDB format to LDIF format
+
+If you have directory data that is or was held in a QUIPU
+DSA (available as part of the ISODE package), you will want
+to convert the EDB files used by QUIPU into an LDIF file.
+The edb2ldif program is provided to do most of the
+conversion for you. Once you have an LDIF file, you should
+follow the steps outlined in section 6.2 above to build an
+LDBM database for slapd.
+
+
+
+H3: The {{EX: edb2ldif}} program
+
+The edb2ldif program is invoked like this:
+
+E: edb2ldif [-d] [-v] [-r] [-o] [-b <basedn>]
+E: [-a <addvalsfile>] [-f <fileattrdir>]
+E: [-i <ignoreattr...>] [<edbfile...>]
+
+The LDIF data is written to standard output. The arguments
+have the following meanings:
+
+E: -d
+
+This option enables some debugging output on standard
+error.
+
+E: -v
+
+Enable verbose mode that writes status information to
+standard error, such as which EDB file is being processed,
+how many entries have been converted so far, etc.
+
+E: -r
+
+Recurse through child directories, processing all EDB files
+found.
+
+E: -o
+
+Cause local .add file definitions to override the global addfile
+(see -a below)
+
+E: -b <basedn>
+
+Specify the Distinguished Name that all EDB file entries
+appear below.
+
+E: -a <addvalsfile>
+
+The LDIF information contained in this file will be appended
+to each entry.
+
+E: -f <fileattrdir>
+
+Specify a single directory where all file-based attributes
+(typically sounds and images) can be found. If this option is
+not given, file attributes are assumed to be located in the
+same directory as the EDB file that refers to them.
+
+E: -i <ignoreattr>
+
+Specify an attribute that should not be converted. You can
+include as many -i flags as necessary.
+
+E: <edbfile>
+
+Specify a particular EDB file (or files) to read data from. By
+default, the EDB.root (if it exists) and EDB files in the current
+directory are used.
+
+When {{EX: edb2ldif}} is invoked, it will also look for files named
+.add in the directories where EDB files are found and append
+the contents of the .add file to each entry. Typically, this
+feature is used to include inherited attribute values (e.g.,
+{{EX: objectClass}}) that do not appear in the EDB files.
+
+
+
+H3: Step-by-step EDB to LDIF conversion
+
+The basic steps to follow when converting your EDB format
+data to an LDIF file are:
+
+^ Locate the directory at the top of the EDB file hierarchy
+.that your QUIPU DSA masters. The EDB file located there
+.should contain the entries for the first level of your
+.organization or organizational unit. If you are using an
+.indexed database with QUIPU, you may need to create EDB
+.files from your index files (using the synctree or qb2edb
+.tools).
+.
+
++If you do not have a file named EDB.root in the same
+.directory that contains your organizational or organizational
+.unit entry, create it now by hand. Its contents should look
+.something like this:
+.
+.{{EX: MASTER}}
+.{{EX: 000001}}
+.{{EX: }}
+.{{EX: o=University of Michigan}}
+.{{EX: objectClass= top & organization & domainRelatedObject &\}}
+.{{EX: quipuObject & quipuNonLeafObject}}
+.{{EX: l= Ann Arbor, Michigan}}
+.{{EX: st= Michigan}}
+.{{EX: o= University of Michigan & UMICH & UM & U-M & U of M}}
+.{{EX: description= The University of Michigan at Ann Arbor}}
+.{{EX: associatedDomain= umich.edu}}
+.{{EX: masterDSA= c=US@cn=Woolly Monkey}}
+.{{EX: }}
+
++ (Optional) Create a global add file and/or local .add files to
+.take care of adding any attribute values that do not appear in
+.the EDB files. For example, if all entries in a particular EDB
+.are person entries and you want to add the appropriate
+.objectClass attribute value for them, create a file called .add
+.in the same directory as the person EDB that contains the
+.single line:
+.
+.{{EX: objectClass: person }}
+.
+
++ Run the edb2ldif program to do the actual conversion.
+.Make sure you are in the directory that contains the root of
+.the EDB hierarchy (the one where the EDB.root file resides).
+.Include a -b flag with a base DN one level above your
+.organizational entry, and include -i flags to ignore any
+.attributes that are not useful to slapd. E.g., the command:
+.
+.{{EX: edb2ldif -v -r -b "c=US" -i iattr -i acl -i xacl -i sacl}}
+.{{EX: -i lacl -i masterDSA -i slaveDSA > ldif}}
+.
+.will convert the entire EDB hierarchy to LDIF format and
+.write the result to a file named ldif. Some attributes that are
+.not useful when running slapd are ignored. The EDB
+.hierarchy is assumed to reside logically below the base DN
+."c=US".
+.
+
++ Follow the steps outlined in section 8.2 above to produce
+.an LDBM database from your new LDIF file.
+
+
+
+H2: The ldbmtest program
+
+Occasionally you may find it useful to look at the LDBM
+database and index files directly (i.e., without going through
+slapd). The {{EX: ldbmtest}} program is provided for this purpose. It
+gives you raw access to the database itself. {{EX: ldbmtest}} should
+be run line this:
+
+E: ldbmtest [-d <debuglevel>] [-f <slapdconfigfile>]
+
+The default configuration file in the {{EX: ETCDIR}} is used if you
+don't supply one. By default, ldbmtest operates on the last
+database listed in the config file. You can specify an
+alternate database, or see the current database with the
+following commands.
+
+E: b specify an alternate backend database
+E: B print out the current backend database
+
+The {{EX: b}} command will prompt you for the suffix associated with
+the database you want. The database you select can be
+viewed and modified using a set of two-letter commands.
+The first letter selects the command function to perform.
+Possible commands and their meanings are as follows.
+
+E: l lookup (do not follow indirection)
+E: L lookup (follow indirection)
+E: t traverse and print keys and data
+E: T traverse and print keys only
+E: x delete an index item
+E: e edit an index item
+E: a add an index item
+E: c create an index file
+E: i insert an entry into an index item
+
+The second letter indicates which index the command
+applies to. The possible index selections are as follows.
+
+E: c id2children index
+E: d dn2id index
+E: e id2entry index
+E: f arbitrary file name
+E: i attribute index
+
+Each command may require additional arguments which
+ldbmtest will prompt you for.
+
+To exit {{EX: ldbmtest}}, type {{EX: control-D}} or {{EX: control-C}}.
+
+Note that this is a very raw interface originally developed
+when testing the database format. It is provided and
+minimally documented here for interested parties, but it is not
+meant to be used by the inexperienced. See the next section
+for a brief description of the LDBM database format.
+
+
+
+H2: The LDBM database format
+
+In normal operation, it is not necessary for you to know much
+about the LDBM database format. If you are going to use the
+ldbmtest program to look at or alter the database, or if you
+want a deeper understanding of how indexes are maintained,
+some knowledge of how it works could be useful. This
+section gives an overview of the database format and how
+slapd makes use of it.
+
+
+
+H3: Overview
+
+The LDBM database works by assigning a compact
+four-byte unique identifier to each entry in the database. It
+uses this identifier to refer to entries in indexes. The
+database consists of one main index file, called id2entry,
+which maps from an entry's unique identifier (EID) to a text
+representation of the entry itself. Other index files are
+maintained, for each indexed attribute for example, that map
+values people are likely to search on to lists of EIDs.
+
+Using this simple scheme, many LDAP queries can be
+answered efficiently. For example, to answer a search for
+entries with a surname of "Jensen", slapd would first consult
+the surname attribute index, look up the value "Jensen" and
+retrieve the corresponding list of EIDs. Next, slapd would
+look up each EID in the id2entry index, retrieve the
+corresponding entry, convert it from text to LDAP format, and
+return it to the client.
+
+The following sections give a very brief overview of each
+type of index and what it contains. For more detailed
+information see the paper "An X.500 and LDAP Database:
+Design and Implementation," available in postscript format
+from
+
+{{CMD[jump="ftp://terminator.rs.itd.umich.edu/ldap/papers/xldbm.ps"]ftp://terminator.rs.itd.umich.edu/ldap/papers/xldbm.ps}}
+
+
+
+H3: Attribute index format
+
+The LDBM backend will maintain one index file for each
+attribute it is asked to index. Several sets of keys must
+coexist in this file (e.g., keys for equality and approximate
+equality), so the keys are prefixed with a character to ensure
+uniqueness. The prefixes are given in the table below
+
+E: = equality keys
+E: ~ approximate equality keys
+E: * substring equality keys
+E: \ continuation keys
+
+Key values are also normalized (e.g., converted to upper
+case for case ignore attributes). So, for example, to look up
+the surname equality value in the example above using the
+ldbmtest program, you would look up the value "{{EX: =JENSEN}}".
+
+Substring indexes are maintained by generating all possible
+N-character substrings for a value (N is 3 by default). These
+substrings are then stored in the attribute index, prefixed by
+"*". Additional anchors of "^" and "$" are added at the
+beginning and end of words. So, for example the surname of
+Jensen would cause the following keys to be entered in the
+index: {{EX: ^JE, JEN, ENS, NSE, SEN, EN$}}.
+
+Approximate values are handled in a similar way, with
+phonetic codes being generated for each word in a value
+and then stored in the index, prefixed by "~".
+
+Large blocks in the index are split into smaller ones. The
+smaller blocks are accessed through a level of indirection
+provided by the original block. They are stored in the index
+using the continuation key prefix of "\".
+
+
+
+H3: Other indexes
+
+In addition to the {{EX: id2entry}} and attribute indexes, LDBM
+maintains a number of other indexes, including the {{EX: dn2id}}
+index and the {{EX: id2children}} index. These indexes provide the
+mapping between a DN and the corresponding EID, and the
+mapping between an EID and the EIDs of the corresponding
+entry's children, respectively.
+
+The {{EX: dn2id}} index stores normalized DNs as keys. The data
+stored is the corresponding EID.
+
+The {{EX: id2children}} index stores EIDs as keys. The data stored
+is a list of EIDs, just as for the attribute indexes.
+
+
+PB:
+
+
+
--- /dev/null
+H1: Building and Installing slapd & slurpd
+
+Building and installing slapd requires three simple steps: configuring;
+making; and installing. The following sections describe each step in
+detail. If you are reading this guide, chances are you have already
+obtained the software, but just in case, here's where you can get the
+latest version of the OpenLDAP package, which includes all of the
+software discussed in this guide:
+
+{{CMD[jump="ftp://ftp.openldap.org/pub/OpenLDAP/openldap-release.tgz"]ftp://ftp.openldap.org/pub/OpenLDAP/openldap-release.tgz}}
+
+There is also an OpenLDAP homepage accessible from the World
+Wide Web. This page contains the latest OpenLDAP news, release
+announcements, and pointers to other resources. You can access it
+at:
+
+{{CMD[jump="http://www.OpenLDAP.org/"]http://www.OpenLDAP.org/}}
+
+
+H2: Pre-Build Configuration
+
+Before building slapd, be sure to take a look at the README file in the
+top level directory in the distribution so that you are familiar with the
+general configuration and make process.
+
+Briefly, you should edit the include/ldapconfig.h.edit and
+Make-common files to contain the site-specific configuration your site
+requires before making. The next sections discuss these steps in
+more detail.
+
+
+
+H3: Editing the {{EX: Make-common}} file
+
+All of the general Make-common configuration variables (e.g.,
+ETCDIR, BINDIR, etc.) apply to both slapd and slurpd. There are
+additional Make-common configuration variables that also affect how
+slapd and slurpd are built. They are:
+
+H4: MAKE_SLAPD
+
+This option controls whether slapd and slurpd get built at all. You
+should set it to yes, like this:
+
+E: MAKE_SLAPD = yes
+
+H4: SLAPD_BACKENDS
+
+This option controls which slapd backend databases get built. You
+should set it to one or more of the following:
+
+*{{EX: DLDAP_LDBM}} This is the main backend. It is a high-performance
+disk-based database suitable for handling up to a million entries or so.
+See the LDBMBACKEND and LDBMLIB options below.
+
+*{{EX: DLDAP_PASSWD}} This is a simple search-only backend that can be
+pointed at an {{EX: /etc/passwd}} file. It is intended more as an example than
+as a real backend.
+
+*{{EX: DLDAP_SHELL}} This backend allows the execution of arbitrary
+system administrator-defined commands in response to LDAP
+queries. The commands to execute are defined in the configuration file.
+See Appendix B for more information on writing shell backend
+programs.
+
+Example to enable the LDBM and SHELL backends only:
+
+E: SLAPD_BACKENDS= -DLDAP_LDBM -DLDAP_SHELL
+
+The default is to build all three backends. Note that building a backend
+only means that it can be enabled through the configuration file, not
+that it will automatically be enabled.
+
+H4: LDBMBACKEND
+
+This option should only be defined if you have enabled the LDBM
+backend as described above. The LDBM backend relies on a
+low-level hash or B-tree package for its underlying database. This
+option selects which package it will use. The currently supported
+options in order of preference are:
+
+*{{EX: DLDBM_USE_DBBTREE}}
+.
+.This option enables the Berkeley DB package btree database as the
+.LDBM backend. You can get this package from
+.
+.{{CMD[jump="ftp://ftp.cs.berkeley.edu/ucb/4bsd/db.tar.Z"]ftp://ftp.cs.berkeley.edu/ucb/4bsd/db.tar.Z}}
+.
+
+*{{EX: DLDBM_USE_DBHASH}}
+.
+.This option enables the Berkeley DB package hash database as the
+.LDBM backend. You can get this package from
+.
+.{{CMD[jump="ftp://ftp.cs.berkeley.edu/ucb/4bsd/db.tar.Z"]ftp://ftp.cs.berkeley.edu/ucb/4bsd/db.tar.Z}}
+.
+
+*{{EX: DLDBM_USE_GDBM}}
+.
+.This option enables GNU dbm as the LDBM backend. You can get this
+.package from
+.
+.{{CMD[jump="ftp://prep.ai.mit.edu/pub/gnu/gdbm-1.7.3.tar.gz"]ftp://prep.ai.mit.edu/pub/gnu/gdbm-1.7.3.tar.gz}}
+.
+
+*{{EX: DLDBM_USE_NDBM}}
+.
+.This option enables the standard UNIX ndbm(3) package as the
+.LDBM backend. This package should come standard on your UNIX
+.system. man ndbm for details.
+.
+
+Example to enable the Berkeley DB Btree backend:
+
+E: LDBMBACKEND= -DLDBM_USE_DBBTREE
+
+The default is -DLDBM_USE_NDBM, since it is the only one available
+on all UNIX systems. NDBM has some serious limitations, though (not
+thread-safe, severe size limits), and you are strongly encouraged to
+use one of the other packages if you can.
+
+Note[label='Note to Solaris users: '] If you are running under Solaris 2.x
+and linking in an external database package (e.g., db or gdbm) it is
+very important that you compile the package with the {{EX: D_REENTRANT}}
+flag. If you do not, bad things will happen.
+
+If you are using version 1.85 or earlier of the Berkeley db package, you
+will need to apply the patch found in build/db.1.85.patch to the db
+source before compiling it. You can do this with a command like this
+from the db source area:
+
+E: patch -p < ldap-source-directory/build/db.1.85.patch
+
+H4: LDBMLIB
+
+This option should only be defined if you have enabled the LDBM
+backend as described above, and the necessary library for the
+LDBMBACKEND option you chose above is not part of the standard C
+library (i.e., anything other than NDBM). This option specifies the library
+to link containing the package you selected, and optionally, its location.
+
+Example to link with {{EX: libdb.a}}, contained in {{EX: /usr/local/lib}}:
+
+E: LDBMLIB= -L/usr/local/lib -ldb
+
+H4: THREADS
+
+This option is normally set automatically in the {{EX: Make-platform}} file,
+based on the platform on which you are building. You do not normally
+need to set it. If you want to use a non-default threads package, you
+can specify the appropriate {{EX: -Ddefine}} to enable it here.
+
+H4: THREADSLIB
+
+This option is normally set automatically in the {{EX: Make-platform}} file,
+based on the platform on which you are building. You do not normally
+need to set it. If you have set {{EX: THREADS}} to a non-default threads
+package as described above, you can specify the appropriate
+ {{EX: -Ldirectory}} flag and {{EX: -llibname}} flag needed to link the package here.
+
+H4: PHONETIC
+
+This option controls the phonetic algorithm used by {{I: slapd}} when doing
+approximate searches. The default is to use the metaphone algorithm.
+You can have {{I: slapd}} use the soundex algorithm by setting this variable
+to {{EX: -DSOUNDEX}}.
+
+
+H3: Editing the {{EX: include/ldapconfig.h}} file
+
+In addition to setting the {{EX: LDAPHOST}} and {{EX: DEFAULT_BASE}} defines
+near the top of this file, there are some slapd-specific defines near the
+bottom of the file you may want to change. The defaults should be just
+fine, unless you have special needs.
+
+H4: SLAPD_DEFAULT_CONFIGFILE
+
+This define sets the location of the default slapd configuration file.
+Normally, it is set to {{EX: $(ETCDIR)/slapd.conf}}, where
+{{EX: ETCDIR}} comes from Make-common.
+
+H4: SLAPD_DEFAULT_SIZELIMIT
+
+This define sets the default size limit on the number of entries returned
+from a search. This option is configurable via the tailor file, but if you
+want to change the default, do it here.
+
+H4: SLAPD_DEFAULT_TIMELIMIT
+
+This define sets the default time limit for a search. This option is
+configurable via the tailor file, but if you want to change the default, do it
+here.
+
+H4: SLAPD_PIDFILE
+
+This define sets the location of the file to which slapd will write its
+process ID when it starts up.
+
+H4: SLAPD_ARGSFILE
+
+This define sets the location of the file to which slapd will write its
+argument vector when it starts up.
+
+H4: SLAPD_MONITOR_DN
+
+This define sets the distinguished name used to retrieve monitoring
+information from {{I: slapd}}. See section 7 for more details.
+
+H4: SLAPD_LDBM_MIN_MAXIDS
+
+This define is only relevant to the LDBM backend. It sets the minimum
+number of entry IDs that an index entry will contain before it becomes
+an allIDs entry. See Section 9.1 for more details.
+
+
+
+H2: Making the Software
+
+Once you have edited the {{EX: include/ldapconfig.h.edit}} file and the
+Make-common file (see the top level {{EX: README}} file in the distribution),
+you are ready to make the software. From the top level LDAP source
+directory, type
+
+E: make
+
+You should examine the output of this command carefully to make sure
+everything is built correctly. Note that this command builds the LDAP
+libraries and associated clients as well as slapd and slurpd.
+
+Note that the LDAP distribution can support making for multiple
+platforms from a single source tree. If you want to do this, consult the
+{{EX: INSTALL}} file in the top level distribution directory.
+
+
+
+H2: Installing the Software
+
+Once the software has been properly configured and successfully
+made, you are ready to install it. You will need to have write permission
+to the installation directories you specified in the {{EX: Make-common}} file.
+Typically, the installation is done as root. From the top level LDAP
+source directory, type
+
+E: make install
+
+You should examine the output of this command carefully to make sure
+everything is installed correctly. Slapd, slurpd, and their configuration
+files, {{EX: slapd.conf}}, {{EX: slapd.at.conf}}, and {{EX: slapd.oc.conf}}
+ will be installed in the {{EX: ETCDIR}} directory you specified
+in the {{EX: Make-common}} file.
+
+This command will install the entire LDAP distribution. If you only want
+to install slapd and slurpd, you could do something like this:
+
+E: (cd servers/slapd; make install)
+
+E: (cd servers/slurpd; make install)
+
+Note: The installation process installs configuration files as well as
+binaries. Existing configuration files are first moved to a name with a
+dash '-' appended, e.g., {{EX: slapd.conf}} is moved to {{EX: slapd.conf-}}.
+If you install things twice, however, you can lose your existing configuration
+files.
+
+
+PB:
+
+
--- /dev/null
+H1: Introduction to slapd and slurpd
+
+This document describes how to build, configure, and run the stand-alone
+LDAP daemon ({{I:slapd}}) and the stand-alone LDAP update replication
+daemon ({{I:slurpd}}). It is intended for newcomers and experienced
+administrators alike. This section provides a basic introduction to directory
+service, and the directory service provided by {{I:slapd}} in particular.
+
+
+
+H2: What is a directory service?
+
+A directory is like a database, but tends to contain more descriptive,
+attribute-based information. The information in a directory is generally read
+much more often than it is written. As a consequence, directories don't
+usually implement the complicated transaction or roll-back schemes regular
+databases use for doing high-volume complex updates. Directory updates
+are typically simple all-or-nothing changes, if they are allowed at all.
+Directories are tuned to give quick-response to high-volume lookup or
+search operations. They may have the ability to replicate information widely in
+order to increase availability and reliability, while reducing response time.
+When directory information is replicated, temporary inconsistencies between
+the replicas may be OK, as long as they get in sync eventually.
+
+There are many different ways to provide a directory service. Different
+methods allow different kinds of information to be stored in the directory,
+place different requirements on how that information can be referenced,
+queried and updated, how it is protected from unauthorized access, etc.
+Some directory services are {{I:local}}, providing service to a restricted
+context (e.g., the finger service on a single machine). Other services are
+global, providing service to a much broader context (e.g., the entire Internet).
+Global services are usually {{I:distributed}}, meaning that the data they contain
+is spread across many machines, all of which cooperate to provide the
+directory service. Typically a global service defines a uniform {{I:namespace}}
+which gives the same view of the data no matter where you are in relation to
+the data itself.
+
+
+
+H2: What is LDAP?
+
+{{I:Slapd}}'s model for directory service is based on a global directory model
+called LDAP, which stands for the Lightweight Directory Access Protocol.
+LDAP is a directory service protocol that runs over TCP/IP. The nitty-gritty
+details of LDAP are defined in RFC 1777 "The Lightweight Directory Access
+Protocol." This section gives an overview of LDAP from a user's perspective.
+
+{{I:What kind of information can be stored in the directory?}} The LDAP directory
+service model is based on {{I:entries}}. An entry is a collection of
+attributes that has a name, called a {{I:distinguished name}} (DN).
+The DN is used to refer to the entry unambiguously. Each of the
+entry's attributes has a {{I:type}} and one or
+more {{I:values}}.
+The types are typically mnemonic strings, like "{{EX:cn}}" for common
+name, or "{{EX:mail}}" for email address. The values depend on what type of
+attribute it is. For example, a {{EX:mail}} attribute might contain the value
+"{{EX:babs@umich.edu}}". A {{EX:jpegPhoto}} attribute would contain
+a photograph in binary JPEG/JFIF format.
+
+{{I:How is the information arranged?}} In LDAP, directory entries are arranged in
+a hierarchical tree-like structure that reflects political, geographic and/or
+organizational boundaries. Entries representing countries appear at the top
+of the tree. Below them are entries representing states or national
+organizations. Below them might be entries representing people,
+organizational units, printers, documents, or just about anything else you can
+think of. Figure 1 shows an example LDAP directory tree, which should help
+make things clear.
+
+
+!import "figure_1.gif"; align="center"; title="An example LDAP directory tree"
+FT: Figure 1: An example LDAP directory tree.
+
+
+In addition, LDAP allows you to control which attributes are required and
+allowed in an entry through the use of a special attribute called
+{{I:objectclass}}.
+The values of the {{I:objectclass}} attribute determine
+the {{I:schema}} rules the entry
+must obey.
+
+{{I:How is the information referenced?}} An entry is referenced by its
+distinguished name, which is constructed by taking the name of the entry
+itself (called the relative distinguished name, or RDN) and concatenating the
+names of its ancestor entries. For example, the entry for Barbara Jensen in
+the example above has an RDN of "{{EX:cn=Barbara J Jensen}}" and a DN of
+"{{EX:cn=Barbara J Jensen, o=U of M, c=US}}". The full DN format is described in
+RFC 1779, "A String Representation of Distinguished Names."
+
+{{I:How is the information accessed?}} LDAP defines operations for interrogating
+and updating the directory. Operations are provided for adding and deleting
+an entry from the directory, changing an existing entry, and changing the
+name of an entry. Most of the time, though, LDAP is used to search for
+information in the directory. The LDAP search operation allows some portion
+of the directory to be searched for entries that match some criteria specified
+by a search filter. Information can be requested from each entry that matches
+the criteria.
+
+For example, you might want to search the entire directory subtree below the
+University of Michigan for people with the name Barbara Jensen, retrieving
+the email address of each entry found. LDAP lets you do this easily. Or you
+might want to search the entries directly below the c=US entry for
+organizations with the string "Acme" in their name, and that have a fax
+number. LDAP lets you do this too. The next section describes in more detail
+what you can do with LDAP and how it might be useful to you.
+
+{{I:How is the information protected from unauthorized access?}} Some directory
+services provide no protection, allowing anyone to see the information. LDAP
+provides a method for a client to authenticate, or prove its identity to a
+directory server, paving the way for rich access control to protect the
+information the server contains.
+
+
+
+H2: How does LDAP work?
+
+LDAP directory service is based on a {{I:client-server}} model. One or more
+LDAP servers contain the data making up the LDAP directory tree. An LDAP
+client connects to an LDAP server and asks it a question. The server
+responds with the answer, or with a pointer to where the client can get more
+information (typically, another LDAP server). No matter which LDAP server a
+client connects to, it sees the same view of the directory; a name presented
+to one LDAP server references the same entry it would at another LDAP
+server. This is an important feature of a global directory service, like LDAP.
+
+
+
+
+H2: What is slapd and what can it do?
+
+{{I:Slapd}} is an LDAP directory server that runs on many different UNIX
+platforms. You can use it to provide a directory service of your very own.
+Your directory can contain pretty much anything you want to put in it. You
+can connect it to the global LDAP directory service, or run a service all by
+yourself. Some of slapd's more interesting features and capabilities include:
+
+{{B:Choice of databases}}: {{I:Slapd}} comes with three different backend
+databases you can choose from. They are LDBM, a high-performance disk-based
+database; SHELL, a database interface to arbitrary UNIX commands or shell
+scripts; and PASSWD, a simple password file database.
+
+{{B:Multiple database instances}}: {{I:Slapd}} can be configured to serve
+multiple databases at the same time. This means that a single {{I:slapd}}
+server can respond to requests for many logically different portions
+of the LDAP tree, using the same or different backend databases.
+
+{{B:Generic database API}}: If you require even more customization, {{I:slapd}}
+lets you write your own backend database easily. {{I:Slapd}}
+consists of two distinct parts: a front end that handles protocol
+communication with LDAP clients; and a backend that handles database
+operations. Because these two pieces communicate via a well-defined
+C API, you can write your own customized database backend to {{I:slapd}}.
+
+{{B:Access control}}: {{I:Slapd}} provides a rich and powerful access
+control facility, allowing you to control access to the information
+in your database(s). You can control access to entries based on
+LDAP authentication information, IP address, domain name and other criteria.
+
+{{B:Threads}}: {{I:Slapd}} is threaded for high performance. A
+single multi-threaded {{I:slapd}} process handles all incoming
+requests, reducing the amount of system overhead required. {{I:Slapd}}
+will automatically select the best thread support for your platform.
+
+{{B:Replication}}: {{I:Slapd}} can be configured to maintain replica
+copies of its database. This master/slave replication scheme is
+vital in high-volume environments where a single {{I:slapd}} just
+doesn't provide the necessary availability or reliability.
+
+{{B:Configuration}}: {{I:Slapd}} is highly configurable through a
+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.
+
+{{I:Slapd}} also has its limitations, of course. It does not
+currently handle aliases, which are part of the LDAP model. The
+main LDBM database backend does not handle range queries or negation
+queries very well. These features and more will be coming in a future release.
+
+
+
+H2: What about X.500?
+
+LDAP was originally developed as a front end to X.500, the OSI directory
+service. X.500 defines the Directory Access Protocol (DAP) for clients to
+use when contacting directory servers. DAP is a heavyweight protocol that
+runs over a full OSI stack and requires a significant amount of computing
+resources to run. LDAP runs directly over TCP and provides most of the
+functionality of DAP at a much lower cost.
+
+This use of LDAP makes it easy to access the X.500 directory, but still
+requires a full X.500 service to make data available to the many LDAP clients
+being developed. As with full X.500 DAP clients, a full X.500 server is no
+small piece of software to run.
+
+The stand-alone LDAP daemon, or {{I:slapd}}, is meant to remove much of the
+burden from the server side just as LDAP itself removed much of the burden
+from clients. If you are already running an X.500 service and you want to
+continue to do so, you can probably stop reading this guide, which is all
+about running LDAP via {{I:slapd}}, without running X.500. If you are not running
+X.500, want to stop running X.500, or have no immediate plans to run X.500,
+read on.
+
+It is possible to replicate data from a {{I:slapd}} directory
+server to an X.500 DSA, which allows your organization to make your
+data available as part of the global X.500 directory service on a
+"read-only" basis. This is discussed in section 11.6.
+
+Another way to make data in a {{I:slapd}} server available to the X.500
+community would be by using a X.500 DAP to LDAP gateway. At this time, no
+such software has been written (to the best of our knowledge), but hopefully
+some group will see fit towrite such a gateway.
+
+
+
+H2: What is slurpd and what can it do?
+
+{{I:Slurpd}} is a UNIX daemon that helps {{I:slapd}} provide
+replicated service. It is responsible for distributing changes made
+to the master {{I:slapd}} database out to the various {{I:slapd}}
+replicas. It frees {{I:slapd}} from having to worry that some
+replicas might be down or unreachable when a change comes through;
+{{I:slurpd}} handles retrying failed requests automatically.
+{{I:Slapd}} and {{I:slurpd}} communicate through a simple text
+file that is used to log changes.
+
+PB:
+
+
--- /dev/null
+# master.sdf
+# SDF master file for the OpenLDAP Administrator's guide
+#
+
+!include "preamble.sdf"
+
+!include "intro.sdf"
+!include "quickstart.sdf"
+!include "config.sdf"
+!include "install.sdf"
+!include "slapdconfig.sdf"
+!include "runningslapd.sdf"
+!include "monitoringslapd.sdf"
+!include "dbtools.sdf"
+!include "tuning.sdf"
+!include "referrals.sdf"
+!include "replication.sdf"
+
+
+
--- /dev/null
+H1: Monitoring Slapd
+
+Slapd supports a monitoring interface you can use to find out
+many useful bits of information about what slapd is currently
+doing, how many connections it has, how many threads are
+working, etc. You can access the monitor feature by doing a
+base object search of the SLAPD_MONITOR_DN from
+include/ldapconfig.h with any kind of valid filter (e.g.,
+"(objectclass=*)"). By default, this DN is set to "cn=monitor".
+You will get one entry returned to you, with the following
+attributes:
+
+E: version: slapd <version> (<date>)
+
+This attribute identifies the slapd server software by name,
+version, and build date, e.g., {{EX: slapd 3.3 (Thu May 21 14:19:03
+EDT 1996)}}
+
+E: threads: <integer>
+
+This attribute indicates the number of threads (operations)
+currently outstanding in slapd.
+
+E: connection: <fd> : <opentime> : <opsinitiated> :
+E: <opscompleted> : <binddn> : [ <rw> ]
+
+This multi-valued attribute summarizes information for each
+open connection. The information given is {{EX: <fd>}}, the file
+descriptor; {{EX: <opentime>}}, the time the connection was opened
+in UTC format; {{EX: <opsinitiated>}}, the number of operations
+initiated over the connection; {{EX: <opscompleted>}}, the number
+of operations completed over the connection; {{EX: <binddn>}}, the
+DN currently bound to the connection; and optionally {{EX: <rw>}},
+indicating whether the connection is currently blocked for
+read or write..
+
+E: currentconnections: <integer>
+
+The current number of connections.
+
+E: totalconnections: <integer>
+
+The total number of connections handled by slapd since it
+started.
+
+E: dtablesize: <integer>
+
+The size of slapd's file descriptor table.
+
+E: writewaiters: <integer>
+
+The number of threads blocked waiting to write data to a
+client.
+
+E: readwaiters: <integer>
+
+The number of threads blocked waiting to read data from a
+client.
+
+E: opsinitiated: <integer>
+
+The total number of operations initiated by slapd since it
+started.
+
+E: opscompleted: <integer>
+
+The total number of operations completed by slapd since it
+started.
+
+E: entriessent: <integer>
+
+The total number of entries sent to clients by slapd since it
+started.
+
+E: bytessent: <integer>
+
+The total number of bytes sent to clients by slapd since it
+started.
+
+E: currenttime: <UTC time>
+
+Slapd's idea of the current time.
+
+E: starttime: <integer>
+
+The time slapd was started.
+
+E: nbackends: <integer>
+
+The number of backends currently being served by slapd.
+
+E: concurrency: <integer>
+
+Under Solaris 2.x only, an indication of the current level of
+thread concurrency.
+
+Note that slapd takes a snapshot of this information and
+returns it to you. No attempt is made to ensure that the
+information is consistent (i.e., if an operation thread is
+modifying one of these things when the monitor thread is
+reading it, strange results could be returned).
+
+You should be able to use any LDAP client to retrieve this
+information. Here's how you might do it using the
+{{I: ldapsearch}}(1) client:
+
+E: ldapsearch -s base -b cn=monitor 'objectclass=*'
+
+PB:
+
+
+
--- /dev/null
+# file: guide.sdf
+#
+
+!define DOC_NAME "OpenLDAP Administrators Guide"
+!define DOC_AUTHOR "OpenLDAP"
+!define DOC_LOGO "LDAPwww.gif"
+!define DOC_LOF_TITLE "Figures"
+!define DOC_LOF
+!build_title
+
+
--- /dev/null
+
+H1: A Quick-Start Guide to Running slapd
+
+This section provides a quick step-by-step guide to building,
+installing and running {{I:slapd}}. It is intended to provide users with a
+simple and quick way to get started only. If you intend to run slapd
+seriously, you should read the rest of this guide.
+
+
+^ {{B:Get the software}}. {{I:Slapd}} is part of the OpenLDAP distribution, which
+you can retrieve using this URL:
+.
+.{{CMD[jump="ftp://ftp.openldap.org/pub/OpenLDAP/openldap-release.tgz"]ftp://ftp.openldap.org/pub/OpenLDAP/openldap-release.tgz}}
+.
+.If you are reading this guide, you have probably already done this.
+.
+
++ {{B:Untar the distribution}}. Pick a place for the LDAP source to live, cd
+there, and untar it. For example:
+.
+.{{EX: cd /usr/local/src}}
+.{{EX: gunzip -c openldap-release.tgz | tar xvfB -}}
+.{{EX: cd ldap}}
++{{B: Configure the software}}.
+.
+.You will have to edit two files to configure things for your site.
+.
+.{{EX: vi Make-common}}
+.{{EX:vi include/ldapconfig.h.edit}}
+.
+.Read the comments in Make-common and configure things
+.appropriately. If you have the Berkeley DB package installed, or the
+.GDBM package, you should set the LDBMBACKEND variable
+.accordingly. Otherwise, the defaults should be OK to get you started.
+.
+.In the include/ldapconfig.h.edit file, be sure to set the DEFAULT_BASE
+.and LDAPHOST variables to something appropriate for your site.
+.Other than that, the defaults should work OK.
+
+
++{{B:Install the software}}. From the top level LDAP source directory,
+type:
+.
+.{{EX: su}}
+.{{EX: make install}}
+.
+.Examine the output of this command carefully to ensure everything is
+.installed properly.
+.
+
+
++{{B:Make a configuration file}}. Create a file called myslapd.conf and
+.enter the following lines into it. See Section 5 for more details on this
+.file.
+.
+.{{EX:referral ldap://ldap.itd.umich.edu}}
+.{{EX:database ldbm}}
+.{{EX:suffix "o=<YOUR ORGANIZATION>, c=US"}}
+.{{EX:rootdn "cn=<YOUR NAME>, o=<YOUR ORGANIZATION>, c=US"}}
+.{{EX:rootpw secret}}
+.
+.Be sure to replace "<YOUR ORGANIZATION>" with the name of your
+.organization and "<YOUR NAME>" with your name. If you are not in
+.the US, replace "US" with your two-letter country code. The rootdn
+.and rootpw lines are only required if later you want to easily add or
+.modify entries via LDAP.
+.
+
+
++{{B:Create a database}}. This is a two-step process. Step A is to create
+.a file (we'll call it myldif) containing the entries you want your database
+.to contain. Use the following example as a guide, or see Section 7.3 for
+.more details.
+.
+.{{EX:dn: o=<YOUR ORGANIZATION>, c=US}}
+.{{EX:o: <YOUR ORGANIZATION>}}
+.{{EX:objectclass: organization}}
+.
+.{{EX:dn: cn=<YOUR NAME>, o=<YOUR ORGANIZATION>, c=US}}
+.{{EX:cn: <YOUR NAME>}}
+.{{EX:sn: <YOUR LAST NAME>}}
+.{{EX:mail: <YOUR EMAIL ADDRESS>}}
+.{{EX:objectclass: person}}
+.
+.You can include additional entries and attributes in this file if you want,
+.or add them later via LDAP.
+.
+.Step B is to run this file through a tool to create the slapd database.
+.
+.{{EX:$(ETCDIR)/ldif2ldbm -f myslapd.conf -i myldif}}
+.
+.Where myslapd.conf is the configuration file you made in step 6, and
+.myldif is the file you made in step 7A above. By default, the database
+.files will be created in /usr/tmp. You may specify an alternate directory
+.via the directory option in the slapd.conf file.
+.
+
+
++{{B:See if it works}}.You can use any LDAP client to do this, but our
+.example uses the ldapsearch tool.
+.
+.{{EX:ldapsearch -h 127.0.0.1 'objectclass=*'}}
+.
+.This command will search for and retrieve every entry in the database.
+.Note the use of single quotes around the filter, which prevents the "*"
+.from being interpreted by the shell.
+.
+.You are now ready to add more entries (e.g., using {{I:ldapadd}}(3) or
+.another LDAP client), experiment with various configuration options,
+.backend arrangements, etc. Note that by default, the {{I:slapd}} database
+.grants {{EX:READ}} access to everybody. So if you want to add or modify
+.entries over LDAP, you will have to bind as the rootdn specified in the
+.config file (see Section 5.2.2), or change the default access control
+.(see Section 5.3).
+.
+
+
+The following sections provide more detailed information on making,
+installing, and running slapd.
+
+PB:
+
+
--- /dev/null
+H1: Distributing {{I: slapd}} DATA
+
+For many sites, running one or more {{I: slapds}} that hold an
+entire subtree of data is sufficient. But sometimes it may be
+desirable to have one slapd refer to other {{I: slapds}} for a
+certain part of the tree. This can be accomplished by
+creating a referral entry in one {{I:slapd}}'s database pointing
+to another {{I: slapd}}. For those familiar with X.500, a {{I:slapd}}
+{{I: referral}} entry is similar to an X.500 knowledge reference.
+
+The referral entry acts as a mount point, glueing two slapd
+databases together. A referral entry has an {{I: objectclass}} of
+"referral" and is named by a {{I: ref}} attribute containing a URL
+pointing to the slapd holding the data below the mount
+point. This mechanism is very general and allows slapd
+databases that are not normally hierarchical to be grafted
+together.
+
+An example should help illustrate things. Suppose your
+company is running a slapd and just purchased a new
+company, also running a slapd. You can easily connect
+the two databases by creating an entry like this in your
+slapd's database.
+
+E: dn: ref="ldap://new.host/o=New Company,c=US", o=Your
+
+company, c=US
+
+E: objectclass: referral
+
+Now any subtree search that has this entry in its scope
+will return a referral to the new company, in addition to any
+entries matched in your database. Referral-aware clients
+will continue the search at the new company's server.
+
+A mechanism similar to this is used to support distributed
+indexing, described in Appendix C.
+
+
+PB:
+
--- /dev/null
+H1: Replication with slurpd
+
+In certain configurations, a single slapd instance may be
+insufficient to handle the number of clients requiring
+directory service via LDAP. It may become necessary to
+run more than one slapd instance. At the University of
+Michigan, for instance, there are four slapd servers, one
+master and three slaves. A DNS lookup of the name
+ldap.itd.umich.edu returns the IP addresses of those four
+servers, distributing the load among them. This
+master/slave arrangement provides a simple and effective
+way to increase capacity, availability and reliability.
+
+Slurpd provides the capability for a master slapd to
+propagate changes to slave slapd instances,
+implementing the master/slave replication scheme
+described above. Slurpd runs on the same host as the
+master slapd instance.
+
+
+
+H2: Overview
+
+Slurpd provides replication services "in band". That is, it
+uses the LDAP protocol to update a slave database from
+the master. Perhaps the easiest way to illustrate this is
+with an example. In this example, we trace the propagation
+of an LDAP modify operation from its initiation by the LDAP
+client to its distribution to the slave slapd instance.
+
+
+{{B: Sample replication scenario:}}
+
+* Step 1: An LDAP client starts up and connects to a slave
+slapd.
+
+* Step 2: The LDAP client submits an LDAP modify
+. operation to the slave slapd.
+
+* Step 3: The slave slapd returns a referral to the LDAP
+. client, which causes the client to send the modify
+. operation to the master slapd.
+
+* Step 4: The master slapd performs the modify operation,
+. writes out the change to its replication log file and returns
+. a success code to the client.
+
+* Step 5: The slurpd process notices that a new entry has
+. been appended to the replication log file, reads the
+. replication log entry, and sends the change to the slave
+. slapd via LDAP.
+
+* Step 6: The slave slapd performs the modify operation and
+. returns a success code to the slurpd process.
+
+Note: if the LDAP client happened to connect to the
+master slapd to begin with, Step 3 is omitted, but the rest
+of the scenario remains the same.
+
+
+
+H2: Replication Logs
+
+When slapd is configured to generate a replication logfile,
+it writes out a file in a format which is a variant of the LDIF
+format. The replication log gives the replication site(s), a
+timestamp, the DN of the entry being modified, and a series
+of lines which specify the changes to make. In the
+example below, "Barbara Jensen" has replaced a line of
+her multiLineDescription. The change is to be propagated
+to the slapd instance running on truelies.rs.itd.umich.edu.
+The lastModifiedBy and lastModified Time attributes are
+also propagated to the slave slapd.
+
+E: replica: truelies.rs.itd.umich.edu:389
+E: time: 809618633
+E: dn: cn=Barbara Jensen, ou=People, o=University of Michigan,c=US
+E: changetype: modify
+E: delete: multiLineDescription
+E: multiLineDescription: I enjoy sailing in my spare time
+E: -
+E: add: multiLineDescription
+E: multiLineDescription: A dreamer...
+E: -
+E: delete: lastModifiedBy
+E: -
+E: add: lastModifiedBy
+E: lastModifiedBy: cn=Barbara Jensen, ou=People, o=University of Michigan, c=US
+E: -
+E: delete: lastModifiedTime
+E: -
+E: add: lastModifiedTime
+E: lastModifiedTime: 950825073308Z
+E: -
+
+The modifications to {{EX: lastModifiedBy}} and {{EX: lastModifiedTime}}
+were initiated by the master {{I: slapd}}.
+
+
+
+H2: Command-Line Options
+
+Slurpd supports the following command-line options.
+
+E: -d <level> | ?
+
+This option sets the slurpd debug level to {{EX: <level>}}. When
+level is a `?' character, the various debugging levels are
+printed and slapd exits, regardless of any other options
+you give it. Current debugging levels (a subset of slapd's
+debugging levels) are
+
+
+E: 4 heavy trace debugging
+E: 64 configuration file processing
+E: 65535 enable all debugging
+
+Debugging levels are additive. That is, if you want heavy
+trace debugging and want to watch the config file being
+processed, you would set level to the sum of those two
+levels (in this case, 68).
+
+E: -f <filename>
+
+This option specifies an alternate slapd configuration file.
+Slurpd does not have its own configuration file. Instead, all
+configuration information is read from the slapd
+configuration file.
+
+E: -r <filename>
+
+This option specifies an alternate slapd replication log file.
+Under normal circumstances, slurpd reads the name of
+the slapd replication log file from the slapd configuration
+file. However, you can override this with the -r flag, to
+cause slurpd to process a different replication log file. See
+section 10.5, Advanced slurpd Operation, for a discussion
+of how you might use this option.
+
+E: -o
+
+Operate in "one-shot" mode. Under normal
+circumstances, when slurpd finishes processing a
+replication log, it remains active and periodically checks to
+see if new entries have been added to the replication log.
+In one-shot mode, by comparison, slurpd processes a
+replication log and exits immediately. If the -o option is
+given, the replication log file must be explicitly specified
+with the -r option
+
+E: -t <directory>
+
+Specify an alternate directory for slurpd's temporary
+copies of replication logs. The default location is /usr/tmp.
+
+E: -k <filename>
+
+When slurpd uses kerberos to authenticate to slave slapd
+instances, it needs to have an appropriate srvtab file for
+the remote slapd. This option allows you to specify an
+alternate filename containing kerberos keys for the remote
+slapd. The default filename is /etc/srvtab. You can also
+specify the srvtab file to use in the slapd configuration
+file's replica option. See the documentation on the srvtab
+directive in section 5.2.2, General Backend Options. A
+more complete discussion of using kerberos with slapd
+and slurpd may be found in Appendix D.
+
+
+
+H2: Configuring slurpd and a slave slapd instance
+
+To bring up a replica slapd instance, you must configure
+the master and slave slapd instances for replication, then
+shut down the master slapd so you can copy the
+database. Finally, you bring up the master slapd instance,
+the slave slapd instance, and the slurpd instance. These
+steps are detailed in the following sections. You can set
+up as many slave slapd instances as you wish.
+
+
+H3: Set up the master slapd
+
+Follow the procedures in Section 4, Building and Installing
+slapd. Be sure that the slapd instance is working properly
+before proceeding. Be sure to do the following in the
+master slapd configuration file.
+
+^ Add a replica directive for each replica. The binddn=
+. parameter should match the updatedn option in the
+. corresponding slave slapd configuration file, and should
+. name an entry with write permission to the slave database
+. (e.g., an entry listed as rootdn, or allowed access via
+. access directives in the slave slapd configuration file).
+
++ Add a replogfile directive, which tells slapd where to log
+. changes. This file will be read by slurpd.
+
+
+
+H3: Set up the slave slapd
+
+Install the slapd software on the host which is to be the
+slave slapd server. The configuration of the slave server
+should be identical to that of the master, with the following
+exceptions:
+
+^ Do not include a replica directive. While it is possible to
+. create "chains" of replicas, in most cases this is
+. inappropriate.
+
++ Do not include a replogfile directive.
+
++ Do include an updatedn line. The DN given should
+. match the DN given in the {{EX: binddn=}} parameter of the
+. corresponding {{EX: replica=}} directive in the master slapd
+. config file.
+
++ Make sure the DN given in the {{EX: updatedn}} directive has
+. permission to write the database (e.g., it is listed as rootdn
+. or is allowed access by one or more access directives).
+
+
+
+H3: Shut down the master slapd
+
+In order to ensure that the slave starts with an exact copy
+of the master's data, you must shut down the master
+slapd. Do this by sending the master slapd process an
+interrupt signal with {{EX: kill -TERM <pid>}}, where {{EX: <pid>}} is the
+process-id of the master slapd process.
+
+If you like, you may restart the master slapd in read-only
+mode while you are replicating the database. During this
+time, the master slapd will return an "unwilling to perform"
+error to clients that attempt to modify data.
+
+
+
+H3: Copy the master slapd's database to the slave
+
+Copy the master's database(s) to the slave. For an
+LDBM-based database, you must copy all index files as
+well as the "NEXTID" file. Index files will have a different
+suffix depending on the underlying database package
+used. The current possibilities are
+
+* {{EX: dbb}} Berkeley DB B-tree backend
+* {{EX: dbh}} Berkeley DB hash backend
+* {{EX: gdbm}} GNU DBM backend
+* {{EX: pag}} UNIX NBDM backend
+* {{EX: dir}} UNIX NBDM backend
+
+You should copy all files with such a suffix that are located
+in the index directory specified in your slapd config file.
+
+
+
+H3: Configure the master slapd for replication
+
+To configure slapd to generate a replication logfile, you
+add a "{{EX: replica}}" configuration option to the master slapd's
+config file. For example, if we wish to propagate changes
+to the slapd instance running on host
+truelies.rs.itd.umich.edu:
+
+E: replica host=truelies.rs.itd.umich.edu:389
+E: binddn="cn=Replicator, o=U of M, c=US"
+E: bindmethod=simple credentials=secret
+
+In this example, changes will be sent to port 389 (the
+standard LDAP port) on host truelies. The slurpd process
+will bind to the slave slapd as
+"cn=Replicator, o=U of M, c=US"
+using simple authentication with password "secret".
+Note that the entry given by the binddn= directive must
+exist in the slave slapd's database (or be the rootdn
+specified in the slapd config file) in order for the bind
+operation to succeed.
+
+
+
+H3: Restart the master slapd and start the slave slapd
+
+Restart the master slapd process. To check that it is
+generating replication logs, perform a modification of any
+entry in the database, and check that data has been
+written to the log file.
+
+
+
+H3: Start slurpd
+
+Start the slurpd process. Slurpd should immediately send
+the test modification you made to the slave slapd. Watch
+the slave slapd's logfile to be sure that the modification
+was sent.
+
+{{EX: slurpd -f <masterslapdconfigfile>}}
+
+
+
+H2: Advanced slurpd Operation
+
+H3: Replication errors
+
+When slurpd propagates a change to a slave slapd and
+receives an error return code, it writes the reason for the
+error and the replication record to a reject file. The reject
+file is located in the same directory with the per-replica
+replication logfile, and has the same name, but with the
+string ".rej" appended. For example, for a replica running
+on host truelies.rs.itd.umich.edu, port 389, the reject file, if it
+exists, will be named
+
+E: /usr/tmp/truelies.rs.itd.umich.edu:389.
+
+A sample rejection log entry follows:
+
+E: ERROR: No such attribute
+E: replica: truelies.rs.itd.umich.edu:389
+E: time: 809618633
+E: dn: cn=Barbara Jensen, ou=People, o=University of Michigan, c=US
+E: changetype: modify
+E: delete: multiLineDescription
+E: multiLineDescription: I enjoy sailing in my spare time
+E: -
+E: add: multiLineDescription
+E: multiLineDescription: A dreamer...
+E: -
+E: delete: lastModifiedBy
+E: -
+E: add: lastModifiedBy
+E: lastModifiedBy: cn=Barbara Jensen, ou=People, o=University of Michigan, c=US
+E: -
+E: delete: lastModifiedTime
+E: -
+E: add: lastModifiedTime
+E: lastModifiedTime: 950825073308Z
+E: -
+
+Note that this is precisely the same format as the original
+replication log entry, but with an ERROR line prepended to
+the entry.
+
+
+
+H3: {{I:Slurpd}}'s one-shot mode and reject files
+
+It is possible to use slurpd to process a rejection log with
+its "one-shot mode." In normal operation, slurpd watches
+for more replication records to be appended to the
+replication log file. In one-shot mode, by contrast, slurpd
+processes a single log file and exits. Slurpd ignores
+ERROR lines at the beginning of replication log entries, so
+it's not necessary to edit them out before feeding it the
+rejection log.
+
+To use one-shot mode, specify the name of the rejection
+log on the command line as the argument to the -r flag,
+and specify one-shot mode with the -o flag. For example,
+to process the rejection log file
+/usr/tmp/replog.truelies.rs.itd.umich.edu:389 and exit, use the
+command
+
+E: slurpd -r /usr/tmp/truelies.rs.itd.umich.edu:389 -o
+
+
+H2: Replication from a slapd directory server to an X.500 DSA
+
+In mixed environments where both X.500 DSAs and slapd
+are used, it may be desirable to replicate changes from a
+slapd directory server to an X.500 DSA. This section
+discusses issues involved with this method of replication,
+and describes the currently-available facilities.
+
+To propagate changes from a slapd directory server to an
+X.500 DSA, slurpd runs on the master slapd host, and
+sends changes to an ldapd which acts as a gateway to
+the X.500 DSA:
+
+!import "figure_1.gif"; align="center"; title="Replication from slapd to an X.500 DSA"
+FT: Figure 6: Replication from slapd to an X.500 DSA
+
+Note that the X.500 DSA must be a read-only copy. Since
+the replication is one-way, updates from DAP clients
+connecting to the X.500 DSA simply cannot be handled.
+
+A problem arises where attribute names differ between the
+slapd directory server and the X.500 DSA. At present,
+slapd and slurpd do not support selective replication of
+attributes, nor do they support translation of attribute
+names and values. For example, slurpd will attempt to
+update the "modifiersName" and "modifyTimeStamp"
+attributes on the slave it connects to. However, the X.500
+DSA may expect these attributes to be named
+"lastModifiedBy" and "lastModifiedTime".
+
+A solution to this attribute naming problem is to have the
+ldapd read oidtables that map "modifiersName" to the
+objectID (OID) for the "lastModifiedBy" attribute and
+"modifyTimeStamp" to the OID for the "lastModifiedTime"
+attribute. Since attribute names are carried as OIDs over
+DAP, this should perform the appropriate translation of
+attribute names.
+
+
--- /dev/null
+H1: Running slapd
+
+Slapd can be run in two different modes, stand-alone or from
+inetd(8). Stand-alone operation is recommended, especially if you
+are using the LDBM backend. This allows the backend to take
+advantage of caching and avoids concurrency problems with the
+LDBM index files. If you are running only a PASSWD or SHELL
+backend, running from inetd is an option. How to do this is
+described in the next section, after the command-line options and
+stand-alone daemon operation are described.
+
+
+
+H2: Command-Line Options
+
+{{I:Slapd}} supports the following command-line options.
+
+E: -d <level> | ?
+
+This option sets the slapd debug level to <level>. When level is a
+`?' character, the various debugging levels are printed and slapd
+exits, regardless of any other options you give it. Current
+debugging levels are
+
+E: 1 trace function calls
+E: 2 debug packet handling
+E: 4 heavy trace debugging
+E: 8 connection management
+E: 16 print out packets sent and received
+E: 32 search filter processing
+E: 64 configuration file processing
+E: 128 access control list processing
+E: 256 stats log connections/operations/results
+E: 512 stats log entries sent
+E: 1024 print communication with shell backends
+E: 2048 print entry parsing debugging
+E: 65535 enable all debugging
+
+Debugging levels are additive. That is, if you want to trace function
+calls and watch the config file being processed, you would set
+level to the sum of those two levels (in this case, 65). Consult
+{{EX: <ldap.h>}} for more details.
+
+Note: slapd must have been compiled with {{EX:-DLDAP_DEBUG}}
+defined for any debugging information beyond the two stats levels
+to be available.
+
+E: -f <filename>
+
+This option specifies an alternate configuration file for slapd.
+
+E: -i
+
+This option tells slapd that it is running from inetd instead of as a
+stand-alone server. See the next section on running slapd from
+inetd for more details.
+
+E: -p <port>
+
+This option specifies an alternate TCP port on which slapd should
+listen for connections. The default port is 389.
+
+
+
+H2: Running slapd as a Stand-Alone Daemon
+
+In general, slapd is run like this:
+
+E: $(ETCDIR)/slapd [<option>]*
+
+where ETCDIR has the value you gave in the Make-common file
+during the pre-build configuration, and <option> is one of the
+options described below. Unless you have specified a debugging
+level, slapd will automatically fork and detach itself from its
+controlling terminal and run in the background. Any of the options
+given above can be given to slapd to point it at a different
+configuration file, listen on another port, etc.
+
+To kill off slapd safely, you should give a command like this
+
+E: kill -TERM `cat $(ETCDIR)/slapd.pid`
+
+Killing slapd by a more drastic method may cause its LDBM
+databases to be corrupted, as it may need to flush various buffers
+before it exits. Note that slapd writes its pid to a file called
+{{EX: slapd.pid}} in the {{EX: ETCDIR}} you configured in
+{{EX: Make-common}}. You can change
+the location of this pid file by changing the {{EX: SLAPD_PIDFILE}}
+variable in {{EX: include/ldapconfig.h.edit}}.
+
+{{I: Slapd}} will also write its arguments to a file called
+{{EX: slapd.args}} in the {{EX: ETCDIR}} you configured
+in {{EX: Make-common}}. You can change the
+location of the args file by changing the {{EX: SLAPD_ARGSFILE}}
+variable in {{EX: include/ldapconfig.h.edit}}.
+
+
+
+H2: Running slapd from inetd
+
+First, make sure that running from {{I: inetd}}(8) is a good idea. If you
+are using the LDBM backend, it is not. If you are in a high-volume
+environment, the overhead of running from inetd also makes it a
+bad idea. Otherwise, you may proceed with the two steps
+necessary.
+
+Step 1 is to add a line like this to your {{EX: /etc/services}} file:
+
+E: ldap 389 # ldap directory service
+
+Step 2 is to add a line like this to your /etc/inetd.conf file:
+
+E: ldap stream tcp nowait nobody $(ETCDIR)/slapd slapd -i
+
+where {{EX: ETCDIR}} has the value you gave it in the
+{{EX: Make-common}} file
+during pre-build configuration. Finally, send inetd a HUP signal,
+and you should be all set.
+
+PB:
+
+
+
--- /dev/null
+H1: The {{I: slapd}} Configuration File
+
+Once the software has been built and installed, you are ready to configure it
+for use at your site. All slapd runtime configuration is accomplished through
+the {{EX: slapd.conf}} file, installed in the {{EX: ETCDIR}}
+directory you specified in the {{EX: Make-common}} file.
+
+An alternate configuration file can be specified via a
+command-line option to slapd or slurpd (see Sections 5 and 8,
+respectively). This section describes the general format of the config file,
+followed by a detailed description of each config file option.
+
+
+
+H2: Configuration File Format
+
+The {{EX: slapd.conf}} file consists of a series of global configuration options
+that apply to slapd as a whole (including all backends), followed by
+zero or more database backend definitions that contain information
+specific to a backend instance.
+
+Global options can be overridden in a backend (for options that
+appear more than once, the last appearance in the slapd.conf file is
+used). Blank lines and comment lines beginning with a `#' character
+are ignored. If a line begins with white space, it is considered a
+continuation of the previous line. The general format of slapd.conf is
+as follows:
+
+E: # comment - these options apply to every database
+E: <global config options>
+E: # first database definition & config options
+E: database <backend 1 type>
+E: <config options specific to backend 1>
+E: # second database definition & config options
+E: database <backend 2 type>
+E: <config options specific to backend 2>
+E: # subsequent database definitions & config options
+E: ...
+
+Configuration line arguments are separated by white space. If
+an argument contains white space, the argument should be
+enclosed in double quotes "like this". If an argument contains
+a double quote or a backslash character `\', the character
+should be preceded by a backslash character `\'.
+
+The distribution contains an example configuration file that will
+be installed in the {{EX: ETCDIR}} directory. Also provided are
+{{EX: slapd.at.conf}}, which contains many commonly used attribute
+definitions, and {{EX: slapd.oc.conf}}, which contains many commonly
+used object class definitions. These files can be included from
+the slapd configuration file (see below).
+
+
+
+H2: Configuration File Options
+
+This section separates the configuration file options into
+global and backend-specific categories, describing each
+option and its default value (if any), and giving an example of
+its use.
+
+
+
+H3: Global Options
+
+Options described in this section apply to all backends,
+unless specifically overridden in a backend definition. Option
+arguments that should be replaced by actual text are shown
+in brackets <>.
+
+
+H4: access to <what> [ by <who> <accesslevel> ]+
+
+This option grants access (specified by <accesslevel>) to a
+set of entries and/or attributes (specified by <what>) by one or
+more requesters (specified by <who>). See Section 5.3 on
+access control for more details and examples.
+
+
+H4: attribute <name> [<name2>] { bin | ces | cis | tel | dn }
+
+This option associates a syntax with an attribute name. By
+default, an attribute is assumed to have syntax cis. An
+optional alternate name can be given for an attribute. The
+possible syntaxes and their meanings are
+
+* {{EX: bin}} binary
+* {{EX: ces}} case exact string (case must match during comparisons)
+* {{EX: cis}} case ignore string (case is ignored during comparisons)
+* {{EX: tel}} telephone number string (like cis but blanks and dashes ` '
+are ignored during comparisons)
+* {{EX: dn}} distinguished name
+
+
+H4: defaultaccess { none | compare | search | read | write }
+
+This option specifies the default access to grant requesters
+not matched by any other access line (see Section 5.3). Note
+that an access level implies all lesser access levels (e.g.,
+write access implies read, search and compare).
+
+\Default:
+
+E: defaultaccess read
+
+H4: include <filename>
+
+This option specifies that slapd should read additional
+configuration information from the given file before continuing
+with the next line of the current file. The included file should
+follow the normal slapd config file format.
+
+Note: You should be careful when using this option - there is
+no small limit on the number of nested include options, and no
+loop detection is done.
+
+H4: loglevel <integer>
+
+This option specifies the level at which debugging statements
+and operation statistics should be syslogged (currently
+logged to the syslogd(8) LOG_LOCAL4 facility). You must
+have compiled slapd with DLDAP_DEBUG for this to work
+(except for the two stats levels, which are always enabled).
+Log levels are additive. To display what numbers correspond
+to what kind of debugging, invoke slapd with the ? flag or
+consult the table below. The possible values for <integer> are:
+
+*1 trace function calls
+*2 debug packet handling
+*4 heavy trace debugging
+*8 connection management
+*16 print out packets sent and received
+*32 search filter processing
+*64 configuration file processing
+*128 access control list processing
+*256 stats log connections/operations/results
+*512 stats log entries sent
+*1024 print communication with shell backends
+*2048 print entry parsing debugging
+
+\Example:
+
+E: loglevel 255
+
+This will cause lots and lots of debugging information to be
+syslogged.
+
+\Default:
+
+E: loglevel 256
+
+H4: objectclass <name> [ requires <attrs> ] [ allows <attrs> ]
+
+This option defines the schema rules for the given object
+class. Used in conjunction with the schemacheck option. See
+Section 5.4 for more details.
+
+H4: referral <url>
+
+This option specifies the referral to pass back when slapd
+cannot find a local database to handle a request.
+
+\Example:
+
+E: referral ldap://ldap.itd.umich.edu
+
+This will refer non-local queries to the LDAP server at the
+University of Michigan. Smart LDAP clients can re-ask their
+query at that server, but note that most of these clients are
+only going to know how to handle simple LDAP URLs that
+contain a host part and optionally a distinguished name part.
+
+H4: schemacheck { on | off }
+
+This option turns schema checking on or off. If schema
+checking is on, entries added or modified will be checked to
+ensure they obey the schema rules implied by their object
+class(es) as defined by the corresponding objectclass
+option(s). If schema checking is off this check is not done.
+
+\Default:
+
+E: schemacheck off
+
+H4: sizelimit <integer>
+
+This option specifies the maximum number of entries to return
+from a search operation.
+
+\Default:
+
+E: sizelimit 500
+
+
+H4: srvtab <filename>
+
+This option specifies the srvtab file in which slapd can find the
+kerberos keys necessary for authenticating clients using
+kerberos. This option is only meaningful if you are using
+kerberos authentication, which must be enabled at compile
+time by including the appropriate definitions in the
+{{EX: Make-common}} file.
+
+\Default:
+
+E: srvtab /etc/srvtab
+
+H4: timelimit <integer>
+
+This option specifies the maximum number of seconds (in real
+time) slapd will spend answering a search request. If a
+request is not finished in this time, a result indicating an
+exceeded timelimit will be returned.
+
+\Default:
+
+E: timelimit 3600
+
+
+
+H3: General Backend Options
+
+Options in this section only apply to the backend in which
+they are defined. They are supported by every type of
+backend.
+
+H4: database <databasetype>
+
+This option marks the beginning of a new database instance
+definition. <databasetype> should be one of ldbm, shell, or
+passwd, depending on which backend will serve the
+database.
+
+\Example:
+
+E: database ldbm
+
+This marks the beginning of a new LDBM backend database
+instance definition.
+
+H4: lastmod { on | off }
+
+This option controls whether slapd will automatically maintain
+the modifiersName, modifyTimestamp, creatorsName, and
+createTimestamp attributes for entries.
+
+\Default:
+
+E: lastmod off
+
+H4: readonly { on | off }
+
+This option puts the database into "read-only" mode. Any
+attempts to modify the database will return an "unwilling to
+perform" error.
+
+\Default:
+
+E: readonly off
+
+H4: replica
+E: replica host=<hostname>[:<port>]
+E: "binddn=<DN>"
+E: bindmethod={ simple | kerberos }
+E: \[credentials=<password>]
+E: \[srvtab=<filename>]
+
+This option specifies a replication site for this database. The
+{{EX: host=}} parameter specifies a host and optionally a port where
+the slave slapd instance can be found. Either a domain name
+or IP address may be used for <hostname>. If <port> is not
+given, the standard LDAP port number (389) is used.
+
+The {{EX: binddn=}} parameter gives the DN to bind as for updates to
+the slave slapd. It should be a DN which has read/write
+access to the slave slapd's database, typically given as a
+"rootdn" in the slave's config file. It must also match the
+updatedn option in the slave slapd's config file. Since DNs are
+likely to contain embedded spaces, the entire "{{EX: binddn=<DN>}}"
+string should be enclosed in quotes.
+
+{{EX: bindmethod}} is either simple or kerberos, depending on
+whether simple password-based authentication or kerberos
+authentication is to be used when connecting to the slave
+slapd. Simple authentication requires a valid password be
+given. Kerberos authentication requires a valid srvtab file.
+
+The {{EX: credentials=}} parameter, which is only required if using
+simple authentication, gives the password for binddn on the
+slave slapd.
+
+The {{EX: srvtab=}} parameter, which is only required if using
+kerberos, specifies the filename which holds the kerberos key
+for the slave slapd. If omitted, {{EX: /etc/srvtab}} is used.
+
+See Section 10 for more details on replication.
+
+H4: replogfile <filename>
+
+This option specifies the name of the replication log file to
+which slapd will log changes. The replication log is typically
+written by slapd and read by slurpd. Normally, this option is
+only used if slurpd is being used to replicate the database.
+However, you can also use it to generate a transaction log, if
+slurpd is not running. In this case, you will need to periodically
+truncate the file, since it will grow indefinitely otherwise.
+
+See Section 10 for more details on replication.
+
+H4: rootdn <dn>
+
+This option specifies the DN of an entry that is not subject to
+access control or administrative limit restrictions for
+operations on this database.
+
+\Example:
+
+E: rootdn "cn=Manager, o=U of M, c=US"
+
+H4: rootkrbname <kerberosname>
+
+This option specifies a kerberos name for the DN given above
+that will always work, regardless of whether an entry with the
+given DN exists or has a {{EX: krbName}} attribute. This option is
+useful when creating a database and also when using slurpd
+to provide replication service (see Section 10).
+
+\Example:
+
+E: rootkrbname admin@umich.edu
+
+H4: rootpw <password>
+
+This option specifies a password for the DN given above that
+will always work, regardless of whether an entry with the given
+DN exists or has a password. This option is useful when
+creating a database and also when using slurpd to provide
+replication service (see Section 10).
+
+\Example:
+
+E: rootpw secret
+
+H4: suffix <dn suffix>
+
+This option specifies the DN suffix of queries that will be
+passed to this backend database. Multiple suffix lines can be
+given, and at least one is required for each database
+definition.
+
+\Example:
+
+E: suffix "o=University of Michigan, c=US"
+
+Queries with a DN ending in "o=University of Michigan, c=US"
+will be passed to this backend.
+
+Note: when the backend to pass a query to is selected, slapd
+looks at the suffix line(s) in each database definition in the
+order they appear in the file. Thus, if one database suffix is a
+prefix of another, it must appear after it in the config file.
+
+H4: updatedn <dn>
+
+This option is only applicable in a slave slapd. It specifies the
+DN allowed to make changes to the replica (typically, this is
+the DN slurpd binds as when making changes to the replica).
+
+
+
+H3: LDBM Backend-Specific Options
+
+Options 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.
+
+H4: cachesize <integer>
+
+This option specifies the size in entries of the in-memory
+cache maintained by the LDBM backend database instance.
+
+\Default:
+
+E: cachesize 1000
+
+
+H4: dbcachesize <integer>
+
+This option specifies the size in bytes of the in-memory cache
+associated with each open index file. If not supported by the
+underlying database method, this option is ignored without
+comment. Increasing this number uses more memory but can
+cause a dramatic performance increase, especially during
+modifies or when building indexes.
+
+\Default:
+
+E: dbcachesize 100000
+
+
+H4: directory <directory>
+
+This option specifies the directory where the LDBM files
+containing the database and associated indexes live.
+
+\Default:
+
+E: directory /usr/tmp
+
+
+H4: index {<attrlist> | default} [pres,eq,approx,sub,none]
+
+This option specifies the indexes to maintain for the given
+attribute. If only an <attrlist> is given, all possible indexes are
+maintained.
+
+\Example:
+
+E: index cn
+
+E: index sn,uid eq,sub,approx
+
+E: index default none
+
+This example causes all indexes to be maintained for the cn
+attribute; equality, substring, and approximate indexes for the
+sn and uid attributes; and no indexes for all other attributes.
+
+
+H4: mode <integer>
+
+This option specifies the file protection mode that newly
+created database index files should have.
+
+\Default:
+
+E: mode 0600
+
+
+
+H3: Shell Backend-Specific Options
+
+E: bind <pathname>
+
+E: unbind <pathname>
+
+E: search <pathname>
+
+E: compare <pathname>
+
+E: modify <pathname>
+
+E: modrdn <pathname>
+
+E: add <pathname>
+
+E: delete <pathname>
+
+E: abandon <pathname>
+
+These options specify the pathname of the command to
+execute in response to the given LDAP operation. The
+command given should understand and follow the input/output
+conventions described in Appendix B.
+
+\Example:
+
+E: search /usr/local/bin/search.sh
+
+Note that you need only supply those commands you want the
+backend to handle. Operations for which a command is not
+supplied will be refused with an "unwilling to perform" error.
+
+
+
+H3: Password Backend-Specific Options
+
+Options in this category only apply to the PASSWD backend
+database. That is, they must follow a "database passwd" line
+and come before any other "database" line.
+
+H4: file <filename>
+
+This option specifies an alternate passwd file to use.
+
+\Default:
+
+E: file /etc/passwd
+
+
+
+H2: Access Control
+
+Access to slapd entries and attributes is controlled by the
+access configuration file directive. The general form of an
+access line is:
+
+E: <access directive> ::= access to <what>
+E: [ by <who> <access> ]+
+E: <what> ::= * | [ dn=<regex> ] [ filter=<ldapfilter> ]
+E: [ attrs=<attrlist> ]
+E: <who> ::= * | self | dn=<regex> | addr=<regex> |
+E: domain=<regex> | dnattr=<dn attribute>
+E: <access> ::= [self]none | [self]compare | [self]search
+E: | [self]read | [self]write
+
+where the <what> part selects the entries and/or attributes to
+which the access applies, the <who> part specifies which
+entities are granted access, and the <access> part specifies
+the access granted. Multiple <who> <access> pairs are
+supported, allowing many entities to be granted different
+access to the same set of entries and attributes.
+
+
+H3: What to control access to
+
+The <what> part of an access specification determines the
+entries and attributes to which the access control applies.
+Entries can be selected in two ways: by a regular expression
+matching the entry's distinguished name:
+
+E: dn=<regular expression>
+
+Note: The DN pattern specified should be "normalized",
+meaning that there should be no extra spaces, and commas
+should be used to separate components. An example
+normalized DN is "cn=Babs Jensen,o=University of
+Michigan,c=US". An example of a non-normalized DN is
+"cn=Babs Jensen; o=University of Michigan, c=US".
+
+Or, entries may be selected by a filter matching some
+attribute(s) in the entry:
+
+E: filter=<ldap filter>
+
+where <ldap filter> is a string representation of an LDAP
+search filter, as described in RFC 1588. The special entry
+selector "*" is used to select any entry, and is a convenient
+shorthand for the equivalent "dn=.*" selector.
+
+Attributes within an entry are selected by including a
+comma-separated list of attribute names in the <what>
+selector:
+
+E: attrs=<attribute list>
+
+Access to the entry itself must be granted or denied using the
+special attribute name "entry". Note that giving access to an
+attribute is not enough; access to the entry itself through the
+"entry" attribute is also required. The complete examples at
+the end of this section should help clear things up.
+
+
+
+H2: Who to grant access to
+
+The <who> part identifies the entity or entities being granted
+access. Note that access is granted to "entities" not "entries."
+Entities can be specified by the special "*" identifier, matching
+any entry, the keyword "self" matching the entry protected by
+the access, or by a regular expression matching an entry's
+distinguished name:
+
+E: dn=<regular expression>
+
+Note: The DN pattern specified should be "normalized",
+meaning that there should be no extra spaces, and commas
+should be used to separate components.
+
+Or entities can be specified by a regular expression matching
+the client's IP address or domain name:
+
+E: addr=<regular expression>
+E: domain=<regular expression>
+
+or by an entry listed in a DN-valued attribute in the entry to
+which the access applies:
+
+E: dnattr=<dn-valued attribute name>
+
+The dnattr specification is used to give access to an entry
+whose DN is listed in an attribute of the entry (e.g., give
+access to a group entry to whoever is listed as the owner of
+the group entry).
+
+
+
+H3: The access to grant
+
+
+The kind of <access> granted can be one of the following:
+
+E: none | compare | search | read | write
+
+Note that each level implies all lower levels of access. So, for
+example, granting someone write access to an entry also
+grants them read, search, and compare access.
+
+
+
+H3: Access Control Evaluation
+
+When evaluating whether some requester should be given
+access to an entry and/or attribute, slapd compares the entry
+and/or attribute to the {{EX: <what>}} selectors given in the
+configuration file. Access directives local to the current
+database are examined first, followed by global access
+directives. Within this priority, access directives are
+examined in the order in which they appear in the config file.
+Slapd stops with the first {{EX: <what>}} selector that matches the
+entry and/or attribute. The corresponding access directive is
+the one slapd will use to evaluate access.
+
+Next, slapd compares the entity requesting access to the
+{{EX: <who>}} selectors within the access directive selected above,
+in the order in which they appear. It stops with the first {{EX: <who>}}
+selector that matches the requester. This determines the
+access the entity requesting access has to the entry and/or
+attribute.
+
+Finally, slapd compares the access granted in the selected
+{{EX: <access>}} clause to the access requested by the client. If it
+allows greater or equal access, access is granted. Otherwise,
+access is denied.
+
+The order of evaluation of access directives makes their
+placement in the configuration file important. If one access
+directive is more specific than another in terms of the entries
+it selects, it should appear first in the config file. Similarly, if
+one {{EX: <who>}} selector is more specific than another it should
+come first in the access directive. The access control
+examples given below should help make this clear.
+
+
+
+H3: Access Control Examples
+
+
+
+The access control facility described above is quite powerful.
+This section shows some examples of its use. First, some
+simple examples:
+
+E: access to * by * read
+
+This access directive grants read access to everyone. If it
+appears alone it is the same as the following defaultaccess
+line.
+
+E: defaultaccess read
+
+The following example shows the use of a regular expression
+to select the entries by DN in two access directives where
+ordering is significant.
+
+E: access to dn=".*, o=U of M, c=US"
+E: by * search
+E: access to dn=".*, c=US"
+E: by * read
+
+Read access is granted to entries under the c=US subtree,
+except for those entries under the "o=University of Michigan,
+c=US" subtree, to which search access is granted. If the
+order of these access directives was reversed, the
+U-M-specific directive would never be matched, since all
+U-M entries are also c=US entries.
+
+The next example again shows the importance of ordering,
+both of the access directives and the "by" clauses. It also
+shows the use of an attribute selector to grant access to a
+specific attribute and various <who> selectors.
+
+E:access to dn=".*, o=U of M, c=US" attr=homePhone
+E: by self write
+E: by dn=".*, o=U of M, c=US" search
+E: by domain=.*\.umich\.edu read
+E: by * compare
+E:access to dn=".*, o=U of M, c=US"
+E: by self write
+E: by dn=".*, o=U of M, c=US" search
+E: by * none
+
+This example applies to entries in the "o=U of M, c=US"
+subtree. To all attributes except homePhone, the entry itself
+can write them, other U-M entries can search by them,
+anybody else has no access. The homePhone attribute is
+writable by the entry, searchable by other U-M entries,
+readable by clients connecting from somewhere in the
+umich.edu domain, and comparable by everybody else.
+
+Sometimes it is useful to permit a particular DN to add or
+remove itself from an attribute. For example, if you would like to
+create a group and allow people too add and remove only
+their own DN from the member attribute, you could accomplish
+it with an access directive like this:
+
+E: access to attr=member,entry
+E: by dnattr=member selfwrite
+
+The dnattr {{EX: <who>}} selector says that the access applies to
+entries listed in the member attribute. The selfwrite access
+selector says that such members can only add or delete their
+own DN from the attribute, not other values. The addition of
+the entry attribute is required because access to the entry is
+required to access any of the entry's attributes.
+
+Note that the attr=member construct in the {{EX: <what>}} clause is a
+shorthand for the clause "dn=* attr=member" (i.e., it matches
+the member attribute in all entries).
+
+
+
+H2: Schema Enforcement
+
+
+
+The {{EX: objectclass}} and schemacheck configuration file options
+can be used to enforce schema rules on entries in the
+directory. The schema rules are defined by one or more
+objectclass lines, and enforcement is turned on or off via the
+schemacheck option. The format of an {{EX: objectclass}} line is:
+
+E: objectclass <name>
+E: [ requires <attrs> ]
+E: [ allows <attrs> ]
+
+This option defines the schema rules for the object class
+given by {{EX: <name>}}. Schema rules consist of the attributes the
+entry is required to have (given by the requires {{EX: <attrs>}}
+clause) and those attributes that it may optionally have (given
+by the allows {{EX: <attrs>}} clause). In both clauses, {{EX: <attrs>}} is a
+comma-separated list of attribute names.
+
+Note that object class inheritance (that is, defining one object
+class in terms of another) is not supported directly. All of an
+object class's required and allowed attributes must be listed
+in the objectclass definition.
+
+For example, to define an objectclass called myPerson, you
+might include a definition like this:
+
+E: objectclass myperson
+E: requires cn, sn, objectclass
+E: allows mail, phone, fax
+
+To then enforce this rule (i.e., to make sure an entry with an
+objectclass of myperson contains the cn, sn and objectclass
+attributes, and that it contains no other attributes besides
+mail, phone, and fax), turn on schema checking with a line like
+this:
+
+E: schemacheck on
+
+
+
+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 X.500 tree; both are LDBM database
+instances. The line numbers shown are provided for
+reference only and are not included in the actual file. First, the
+global configuration section:
+
+E: 1. # example config file - global configuration section
+E: 2. include /usr/local/etc/slapd.at.conf
+E: 3. include /usr/local/etc/slapd.oc.conf
+E: 4. schemacheck on
+E: 5. referral ldap://ldap.itd.umich.edu
+
+Line 1 is a comment. Lines 2 and 3 include other config files
+containing attribute and object class definitions, respectively.
+Line 4 turns on schema checking. The {{EX: referral}} option on line 5
+means that queries not local to one of the databases defined
+below will be referred to the LDAP server running on the
+standard port (389) at the host {{EX: ldap.itd.umich.edu}}.
+
+The next section of the configuration file defines an LDBM
+backend that will handle queries for things in the
+"o=University of Michigan, c=US" portion of the tree. The
+database is to be replicated to two slave slapds, one on
+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: 1. # ldbm definition for the U-M database
+E: 2. database ldbm
+E: 3. suffix "o=University of Michigan, c=US"
+E: 4. directory /usr/local/ldbm-umich
+E: 6. rootdn "cn=Manager, o=University of Michigan, c=US"
+E: 7. rootpw secret
+E: 8. replogfile /usr/local/ldbm-umich/slapd.replog
+E: 9. replica host=truelies.rs.itd.umich.edu:389
+E: 10. binddn="cn=Replicator, o=U of M, c=US"
+E: 11. bindmethod=simple credentials=secret
+E: 12.replica host=judgmentday.rs.itd.umich.edu
+E: 13. binddn="cn=Replicator, o=U of M, c=US"
+E: 14. bindmethod=kerberos
+E: 15. srvtab=/etc/srvtab.judgmentday
+E: 16.# ldbm indexed attribute definitions
+E: 17.index cn,sn,uid pres,eq,approx,sub
+E: 18.index objectclass pres,eq
+E: 19.index default none
+E: 20.# ldbm access control definitions
+E: 21.defaultaccess read
+E: 22.access to attr=userpassword
+E: 23. by self write
+E: 24. by dn="cn=Admin, o=University of Michigan, c=US" write
+E: 25. by * compare
+
+Line 1 is a comment. The start of the database definition is
+marked by the database keyword on line 2. Line 3 specifies
+the DN suffix for queries to pass to this database. Line 4
+specifies the directory in which the database files will live
+
+Lines 6 and 7 identify the database "super user" entry and
+associated password. This entry is not subject to access
+control or size or time limit restrictions.
+
+Lines 8 through 15 are for replication. Line 8 specifies the
+replication log file (where changes to the database are logged
+\- this file is written by slapd and read by slurpd). Lines 9
+through 11 specify the hostname and port for a replicated
+host, the DN to bind as when performing updates, the bind
+method (simple) and the credentials (password) for the
+binddn. Lines 12 through 15 specify a second replication site,
+using kerberos instead of simple authentication. See Section
+10 on slurpd for more information on these options.
+
+Lines 16 through 19 indicate the indexes to maintain for
+various attributes. The default is not to maintain any indexes
+(line 19).
+
+Lines 20 through 25 specify access control for entries in the
+database. For all entries, the {{EX: userPassword}} attribute is
+writable by the entry and the "admin" entry, comparable by
+everyone else. All other attributes allow read access by
+default (line 21). Note that the special "entry" attribute is not
+required in the access directive beginning on line 22. This is
+because the default access is read.
+
+The next section of the example configuration file defines
+another LDBM database. This one handles queries involving
+the "o="Babs, Inc.", c=US" subtree.
+
+E: 1. # ldbm definition for Babs, Inc. database
+E: 2. database ldbm
+E: 3. suffix "o=\"Babs, Inc.\", c=US"
+E: 4. directory /usr/local/ldbm-babs
+E: 5. rootdn "cn=Babs, o=\"Babs, Inc.\", c=US"
+E: 6. index default
+
+Note the use of `\' to escape the quotes necessary in the
+distinguished names given on lines 3 and 5. By default, all
+indexes are maintained for every attribute in an entry.
+
+
+PB:
+
+
--- /dev/null
+H1: Performance 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
+information in slapd. Each entry is assigned a unique ID, used to
+refer to the entry in the indexes. A search for entries with a
+surname of "Jensen", for example, would look up the index entry
+"=JENSEN" in the surname index. The data returned is a list of
+IDs of entries having that value for the surname attribute. We
+have found several things to be useful in improving the
+performance of this indexing scheme, especially on modify
+operations.
+
+
+
+H2: The allIDs threshold
+
+Some index entries become so large as to be useless. For
+example, if every entry in your database is a person entry, the
+"=PERSON" index entry in the objectclass index contains every
+entry. This returns very little useful information, and can cause
+significant delays, especially on updates. To alleviate this
+problem, we have introduced the idea of an allIDs index entry.
+
+The allIDs entry stands for a real index entry containing the IDs
+of every entry in the database, but it takes up very little space,
+never needs updating, and can be manipulated quickly and
+efficiently. The trade-off is that it does not prune the set of
+candidate entries at all during a search. This must be done
+using other, more "high-powered" index entries.
+
+You can set the minimum number of IDs that an index entry may
+contain before it turns into an allIDs block by changing the
+{{EX: SLAPD_LDBM_MIN_MAXIDS}} variable in the
+{{EX: include/ldapconfig.h}} file. The actual number is determined at
+runtime by the LDBM backend, depending on the block size of
+the underlying device (i.e., the number you provide is rounded up
+to the nearest multiple of a block size).
+
+
+
+H2: The entry cache
+
+The LDBM backend can be configured to keep a cache of
+entries in memory. Since the LDBM database spends much of its
+time reading entries from the id2entry file into memory, this cache
+can greatly speed performance. The trade-off is that the cache
+uses some extra memory. The default cache size is 1000
+entries. See the discussion of the cachesize option in Section
+5.2.3 on LDBM configuration.
+
+
+
+H2: The DB cache
+
+The LDBM backend uses a number of disk-based index files. If
+the underlying hash or B-tree package supports in-memory
+caching of these files, performance can be greatly improved,
+especially on modifies. The size of this in-memory file cache is
+given by the dbcachesize option, discussed in more detail in
+section 5.2.3 on LDBM configuration. The default {{EX: dbcachesize}} is
+100K.
+
+
+
+H2: Maintain the right indices
+
+Finally, one of the best performance tune-ups you can do is to
+make sure you are maintaining the right indices. Too few indices
+can lead to poor search performance. Too many indices can
+lead to poor update performance. For example, the LDBM
+backend would be perfectly happy to maintain substring and
+approximate indices for the {{EX: objectclass attribute}}, but this would
+not be useful and would just slow down update operations. If
+your database has many entries and is handling queries for
+substring equality on the surname attribute, you should make
+sure to maintain a surname substring index so these queries are
+answered quickly.
+
+So, take a look at the index lines in your slapd configuration file to
+ensure that only those indices that make sense and are needed
+are being maintained.
+
+PB:
+
projects / openldap / commitdiff
