<?xml version="1.0"?>
-<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/><title>Courier Authentication Library</title><link rel="stylesheet" href="style.css" type="text/css"/><meta name="generator" content="DocBook XSL Stylesheets V1.74.0"/><link rel="home" href="#authlib" title="Courier Authentication Library"/><link rel="next" href="#authpwd" title="The authpwd authentication module"/><link xmlns="" rel="stylesheet" type="text/css" href="manpage.css"/><meta xmlns="" name="MSSmartTagsPreventParsing" content="TRUE"/><link xmlns="" rel="icon" href="icon.gif" type="image/gif"/><!--
+<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/><title>Courier Authentication Library</title><link rel="stylesheet" type="text/css" href="style.css"/><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"/><link rel="home" href="#authlib" title="Courier Authentication Library"/><link rel="next" href="#authpwd" title="The authpwd authentication module"/><link xmlns="" rel="stylesheet" type="text/css" href="manpage.css"/><meta xmlns="" name="MSSmartTagsPreventParsing" content="TRUE"/><link xmlns="" rel="icon" href="icon.gif" type="image/gif"/><!--
Copyright 1998 - 2009 Double Precision, Inc. See COPYING for distribution
information.
---></head><body><div class="chapter"
lang="en" xml:lang="en"><div class="titlepage"><div><div><h1 class="title"><a id="authlib" shape="rect"> </a>Courier Authentication Library</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#authpwd" shape="rect">The <code class="literal">authpwd</code> authentication module</a></span></dt><dt><span class="sect1"><a href="#authshadow" shape="rect">The <code class="literal">authshadow</code> authentication module</a></span></dt><dt><span class="sect1"><a href="#authpam" shape="rect">The <code class="literal">authpam</code> authentication module</a></span></dt><dt><span class="sect1"><a href="#authpipe" shape="rect">The <code class="literal">authpipe</code> authentication module</a></span></dt><dt><span class="sect1"><a href="#authpipeproto" shape="rect">The <code class="literal">authpipe</code> protocol</a></span></dt><dt><span class="sect1"><a href="#authuserdb" shape="rect">The <code class="literal">authuserdb</code> authentication module</a></span></dt><dd><dl><dt><span class="sect2"><a href="#userdbprimer" shape="rect">A brief <code class="literal">userdb</code> primer</a></span></dt><dt><span class="sect2"><a href="#userdbsimple" shape="rect">A simple userdb setup</a></span></dt><dt><span class="sect2"><a href="#userdbcomplex" shape="rect">Large virtual domain farm</a></span></dt><dt><span class="sect2"><a href="#moreuserdb" shape="rect">Beyond <code class="literal">userdb</code></a></span></dt></dl></dd><dt><span class="sect1"><a href="#authmysql" shape="rect">The <code class="literal">authmysql</code> authentication module</a></span></dt><dt><span class="sect1"><a href="#authpgsql" shape="rect">The <code class="literal">authpgsql</code> authentication module</a></span></dt><dt><span class="sect1"><a href="#authldap" shape="rect">The <code class="literal">authldap</code> authentication module</a></span></dt><dt><span class="sect1"><a href="#authcustom" shape="rect"><code class="literal">authcustom</code></a></span></dt><dt><span class="sect1"><a href="#options" shape="rect">Account options</a></span></dt><dt><span class="sect1"><a href="#authtest" shape="rect">Running <span class="command"><strong>authtest</strong></span></a></span></dt><dd><dl><dt><span class="sect2"><a href="#pwchange" shape="rect">Changing account passwords</a></span></dt></dl></dd><dt><span class="sect1"><a href="#internals" shape="rect">Authentication internals</a></span></dt><dt><span class="sect1"><a href="#files" shape="rect">FILES</a></span></dt><dt><span class="sect1"><a href="#seealso" shape="rect">SEE ALSO</a></span></dt></dl></div><p>
+--></head><body><div class="chapter"
><div class="titlepage"><div><div><h1 class="title"><a id="authlib" shape="rect"> </a>Courier Authentication Library</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="#authpwd" shape="rect">The <code class="literal">authpwd</code> authentication module</a></span></dt><dt><span class="sect1"><a href="#authshadow" shape="rect">The <code class="literal">authshadow</code> authentication module</a></span></dt><dt><span class="sect1"><a href="#authpam" shape="rect">The <code class="literal">authpam</code> authentication module</a></span></dt><dt><span class="sect1"><a href="#authpipe" shape="rect">The <code class="literal">authpipe</code> authentication module</a></span></dt><dt><span class="sect1"><a href="#authpipeproto" shape="rect">The <code class="literal">authpipe</code> protocol</a></span></dt><dt><span class="sect1"><a href="#authuserdb" shape="rect">The <code class="literal">authuserdb</code> authentication module</a></span></dt><dd><dl><dt><span class="sect2"><a href="#userdbprimer" shape="rect">A brief <code class="literal">userdb</code> primer</a></span></dt><dt><span class="sect2"><a href="#userdbsimple" shape="rect">A simple userdb setup</a></span></dt><dt><span class="sect2"><a href="#userdbcomplex" shape="rect">Large virtual domain farm</a></span></dt><dt><span class="sect2"><a href="#moreuserdb" shape="rect">Beyond <code class="literal">userdb</code></a></span></dt></dl></dd><dt><span class="sect1"><a href="#authmysql" shape="rect">The <code class="literal">authmysql</code> authentication module</a></span></dt><dt><span class="sect1"><a href="#authpgsql" shape="rect">The <code class="literal">authpgsql</code> authentication module</a></span></dt><dt><span class="sect1"><a href="#authsqlite" shape="rect">The <code class="literal">authsqlite</code> authentication module</a></span></dt><dt><span class="sect1"><a href="#authldap" shape="rect">The <code class="literal">authldap</code> authentication module</a></span></dt><dt><span class="sect1"><a href="#authcustom" shape="rect"><code class="literal">authcustom</code></a></span></dt><dt><span class="sect1"><a href="#options" shape="rect">Account options</a></span></dt><dt><span class="sect1"><a href="#authtest" shape="rect">Running <span class="command"><strong>authtest</strong></span></a></span></dt><dd><dl><dt><span class="sect2"><a href="#pwchange" shape="rect">Changing account passwords</a></span></dt></dl></dd><dt><span class="sect1"><a href="#internals" shape="rect">Authentication internals</a></span></dt><dt><span class="sect1"><a href="#files" shape="rect">FILES</a></span></dt><dt><span class="sect1"><a href="#seealso" shape="rect">SEE ALSO</a></span></dt></dl></div><p>
This library is used for two purposes:</p><p>
1. Read the name of a mail account.
Determine the local account's home directory, and system userid and
The library contains several alternative authentication modules to choose
from, described below.</p><p>
The configuration file <code class="filename">@authdaemonrc@</code> contains several
-settings. The most important of them are:</p><div class="itemizedlist"><ul
type="disc"><li><p>
+settings. The most important of them are:</p><div class="itemizedlist"><ul
class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
A list of authentication modules to activate.
By default, this list includes all available authentication modules,
even if some are not actually installed at the moment.
Installing the sub-package is the only action needed to make use of it.</p><p>
The only time the list of authentication modules need to be adjusted is
when an available authentication module must be disabled for some reason.
-This should only be needed in the most unusual circumstances.</p></li><li><p>
+This should only be needed in the most unusual circumstances.</p></li><li
class="listitem"><p>
Number of authentication processes.
The default setting is to start five authentication processes, which should be
sufficient for normal usage.
Try increasing this setting if its taking too long to log into an account,
and you have determined that this is not due to a bottleneck in the whatever
-authentication database you're using (LDAP, MySQL, or PostgreSQL).</p><p>
+authentication database you're using (LDAP, MySQL, SQLite,
+or PostgreSQL).</p><p>
An authentication request must be completed within thirty seconds, otherwise
it gets rejected.
When authentication requests come in faster than all five authentication
If all the activity maxes out the CPU or I/O bandwidth,
nothing can be done about it, short
of getting another server. However if there's plenty of available CPU and
-I/O, increasing the number of processes will do the trick.</p></li></ul></div><div class="sect1"
lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="authpwd" shape="rect"> </a>The <code class="literal">authpwd</code> authentication module</h2></div></div></div><p>
+I/O, increasing the number of processes will do the trick.</p></li></ul></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="authpwd" shape="rect"> </a>The <code class="literal">authpwd</code> authentication module</h2></div></div></div><p>
This modules obtains account information and passwords from the
<code class="filename">/etc/passwd</code> file.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
This module doesn't actually read the <code class="filename">/etc/passwd</code>
file, it uses the C library's getpw() functions.
The C library implementation could use any mechanism to obtain the equivalent
-information.</p></div></div><div class="sect1"
lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="authshadow" shape="rect"> </a>The <code class="literal">authshadow</code> authentication module</h2></div></div></div><p>
+information.</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="authshadow" shape="rect"> </a>The <code class="literal">authshadow</code> authentication module</h2></div></div></div><p>
This module is a version of the <code class="literal">authpwd</code> module that
reads passwords
from <code class="filename">/etc/shadow</code> (the C library's getsp()
-functions).</p></div><div class="sect1"
lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="authpam" shape="rect"> </a>The <code class="literal">authpam</code> authentication module</h2></div></div></div><p>
+functions).</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="authpam" shape="rect"> </a>The <code class="literal">authpam</code> authentication module</h2></div></div></div><p>
This modules uses the system's PAM library
(pluggable authentication modules) for authentication.
This is, essentially, a way to use existing PAM modules for authentication.
Additional configuration steps will be required to set up
the PAM library to authenticate Courier's services.
Courier's IMAP and POP3 servers, for example, require that the
-“<span class="quote">imap</span>” and “<span class="quote">pop3</span>” PAM service to be
+<span class="quote">“<span class="quote">imap</span>”</span> and <span class="quote">“<span class="quote">pop3</span>”</span> PAM service to be
configured.</p><p>
The specific configuration steps differ from system to system.
Consult the system documentation for more information.
Some PAM libraries use
<code class="filename">pam_pwdb.so</code> instead of
<code class="filename">pam_unix.so</code>; consult the PAM library's
-documentation for more information.</p></div></div><div class="sect1"
lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="authpipe" shape="rect"> </a>The <code class="literal">authpipe</code> authentication module</h2></div></div></div><p>This is a generic plug-in module that runs an external script,
+documentation for more information.</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="authpipe" shape="rect"> </a>The <code class="literal">authpipe</code> authentication module</h2></div></div></div><p>This is a generic plug-in module that runs an external script,
or a program, in response to authentication requests.</p><p>The external program reads from stdin and writes to stdout. It
can be persistent and handle many authentication requests. Only one request
will be sent to it at a time; each authdaemon process starts its own copy of
<code class="literal">--with-pipeprog</code> configure option,
which defaults to
<code class="filename">@sysconfdir@/authlib/authProg</code>. A sample program
-is included in the courier-authlib source.</p></div><div class="sect1"
lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="authpipeproto" shape="rect"> </a>The <code class="literal">authpipe</code> protocol</h2></div></div></div><p>
+is included in the courier-authlib source.</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="authpipeproto" shape="rect"> </a>The <code class="literal">authpipe</code> protocol</h2></div></div></div><p>
authpipe uses the same protocol as authdaemon clients use to communicate
with authdaemond.</p><p>There are four possible requests: <code class="literal">PRE</code>,
<code class="literal">AUTH</code>, <code class="literal">PASSWD</code> and
<code class="literal">ENUMERATE</code>. Apart from <code class="literal">AUTH</code>, each
request is a single line terminated by newline.
-</p><div class="variablelist"><dl><dt><span class="term">PRE . <em class="replaceable"><code>authservice</code></em> <em class="replaceable"><code>username</code></em> <span class="emphasis"><em><newline></em></span></span></dt><dd><p>Look up data for an account.
+</p><div class="variablelist"><dl
class="variablelist"><dt><span class="term">PRE . <em class="replaceable"><code>authservice</code></em> <em class="replaceable"><code>username</code></em> <span class="emphasis"><em><newline></em></span></span></dt><dd><p>Look up data for an account.
<em class="replaceable"><code>authservice</code></em> identifies the service the
user is trying to use - e.g. pop3, imap, webmail etc.</p><p>If the account exists, return the account
data as a series of ATTR=value newline-terminated lines, followed by a
such as a database being down or an error occuring mid-way through
returning account data, authProg should terminate before sending
the terminating period.
- </p></dd></dl></div></div><div class="sect1"
lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="authuserdb" shape="rect"> </a>The <code class="literal">authuserdb</code> authentication module</h2></div></div></div><p>
+ </p></dd></dl></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="authuserdb" shape="rect"> </a>The <code class="literal">authuserdb</code> authentication module</h2></div></div></div><p>
This module
uses a GDBM or a DB-based
<a class="ulink" href="userdb.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">userdb</span>(8)</span></a> database.
Instead, a fast database lookup can retrieve the same information from the
database file.
Review the included manual pages, starting with
-<a class="ulink" href="userdb.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">userdb</span>(8)</span></a>, for more information.</p><div class="sect2"
lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="userdbprimer" shape="rect"> </a>A brief <code class="literal">userdb</code> primer</h3></div></div></div><p>
+<a class="ulink" href="userdb.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">userdb</span>(8)</span></a>, for more information.</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="userdbprimer" shape="rect"> </a>A brief <code class="literal">userdb</code> primer</h3></div></div></div><p>
<code class="literal">userdb</code> is a way to implement many virtual mailboxes - many
mailboxes that do not have to have a separate system userid allocated for
each one, and there is no system login associated with each mailbox.
maildirs. It should be scalable to thousands of mailboxes. It can also be
used to replace linear searches of <code class="filename">/etc/passwd</code> with a database
lookup, see
-<a class="ulink" href="
pw2userdb.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">pw2userdb</span>(8)</span></a>.</p><p>
+<a class="ulink" href="
userdb.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">userdb</span>(8)</span></a>.</p><p>
Note - you still MUST use some valid system userid and groupid that is
shared by all virtual mailboxes. Instead of allocating a single userid and
groupid per each mailbox, the same userid and groupid is used for all of
The best way to describe how <code class="literal">userdb</code> works is to try to create
one virtual mail account. As mentioned before, virtual mailboxes still need
one system account to be used for uid/gid purposes. Let's call this system
-account "vmail".</p></div><div class="sect2"
lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="userdbsimple" shape="rect"> </a>A simple userdb setup</h3></div></div></div><p>
+account "vmail".</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="userdbsimple" shape="rect"> </a>A simple userdb setup</h3></div></div></div><p>
This approach should be used if you do not have many virtual mailboxes.
It's very simple, but quickly becomes cumbersome if you administer many
virtual mailboxes.</p><p>Create an empty <code class="filename">@userdb@</code> file:</p><div class="informalexample"><pre class="programlisting" xml:space="preserve">
You may need to specify a full path to your <span class="command"><strong>maildirmake</strong></span>
program. The end result is that you created
<code class="filename">$HOME/john-example</code> in vmail's account, which
-can be thought of as a “<span class="quote">virtual home directory</span>” for
-“<span class="quote">john@example.com</span>”, that contains the account's maildir
+can be thought of as a <span class="quote">“<span class="quote">virtual home directory</span>”</span> for
+<span class="quote">“<span class="quote">john@example.com</span>”</span>, that contains the account's maildir
mailbox.</p><p>
Now, let's connect the dots here, and create an entry in
<code class="filename">@userdb@</code> for <code class="filename">john@example.com</code>:</p><div class="informalexample"><pre class="programlisting" xml:space="preserve">
installed, by default in <code class="filename">@sbindir@</code>. Replace UUU and
GGG with the userid and groupid of the vmail account. If you now look in
<code class="filename">@userdb@</code>, you will see that a new record for
-“<span class="quote">john@example.com</span>”
+<span class="quote">“<span class="quote">john@example.com</span>”</span>
has been appended to the end of the file.</p><p>
One more detail: we need to set the IMAP password for this
mailbox:</p><div class="informalexample"><pre class="programlisting" xml:space="preserve">
<code class="filename">@userdb@shadow.dat</code> only. The plain text source,
<code class="filename">@userdb@</code> is not read by Courier itself. Changes take
effect
-only when <span class="command"><strong>makeuserdb</strong></span> runs.</p></div><div class="sect2"
lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="userdbcomplex" shape="rect"> </a>Large virtual domain farm</h3></div></div></div><p>
+only when <span class="command"><strong>makeuserdb</strong></span> runs.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="userdbcomplex" shape="rect"> </a>Large virtual domain farm</h3></div></div></div><p>
The previous approach used a single flat file, <code class="filename">@userdb@</code>.
This
will work for up to a couple of hundred accounts.
</pre></div><p>
This sets the IMAP access password for this account. Finally:</p><div class="informalexample"><pre class="programlisting" xml:space="preserve">
$ makeuserdb
-</pre></div></div><div class="sect2"
lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="moreuserdb" shape="rect"> </a>Beyond <code class="literal">userdb</code></h3></div></div></div><p>
+</pre></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="moreuserdb" shape="rect"> </a>Beyond <code class="literal">userdb</code></h3></div></div></div><p>
<code class="literal">userdb</code> is a simple, straightforward solution that scales
to a couple of thousand of mail accounts, depending on the hardware.
Beyond that, one of database-based modules will need to be used,
such as
<code class="literal">authldap</code>,
<code class="literal">authmysql</code>,
+<code class="literal">authsqlite</code>,
<code class="literal">authpgsql</code>.
Since <code class="literal">userdb</code> is maintained as plain text files that
are easily parsed by a script, migrating data from userdb will not be
-difficult.</p></div></div><div class="sect1"
lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="authmysql" shape="rect"> </a>The <code class="literal">authmysql</code> authentication module</h2></div></div></div><p>
+difficult.</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="authmysql" shape="rect"> </a>The <code class="literal">authmysql</code> authentication module</h2></div></div></div><p>
This module reads
the list of mail accounts and passwords from a table in a
MySQL database.
The <code class="filename">@authmysqlrc@</code> configuration file defines the
particular details regarding the MySQL database and the schema of the
-mail account table.</p></div><div class="sect1"
lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="authpgsql" shape="rect"> </a>The <code class="literal">authpgsql</code> authentication module</h2></div></div></div><p>
+mail account table.</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="authpgsql" shape="rect"> </a>The <code class="literal">authpgsql</code> authentication module</h2></div></div></div><p>
This module reads
the list of mail accounts and passwords from a table in a
PostgreSQL database.
The <code class="filename">@authpgsqlrc@</code> configuration file defines the
particular details regarding the PostgreSQL database and the schema of the
-mail account table.</p></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="authldap" shape="rect"> </a>The <code class="literal">authldap</code> authentication module</h2></div></div></div><p>
+mail account table.</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="authsqlite" shape="rect"> </a>The <code class="literal">authsqlite</code> authentication module</h2></div></div></div><p>
+This module reads
+the list of mail accounts and passwords from a table in a
+SQLite database file.
+The <code class="filename">@authsqliterc@</code> configuration file defines the
+particular details regarding the SQLite database file and the schema of the
+mail account table.</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="authldap" shape="rect"> </a>The <code class="literal">authldap</code> authentication module</h2></div></div></div><p>
This module reads
the list of mail accounts and passwords from an LDAP directory.
The <code class="filename">@authldaprc@</code> configuration file defines the
A suggested LDAP schema can be found in the file
<code class="filename">authldap.schema</code>,
which is included in Courier authentication library's source code, and
-may be installed on your system.</p></div><div class="sect1"
lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="authcustom" shape="rect"> </a><code class="literal">authcustom</code></h2></div></div></div><p>
+may be installed on your system.</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="authcustom" shape="rect"> </a><code class="literal">authcustom</code></h2></div></div></div><p>
This is a do-nothing module where custom authentication code
can be added.
This authentication module is just a stub that doesn't really do anything.
It's purpose is to serve as a placeholder where custom authentication code
-can be easily implement.</p></div><div class="sect1"
lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="options" shape="rect"> </a>Account options</h2></div></div></div><p>
+can be easily implement.</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="options" shape="rect"> </a>Account options</h2></div></div></div><p>
The authentication library has a facility for keep arbitrary
-“<span class="quote">name=value</span>”-type settings,
-called “<span class="quote">options</span>”, for individual accounts. This feature is
+<span class="quote">“<span class="quote">name=value</span>”</span>-type settings,
+called <span class="quote">“<span class="quote">options</span>”</span>, for individual accounts. This feature is
only available with
<code class="literal">userdb</code>,
-<code class="literal">LDAP</code>, <code class="literal">MySQL</code>, and
+<code class="literal">LDAP</code>, <code class="literal">MySQL</code>, <code class="literal">SQLite</code> and
<code class="literal">PostgresSQL</code>
modules. Individual account options are not supported with
system-based authentication modules (password/shadow files, or PAM).</p><p>
-See the
+See
<a class="ulink" href="auth_generic.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">auth_generic</span>(3)</span></a>
for a description of option names used by various Courier packages.
Other applications can make up names for their own settings, and
use them in the same way.</p><p>
Account options are specified via the authentication modules in the
-following manner:</p><div class="variablelist"><dl><dt><span class="term"><code class="literal">userdb</code></span></dt><dd><p>
+following manner:</p><div class="variablelist"><dl
class="variablelist"><dt><span class="term"><code class="literal">userdb</code></span></dt><dd><p>
Use the <span class="command"><strong>userdb</strong></span> command to set a field called
"<code class="literal">options</code>". Example:</p><div class="informalexample"><pre class="programlisting" xml:space="preserve">
userdb user1@example.com set options=disableimap=1,sharedgroup=44
of "shared=sharedgroup,disableimap" means that the LDAP attribute
called "shared" contains the "sharedgroup" setting, as described
previously; and an LDAP attribute of disableimap contains the setting
-of the same name.</p></dd><dt><span class="term"><span class="application">MySQL</span>, and <span class="application">PostgreSQL</span></span></dt><dd><p>
-Account options are defined by <code class="literal">MYSQL_AUXOPTIONS_FIELD</code>
+of the same name.</p></dd><dt><span class="term"><span class="application">MySQL</span>,
+<span class="application">SQLite</span>, and <span class="application">PostgreSQL</span></span></dt><dd><p>
+Account options are defined by <code class="literal">MYSQL_AUXOPTIONS_FIELD</code>,
+<code class="literal">SQLITE_AUXOPTIONS_FIELD</code>,
or <code class="literal">POSTGRESQL_AUXOPTIONS_FIELD</code>, in its corresponding
configuration file. In the most simplest case, add a character field to
the database, and put the field name into the
-<code class="literal">MYSQL_AUXOPTIONS_FIELD</code> or
+<code class="literal">MYSQL_AUXOPTIONS_FIELD</code>,
+<code class="literal">SQLITE_AUXOPTIONS_FIELD</code>, or
<code class="literal">POSTGRESQL_AUXOPTIONS_FIELD</code> configuration file setting.
For each account, the character field should contain the literal option
string. Yes, you'll just put "shared=sharedgroup,disableimap"
literally, in that field.</p><p>
Fortunately, there is a cleaner way to do this, which avoid driving
a database designer batty. Keep in mind that the contents of
-<code class="literal">MYSQL_AUXOPTIONS_FIELD</code>/<code class="literal">POSTGRESQL_AUXOPTIONS_FIELD</code>
+<code class="literal">MYSQL_AUXOPTIONS_FIELD</code>/<code class="literal">SQLITE_AUXOPTIONS_FIELD</code>/<code class="literal">POSTGRESQL_AUXOPTIONS_FIELD</code>
are simply inserted directly into the SQL query that fetches the
-account information. Both MySQL and PostgreSQL have a rich SQL that can
+account information. MySQL, SQLite, and PostgreSQL have a rich SQL that can
be used to manufacture a suitable option string from plain,
garden-variety, database fields. That is, you may define individual
table fields like "disableimap", and "disablepop3", then provide a
the expected option string. An example of such an SQL string is
provided in the comments portion of the configuration file.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
When using the alternative custom query option, the option string
- is the last field that the custom SQL query should return.</p></div></dd></dl></div></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="authtest" shape="rect"> </a>Running <span class="command"><strong>authtest</strong></span></h2></div></div></div><p>
+ is the last field that the custom SQL query should return.</p></div></dd></dl></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
+The following list of account options is a combined list of implemented
+options supported by Courier, Courier-IMAP, and
+SqWebMail packages. Some of the following information is obviously
+not applicable for a particular package.
+The inapplicable bits should be obvious.</p></div><p>
+The following options are recognized by the various Courier
+packages:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">disableimap=</code><em class="replaceable"><code>n</code></em></span></dt><dd><p>
+If "n" is 1, IMAP access to this account should be disabled.</p></dd><dt><span class="term"><code class="literal">disablepop3=</code><em class="replaceable"><code>n</code></em></span></dt><dd><p>
+If "n" is 1, POP3 access to this account should be disabled.</p></dd><dt><span class="term"><code class="literal">disableinsecureimap=</code><em class="replaceable"><code>n</code></em></span></dt><dd><p>
+If "n" is 1, unencrypted IMAP access to this account should be disabled.</p></dd><dt><span class="term"><code class="literal">disableinsecurepop3=</code><em class="replaceable"><code>n</code></em></span></dt><dd><p>
+If "n" is 1, unencrypted POP3 access to this account should be disabled.</p></dd><dt><span class="term"><code class="literal">disablewebmail=</code><em class="replaceable"><code>n</code></em></span></dt><dd><p>
+If "n" is 1, webmail access to this account should be disabled.</p></dd><dt><span class="term"><code class="literal">disableshared=</code><em class="replaceable"><code>n</code></em></span></dt><dd><p>
+If "n" is 1, this account should not have access to shared folders or be able
+to share its own folders with other people.</p></dd><dt><span class="term"><code class="literal">group=</code><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+This option is used by Courier-IMAP in calculating access control lists.
+This option places the account as a member of access group
+<em class="replaceable"><code>name</code></em>.
+Instead of granting access rights on individual mail folders to individual
+accounts, the access rights can be granted to an access group
+<span class="quote">“<span class="quote">name</span>”</span>, and all members of this group get the specified access
+rights.</p><p>
+The access group name <span class="quote">“<span class="quote">administrators</span>”</span> is a reserved group.
+All accounts in the <code class="literal">administrators</code> group automatically
+receive all rights to all accessible folders.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
+This option may be specified multiple times to specify that the account
+belongs to multiple account groups.</p></div></dd><dt><span class="term"><code class="literal">sharedgroup=</code><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+Another option used by Courier-IMAP.
+Append "name" to the name of the top level virtual shared folder
+index file. This setting restricts which virtual shared folders this
+account could possibly access (and that's on top of whatever else the
+access control lists say). See the virtual shared folder documentation
+for more information.</p><p>
+For technical reasons, group names may not include comma, tab, "/" or "|"
+characters.</p></dd></dl></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="authtest" shape="rect"> </a>Running <span class="command"><strong>authtest</strong></span></h2></div></div></div><p>
The <span class="command"><strong>authtest</strong></span> command may be used to verify that the
authentication library is working:</p><div class="informalexample"><pre class="programlisting" xml:space="preserve">
authtest userid
command attemps to change the account's password.
The second argument is the old password, the third argument is the
new password.</p><p>
-See <a class="ulink" href="README.authdebug.html" target="_top" shape="rect"><code class="filename">README.authdebug.html</code></a> for more information.</p><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="pwchange" shape="rect"> </a>Changing account passwords</h3></div></div></div><p>For the virtual domain modules (<code class="literal">authldap</code>,
-<code class="literal">authmysql</code>, <code class="literal">authpgsql</code> and friends) changing the
+See <a class="ulink" href="README.authdebug.html" target="_top" shape="rect"><code class="filename">README.authdebug.html</code></a> for more information.</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="pwchange" shape="rect"> </a>Changing account passwords</h3></div></div></div><p>For the virtual domain modules (<code class="literal">authldap</code>,
+<code class="literal">authmysql</code>,
+<code class="literal">authsqlite</code>,
+<code class="literal">authpgsql</code> and friends) changing the
login is a no-brainer. The tricky situation is when SqWebMail uses system
passwords to log in (the <code class="literal">authpwd</code>, <code class="literal">authshadow</code>, or
<code class="literal">authpam</code> authentication module). Different systems use different
messages from <span class="command"><strong>passwd</strong></span> will not be shown by.</p><p>
The <span class="command"><strong>expect</strong></span> script is installed as
<code class="filename">/usr/local/libexec/courier-authlib/authsystem.passwd</code>
-(assuming default options to the <span class="command"><strong>configure</strong></span> script).</p></div></div><div class="sect1"
lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="internals" shape="rect"> </a>Authentication internals</h2></div></div></div><p>
-The following structure describes an authentication module:</p><div class="blockquote"><blockquote class="blockquote"><div class="example"><a id="authstaticinfo" shape="rect"> </a><p class="title"><
b>Example 1. struct authstaticinfo</b></p><div class="example-contents"><pre class="programlisting" xml:space="preserve">
+(assuming default options to the <span class="command"><strong>configure</strong></span> script).</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="internals" shape="rect"> </a>Authentication internals</h2></div></div></div><p>
+The following structure describes an authentication module:</p><div class="blockquote"><blockquote class="blockquote"><div class="example"><a id="authstaticinfo" shape="rect"> </a><p class="title"><
strong>Example 1. struct authstaticinfo</strong></p><div class="example-contents"><pre class="programlisting" xml:space="preserve">
struct authstaticinfo {
const char *auth_name;
int (*auth_func)(const char *, const char *, char *, int,
</pre></div></div><br class="example-break" clear="none"/></blockquote></div><p>
An authentication module is a shared library that defines a single function
called
-“<span class="quote">courier_auth_<em class="replaceable"><code>NAME</code></em>_init</span>”, where
-“<span class="quote">NAME</span>” is the name of the authentication module.
+<span class="quote">“<span class="quote">courier_auth_<em class="replaceable"><code>NAME</code></em>_init</span>”</span>, where
+<span class="quote">“<span class="quote">NAME</span>”</span> is the name of the authentication module.
The shared library does not need to export any other symbols, this is the
only function that needs to be exported.
The function returns a pointer to the <span class="structname">authstaticinfo</span>
structure.
For example, the relevant code from the <code class="literal">authmysql</code> module is:
-</p><div class="blockquote"><blockquote class="blockquote"><div class="example"><a id="authmysqlex" shape="rect"> </a><p class="title"><
b>Example 2. authmysql</b></p><div class="example-contents"><pre class="programlisting" xml:space="preserve">
+</p><div class="blockquote"><blockquote class="blockquote"><div class="example"><a id="authmysqlex" shape="rect"> </a><p class="title"><
strong>Example 2. authmysql</strong></p><div class="example-contents"><pre class="programlisting" xml:space="preserve">
static struct authstaticinfo authmysql_info={
"authmysql",
auth_mysql,
}
</pre></div></div><br class="example-break" clear="none"/></blockquote></div><p>
<code class="function">auth_func</code> points to a function that handles an
-authentication request. The function is invoked as follows:</p><div class="blockquote"><blockquote class="blockquote"><div class="example"><a id="auth_func" shape="rect"> </a><p class="title"><
b>Example 3. auth_func</b></p><div class="example-contents"><pre class="programlisting" xml:space="preserve">
+authentication request. The function is invoked as follows:</p><div class="blockquote"><blockquote class="blockquote"><div class="example"><a id="auth_func" shape="rect"> </a><p class="title"><
strong>Example 3. auth_func</strong></p><div class="example-contents"><pre class="programlisting" xml:space="preserve">
int result=auth_func(const char *service, const char *authtype,
const char *authdata,
int (*callback_func)(struct authinfo *, void *),
void *callback_arg);
</pre></div></div><br class="example-break" clear="none"/></blockquote></div><p>
-“<span class="quote">service</span>” is the name of the service being authenticated,
-such as “<span class="quote"><code class="literal">imap</code></span>” or
-“<span class="quote"><code class="literal">pop3</code></span>”.
-“<span class="quote">authtype</span>” defines the authentication format,
-and
“<span class="quote">authdata</span>” is the actual authentication request.</p><p>
+<span class="quote">“<span class="quote">service</span>”</span> is the name of the service being authenticated,
+such as <span class="quote">“<span class="quote"><code class="literal">imap</code></span>”</span> or
+<span class="quote">“<span class="quote"><code class="literal">pop3</code></span>”</span>.
+<span class="quote">“<span class="quote">authtype</span>”</span> defines the authentication format,
+and
<span class="quote">“<span class="quote">authdata</span>”</span> is the actual authentication request.</p><p>
Two authentication formats are defined at this time.
-The “<span class="quote">authtype</span>” string is set to one of the following
-strings:</p><div class="variablelist"><dl
><dt><span class="term">“<span class="quote">login</span>”</span></dt><dd><p>
+The <span class="quote">“<span class="quote">authtype</span>”</span> string is set to one of the following
+strings:</p><div class="variablelist"><dl
class="variablelist"><dt><span class="term"><span class="quote">“<span class="quote">login</span>”</span></span></dt><dd><p>
Tradition userid/password authentication.
<code class="literal">authdata</code> points to a string that consists of:
the userid; a newline character; the password; a final newline
-character.</p></dd><dt><span class="term">
“<span class="quote">cram-md5</span>”, or “<span class="quote">cram-sha1</span>”</span></dt><dd><p>
+character.</p></dd><dt><span class="term">
<span class="quote">“<span class="quote">cram-md5</span>”</span>, or <span class="quote">“<span class="quote">cram-sha1</span>”</span></span></dt><dd><p>
Challenge/response authentication.
<code class="literal">authdata</code> points to a string that consists of:
the base64-encoded challenge; a newline character;
After the callback function returns this structure can be deallocated.
The authentication module initializes the following fields:</p><p>
<code class="function">auth_pre_func</code> points to a function that obtains
-account information. The function is invoked as follows:</p><div class="blockquote"><blockquote class="blockquote"><div class="example"><a id="auth_pre_func" shape="rect"> </a><p class="title"><
b>Example 4. auth_pre_func</b></p><div class="example-contents"><pre class="programlisting" xml:space="preserve">
+account information. The function is invoked as follows:</p><div class="blockquote"><blockquote class="blockquote"><div class="example"><a id="auth_pre_func" shape="rect"> </a><p class="title"><
strong>Example 4. auth_pre_func</strong></p><div class="example-contents"><pre class="programlisting" xml:space="preserve">
int auth_pre_func(const char *user, const char *service,
int (*callback)(struct authinfo *, void *), void *arg);
</pre></div></div><br class="example-break" clear="none"/></blockquote></div><p>
-This function does the same thing as “<span class="quote">auth_func</span>” except that
+This function does the same thing as <span class="quote">“<span class="quote">auth_func</span>”</span> except that
the password is not actually verified.
If the account exists, the callback function is invoked with the
same callback arguments.</p><p>
resulting in an error the next time an authentication request is
received.</p><p>
<code class="function">auth_changepwd</code> points to a function that will be
-invoked to change a password on an account, as follows.</p><div class="blockquote"><blockquote class="blockquote"><div class="example"><a id="auth_changepwd" shape="rect"> </a><p class="title"><
b>Example 5. auth_changepwd</b></p><div class="example-contents"><pre class="programlisting" xml:space="preserve">
+invoked to change a password on an account, as follows.</p><div class="blockquote"><blockquote class="blockquote"><div class="example"><a id="auth_changepwd" shape="rect"> </a><p class="title"><
strong>Example 5. auth_changepwd</strong></p><div class="example-contents"><pre class="programlisting" xml:space="preserve">
int auth_changepwd(const char *service, const char *user,
const char *oldpw, const char *newpw);
</pre></div></div><br class="example-break" clear="none"/></blockquote></div><p>
<code class="literal">service</code> is the name of the service whose password is to
-be changed (such as “<span class="quote">imap</span>” or “<span class="quote">pop3</span>”).
+be changed (such as <span class="quote">“<span class="quote">imap</span>”</span> or <span class="quote">“<span class="quote">pop3</span>”</span>).
<code class="function">auth_changepwd</code> should return 0 if the password was
changed succesfully, a negative value if <code class="literal">user</code> is invalid
(the next authentication module will be tried), or a positive value if
the callback function one last time, with a NULL pointer for the login ID,
then returns. If an error is encountered while enumerating the login IDs,
<code class="function">auth_enumerate</code> terminates without invoking
-the callback function with a NULL login ID.</p></div><div class="sect1"
lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="files" shape="rect"> </a>FILES</h2></div></div></div><p>
+the callback function with a NULL login ID.</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="files" shape="rect"> </a>FILES</h2></div></div></div><p>
<code class="filename"> @authdaemonrc@</code> - <span class="command"><strong>authdaemond</strong></span> configuration file</p><p>
<code class="filename"> @authldaprc@</code> - <span class="command"><strong>authldap</strong></span> configuration file</p><p>
<code class="filename"> @authmysqlrc@</code> - <span class="command"><strong>authmysql</strong></span> configuration file</p><p>
-<code class="filename"> @authpgsqlrc@</code> - <span class="command"><strong>authpgsql</strong></span> configuration file</p></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="seealso" shape="rect"> </a>SEE ALSO</h2></div></div></div><p>
+<code class="filename"> @authsqliterc@</code> - <span class="command"><strong>authsqlite</strong></span> configuration file</p><p>
+<code class="filename"> @authpgsqlrc@</code> - <span class="command"><strong>authpgsql</strong></span> configuration file</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="seealso" shape="rect"> </a>SEE ALSO</h2></div></div></div><p>
<a class="ulink" href="courier.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">courier</span>(8)</span></a>,
<a class="ulink" href="userdb.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">userdb</span>(8)</span></a></p></div></div></body></html>
HCoop / hcoop / debian / courier-authlib.git / blobdiff