2 # Copyright 1999-2009 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}}(8). 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.
190 > -F <slapdconfdirectory>
192 Specifies a config directory. If both {{EX:-f}} and {{EX:-F}} are specified,
193 the config file will be read and converted to config directory format and
194 written to the specified directory. If neither option is specified, an attempt
195 to read the default config directory will be made before trying to use the
196 default config file. If a valid config directory exists then the default
197 config file is ignored. If dryrun mode is also specified, no conversion will occur.
201 Turn on debugging, as specified by {{EX:<debuglevel>}}. The debug
202 levels are the same as for slapd. See the {{SECT:Command-Line
203 Options}} section in {{SECT:Running slapd}}.
205 > -n <databasenumber>
207 An optional argument that specifies which database to modify. The
208 first database listed in the configuration file is {{EX:1}}, the
209 second {{EX:2}}, etc. By default, the first database in the
210 configuration file is used. Should not be used in conjunction with
215 An optional argument that specifies which database to modify. The
216 provided suffix is matched against a database {{EX:suffix}} directive
217 to determine the database number. Should not be used in conjunction
221 H3: The {{EX:slapindex}} program
223 Sometimes it may be necessary to regenerate indices (such as after
224 modifying {{slapd.conf}}(5)). This is possible using the {{slapindex}}(8)
225 program. {{slapindex}} is invoked like this
227 > slapindex -f <slapdconfigfile>
228 > [-d <debuglevel>] [-n <databasenumber>|-b <suffix>]
230 Where the {{EX:-f}}, {{EX:-d}}, {{EX:-n}} and {{EX:-b}} options
231 are the same as for the {{slapadd}}(1) program. {{slapindex}}
232 rebuilds all indices based upon the current database contents.
235 H3: The {{EX:slapcat}} program
237 The {{EX:slapcat}} program is used to dump the database to an
238 {{TERM:LDIF}} file. This can be useful when you want to make a
239 human-readable backup of your database or when you want to edit
240 your database off-line. The program is invoked like this:
242 > slapcat -l <filename> -f <slapdconfigfile>
243 > [-d <debuglevel>] [-n <databasenumber>|-b <suffix>]
245 where {{EX:-n}} or {{EX:-b}} is used to select the database in the
246 {{slapd.conf}}(5) specified using {{EX:-f}}. The corresponding
247 {{TERM:LDIF}} output is written to standard output or to the file
248 specified using the {{EX:-l}} option.
252 H3: The {{EX:ldif}} program
254 The {{ldif}}(1) program is used to convert arbitrary data values
255 to {{TERM:LDIF}} format. This can be useful when writing a program
256 or script to create the LDIF file you will feed into the {{slapadd}}(8)
257 or {{ldapadd}}(1) program, or when writing a SHELL backend.
258 {{ldif}}(1) takes an attribute description as an argument and reads
259 the attribute value(s) from standard input. It produces the LDIF
260 formatted attribute line(s) on standard output. The usage is:
262 > ldif [-b] <attrdesc>
264 where {{EX:<attrdesc>}} is an attribute description. Without the
265 {{EX-b}} option, the {{ldif}} program will consider each line of
266 standard input to be a separate value of the attribute.
268 > ldif description << EOF
270 > # leading hash mark
273 The {{EX:-b}} option can be used to force the {{ldif}} program to
274 interpret its input as a single raw binary value. This option is
275 useful when converting binary data such as a {{EX:jpegPhoto}} or
276 {{EX:audio}} attribute. For example:
278 > ldif -b jpegPhoto < photo.jpeg
282 H2: The LDIF text entry format
284 The {{TERM[expand]LDIF}} (LDIF) is used to represent LDAP entries
285 in a simple text format. This section provides a brief description
286 of the LDIF entry format which complements {{ldif}}(5) and the
287 technical specification {{REF:RFC2849}}.
289 The basic form of an entry is:
292 > dn: <distinguished name>
293 > <attrdesc>: <attrvalue>
294 > <attrdesc>: <attrvalue>
298 Lines starting with a '{{EX:#}}' character are comments. An
299 attribute description may be a simple attribute type like {{EX:cn}}
300 or {{EX:objectClass}} or {{EX:1.2.3}} (an {{TERM:OID}} associated
301 with an attribute type) or may include options such as {{EX:cn;lang_en_US}}
302 or {{EX:userCertificate;binary}}.
304 A line may be continued by starting the next line with a {{single}}
305 space or tab character. For example:
307 > dn: cn=Barbara J Jensen,dc=example,dc=
314 > dn: cn=Barbara J Jensen,dc=example,dc=com
315 > cn: Barbara J Jensen
317 Multiple attribute values are specified on separate lines. e.g.,
319 > cn: Barbara J Jensen
322 If an {{EX:<attrvalue>}} contains non-printing characters or begins
323 with a space, a colon ('{{EX::}}'), or a less than ('{{EX:<}}'),
324 the {{EX:<attrdesc>}} is followed by a double colon and the base64
325 encoding of the value. For example, the value "{{EX: begins with
326 a space}}" would be encoded like this:
328 > cn:: IGJlZ2lucyB3aXRoIGEgc3BhY2U=
330 You can also specify a {{TERM:URL}} containing the attribute value.
331 For example, the following specifies the {{EX:jpegPhoto}} value
332 should be obtained from the file {{F:/path/to/file.jpeg}}.
334 > cn:< file:///path/to/file.jpeg
336 Multiple entries within the same LDIF file are separated by blank
337 lines. Here's an example of an LDIF file containing three entries.
340 > dn: cn=Barbara J Jensen,dc=example,dc=com
341 > cn: Barbara J Jensen
343 > objectClass: person
347 > dn: cn=Bjorn J Jensen,dc=example,dc=com
350 > objectClass: person
352 > # Base64 encoded JPEG photo
353 > jpegPhoto:: /9j/4AAQSkZJRgABAAAAAQABAAD/2wBDABALD
354 > A4MChAODQ4SERATGCgaGBYWGDEjJR0oOjM9PDkzODdASFxOQ
355 > ERXRTc4UG1RV19iZ2hnPk1xeXBkeFxlZ2P/2wBDARESEhgVG
358 > dn: cn=Jennifer J Jensen,dc=example,dc=com
359 > cn: Jennifer J Jensen
360 > cn: Jennifer Jensen
361 > objectClass: person
363 > # JPEG photo from file
364 > jpegPhoto:< file:///path/to/file.jpeg
366 Notice that the {{EX:jpegPhoto}} in Bjorn's entry is base 64 encoded
367 and the {{EX:jpegPhoto}} in Jennifer's entry is obtained from the
368 location indicated by the URL.
370 Note: Trailing spaces are not trimmed from values in an LDIF file.
371 Nor are multiple internal spaces compressed. If you don't want them
372 in your data, don't put them there.