external/ibm-public/postfix/dist/README_FILES/DB_README

   1 P\bPo\bos\bst\btf\bfi\bix\bx B\bBe\ber\brk\bke\bel\ble\bey\by D\bDB\bB H\bHo\bow\bwt\bto\bo
   2
   3 -------------------------------------------------------------------------------
   4
   5 I\bIn\bnt\btr\bro\bod\bdu\buc\bct\bti\bio\bon\bn
   6
   7 Postfix uses databases of various kinds to store and look up information.
   8 Postfix databases are specified as "type:name". Berkeley DB implements the
   9 Postfix database type "hash" and "btree". The name of a Postfix Berkeley DB
  10 database is the name of the database file without the ".db" suffix. Berkeley DB
  11 databases are maintained with the postmap(1) command.
  12
  13 Note: Berkeley DB version 4 is not supported by Postfix versions before 2.0.
  14
  15 This document describes:
  16
  17  1. How to build Postfix on systems without Berkeley DB library.
  18
  19  2. How to build Postfix on BSD or Linux systems with multiple Berkeley DB
  20     versions.
  21
  22  3. How to tweak performance.
  23
  24  4. Missing pthread library trouble.
  25
  26 B\bBu\bui\bil\bld\bdi\bin\bng\bg P\bPo\bos\bst\btf\bfi\bix\bx o\bon\bn s\bsy\bys\bst\bte\bem\bms\bs w\bwi\bit\bth\bho\bou\but\bt B\bBe\ber\brk\bke\bel\ble\bey\by D\bDB\bB
  27
  28 Some UNIXes ship without Berkeley DB support; for historical reasons these use
  29 DBM files instead. A problem with DBM files is that they can store only limited
  30 amounts of data. To build Postfix with Berkeley DB support you need to download
  31 and install the source code from http://www.oracle.com/database/berkeley-db/.
  32
  33 Warning: some Linux system libraries use Berkeley DB, as do some third-party
  34 libraries such as SASL. If you compile Postfix with a different Berkeley DB
  35 implementation, then every Postfix program will dump core because either the
  36 system library, the SASL library, or Postfix itself ends up using the wrong
  37 version.
  38
  39 The more recent Berkeley DB versions have a compile-time switch, "--with-
  40 uniquename", which renames the symbols so that multiple versions of Berkeley DB
  41 can co-exist in the same application. Although wasteful, this may be the only
  42 way to keep things from falling apart.
  43
  44 To build Postfix after you installed the Berkeley DB from source code, use
  45 something like:
  46
  47     % make tidy
  48     % make makefiles CCARGS="-DHAS_DB -I/usr/local/BerkeleyDB/include" \
  49         AUXLIBS="-L/usr/local/BerkeleyDB/lib -ldb"
  50     % make
  51
  52 Solaris needs this:
  53
  54     % make tidy
  55     % make makefiles CCARGS="-DHAS_DB -I/usr/local/BerkeleyDB/include" \
  56         AUXLIBS="-R/usr/local/BerkeleyDB/lib -L/usr/local/BerkeleyDB/lib -ldb"
  57     % make
  58
  59 The exact pathnames depend on the Berkeley DB version, and on how it was
  60 installed.
  61
  62 Warning: the file format produced by Berkeley DB version 1 is not compatible
  63 with that of versions 2 and 3 (versions 2 and 3 have the same format). If you
  64 switch between DB versions, then you may have to rebuild all your Postfix DB
  65 files.
  66
  67 Warning: if you use Berkeley DB version 2 or later, do not enable DB 1.85
  68 compatibility mode. Doing so would break fcntl file locking.
  69
  70 Warning: if you use Perl to manipulate Postfix's Berkeley DB files, then you
  71 need to use the same Berkeley DB version in Perl as in Postfix.
  72
  73 B\bBu\bui\bil\bld\bdi\bin\bng\bg P\bPo\bos\bst\btf\bfi\bix\bx o\bon\bn B\bBS\bSD\bD s\bsy\bys\bst\bte\bem\bms\bs w\bwi\bit\bth\bh m\bmu\bul\blt\bti\bip\bpl\ble\be B\bBe\ber\brk\bke\bel\ble\bey\by D\bDB\bB v\bve\ber\brs\bsi\bio\bon\bns\bs
  74
  75 Some BSD systems ship with multiple Berkeley DB implementations. Normally,
  76 Postfix builds with the default DB version that ships with the system.
  77
  78 To build Postfix on BSD systems with a non-default DB version, use a variant of
  79 the following commands:
  80
  81     % make tidy
  82     % make makefiles CCARGS=-I/usr/include/db3 AUXLIBS=-ldb3
  83     % make
  84
  85 Warning: the file format produced by Berkeley DB version 1 is not compatible
  86 with that of versions 2 and 3 (versions 2 and 3 have the same format). If you
  87 switch between DB versions, then you may have to rebuild all your Postfix DB
  88 files.
  89
  90 Warning: if you use Berkeley DB version 2 or later, do not enable DB 1.85
  91 compatibility mode. Doing so would break fcntl file locking.
  92
  93 Warning: if you use Perl to manipulate Postfix's Berkeley DB files, then you
  94 need to use the same Berkeley DB version in Perl as in Postfix.
  95
  96 B\bBu\bui\bil\bld\bdi\bin\bng\bg P\bPo\bos\bst\btf\bfi\bix\bx o\bon\bn L\bLi\bin\bnu\bux\bx s\bsy\bys\bst\bte\bem\bms\bs w\bwi\bit\bth\bh m\bmu\bul\blt\bti\bip\bpl\ble\be B\bBe\ber\brk\bke\bel\ble\bey\by D\bDB\bB v\bve\ber\brs\bsi\bio\bon\bns\bs
  97
  98 Some Linux systems ship with multiple Berkeley DB implementations. Normally,
  99 Postfix builds with the default DB version that ships with the system.
 100
 101 Warning: some Linux system libraries use Berkeley DB. If you compile Postfix
 102 with a non-default Berkeley DB implementation, then every Postfix program will
 103 dump core because either the system library or Postfix itself ends up using the
 104 wrong version.
 105
 106 On Linux, you need to edit the makedefs script in order to specify a non-
 107 default DB library. The reason is that the location of the default db.h include
 108 file changes randomly between vendors and between versions, so that Postfix has
 109 to choose the file for you.
 110
 111 Warning: the file format produced by Berkeley DB version 1 is not compatible
 112 with that of versions 2 and 3 (versions 2 and 3 have the same format). If you
 113 switch between DB versions, then you may have to rebuild all your Postfix DB
 114 files.
 115
 116 Warning: if you use Berkeley DB version 2 or later, do not enable DB 1.85
 117 compatibility mode. Doing so would break fcntl file locking.
 118
 119 Warning: if you use Perl to manipulate Postfix's Berkeley DB files, then you
 120 need to use the same Berkeley DB version in Perl as in Postfix.
 121
 122 T\bTw\bwe\bea\bak\bki\bin\bng\bg p\bpe\ber\brf\bfo\bor\brm\bma\ban\bnc\bce\be
 123
 124 Postfix provides two configuration parameters that control how much buffering
 125 memory Berkeley DB will use.
 126
 127   * berkeley_db_create_buffer_size (default: 16 MBytes per table). This setting
 128     is used by the commands that maintain Berkeley DB files: postalias(1) and
 129     postmap(1). For "hash" files, create performance degrades rapidly unless
 130     the memory pool is O(file size). For "btree" files, create performance is
 131     good with sorted input even for small memory pools, but with random input
 132     degrades rapidly unless the memory pool is O(file size).
 133
 134   * berkeley_db_read_buffer_size (default: 128 kBytes per table). This setting
 135     is used by all other Postfix programs. The buffer size is adequate for
 136     reading. If the cache is smaller than the table, random read performance is
 137     hardly cache size dependent, except with btree tables, where the cache size
 138     must be large enough to contain the entire path from the root node.
 139     Empirical evidence shows that 64 kBytes may be sufficient. We double the
 140     size to play safe, and to anticipate changes in implementation and bloat.
 141
 142 M\bMi\bis\bss\bsi\bin\bng\bg p\bpt\bth\bhr\bre\bea\bad\bd l\bli\bib\bbr\bra\bar\bry\by t\btr\bro\bou\bub\bbl\ble\be
 143
 144 When building Postfix fails with:
 145
 146     undefined reference to `pthread_condattr_setpshared'
 147     undefined reference to `pthread_mutexattr_destroy'
 148     undefined reference to `pthread_mutexattr_init'
 149     undefined reference to `pthread_mutex_trylock'
 150
 151 Add the "-lpthread" library to the "make makefiles" command.
 152
 153     % make makefiles .... AUXLIBS="... -lpthread"
 154
 155 More information is available at http://www.oracle.com/database/berkeley-db/.
 156