2 # Copyright 1999-2000, The OpenLDAP Foundation, All Rights Reserved.
3 # COPYING RESTRICTIONS APPLY, see COPYRIGHT.
5 H1: Database Creation and Maintenance Tools
7 This section tells you how to create a slapd database from
8 scratch, and how to do trouble shooting if you run into
9 problems. There are two ways to create a database. First,
10 you can create the database on-line using LDAP. With this
11 method, you simply start up slapd and add entries using the
12 LDAP client of your choice. This method is fine for relatively
13 small databases (a few hundred or thousand entries,
14 depending on your requirements). This method works for database
15 types which support updates.
17 The second method of database creation is to do it off-line
18 using special utilities provided with slapd. This method is
19 best if you have many thousands of entries to create, which
20 would take an unacceptably long time using the LDAP method,
21 or if you want to ensure the database is not accessed while
22 it is being created. Note that not all database types support
26 H2: Creating a database over LDAP
28 With this method, you use the LDAP client of your choice
29 (e.g., the ldapadd(1)) to add entries, just like you would
30 once the database is created. You should be sure to set the
31 following configuration options before starting slapd:
35 As described in the preceding section, this option says what
36 entries are to be held by this database. You should set this
37 to the DN of the root of the subtree you are trying to create.
40 > suffix "dc=example, dc=com"
42 You should be sure to specify a directory where the index
43 files should be created:
45 > directory <directory>
49 > directory /usr/local/var/openldap-ldbm
51 You need to create this directory with appropriate permissions
52 such that slapd can write to it.
54 You need to make it so you can connect to slapd as directory user
55 with permission to add entries. You can configure the directory
56 to support a special {{super-user}} or {{root}} user just for
57 this purpose. This is done through the following two options
58 in the database definition:
65 > rootdn "cn=Manager, dc=example, dc=com"
68 These options specify a DN and password that can be used
69 to authenticate as the {{super-user}} entry of the database (i.e.,
70 the entry allowed to do anything). The DN and password
71 specified here will always work, regardless of whether the
72 entry named actually exists or has the password given. This
73 solves the chicken-and-egg problem of how to authenticate
74 and add entries before any entries yet exist.
76 Finally, you should make sure that the database definition
77 contains the index definitions you want:
79 > index {<attrlist> | default} [pres,eq,approx,sub,none]
81 For example, to index the cn, sn, uid and objectclass
82 attributes the following index configuration lines could be
86 > index objectclass pres,eq
88 See Section 4 on the configuration file for more details on
89 this option. Once you have configured things to your liking,
90 start up slapd, connect with your LDAP client, and start
91 adding entries. For example, to add a the organizational entry
92 followed by a Postmaster entry using the {{I:ldapadd}} tool, you
93 could create an {{TERM:LDIF}} file called {{EX:entries.ldif}} with the
97 > objectClass=dcObject
98 > objectClass=organization
100 > o=Example Corporation
101 > description=The Example Corporation
103 > cn=Postmaster, dc=example, dc=com
104 > objectClass=organizationalRole
106 > description=OpenLDAP Postmaster <Postmaster@example.com>
108 and then use a command like this to actually create the
111 > ldapadd -f entries.ldif -x -D "cn=Manager,dc=example,dc=com" -w secret
113 The above command assumes settings provided in the above
117 H2: Creating a database off-line
119 The second method of database creation is to do it off-line,
120 using the slapd database tools described below. This method is
121 best if you have many thousands of entries to create, which
122 would take an unacceptably long time using
123 the LDAP method described above. These tools read the
124 slapd configuration file and an input file containing a text
125 representation of the entries to add. For database types which
126 support the tools, they produce the database files directly (otherwise
127 you must use the on-line method above). There are several important
128 configuration options you will want to be sure and set in the config
129 file database definition first:
133 As described in the preceding section, this option says what
134 entries are to be held by this database. You should set this
135 to the DN of the root of the subtree you are trying to create.
138 > suffix "dc=example, dc=com"
140 You should be sure to specify a directory where the index
141 files should be created:
143 > directory <directory>
147 > directory /usr/local/var/openldap-ldbm
149 Finally, you need to specify which indexes you want to build.
150 This is done by one or more index options.
152 > index {<attrlist> | default} [pres,eq,approx,sub,none]
156 > index cn,sn,uid pres,eq,approx
157 > index objectClass eq
159 This would create presence, equality and approximate
160 indexes for the cn, sn, and uid attributes and an equality
161 index for the objectClass attribute. See the configuration
162 file section for more information on this option.
164 H3: The {{EX:slapadd}} program
166 Once you've configured things to your liking, you create the
167 primary database and associated indexes by running the
168 {{slapadd}}(8) program:
170 > slapadd -l <inputfile> -f <slapdconfigfile>
171 > [-d <debuglevel>] [-n <integer>|-b <suffix>]
173 The arguments have the following meanings:
177 Specifies the LDIF input file containing the entries to add in
178 text form (described below in Section 8.3).
180 > -f <slapdconfigfile>
182 Specifies the slapd configuration file that tells where to
183 create the indexes, what indexes to create, etc.
187 Turn on debugging, as specified by {{EX:<debuglevel>}}. The
188 debug levels are the same as for slapd (see Section 6.1).
190 > -n <databasenumber>
192 An optional argument that specifies the configuration file
193 database for which to build. The first database listed
194 is "1", the second "2", etc. By default, the first ldbm database
195 in the configuration file is used. Should not be used in
196 conjunction with {{EX:-b}}.
200 An optional argument that specifies the configuration file
201 database for which to build. The provided suffix is matched
202 against database {{EX:suffix}} to determine the database
203 number. Should not be used in conjunction with {{EX:-n}}.
206 H3: The {{EX:slapindex}} program
208 Sometimes it may be necessary to regenerate indices (such
209 as after modifying {{slapd.conf}}(5)). This is possible using
210 the {{slapindex}}(8) program. {{EX:slapindex}} is invoked
213 > slapindex -f <slapdconfigfile>
214 > [-d <debuglevel>] [-n <databasenumber>|-b <suffix>]
216 Where the -f, -d, -n and -b options are the same as for the
217 {{slapadd}}(1) program. slapindex rebuilds all indices based
218 upon the current database contents.
221 H3: The {{EX:slapcat}} program
223 The {{EX:slapcat}} program is used to dump the database to a {{TERM:LDIF}}
224 file. This can be useful when you want to make a human-readable
225 backup of your database or for editing your database off-line.
226 The program is invoked like this:
228 > slapcat -l <filename> -f <slapdconfigfile>
229 > [-d <debuglevel>] [-n <databasenumber>|-b <suffix>]
231 where -n or -b is used to select the database in the slapd.conf(5)
232 specified using -f. The corresponding LDIF output is written to
233 standard output or to the file specified using the -l option.
236 H3: The {{EX:ldif}} program
238 The {{ldif}}(1) program is used to convert arbitrary data values to
239 {{TERM:LDIF}} format. This can be useful when writing a program or
240 script to create the LDIF file you will feed into the {{slapadd}}(8)
241 or {{ldapadd}}(1) program, or when writing a SHELL backend. {{ldif}}(1)
242 takes an attribute descriptin as an argument and reads the attribute
243 value(s) from standard input. It produces the LDIF formatted
244 attribute line(s) on standard output. The usage is:
246 > ldif [-b] <attrdesc>
248 where {{EX:<attrdesc>}} is an attribute description. Without the -b
249 option, ldif considers each line of standard input to be a separate
250 value of the attribute.
252 > ldif description << EOF
254 > # leading hash mark
257 The -b option can be used to force ldif to interpret its input
258 as a single raw binary value. This option is useful when
259 converting binary data such as a {{EX:jpegPhoto}} or {{EX:audio}}
260 attribute. For example:
262 > ldif -b jpegPhoto < photo.jpeg
265 H2: The LDIF text entry format
267 The LDAP Data Interchange Format (LDIF) is used to represent LDAP
268 entries in a simple text format. The basic form of an entry is:
271 > dn: <distinguished name>
272 > <attrdesc>: <attrvalue>
273 > <attrdesc>: <attrvalue>
277 Lines starting with '{{EX:#}}' character are
278 comments. An attribute description may be a simple attribute
279 type like {{EX:cn}} or {{EX:objectClass}} or {{EX:1.2.3}} (an {{TERM:OID}}
280 associated with an attribute type) or may include options such
281 as {{EX:cn;lang_en_US}} or {{EX:userCertificate;binary}}.
283 A line may be continued by starting the next line with a
284 {{single}} space or tab character. For example:
286 > dn: cn=Barbara J Jensen, dc=example, dc=
293 > dn: cn=Barbara J Jensen, dc=example, dc=com
294 > cn: Barbara J Jensen
296 Multiple attribute values are specified on separate lines. e.g.,
298 > cn: Barbara J Jensen
301 If an {{EX:<attrvalue>}} contains a non-printing character, or
302 begins with a space or a colon '{{EX::}}', the {{EX:<attrdesc>}} is followed
303 by a double colon and the value is encoded in base 64
304 notation. e.g., the value {{EX:" begins with a space"}} would be
307 > cn:: IGJlZ2lucyB3aXRoIGEgc3BhY2U=
309 Multiple entries within the same LDIF file are separated by
310 blank lines. Here's an example of an LDIF file containing
314 > dn: cn=Barbara J Jensen, dc=example, dc=com
315 > cn: Barbara J Jensen
317 > objectclass: person
321 > dn: cn=Bjorn J Jensen, dc=example, dc=com
324 > objectclass: person
328 > dn: cn=Jennifer J Jensen, dc=example, dc=com
329 > cn: Jennifer J Jensen
330 > cn: Jennifer Jensen
331 > objectclass: person
333 > # Base64 encoded JPEG photo
334 > jpegPhoto:: /9j/4AAQSkZJRgABAAAAAQABAAD/2wBDABALD
335 > A4MChAODQ4SERATGCgaGBYWGDEjJR0oOjM9PDkzODdASFxOQ
336 > ERXRTc4UG1RV19iZ2hnPk1xeXBkeFxlZ2P/2wBDARESEhgVG
338 Notice that the {{EX:jpegPhoto}} in Jennifer's entry is
339 encoded using base 64. The {{ldif}}(1) program (described in
340 {{SECT:The {{EX:ldif}} program}} section above) can be used to
341 produce an attribute-description/base64-value pair suitable for
342 inclusion in an LDIF file.
344 Note: Trailing spaces are not trimmed from values in an
345 LDIF file. Nor are multiple internal spaces compressed. If
346 you don't want them in your data, don't put them there.