summaryrefslogtreecommitdiffstats
path: root/debian/manpages/exim_db.8
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--debian/manpages/exim_db.8193
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).