CDB_README.html revision 1.1.1.6
1 1.1 tron <!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN" 2 1.1.1.5 christos "https://www.w3.org/TR/html4/loose.dtd"> 3 1.1 tron 4 1.1 tron <html> 5 1.1 tron 6 1.1 tron <head> 7 1.1 tron 8 1.1 tron <title>Postfix CDB Howto</title> 9 1.1 tron 10 1.1.1.3 christos <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> 11 1.1.1.4 christos <link rel='stylesheet' type='text/css' href='postfix-doc.css'> 12 1.1 tron 13 1.1 tron </head> 14 1.1 tron 15 1.1 tron <body> 16 1.1 tron 17 1.1 tron <h1><img src="postfix-logo.jpg" width="203" height="98" ALT="">Postfix CDB Howto</h1> 18 1.1 tron 19 1.1 tron <hr> 20 1.1 tron 21 1.1 tron <h2>Introduction</h2> 22 1.1 tron 23 1.1 tron <p> CDB (Constant DataBase) is an indexed file format designed by 24 1.1 tron Daniel Bernstein. CDB is optimized exclusively for read access 25 1.1 tron and guarantees that each record will be read in at most two disk 26 1.1 tron accesses. This is achieved by forgoing support for incremental 27 1.1 tron updates: no single-record inserts or deletes are supported. CDB 28 1.1 tron databases can be modified only by rebuilding them completely from 29 1.1 tron scratch, hence the "constant" qualifier in the name. </p> 30 1.1 tron 31 1.1 tron <p> Postfix CDB databases are specified as "<a href="CDB_README.html">cdb</a>:<i>name</i>", where 32 1.1 tron <i>name</i> specifies the CDB file name without the ".cdb" suffix 33 1.1 tron (another suffix, ".tmp", is used temporarily while a CDB file is 34 1.1 tron under construction). CDB databases are maintained with the <a href="postmap.1.html">postmap(1)</a> 35 1.1 tron or <a href="postalias.1.html">postalias(1)</a> command. The <a href="DATABASE_README.html">DATABASE_README</a> document has general 36 1.1 tron information about Postfix databases. </p> 37 1.1 tron 38 1.1.1.5 christos <p> You can use "<a href="CDB_README.html">cdb</a>:" tables wherever you can use read-only "hash", 39 1.1.1.5 christos "btree" or "lmdb" tables with the following limitations: </p> 40 1.1.1.5 christos 41 1.1.1.5 christos <ul> 42 1.1.1.5 christos 43 1.1.1.6 christos <li> <p> Historically, CDB databases could not be larger than 4GB 44 1.1.1.6 christos on LP64 and ILP32 systems, because the CDB library API used unsigned 45 1.1.1.6 christos integers for file offsets. Recently, the CDB format was updated to 46 1.1.1.6 christos take better advantage of 64-bit processors. </p> 47 1.1.1.5 christos 48 1.1.1.6 christos <li> <p> The "<b>postmap -i</b>" (individual record insertion) and 49 1.1.1.6 christos "<b>postmap -d</b>" (individual record deletion) command-line 50 1.1.1.5 christos options are not available. For the same reason the "<a href="CDB_README.html">cdb</a>:" map type 51 1.1.1.5 christos cannot be used to for persistent caches, such as the address 52 1.1.1.5 christos verification cache for the <a href="verify.8.html">verify(8)</a> service, the TLS session cache 53 1.1.1.5 christos for the <a href="tlsmgr.8.html">tlsmgr(8)</a> service, or the dynamic allowlist for <a href="postscreen.8.html">postscreen(8)</a>. 54 1.1.1.5 christos </p> 55 1.1.1.5 christos 56 1.1.1.5 christos <li> <p> The "sequence" operation ("<b>postmap -s</b>" or "<b>postalias 57 1.1.1.5 christos -s</b>") is available only wen Postfix is built with tinycdb by 58 1.1.1.5 christos Michael Tokarev, not with the original cdb library by Daniel Bernstein. 59 1.1.1.5 christos </p> 60 1.1.1.5 christos 61 1.1.1.5 christos </ul> 62 1.1.1.5 christos 63 1.1 tron <p> CDB support is available with Postfix 2.2 and later releases. 64 1.1.1.5 christos The remainder of this document describes how to build Postfix with 65 1.1.1.5 christos CDB support. </p> 66 1.1 tron 67 1.1 tron <h2>Building Postfix with CDB support</h2> 68 1.1 tron 69 1.1 tron <p> These instructions assume that you build Postfix from source 70 1.1 tron code as described in the <a href="INSTALL.html">INSTALL</a> document. Some modification may 71 1.1 tron be required if you build Postfix from a vendor-specific source 72 1.1 tron package. </p> 73 1.1 tron 74 1.1.1.6 christos <p> Historically, Postfix has been compatible with two CDB 75 1.1.1.6 christos implementations: </p> 76 1.1 tron 77 1.1 tron <ul> 78 1.1 tron 79 1.1 tron <li> <p> The original cdb library from Daniel Bernstein, available 80 1.1.1.5 christos from <a href="https://cr.yp.to/cdb.html">https://cr.yp.to/cdb.html</a>, and </p> 81 1.1 tron 82 1.1 tron <li> <p> tinycdb (version 0.5 and later) from Michael Tokarev, 83 1.1.1.5 christos available from <a href="https://www.corpit.ru/mjt/tinycdb.html">https://www.corpit.ru/mjt/tinycdb.html</a>. </p> 84 1.1 tron 85 1.1 tron </ul> 86 1.1 tron 87 1.1.1.6 christos <p> To build Postfix with tinycdb, install tinycdb so that the files 88 1.1.1.6 christos "cdb.h" and "libcdb.*" are in the appropriate locations for your 89 1.1.1.6 christos OS distribution. Then, use something like: </p> 90 1.1 tron 91 1.1 tron <blockquote> 92 1.1 tron <pre> 93 1.1 tron % make tidy 94 1.1.1.6 christos % make -f Makefile.init makefiles \ 95 1.1.1.6 christos "CCARGS=-DHAS_CDB -I/usr/local/include ..." \ 96 1.1.1.6 christos "<a href="CDB_README.html">AUXLIBS_CDB</a>=L/usr/local/lib -lcdb" ... 97 1.1 tron % make 98 1.1 tron </pre> 99 1.1 tron </blockquote> 100 1.1 tron 101 1.1.1.6 christos <p> The exact pathnames depend on where "cdb.h" and "libcdb.*" are 102 1.1.1.6 christos installed. The "<tt>...</tt>" may contain build information for 103 1.1.1.6 christos other optional features such as databases, TLS support, and so on. 104 1.1.1.6 christos </p> 105 1.1.1.6 christos 106 1.1.1.6 christos <p> Alternatively, for the D.J.B. version of CDB:, build but do not 107 1.1.1.6 christos install CDB, then in the Postfix top-level directory: <p> 108 1.1 tron 109 1.1 tron <blockquote> 110 1.1 tron <pre> 111 1.1 tron % make tidy 112 1.1.1.6 christos % CDB=<i>/some/where/</i>cdb-<i>version</i> 113 1.1.1.6 christos % make -f Makefile.init makefiles \ 114 1.1.1.6 christos "CCARGS=-DHAS_CDB -I$CDB ..." \ 115 1.1.1.6 christos "<a href="CDB_README.html">AUXLIBS_CDB</a>=$CDB/cdb.a $CDB/alloc.a $CDB/buffer.a $CDB/unix.a $CDB/byte.a" ... 116 1.1 tron % make 117 1.1 tron </pre> 118 1.1 tron </blockquote> 119 1.1 tron 120 1.1.1.6 christos <p> (With cdb-20251021 and later, use 'cdb64.a' instead of 'alloc.a'.) </p> 121 1.1.1.6 christos 122 1.1.1.2 christos <p> Postfix versions before 3.0 use AUXLIBS instead of <a href="CDB_README.html">AUXLIBS_CDB</a>. 123 1.1.1.2 christos With Postfix 3.0 and later, the old AUXLIBS variable still supports 124 1.1.1.2 christos building a statically-loaded CDB database client, but only the new 125 1.1.1.2 christos <a href="CDB_README.html">AUXLIBS_CDB</a> variable supports building a dynamically-loaded or 126 1.1.1.2 christos statically-loaded CDB database client. </p> 127 1.1.1.2 christos 128 1.1.1.2 christos <blockquote> 129 1.1.1.2 christos 130 1.1.1.2 christos <p> Failure to use the <a href="CDB_README.html">AUXLIBS_CDB</a> variable will defeat the purpose 131 1.1.1.2 christos of dynamic database client loading. Every Postfix executable file 132 1.1.1.2 christos will have CDB database library dependencies. And that was exactly 133 1.1.1.2 christos what dynamic database client loading was meant to avoid. </p> 134 1.1.1.2 christos 135 1.1.1.2 christos </blockquote> 136
Indexes created Fri Sep 25 00:27:33 UTC 2026