postfix-master/MYSQL_README.html

   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
  23 MySQL database. This implementation allows for multiple mysql
  24 databases: 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
  26 can specify multiple servers for the same database, so that Postfix
  27 can switch to a good database server if one goes bad.  </p>
  28
  29 <p> Busy mail servers using mysql maps will generate lots of
  30 concurrent mysql clients, so the mysql server(s) should be run with
  31 this fact in mind.  You can reduce the number of concurrent mysql
  32 clients 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
  37 code as described in the <a href="INSTALL.html">INSTALL</a> document. Some modification may
  38 be required if you build Postfix from a vendor-specific source
  39 package.  </p>
  40
  41 <p> Note: to use mysql with Debian GNU/Linux's Postfix, all you
  42 need is to install the postfix-mysql package and you're done.
  43 There is no need to recompile Postfix. </p>
  44
  45 <p> The Postfix MySQL client utilizes the mysql client library,
  46 which 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
  55 the mysqlclient library (and libm) to AUXLIBS, for example: </p>
  56
  57 <blockquote>
  58 <pre>
  59 make -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>
  69 make -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
  77 library.  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
  82 map 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
  91 information telling Postfix how to reference the mysql database.
  92 For 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.
 102 user = someone
 103 password = some_password
 104
 105 # The database name on the servers.
 106 dbname = 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.
 110 query = 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.
 113 select_field = forw_addr
 114 table = mxaliases
 115 where_field = alias
 116 # Don't forget the leading "AND"!
 117 additional_conditions = AND status = 'paid'
 118 </pre>
 119
 120 <h2>Additional notes</h2>
 121
 122 <p> The MySQL configuration interface setup allows for multiple
 123 mysql databases: you can use one for a virtual table, one for an
 124 access 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
 127 enjoy the convenience of using a networked mailer database, but do
 128 not want to introduce a single point of failure to their system,
 129 we've included the ability to have Postfix reference multiple hosts
 130 for access to a single mysql map.  This will work if sites set up
 131 mirrored mysql databases on two or more hosts.  Whenever queries
 132 fail with an error at one host, the rest of the hosts will be tried
 133 in random order.  If no mysql server hosts are reachable, then mail
 134 will 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
 142 Marcus, 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
 148 Victor Duchovni developed the common query, result_format, domain and
 149 expansion_limit interface for LDAP, MySQL and PosgreSQL.</li>
 150
 151 </ul>
 152
 153 </body>
 154
 155 </html>