summaryrefslogtreecommitdiffstats
path: root/proto/DB_README.html
diff options
context:
space:
mode:
Diffstat (limited to 'proto/DB_README.html')
-rw-r--r--proto/DB_README.html242
1 files changed, 242 insertions, 0 deletions
diff --git a/proto/DB_README.html b/proto/DB_README.html
new file mode 100644
index 0000000..0d4fa39
--- /dev/null
+++ b/proto/DB_README.html
@@ -0,0 +1,242 @@
+<!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=us-ascii">
+
+</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> 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>