summaryrefslogtreecommitdiffstats
path: root/debian/slapd.README.Debian
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-27 11:11:40 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-27 11:11:40 +0000
commit2886df93860f983d875b7d6acb418faa31491d5a (patch)
treeb596ddcbb70247c1994f3b1d8ba9e793b9788a9d /debian/slapd.README.Debian
parentAdding upstream version 2.4.57+dfsg. (diff)
downloadopenldap-debian.tar.xz
openldap-debian.zip
Adding debian version 2.4.57+dfsg-3+deb11u1.debian/2.4.57+dfsg-3+deb11u1debian
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'debian/slapd.README.Debian')
-rw-r--r--debian/slapd.README.Debian333
1 files changed, 333 insertions, 0 deletions
diff --git a/debian/slapd.README.Debian b/debian/slapd.README.Debian
new file mode 100644
index 0000000..ecec104
--- /dev/null
+++ b/debian/slapd.README.Debian
@@ -0,0 +1,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