diff options
Diffstat (limited to 'debian/slapd.README.Debian')
| -rw-r--r-- | debian/slapd.README.Debian | 281 |
1 files changed, 281 insertions, 0 deletions
diff --git a/debian/slapd.README.Debian b/debian/slapd.README.Debian new file mode 100644 index 0000000..a5e307f --- /dev/null +++ b/debian/slapd.README.Debian @@ -0,0 +1,281 @@ +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/> + +The OpenLDAP configuration + + Since version 2.4.23-3 the configuration of OpenLDAP has been changed to + /etc/ldap/slapd.d by default. 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}. In Debian you can use the following command 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. + +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: + + chgrp <group> /etc/ldap/slapd.conf + chmod 0640 /etc/ldap/slapd.conf + + - 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. + + * libldap has been patched to work around what may be a bug in GnuTLS in + calculating the length of subjectAltName in TLS certificates. See + <http://bugs.debian.org/465197>. + + * 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 |