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
87 on this option. Once you have configured things to your liking,
88 start up slapd, connect with your LDAP client, and start adding
89 entries. For example, to add a the organizational entry followed
90 by a Postmaster entry using the {{I:ldapadd}} tool, you could create
91 an {{TERM:LDIF}} file called {{EX:entries.ldif}} with the contents:
94 > objectClass=dcObject
95 > objectClass=organization
97 > o=Example Corporation
98 > description=The Example Corporation
100 > cn=Postmaster, dc=example, dc=com
101 > objectClass=organizationalRole
103 > description=OpenLDAP Postmaster <Postmaster@example.com>
105 and then use a command like this to actually create the entry:
107 > ldapadd -f entries.ldif -x -D "cn=Manager,dc=example,dc=com" -w secret
109 The above command assumes settings provided in the above examples.
112 H2: Creating a database off-line
114 The second method of database creation is to do it off-line, using
115 the slapd database tools described below. This method is best if
116 you have many thousands of entries to create, which would take an
117 unacceptably long time to add using the LDAP method described above.
118 These tools read the slapd configuration file and an input file
119 containing a text representation of the entries to add. For database
120 types which support the tools, they produce the database files
121 directly (otherwise you must use the on-line method above). There
122 are several important configuration options you will want to be
123 sure and set in the config file database definition first:
127 As described in the {{SECT:General Database Directives}} section,
128 this option defines which entries are to be held by this database.
129 You should set this to the DN of the root of the subtree you are
130 trying to create. For example:
132 > suffix "dc=example, dc=com"
134 You should be sure to specify a directory where the index files
137 > directory <directory>
141 > directory /usr/local/var/openldap-ldbm
143 Finally, you need to specify which indexes you want to build. This
144 is done by one or more index options.
146 > index {<attrlist> | default} [pres,eq,approx,sub,none]
150 > index cn,sn,uid pres,eq,approx
151 > index objectClass eq
153 This would create presence, equality and approximate indexes for
154 the {{EX:cn}}, {{EX:sn}}, and {{EX:uid}} attributes and an equality
155 index for the {{EX:objectClass}} attribute. See the configuration
156 file section for more information on this option.
158 H3: The {{EX:slapadd}} program
160 Once you've configured things to your liking, you create the primary
161 database and associated indexes by running the {{slapadd}}(8)
164 > slapadd -l <inputfile> -f <slapdconfigfile>
165 > [-d <debuglevel>] [-n <integer>|-b <suffix>]
167 The arguments have the following meanings:
171 Specifies the LDIF input file containing the entries to add in text
172 form (described below in the {{SECT:The LDIF text entry format}}
175 > -f <slapdconfigfile>
177 Specifies the slapd configuration file that tells where to create
178 the indexes, what indexes to create, etc.
182 Turn on debugging, as specified by {{EX:<debuglevel>}}. The debug
183 levels are the same as for slapd. See the {{SECT:Command-Line
184 Options}} section in {{SECT:Running slapd}}.
186 > -n <databasenumber>
188 An optional argument that specifies which database to modify. The
189 first database listed in the configuration file is {{EX:1}}, the
190 second {{EX:2}}, etc. By default, the first ldbm database in the
191 configuration file is used. Should not be used in conjunction with
196 An optional argument that specifies which database to modify. The
197 provided suffix is matched against a database {{EX:suffix}} directive
198 to determine the database number. Should not be used in conjunction
202 H3: The {{EX:slapindex}} program
204 Sometimes it may be necessary to regenerate indices (such as after
205 modifying {{slapd.conf}}(5)). This is possible using the {{slapindex}}(8)
206 program. {{slapindex}} is invoked like this
208 > slapindex -f <slapdconfigfile>
209 > [-d <debuglevel>] [-n <databasenumber>|-b <suffix>]
211 Where the {{EX:-f}}, {{EX:-d}}, {{EX:-n}} and {{EX:-b}} options
212 are the same as for the {{slapadd}}(1) program. {{slapindex}}
213 rebuilds all indices based upon the current database contents.
216 H3: The {{EX:slapcat}} program
218 The {{EX:slapcat}} program is used to dump the database to an
219 {{TERM:LDIF}} file. This can be useful when you want to make a
220 human-readable backup of your database or when you want to edit
221 your database off-line. The program is invoked like this:
223 > slapcat -l <filename> -f <slapdconfigfile>
224 > [-d <debuglevel>] [-n <databasenumber>|-b <suffix>]
226 where {{EX:-n}} or {{EX:-b}} is used to select the database in the
227 {{slapd.conf}}(5) specified using {{EX:-f}}. The corresponding
228 LDIF output is written to standard output or to the file specified
229 using the {{EX:-l}} option.
233 H3: The {{EX:ldif}} program
235 The {{ldif}}(1) program is used to convert arbitrary data values
236 to {{TERM:LDIF}} format. This can be useful when writing a program
237 or script to create the LDIF file you will feed into the {{slapadd}}(8)
238 or {{ldapadd}}(1) program, or when writing a SHELL backend.
239 {{ldif}}(1) takes an attribute description as an argument and reads
240 the attribute value(s) from standard input. It produces the LDIF
241 formatted attribute line(s) on standard output. The usage is:
243 > ldif [-b] <attrdesc>
245 where {{EX:<attrdesc>}} is an attribute description. Without the
246 {{EX-b}} option, the {{ldif}} program will consider each line of
247 standard input to be a separate value of the attribute.
249 > ldif description << EOF
251 > # leading hash mark
254 The {{EX:-b}} option can be used to force the {{ldif}} program to
255 interpret its input as a single raw binary value. This option is
256 useful when converting binary data such as a {{EX:jpegPhoto}} or
257 {{EX:audio}} attribute. For example:
259 > ldif -b jpegPhoto < photo.jpeg
263 H2: The LDIF text entry format
265 The {{TERM[expand]LDIF}} (LDIF) is used to represent LDAP entries
266 in a simple text format. This section provides a brief description
267 of the LDIF entry format which complements {{ldif}}(5) and the
268 technical specification {{REF:RFC2849}}.
270 The basic form of an entry is:
273 > dn: <distinguished name>
274 > <attrdesc>: <attrvalue>
275 > <attrdesc>: <attrvalue>
279 Lines starting with a '{{EX:#}}' character are comments. An
280 attribute description may be a simple attribute type like {{EX:cn}}
281 or {{EX:objectClass}} or {{EX:1.2.3}} (an {{TERM:OID}} associated
282 with an attribute type) or may include options such as {{EX:cn;lang_en_US}}
283 or {{EX:userCertificate;binary}}.
285 A line may be continued by starting the next line with a {{single}}
286 space or tab character. For example:
288 > dn: cn=Barbara J Jensen, dc=example, dc=
295 > dn: cn=Barbara J Jensen, dc=example, dc=com
296 > cn: Barbara J Jensen
298 Multiple attribute values are specified on separate lines. e.g.,
300 > cn: Barbara J Jensen
303 If an {{EX:<attrvalue>}} contains non-printing characters or begins
304 with a space, a colon ('{{EX::}}'), or a less than ('{{EX:<}}'),
305 the {{EX:<attrdesc>}} is followed by a double colon and the base64
306 encoding of the value. For example, the value "{{EX: begins with
307 a space}}" would be encoded like this:
309 > cn:: IGJlZ2lucyB3aXRoIGEgc3BhY2U=
311 You can also specify a {{TERM:URL}} containing the attribute value.
312 For example, the following specifies the {{EX:jpegPhoto}} value
313 should be obtained from the file {{F:/path/to/file.jpeg}}.
315 > cn:< file://path/to/file.jpeg
317 Multiple entries within the same LDIF file are separated by blank
318 lines. Here's an example of an LDIF file containing three entries.
321 > dn: cn=Barbara J Jensen, dc=example, dc=com
322 > cn: Barbara J Jensen
324 > objectClass: person
328 > dn: cn=Bjorn J Jensen, dc=example, dc=com
331 > objectClass: person
333 > # Base64 encoded JPEG photo
334 > jpegPhoto:: /9j/4AAQSkZJRgABAAAAAQABAAD/2wBDABALD
335 > A4MChAODQ4SERATGCgaGBYWGDEjJR0oOjM9PDkzODdASFxOQ
336 > ERXRTc4UG1RV19iZ2hnPk1xeXBkeFxlZ2P/2wBDARESEhgVG
339 > dn: cn=Jennifer J Jensen, dc=example, dc=com
340 > cn: Jennifer J Jensen
341 > cn: Jennifer Jensen
342 > objectClass: person
344 > # JPEG photo from file
345 > jpegPhoto:< file://path/to/file.jpeg
347 Notice that the {{EX:jpegPhoto}} in Bjorn's entry is base 64 encoded
348 and the {{EX:jpegPhoto}} in Jennifer's entry is obtained from the
349 location indicated by the URL.
351 Note: Trailing spaces are not trimmed from values in an LDIF file.
352 Nor are multiple internal spaces compressed. If you don't want them
353 in your data, don't put them there.