]> git.sur5r.net Git - openldap/blob - doc/guide/admin/dbtools.sdf
bf191347a1b862b77bafe70109b97873e2e9594d
[openldap] / doc / guide / admin / dbtools.sdf
1 # $OpenLDAP$
2 # Copyright 1999-2000, The OpenLDAP Foundation, All Rights Reserved.
3 # COPYING RESTRICTIONS APPLY, see COPYRIGHT.
4
5 H1: Database Creation and Maintenance Tools
6
7 This section tells you how to create a slapd database from
8 scratch, and how to do trouble shooting if you run into
9 problems. There are two ways to create a database. First,
10 you can create the database on-line using LDAP. With this
11 method, you simply start up slapd and add entries using the
12 LDAP client of your choice. This method is fine for relatively
13 small databases (a few hundred or thousand entries,
14 depending on your requirements). This method works for database
15 types which support updates.
16
17 The second method of database creation is to do it off-line
18 using special utilities provided with slapd. This method is
19 best if you have many thousands of entries to create, which
20 would take an unacceptably long time using the LDAP method,
21 or if you want to ensure the database is not accessed while
22 it is being created. Note that not all database types support
23 these utilitites.
24
25
26 H2: Creating a database over LDAP
27
28 With this method, you use the LDAP client of your choice
29 (e.g., the ldapadd(1)) to add entries, just like you would
30 once the database is created. You should be sure to set the
31 following configuration options before starting slapd:
32
33 >       suffix <dn>
34
35 As described in the preceding section, this option says what
36 entries are to be held by this database. You should set this
37 to the DN of the root of the subtree you are trying to create.
38 For example
39
40 >       suffix "dc=example, dc=com"
41
42 You should be sure to specify a directory where the index
43 files should be created:
44
45 >       directory <directory>
46
47 For example:
48
49 >       directory /usr/local/var/openldap-ldbm
50
51 You need to create this directory with appropriate permissions
52 such that slapd can write to it.
53
54 You need to make it so you can connect to slapd as directory user
55 with permission to add entries. You can configure the directory
56 to support a special {{super-user}} or {{root}} user just for
57 this purpose. This is done through the following two options
58 in the database definition:
59
60 >       rootdn <dn>
61 >       rootpw <passwd>
62
63 For example:
64
65 >       rootdn "cn=Manager, dc=example, dc=com"
66 >       rootpw secret
67
68 These options specify a DN and password that can be used
69 to authenticate as the {{super-user}} entry of the database (i.e.,
70 the entry allowed to do anything). The DN and password
71 specified here will always work, regardless of whether the
72 entry named actually exists or has the password given. This
73 solves the chicken-and-egg problem of how to authenticate
74 and add entries before any entries yet exist.
75
76 Finally, you should make sure that the database definition
77 contains the index definitions you want:
78
79 >       index {<attrlist> | default} [pres,eq,approx,sub,none]
80
81 For example, to index the cn, sn, uid and objectclass
82 attributes the following index configuration lines could be
83 used.
84
85 >       index cn,sn,uid
86 >       index objectclass pres,eq
87
88 See Section 4 on the configuration file for more details on
89 this option. Once you have configured things to your liking,
90 start up slapd, connect with your LDAP client, and start
91 adding entries. For example, to add a the organizational entry
92 followed by a Postmaster entry using the {{I:ldapadd}} tool, you
93 could create an {{TERM:LDIF}} file called {{EX:entries.ldif}} with the
94 contents:
95
96 >       dc=example, dc=com
97 >       objectClass=dcObject
98 >       objectClass=organization
99 >       dc=example
100 >       o=Example Corporation
101 >       description=The Example Corporation
102 >
103 >       cn=Postmaster, dc=example, dc=com
104 >       objectClass=organizationalRole
105 >       cn=Postmaster
106 >       description=OpenLDAP Postmaster <Postmaster@example.com>
107
108 and then use a command like this to actually create the
109 entry:
110
111 >       ldapadd -f entries.ldif -x -D "cn=Manager,dc=example,dc=com" -w secret
112
113 The above command assumes settings provided in the above
114 examples.
115
116
117 H2: Creating a database off-line
118
119 The second method of database creation is to do it off-line,
120 using the slapd database tools described below. This method is
121 best if you have many thousands of entries to create, which
122 would take an unacceptably long time using
123 the LDAP method described above. These tools read the
124 slapd configuration file and an input file containing a text
125 representation of the entries to add. For database types which
126 support the tools, they produce the database files directly (otherwise
127 you must use the on-line method above). There are several important
128 configuration options you will want to be sure and set in the config
129 file database definition first:
130
131 >       suffix <dn>
132
133 As described in the preceding section, this option says what
134 entries are to be held by this database. You should set this
135 to the DN of the root of the subtree you are trying to create.
136 For example
137
138 >       suffix "dc=example, dc=com"
139
140 You should be sure to specify a directory where the index
141 files should be created:
142
143 >       directory <directory>
144
145 For example:
146
147 >       directory /usr/local/var/openldap-ldbm
148
149 Finally, you need to specify which indexes you want to build.
150 This is done by one or more index options.
151
152 >       index {<attrlist> | default} [pres,eq,approx,sub,none]
153
154 For example:
155
156 >       index cn,sn,uid pres,eq,approx
157 >       index objectClass eq
158
159 This would create presence, equality and approximate
160 indexes for the cn, sn, and uid attributes and an equality
161 index for the objectClass attribute. See the configuration
162 file section for more information on this option.
163
164 H3: The {{EX:slapadd}} program
165
166 Once you've configured things to your liking, you create the
167 primary database and associated indexes by running the
168 {{slapadd}}(8) program:
169
170 >       slapadd -l <inputfile> -f <slapdconfigfile>
171 >               [-d <debuglevel>] [-n <integer>|-b <suffix>]
172
173 The arguments have the following meanings:
174
175 >       -l <inputfile>
176
177 Specifies the LDIF input file containing the entries to add in
178 text form (described below in Section 8.3).
179
180 >       -f <slapdconfigfile>
181
182 Specifies the slapd configuration file that tells where to
183 create the indexes, what indexes to create, etc.
184
185 >       -d <debuglevel>
186
187 Turn on debugging, as specified by {{EX:<debuglevel>}}. The
188 debug levels are the same as for slapd (see Section 6.1).
189
190 >       -n <databasenumber>
191
192 An optional argument that specifies the configuration file
193 database for which to build. The first database listed
194 is "1", the second "2", etc. By default, the first ldbm database
195 in the configuration file is used. Should not be used in
196 conjunction with {{EX:-b}}.
197
198 >       -b <suffix>
199
200 An optional argument that specifies the configuration file
201 database for which to build. The provided suffix is matched
202 against database {{EX:suffix}} to determine the database
203 number. Should not be used in conjunction with {{EX:-n}}.
204
205
206 H3: The {{EX:slapindex}} program
207
208 Sometimes it may be necessary to regenerate indices (such
209 as after modifying {{slapd.conf}}(5)). This is possible using
210 the {{slapindex}}(8) program. {{EX:slapindex}} is invoked
211 like this
212
213 >       slapindex -f <slapdconfigfile>
214 >               [-d <debuglevel>] [-n <databasenumber>|-b <suffix>]
215
216 Where the -f, -d, -n and -b options are the same as for the
217 {{slapadd}}(1) program. slapindex rebuilds all indices based
218 upon the current database contents.
219
220
221 H3: The {{EX:slapcat}} program
222
223 The {{EX:slapcat}} program is used to dump the database to a {{TERM:LDIF}}
224 file. This can be useful when you want to make a human-readable
225 backup of your database or for editing your database off-line.
226 The program is invoked like this:
227
228 >       slapcat -l <filename> -f <slapdconfigfile>
229 >               [-d <debuglevel>] [-n <databasenumber>|-b <suffix>]
230
231 where -n or -b is used to select the database in the slapd.conf(5)
232 specified using -f. The corresponding LDIF output is written to
233 standard output or to the file specified using the -l option.
234
235
236 H3: The {{EX:ldif}} program
237
238 The {{ldif}}(1) program is used to convert arbitrary data values to
239 {{TERM:LDIF}} format. This can be useful when writing a program or
240 script to create the LDIF file you will feed into the {{slapadd}}(8)
241 or {{ldapadd}}(1) program, or when writing a SHELL backend. {{ldif}}(1)
242 takes an attribute descriptin as an argument and reads the attribute
243 value(s) from standard input. It produces the LDIF formatted
244 attribute line(s) on standard output. The usage is:
245
246 >       ldif [-b] <attrdesc>
247
248 where {{EX:<attrdesc>}} is an attribute description. Without the -b
249 option, ldif considers each line of standard input to be a separate
250 value of the attribute.
251
252 >       ldif description << EOF
253 >        leading space
254 >       # leading hash mark
255 >       EOF
256
257 The -b option can be used to force ldif to interpret its input
258 as a single raw binary value. This option is useful when
259 converting binary data such as a {{EX:jpegPhoto}} or {{EX:audio}}
260 attribute.  For example:
261
262 >       ldif -b jpegPhoto < photo.jpeg
263
264
265 H2: The LDIF text entry format
266
267 The LDAP Data Interchange Format (LDIF) is used to represent LDAP
268 entries in a simple text format. The basic form of an entry is:
269
270 >       # comment
271 >       dn: <distinguished name>
272 >       <attrdesc>: <attrvalue>
273 >       <attrdesc>: <attrvalue>
274 >
275 >       ...
276
277 Lines starting with '{{EX:#}}' character are
278 comments.  An attribute description may be a simple attribute
279 type like {{EX:cn}} or {{EX:objectClass}} or {{EX:1.2.3}} (an {{TERM:OID}}
280 associated with an attribute type) or may include options such
281 as {{EX:cn;lang_en_US}} or {{EX:userCertificate;binary}}.
282
283 A line may be continued by starting the next line with a
284 {{single}} space or tab character.  For example:
285
286 >       dn: cn=Barbara J Jensen, dc=example, dc=
287 >        com
288 >       cn: Barbara J
289 >         Jensen
290
291 is equivalent to:
292
293 >       dn: cn=Barbara J Jensen, dc=example, dc=com
294 >       cn: Barbara J Jensen
295
296 Multiple attribute values are specified on separate lines. e.g.,
297
298 >       cn: Barbara J Jensen
299 >       cn: Babs Jensen
300
301 If an {{EX:<attrvalue>}} contains a non-printing character, or
302 begins with a space or a colon '{{EX::}}', the {{EX:<attrdesc>}} is followed
303 by a double colon and the value is encoded in base 64
304 notation. e.g., the value {{EX:" begins with a space"}} would be
305 encoded like this:
306
307 >       cn:: IGJlZ2lucyB3aXRoIGEgc3BhY2U=
308
309 Multiple entries within the same LDIF file are separated by
310 blank lines. Here's an example of an LDIF file containing
311 three entries.
312
313 >       # First Entry
314 >       dn: cn=Barbara J Jensen, dc=example, dc=com
315 >       cn: Barbara J Jensen
316 >       cn: Babs Jensen
317 >       objectclass: person
318 >       sn: Jensen
319 >
320 >       # Second Entry
321 >       dn: cn=Bjorn J Jensen, dc=example, dc=com
322 >       cn: Bjorn J Jensen
323 >       cn: Bjorn Jensen
324 >       objectclass: person
325 >       sn: Jensen
326 >
327 >       # Third Entry
328 >       dn: cn=Jennifer J Jensen, dc=example, dc=com
329 >       cn: Jennifer J Jensen
330 >       cn: Jennifer Jensen
331 >       objectclass: person
332 >       sn: Jensen
333 >       # Base64 encoded JPEG photo
334 >       jpegPhoto:: /9j/4AAQSkZJRgABAAAAAQABAAD/2wBDABALD
335 >       A4MChAODQ4SERATGCgaGBYWGDEjJR0oOjM9PDkzODdASFxOQ
336 >       ERXRTc4UG1RV19iZ2hnPk1xeXBkeFxlZ2P/2wBDARESEhgVG
337
338 Notice that the {{EX:jpegPhoto}} in Jennifer's entry is
339 encoded using base 64. The {{ldif}}(1) program (described in
340 {{SECT:The {{EX:ldif}} program}} section above) can be used to
341 produce an attribute-description/base64-value pair suitable for
342 inclusion in an LDIF file.
343
344 Note: Trailing spaces are not trimmed from values in an
345 LDIF file. Nor are multiple internal spaces compressed. If
346 you don't want them in your data, don't put them there.
347