diff options
Diffstat (limited to 'debian/manpages/exim_db.8')
| -rw-r--r-- | debian/manpages/exim_db.8 | 193 |
1 files changed, 193 insertions, 0 deletions
diff --git a/debian/manpages/exim_db.8 b/debian/manpages/exim_db.8 new file mode 100644 index 0000000..1e25aa2 --- /dev/null +++ b/debian/manpages/exim_db.8 @@ -0,0 +1,193 @@ +.\" Hey, EMACS: -*- nroff -*- +.\" First parameter, NAME, should be all caps +.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection +.\" other parameters are allowed: see man(7), man(1) +.TH EXIM_DB 8 "December 26, 2012" +.\" Please adjust this date whenever revising the manpage. +.\" Up to date for 4.80 +.\" +.\" Some roff macros, for reference: +.\" .nh disable hyphenation +.\" .hy enable hyphenation +.\" .ad l left justify +.\" .ad b justify to both left and right margins +.\" .nf disable filling +.\" .fi enable filling +.\" .br insert line break +.\" .sp <n> insert n+1 empty lines +.\" for manpage-specific macros, see man(7) +.\" \(oqthis text is enclosed in single quotes\(cq +.\" \(lqthis text is enclosed in double quotes\(rq +.SH NAME +exim_db \- Exim's hint databases maintenance (exim_dumpdb, exim_fixdb, exim_tidydb) +.SH SYNOPSIS +.B exim_dumpdb +.I spooldir database +.br +.B exim_fixdb +.I spooldir database +.br +.B exim_tidydb +.I [\-f] [\-t time] spooldir database + +.SH 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: +.TP +.B retry +the database of retry information +.TP +.B wait\-<transport name> +databases of information about messages waiting for remote hosts +.TP +.B callout +the callout cache +.TP +.B ratelimit +the data for implementing the ratelimit ACL condition +.TP +.B misc +other hints data (for example, for serializing ETRN runs) +.P +The entire contents of a database are written to the standard output by the +.B exim_dumpdb +program, which has no options or arguments other than the spool +and database names. +For example, to dump the retry database: + +.I exim_dumpdb /var/spool/exim4 retry + +Two lines of output are produced for each entry: +.nf + 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 * + +.fi +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 \(lqretry_include_ip_address\(rq 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 +.B exim_dumpdb +for the +.I 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 +.B 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: + +.I exim_tidydb \-t 7d /var/spool/exim4 retry + +Both the +.I wait\-xxx +and +.I 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 \(lqexim_tidydb\(rq 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 \(lqwait\-\(rqxxx +records, and if this leaves any records empty, they are deleted. +For the \(lqretry\(rq database, records whose keys are non-existent message +ids are removed. +The +.B 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 \(lqexim_tidydb\(rq 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 \(lqexim_tidydb\(rq, the space used by the hints +databases is likely to keep on increasing. + +The +.B 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 \(oqd\(cq is typed at the next prompt, the entire record is deleted. +For all except the +.I retry +database, that is the only operation that can be carried out. +For the +.I 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. + +.SH 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. + +.SH SEE ALSO +.BR exim (8), +/usr/share/doc/exim4\-base/ + +.SH 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). |