summaryrefslogtreecommitdiffstats
path: root/doc/guide/admin/dbtools.sdf
blob: 62559d5cf043908f8b4be076b779b41d17e3b3eb (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
# $OpenLDAP$
# Copyright 1999-2021 The OpenLDAP Foundation, All Rights Reserved.
# COPYING RESTRICTIONS APPLY, see COPYRIGHT.

H1: Database Creation and Maintenance Tools

This section tells you how to create a slapd database from scratch,
and how to do trouble shooting if you run into problems. There are
two ways to create a database. First, you can create the database
on-line using {{TERM:LDAP}}. With this method, you simply start up slapd
and add entries using the LDAP client of your choice. This method
is fine for relatively small databases (a few hundred or thousand
entries, depending on your requirements). This method works for
database types which support updates.

The second method of database creation is to do it off-line using
special utilities provided with {{slapd}}(8). This method is best if you
have many thousands of entries to create, which would take an
unacceptably long time using the LDAP method, or if you want to
ensure the database is not accessed while it is being created. Note
that not all database types support these utilities.


H2: Creating a database over LDAP

With this method, you use the LDAP client of your choice (e.g.,
the {{ldapadd}}(1)) to add entries, just like you would once the
database is created.  You should be sure to set the following
options in the configuration file before starting {{slapd}}(8). 

>	suffix <dn>

As described in the {{SECT:General Database Directives}} section,
this option defines which entries are to be held by this database.
You should set this to the DN of the root of the subtree you are
trying to create.  For example:

>	suffix "dc=example,dc=com"

You should be sure to specify a directory where the index files
should be created:

>	directory <directory>

For example:

>	directory /usr/local/var/openldap-data

You need to create this directory with appropriate permissions such
that slapd can write to it.

You need to configure slapd so that you can connect to it as a
directory user with permission to add entries. You can configure
the directory to support a special {{super-user}} or {{root}} user
just for this purpose. This is done through the following two
options in the database definition:

>	rootdn <dn>
>	rootpw <passwd>

For example:

>	rootdn "cn=Manager,dc=example,dc=com"
>	rootpw secret

These options specify a DN and password that can be used to
authenticate as the {{super-user}} entry of the database (i.e.,
the entry allowed to do anything). The DN and password specified
here will always work, regardless of whether the entry named actually
exists or has the password given. This solves the chicken-and-egg
problem of how to authenticate and add entries before any entries
yet exist.

Finally, you should make sure that the database definition contains
the index definitions you want:

>	index {<attrlist> | default} [pres,eq,approx,sub,none]

For example, to index the {{EX:cn}}, {{EX:sn}}, {{EX:uid}} and
{{EX:objectclass}} attributes, the following {{EX:index}} directives
could be used:

>	index cn,sn,uid pres,eq,approx,sub
>	index objectClass eq

This would create presence, equality, approximate, and substring
indices for the {{EX:cn}}, {{EX:sn}}, and {{EX:uid}} attributes and
an equality index for the {{EX:objectClass}} attribute.  Note that
not all index types are available with all attribute types.  See
{{SECT:The slapd Configuration File}} section for more information
on this option.

Once you have configured things to your liking, start up slapd,
connect with your LDAP client, and start adding entries.  For
example, to add an organization entry and an organizational role
entry using the {{I:ldapadd}} tool, you could create an {{TERM:LDIF}}
file called {{EX:entries.ldif}} with the contents:

>	# Organization for Example Corporation
>	dn: dc=example,dc=com
>	objectClass: dcObject
>	objectClass: organization
>	dc: example
>	o: Example Corporation
>	description: The Example Corporation
>
>	# Organizational Role for Directory Manager
>	dn: cn=Manager,dc=example,dc=com
>	objectClass: organizationalRole
>	cn: Manager
>	description: Directory Manager

and then use a command like this to actually create the entry:

>	ldapadd -f entries.ldif -x -D "cn=Manager,dc=example,dc=com" -w secret

The above command assumes settings provided in the above examples.


H2: Creating a database off-line

The second method of database creation is to do it off-line, using
the slapd database tools described below. This method is best if
you have many thousands of entries to create, which would take an
unacceptably long time to add using the LDAP method described above.
These tools read the slapd configuration file and an input file
containing a text representation of the entries to add. For database
types which support the tools, they produce the database files
directly (otherwise you must use the on-line method above). There
are several important configuration options you will want to be
sure and set in the config file database definition first:

>	suffix <dn>

As described in the {{SECT:General Database Directives}} section,
this option defines which entries are to be held by this database.
You should set this to the DN of the root of the subtree you are
trying to create.  For example:

>	suffix "dc=example,dc=com"

You should be sure to specify a directory where the index files
should be created:

>	directory <directory>

For example:

>	directory /usr/local/var/openldap-data

Finally, you need to specify which indices you want to build.  This
is done by one or more index options.

>	index {<attrlist> | default} [pres,eq,approx,sub,none]

For example:

>	index cn,sn,uid pres,eq,approx,sub
>	index objectClass eq

This would create presence, equality, approximate, and substring
indices for the {{EX:cn}}, {{EX:sn}}, and {{EX:uid}} attributes and
an equality index for the {{EX:objectClass}} attribute.  Note that
not all index types are available with all attribute types.  See
{{SECT:The slapd Configuration File}} section for more information
on this option.

H3: The {{EX:slapadd}} program

Once you've configured things to your liking, you create the primary
database and associated indices by running the {{slapadd}}(8)
program:

>	slapadd -l <inputfile> -f <slapdconfigfile>
>		[-d <debuglevel>] [-n <integer>|-b <suffix>]

The arguments have the following meanings:

>	-l <inputfile>

Specifies the {{TERM:LDIF}} input file containing the entries to
add in text form (described below in the {{SECT:The LDIF text entry
format}} section).

>	-f <slapdconfigfile>

Specifies the slapd configuration file that tells where to create
the indices, what indices to create, etc.

>	-F <slapdconfdirectory>

Specifies a config directory.  If both {{EX:-f}} and {{EX:-F}} are specified, 
the config file will be read and converted to config  directory format and 
written to the specified directory.  If neither option is specified, an attempt 
to read the default config directory will be made before trying to use the 
default config file. If a valid config directory exists then the default 
config file is ignored. If dryrun mode is also specified, no conversion will occur.

>	-d <debuglevel>

Turn on debugging, as specified by {{EX:<debuglevel>}}. The debug
levels are the same as for slapd.  See the {{SECT:Command-Line
Options}} section in {{SECT:Running slapd}}.

> 	-n <databasenumber>

An optional argument that specifies which database to modify.  The
first database listed in the configuration file is {{EX:1}}, the
second {{EX:2}}, etc. By default, the first database in the
configuration file is used. Should not be used in conjunction with
{{EX:-b}}.

>	-b <suffix>

An optional argument that specifies which database to modify.  The
provided suffix is matched against a database {{EX:suffix}} directive
to determine the database number. Should not be used in conjunction
with {{EX:-n}}.


H3: The {{EX:slapindex}} program

Sometimes it may be necessary to regenerate indices (such as after
modifying {{slapd.conf}}(5)). This is possible using the {{slapindex}}(8)
program.  {{slapindex}} is invoked like this

>	slapindex -f <slapdconfigfile>
>		[-d <debuglevel>] [-n <databasenumber>|-b <suffix>]

Where the {{EX:-f}}, {{EX:-d}}, {{EX:-n}} and {{EX:-b}} options
are the same as for the {{slapadd}}(1) program.  {{slapindex}}
rebuilds all indices based upon the current database contents.


H3: The {{EX:slapcat}} program

The {{EX:slapcat}} program is used to dump the database to an
{{TERM:LDIF}} file.  This can be useful when you want to make a
human-readable backup of your database or when you want to edit
your database off-line.  The program is invoked like this:

>	slapcat -l <filename> -f <slapdconfigfile>
>		[-d <debuglevel>] [-n <databasenumber>|-b <suffix>]

where {{EX:-n}} or {{EX:-b}} is used to select the database in the
{{slapd.conf}}(5) specified using {{EX:-f}}.  The corresponding
{{TERM:LDIF}} output is written to standard output or to the file
specified using the {{EX:-l}} option.


!if 0
H3: The {{EX:ldif}} program

The {{ldif}}(1) program is used to convert arbitrary data values
to {{TERM:LDIF}} format.  This can be useful when writing a program
or script to create the LDIF file you will feed into the {{slapadd}}(8)
or {{ldapadd}}(1) program, or when writing a SHELL backend.
{{ldif}}(1) takes an attribute description as an argument and reads
the attribute value(s) from standard input.  It produces the LDIF
formatted attribute line(s) on standard output. The usage is:

> 	ldif [-b] <attrdesc>

where {{EX:<attrdesc>}} is an attribute description. Without the
{{EX-b}} option, the {{ldif}} program will consider each line of
standard input to be a separate value of the attribute.

>	ldif description << EOF
>	 leading space
>	# leading hash mark
>	EOF

The {{EX:-b}} option can be used to force the {{ldif}} program to
interpret its input as a single raw binary value.  This option is
useful when converting binary data such as a {{EX:jpegPhoto}} or
{{EX:audio}} attribute.  For example:

>	ldif -b jpegPhoto < photo.jpeg
!endif


H2: The LDIF text entry format

The {{TERM[expand]LDIF}} (LDIF) is used to represent LDAP entries
in a simple text format.  This section provides a brief description
of the LDIF entry format which complements {{ldif}}(5) and the
technical specification {{REF:RFC2849}}.

The basic form of an entry is:

>	# comment
>	dn: <distinguished name>
>	<attrdesc>: <attrvalue>
>	<attrdesc>: <attrvalue>
>
> 	...

Lines starting with a '{{EX:#}}' character are comments.  An
attribute description may be a simple attribute type like {{EX:cn}}
or {{EX:objectClass}} or {{EX:1.2.3}} (an {{TERM:OID}} associated
with an attribute type) or may include options such as {{EX:cn;lang_en_US}}
or {{EX:userCertificate;binary}}.

A line may be continued by starting the next line with a {{single}}
space or tab character.  For example:

>	dn: cn=Barbara J Jensen,dc=example,dc=
>	 com
>	cn: Barbara J
>	  Jensen

is equivalent to:

>	dn: cn=Barbara J Jensen,dc=example,dc=com
>	cn: Barbara J Jensen

Multiple attribute values are specified on separate lines. e.g.,

>	cn: Barbara J Jensen
>	cn: Babs Jensen

If an {{EX:<attrvalue>}} contains non-printing characters or begins
with a space, a colon ('{{EX::}}'), or a less than ('{{EX:<}}'),
the {{EX:<attrdesc>}} is followed by a double colon and the base64
encoding of the value.  For example, the value "{{EX: begins with
a space}}" would be encoded like this:

>	cn:: IGJlZ2lucyB3aXRoIGEgc3BhY2U=

You can also specify a {{TERM:URL}} containing the attribute value.
For example, the following specifies the {{EX:jpegPhoto}} value
should be obtained from the file {{F:/path/to/file.jpeg}}.

>	cn:< file:///path/to/file.jpeg

Multiple entries within the same LDIF file are separated by blank
lines. Here's an example of an LDIF file containing three entries.

>	# Barbara's Entry
>	dn: cn=Barbara J Jensen,dc=example,dc=com
>	cn: Barbara J Jensen
>	cn: Babs Jensen
>	objectClass: person
>	sn: Jensen
>
>	# Bjorn's Entry
>	dn: cn=Bjorn J Jensen,dc=example,dc=com
>	cn: Bjorn J Jensen
>	cn: Bjorn Jensen
>	objectClass: person
>	sn: Jensen
>	# Base64 encoded JPEG photo
>	jpegPhoto:: /9j/4AAQSkZJRgABAAAAAQABAAD/2wBDABALD
>	 A4MChAODQ4SERATGCgaGBYWGDEjJR0oOjM9PDkzODdASFxOQ
>	 ERXRTc4UG1RV19iZ2hnPk1xeXBkeFxlZ2P/2wBDARESEhgVG
>
>	# Jennifer's Entry
>	dn: cn=Jennifer J Jensen,dc=example,dc=com
>	cn: Jennifer J Jensen
>	cn: Jennifer Jensen
>	objectClass: person
>	sn: Jensen
>	# JPEG photo from file
>	jpegPhoto:< file:///path/to/file.jpeg

Notice that the {{EX:jpegPhoto}} in Bjorn's entry is base 64 encoded
and the {{EX:jpegPhoto}} in Jennifer's entry is obtained from the
location indicated by the URL.

Note: Trailing spaces are not trimmed from values in an LDIF file.
Nor are multiple internal spaces compressed. If you don't want them
in your data, don't put them there.