<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<refentry lang="en">
  <refmeta>
    <refentrytitle>ldapdb</refentrytitle>

    <manvolnum>5</manvolnum>
  </refmeta>

  <refnamediv>
    <refname>ldapdb</refname>

    <refpurpose>auxiliary property plugin</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <para>Cyrus SASL auxprop plugin to access LDAP authentication
    backends.</para>
  </refsynopsisdiv>

  <refsection>
    <title>Description</title>

    <para>This document describes configuration options for the Cyrus SASL
    auxiliary property plugin <option>ldapdb</option>.</para>

    <para>This plugin reads all user data from an OpenLDAP server. It requires
    configuration of the <option>ldapdb</option> plugin and of the LDAP
    server. The <option>ldapdb</option> plugin must name a proxy user. The
    proxy user must (also) SASL authenticate at the LDAP server. The LDAP
    server must authorize the <option>ldapdb</option> proxy user to access the
    authenticating users <parameter>userPassword</parameter>.</para>
  </refsection>

  <refsection>
    <title>Options</title>

    <para>The following configuration parameters are applicable in the context
    of the <option>ldapdb</option> plugin:</para>

    <variablelist>
      <varlistentry>
        <term><option>ldapdb_uri</option> (default: empty)</term>

        <listitem>
          <para>Specifies a whitespace-separated list of LDAP servers
          (authentication backends). Use <option>ldapi://</option>...,
          <option>ldap://</option>... or <option>ldaps://</option>... to
          specify how the servers should be contacted.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>ldapdb_id</option> (default: empty)</term>

        <listitem>
          <para>Specifies the proxy user name (authentication id) who logs
          into the LDAP server in order to retrieve the authenticating users
          <parameter>userPassword</parameter>.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>ldapdb_mech</option> (default: empty)</term>

        <listitem>
          <para>Sets the SASL mechanism the <option>ldapdb</option> plugin
          (client) should use when it SASL connects to the LDAP server.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>ldapdb_pw</option> (default: empty)</term>

        <listitem>
          <para>Specifies the password used by
          <parameter>ldapdb_id</parameter>. The password must be written in
          cleartext.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>ldapdb_rc</option> (default: empty)</term>

        <listitem>
          <para>Specifies a path to a file that contains configuration options
          to override system-wide defaults when running ldap clients (see
          also: <citerefentry>
              <refentrytitle>ldap.conf</refentrytitle>

              <manvolnum>5</manvolnum>
            </citerefentry>).</para>

          <para>The main purpose behind this option is to drop transmission of
          <parameter>ldapdb_pw</parameter> in favor of a client TLS
          certificate specified in <parameter>ldapdb_rc</parameter>, so that
          SASL/EXTERNAL may be used between the ldapdb plugin and the LDAP
          server.</para>

          <note>
            <para>This is the most optimal way to use the ldapdb plugin when
            the servers are on separate machines - the connection is encrypted
            and password transmission is not necessary because the client is
            identified by its TLS client certificate.</para>
          </note>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>ldapdb_starttls</option> (default: empty)</term>

        <listitem>
          <para>Enable encrypted communication using StartTLS. Valid options
          are:</para>

          <variablelist>
            <varlistentry>
              <term><option>try</option></term>

              <listitem>
                <para>StartTLS encrypted communication is attempted. If it
                fails the client communicates unencrypted.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><option>demand</option></term>

              <listitem>
                <para>StartTLS encrypted communication is required. If it
                fails the client aborts the connection.</para>
              </listitem>
            </varlistentry>
          </variablelist>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsection>

  <refsection>
    <title>Example</title>

    <para>The following example shows a typical <option>ldapdb</option>
    configuration.</para>

    <programlisting>pwcheck_method: auxprop
auxprop_plugin: ldapdb
mech_list: PLAIN LOGIN NTLM CRAM-MD5 DIGEST-MD5
ldapdb_uri: ldap://localhost ldaps://ldap.example.com
ldapdb_id: proxyuser
ldapdb_pw: proxypass
ldapdb_mech: DIGEST-MD5</programlisting>
  </refsection>

  <refsection>
    <title>See also</title>

    <para><citerefentry>
        <refentrytitle>authdaemond</refentrytitle>

        <manvolnum>5</manvolnum>
      </citerefentry>, <citerefentry>
        <refentrytitle>ldapdb</refentrytitle>

        <manvolnum>5</manvolnum>
      </citerefentry>, <citerefentry>
        <refentrytitle>libsasl</refentrytitle>

        <manvolnum>5</manvolnum>
      </citerefentry>, <citerefentry>
        <refentrytitle>saslauthd</refentrytitle>

        <manvolnum>8</manvolnum>
      </citerefentry>, <citerefentry>
        <refentrytitle>saslauthd.conf</refentrytitle>

        <manvolnum>5</manvolnum>
      </citerefentry>, <citerefentry>
        <refentrytitle>saslpasswd2</refentrytitle>

        <manvolnum>5</manvolnum>
      </citerefentry>, <citerefentry>
        <refentrytitle>sasldblistusers2</refentrytitle>

        <manvolnum>5</manvolnum>
      </citerefentry>, <citerefentry>
        <refentrytitle>sasldb</refentrytitle>

        <manvolnum>5</manvolnum>
      </citerefentry>, <citerefentry>
        <refentrytitle>sql</refentrytitle>

        <manvolnum>5</manvolnum>
      </citerefentry></para>
  </refsection>

  <refsection>
    <title>Readme files</title>

    <para><filename>README.Debian</filename></para>
  </refsection>

  <refsection>
    <title>Author</title>

    <para>This manual was written for the Debian distribution because the
    original program does not have a manual page. Parts of the documentation
    have been taken from the Cyrus SASL's
    <filename>options.html</filename>.</para>

    <para><address>Patrick Ben Koetter
<email>p@state-of-mind.de</email></address></para>
  </refsection>
</refentry>