external/ibm-public/postfix/dist/proto/DB_README.html

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