source: postlfs/security/cyrus-sasl.xml@ a273763

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../../general.ent">
  %general-entities;

  <!ENTITY cyrus-sasl-download-http "http://ftp.andrew.cmu.edu/pub/cyrus-mail/cyrus-sasl-&cyrus-sasl-version;.tar.gz ">
  <!ENTITY cyrus-sasl-download-ftp  "ftp://ftp.andrew.cmu.edu/pub/cyrus-mail/cyrus-sasl-&cyrus-sasl-version;.tar.gz">
  <!ENTITY cyrus-sasl-md5sum        "45dde9d19193ae9dd388eb68b2027bc9">
  <!ENTITY cyrus-sasl-size          "1.5 MB">
  <!ENTITY cyrus-sasl-buildsize     "14 MB">
  <!ENTITY cyrus-sasl-time          "0.2 SBU">
]>

<sect1 id="cyrus-sasl" xreflabel="Cyrus SASL-&cyrus-sasl-version;">
  <?dbhtml filename="cyrus-sasl.html"?>

  <sect1info>
    <othername>$LastChangedBy$</othername>
    <date>$Date$</date>
  </sect1info>

  <title>Cyrus SASL-&cyrus-sasl-version;</title>

  <indexterm zone="cyrus-sasl">
    <primary sortas="a-Cyrus-SASL">Cyrus SASL</primary>
  </indexterm>

  <sect2 role="package">
    <title>Introduction to Cyrus SASL</title>

    <para>The <application>Cyrus SASL</application> package contains a Simple
    Authentication and Security Layer, a method for adding authentication
    support to connection-based protocols. To use SASL, a protocol includes a
    command for identifying and authenticating a user to a server and for
    optionally negotiating protection of subsequent protocol interactions. If
    its use is negotiated, a security layer is inserted between the protocol
    and the connection.</para>

    <bridgehead renderas="sect3">Package Information</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>Download (HTTP): <ulink url="&cyrus-sasl-download-http;"/></para>
      </listitem>
      <listitem>
        <para>Download (FTP): <ulink url="&cyrus-sasl-download-ftp;"/></para>
      </listitem>
      <listitem>
        <para>Download MD5 sum: &cyrus-sasl-md5sum;</para>
      </listitem>
      <listitem>
        <para>Download size: &cyrus-sasl-size;</para>
      </listitem>
      <listitem>
        <para>Estimated disk space required: &cyrus-sasl-buildsize;</para>
      </listitem>
      <listitem>
        <para>Estimated build time: &cyrus-sasl-time;</para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">Cyrus SASL Dependencies</bridgehead>

    <bridgehead renderas="sect4">Required</bridgehead>
    <para role="required"><xref linkend="openssl"/></para>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional"><xref linkend="linux-pam"/>,
    <xref linkend="openldap"/>,
    <xref linkend="heimdal"/> or <xref linkend="mitkrb"/>,
    <xref linkend="jdk"/>,
    <xref linkend="mysql"/>,
    <xref linkend="postgresql"/>,
    <!-- <xref linkend="db"/>, -->
    <xref linkend="gdbm"/>,
    <!-- <xref linkend="courier"/>,  -->
    <ulink url="http://www.pdc.kth.se/kth-krb/">krb4</ulink>,
    <ulink url="http://sqlite.org/">SQLite</ulink>, and
    <ulink url="http://dmalloc.com/">Dmalloc</ulink></para>

    <para condition="html" role="usernotes">User Notes:
    <ulink url="&blfs-wiki;/cyrus-sasl"/></para>

  </sect2>

  <sect2 role="installation">
    <title>Installation of Cyrus SASL</title>

    <para>Install <application>Cyrus SASL</application> by
    running the following commands:</para>

<screen><userinput>patch -Np1 -i ../cyrus-sasl-&cyrus-sasl-version;-openldap23-1.patch &amp;&amp;
./configure --prefix=/usr --sysconfdir=/etc \
            --with-dbpath=/var/lib/sasl/sasldb2 \
            --with-saslauthd=/var/run/saslauthd &amp;&amp;
make</userinput></screen>

    <para>This package does not come with a test suite. If you are planning
    on using the GSSAPI authentication mechanism, it is recommended to test
    it after installing the package using the sample server and client programs
    which were built in the preceding step. Instructions for performing the
    tests can be found at <ulink
    url="&hints-root;/downloads/files/cyrus-sasl.txt"/>.</para>

    <para>Now, as the <systemitem class="username">root</systemitem> user:</para>

<screen role="root"><userinput>make install &amp;&amp;
install -v -m755 -d /usr/share/doc/cyrus-sasl-&cyrus-sasl-version; &amp;&amp;
install -v -m644 doc/{*.{html,txt,fig},ONEWS,TODO} \
    saslauthd/LDAP_SASLAUTHD /usr/share/doc/cyrus-sasl-&cyrus-sasl-version; &amp;&amp;
install -v -m700 -d /var/lib/sasl /var/run/saslauthd</userinput></screen>

  </sect2>

  <sect2 role="commands">
    <title>Command Explanations</title>

    <para><parameter>--with-dbpath=/var/lib/sasl/sasldb2</parameter>: This
    parameter forces the <command>sasldb</command> database to be created
    in <filename class='directory'>/var/lib/sasl</filename> instead of
    <filename class='directory'>/etc</filename>.</para>

    <para><parameter>--with-saslauthd=/var/run/saslauthd</parameter>: This
    parameter forces <command>saslauthd</command> to use the FHS compliant
    directory <filename class='directory'>/var/run/saslauthd</filename> for
    variable run-time data.</para>

    <para><parameter>--with-dblib=gdbm</parameter>: This parameter forces
    <application>GDBM</application> to be used instead of
    <application>Berkeley DB</application>.</para>

    <para><option>--with-ldap</option>: This parameter enables use
    with <application>OpenLDAP</application>.</para>

    <para><option>--enable-ldapdb</option>: This parameter enables the
    LDAPDB authentication backend. There is a circular dependency with this
    parameter. See <ulink url="&blfs-wiki;/cyrus-sasl"/> for a solution to
    this problem.</para>

    <para><command>install -v -m644 ...</command>: These commands
    install documentation which is not installed by the
    <command>make install</command> command.</para>

    <para><command>install -v -m700 -d /var/lib/sasl /var/run/saslauthd</command>:
    These directories must exist when starting <command>saslauthd</command> or
    using the sasldb plugin. If you're not going to be running the daemon or
    using the plugins, you may omit the creation of this directory.</para>

  </sect2>

  <sect2 role="configuration">
    <title>Configuring Cyrus SASL</title>

    <sect3 id="cyrus-sasl-config">
      <title>Config Files</title>

      <para><filename>/etc/saslauthd.conf</filename> (for
      <command>saslauthd</command> LDAP configuration)
      and <filename>/etc/sasl2/Appname.conf</filename> (where "Appname"
      is the application defined name of the application)</para>

      <indexterm zone="cyrus-sasl cyrus-sasl-config">
        <primary sortas="e-etc-saslauthd.conf">/etc/saslauthd.conf</primary>
      </indexterm>

    </sect3>

    <sect3>
      <title>Configuration Information</title>

      <para>See <ulink
      url="file:///usr/share/doc/cyrus-sasl-&cyrus-sasl-version;/sysadmin.html"/>
      for information on what to include in the application configuration files.
      See <ulink
      url="file:///usr/share/doc/cyrus-sasl-&cyrus-sasl-version;/LDAP_SASLAUTHD"/>
      for configuring <command>saslauthd</command> with
      <application>OpenLDAP</application>.</para>

    </sect3>

    <sect3 id="cyrus-sasl-init">
      <title>Init Script</title>

      <para>If you need to run the <command>saslauthd</command> daemon at system
      startup, install the <filename>/etc/rc.d/init.d/cyrus-sasl</filename>
      init script included in the <xref linkend="bootscripts"/>
      package.</para>

      <indexterm zone="cyrus-sasl cyrus-sasl-init">
        <primary sortas="f-cyrus-sasl-init">cyrus-sasl</primary>
      </indexterm>

<screen role="root"><userinput>make install-cyrus-sasl</userinput></screen>

      <note>
        <para>You'll need to modify the init script and replace the
        <option><replaceable>&lt;authmech&gt;</replaceable></option> parameter
        to the <option>-a</option> switch with your desired authentication
        mechanism.</para>
      </note>

    </sect3>

  </sect2>

  <sect2 role="content">
    <title>Contents</title>

    <segmentedlist>
      <segtitle>Installed Programs</segtitle>
      <segtitle>Installed Libraries</segtitle>
      <segtitle>Installed Directories</segtitle>

      <seglistitem>
        <seg>saslauthd, sasldblistusers2, and saslpasswd2</seg>
        <seg>libjavasasl.so, libsasl2.so, and numerous SASL plugins and
        Java classes</seg>
        <seg>/usr/include/sasl, /usr/lib/java/classes/sasl, /usr/lib/sasl2,
        /usr/share/doc/cyrus-sasl-&cyrus-sasl-version;, and /var/lib/sasl</seg>
      </seglistitem>
    </segmentedlist>

    <variablelist>
      <bridgehead renderas="sect3">Short Descriptions</bridgehead>
      <?dbfo list-presentation="list"?>
      <?dbhtml list-presentation="table"?>

      <varlistentry id="saslauthd">
        <term><command>saslauthd</command></term>
        <listitem>
          <para>is the SASL authentication server.</para>
          <indexterm zone="cyrus-sasl saslauthd">
            <primary sortas="b-saslauthd">saslauthd</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="sasldblistusers2">
        <term><command>sasldblistusers2</command></term>
        <listitem>
          <para>is used to list the users in the SASL password database
          <filename>sasldb2</filename>.</para>
          <indexterm zone="cyrus-sasl sasldblistusers2">
            <primary sortas="b-sasldblistusers2">sasldblistusers2</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="saslpasswd2">
        <term><command>saslpasswd2</command></term>
        <listitem>
          <para>is used to set and delete a user's SASL password and
          mechanism specific secrets in the SASL password database
          <filename>sasldb2</filename>.</para>
          <indexterm zone="cyrus-sasl saslpasswd2">
            <primary sortas="b-saslpasswd2">saslpasswd2</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libsasl2">
        <term><filename class='libraryfile'>libsasl2.so</filename></term>
        <listitem>
          <para>is a general purpose authentication library for server and
          client applications.</para>
          <indexterm zone="cyrus-sasl libsasl2">
            <primary sortas="c-libsasl2">libsasl2.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>