<?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>saslauthd.conf</refentrytitle>

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

  <refnamediv>
    <refname>saslauthd.conf</refname>

    <refpurpose>saslauthd LDAP configuration file</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <cmdsynopsis>
      <command>saslauthd</command>

      <arg>-a ldap</arg>
    </cmdsynopsis>

    <cmdsynopsis>
      <command>saslauthd</command>

      <arg>-a ldap</arg>

      <arg>-O <replaceable>/etc/saslauthd.conf</replaceable></arg>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsection>
    <title>Description</title>

    <para>This document describes LDAP configuration options for the Cyrus
    SASL password verification service <command>saslauthd</command>.</para>

    <para>By default <command>saslauthd</command> searches for LDAP
    configuration options in
    <filename>/usr/local/etc/saslauthd.conf</filename>. This location can be
    overridden if the additional command line option <option>-O</option>
    specifies an alternative path to the configuration file.</para>
  </refsection>

  <refsection>
    <title>Syntax</title>

    <para>Do not use quotes (\"\') in the parameter values.</para>
  </refsection>

  <refsection>
    <title>Options</title>

    <para>The following are available LDAP parameters. The defaults are
    probably adequate for most installations. Only
    <parameter><parameter>ldap_servers</parameter></parameter> may need to be
    specified.</para>

    <variablelist>
      <varlistentry>
        <term><parameter>ldap_auth_method</parameter> (default:
        <option>bind</option>|<option>fastbind</option>)</term>

        <listitem>
          <para>The bind method uses the LDAP bind facility to verify the
          password. The bind method is not available when
          <parameter>ldap_use_sasl</parameter> is turned on. In that case
          saslauthd will use fastbind.</para>

          <variablelist>
            <varlistentry>
              <term><option>bind</option></term>

              <listitem>
                <para><option>bind</option> is the default auth method. When
                ldap_use_sasl is enabled, 'fastbind' is the default.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><option>custom</option></term>

              <listitem>
                <para>The <option>custom</option> method uses
                <parameter>userPassword</parameter> attribute to verify the
                password. Supported hashes: <literal>crypt</literal>,
                <literal>md5</literal>, smd5, <literal>sha</literal> and
                <literal>ssha</literal>. <literal>Cleartext</literal> is
                supported as well.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><option>fastbind</option></term>

              <listitem>
                <para>The <option>fastbind</option> method - when
                <parameter>ldap_use_sasl</parameter> is <option>no</option> -
                does away with the search and an extra anonymous bind in
                auth_bind, but makes two assumptions:</para>

                <orderedlist>
                  <listitem>
                    <para>Expanding the ldap_filter expression gives the
                    user's fully-qualified DN</para>
                  </listitem>

                  <listitem>
                    <para>There is no cost to staying bound as a named
                    user</para>
                  </listitem>
                </orderedlist>
              </listitem>
            </varlistentry>
          </variablelist>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><parameter>ldap_bind_dn</parameter> (default: empty)</term>

        <listitem>
          <para>Specify <literal>DN</literal> (distinguished name) to bind to
          the LDAP directory. Do not specify this parameter for the anonymous
          bind.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><parameter>ldap_bind_pw</parameter> (default: empty)</term>

        <listitem>
          <para>An alias for <varname>ldap_password</varname>.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><parameter>ldap_default_domain</parameter> (default:
        empty)</term>

        <listitem>
          <para>An alias for <varname>ldap_default_realm</varname>.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><parameter>ldap_default_realm</parameter> (default:
        empty)</term>

        <listitem>
          <para>The default realm is assigned to the <option>%r</option> token
          when realm is not available. See <parameter>ldap_filter</parameter>
          for more.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><parameter>ldap_deref</parameter> (default: empty)</term>

        <listitem>
          <para>Specify how aliases dereferencing is handled during search.
          Should be one of <option>never</option>, <option>always</option>,
          <option>search</option>, or <option>find</option> to specify that
          aliases are never dereferenced, always dereferenced, dereferenced
          when searching, or dereferenced only when locating the base object
          for the search.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><parameter>ldap_filter</parameter> (default:
        <option>uid=%u</option>)</term>

        <listitem>
          <para>Specify a filter. The following tokens can be used in the
          filter string:</para>

          <variablelist>
            <varlistentry>
              <term><option>%%</option></term>

              <listitem>
                <para>This is replaced by a literal ’%’ character.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><option>%u</option></term>

              <listitem>
                <para><option>%u</option> is replaced by the complete user
                string.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><option>%U</option></term>

              <listitem>
                <para>If the string is an address (<option>%u</option>),
                <option>%U</option> will be replaced by the local part of that
                address.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><option>%d</option></term>

              <listitem>
                <para>If the string is an address (<option>%u</option>),
                <option>%d</option> will be replaced by the domain part of
                that address. Otherwise it will be the same as
                <option>%r</option>.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><option>%1-9</option></term>

              <listitem>
                <para>If the input key is
                <literal>user@mail.example.com</literal>, then
                <option>%1</option> is <literal>com</literal>,
                <option>%2</option> is <literal>example</literal> and
                <option>%3</option> is <literal>mail</literal>.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><option>%s</option></term>

              <listitem>
                <para><option>%s</option> is replaced by the complete service
                string.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><option>%r</option></term>

              <listitem>
                <para><option>%r</option> is replaced by the complete realm
                string.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><option>%D</option></term>

              <listitem>
                <para><option>%D</option> is replaced by the complete user DN
                (available for group checks)</para>
              </listitem>
            </varlistentry>
          </variablelist>

          <para>The <option>%u</option> token has to be used at minimum for
          the filter to be useful. If <parameter>ldap_auth_method</parameter>
          is <option>bind</option>, the filter will search for the
          <literal>DN</literal> (distinguished name) attribute. Otherwise, the
          search will look for the <parameter>ldap_password_attr</parameter>
          attribute.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><parameter>ldap_group_attr</parameter> (default:
        <option>uniqueMember</option>)</term>

        <listitem>
          <para>Specify what attribute to compare the user DN against in the
          group. If <parameter>ldap_group_dn</parameter> is not specified,
          this parameter is ignored. If
          <parameter>ldap_group_match_method</parameter> is not
          <option>attr</option>, this parameter is ignored.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><parameter>ldap_group_dn</parameter> (default: empty)</term>

        <listitem>
          <para>If specified, the user has to be part of the group in order to
          authenticate successfully. Tokens described in
          <parameter>ldap_filter</parameter> can be used for
          substitution.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><parameter>ldap_group_filter</parameter> (default: empty)</term>

        <listitem>
          <para>Specify a filter. If a filter match is found then the user is
          in the group. Tokens described in <parameter>ldap_filter</parameter>
          can be used for for substitution. If
          <parameter>ldap_group_dn</parameter> is not specified, this
          parameter is ignored. If
          <parameter>ldap_group_match_method</parameter> is not filter, this
          parameter is ignored.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><parameter>ldap_group_match_method</parameter> (default:
        <option>attr</option>)</term>

        <listitem>
          <para>If <option>attr</option> is used the group match method uses
          <parameter>ldap_group_attr</parameter> and if
          <option>filter</option> is used
          <parameter>ldap_group_search</parameter> will be used as group match
          method. If <parameter>ldap_group_dn</parameter> is not specified,
          this parameter is ignored.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><parameter>ldap_group_search_base</parameter> (default:
        <varname>ldap_search_base</varname>)</term>

        <listitem>
          <para>Specify a starting point for the group search: e.g.
          <literal>dc=example,dc=com</literal>. Tokens described in
          <parameter>ldap_filter</parameter> can be used for
          substitution.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><parameter>ldap_group_scope</parameter> (default: sub)</term>

        <listitem>
          <para>Group search scope. Options are either <option>sub</option>,
          <option>one</option> or <option>base</option>.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><parameter>ldap_password</parameter> (default: empty)</term>

        <listitem>
          <para>Specify the password for <parameter>ldap_bind_dn</parameter>
          or <parameter>ldap_id</parameter> if
          <parameter>ldap_use_sasl</parameter> is turned on. Do not specify
          this parameter for the anonymous bind.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><parameter>ldap_password_attr</parameter> (default:
        <option>userPassword</option>)</term>

        <listitem>
          <para>Specify what password attribute to use for password
          verification.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><parameter>ldap_referrals</parameter> (default:
        <option>no</option>)</term>

        <listitem>
          <para>Specify whether or not the client should follow
          referrals.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><parameter>ldap_restart</parameter> (default:
        <option>yes</option>)</term>

        <listitem>
          <para>Specify whether or not LDAP I/O operations are automatically
          restarted if they abort prematurely.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><parameter>ldap_id</parameter> (default: empty)</term>

        <listitem>
          <para>Specify the authentication ID for SASL bind.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><parameter>ldap_authz_id</parameter> (default: empty)</term>

        <listitem>
          <para>Specify the proxy authorization ID for SASL bind.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><parameter>ldap_mech</parameter> (default: empty)</term>

        <listitem>
          <para>Specify the authentication mechanism for SASL bind.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><parameter>ldap_realm</parameter> (default: empty)</term>

        <listitem>
          <para>Specify the realm of authentication ID for SASL bind.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><parameter>ldap_scope</parameter> (default:
        <option>sub</option>)</term>

        <listitem>
          <para>Search scope. Options are either <option>sub</option>,
          <option>one</option> or <option>base</option>.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><parameter>ldap_search_base</parameter> (default: empty)</term>

        <listitem>
          <para>Specify a starting point for the search: e.g.
          <literal>dc=example,dc=com</literal>. Tokens described in
          <parameter>ldap_filter</parameter> can be used for
          substitution.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><parameter>ldap_servers</parameter> (default:
        <option>ldap://localhost/</option>)</term>

        <listitem>
          <para>Specify one or more URI(s) referring to LDAP server(s), e.g.
          <literal>ldaps://10.1.1.2:999/</literal>. Multiple servers must be
          separated by space.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><parameter>ldap_start_tls</parameter> (default:
        <option>no</option>)</term>

        <listitem>
          <para>Use StartTLS extended operation. Do not use ldaps:
          ldap_servers when this option is turned on.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><parameter>ldap_time_limit</parameter> (default:
        <option>5</option>)</term>

        <listitem>
          <para>Specify a number of seconds for a search request to
          complete.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><parameter>ldap_timeout</parameter> (default:
        <option>5</option>)</term>

        <listitem>
          <para>Specify a number of seconds a search can take before timing
          out.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><parameter>ldap_tls_check_peer</parameter> (default:
        <option>no</option>)</term>

        <listitem>
          <para>Require and verify server certificate. If this option is
          <option>yes</option>, you must specify
          <parameter>ldap_tls_cacert_file</parameter> or
          <parameter>ldap_tls_cacert_dir</parameter>.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><parameter>ldap_tls_cacert_file</parameter> (default:
        empty)</term>

        <listitem>
          <para>File containing CA (Certificate Authority)
          certificate(s).</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><parameter>ldap_tls_cacert_dir</parameter> (default:
        empty)</term>

        <listitem>
          <para>Path to directory with CA (Certificate Authority)
          certificates.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><parameter>ldap_tls_ciphers</parameter> (default:
        <option>DEFAULT</option>)</term>

        <listitem>
          <para>List of SSL/TLS ciphers to allow. The format of the string is
          described in <citerefentry>
              <refentrytitle>ciphers</refentrytitle>

              <manvolnum>1</manvolnum>
            </citerefentry>.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><parameter>ldap_tls_cert</parameter> (default: empty)</term>

        <listitem>
          <para>File containing the client certificate.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><parameter>ldap_tls_key</parameter> (default: empty)</term>

        <listitem>
          <para>File containing the private client key.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><parameter>ldap_use_sasl</parameter> (default:
        <option>no</option>)</term>

        <listitem>
          <para>Use SASL bind instead of simple bind when connecting to the
          LDAP server.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><parameter>ldap_version</parameter> (default:
        <option>3</option>)</term>

        <listitem>
          <para>Specify the LDAP protocol version - either <option>2</option>
          or <option>3</option>. If <parameter>ldap_start_tls</parameter>
          and/or <parameter>ldap_use_sasl</parameter> are enabled,
          <parameter>ldap_version</parameter> will be automatically set to
          <option>3</option>.</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsection>

  <refsection>
    <title>Example</title>

    <para></para>

    <programlisting></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(s)</title>

    <para>This manual is based on notes in <filename>LDAP_SASLAUTHD</filename>
    from Igor Brezac.</para>

    <para><address>Igor Brezac
<email>Igor@ipass.net</email></address></para>

    <para>It was edited and revised for the Debian distribution because the
    original program does not have a manual page.</para>

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