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-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
84 > index objectClass pres,eq
86 Note that not all index types are available with all attribute types.
87 See {{SECT:The slapd Configuration File}} section for more details on
88 this option. Once you have configured things to your liking, start up
89 slapd, connect with your LDAP client, and start adding entries. For
90 example, to add an organization entry and an organizational role entry
91 using the {{I:ldapadd}} tool, you could create an {{TERM:LDIF}} file
92 called {{EX:entries.ldif}} with the contents:
94 > # Organization for Example Corporation
95 > dn: dc=example,dc=com
96 > objectClass: dcObject
97 > objectClass: organization
99 > o: Example Corporation
100 > description: The Example Corporation
102 > # Organizational Role for Directory Manager
103 > dn: cn=Manager,dc=example,dc=com
104 > objectClass: organizationalRole
106 > description: Directory Manager
108 and then use a command like this to actually create the entry:
110 > ldapadd -f entries.ldif -x -D "cn=Manager,dc=example,dc=com" -w secret
112 The above command assumes settings provided in the above examples.
115 H2: Creating a database off-line
117 The second method of database creation is to do it off-line, using
118 the slapd database tools described below. This method is best if
119 you have many thousands of entries to create, which would take an
120 unacceptably long time to add using the LDAP method described above.
121 These tools read the slapd configuration file and an input file
122 containing a text representation of the entries to add. For database
123 types which support the tools, they produce the database files
124 directly (otherwise you must use the on-line method above). There
125 are several important configuration options you will want to be
126 sure and set in the config file database definition first:
130 As described in the {{SECT:General Database Directives}} section,
131 this option defines which entries are to be held by this database.
132 You should set this to the DN of the root of the subtree you are
133 trying to create. For example:
135 > suffix "dc=example,dc=com"
137 You should be sure to specify a directory where the index files
140 > directory <directory>
144 > directory /usr/local/var/openldap-data
146 Finally, you need to specify which indices you want to build. This
147 is done by one or more index options.
149 > index {<attrlist> | default} [pres,eq,approx,sub,none]
153 > index cn,sn,uid pres,eq,sub
154 > index objectClass eq
156 This would create presence, equality and substring indices for
157 the {{EX:cn}}, {{EX:sn}}, and {{EX:uid}} attributes and an equality
158 index for the {{EX:objectClass}} attribute. See
159 {{SECT:The slapd Configuration File}} section
160 for more information on this option.
162 H3: The {{EX:slapadd}} program
164 Once you've configured things to your liking, you create the primary
165 database and associated indices by running the {{slapadd}}(8)
168 > slapadd -l <inputfile> -f <slapdconfigfile>
169 > [-d <debuglevel>] [-n <integer>|-b <suffix>]
171 The arguments have the following meanings:
175 Specifies the LDIF input file containing the entries to add in text
176 form (described below in the {{SECT:The LDIF text entry format}}
179 > -f <slapdconfigfile>
181 Specifies the slapd configuration file that tells where to create
182 the indices, what indices to create, etc.
186 Turn on debugging, as specified by {{EX:<debuglevel>}}. The debug
187 levels are the same as for slapd. See the {{SECT:Command-Line
188 Options}} section in {{SECT:Running slapd}}.
190 > -n <databasenumber>
192 An optional argument that specifies which database to modify. The
193 first database listed in the configuration file is {{EX:1}}, the
194 second {{EX:2}}, etc. By default, the first database in the
195 configuration file is used. Should not be used in conjunction with
200 An optional argument that specifies which database to modify. The
201 provided suffix is matched against a database {{EX:suffix}} directive
202 to determine the database number. Should not be used in conjunction
206 H3: The {{EX:slapindex}} program
208 Sometimes it may be necessary to regenerate indices (such as after
209 modifying {{slapd.conf}}(5)). This is possible using the {{slapindex}}(8)
210 program. {{slapindex}} is invoked like this
212 > slapindex -f <slapdconfigfile>
213 > [-d <debuglevel>] [-n <databasenumber>|-b <suffix>]
215 Where the {{EX:-f}}, {{EX:-d}}, {{EX:-n}} and {{EX:-b}} options
216 are the same as for the {{slapadd}}(1) program. {{slapindex}}
217 rebuilds all indices based upon the current database contents.
220 H3: The {{EX:slapcat}} program
222 The {{EX:slapcat}} program is used to dump the database to an
223 {{TERM:LDIF}} file. This can be useful when you want to make a
224 human-readable backup of your database or when you want to edit
225 your database off-line. The program is invoked like this:
227 > slapcat -l <filename> -f <slapdconfigfile>
228 > [-d <debuglevel>] [-n <databasenumber>|-b <suffix>]
230 where {{EX:-n}} or {{EX:-b}} is used to select the database in the
231 {{slapd.conf}}(5) specified using {{EX:-f}}. The corresponding
232 LDIF output is written to standard output or to the file specified
233 using the {{EX:-l}} option.
237 H3: The {{EX:ldif}} program
239 The {{ldif}}(1) program is used to convert arbitrary data values
240 to {{TERM:LDIF}} format. This can be useful when writing a program
241 or script to create the LDIF file you will feed into the {{slapadd}}(8)
242 or {{ldapadd}}(1) program, or when writing a SHELL backend.
243 {{ldif}}(1) takes an attribute description as an argument and reads
244 the attribute value(s) from standard input. It produces the LDIF
245 formatted attribute line(s) on standard output. The usage is:
247 > ldif [-b] <attrdesc>
249 where {{EX:<attrdesc>}} is an attribute description. Without the
250 {{EX-b}} option, the {{ldif}} program will consider each line of
251 standard input to be a separate value of the attribute.
253 > ldif description << EOF
255 > # leading hash mark
258 The {{EX:-b}} option can be used to force the {{ldif}} program to
259 interpret its input as a single raw binary value. This option is
260 useful when converting binary data such as a {{EX:jpegPhoto}} or
261 {{EX:audio}} attribute. For example:
263 > ldif -b jpegPhoto < photo.jpeg
267 H2: The LDIF text entry format
269 The {{TERM[expand]LDIF}} (LDIF) is used to represent LDAP entries
270 in a simple text format. This section provides a brief description
271 of the LDIF entry format which complements {{ldif}}(5) and the
272 technical specification {{REF:RFC2849}}.
274 The basic form of an entry is:
277 > dn: <distinguished name>
278 > <attrdesc>: <attrvalue>
279 > <attrdesc>: <attrvalue>
283 Lines starting with a '{{EX:#}}' character are comments. An
284 attribute description may be a simple attribute type like {{EX:cn}}
285 or {{EX:objectClass}} or {{EX:1.2.3}} (an {{TERM:OID}} associated
286 with an attribute type) or may include options such as {{EX:cn;lang_en_US}}
287 or {{EX:userCertificate;binary}}.
289 A line may be continued by starting the next line with a {{single}}
290 space or tab character. For example:
292 > dn: cn=Barbara J Jensen,dc=example,dc=
299 > dn: cn=Barbara J Jensen,dc=example,dc=com
300 > cn: Barbara J Jensen
302 Multiple attribute values are specified on separate lines. e.g.,
304 > cn: Barbara J Jensen
307 If an {{EX:<attrvalue>}} contains non-printing characters or begins
308 with a space, a colon ('{{EX::}}'), or a less than ('{{EX:<}}'),
309 the {{EX:<attrdesc>}} is followed by a double colon and the base64
310 encoding of the value. For example, the value "{{EX: begins with
311 a space}}" would be encoded like this:
313 > cn:: IGJlZ2lucyB3aXRoIGEgc3BhY2U=
315 You can also specify a {{TERM:URL}} containing the attribute value.
316 For example, the following specifies the {{EX:jpegPhoto}} value
317 should be obtained from the file {{F:/path/to/file.jpeg}}.
319 > cn:< file:///path/to/file.jpeg
321 Multiple entries within the same LDIF file are separated by blank
322 lines. Here's an example of an LDIF file containing three entries.
325 > dn: cn=Barbara J Jensen,dc=example,dc=com
326 > cn: Barbara J Jensen
328 > objectClass: person
332 > dn: cn=Bjorn J Jensen,dc=example,dc=com
335 > objectClass: person
337 > # Base64 encoded JPEG photo
338 > jpegPhoto:: /9j/4AAQSkZJRgABAAAAAQABAAD/2wBDABALD
339 > A4MChAODQ4SERATGCgaGBYWGDEjJR0oOjM9PDkzODdASFxOQ
340 > ERXRTc4UG1RV19iZ2hnPk1xeXBkeFxlZ2P/2wBDARESEhgVG
343 > dn: cn=Jennifer J Jensen,dc=example,dc=com
344 > cn: Jennifer J Jensen
345 > cn: Jennifer Jensen
346 > objectClass: person
348 > # JPEG photo from file
349 > jpegPhoto:< file:///path/to/file.jpeg
351 Notice that the {{EX:jpegPhoto}} in Bjorn's entry is base 64 encoded
352 and the {{EX:jpegPhoto}} in Jennifer's entry is obtained from the
353 location indicated by the URL.
355 Note: Trailing spaces are not trimmed from values in an LDIF file.
356 Nor are multiple internal spaces compressed. If you don't want them
357 in your data, don't put them there.