Backport to wheezy
[hcoop/debian/courier-authlib.git] / README.authmysql.html
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"
12 alink="#FF0000">
13 <h1>Courier MySQL authentication module</h1>
14
15 <p>This module allows authentication information to be stored in a MySQL
16 database.</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
28 set up your MySQL authentication.</p>
29
30 <hr />
31
32 <p>Edit <code>authmysqlrc</code>, and initialize the following variables:</p>
33 <ul>
34 <li><code>MYSQL_SERVER</code> - MySQL server name (required).</li>
35 <li><code>MYSQL_PORT</code> - server port where MySQL accepts
36 connections.</li>
37 <li><code>MYSQL_SOCKET</code> - If MySQL is running on the same machine and
38 can accept connections from a filesystem socket, enter the path to the
39 filesystem socket here, and do not initialize SERVER/PORT.</li>
40 <li><code>MYSQL_USERNAME</code> - MySQL username with log in with
41 (required).</li>
42 <li><code>MYSQL_PASSWORD</code> - MySQL password with log in with
43 (required).</li>
44 <li><code>MYSQL_DATABASE</code> - MySQL database to log in to
45 (required).</li>
46 <li><code>MYSQL_SSL_KEY</code> - name of the field containing a SSL key path
47 (optional).</li>
48 <li><code>MYSQL_SSL_CERT</code> - name of the field containing a SSL
49 certificate path (optional).</li>
50 <li><code>MYSQL_SSL_CACERT</code> - name of the field containing a SSL CA
51 certificate (optional).</li>
52 <li><code>MYSQL_SSL_CAPATH</code> - name of the filend containing a name to a
53 directory that contains trusted SSL CA certificates in pem format. (optional).</li>
54 <li><code>MYSQL_SSL_CIPHER</code> - name of the field containing a SSL
55 cipher list (optional).</li>
56 <li><code>MYSQL_USER_TABLE</code> - name of the MySQL with the
57 authentication information (see below) (required).</li>
58 <li><code>MYSQL_LOGIN_FIELD</code> - field that contains the login id for
59 this account.</li>
60 <li><code>MYSQL_CRYPT_PWFIELD</code> - name of the field containing the
61 crypt-ed password (either <code>MYSQL_CRYPT_PWFIELD</code> or
62 <code>MYSQL_CLEAR_PWFIELD</code> is required). <strong>NOTE: this
63 password must be crypt-ed using the operating system's crypt function,
64 NOT MySQL's crypt function. MySQL's crypt() function is non-standard and
65 is not generally compatible with the operating system's crypt
66 function.</strong></li>
67 <li><code>MYSQL_CLEAR_PWFIELD</code> - name of the field containing the
68 cleartext password (either <code>MYSQL_CRYPT_PWFIELD</code> or
69 <code>MYSQL_CLEAR_PWFIELD</code> is required).</li>
70 <li><code>MYSQL_UID_FIELD</code> - field that contains the system userid
71 for this account.</li>
72 <li><code>MYSQL_GID_FIELD</code> - field that contains the system groupid
73 for this account.</li>
74 <li><code>MYSQL_MAILDIR_FIELD</code> - name of the field containing a
75 non-default location of the account's system mailbox (optional).</li>
76 <li><code>MYSQL_DEFAULTDELIVERY</code> - default mail delivery instructions
77 for the Courier mail server. If this field in the record is not empty,
78 its contents supercede the DEFAULTDELIVERY setting.</li>
79 <li><code>MYSQL_QUOTA_FIELD</code> - name of the field containing a maildir
80 quota (optional).</li>
81 <li><code>MYSQL_AUXOPTIONS</code> - auxiliary options. This field, if
82 defined, should consist of a <code>VARCHAR</code> consisting of a
83 comma-separate list of "<code>IDENTIFIER=VALUE</code>" pairs, that
84 specify per-account options. See INSTALL's description of the "Account
85 OPTIONS" setting for more information.</li>
86 <li><code>DEFAULT_DOMAIN</code> - if the user logs in without specifying
87 <code>@domain</code>, use the following domain (in this case the id field
88 must always contain <code>user@host</code>) (optional).</li>
89 <li><code>MYSQL_WHERE_CLAUSE</code> - optional freeform SQL that is
90 appended to the SQL query string.</li>
91 </ul>
92
93 <p>Here's a recommended definition of <code>MYSQL_USER_TABLE</code>:</p>
94 <pre>CREATE TABLE passwd (
95 id char(128) DEFAULT '' NOT NULL,
96 crypt char(128) DEFAULT '' NOT NULL,
97 clear char(128) DEFAULT '' NOT NULL,
98 name char(128) DEFAULT '' NOT NULL,
99 uid int(10) unsigned DEFAULT '65534' NOT NULL,
100 gid int(10) unsigned DEFAULT '65534' NOT NULL,
101 home char(255) DEFAULT '' NOT NULL,
102 maildir char(255) DEFAULT '' NOT NULL,
103 defaultdelivery char(255) DEFAULT '' NOT NULL,
104 quota char(255) DEFAULT '' NOT NULL,
105 options char(255) DEFAULT '' NOT NULL,
106 KEY id (id(128))
107 );</pre>
108
109 <p>Observe that a valid SQL expression may be used in place of any field
110 setting, since all that happens is that the contents of the settings are
111 inserted into an SQL SELECT statement. Specifically, the <code>options</code>
112 field may be replaced by several normal fields, such as
113 "<code>disablepop3</code>", "<code>disableimap</code>",
114 "<code>disablewebmail</code>", and "<code>sharedgroup</code>"; then
115 <code>MYSQL_AUXOPTIONS</code> would be set to:</p>
116
117 <blockquote>
118 <code>CONCAT("disableimap=",disableimap,",disablepop3=",disablepop3,",disablewebmail=",disablewebmail,",sharedgroup=",sharedgroup)</code></blockquote>
119
120 <p>This results in the expected comma-delimited options list, which is built
121 up from individual table fields.</p>
122 </body>
123 </html>