EXIM_DB(8) System Manager's Manual EXIM_DB(8)
NAME
exim_db - Exim's hint databases maintenance (exim_dumpdb, exim_fixdb,
exim_tidydb)
SYNOPSIS
exim_dumpdb spooldir database
exim_fixdb spooldir database
exim_tidydb [-f] [-t time] spooldir database
DESCRIPTION
Three utility programs are provided for maintaining the DBM files that
Exim uses to contain its delivery hint information. Each program re-
quires two arguments. The first specifies the name of Exim's spool di-
rectory, and the second is the name of the database it is to operate
on. These are as follows:
retry the database of retry information
wait-<transport name>
databases of information about messages waiting for remote hosts
callout
the callout cache
ratelimit
the data for implementing the ratelimit ACL condition
misc other hints data (for example, for serializing ETRN runs)
The entire contents of a database are written to the standard output by
the exim_dumpdb program, which has no options or arguments other than
the spool and database names. For example, to dump the retry database:
exim_dumpdb /var/spool/exim4 retry
Two lines of output are produced for each entry:
T:mail.ref.example:192.168.242.242 146 77 Connection refused
31-Oct-1995 12:00:12 02-Nov-1995 12:21:39 02-Nov-1995 20:21:39 *
The first item on the first line is the key of the record. It starts
with one of the letters R, or T, depending on whether it refers to a
routing or transport retry. For a local delivery, the next part is the
local address; for a remote delivery it is the name of the remote host,
followed by its failing IP address (unless "retry_include_ip_address"
is set false on the smtp transport). If the remote port is not the
standard one (port 25), it is added to the IP address. Then there fol-
lows an error code, an additional error code, and a textual description
of the error.
The three times on the second line are the time of first failure, the
time of the last delivery attempt, and the computed time for the next
attempt. The line ends with an asterisk if the cutoff time for the
last retry rule has been exceeded.
Each output line from exim_dumpdb for the wait-xxx databases consists
of a host name followed by a list of ids for messages that are or were
waiting to be delivered to that host. If there are a very large number
for any one host, continuation records, with a sequence number added to
the host name, may be seen. The data in these records is often out of
date, because a message may be routed to several alternative hosts, and
Exim makes no effort to keep cross-references.
The exim_tidydb utility program is used to tidy up the contents of a
hints database. If run with no options, it removes all records that
are more than 30 days old. The age is calculated from the date and
time that the record was last updated. Note that, in the case of the
retry database, it is not the time since the first delivery failure.
Information about a host that has been down for more than 30 days will
remain in the database, provided that the record is updated suffi-
ciently often.
The cutoff date can be altered by means of the -t option, which must be
followed by a time. For example, to remove all records older than a
week from the retry database:
exim_tidydb -t 7d /var/spool/exim4 retry
Both the wait-xxx and retry databases contain items that involve mes-
sage ids. In the former these appear as data in records keyed by host
- they were messages that were waiting for that host - and in the lat-
ter they are the keys for retry information for messages that have suf-
fered certain types of error. When "exim_tidydb" is run, a check is
made to ensure that message ids in database records are those of mes-
sages that are still on the queue. Message ids for messages that no
longer exist are removed from "wait-"xxx records, and if this leaves
any records empty, they are deleted. For the "retry" database, records
whose keys are non-existent message ids are removed. The exim_tidydb
utility outputs comments on the standard output whenever it removes in-
formation from the database.
Certain records are automatically removed by Exim when they are no
longer needed, but others are not. For example, if all the MX hosts for
a domain are down, a retry record is created for each one. If the pri-
mary MX host comes back first, its record is removed when Exim success-
fully delivers to it, but the records for the others remain because
Exim has not tried to use those hosts.
It is important, therefore, to run "exim_tidydb" periodically on all
the hints databases. You should do this at a quiet time of day, because
it requires a database to be locked (and therefore inaccessible to
Exim) while it does its work. Removing records from a DBM file does not
normally make the file smaller, but all the common DBM libraries are
able to re-use the space that is released. After an initial phase of
increasing in size, the databases normally reach a point at which they
no longer get any bigger, as long as they are regularly tidied.
Warning: If you never run "exim_tidydb", the space used by the hints
databases is likely to keep on increasing.
The exim_fixdb program is a utility for interactively modifying data-
bases. Its main use is for testing Exim, but it might also be occa-
sionally useful for getting round problems in a live system. It has no
options, and its interface is somewhat crude. On entry, it prompts for
input with a right angle-bracket. A key of a database record can then
be entered, and the data for that record is displayed.
If 'd' is typed at the next prompt, the entire record is deleted. For
all except the retry database, that is the only operation that can be
carried out. For the retry database, each field is output preceded by
a number, and data for individual fields can be changed by typing the
field number followed by new data, for example:
> 4 951102:1000
resets the time of the next delivery attempt. Time values are given as
a sequence of digit pairs for year, month, day, hour, and minute.
Colons can be used as optional separators.
BUGS
This manual page needs a major re-work. If somebody knows better groff
than us and has more experience in writing manual pages, any patches
would be greatly appreciated.
SEE ALSO
exim(8), /usr/share/doc/exim4-base/
AUTHOR
This manual page was stitched together from spec.txt by Andreas Metzler
<ametzler at downhill.at.eu.org>, for the Debian GNU/Linux system (but
may be used by others).
December 26, 2012 EXIM_DB(8)