EXIM_DB(8)

💖 NAME 💖

exim_db — Exim's hint databases maintenance, aka the whole exim_dumpdb, exim_fixdb, exim_tidydb squad 🎀

So bestie, you know that manual page header situation? This is EXIM_DB(8) from the System Manager's Manual. Yes queen, section 8, system admin territory. Let's get into it. ✨

---

🦋 SYNOPSIS 🦋

exim_dumpdb spooldir database
exim_fixdb spooldir database
exim_tidydb [-f] [-t time] spooldir database

Look at them, three little icons living their best lives. 🫶

---

🌸 DESCRIPTION 🌸

Okay so, there are three utility programs for keeping the DBM files in check — the ones Exim uses to hold its delivery hint information. Each program needs two arguments, no more no less:

• the first one is the name of Exim's spool directory 🗂️
• the second one is the name of the database it's gonna operate on 💾

And the databases are, in no particular order but very much in this order:

• 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, like for serializing ETRN runs 🧚

---

✨ exim_dumpdb ✨

exim_dumpdb writes the entire contents of a database to the standard output. It has no options or arguments other than the spool and database names. She's low maintenance like that 💅

So like, to dump the retry database:

exim_dumpdb /var/spool/exim4 retry

Two lines of output get produced for every entry, no cap:

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, periodt. It starts with one of the letters R or T, depending on whether it's referring to a routing retry or a transport retry. For a local delivery, the next part is the local address. For a remote delivery it's the name of the remote host, followed by its failing IP address — unless retry_include_ip_address is set false on the smtp transport, iykyk. And if the remote port isn't the standard one (port 25), it gets added to the IP address. Then comes an error code, an additional error code, and a textual description of the error. Chef's kiss, that's the whole anatomy 🧬

The three times on the second line are:

1. the time of first failure
2. the time of the last delivery attempt
3. the computed time for the next attempt

And the line ends with an asterisk if the cutoff time for the last retry rule has been exceeded. ⭐

---

🐚 the wait-xxx databases 🐚

Each output line from exim_dumpdb for the wait-xxx databases is 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 show up. 💀

And ngl, 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. It's giving messy, but that's just how it is 🙈

---

🧹 exim_tidydb 🧹

exim_tidydb is the one that tidies up the contents of a hints database. Run it with no options and 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.

Careful bestie — in the case of the retry database, it is not the time since the first delivery failure.

So information about a host that's been down for more than 30 days will remain in the database, provided that the record is updated sufficiently often. She stays relevant, okay? 👑

The cutoff date can be altered with 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

🎀 the message id situation 🎀

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. 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. And exim_tidydb outputs comments on the standard output whenever it removes information from the database. Very transparent of her 💜

🌈 why you actually have to do this 🌈

Certain records are automatically removed by Exim when they're no longer needed, but others are not. Example time: 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. Growth arc complete, we love a glow-up that stabilizes 🌱

Warning: If you never run exim_tidydb, the space used by the hints databases is likely to keep on increasing. Not a vibe. Run the tidy. 🔥

---

🛠️ exim_fixdb 🛠️

exim_fixdb 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. We're keeping it real, it's giving raw 💀

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

which 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. Bestie if that's you, the door is open, come thru 🫶

---

👀 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).

---

And that's the whole page, bestie — originally dated December 26, 2012, living under the EXIM_DB(8) tag. Mwah, slay, go tidy your databases. 💖✨🎀