path: root/debian/slapd.README.Debian

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