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