summaryrefslogtreecommitdiffstats
path: root/proto/DB_README.html
blob: c61723c9e3ff2d3cbfe2134feb166b9cb8f77a00 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"
        "http://www.w3.org/TR/html4/loose.dtd">

<html>

<head>

<title>Postfix Berkeley DB Howto</title>

<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link rel='stylesheet' type='text/css' href='postfix-doc.css'>

</head>

<body>

<h1><img src="postfix-logo.jpg" width="203" height="98" ALT="">Postfix Berkeley DB Howto</h1>

<hr>

<h2>Introduction</h2>

<p> Postfix uses databases of various kinds to store and look up
information. Postfix databases are specified as "type:name".
Berkeley DB implements the Postfix database type "hash" and
"btree".  The name of a Postfix Berkeley DB database is the name
of the database file without the ".db" suffix. Berkeley DB databases
are maintained with the postmap(1) command.  </p>

<p> Note: Berkeley DB version 4 is not supported by Postfix versions
before 2.0.  </p>

<p> This document describes: </p>

<ol>

<li> <p> How to build Postfix <a href="#disable_db">without Berkeley
DB support</a> even if the system comes with Berkeley DB. </p>

<li> <p> How to build Postfix on <a href="#no_db">systems that
normally have no Berkeley DB library</a>. </p>

<li> <p> How to build Postfix on <a href="#bsd">BSD</a> or <a
href="#linux">Linux</a> systems with multiple Berkeley DB
versions.  </p>

<li> <p> How to <a href="#tweak">tweak</a> performance. </p>

<li> <p> Missing <a href="#pthread">pthread</a> library trouble. </p>

</ol>

<h2><a name="disable_db">Building Postfix without Berkeley
DB support even if the system comes with Berkeley DB</a></h2>

<p> Note: The following instructions apply to Postfix 2.9 and later. </p>

<p> Postfix will normally enable Berkeley DB support if the system
is known to have it. To build Postfix without Berkeley DB support,
build the makefiles as follows: </p>

<blockquote>
<pre>
% make makefiles CCARGS="-DNO_DB"
% make
</pre>
</blockquote>

<p> This will disable support for "hash" and "btree" files. </p>

<h2><a name="no_db">Building Postfix on systems that normally have
no Berkeley DB library</a></h2>

<p> Some UNIXes ship without Berkeley DB support; for historical
reasons these use DBM files instead. A problem with DBM files is
that they can store only limited amounts of data. To build Postfix
with
Berkeley DB support you need to download and install the source
code from http://www.oracle.com/database/berkeley-db/. </p>

<p> Warning: some Linux system libraries use Berkeley DB, as do
some third-party libraries such as SASL. If you compile Postfix
with a different Berkeley DB implementation, then every Postfix
program will dump core because either the system library, the SASL
library, or Postfix itself ends up using the wrong version. </p>

<p>The more recent Berkeley DB versions have a compile-time switch,
"--with-uniquename", which renames the symbols so that multiple
versions of Berkeley DB can co-exist in the same application.
Although wasteful, this may be the only way to keep things from
falling apart. </p>

<p> To build Postfix after you installed the Berkeley DB from
source code, use something like: </p>

<blockquote>
<pre>
% make makefiles CCARGS="-DHAS_DB -I/usr/local/BerkeleyDB/include" \
    AUXLIBS="-L/usr/local/BerkeleyDB/lib -ldb"
% make
</pre>
</blockquote>

<p> If your Berkeley DB shared library is in a directory that the RUN-TIME
linker does not know about, add a "-Wl,-R,/path/to/directory" option after
"-ldb". </p>

<p> Solaris needs this: </p>

<blockquote>
<pre>
% make makefiles CCARGS="-DHAS_DB -I/usr/local/BerkeleyDB/include" \
    AUXLIBS="-R/usr/local/BerkeleyDB/lib -L/usr/local/BerkeleyDB/lib -ldb"
% make
</pre>
</blockquote>

<p> The exact pathnames depend on the Berkeley DB version, and on
how it was installed. </p>

<p> Warning: the file format produced by Berkeley DB version 1 is
not compatible with that of versions 2 and 3 (versions 2 and 3 have
the same format). If you switch between DB versions, then you may
have to rebuild all your Postfix DB files. </p>

<p> Warning: if you use Berkeley DB version 2 or later, do not
enable DB 1.85 compatibility mode. Doing so would break fcntl file
locking. </p>

<p> Warning: if you use Perl to manipulate Postfix's Berkeley DB
files, then you need to use the same Berkeley DB version in Perl
as in Postfix.  </p>

<h2><a name="bsd">Building Postfix on BSD systems with multiple
Berkeley DB versions</a></h2>

<p> Some BSD systems ship with multiple Berkeley DB implementations.
Normally, Postfix builds with the default DB version that ships
with the system. </p>

<p> To build Postfix on BSD systems with a non-default DB version,
use a variant of the following commands: </p>

<blockquote>
<pre>
% make makefiles CCARGS=-I/usr/include/db3 AUXLIBS=-ldb3
% make
</pre>
</blockquote>

<p> Warning: the file format produced by Berkeley DB version 1 is
not compatible with that of versions 2 and 3 (versions 2 and 3 have
the same format). If you switch between DB versions, then you may
have to rebuild all your Postfix DB files. </p>

<p> Warning: if you use Berkeley DB version 2 or later, do not
enable DB 1.85 compatibility mode. Doing so would break fcntl file
locking. </p>

<p> Warning: if you use Perl to manipulate Postfix's Berkeley DB
files, then you need to use the same Berkeley DB version in Perl
as in Postfix.  </p>

<h2><a name="linux">Building Postfix on Linux systems with multiple
Berkeley DB versions</a></h2>

<p> Some Linux systems ship with multiple Berkeley DB implementations.
Normally, Postfix builds with the default DB version that ships
with the system. </p>

<p> Warning: some Linux system libraries use Berkeley DB. If you
compile Postfix with a non-default Berkeley DB implementation, then
every Postfix program will dump core because either the system
library or Postfix itself ends up using the wrong version. </p>

<p> On Linux, you need to edit the makedefs script in order to
specify a non-default DB library.  The reason is that the location
of the default db.h include file changes randomly between vendors
and between versions, so that Postfix has to choose the file for
you. </p>

<p> Warning: the file format produced by Berkeley DB version 1 is
not compatible with that of versions 2 and 3 (versions 2 and 3 have
the same format). If you switch between DB versions, then you may
have to rebuild all your Postfix DB files. </p>

<p> Warning: if you use Berkeley DB version 2 or later, do not
enable DB 1.85 compatibility mode. Doing so would break fcntl file
locking. </p>

<p> Warning: if you use Perl to manipulate Postfix's Berkeley DB
files, then you need to use the same Berkeley DB version in Perl
as in Postfix.  </p>

<h2><a name="tweak">Tweaking performance</a></h2>

<p> Postfix provides two configuration parameters that control how
much buffering memory Berkeley DB will use. </p>

<ul>

<li> <p> berkeley_db_create_buffer_size (default: 16 MBytes per
table).  This setting is used by the commands that maintain Berkeley
DB files: postalias(1) and postmap(1).  For "hash" files, create
performance degrades rapidly unless the memory pool is O(file size).
For "btree" files, create performance is good with sorted input even
for small memory pools, but with random input degrades rapidly
unless the memory pool is O(file size). </p>

<li> <p> berkeley_db_read_buffer_size (default: 128 kBytes per
table).  This setting is used by all other Postfix programs. The
buffer size is adequate for reading. If the cache is smaller than
the table, random read performance is hardly cache size dependent,
except with btree tables, where the cache size must be large enough
to contain the entire path from the root node. Empirical evidence
shows that 64 kBytes may be sufficient. We double the size to play
safe, and to anticipate changes in implementation and bloat. </p>

</ul>

<h2><a name="pthread">Missing pthread library trouble</a></h2>

<p> When building Postfix fails with: </p>

<blockquote>
<pre>
undefined reference to `pthread_condattr_setpshared'
undefined reference to `pthread_mutexattr_destroy'
undefined reference to `pthread_mutexattr_init'
undefined reference to `pthread_mutex_trylock'
</pre>
</blockquote>

<p> Add the "-lpthread" library to the "make makefiles" command. </p>

<blockquote>
<pre>
% make makefiles .... AUXLIBS="... -lpthread"
</pre>
</blockquote>

<p> More information is available at
http://www.oracle.com/database/berkeley-db/. </p>

</body>

</html>