Imported Debian patch 0.60.1-1
[hcoop/debian/courier-authlib.git] / README.authmysql.html
CommitLineData
d9898ee8 1<?xml version="1.0" encoding="iso-8859-1"?>
2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
3 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
4<html xmlns="http://www.w3.org/1999/xhtml">
5<head>
6 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
7 <title>Courier MySQL authentication module</title>
8 <meta name="MSSmartTagsPreventParsing" content="TRUE" />
9</head>
10
11<body text="#000000" bgcolor="#FFFFFF" link="#0000EE" vlink="#551A8B"
12alink="#FF0000">
13<h1>Courier MySQL authentication module</h1>
14
15<p>This module allows authentication information to be stored in a MySQL
16database.</p>
17<ul>
18 <li>Supports both physical and virtual mail accounts.<br />
19 <br />
20 </li>
21 <li>Can be configured to use either crypted or cleartext passwords (or
22 both). Cleartext passwords allow CRAM-MD5 authentication to be
23 implemented.</li>
24</ul>
25
26<p>When <code>authmysql</code> is installed, a default configuration file,
27<code>authmysqlrc</code> will be installed too. You must edit this file to
28set up your MySQL authentication.</p>
29
30<p><strong>NOTE: this authentication module should NOT be used if you are
31using the vpopmail virtual mailing list manager. You should select the
32<code>authvchkpw</code> authentication module instead (which should happen
33automatically). It may be necessary to use the
34<code>--without-authmysql</code> flag to the <code>configure</code> script,
35because <code>configure</code> by default will include <code>authmysql</code>
36if it finds MySQL client libraries.</strong>.</p>
37<hr />
38
39<p>Edit <code>authmysqlrc</code>, and initialize the following variables:</p>
40<ul>
41 <li><code>MYSQL_SERVER</code> - MySQL server name (required).</li>
42 <li><code>MYSQL_PORT</code> - server port where MySQL accepts
43 connections.</li>
44 <li><code>MYSQL_SOCKET</code> - If MySQL is running on the same machine and
45 can accept connections from a filesystem socket, enter the path to the
46 filesystem socket here, and do not initialize SERVER/PORT.</li>
47 <li><code>MYSQL_USERNAME</code> - MySQL username with log in with
48 (required).</li>
49 <li><code>MYSQL_PASSWORD</code> - MySQL password with log in with
50 (required).</li>
51 <li><code>MYSQL_DATABASE</code> - MySQL database to log in to
52 (required).</li>
53 <li><code>MYSQL_SSL_KEY</code> - name of the field containing a SSL key path
54 (optional).</li>
55 <li><code>MYSQL_SSL_CERT</code> - name of the field containing a SSL
56 certificate path (optional).</li>
57 <li><code>MYSQL_SSL_CACERT</code> - name of the field containing a SSL CA
58 certificate (optional).</li>
59 <li><code>MYSQL_SSL_CAPATH</code> - name of the filend containing a name to a
60 directory that contains trusted SSL CA certificates in pem format. (optional).</li>
61 <li><code>MYSQL_SSL_CIPHER</code> - name of the field containing a SSL
62 cipher list (optional).</li>
63 <li><code>MYSQL_USER_TABLE</code> - name of the MySQL with the
64 authentication information (see below) (required).</li>
65 <li><code>MYSQL_LOGIN_FIELD</code> - field that contains the login id for
66 this account.</li>
67 <li><code>MYSQL_CRYPT_PWFIELD</code> - name of the field containing the
68 crypt-ed password (either <code>MYSQL_CRYPT_PWFIELD</code> or
69 <code>MYSQL_CLEAR_PWFIELD</code> is required). <strong>NOTE: this
70 password must be crypt-ed using the operating system's crypt function,
71 NOT MySQL's crypt function. MySQL's crypt() function is non-standard and
72 is not generally compatible with the operating system's crypt
73 function.</strong></li>
74 <li><code>MYSQL_CLEAR_PWFIELD</code> - name of the field containing the
75 cleartext password (either <code>MYSQL_CRYPT_PWFIELD</code> or
76 <code>MYSQL_CLEAR_PWFIELD</code> is required).</li>
77 <li><code>MYSQL_UID_FIELD</code> - field that contains the system userid
78 for this account.</li>
79 <li><code>MYSQL_GID_FIELD</code> - field that contains the system groupid
80 for this account.</li>
81 <li><code>MYSQL_MAILDIR_FIELD</code> - name of the field containing a
82 non-default location of the account's system mailbox (optional).</li>
83 <li><code>MYSQL_DEFAULTDELIVERY</code> - default mail delivery instructions
84 for the Courier mail server. If this field in the record is not empty,
85 its contents supercede the DEFAULTDELIVERY setting.</li>
86 <li><code>MYSQL_QUOTA_FIELD</code> - name of the field containing a maildir
87 quota (optional).</li>
88 <li><code>MYSQL_AUXOPTIONS</code> - auxiliary options. This field, if
89 defined, should consist of a <code>VARCHAR</code> consisting of a
90 comma-separate list of "<code>IDENTIFIER=VALUE</code>" pairs, that
91 specify per-account options. See INSTALL's description of the "Account
92 OPTIONS" setting for more information.</li>
93 <li><code>DEFAULT_DOMAIN</code> - if the user logs in without specifying
94 <code>@domain</code>, use the following domain (in this case the id field
95 must always contain <code>user@host</code>) (optional).</li>
96 <li><code>MYSQL_WHERE_CLAUSE</code> - optional freeform SQL that is
97 appended to the SQL query string.</li>
98</ul>
99
100<p>Here's a recommended definition of <code>MYSQL_USER_TABLE</code>:</p>
101<pre>CREATE TABLE passwd (
102 id char(128) DEFAULT '' NOT NULL,
103 crypt char(128) DEFAULT '' NOT NULL,
104 clear char(128) DEFAULT '' NOT NULL,
105 name char(128) DEFAULT '' NOT NULL,
106 uid int(10) unsigned DEFAULT '65534' NOT NULL,
107 gid int(10) unsigned DEFAULT '65534' NOT NULL,
108 home char(255) DEFAULT '' NOT NULL,
109 maildir char(255) DEFAULT '' NOT NULL,
110 defaultdelivery char(255) DEFAULT '' NOT NULL,
111 quota char(255) DEFAULT '' NOT NULL,
112 options char(255) DEFAULT '' NOT NULL,
113 KEY id (id(128))
114);</pre>
115
116<p>Observe that a valid SQL expression may be used in place of any field
117setting, since all that happens is that the contents of the settings are
118inserted into an SQL SELECT statement. Specifically, the <code>options</code>
119field may be replaced by several normal fields, such as
120"<code>disablepop3</code>", "<code>disableimap</code>",
121"<code>disablewebmail</code>", and "<code>sharedgroup</code>"; then
122<code>MYSQL_AUXOPTIONS</code> would be set to:</p>
123
124<blockquote>
125 <code>CONCAT("disableimap=",disableimap,",disablepop3=",disablepop3,",disablewebmail=",disablewebmail,",sharedgroup=",sharedgroup)</code></blockquote>
126
127<p>This results in the expected comma-delimited options list, which is built
128up from individual table fields.</p>
129</body>
130</html>