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 {{SECT:The slapd Configuration File}} section 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 {{EX:cn}}, {{EX:sn}}, and {{EX:uid}} attributes
161 and an equality index for the {{EX:objectClass}} attribute. See
162 the configuration 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 the {{SECT:The LDIF text entry format}}
181 > -f <slapdconfigfile>
183 Specifies the slapd configuration file that tells where to
184 create the indexes, what indexes to create, etc.
188 Turn on debugging, as specified by {{EX:<debuglevel>}}. The
189 debug levels are the same as for slapd. See
190 the {{SECT:Command-Line Options}} section in {{SECT:Running slapd}}.
192 > -n <databasenumber>
194 An optional argument that specifies the configuration file
195 database for which to build. The first database listed
196 is "1", the second "2", etc. By default, the first ldbm database
197 in the configuration file is used. Should not be used in
198 conjunction with {{EX:-b}}.
202 An optional argument that specifies the configuration file
203 database for which to build. The provided suffix is matched
204 against database {{EX:suffix}} to determine the database
205 number. Should not be used in conjunction with {{EX:-n}}.
208 H3: The {{EX:slapindex}} program
210 Sometimes it may be necessary to regenerate indices (such
211 as after modifying {{slapd.conf}}(5)). This is possible using
212 the {{slapindex}}(8) program. {{slapindex}} is invoked
215 > slapindex -f <slapdconfigfile>
216 > [-d <debuglevel>] [-n <databasenumber>|-b <suffix>]
218 Where the -f, -d, -n and -b options are the same as for the
219 {{slapadd}}(1) program. slapindex rebuilds all indices based
220 upon the current database contents.
223 H3: The {{EX:slapcat}} program
225 The {{EX:slapcat}} program is used to dump the database to a {{TERM:LDIF}}
226 file. This can be useful when you want to make a human-readable
227 backup of your database or for editing your database off-line.
228 The program is invoked like this:
230 > slapcat -l <filename> -f <slapdconfigfile>
231 > [-d <debuglevel>] [-n <databasenumber>|-b <suffix>]
233 where -n or -b is used to select the database in the {{slapd.conf}}(5)
234 specified using -f. The corresponding LDIF output is written to
235 standard output or to the file specified using the -l option.
239 H3: The {{EX:ldif}} program
241 The {{ldif}}(1) program is used to convert arbitrary data values to
242 {{TERM:LDIF}} format. This can be useful when writing a program or
243 script to create the LDIF file you will feed into the {{slapadd}}(8)
244 or {{ldapadd}}(1) program, or when writing a SHELL backend. {{ldif}}(1)
245 takes an attribute descriptin as an argument and reads the attribute
246 value(s) from standard input. It produces the LDIF formatted
247 attribute line(s) on standard output. The usage is:
249 > ldif [-b] <attrdesc>
251 where {{EX:<attrdesc>}} is an attribute description. Without the -b
252 option, ldif considers each line of standard input to be a separate
253 value of the attribute.
255 > ldif description << EOF
257 > # leading hash mark
260 The -b option can be used to force ldif to interpret its input
261 as a single raw binary value. This option is useful when
262 converting binary data such as a {{EX:jpegPhoto}} or {{EX:audio}}
263 attribute. For example:
265 > ldif -b jpegPhoto < photo.jpeg
269 H2: The LDIF text entry format
271 The {{TERM[expand]LDIF}} (LDIF) is used to represent LDAP
272 entries in a simple text format. This section provides a brief
273 description of the LDIF entry format which complements {{ldif}}(5)
274 and the technical specification {{REF:RFC2849}}.
276 The basic form of an entry is:
279 > dn: <distinguished name>
280 > <attrdesc>: <attrvalue>
281 > <attrdesc>: <attrvalue>
285 Lines starting with '{{EX:#}}' character are
286 comments. An attribute description may be a simple attribute
287 type like {{EX:cn}} or {{EX:objectClass}} or {{EX:1.2.3}} (an {{TERM:OID}}
288 associated with an attribute type) or may include options such
289 as {{EX:cn;lang_en_US}} or {{EX:userCertificate;binary}}.
291 A line may be continued by starting the next line with a
292 {{single}} space or tab character. For example:
294 > dn: cn=Barbara J Jensen, dc=example, dc=
301 > dn: cn=Barbara J Jensen, dc=example, dc=com
302 > cn: Barbara J Jensen
304 Multiple attribute values are specified on separate lines. e.g.,
306 > cn: Barbara J Jensen
309 If an {{EX:<attrvalue>}} contains non-printing characters or begins
310 with a space, a colon ('{{EX::}}'), or a less than ('{{EX:<}}'),
311 the {{EX:<attrdesc>}} is followed by a double colon and the base64
312 encoding of the value.
313 For example, the value "{{EX: begins with a space}}" would be
316 > cn:: IGJlZ2lucyB3aXRoIGEgc3BhY2U=
318 You can also specify a {{TERM:URL}} containing the attribute value.
319 For example, the following specifies the {{EX:jpegPhoto}} value
320 should be obtained from the file {{F:/path/to/file.jpeg}}.
322 > cn:< file://path/to/file.jpeg
324 Multiple entries within the same LDIF file are separated by
325 blank lines. Here's an example of an LDIF file containing
329 > dn: cn=Barbara J Jensen, dc=example, dc=com
330 > cn: Barbara J Jensen
332 > objectClass: person
336 > dn: cn=Bjorn J Jensen, dc=example, dc=com
339 > objectClass: person
341 > # Base64 encoded JPEG photo
342 > jpegPhoto:: /9j/4AAQSkZJRgABAAAAAQABAAD/2wBDABALD
343 > A4MChAODQ4SERATGCgaGBYWGDEjJR0oOjM9PDkzODdASFxOQ
344 > ERXRTc4UG1RV19iZ2hnPk1xeXBkeFxlZ2P/2wBDARESEhgVG
347 > dn: cn=Jennifer J Jensen, dc=example, dc=com
348 > cn: Jennifer J Jensen
349 > cn: Jennifer Jensen
350 > objectClass: person
352 > # JPEG photo from file
353 > jpegPhoto:< file://path/to/file.jpeg
355 Notice that the {{EX:jpegPhoto}} in Bjorn's entry is base 64 encoded
356 and the {{EX:jpegPhoto}} in Jennifer's entry is obtained from the
357 location indicated by the URL.
359 Note: Trailing spaces are not trimmed from values in an
360 LDIF file. Nor are multiple internal spaces compressed. If
361 you don't want them in your data, don't put them there.