<!doctype html public "-//W30//DTD W3 HTML 2.0//EN">
<HTML>
<!-- This file was generated using SDF 2.001 by
Ian Clatworthy (ianc@mincom.com). SDF is freely
available from http://www.mincom.com/mtr/sdf. -->
<HEAD>
<TITLE>OpenLDAP Software 2.4 Administrator's Guide: Database Creation and Maintenance Tools</TITLE>
</HEAD>
<BODY>
<DIV CLASS="header">
<A HREF="http://www.OpenLDAP.org/">
<P><IMG SRC="../images/LDAPlogo.gif" ALIGN="Left" BORDER=0></P>
</A>
<DIV CLASS="navigate">
<P ALIGN="Center"><A HREF="index.html">Contents</A> | <A HREF="index.html">Parent Topic</A> | <A HREF="limits.html">Previous Topic</A> | <A HREF="backends.html">Next Topic</A> <BR><A HREF="http://www.openldap.org/">Home</A> | <A HREF="../index.html">Catalog</A></P>
</DIV>
<BR CLEAR="Left">
</DIV>
<DIV CLASS="main">
<H1>10. Database Creation and Maintenance Tools</H1>
<P>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 <TERM>LDAP</TERM>. 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.</P>
<P>The second method of database creation is to do it off-line using special utilities provided with <EM>slapd</EM>(8). 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 utilities.</P>
<HR>
<H2><A NAME="Creating a database over LDAP">10.1. Creating a database over LDAP</A></H2>
<P>With this method, you use the LDAP client of your choice (e.g., the <EM>ldapadd</EM>(1)) to add entries, just like you would once the database is created. You should be sure to set the following options in the configuration file before starting <EM>slapd</EM>(8).</P>
<PRE>
suffix <dn>
</PRE>
<P>As described in the <A HREF="slapdconfig.html#General Database Directives">General Database Directives</A> section, this option defines which 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:</P>
<PRE>
suffix "dc=example,dc=com"
</PRE>
<P>You should be sure to specify a directory where the index files should be created:</P>
<PRE>
directory <directory>
</PRE>
<P>For example:</P>
<PRE>
directory /usr/local/var/openldap-data
</PRE>
<P>You need to create this directory with appropriate permissions such that slapd can write to it.</P>
<P>You need to configure slapd so that you can connect to it as a directory user with permission to add entries. You can configure the directory to support a special <EM>super-user</EM> or <EM>root</EM> user just for this purpose. This is done through the following two options in the database definition:</P>
<PRE>
rootdn <dn>
rootpw <passwd>
</PRE>
<P>For example:</P>
<PRE>
rootdn "cn=Manager,dc=example,dc=com"
rootpw secret
</PRE>
<P>These options specify a DN and password that can be used to authenticate as the <EM>super-user</EM> 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.</P>
<P>Finally, you should make sure that the database definition contains the index definitions you want:</P>
<PRE>
index {<attrlist> | default} [pres,eq,approx,sub,none]
</PRE>
<P>For example, to index the <TT>cn</TT>, <TT>sn</TT>, <TT>uid</TT> and <TT>objectclass</TT> attributes, the following <TT>index</TT> directives could be used:</P>
<PRE>
index cn,sn,uid pres,eq,approx,sub
index objectClass eq
</PRE>
<P>This would create presence, equality, approximate, and substring indices for the <TT>cn</TT>, <TT>sn</TT>, and <TT>uid</TT> attributes and an equality index for the <TT>objectClass</TT> attribute. Note that not all index types are available with all attribute types. See <A HREF="slapdconfig.html">The slapd Configuration File</A> section for more information on this option.</P>
<P>Once you have configured things to your liking, start up slapd, connect with your LDAP client, and start adding entries. For example, to add an organization entry and an organizational role entry using the <I>ldapadd</I> tool, you could create an <TERM>LDIF</TERM> file called <TT>entries.ldif</TT> with the contents:</P>
<PRE>
# Organization for Example Corporation
dn: dc=example,dc=com
objectClass: dcObject
objectClass: organization
dc: example
o: Example Corporation
description: The Example Corporation
# Organizational Role for Directory Manager
dn: cn=Manager,dc=example,dc=com
objectClass: organizationalRole
cn: Manager
description: Directory Manager
</PRE>
<P>and then use a command like this to actually create the entry:</P>
<PRE>
ldapadd -f entries.ldif -x -D "cn=Manager,dc=example,dc=com" -w secret
</PRE>
<P>The above command assumes settings provided in the above examples.</P>
<HR>
<H2><A NAME="Creating a database off-line">10.2. Creating a database off-line</A></H2>
<P>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 to add 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:</P>
<PRE>
suffix <dn>
</PRE>
<P>As described in the <A HREF="slapdconfig.html#General Database Directives">General Database Directives</A> section, this option defines which 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:</P>
<PRE>
suffix "dc=example,dc=com"
</PRE>
<P>You should be sure to specify a directory where the index files should be created:</P>
<PRE>
directory <directory>
</PRE>
<P>For example:</P>
<PRE>
directory /usr/local/var/openldap-data
</PRE>
<P>Finally, you need to specify which indices you want to build. This is done by one or more index options.</P>
<PRE>
index {<attrlist> | default} [pres,eq,approx,sub,none]
</PRE>
<P>For example:</P>
<PRE>
index cn,sn,uid pres,eq,approx,sub
index objectClass eq
</PRE>
<P>This would create presence, equality, approximate, and substring indices for the <TT>cn</TT>, <TT>sn</TT>, and <TT>uid</TT> attributes and an equality index for the <TT>objectClass</TT> attribute. Note that not all index types are available with all attribute types. See <A HREF="slapdconfig.html">The slapd Configuration File</A> section for more information on this option.</P>
<H3><A NAME="The {{EX:slapadd}} program">10.2.1. The <TT>slapadd</TT> program</A></H3>
<P>Once you've configured things to your liking, you create the primary database and associated indices by running the <EM>slapadd</EM>(8) program:</P>
<PRE>
slapadd -l <inputfile> -f <slapdconfigfile>
[-d <debuglevel>] [-n <integer>|-b <suffix>]
</PRE>
<P>The arguments have the following meanings:</P>
<PRE>
-l <inputfile>
</PRE>
<P>Specifies the <TERM>LDIF</TERM> input file containing the entries to add in text form (described below in the <A HREF="dbtools.html#The LDIF text entry format">The LDIF text entry format</A> section).</P>
<PRE>
-f <slapdconfigfile>
</PRE>
<P>Specifies the slapd configuration file that tells where to create the indices, what indices to create, etc.</P>
<PRE>
-F <slapdconfdirectory>
</PRE>
<P>Specifies a config directory. If both <TT>-f</TT> and <TT>-F</TT> are specified, the config file will be read and converted to config directory format and written to the specified directory. If neither option is specified, an attempt to read the default config directory will be made before trying to use the default config file. If a valid config directory exists then the default config file is ignored. If dryrun mode is also specified, no conversion will occur.</P>
<PRE>
-d <debuglevel>
</PRE>
<P>Turn on debugging, as specified by <TT><debuglevel></TT>. The debug levels are the same as for slapd. See the <A HREF="runningslapd.html#Command-Line Options">Command-Line Options</A> section in <A HREF="runningslapd.html">Running slapd</A>.</P>
<PRE>
-n <databasenumber>
</PRE>
<P>An optional argument that specifies which database to modify. The first database listed in the configuration file is <TT>1</TT>, the second <TT>2</TT>, etc. By default, the first database in the configuration file is used. Should not be used in conjunction with <TT>-b</TT>.</P>
<PRE>
-b <suffix>
</PRE>
<P>An optional argument that specifies which database to modify. The provided suffix is matched against a database <TT>suffix</TT> directive to determine the database number. Should not be used in conjunction with <TT>-n</TT>.</P>
<H3><A NAME="The {{EX:slapindex}} program">10.2.2. The <TT>slapindex</TT> program</A></H3>
<P>Sometimes it may be necessary to regenerate indices (such as after modifying <EM>slapd.conf</EM>(5)). This is possible using the <EM>slapindex</EM>(8) program. <EM>slapindex</EM> is invoked like this</P>
<PRE>
slapindex -f <slapdconfigfile>
[-d <debuglevel>] [-n <databasenumber>|-b <suffix>]
</PRE>
<P>Where the <TT>-f</TT>, <TT>-d</TT>, <TT>-n</TT> and <TT>-b</TT> options are the same as for the <EM>slapadd</EM>(1) program. <EM>slapindex</EM> rebuilds all indices based upon the current database contents.</P>
<H3><A NAME="The {{EX:slapcat}} program">10.2.3. The <TT>slapcat</TT> program</A></H3>
<P>The <TT>slapcat</TT> program is used to dump the database to an <TERM>LDIF</TERM> file. This can be useful when you want to make a human-readable backup of your database or when you want to edit your database off-line. The program is invoked like this:</P>
<PRE>
slapcat -l <filename> -f <slapdconfigfile>
[-d <debuglevel>] [-n <databasenumber>|-b <suffix>]
</PRE>
<P>where <TT>-n</TT> or <TT>-b</TT> is used to select the database in the <EM>slapd.conf</EM>(5) specified using <TT>-f</TT>. The corresponding <TERM>LDIF</TERM> output is written to standard output or to the file specified using the <TT>-l</TT> option.</P>
<HR>
<H2><A NAME="The LDIF text entry format">10.3. The LDIF text entry format</A></H2>
<P>The <TERM>LDAP Data Interchange Format</TERM> (LDIF) is used to represent LDAP entries in a simple text format. This section provides a brief description of the LDIF entry format which complements <EM>ldif</EM>(5) and the technical specification <A HREF="http://www.rfc-editor.org/rfc/rfc2849.txt">RFC2849</A>.</P>
<P>The basic form of an entry is:</P>
<PRE>
# comment
dn: <distinguished name>
<attrdesc>: <attrvalue>
<attrdesc>: <attrvalue>
...
</PRE>
<P>Lines starting with a '<TT>#</TT>' character are comments. An attribute description may be a simple attribute type like <TT>cn</TT> or <TT>objectClass</TT> or <TT>1.2.3</TT> (an <TERM>OID</TERM> associated with an attribute type) or may include options such as <TT>cn;lang_en_US</TT> or <TT>userCertificate;binary</TT>.</P>
<P>A line may be continued by starting the next line with a <EM>single</EM> space or tab character. For example:</P>
<PRE>
dn: cn=Barbara J Jensen,dc=example,dc=
com
cn: Barbara J
Jensen
</PRE>
<P>is equivalent to:</P>
<PRE>
dn: cn=Barbara J Jensen,dc=example,dc=com
cn: Barbara J Jensen
</PRE>
<P>Multiple attribute values are specified on separate lines. e.g.,</P>
<PRE>
cn: Barbara J Jensen
cn: Babs Jensen
</PRE>
<P>If an <TT><attrvalue></TT> contains non-printing characters or begins with a space, a colon ('<TT>:</TT>'), or a less than ('<TT><</TT>'), the <TT><attrdesc></TT> is followed by a double colon and the base64 encoding of the value. For example, the value "<TT> begins with a space</TT>" would be encoded like this:</P>
<PRE>
cn:: IGJlZ2lucyB3aXRoIGEgc3BhY2U=
</PRE>
<P>You can also specify a <TERM>URL</TERM> containing the attribute value. For example, the following specifies the <TT>jpegPhoto</TT> value should be obtained from the file <TT>/path/to/file.jpeg</TT>.</P>
<PRE>
cn:< file:///path/to/file.jpeg
</PRE>
<P>Multiple entries within the same LDIF file are separated by blank lines. Here's an example of an LDIF file containing three entries.</P>
<PRE>
# Barbara's Entry
dn: cn=Barbara J Jensen,dc=example,dc=com
cn: Barbara J Jensen
cn: Babs Jensen
objectClass: person
sn: Jensen
# Bjorn's Entry
dn: cn=Bjorn J Jensen,dc=example,dc=com
cn: Bjorn J Jensen
cn: Bjorn Jensen
objectClass: person
sn: Jensen
# Base64 encoded JPEG photo
jpegPhoto:: /9j/4AAQSkZJRgABAAAAAQABAAD/2wBDABALD
A4MChAODQ4SERATGCgaGBYWGDEjJR0oOjM9PDkzODdASFxOQ
ERXRTc4UG1RV19iZ2hnPk1xeXBkeFxlZ2P/2wBDARESEhgVG
# Jennifer's Entry
dn: cn=Jennifer J Jensen,dc=example,dc=com
cn: Jennifer J Jensen
cn: Jennifer Jensen
objectClass: person
sn: Jensen
# JPEG photo from file
jpegPhoto:< file:///path/to/file.jpeg
</PRE>
<P>Notice that the <TT>jpegPhoto</TT> in Bjorn's entry is base 64 encoded and the <TT>jpegPhoto</TT> in Jennifer's entry is obtained from the location indicated by the URL.</P>
<P><HR WIDTH="80%" ALIGN="Left">
<STRONG>Note: </STRONG>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.
<HR WIDTH="80%" ALIGN="Left"></P>
<P></P>
</DIV>
<DIV CLASS="footer">
<HR>
<DIV CLASS="navigate">
<P ALIGN="Center"><A HREF="index.html">Contents</A> | <A HREF="index.html">Parent Topic</A> | <A HREF="limits.html">Previous Topic</A> | <A HREF="backends.html">Next Topic</A> <BR><A HREF="http://www.openldap.org/">Home</A> | <A HREF="../index.html">Catalog</A></P>
</DIV>
<P>
<FONT COLOR="#808080" FACE="Arial,Verdana,Helvetica" SIZE="1"><B>
________________<BR>
<SMALL>© Copyright 2011, <A HREF="http://www.OpenLDAP.org/foundation/">OpenLDAP Foundation</A>, <A HREF="mailto:info@OpenLDAP.org">info@OpenLDAP.org</A></SMALL></B></FONT>
</DIV>
</BODY>
</HTML>
