# $OpenLDAP$ # Copyright 1999-2000, The OpenLDAP Foundation, All Rights Reserved. # COPYING RESTRICTIONS APPLY, see COPYRIGHT. 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). This method works for database types which support updates. The second method of database creation is to do it off-line using special utilities provided with slapd. 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. Note that not all database types support these utilitites. H2: Creating a database over LDAP With this method, you use the LDAP client of your choice (e.g., the ldapadd(1)) 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: > suffix 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 > suffix "dc=example, dc=com" You should be sure to specify a directory where the index files should be created: > directory For example: > directory /usr/local/var/openldap-ldbm You need to create this directory with appropriate permissions such that slapd can write to it. You need to make it so you can connect to slapd as directory user with permission to add entries. You can configure the directory to support a special {{super-user}} or {{root}} user just for this purpose. This is done through the following two options in the database definition: > rootdn > rootpw For example: > rootdn "cn=Manager, dc=example, dc=com" > rootpw secret These options specify a DN and password that can be used to authenticate as the {{super-user}} 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: > index { | 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. > index cn,sn,uid > index objectclass pres,eq 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 organizational entry followed by a Postmaster entry using the {{I:ldapadd}} tool, you could create an {{TERM:LDIF}} file called {{EX:entries.ldif}} with the contents: > dc=example, dc=com > objectClass=dcObject > objectClass=organization > dc=example > o=Example Corporation > description=The Example Corporation > > cn=Postmaster, dc=example, dc=com > objectClass=organizationalRole > cn=Postmaster > description=OpenLDAP Postmaster and then use a command like this to actually create the entry: > ldapadd -f entries.ldif -x -D "cn=Manager,dc=example,dc=com" -w secret The above command assumes settings provided in the above examples. H2: Creating a database off-line The second method of database creation is to do it off-line, using the slapd database 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. For database types which support the tools, they produce the database files directly (otherwise you must use the on-line method above). There are several important configuration options you will want to be sure and set in the config file database definition first: > suffix 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 > suffix "dc=example, dc=com" You should be sure to specify a directory where the index files should be created: > directory For example: > directory /usr/local/var/openldap-ldbm Finally, you need to specify which indexes you want to build. This is done by one or more index options. > index { | default} [pres,eq,approx,sub,none] For example: > index cn,sn,uid pres,eq,approx > index objectClass eq This would create presence, equality and approximate indexes for the cn, sn, and uid attributes and an equality index for the objectClass attribute. See the configuration file section for more information on this option. H3: The {{EX:slapadd}} program Once you've configured things to your liking, you create the primary database and associated indexes by running the {{slapadd}}(8) program: > slapadd -l -f > [-d ] [-n |-b ] The arguments have the following meanings: > -l Specifies the LDIF input file containing the entries to add in text form (described below in Section 8.3). > -f Specifies the slapd configuration file that tells where to create the indexes, what indexes to create, etc. > -d Turn on debugging, as specified by {{EX:}}. The debug levels are the same as for slapd (see Section 6.1). > -n An optional argument that specifies the configuration file database for which to build. The first database listed is "1", the second "2", etc. By default, the first ldbm database in the configuration file is used. Should not be used in conjunction with {{EX:-b}}. > -b An optional argument that specifies the configuration file database for which to build. The provided suffix is matched against database {{EX:suffix}} to determine the database number. Should not be used in conjunction with {{EX:-n}}. H3: The {{EX:slapindex}} program Sometimes it may be necessary to regenerate indices (such as after modifying {{slapd.conf}}(5)). This is possible using the {{slapindex}}(8) program. {{EX:slapindex}} is invoked like this > slapindex -f > [-d ] [-n |-b ] Where the -f, -d, -n and -b options are the same as for the {{slapadd}}(1) program. slapindex rebuilds all indices based upon the current database contents. H3: The {{EX:slapcat}} program The {{EX:slapcat}} program is dump the database to a {{TERM:LDIF}} file. This can be useful when you want to make a human-readable backup of your database or for editing your database off-line. The program is invoked like this: > slapcat -l -f > [-d ] [-n |-b ] where -n or -b is used to select the database in the slapd.conf(5) specified using -f. The corresponding LDIF output is written to standard output or to the file specified using the -l option. H3: The {{EX:ldif}} program The {{ldif}}(1) program is used to convert arbitrary data values to {{TERM:LDIF}} format. This can be useful when writing a program or script to create the LDIF file you will feed into the {{slapadd}}(8) or {{ldapadd}}(1) program, or when writing a SHELL backend. {{ldif}}(1) takes an attribute descriptin 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: > ldif [-b] where {{EX:}} is an attribute description. Without the -b option, ldif considers each line of standard input to be a separate value of the attribute. > ldif description << EOF > leading space > # leading hash mark > EOF 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. For example: > ldif -b jpegPhoto < photo.jpeg 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: > # comment > dn: > : > : > > ... Lines starting with '{{EX:#}}' character are comments. An attribute description may be a simple attribute type like {{EX:cn}} or {{EX:objectClass}} or {{EX:1.2.3}} (an {{TERM:OID}} associated with an attribute type) or may include options such as {{EX:cn;lang_en_US}} or {{EX:userCertificate;binary}}. A line may be continued by starting the next line with a {{single}} space or tab character. For example: > dn: cn=Barbara J Jensen, dc=example, dc= > com > cn: Barbara J > Jensen is equivalent to: > dn: cn=Barbara J Jensen, dc=example, dc=com > cn: Barbara J Jensen Multiple attribute values are specified on separate lines. e.g., > cn: Barbara J Jensen > cn: Babs Jensen If an {{EX:}} contains a non-printing character, or begins with a space or a colon '{{EX::}}', the {{EX:}} is followed by a double colon and the value is encoded in base 64 notation. e.g., the value {{EX:" begins with a space"}} would be encoded like this: > 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. > # First Entry > dn: cn=Barbara J Jensen, dc=example, dc=com > cn: Barbara J Jensen > cn: Babs Jensen > objectclass: person > sn: Jensen > > # Second Entry > dn: cn=Bjorn J Jensen, dc=example, dc=com > cn: Bjorn J Jensen > cn: Bjorn Jensen > objectclass: person > sn: Jensen > > # Third Entry > dn: cn=Jennifer J Jensen, dc=example, dc=com > cn: Jennifer J Jensen > cn: Jennifer Jensen > objectclass: person > sn: Jensen > # Base64 encoded JPEG photo > jpegPhoto:: /9j/4AAQSkZJRgABAAAAAQABAAD/2wBDABALD > A4MChAODQ4SERATGCgaGBYWGDEjJR0oOjM9PDkzODdASFxOQ > ERXRTc4UG1RV19iZ2hnPk1xeXBkeFxlZ2P/2wBDARESEhgVG Notice that the {{EX:jpegPhoto}} in Jennifer's entry is encoded using base 64. The {{ldif}}(1) program (described in {{SECT:The {{EX:ldif}} program}} section above) can be used to produce an attribute-description/base64-value pair suitable for inclusion in an LDIF file. 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.