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
|
Notes about Debian's slapd package
----------------------------------
Please see the bottom of this file for the ways in which the Debian
OpenLDAP packages differ from the upstream OpenLDAP releases. Please
report any bugs that may be related to those changes to Debian via
reportbug and not to upstream; upstream is not responsible for changes
made in the Debian package.
In addition to the man pages shipped with this package, please consult
the OpenLDAP Admin Guide for more information, including configuration
examples for common use cases. <http://www.openldap.org/doc/admin24/>
Initial slapd configuration
Upon installation the slapd package performs a number of tasks. It
initializes the configuration database, stored in LDAP and rooted at
the DN "cn=config". It creates an initial directory database with a
DN rooted at a suffix derived from the DNS domain configured in
debconf (e.g. "dc=example,dc=com"). The default backend for the
directory database is the MDB backend. The root (administrative) DN
is set to "cn=admin,<suffix>". The root password is set to the
password configured in debconf, or a randomly generated password if
none was set.
If desired, a new configuration and directory database can be
created by running, as root:
dpkg-reconfigure slapd
Caution: this command completely resets the configuration and all
LDAP directory data (saving a backup in /var/backups), resetting
slapd to a new initial state.
The configuration database ("cn=config") and directory database
("dc=<domain>,dc=<tld>") have different permissions. Upon
installation, the Unix root user has permission to manage the slapd
configuration ("cn=config") database. The LDAP directory manager
("cn=admin,<suffix>") has permission to manage the directory database
("dc=<domain>,dc=<tld>"). This policy is specific to Debian.
Maintaining the slapd configuration
Since version 2.4.23-3 the default configuration of OpenLDAP has
been changed to "/etc/ldap/slapd.d"; configuration is stored in an
LDAP directory. The OpenLDAP packages in Debian provide an
automatic migration to the new configuration style. With the new
configuration style it is possible to change values on the fly
without restarting slapd. Changes are made through the use of ldif
files and ldap{add,modify}.
Debian defaults to granting the Unix root user, and only the Unix
root user, administrative privileges to the configuration database.
The configuration database is stored in LDAP. Administrative
privileges to the configuration database are granted to root when
the special SASL mechanism "EXTERNAL" is used for authentication.
The OpenLDAP client command option for this is "-Y EXTERNAL".
You can use the following shell command, as root, to search the
configuration:
ldapsearch -Y EXTERNAL -H ldapi:/// -b "cn=config"
To modify configuration use the command:
ldapmodify -Y EXTERNAL -H ldapi:/// -f <file.ldif>
For configuration options see the several manpages that exist or the
documentation provided upstream.
To change the directory administrator's password, the olcRootPW
attribute of the database configuration must be updated. The new
password should be hashed using the slappasswd(8) command. Then, the
root user should update the attribute using ldapmodify(1):
ldapmodify -H ldapi:// -Y EXTERNAL << EOF
dn: olcDatabase={1}mdb,cn=config
changetype: modify
replace: olcRootPW
olcRootPW: <new hashed password>
EOF
Versions of slapd before 2.4.51+dfsg-1 additionally created a database
entry named the same as the rootDN (cn=admin,<suffix>) and having the
same password. If this entry exists in your directory, its password
must also be updated using ldappasswd(1), otherwise the old password
can still be used.
Using the MDB Backend
MDB is a new database backend using the LMDB library created by the
OpenLDAP developers. The MDB backend has fewer configuration
parameters than HDB/BDB and generally does not require hand tuning.
The database is stored in a sparse file with a specified maximum size.
The size should be set larger than the database is ever anticipated to
grow, but can be increased later if needed. When the MDB backend is
chosen during initial configuration, the Debian package configures the
automatically created database with a maximum size of 1 GiB.
The space currently used by the database can be found using du(1); for
example: du -h /var/lib/ldap/data.mdb
Using BDB/HDB Backends
HDB was the recommended backend before MDB was developed. It's the
same as BDB but allows some additional operations.
slapd BDB and HDB backends rely on libdb to store data on your disks.
libdb uses a configuration file to tune database specific
parameters. This file is called DB_CONFIG, and should be created in each
directory containing one of your ldap databases, usually /var/lib/ldap.
It is VERY IMPORTANT to correctly setup a DB_CONFIG file. It is not
just a matter of performance: depending on the version of slapd and
libdb being used, your slapd may just hang and stop answering queries.
To correctly set up your DB_CONFIG file, please refer to
README.DB_CONFIG.gz in this directory.
BerkeleyDB Version
slapd has been built against version 5.3.28 of BerkeleyDB.
slapd will automatically handle database recovery, so you generally do
not need the BerkeleyDB utilities. However, if you want to perform
other operations directly on the raw database without using the slapd
tools, install db5.3-util and use those BerkeleyDB utilities. Utilities
from other db*-util packages will not work correctly and may render the
database unusable by slapd.
BerkeleyDB database format upgrades
When upgrading slapd to a new version where the Berkeley DB library's
storage format has changed, the database has to be backed up using
slapcat(8) before upgrading and restored using slapadd(8) afterwards.
Normally the maintainer scripts will handle this automatically,
performing the dump and restore as needed.
If, after upgrading, slapd fails to start and you see the message
"Program version doesn't match environment version" in syslog, then
the DB version may have changed without a dump and reload. This should
be reported as a bug in the slapd package. In this case you will have
to downgrade slapd to the previous version as the new tools are unable
to dump the old database, and the same error would prevent you from
upgrading to the fixed version. Old package versions can be
found at <http://snapshot.debian.org> if needed.
Logging
slapd logs to the facility local4. If you want to direct slapd's logs to
a separate log file, add a line like:
local4.debug /var/log/slapd.log
to /etc/syslog.conf. You may also want to add ";local4.none" to the
catch-all entry that logs to /var/log/messages so that it doesn't
continue to receive slapd logs.
SASL Configuration
To enable GSSAPI (Kerberos) authentication to slapd, install either the
libsasl2-modules-gssapi-mit or libsasl2-modules-gssapi-heimdal packages
depending on which Kerberos implementation you want to use.
SASL configuration files may be placed either in /usr/lib/sasl2 (the
standard path, but not a great place for configuration files) or in
/etc/ldap/sasl2. A SASL configuration file should be named after the
program that will use it. So, for instance, to configure SASL for
slapd, create a file named slapd.conf in /etc/ldap/sasl2 or in
/usr/lib/sasl2.
TCP Wrappers
The Debian slapd package is compiled with TCP wrappers. This means that
you are able to restrict access to the LDAP server using /etc/hosts.deny
or /etc/hosts.allow.
Running slapd under a Different UID/GID
By default, slapd runs as openldap in the openldap group. Keeping the
default is easiest. If for some reason you need to run slapd as a
different user:
- Create the user/group for slapd -- usually:
adduser --system --group <group> --disabled-login <user>
- Stop slapd:
/etc/init.d/slapd stop
- Tell slapd to run under a different UID by editing /etc/default/slapd
and setting SLAPD_USER and SLAPD_GROUP. (For example,
SLAPD_USER="ldap", SLAPD_GROUP="ldap")
- Tell linux slapd can access all database files -- usually:
chown -R <user>:<group> /var/lib/ldap
- Tell linux slapd can access configuration files -- usually:
chown -R <user>:<group> /etc/ldap/slapd.d
- Tell linux slapd can access /var/run/slapd and write a PID file:
chgrp <group> /var/run/slapd
chmod 0770 /var/run/slapd
- Start slapd -- /etc/init.d/slapd start
Once you have done so, remember to always run any utilities that access
or update the database (such as slapadd) as the same user that slapd is
running as. If you forget, you will need to redo the chown noted above.
If slapd Depends on Other Service
In the event that you are running slapd with a different back-end module
that depends on other programs (such as an SQL database) you may need to
adjust the runlevels of slapd to start after the SQL database.
Creating NSS Flat Files from LDAP
If you have need to create passwd/shadow/etc files from an LDAP
directory there is now a script included with these Debian packages
which may help you. The script is in /usr/share/slapd/ and is named
ldiftopasswd. In general you should be able to do:
ldapsearch | ldiftopasswd
and it will generate the files for you. You will need appropriate
privileges, of course, and appropriate arguments to ldapsearch.
Modifications Compared to Upstream
Compared to stock OpenLDAP as shipped by the OpenLDAP project, the
Debian packages make the following modifications. If you see any
problems caused by or related to these modifications, please report them
via the Debian bug tracking system using reportbug, not to the OpenLDAP
project.
* The only LDAP library installed is libldap_r, which in the upstream
release is only used for slapd, and libldap is a symlink to it. This
library has thread safety for use with slapd, but that thread safety
is not checked for any application other than slapd by upstream.
Upstream does not support using libldap_r for programs other than
slapd. The current library installation strategy in the Debian
packages is an attempt to deal with problems caused by symbol
conflicts between libldap and libldap_r when both are pulled in by the
same process (most commonly by libnss-ldap) and the number of packages
that use libldap in threaded code expecting thread safety.
* libldap and libber have symbol versioning added to prevent problems
during partial upgrades from older versions of the libraries.
* slapindex has been patched to warn when run as root and the man page
has been patched to notify users that slapindex should be run as the
user slapd runs as. There is some upstream discussion of a better
fix.
* slapd is configured to look in /etc/ldap/sasl2 in addition to
/usr/lib/sasl2 for SASL configuration files.
* The libldap library is patched to add two functions used by
evolution-exchange for NTLM authentication to Active Directory. See
<http://bugs.debian.org/457374>.
* Several paths have been adjusted to fit Debian file permissions and
for Filesystem Hierarchy Standard compliance, namely:
- The ldapi socket is in /var/run/slapd
- The slapi error log has been moved to /var/log/slapi-errors
- The slapd database location is /var/lib/ldap
In addition, upstream patches from CVS may be applied to fix bugs in the
current release and will not be noted here unless they're not expected
to be in the next release.
Finally, note that the Debian OpenLDAP packages have been compiled
against GnuTLS instead of OpenSSL to avoid licensing problems for
GPL-covered packages that use the LDAP libraries. This is a supported
configuration, but it's not widely used outside of Debian.
For the exact patches applied to the upstream source and references to
the relevant upstream ITS numbers, Debian bugs, and upstream
synchronization status, see the debian/patches directory in the
openldap source package.
-- Russ Allbery <rra@debian.org>, Thu, 14 Feb 2008 18:47:07 -0800
Unsafe access control rule installed by default in previous versions
Versions of slapd before 2.4.40-1 configured the default database with
an access control rule of the form:
to *
by self write
by dn="cn=admin,dc=example,dc=com" write
by * read
Depending on how the database and client applications are configured,
users might be able to impersonate others by editing attributes such
as their Unix user and group numbers, or other application-specific
attributes.
New installations no longer include "by self write", but existing
configurations will not be automatically modified.
To list your current access control rules, use the command:
ldapsearch -Y EXTERNAL -H ldapi:/// -b 'cn=config' '(olcAccess=*)' olcAccess
To fix the problem, create an LDIF file to replace the rules as
needed. For example:
dn: olcDatabase={1}hdb,cn=config
delete: olcAccess
olcAccess: {2}
-
add: olcAccess
olcAccess: {2}to * by dn="cn=admin,dc=example,dc=com" write by * read
Adjust the database DN, the administrative DN, and the rule numbers
according to your configuration, following the output from ldapsearch.
Next, apply the configuration changes from the file:
ldapmodify -Y EXTERNAL -H ldapi:/// -f mods.ldif
For more information about access control rules, refer to the
slapd.access(5) man page.
-- Ryan Tandy <ryan@nardis.ca>, Mon, 20 Oct 2014 11:45:20 -0700
|