<?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 id="auxprop-sql.5">
  <refentryinfo>
    <title>Cyrus SASL sql auxprop plugin</title>
  </refentryinfo>

  <refmeta>
    <refentrytitle>sql</refentrytitle>

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

  <refnamediv>
    <refname>sql</refname>

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

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

  <refsection>
    <title>Description</title>

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

    <para><option>sql</option> is a generic plugin for various SQL backends.
    Currently it provides access to either MySQL, PostgreSQL or SQLite
    databases.</para>

    <note>
      <para>The plugin requires that passwords in the database are stored in
      plaintext format in order to use shared-secret mechanisms.</para>
    </note>
  </refsection>

  <refsection>
    <title>Configuration Syntax</title>

    <para>The following syntax is mandatory for <option>sql</option> plugin
    configuration:</para>

    <itemizedlist>
      <listitem>
        <para>SQL statements specified with <parameter>sql_select</parameter>,
        <parameter>sql_select</parameter> and
        <parameter>sql_select</parameter> must not be enclosed in
        quotes.</para>
      </listitem>

      <listitem>
        <para>Macros, e.g. <option>%u</option>, <option>%r</option> and
        <option>%v</option>, specified within SQL statements must be quoted
        individually.</para>
      </listitem>
    </itemizedlist>

    <para>See <xref linkend="example" /> for a valid configuration
    example.</para>
  </refsection>

  <refsection>
    <title>Options</title>

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

    <variablelist>
      <varlistentry>
        <term><parameter>sql_engine</parameter> (default:
        <option>mysql</option>)</term>

        <listitem>
          <para>Specifies the type of SQL engine to use for connections to the
          SQL backend. The following types are available:</para>

          <variablelist>
            <varlistentry>
              <term><option>mysql</option></term>

              <listitem>
                <para>Enables the mysql driver for connections to a MySQL
                server.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><option>pgsql</option></term>

              <listitem>
                <para>Enables the pgsql driver for connections to a PostgreSQL
                server.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><option>sqlite</option></term>

              <listitem>
                <para>Enables the sqlite driver for connections to a SQLite
                server.</para>
              </listitem>
            </varlistentry>
          </variablelist>
        </listitem>
      </varlistentry>

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

        <listitem>
          <para>A comma-separated list of one or more SQL servers the plugin
          should try to connect to and query from. Specify servers separated
          in <literal>hostname[:port]</literal> format.</para>

          <note>
            <para>Specify <systemitem class="server">localhost</systemitem>
            when using the MySQL engine to communicate over a UNIX domain
            socket and <systemitem class="ipaddress">127.0.0.1</systemitem> to
            attempt a connection that uses a TCP socket.</para>
          </note>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><parameter>sql_user</parameter> (default empty)</term>

        <listitem>
          <para>Configures the username the plugin will send when it
          authenticates to the SQL server.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><parameter>sql_passwd</parameter> (defaults: empty)</term>

        <listitem>
          <para>Configures the password the plugin will send when it
          authenticates to the SQL server.</para>
        </listitem>
      </varlistentry>

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

        <listitem>
          <para>Specifies the name of the database which contains auxiliary
          properties (e.g. username, realm, password etc.)</para>
        </listitem>
      </varlistentry>

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

        <listitem>
          <para>Mandatory <literal>SELECT</literal> statement used to fetch
          properties from the SQL database.</para>
        </listitem>
      </varlistentry>

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

        <listitem>
          <para>Optional <literal>INSERT</literal> statement used to create
          properties for new users in the SQL database.</para>
        </listitem>
      </varlistentry>

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

        <listitem>
          <para>Optional <literal>UPDATE</literal> statement used to modify
          properties in the SQL database.</para>
        </listitem>
      </varlistentry>

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

        <listitem>
          <para>Specify either <option>yes</option>, <option>on</option>,
          <option>1</option> or <option>true</option>, and the plugin will try
          to establish a secure connection to the SQL server.</para>

          <remark>Does this really work? I remember it doesn't ...</remark>
        </listitem>
      </varlistentry>
    </variablelist>

    <refsection>
      <title>Macros</title>

      <para>The sql plugin provides macros to build
      <parameter>sql_select</parameter>, <parameter>sql_select</parameter> and
      <parameter>sql_select</parameter> statements. They will be replaced with
      arguments sent from the client. The following macros exist:</para>

      <variablelist>
        <varlistentry>
          <term>%u</term>

          <listitem>
            <para>The name of the user whose properties are being selected,
            inserted or updated.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>%p</term>

          <listitem>
            <para>The name of the property being selected, inserted or
            updated. While this could technically be anything, Cyrus SASL will
            try <parameter>userPassword</parameter> and
            <parameter>cmusaslsecret<replaceable>MECHNAME</replaceable></parameter>
            (where <replaceable>MECHNAME</replaceable> is the name of a SASL
            mechanism).</para>
          </listitem>
        </varlistentry>

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

          <listitem>
            <para>Name of the realm to which the user belongs. This could be
            the KERBEROS realm, the FQDN of the computer the SASL application
            is running on or whatever is after the @ on a username.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>%v</term>

          <listitem>
            <para>Value of the property being stored during insert or update
            operations. While this could technically be anything depending on
            the property itself, it generally is a
            <parameter>userPassword</parameter>.</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </refsection>
  </refsection>

  <refsection id="example">
    <title>Example</title>

    <para>The following example shows a typical <option>sql</option>
    configuration:</para>

    <programlisting>pwcheck_method: auxprop
auxprop_plugin: sql
mech_list: plain login cram-md5 digest-md5
sql_engine: pgsql
sql_hostnames: 127.0.0.1, 192.0.2.1
sql_user: username
sql_passwd: secret
sql_database: company
sql_select: SELECT password FROM users WHERE user = '%u'@'%r'</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>