Relax chown requirements when check_owner is false

[hcoop/debian/exim4.git] / debian / manpages / exim_db.8

.\"                                      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).