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

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)