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 Berkeley DB Howto</title> 9 10<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> 11 12</head> 13 14<body> 15 16<h1><img src="postfix-logo.jpg" width="203" height="98" ALT="">Postfix Berkeley DB Howto</h1> 17 18<hr> 19 20<h2>Introduction</h2> 21 22<p> Postfix uses databases of various kinds to store and look up 23information. Postfix databases are specified as "type:name". 24Berkeley DB implements the Postfix database type "hash" and 25"btree". The name of a Postfix Berkeley DB database is the name 26of the database file without the ".db" suffix. Berkeley DB databases 27are maintained with the <a href="postmap.1.html">postmap(1)</a> command. </p> 28 29<p> Note: Berkeley DB version 4 is not supported by Postfix versions 30before 2.0. </p> 31 32<p> This document describes: </p> 33 34<ol> 35 36<li> <p> How to build Postfix <a href="#disable_db">without Berkeley 37DB support</a> even if the system comes with Berkeley DB. </p> 38 39<li> <p> How to build Postfix on <a href="#no_db">systems that 40normally have no Berkeley DB library</a>. </p> 41 42<li> <p> How to build Postfix on <a href="#bsd">BSD</a> or <a 43href="#linux">Linux</a> systems with multiple Berkeley DB 44versions. </p> 45 46<li> <p> How to <a href="#tweak">tweak</a> performance. </p> 47 48<li> <p> Missing <a href="#pthread">pthread</a> library trouble. </p> 49 50</ol> 51 52<h2><a name="disable_db">Building Postfix without Berkeley 53DB support even if the system comes with Berkeley DB</a></h2> 54 55<p> Note: The following instructions apply to Postfix 2.9 and later. </p> 56 57<p> Postfix will normally enable Berkeley DB support if the system 58is known to have it. To build Postfix without Berkeley DB support, 59build the makefiles as follows: </p> 60 61<blockquote> 62<pre> 63% make makefiles CCARGS="-DNO_DB" 64% make 65</pre> 66</blockquote> 67 68<p> This will disable support for "hash" and "btree" files. </p> 69 70<h2><a name="no_db">Building Postfix on systems that normally have 71no Berkeley DB library</a></h2> 72 73<p> Some UNIXes ship without Berkeley DB support; for historical 74reasons these use DBM files instead. A problem with DBM files is 75that they can store only limited amounts of data. To build Postfix 76with 77Berkeley DB support you need to download and install the source 78code from <a href="http://www.oracle.com/database/berkeley-db/">http://www.oracle.com/database/berkeley-db/</a>. </p> 79 80<p> Warning: some Linux system libraries use Berkeley DB, as do 81some third-party libraries such as SASL. If you compile Postfix 82with a different Berkeley DB implementation, then every Postfix 83program will dump core because either the system library, the SASL 84library, or Postfix itself ends up using the wrong version. </p> 85 86<p>The more recent Berkeley DB versions have a compile-time switch, 87"--with-uniquename", which renames the symbols so that multiple 88versions of Berkeley DB can co-exist in the same application. 89Although wasteful, this may be the only way to keep things from 90falling apart. </p> 91 92<p> To build Postfix after you installed the Berkeley DB from 93source code, use something like: </p> 94 95<blockquote> 96<pre> 97% make makefiles CCARGS="-DHAS_DB -I/usr/local/BerkeleyDB/include" \ 98 AUXLIBS="-L/usr/local/BerkeleyDB/lib -ldb" 99% make 100</pre> 101</blockquote> 102 103<p> If your Berkeley DB shared library is in a directory that the RUN-TIME 104linker does not know about, add a "-Wl,-R,/path/to/directory" option after 105"-ldb". </p> 106 107<p> Solaris needs this: </p> 108 109<blockquote> 110<pre> 111% make makefiles CCARGS="-DHAS_DB -I/usr/local/BerkeleyDB/include" \ 112 AUXLIBS="-R/usr/local/BerkeleyDB/lib -L/usr/local/BerkeleyDB/lib -ldb" 113% make 114</pre> 115</blockquote> 116 117<p> The exact pathnames depend on the Berkeley DB version, and on 118how it was installed. </p> 119 120<p> Warning: the file format produced by Berkeley DB version 1 is 121not compatible with that of versions 2 and 3 (versions 2 and 3 have 122the same format). If you switch between DB versions, then you may 123have to rebuild all your Postfix DB files. </p> 124 125<p> Warning: if you use Berkeley DB version 2 or later, do not 126enable DB 1.85 compatibility mode. Doing so would break fcntl file 127locking. </p> 128 129<p> Warning: if you use Perl to manipulate Postfix's Berkeley DB 130files, then you need to use the same Berkeley DB version in Perl 131as in Postfix. </p> 132 133<h2><a name="bsd">Building Postfix on BSD systems with multiple 134Berkeley DB versions</a></h2> 135 136<p> Some BSD systems ship with multiple Berkeley DB implementations. 137Normally, Postfix builds with the default DB version that ships 138with the system. </p> 139 140<p> To build Postfix on BSD systems with a non-default DB version, 141use a variant of the following commands: </p> 142 143<blockquote> 144<pre> 145% make makefiles CCARGS=-I/usr/include/db3 AUXLIBS=-ldb3 146% make 147</pre> 148</blockquote> 149 150<p> Warning: the file format produced by Berkeley DB version 1 is 151not compatible with that of versions 2 and 3 (versions 2 and 3 have 152the same format). If you switch between DB versions, then you may 153have to rebuild all your Postfix DB files. </p> 154 155<p> Warning: if you use Berkeley DB version 2 or later, do not 156enable DB 1.85 compatibility mode. Doing so would break fcntl file 157locking. </p> 158 159<p> Warning: if you use Perl to manipulate Postfix's Berkeley DB 160files, then you need to use the same Berkeley DB version in Perl 161as in Postfix. </p> 162 163<h2><a name="linux">Building Postfix on Linux systems with multiple 164Berkeley DB versions</a></h2> 165 166<p> Some Linux systems ship with multiple Berkeley DB implementations. 167Normally, Postfix builds with the default DB version that ships 168with the system. </p> 169 170<p> Warning: some Linux system libraries use Berkeley DB. If you 171compile Postfix with a non-default Berkeley DB implementation, then 172every Postfix program will dump core because either the system 173library or Postfix itself ends up using the wrong version. </p> 174 175<p> On Linux, you need to edit the makedefs script in order to 176specify a non-default DB library. The reason is that the location 177of the default db.h include file changes randomly between vendors 178and between versions, so that Postfix has to choose the file for 179you. </p> 180 181<p> Warning: the file format produced by Berkeley DB version 1 is 182not compatible with that of versions 2 and 3 (versions 2 and 3 have 183the same format). If you switch between DB versions, then you may 184have to rebuild all your Postfix DB files. </p> 185 186<p> Warning: if you use Berkeley DB version 2 or later, do not 187enable DB 1.85 compatibility mode. Doing so would break fcntl file 188locking. </p> 189 190<p> Warning: if you use Perl to manipulate Postfix's Berkeley DB 191files, then you need to use the same Berkeley DB version in Perl 192as in Postfix. </p> 193 194<h2><a name="tweak">Tweaking performance</a></h2> 195 196<p> Postfix provides two configuration parameters that control how 197much buffering memory Berkeley DB will use. </p> 198 199<ul> 200 201<li> <p> <a href="postconf.5.html#berkeley_db_create_buffer_size">berkeley_db_create_buffer_size</a> (default: 16 MBytes per 202table). This setting is used by the commands that maintain Berkeley 203DB files: <a href="postalias.1.html">postalias(1)</a> and <a href="postmap.1.html">postmap(1)</a>. For "hash" files, create 204performance degrades rapidly unless the memory pool is O(file size). 205For "btree" files, create performance is good with sorted input even 206for small memory pools, but with random input degrades rapidly 207unless the memory pool is O(file size). </p> 208 209<li> <p> <a href="postconf.5.html#berkeley_db_read_buffer_size">berkeley_db_read_buffer_size</a> (default: 128 kBytes per 210table). This setting is used by all other Postfix programs. The 211buffer size is adequate for reading. If the cache is smaller than 212the table, random read performance is hardly cache size dependent, 213except with btree tables, where the cache size must be large enough 214to contain the entire path from the root node. Empirical evidence 215shows that 64 kBytes may be sufficient. We double the size to play 216safe, and to anticipate changes in implementation and bloat. </p> 217 218</ul> 219 220<h2><a name="pthread">Missing pthread library trouble</a></h2> 221 222<p> When building Postfix fails with: </p> 223 224<blockquote> 225<pre> 226undefined reference to `pthread_condattr_setpshared' 227undefined reference to `pthread_mutexattr_destroy' 228undefined reference to `pthread_mutexattr_init' 229undefined reference to `pthread_mutex_trylock' 230</pre> 231</blockquote> 232 233<p> Add the "-lpthread" library to the "make makefiles" command. </p> 234 235<blockquote> 236<pre> 237% make makefiles .... AUXLIBS="... -lpthread" 238</pre> 239</blockquote> 240 241<p> More information is available at 242<a href="http://www.oracle.com/database/berkeley-db/">http://www.oracle.com/database/berkeley-db/</a>. </p> 243 244</body> 245 246</html> 247
