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 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