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)