source: postlfs/security/cyrus-sasl.xml@ 53d31c69

<?xml version="1.0" encoding="UTF-8"?>
<!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 "https://github.com/cyrusimap/cyrus-sasl/releases/download/cyrus-sasl-&cyrus-sasl-version;/cyrus-sasl-&cyrus-sasl-version;.tar.gz">
  <!ENTITY cyrus-sasl-download-ftp  " ">
  <!ENTITY cyrus-sasl-md5sum        "6f228a692516f5318a64505b46966cfa">
  <!ENTITY cyrus-sasl-size          "3.9 MB">
  <!ENTITY cyrus-sasl-buildsize     "28 MB">
  <!ENTITY cyrus-sasl-time          "0.2 SBU">
]>

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


  <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 implementation, 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>

    &lfs121_checked;

    <!-- To test this package at freeze, run the following command:
         testsaslauthd -u <current user> -p <password>
         after saslauthd is started. -->
    <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>

    <!-- Not needed anymore
    <bridgehead renderas="sect3">Additional Downloads</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          Required patch:
          <ulink url="&patch-root;/cyrus-sasl-&cyrus-sasl-version;-doc_fixes-1.patch"/>
        </para>
      </listitem>
      <!- -<listitem>
        <para>
          Required patch:
          <ulink url="&patch-root;/cyrus-sasl-&cyrus-sasl-version;-openssl-1.1.0-1.patch"/>
       </para>
    </listitem>- ->
    </itemizedlist>
    -->

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

    <bridgehead renderas="sect4">Recommended</bridgehead>
    <para role="recommended">
      <xref linkend="lmdb"/>
    </para>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">
      <xref linkend="linux-pam"/>,
      <xref linkend="mitkrb"/>,
      <xref linkend="mariadb"/> or <ulink url="https://www.mysql.com/">MySQL</ulink>,
      <xref linkend="openldap"/>,
      <xref linkend="postgresql"/>,
      <xref linkend="sphinx"/>,
      <xref linkend="sqlite"/>,
      &berkeley-db;,
      <ulink url="https://stuff.mit.edu/afs/net.mit.edu/project/attic/krb4/">krb4</ulink>,
      <ulink url="https://dmalloc.com/">Dmalloc</ulink>, and
      <ulink url="https://metacpan.org/pod/Pod::POM::View::Restructured">Pod::POM::View::Restructured</ulink>
    </para>

  </sect2>

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

    <note>
      <para>
        This package does not support parallel build.
      </para>
    </note>

    <!-- Without this patch, having Sphinx and/or doctools (doctools not tested)
         on the system causes an FTBFS when man pages are generated. The Sphinx
         and Docutils API has changed significantly between Sphinx-{1,2} and
         Sphinx-3.0.

    <para>
      First, fix a build failure if Sphinx or
      <xref role="nodep" linkend="docutils"/> is installed on the system:
    </para>

<screen><userinput remap="pre">patch -Np1 -i ../cyrus-sasl-2.1.27-doc_fixes-1.patch</userinput></screen>
    -->

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

<screen><userinput>./configure --prefix=/usr        \
            --sysconfdir=/etc    \
            --enable-auth-sasldb \
            --with-dblib=lmdb    \
            --with-dbpath=/var/lib/sasl/sasldb2 \
            --with-sphinx-build=no              \
            --with-saslauthd=/var/run/saslauthd &amp;&amp;
make -j1</userinput></screen>

    <para>
      This package does not come with a test suite. If you are planning
      on using the GSSAPI authentication mechanism, 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 -dm755                          /usr/share/doc/cyrus-sasl-&cyrus-sasl-version;/html &amp;&amp;
install -v -m644  saslauthd/LDAP_SASLAUTHD /usr/share/doc/cyrus-sasl-&cyrus-sasl-version;      &amp;&amp;
install -v -m644  doc/legacy/*.html        /usr/share/doc/cyrus-sasl-&cyrus-sasl-version;/html &amp;&amp;
install -v -dm700 /var/lib/sasl</userinput></screen>

  </sect2>

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

    <para>
      <parameter>--with-dbpath=/var/lib/sasl/sasldb2</parameter>: This
      switch 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
      switch 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>--enable-auth-sasldb</parameter>: This switch enables
      SASLDB authentication backend.
    </para>

    <para>
      <option>--with-dblib=gdbm</option>: This switch forces
      <application>GDBM</application> to be used instead of
      <application>LMDB</application>.
    </para>

    <para>
      <option>--with-ldap</option>: This switch enables the
      <application>OpenLDAP</application> support.
    </para>

    <para>
      <option>--enable-ldapdb</option>: This switch enables the
      LDAPDB authentication backend.
    </para>

<!-- Removed in 2.1.28
    <para>
      <option>- -enable-java</option>: This switch enables compiling of the
      <application>Java</application> support libraries.
    </para>
-->

    <para>
      <option>--enable-login</option>: This option enables unsupported
      LOGIN authentication.
    </para>

    <para>
      <option>--enable-ntlm</option>: This option enables unsupported
      NTLM authentication.
    </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</command>: This directory
      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="https://www.cyrusimap.org/sasl/sasl/sysadmin.html"/>
        for information on what to include in the application configuration files.
      </para>

      <para>
        See
        <ulink url="file:///usr/share/doc/cyrus-sasl-&cyrus-sasl-version;/LDAP_SASLAUTHD"/>
        for configuring <command>saslauthd</command> with
        <application>OpenLDAP</application>.
      </para>

      <para>
        See
        <ulink url="https://www.cyrusimap.org/sasl/sasl/gssapi.html#gssapi"/>
        for configuring <command>saslauthd</command> with <application>Kerberos</application>.
      </para>

    </sect3>

    <sect3 id="cyrus-sasl-init">
      <title><phrase revision="sysv">Init Script</phrase>
             <phrase revision="systemd">Systemd Unit</phrase></title>

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

      <para revision="systemd">
        If you need to run the <command>saslauthd</command> daemon at system
        startup, install the <filename>saslauthd.service</filename> unit
        included in the <xref linkend="systemd-units"/> package using the
        following command:
      </para>

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

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

      <note>
        <para>
          You'll need to modify
          <filename revision="sysv">/etc/sysconfig/saslauthd</filename>
          <filename revision="systemd">/etc/default/saslauthd</filename>
          and modify the
          <option revision="sysv">AUTHMECH</option>
          <option revision="systemd">MECHANISM</option>
          parameter with your desired authentication mechanism.
          <phrase revision="systemd">The default authentication
          mechanism is "shadow".</phrase>
        </para>
      </note>

    </sect3>

  </sect2>

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

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

      <seglistitem>
        <seg>
          pluginviewer, saslauthd, sasldblistusers2, saslpasswd2 and
          testsaslauthd
        </seg>
        <seg>
          libsasl2.so
        </seg>
        <seg>
          /usr/include/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="pluginviewer">
        <term><command>pluginviewer</command></term>
        <listitem>
          <para>
            is used to list loadable SASL plugins and their properties
          </para>
          <indexterm zone="cyrus-sasl pluginviewer">
            <primary sortas="b-pluginviewer">pluginviewer</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <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="testsaslauthd">
        <term><command>testsaslauthd</command></term>
        <listitem>
          <para>
            is a test utility for the SASL authentication server
          </para>
          <indexterm zone="cyrus-sasl testsaslauthd">
            <primary sortas="b-testsaslauthd">testsaslauthd</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>