diff options
Diffstat (limited to 'README_FILES/DB_README')
| -rw-r--r-- | README_FILES/DB_README | 173 |
1 files changed, 173 insertions, 0 deletions
diff --git a/README_FILES/DB_README b/README_FILES/DB_README new file mode 100644 index 0000000..2d0ac93 --- /dev/null +++ b/README_FILES/DB_README @@ -0,0 +1,173 @@ +PPoossttffiixx BBeerrkkeelleeyy DDBB HHoowwttoo + +------------------------------------------------------------------------------- + +IInnttrroodduuccttiioonn + +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. + +Note: Berkeley DB version 4 is not supported by Postfix versions before 2.0. + +This document describes: + + 1. How to build Postfix without Berkeley DB support even if the system comes + with Berkeley DB. + + 2. How to build Postfix on systems that normally have no Berkeley DB library. + + 3. How to build Postfix on BSD or Linux systems with multiple Berkeley DB + versions. + + 4. How to tweak performance. + + 5. Missing pthread library trouble. + +BBuuiillddiinngg PPoossttffiixx wwiitthhoouutt BBeerrkkeelleeyy DDBB ssuuppppoorrtt eevveenn iiff tthhee ssyysstteemm ccoommeess wwiitthh +BBeerrkkeelleeyy DDBB + +Note: The following instructions apply to Postfix 2.9 and later. + +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: + + % make makefiles CCARGS="-DNO_DB" + % make + +This will disable support for "hash" and "btree" files. + +BBuuiillddiinngg PPoossttffiixx oonn ssyysstteemmss tthhaatt nnoorrmmaallllyy hhaavvee nnoo BBeerrkkeelleeyy DDBB lliibbrraarryy + +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/. + +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. + +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. + +To build Postfix after you installed the Berkeley DB from source code, use +something like: + + % make makefiles CCARGS="-DHAS_DB -I/usr/local/BerkeleyDB/include" \ + AUXLIBS="-L/usr/local/BerkeleyDB/lib -ldb" + % make + +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". + +Solaris needs this: + + % make makefiles CCARGS="-DHAS_DB -I/usr/local/BerkeleyDB/include" \ + AUXLIBS="-R/usr/local/BerkeleyDB/lib -L/usr/local/BerkeleyDB/lib -ldb" + % make + +The exact pathnames depend on the Berkeley DB version, and on how it was +installed. + +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. + +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. + +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. + +BBuuiillddiinngg PPoossttffiixx oonn BBSSDD ssyysstteemmss wwiitthh mmuullttiippllee BBeerrkkeelleeyy DDBB vveerrssiioonnss + +Some BSD systems ship with multiple Berkeley DB implementations. Normally, +Postfix builds with the default DB version that ships with the system. + +To build Postfix on BSD systems with a non-default DB version, use a variant of +the following commands: + + % make makefiles CCARGS=-I/usr/include/db3 AUXLIBS=-ldb3 + % make + +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. + +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. + +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. + +BBuuiillddiinngg PPoossttffiixx oonn LLiinnuuxx ssyysstteemmss wwiitthh mmuullttiippllee BBeerrkkeelleeyy DDBB vveerrssiioonnss + +Some Linux systems ship with multiple Berkeley DB implementations. Normally, +Postfix builds with the default DB version that ships with the system. + +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. + +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. + +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. + +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. + +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. + +TTwweeaakkiinngg ppeerrffoorrmmaannccee + +Postfix provides two configuration parameters that control how much buffering +memory Berkeley DB will use. + + * 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). + + * 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. + +MMiissssiinngg pptthhrreeaadd lliibbrraarryy ttrroouubbllee + +When building Postfix fails with: + + undefined reference to `pthread_condattr_setpshared' + undefined reference to `pthread_mutexattr_destroy' + undefined reference to `pthread_mutexattr_init' + undefined reference to `pthread_mutex_trylock' + +Add the "-lpthread" library to the "make makefiles" command. + + % make makefiles .... AUXLIBS="... -lpthread" + +More information is available at http://www.oracle.com/database/berkeley-db/. + |