2 # Copyright 1999-2007 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 {{TERM: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 utilities.
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-data
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
83 > index cn,sn,uid pres,eq,approx,sub
84 > index objectClass eq
86 This would create presence, equality, approximate, and substring
87 indices for the {{EX:cn}}, {{EX:sn}}, and {{EX:uid}} attributes and
88 an equality index for the {{EX:objectClass}} attribute. Note that
89 not all index types are available with all attribute types. See
90 {{SECT:The slapd Configuration File}} section for more information
93 Once you have configured things to your liking, start up slapd,
94 connect with your LDAP client, and start adding entries. For
95 example, to add an organization entry and an organizational role
96 entry using the {{I:ldapadd}} tool, you could create an {{TERM:LDIF}}
97 file called {{EX:entries.ldif}} with the contents:
99 > # Organization for Example Corporation
100 > dn: dc=example,dc=com
101 > objectClass: dcObject
102 > objectClass: organization
104 > o: Example Corporation
105 > description: The Example Corporation
107 > # Organizational Role for Directory Manager
108 > dn: cn=Manager,dc=example,dc=com
109 > objectClass: organizationalRole
111 > description: Directory Manager
113 and then use a command like this to actually create the entry:
115 > ldapadd -f entries.ldif -x -D "cn=Manager,dc=example,dc=com" -w secret
117 The above command assumes settings provided in the above examples.
120 H2: Creating a database off-line
122 The second method of database creation is to do it off-line, using
123 the slapd database tools described below. This method is best if
124 you have many thousands of entries to create, which would take an
125 unacceptably long time to add using the LDAP method described above.
126 These tools read the slapd configuration file and an input file
127 containing a text representation of the entries to add. For database
128 types which support the tools, they produce the database files
129 directly (otherwise you must use the on-line method above). There
130 are several important configuration options you will want to be
131 sure and set in the config file database definition first:
135 As described in the {{SECT:General Database Directives}} section,
136 this option defines which entries are to be held by this database.
137 You should set this to the DN of the root of the subtree you are
138 trying to create. For example:
140 > suffix "dc=example,dc=com"
142 You should be sure to specify a directory where the index files
145 > directory <directory>
149 > directory /usr/local/var/openldap-data
151 Finally, you need to specify which indices you want to build. This
152 is done by one or more index options.
154 > index {<attrlist> | default} [pres,eq,approx,sub,none]
158 > index cn,sn,uid pres,eq,approx,sub
159 > index objectClass eq
161 This would create presence, equality, approximate, and substring
162 indices for the {{EX:cn}}, {{EX:sn}}, and {{EX:uid}} attributes and
163 an equality index for the {{EX:objectClass}} attribute. Note that
164 not all index types are available with all attribute types. See
165 {{SECT:The slapd Configuration File}} section for more information
168 H3: The {{EX:slapadd}} program
170 Once you've configured things to your liking, you create the primary
171 database and associated indices by running the {{slapadd}}(8)
174 > slapadd -l <inputfile> -f <slapdconfigfile>
175 > [-d <debuglevel>] [-n <integer>|-b <suffix>]
177 The arguments have the following meanings:
181 Specifies the {{TERM:LDIF}} input file containing the entries to
182 add in text form (described below in the {{SECT:The LDIF text entry
185 > -f <slapdconfigfile>
187 Specifies the slapd configuration file that tells where to create
188 the indices, what indices to create, etc.
192 Turn on debugging, as specified by {{EX:<debuglevel>}}. The debug
193 levels are the same as for slapd. See the {{SECT:Command-Line
194 Options}} section in {{SECT:Running slapd}}.
196 > -n <databasenumber>
198 An optional argument that specifies which database to modify. The
199 first database listed in the configuration file is {{EX:1}}, the
200 second {{EX:2}}, etc. By default, the first database in the
201 configuration file is used. Should not be used in conjunction with
206 An optional argument that specifies which database to modify. The
207 provided suffix is matched against a database {{EX:suffix}} directive
208 to determine the database number. Should not be used in conjunction
212 H3: The {{EX:slapindex}} program
214 Sometimes it may be necessary to regenerate indices (such as after
215 modifying {{slapd.conf}}(5)). This is possible using the {{slapindex}}(8)
216 program. {{slapindex}} is invoked like this
218 > slapindex -f <slapdconfigfile>
219 > [-d <debuglevel>] [-n <databasenumber>|-b <suffix>]
221 Where the {{EX:-f}}, {{EX:-d}}, {{EX:-n}} and {{EX:-b}} options
222 are the same as for the {{slapadd}}(1) program. {{slapindex}}
223 rebuilds all indices based upon the current database contents.
226 H3: The {{EX:slapcat}} program
228 The {{EX:slapcat}} program is used to dump the database to an
229 {{TERM:LDIF}} file. This can be useful when you want to make a
230 human-readable backup of your database or when you want to edit
231 your database off-line. The program is invoked like this:
233 > slapcat -l <filename> -f <slapdconfigfile>
234 > [-d <debuglevel>] [-n <databasenumber>|-b <suffix>]
236 where {{EX:-n}} or {{EX:-b}} is used to select the database in the
237 {{slapd.conf}}(5) specified using {{EX:-f}}. The corresponding
238 {{TERM:LDIF}} output is written to standard output or to the file
239 specified using the {{EX:-l}} option.
243 H3: The {{EX:ldif}} program
245 The {{ldif}}(1) program is used to convert arbitrary data values
246 to {{TERM:LDIF}} format. This can be useful when writing a program
247 or script to create the LDIF file you will feed into the {{slapadd}}(8)
248 or {{ldapadd}}(1) program, or when writing a SHELL backend.
249 {{ldif}}(1) takes an attribute description as an argument and reads
250 the attribute value(s) from standard input. It produces the LDIF
251 formatted attribute line(s) on standard output. The usage is:
253 > ldif [-b] <attrdesc>
255 where {{EX:<attrdesc>}} is an attribute description. Without the
256 {{EX-b}} option, the {{ldif}} program will consider each line of
257 standard input to be a separate value of the attribute.
259 > ldif description << EOF
261 > # leading hash mark
264 The {{EX:-b}} option can be used to force the {{ldif}} program to
265 interpret its input as a single raw binary value. This option is
266 useful when converting binary data such as a {{EX:jpegPhoto}} or
267 {{EX:audio}} attribute. For example:
269 > ldif -b jpegPhoto < photo.jpeg
273 H2: The LDIF text entry format
275 The {{TERM[expand]LDIF}} (LDIF) is used to represent LDAP entries
276 in a simple text format. This section provides a brief description
277 of the LDIF entry format which complements {{ldif}}(5) and the
278 technical specification {{REF:RFC2849}}.
280 The basic form of an entry is:
283 > dn: <distinguished name>
284 > <attrdesc>: <attrvalue>
285 > <attrdesc>: <attrvalue>
289 Lines starting with a '{{EX:#}}' character are comments. An
290 attribute description may be a simple attribute type like {{EX:cn}}
291 or {{EX:objectClass}} or {{EX:1.2.3}} (an {{TERM:OID}} associated
292 with an attribute type) or may include options such as {{EX:cn;lang_en_US}}
293 or {{EX:userCertificate;binary}}.
295 A line may be continued by starting the next line with a {{single}}
296 space or tab character. For example:
298 > dn: cn=Barbara J Jensen,dc=example,dc=
305 > dn: cn=Barbara J Jensen,dc=example,dc=com
306 > cn: Barbara J Jensen
308 Multiple attribute values are specified on separate lines. e.g.,
310 > cn: Barbara J Jensen
313 If an {{EX:<attrvalue>}} contains non-printing characters or begins
314 with a space, a colon ('{{EX::}}'), or a less than ('{{EX:<}}'),
315 the {{EX:<attrdesc>}} is followed by a double colon and the base64
316 encoding of the value. For example, the value "{{EX: begins with
317 a space}}" would be encoded like this:
319 > cn:: IGJlZ2lucyB3aXRoIGEgc3BhY2U=
321 You can also specify a {{TERM:URL}} containing the attribute value.
322 For example, the following specifies the {{EX:jpegPhoto}} value
323 should be obtained from the file {{F:/path/to/file.jpeg}}.
325 > cn:< file:///path/to/file.jpeg
327 Multiple entries within the same LDIF file are separated by blank
328 lines. Here's an example of an LDIF file containing three entries.
331 > dn: cn=Barbara J Jensen,dc=example,dc=com
332 > cn: Barbara J Jensen
334 > objectClass: person
338 > dn: cn=Bjorn J Jensen,dc=example,dc=com
341 > objectClass: person
343 > # Base64 encoded JPEG photo
344 > jpegPhoto:: /9j/4AAQSkZJRgABAAAAAQABAAD/2wBDABALD
345 > A4MChAODQ4SERATGCgaGBYWGDEjJR0oOjM9PDkzODdASFxOQ
346 > ERXRTc4UG1RV19iZ2hnPk1xeXBkeFxlZ2P/2wBDARESEhgVG
349 > dn: cn=Jennifer J Jensen,dc=example,dc=com
350 > cn: Jennifer J Jensen
351 > cn: Jennifer Jensen
352 > objectClass: person
354 > # JPEG photo from file
355 > jpegPhoto:< file:///path/to/file.jpeg
357 Notice that the {{EX:jpegPhoto}} in Bjorn's entry is base 64 encoded
358 and the {{EX:jpegPhoto}} in Jennifer's entry is obtained from the
359 location indicated by the URL.
361 Note: Trailing spaces are not trimmed from values in an LDIF file.
362 Nor are multiple internal spaces compressed. If you don't want them
363 in your data, don't put them there.