1<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"
2        "http://www.w3.org/TR/html4/loose.dtd">
3
4<html>
5
6<head>
7
8<title>Postfix MySQL Howto</title>
9
10<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
11
12</head>
13
14<body>
15
16<h1><img src="postfix-logo.jpg" width="203" height="98" ALT="">Postfix MySQL Howto</h1>
17
18<hr>
19
20<h2>Introduction</h2>
21
22<p> The Postfix mysql map type allows you to hook up Postfix to a
23MySQL database. This implementation allows for multiple mysql
24databases: you can use one for a <a href="virtual.5.html">virtual(5)</a> table, one for an
25<a href="access.5.html">access(5)</a> table, and one for an <a href="aliases.5.html">aliases(5)</a> table if you want.  You
26can specify multiple servers for the same database, so that Postfix
27can switch to a good database server if one goes bad.  </p>
28
29<p> Busy mail servers using mysql maps will generate lots of
30concurrent mysql clients, so the mysql server(s) should be run with
31this fact in mind.  You can reduce the number of concurrent mysql
32clients by using the Postfix <a href="proxymap.8.html">proxymap(8)</a> service. </p>
33
34<h2>Building Postfix with MySQL support</h2>
35
36<p> These instructions assume that you build Postfix from source
37code as described in the <a href="INSTALL.html">INSTALL</a> document. Some modification may
38be required if you build Postfix from a vendor-specific source
39package.  </p>
40
41<p> Note: to use mysql with Debian GNU/Linux's Postfix, all you
42need is to install the postfix-mysql package and you're done.
43There is no need to recompile Postfix. </p>
44
45<p> The Postfix MySQL client utilizes the mysql client library,
46which can be obtained from: </p>
47
48<blockquote>
49    <p> <a href="http://www.mysql.com/downloads/">http://www.mysql.com/downloads/</a> <br>
50    <a href="http://sourceforge.net/projects/mysql/">http://sourceforge.net/projects/mysql/</a> </p>
51</blockquote>
52
53<p> In order to build Postfix with mysql map support, you will need to add
54-DHAS_MYSQL and -I for the directory containing the mysql headers, and
55the mysqlclient library (and libm) to AUXLIBS, for example: </p>
56
57<blockquote>
58<pre>
59make -f Makefile.init makefiles \
60    'CCARGS=-DHAS_MYSQL -I/usr/local/mysql/include' \
61    'AUXLIBS=-L/usr/local/mysql/lib -lmysqlclient -lz -lm'
62</pre>
63</blockquote>
64
65<p> On Solaris, use this instead: </p>
66
67<blockquote>
68<pre>
69make -f Makefile.init makefiles \
70    'CCARGS=-DHAS_MYSQL -I/usr/local/mysql/include' \
71    'AUXLIBS=-L/usr/local/mysql/lib -R/usr/local/mysql/lib \
72        -lmysqlclient -lz -lm'
73</pre>
74</blockquote>
75
76<p> Then, just run 'make'. This requires libz, the compression
77library.  Older mysql implementations build without libz. </p>
78
79<h2>Using MySQL tables</h2>
80
81<p> Once Postfix is built with mysql support, you can specify a
82map type in <a href="postconf.5.html">main.cf</a> like this: </p>
83
84<blockquote>
85<pre>
86<a href="postconf.5.html#alias_maps">alias_maps</a> = <a href="mysql_table.5.html">mysql</a>:/etc/postfix/mysql-aliases.cf
87</pre>
88</blockquote>
89
90<p> The file /etc/postfix/mysql-aliases.cf specifies lots of
91information telling Postfix how to reference the mysql database.
92For a complete description, see the <a href="mysql_table.5.html">mysql_table(5)</a> manual page. </p>
93
94<h2>Example: local aliases </h2>
95
96<pre>
97#
98# mysql config file for <a href="local.8.html">local(8)</a> <a href="aliases.5.html">aliases(5)</a> lookups
99#
100
101# The user name and password to log into the mysql server.
102user = someone
103password = some_password
104
105# The database name on the servers.
106dbname = customer_database
107
108# For Postfix 2.2 and later The SQL query template.
109# See <a href="mysql_table.5.html">mysql_table(5)</a> for details.
110query = SELECT forw_addr FROM mxaliases WHERE alias='%s' AND status='paid'
111
112# For Postfix releases prior to 2.2. See <a href="mysql_table.5.html">mysql_table(5)</a> for details.
113select_field = forw_addr
114table = mxaliases
115where_field = alias
116# Don't forget the leading "AND"!
117additional_conditions = AND status = 'paid'
118</pre>
119
120<h2>Additional notes</h2>
121
122<p> The MySQL configuration interface setup allows for multiple
123mysql databases: you can use one for a virtual table, one for an
124access table, and one for an aliases table if you want. </p>
125
126<p> Since sites that have a need for multiple mail exchangers may
127enjoy the convenience of using a networked mailer database, but do
128not want to introduce a single point of failure to their system,
129we've included the ability to have Postfix reference multiple hosts
130for access to a single mysql map.  This will work if sites set up
131mirrored mysql databases on two or more hosts.  Whenever queries
132fail with an error at one host, the rest of the hosts will be tried
133in random order.  If no mysql server hosts are reachable, then mail
134will be deferred until at least one of those hosts is reachable.
135</p>
136
137<h2>Credits</h2>
138
139<ul>
140
141<li> The initial version was contributed by Scott Cotton and Joshua
142Marcus, IC Group, Inc.</li>
143
144<li> Liviu Daia revised the configuration interface and added the
145<a href="postconf.5.html">main.cf</a> configuration feature.</li>
146
147<li> Liviu Daia with further refinements from Jose Luis Tallon and
148Victor Duchovni developed the common query, result_format, domain and
149expansion_limit interface for LDAP, MySQL and PosgreSQL.</li>
150
151</ul>
152
153</body>
154
155</html>
156