exim_db - Exim's hint databases maintenance (exim_dumpdb, exim_fixdb,
exim_tidydb)
exim_dumpdb spooldir database
exim_fixdb spooldir database
exim_tidydb [-f] [-t time] spooldir database
Three utility programs are provided for maintaining the DBM files that Exim uses
to contain its delivery hint information. Each program requires two arguments.
The first specifies the name of Exim's spool directory, 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 follows 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 sufficiently 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
message 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 latter they
are the keys for retry information for messages that have suffered certain
types of error. When “exim_tidydb” is run, a check is made to
ensure that message ids in database records are those of messages 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 information 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 primary MX host comes
back first, its record is removed when Exim successfully 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
databases. Its main use is for testing Exim, but it might also be occasionally
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.
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.
exim(8), /usr/share/doc/exim4-base/
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).