debian/manpages/exim_db.8

   1 .\"                                      Hey, EMACS: -*- nroff -*-
   2 .\" First parameter, NAME, should be all caps
   3 .\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
   4 .\" other parameters are allowed: see man(7), man(1)
   5 .TH EXIM_DB 8 "December 26, 2012"
   6 .\" Please adjust this date whenever revising the manpage.
   7 .\" Up to date for 4.80
   8 .\"
   9 .\" Some roff macros, for reference:
  10 .\" .nh        disable hyphenation
  11 .\" .hy        enable hyphenation
  12 .\" .ad l      left justify
  13 .\" .ad b      justify to both left and right margins
  14 .\" .nf        disable filling
  15 .\" .fi        enable filling
  16 .\" .br        insert line break
  17 .\" .sp <n>    insert n+1 empty lines
  18 .\" for manpage-specific macros, see man(7)
  19 .\" \(oqthis text is enclosed in single quotes\(cq
  20 .\" \(lqthis text is enclosed in double quotes\(rq
  21 .SH NAME
  22 exim_db \- Exim's hint databases maintenance (exim_dumpdb, exim_fixdb, exim_tidydb)
  23 .SH SYNOPSIS
  24 .B exim_dumpdb
  25 .I spooldir database
  26 .br
  27 .B exim_fixdb
  28 .I spooldir database
  29 .br
  30 .B exim_tidydb
  31 .I [\-f] [\-t time] spooldir database
  32
  33 .SH DESCRIPTION
  34 Three utility programs are provided for maintaining the DBM files that
  35 Exim uses to contain its delivery hint information.
  36 Each program requires two arguments.
  37 The first specifies the name of Exim's spool directory, and the second is
  38 the name of the database it is to operate on.
  39 These are as follows:
  40 .TP
  41 .B retry
  42 the database of retry information
  43 .TP
  44 .B wait\-<transport name>
  45 databases of information about messages waiting for remote hosts
  46 .TP
  47 .B callout
  48 the callout cache
  49 .TP
  50 .B ratelimit
  51 the data for implementing the ratelimit ACL condition
  52 .TP
  53 .B misc
  54 other hints data (for example, for serializing ETRN runs)
  55 .P
  56 The entire contents of a database are written to the standard output by the
  57 .B exim_dumpdb
  58 program, which has no options or arguments other than the spool
  59 and database names.
  60 For example, to dump the retry database:
  61
  62 .I exim_dumpdb /var/spool/exim4 retry
  63
  64 Two lines of output are produced for each entry:
  65 .nf
  66     T:mail.ref.example:192.168.242.242 146 77 Connection refused
  67   31-Oct-1995 12:00:12  02-Nov-1995 12:21:39  02-Nov-1995 20:21:39 *
  68
  69 .fi
  70 The first item on the first line is the key of the record.
  71 It starts with one of the letters R, or T, depending on whether it refers
  72 to a routing or transport retry.
  73 For a local delivery, the next part is the local address; for a remote
  74 delivery it is the name of the remote host, followed by its failing IP
  75 address (unless \(lqretry_include_ip_address\(rq is set false on the smtp
  76 transport). If the remote port is not the standard one (port 25), it is
  77 added to the IP address.
  78 Then there follows an error code, an additional error code, and a
  79 textual description of the error.
  80
  81 The three times on the second line are the time of first failure, the time of
  82 the last delivery attempt, and the computed time for the next attempt.
  83 The line ends with an asterisk if the cutoff time for the last retry rule
  84 has been exceeded.
  85
  86 Each output line from
  87 .B exim_dumpdb
  88 for the
  89 .I wait\-xxx
  90 databases consists of a host name followed by a list of ids for messages
  91 that are or were waiting to be delivered to that host.
  92 If there are a very large number for any one host, continuation records,
  93 with a sequence number added to the host name, may be seen.
  94 The data in these records is often out of date, because a message may be
  95 routed to several alternative hosts, and Exim makes no effort to keep
  96 cross-references.
  97
  98 The
  99 .B exim_tidydb
 100 utility program is used to tidy up the contents of a hints database.
 101 If run with no options, it removes all records that are more than 30 days
 102 old.  The age is calculated from the date and time that the record was last
 103 updated.  Note that, in the case of the retry database, it is not the time
 104 since the first delivery failure. Information about a host that has been
 105 down for more than 30 days will remain in the database, provided that the
 106 record is updated sufficiently often.
 107
 108 The cutoff date can be altered by means of the \-t option, which must be
 109 followed by a time.
 110 For example, to remove all records older than a week from the retry
 111 database:
 112
 113 .I exim_tidydb \-t 7d /var/spool/exim4 retry
 114
 115 Both the
 116 .I wait\-xxx
 117 and
 118 .I retry
 119 databases contain items that involve message ids.
 120 In the former these appear as data in records keyed by host - they were
 121 messages that were waiting for that host - and in the latter they are the
 122 keys for retry information for messages that have suffered certain types
 123 of error.
 124 When \(lqexim_tidydb\(rq is run, a check is made to ensure that message ids in
 125 database records are those of messages that are still on the queue.
 126 Message ids for messages that no longer exist are removed from \(lqwait\-\(rqxxx
 127 records, and if this leaves any records empty, they are deleted.
 128 For the \(lqretry\(rq database, records whose keys are non-existent message
 129 ids are removed.
 130 The
 131 .B exim_tidydb
 132 utility outputs comments on the standard output whenever it removes
 133 information from the database.
 134
 135 Certain records are automatically removed by Exim when they are no longer
 136 needed, but others are not. For example, if all the MX hosts for a domain
 137 are down, a retry record is created for each one. If the primary MX host
 138 comes back first, its record is removed when Exim successfully delivers to
 139 it, but the records for the others remain because Exim has not tried to use
 140 those hosts.
 141
 142 It is important, therefore, to run \(lqexim_tidydb\(rq periodically on all
 143 the hints databases. You should do this at a quiet time of day, because it
 144 requires a database to be locked (and therefore inaccessible to Exim) while
 145 it does its work. Removing records from a DBM file does not normally make
 146 the file smaller, but all the common DBM libraries are able to re-use the
 147 space that is released. After an initial phase of increasing in size, the
 148 databases normally reach a point at which they no longer get any bigger, as
 149 long as they are regularly tidied.
 150
 151 Warning: If you never run \(lqexim_tidydb\(rq, the space used by the hints
 152 databases is likely to keep on increasing.
 153
 154 The
 155 .B exim_fixdb
 156 program is a utility for interactively modifying databases.
 157 Its main use is for testing Exim, but it might also be occasionally useful
 158 for getting round problems in a live system.
 159 It has no options, and its interface is somewhat crude.
 160 On entry, it prompts for input with a right angle-bracket.
 161 A key of a database record can then be entered, and the data for that
 162 record is displayed.
 163
 164 If \(oqd\(cq is typed at the next prompt, the entire record is deleted.
 165 For all except the
 166 .I retry
 167 database, that is the only operation that can be carried out.
 168 For the
 169 .I retry
 170 database, each field is output preceded by a number, and data for individual
 171 fields can be changed by typing the field number followed by new data, for
 172 example:
 173
 174   > 4 951102:1000
 175
 176 resets the time of the next delivery attempt.
 177 Time values are given as a sequence of digit pairs for year, month, day,
 178 hour, and minute.
 179 Colons can be used as optional separators.
 180
 181 .SH BUGS
 182 This manual page needs a major re-work. If somebody knows better groff
 183 than us and has more experience in writing manual pages, any patches
 184 would be greatly appreciated.
 185
 186 .SH SEE ALSO
 187 .BR exim (8),
 188 /usr/share/doc/exim4\-base/
 189
 190 .SH AUTHOR
 191 This manual page was stitched together from spec.txt by
 192 Andreas Metzler <ametzler at downhill.at.eu.org>,
 193 for the Debian GNU/Linux system (but may be used by others).