diff options
Diffstat (limited to 'proto/DB_README.html')
| -rw-r--r-- | proto/DB_README.html | 246 |
1 files changed, 246 insertions, 0 deletions
diff --git a/proto/DB_README.html b/proto/DB_README.html new file mode 100644 index 0000000..cca3e2b --- /dev/null +++ b/proto/DB_README.html @@ -0,0 +1,246 @@ +<!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"> + +</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> |