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