diff options
Diffstat (limited to 'debian/slapd.README.Debian')
| -rw-r--r-- | debian/slapd.README.Debian | 380 |
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 |