summaryrefslogtreecommitdiffstats
path: root/debian/slapd.README.Debian
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-07 16:35:33 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-07 16:35:33 +0000
commit1f641814b2bfbbf2dc3347e11a3fe901bfdf1efc (patch)
tree77094b19bf9091ceb6f6ab7d0267f70fef9c8323 /debian/slapd.README.Debian
parentAdding upstream version 2.5.13+dfsg. (diff)
downloadopenldap-1f641814b2bfbbf2dc3347e11a3fe901bfdf1efc.tar.xz
openldap-1f641814b2bfbbf2dc3347e11a3fe901bfdf1efc.zip
Adding debian version 2.5.13+dfsg-5.debian/2.5.13+dfsg-5debian
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'debian/slapd.README.Debian')
-rw-r--r--debian/slapd.README.Debian380
1 files changed, 380 insertions, 0 deletions
diff --git a/debian/slapd.README.Debian b/debian/slapd.README.Debian
new file mode 100644
index 0000000..ff7d66b
--- /dev/null
+++ b/debian/slapd.README.Debian
@@ -0,0 +1,380 @@
+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 the former Berkeley DB backend, 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
+
+ When upgrading slapd to a new version where the database'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 the database format changes without a
+ corresponding 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.
+
+ * 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
+
+Migrating your installation to OpenLDAP 2.5.x
+
+ OpenLDAP 2.5 is a major new release and includes several incompatible
+ changes as described in the upstream ANNOUNCEMENT file. Depending on
+ your configuration, completing the upgrade from 2.4.x might require
+ manual intervention.
+
+ The package upgrade process first exports your databases to LDIF
+ format using slapcat(8), then updates the slapd package, and finally
+ imports the LDIF files using slapadd(8). If the slapadd process fails,
+ it must be completed manually after resolving whatever issues caused
+ the failure.
+
+ By default, the Debian package uses LDAP-based configuration
+ (cn=config). To resolve configuration issues with a cn=config
+ database, follow the steps below to reload the config database from an
+ LDIF file. If you use a slapd.conf configuration file, configuration
+ issues can be resolved by just editing that file.
+
+ The following steps assume your configuration database is stored in
+ the default location (/etc/ldap/slapd.d).
+
+ 1. Locate the backup LDIF file exported by the upgrade process:
+
+ /var/backups/slapd-<OLDVERSION>/cn=config.ldif
+
+ Make a copy of this file for working on.
+
+ 2. Edit your copy of cn=config.ldif to fix the issues noted by
+ slapadd, such as removed or renamed modules or backends. See below
+ for suggestions for some specific issues.
+
+ 3. Move away or delete the contents of /etc/ldap/slapd.d, so that it
+ is an empty directory.
+
+ 4. Load your edited cn=config.ldif into the cn=config database:
+
+ slapadd -F/etc/ldap/slapd.d -n0 -l /var/backups/slapd-<OLDVERSION>/cn=config.ldif
+
+ 5. If the slapadd command failed, go back to step 2.
+
+ 6. After the slapadd command succeeds, change the permissions on the
+ slapd.d directory to be owned by the openldap user:
+
+ chown -R openldap:openldap /etc/ldap/slapd.d
+
+ Now you can proceed with reloading the remaining databases. For each
+ configured database:
+
+ 1. Locate the backup LDIF file exported by the upgrade process:
+
+ /var/backups/slapd-<OLDVERSION>/<SUFFIX>.ldif
+
+ where <SUFFIX> is the database suffix such as dc=example,dc=com.
+
+ 2. Ensure the directory where the database is stored (for example
+ /var/lib/ldap) is empty. By default the upgrade process moves away
+ the database files to a directory named
+ /var/backups/<SUFFIX>-<OLDVERSION>.ldapdb.
+
+ 3. Reload the data using slapadd:
+
+ slapadd -l /var/backups/slapd-<OLDVERSION>/<SUFFIX>.ldif
+
+ 4. Make sure the slapadd command succeeded, and then change the
+ permissions on the data directory:
+
+ chown -R openldap:openldap /var/lib/ldap
+
+ After all of your databases have been reloaded successfully, you
+ should be able to start the slapd service again.
+
+Known issues for OpenLDAP 2.5.x upgrades
+
+ * BDB/HDB backends removed: migrating to LMDB backend
+
+ The slapd-bdb(5) and slapd-hdb(5) backends have been removed. These
+ were configured by default in older versions of the slapd package. If
+ you are still using one of these backends, slapadd fails with the
+ following message:
+
+ lt_dlopenext failed: (back_hdb) file not found
+
+ You have to change to the LMDB backend. Edit the exported
+ configuration LDIF as described above, and make the following changes:
+
+ 1. Change olcModuleLoad: back_bdb or back_hdb to back_mdb.
+ 2. If you have an olcBackend: bdb or hdb entry, change it to mdb, or
+ delete it if you don't have to override any global LMDB settings.
+ 2. For each configured BDB or HDB database:
+ - Change objectClass: olcBdbConfig or olcHdbConfig to olcMdbConfig.
+ Also update structuralObjectClass.
+ - Change olcDatabase: bdb or hdb to mdb. Also update the attribute
+ in the DN, for example: olcDatabase={1}mdb,cn=config.
+ - Delete any olcDbConfig attributes.
+ - Add the olcDbMaxSize attribute to set the maximum size of the
+ database, in bytes. If not configured, the default is 10 MiB.
+
+ * ppolicy schema changed to internal
+
+ The slapo-ppolicy(5) module now includes its schema compiled into the
+ module code itself. The external schema is no longer used, and
+ conflicts with the internal copy. If you have the ppolicy schema
+ loaded, slapadd fails with the following message:
+
+ olcAttributeTypes: value #0 olcAttributeTypes: Duplicate attributeType: "1.3.6.1.4.1.42.2.27.8.1.1"
+
+ Edit the exported configuration LDIF as described above. Remove the
+ entire ppolicy schema entry. That is, delete from the line like:
+
+ dn: cn={4}ppolicy,cn=schema,cn=config
+
+ all the way to the next blank line.
+
+ * argon2 module renamed
+
+ The pw-argon2 contrib passwd module was promoted to core and was
+ renamed to argon2. If your config loads the module by its old name,
+ slapadd fails with the following message:
+
+ lt_dlopenext failed: (pw-argon2) file not found
+
+ Edit the exported configuration LDIF as described above. Change
+ olcModuleLoad: pw-argon2 to argon2.
+
+ -- Ryan Tandy <ryan@nardis.ca> Sat, 14 Aug 2021 15:03:31 -0700