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 scratch,
8 and how to do trouble shooting if you run into problems. There are
9 two ways to create a database. First, you can create the database
10 on-line using LDAP. With this method, you simply start up slapd
11 and add entries using the LDAP client of your choice. This method
12 is fine for relatively small databases (a few hundred or thousand
13 entries, depending on your requirements). This method works for
14 database types which support updates.
16 The second method of database creation is to do it off-line using
17 special utilities provided with slapd. This method is best if you
18 have many thousands of entries to create, which would take an
19 unacceptably long time using the LDAP method, or if you want to
20 ensure the database is not accessed while it is being created. Note
21 that not all database types support these utilitites.
24 H2: Creating a database over LDAP
26 With this method, you use the LDAP client of your choice (e.g.,
27 the {{ldapadd}}(1)) to add entries, just like you would once the
28 database is created. You should be sure to set the following
29 options in the configuration file before starting {{slapd}}(8).
33 As described in the {{SECT:General Database Directives}} section,
34 this option defines which entries are to be held by this database.
35 You should set this to the DN of the root of the subtree you are
36 trying to create. For example:
38 > suffix "dc=example, dc=com"
40 You should be sure to specify a directory where the index files
43 > directory <directory>
47 > directory /usr/local/var/openldap-ldbm
49 You need to create this directory with appropriate permissions such
50 that slapd can write to it.
52 You need to configure slapd so that you can connect to it as a
53 directory user with permission to add entries. You can configure
54 the directory to support a special {{super-user}} or {{root}} user
55 just for this purpose. This is done through the following two
56 options in the database definition:
63 > rootdn "cn=Manager, dc=example, dc=com"
66 These options specify a DN and password that can be used to
67 authenticate as the {{super-user}} entry of the database (i.e.,
68 the entry allowed to do anything). The DN and password specified
69 here will always work, regardless of whether the entry named actually
70 exists or has the password given. This solves the chicken-and-egg
71 problem of how to authenticate and add entries before any entries
74 Finally, you should make sure that the database definition contains
75 the index definitions you want:
77 > index {<attrlist> | default} [pres,eq,approx,sub,none]
79 For example, to index the {{EX:cn}}, {{EX:sn}}, {{EX:uid}} and
80 {{EX:objectclass}} attributes, the following {{EX:index}} directives
84 > index objectClass pres,eq
86 See {{SECT:The slapd Configuration File}} section for more details on
87 this option. Once you have configured things to your liking, start up
88 slapd, connect with your LDAP client, and start adding entries. For
89 example, to add an organization entry and an organizational role entry
90 using the {{I:ldapadd}} tool, you could create an {{TERM:LDIF}} file
91 called {{EX:entries.ldif}} with the contents:
93 > # Organization for Example Corporation
94 > dn: dc=example, dc=com
95 > objectClass: dcObject
96 > objectClass: organization
98 > o: Example Corporation
99 > description: The Example Corporation
101 > # Organizational Role for Directory Manager
102 > dn: cn=Manager, dc=example, dc=com
103 > objectClass: organizationalRole
105 > description: Directory Manager
107 and then use a command like this to actually create the entry:
109 > ldapadd -f entries.ldif -x -D "cn=Manager,dc=example,dc=com" -w secret
111 The above command assumes settings provided in the above examples.
114 H2: Creating a database off-line
116 The second method of database creation is to do it off-line, using
117 the slapd database tools described below. This method is best if
118 you have many thousands of entries to create, which would take an
119 unacceptably long time to add using the LDAP method described above.
120 These tools read the slapd configuration file and an input file
121 containing a text representation of the entries to add. For database
122 types which support the tools, they produce the database files
123 directly (otherwise you must use the on-line method above). There
124 are several important configuration options you will want to be
125 sure and set in the config file database definition first:
129 As described in the {{SECT:General Database Directives}} section,
130 this option defines which entries are to be held by this database.
131 You should set this to the DN of the root of the subtree you are
132 trying to create. For example:
134 > suffix "dc=example, dc=com"
136 You should be sure to specify a directory where the index files
139 > directory <directory>
143 > directory /usr/local/var/openldap-ldbm
145 Finally, you need to specify which indexes you want to build. This
146 is done by one or more index options.
148 > index {<attrlist> | default} [pres,eq,approx,sub,none]
152 > index cn,sn,uid pres,eq,approx
153 > index objectClass eq
155 This would create presence, equality and approximate indexes for
156 the {{EX:cn}}, {{EX:sn}}, and {{EX:uid}} attributes and an equality
157 index for the {{EX:objectClass}} attribute. See the configuration
158 file section for more information on this option.
160 H3: The {{EX:slapadd}} program
162 Once you've configured things to your liking, you create the primary
163 database and associated indexes by running the {{slapadd}}(8)
166 > slapadd -l <inputfile> -f <slapdconfigfile>
167 > [-d <debuglevel>] [-n <integer>|-b <suffix>]
169 The arguments have the following meanings:
173 Specifies the LDIF input file containing the entries to add in text
174 form (described below in the {{SECT:The LDIF text entry format}}
177 > -f <slapdconfigfile>
179 Specifies the slapd configuration file that tells where to create
180 the indexes, what indexes to create, etc.
184 Turn on debugging, as specified by {{EX:<debuglevel>}}. The debug
185 levels are the same as for slapd. See the {{SECT:Command-Line
186 Options}} section in {{SECT:Running slapd}}.
188 > -n <databasenumber>
190 An optional argument that specifies which database to modify. The
191 first database listed in the configuration file is {{EX:1}}, the
192 second {{EX:2}}, etc. By default, the first ldbm database in the
193 configuration file is used. Should not be used in conjunction with
198 An optional argument that specifies which database to modify. The
199 provided suffix is matched against a database {{EX:suffix}} directive
200 to determine the database number. Should not be used in conjunction
204 H3: The {{EX:slapindex}} program
206 Sometimes it may be necessary to regenerate indices (such as after
207 modifying {{slapd.conf}}(5)). This is possible using the {{slapindex}}(8)
208 program. {{slapindex}} is invoked like this
210 > slapindex -f <slapdconfigfile>
211 > [-d <debuglevel>] [-n <databasenumber>|-b <suffix>]
213 Where the {{EX:-f}}, {{EX:-d}}, {{EX:-n}} and {{EX:-b}} options
214 are the same as for the {{slapadd}}(1) program. {{slapindex}}
215 rebuilds all indices based upon the current database contents.
218 H3: The {{EX:slapcat}} program
220 The {{EX:slapcat}} program is used to dump the database to an
221 {{TERM:LDIF}} file. This can be useful when you want to make a
222 human-readable backup of your database or when you want to edit
223 your database off-line. The program is invoked like this:
225 > slapcat -l <filename> -f <slapdconfigfile>
226 > [-d <debuglevel>] [-n <databasenumber>|-b <suffix>]
228 where {{EX:-n}} or {{EX:-b}} is used to select the database in the
229 {{slapd.conf}}(5) specified using {{EX:-f}}. The corresponding
230 LDIF output is written to standard output or to the file specified
231 using the {{EX:-l}} option.
235 H3: The {{EX:ldif}} program
237 The {{ldif}}(1) program is used to convert arbitrary data values
238 to {{TERM:LDIF}} format. This can be useful when writing a program
239 or script to create the LDIF file you will feed into the {{slapadd}}(8)
240 or {{ldapadd}}(1) program, or when writing a SHELL backend.
241 {{ldif}}(1) takes an attribute description as an argument and reads
242 the attribute value(s) from standard input. It produces the LDIF
243 formatted attribute line(s) on standard output. The usage is:
245 > ldif [-b] <attrdesc>
247 where {{EX:<attrdesc>}} is an attribute description. Without the
248 {{EX-b}} option, the {{ldif}} program will consider each line of
249 standard input to be a separate value of the attribute.
251 > ldif description << EOF
253 > # leading hash mark
256 The {{EX:-b}} option can be used to force the {{ldif}} program to
257 interpret its input as a single raw binary value. This option is
258 useful when converting binary data such as a {{EX:jpegPhoto}} or
259 {{EX:audio}} attribute. For example:
261 > ldif -b jpegPhoto < photo.jpeg
265 H2: The LDIF text entry format
267 The {{TERM[expand]LDIF}} (LDIF) is used to represent LDAP entries
268 in a simple text format. This section provides a brief description
269 of the LDIF entry format which complements {{ldif}}(5) and the
270 technical specification {{REF:RFC2849}}.
272 The basic form of an entry is:
275 > dn: <distinguished name>
276 > <attrdesc>: <attrvalue>
277 > <attrdesc>: <attrvalue>
281 Lines starting with a '{{EX:#}}' character are comments. An
282 attribute description may be a simple attribute type like {{EX:cn}}
283 or {{EX:objectClass}} or {{EX:1.2.3}} (an {{TERM:OID}} associated
284 with an attribute type) or may include options such as {{EX:cn;lang_en_US}}
285 or {{EX:userCertificate;binary}}.
287 A line may be continued by starting the next line with a {{single}}
288 space or tab character. For example:
290 > dn: cn=Barbara J Jensen, dc=example, dc=
297 > dn: cn=Barbara J Jensen, dc=example, dc=com
298 > cn: Barbara J Jensen
300 Multiple attribute values are specified on separate lines. e.g.,
302 > cn: Barbara J Jensen
305 If an {{EX:<attrvalue>}} contains non-printing characters or begins
306 with a space, a colon ('{{EX::}}'), or a less than ('{{EX:<}}'),
307 the {{EX:<attrdesc>}} is followed by a double colon and the base64
308 encoding of the value. For example, the value "{{EX: begins with
309 a space}}" would be encoded like this:
311 > cn:: IGJlZ2lucyB3aXRoIGEgc3BhY2U=
313 You can also specify a {{TERM:URL}} containing the attribute value.
314 For example, the following specifies the {{EX:jpegPhoto}} value
315 should be obtained from the file {{F:/path/to/file.jpeg}}.
317 > cn:< file://path/to/file.jpeg
319 Multiple entries within the same LDIF file are separated by blank
320 lines. Here's an example of an LDIF file containing three entries.
323 > dn: cn=Barbara J Jensen, dc=example, dc=com
324 > cn: Barbara J Jensen
326 > objectClass: person
330 > dn: cn=Bjorn J Jensen, dc=example, dc=com
333 > objectClass: person
335 > # Base64 encoded JPEG photo
336 > jpegPhoto:: /9j/4AAQSkZJRgABAAAAAQABAAD/2wBDABALD
337 > A4MChAODQ4SERATGCgaGBYWGDEjJR0oOjM9PDkzODdASFxOQ
338 > ERXRTc4UG1RV19iZ2hnPk1xeXBkeFxlZ2P/2wBDARESEhgVG
341 > dn: cn=Jennifer J Jensen, dc=example, dc=com
342 > cn: Jennifer J Jensen
343 > cn: Jennifer Jensen
344 > objectClass: person
346 > # JPEG photo from file
347 > jpegPhoto:< file://path/to/file.jpeg
349 Notice that the {{EX:jpegPhoto}} in Bjorn's entry is base 64 encoded
350 and the {{EX:jpegPhoto}} in Jennifer's entry is obtained from the
351 location indicated by the URL.
353 Note: Trailing spaces are not trimmed from values in an LDIF file.
354 Nor are multiple internal spaces compressed. If you don't want them
355 in your data, don't put them there.