EXIM_DB(8)



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)

Man(1) output converted with man2html
list of all man pages