<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html401/loose.dtd">
<html>
<!-- Created on September, 10 2009 by texi2html 1.78 -->
<!--
Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author)
Karl Berry <karl@freefriends.org>
Olaf Bachmann <obachman@mathematik.uni-kl.de>
and many others.
Maintained by: Many creative people.
Send bugs and suggestions to <texi2html-bug@nongnu.org>
-->
<head>
<title>Specification of the Exim Mail Transfer Agent: 50. Exim utilities</title>
<meta name="description" content="Specification of the Exim Mail Transfer Agent: 50. Exim utilities">
<meta name="keywords" content="Specification of the Exim Mail Transfer Agent: 50. Exim utilities">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="texi2html 1.78">
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
pre.display {font-family: serif}
pre.format {font-family: serif}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: serif; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: serif; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.roman {font-family:serif; font-weight:normal;}
span.sansserif {font-family:sans-serif; font-weight:normal;}
ul.toc {list-style: none}
-->
</style>
</head>
<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
<a name="Exim-utilities"></a>
<a name="SEC452"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="spec_49.html#SEC451" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#SEC453" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="spec_49.html#SEC435" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="spec.html#SEC_Top" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="spec_51.html#SEC468" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="spec.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[Contents]</td>
<td valign="middle" align="left">[<a href="spec_55.html#SEC493" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="spec_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h1 class="chapter"> 50. Exim utilities </h1>
<p>A number of utility scripts and programs are supplied with Exim and are
described in this chapter. There is also the Exim Monitor, which is covered in
the next chapter. The utilities described here are:
</p>
<table>
<tr><td>
<p><a href="#SEC453">Finding out what Exim processes are doing (exiwhat)</a></p></td><td><p> <em>exiwhat</em></p></td><td><p> list what Exim processes are doing
</p></td></tr>
<tr><td>
<p><a href="#SEC454">Selective queue listing (exiqgrep)</a></p></td><td><p> <em>exiqgrep</em></p></td><td><p> grep the queue
</p></td></tr>
<tr><td>
<p><a href="#SEC455">Summarizing the queue (exiqsumm)</a></p></td><td><p> <em>exiqsumm</em></p></td><td><p> summarize the queue
</p></td></tr>
<tr><td>
<p><a href="#SEC456">Extracting specific information from the log (exigrep)</a></p></td><td><p> <em>exigrep</em></p></td><td><p> search the main log
</p></td></tr>
<tr><td>
<p><a href="#SEC457">Selecting messages by various criteria (exipick)</a></p></td><td><p> <em>exipick</em></p></td><td><p> select messages on various criteria
</p></td></tr>
<tr><td>
<p><a href="#SEC458">Cycling log files (exicyclog)</a></p></td><td><p> <em>exicyclog</em></p></td><td><p> cycle (rotate) log files
</p></td></tr>
<tr><td>
<p><a href="#SEC459">Mail statistics (eximstats)</a></p></td><td><p> <em>eximstats</em></p></td><td><p> extract statistics from the log
</p></td></tr>
<tr><td>
<p><a href="#SEC460">Checking access policy (exim_checkaccess)</a></p></td><td><p> <em>exim_checkaccess</em></p></td><td><p> check address acceptance from given IP
</p></td></tr>
<tr><td>
<p><a href="#SEC461">Making DBM files (exim_dbmbuild)</a></p></td><td><p> <em>exim_dbmbuild</em></p></td><td><p> build a DBM file
</p></td></tr>
<tr><td>
<p><a href="#SEC462">Finding individual retry times (exinext)</a></p></td><td><p> <em>exinext</em></p></td><td><p> extract retry information
</p></td></tr>
<tr><td>
<p><a href="#SEC463">Hints database maintenance</a></p></td><td><p> <em>exim_dumpdb</em></p></td><td><p> dump a hints database
</p></td></tr>
<tr><td>
<p><a href="#SEC463">Hints database maintenance</a></p></td><td><p> <em>exim_tidydb</em></p></td><td><p> clean up a hints database
</p></td></tr>
<tr><td>
<p><a href="#SEC463">Hints database maintenance</a></p></td><td><p> <em>exim_fixdb</em></p></td><td><p> patch a hints database
</p></td></tr>
<tr><td>
<p><a href="#SEC467">Mailbox maintenance (exim_lock)</a></p></td><td><p> <em>exim_lock</em></p></td><td><p> lock a mailbox file
</p></td></tr>
</table>
<p>Another utility that might be of use to sites with many MTAs is Tom Kistner's
<em>exilog</em>. It provides log visualizations across multiple Exim servers. See
<strong><a href="http://duncanthrax.net/exilog/">http://duncanthrax.net/exilog/</a></strong> for details.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top"><a href="#SEC453">50.1 Finding out what Exim processes are doing (exiwhat)</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#SEC454">50.2 Selective queue listing (exiqgrep)</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#SEC455">50.3 Summarizing the queue (exiqsumm)</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#SEC456">50.4 Extracting specific information from the log (exigrep)</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#SEC457">50.5 Selecting messages by various criteria (exipick)</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#SEC458">50.6 Cycling log files (exicyclog)</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#SEC459">50.7 Mail statistics (eximstats)</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#SEC460">50.8 Checking access policy (exim_checkaccess)</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#SEC461">50.9 Making DBM files (exim_dbmbuild)</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#SEC462">50.10 Finding individual retry times (exinext)</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#SEC463">50.11 Hints database maintenance</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#SEC464">50.12 exim_dumpdb</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#SEC465">50.13 exim_tidydb</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#SEC466">50.14 exim_fixdb</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#SEC467">50.15 Mailbox maintenance (exim_lock)</a></td><td> </td><td align="left" valign="top">
</td></tr>
</table>
<hr size="6">
<a name="Finding-out-what-Exim-processes-are-doing-_005bexiwhat_005d"></a>
<a name="SEC453"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#SEC452" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#SEC454" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#SEC452" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#SEC452" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="spec_51.html#SEC468" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="spec.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[Contents]</td>
<td valign="middle" align="left">[<a href="spec_55.html#SEC493" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="spec_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h2 class="section"> 50.1 Finding out what Exim processes are doing (exiwhat) </h2>
<p>On operating systems that can restart a system call after receiving a signal
(most modern OS), an Exim process responds to the SIGUSR1 signal by writing
a line describing what it is doing to the file ‘<tt>exim-process.info</tt>’ in the
Exim spool directory. The <em>exiwhat</em> script sends the signal to all Exim
processes it can find, having first emptied the file. It then waits for one
second to allow the Exim processes to react before displaying the results. In
order to run <em>exiwhat</em> successfully you have to have sufficient privilege to
send the signal to the Exim processes, so it is normally run as root.
</p>
<p><strong>Warning</strong>: This is not an efficient process. It is intended for occasional
use by system administrators. It is not sensible, for example, to set up a
script that sends SIGUSR1 signals to Exim processes at short intervals.
</p>
<p>Unfortunately, the <em>ps</em> command that <em>exiwhat</em> uses to find Exim processes
varies in different operating systems. Not only are different options used,
but the format of the output is different. For this reason, there are some
system configuration options that configure exactly how <em>exiwhat</em> works. If
it doesn't seem to be working for you, check the following compile-time
options:
</p>
<table><tr><td> </td><td><pre class="display">EXIWHAT_PS_CMD the command for running ps
EXIWHAT_PS_ARG the argument for ps
EXIWHAT_EGREP_ARG the argument for egrep to select from ps output
EXIWHAT_KILL_ARG the argument for the kill command
</pre></td></tr></table>
<p>An example of typical output from <em>exiwhat</em> is
</p>
<table><tr><td> </td><td><pre class="example">164 daemon: -q1h, listening on port 25
10483 running queue: waiting for 0tAycK-0002ij-00 (10492)
10492 delivering 0tAycK-0002ij-00 to mail.ref.example
[10.19.42.42] (editor@ref.example)
10592 handling incoming call from [192.168.243.242]
10628 accepting a local non-SMTP message
</pre></td></tr></table>
<p>The first number in the output line is the process number. The third line has
been split here, in order to fit it on the page.
</p>
<hr size="6">
<a name="Selective-queue-listing-_005bexiqgrep_005d"></a>
<a name="SEC454"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#SEC453" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#SEC455" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#SEC452" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#SEC452" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="spec_51.html#SEC468" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="spec.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[Contents]</td>
<td valign="middle" align="left">[<a href="spec_55.html#SEC493" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="spec_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h2 class="section"> 50.2 Selective queue listing (exiqgrep) </h2>
<p>This utility is a Perl script contributed by Matt Hubbard. It runs
</p>
<table><tr><td> </td><td><pre class="example">exim -bpu
</pre></td></tr></table>
<p>to obtain a queue listing with undelivered recipients only, and then greps the
output to select messages that match given criteria. The following selection
options are available:
</p>
<dl compact="compact">
<dt> <strong>-f</strong><<em>regex</em>></dt>
<dd><p>Match the sender address. The field that is tested is enclosed in angle
brackets, so you can test for bounce messages with
</p>
<table><tr><td> </td><td><pre class="example">exiqgrep -f '^<>$'
</pre></td></tr></table>
</dd>
<dt> <strong>-r</strong><<em>regex</em>></dt>
<dd><p>Match a recipient address. The field that is tested is not enclosed in angle
brackets.
</p>
</dd>
<dt> <strong>-s</strong><<em>regex</em>></dt>
<dd><p>Match against the size field.
</p>
</dd>
<dt> <strong>-y</strong><<em>seconds</em>></dt>
<dd><p>Match messages that are younger than the given time.
</p>
</dd>
<dt> <strong>-o</strong><<em>seconds</em>></dt>
<dd><p>Match messages that are older than the given time.
</p>
</dd>
<dt> <strong>-z</strong></dt>
<dd><p>Match only frozen messages.
</p>
</dd>
<dt> <strong>-x</strong></dt>
<dd><p>Match only non-frozen messages.
</p></dd>
</dl>
<p>The following options control the format of the output:
</p>
<dl compact="compact">
<dt> <strong>-c</strong></dt>
<dd><p>Display only the count of matching messages.
</p>
</dd>
<dt> <strong>-l</strong></dt>
<dd><p>Long format - display the full message information as output by Exim. This is
the default.
</p>
</dd>
<dt> <strong>-i</strong></dt>
<dd><p>Display message ids only.
</p>
</dd>
<dt> <strong>-b</strong></dt>
<dd><p>Brief format - one line per message.
</p>
</dd>
<dt> <strong>-R</strong></dt>
<dd><p>Display messages in reverse order.
</p></dd>
</dl>
<p>There is one more option, <code>-h</code>, which outputs a list of options.
</p>
<hr size="6">
<a name="Summarizing-the-queue-_005bexiqsumm_005d"></a>
<a name="SEC455"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#SEC454" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#SEC456" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#SEC452" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#SEC452" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="spec_51.html#SEC468" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="spec.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[Contents]</td>
<td valign="middle" align="left">[<a href="spec_55.html#SEC493" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="spec_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h2 class="section"> 50.3 Summarizing the queue (exiqsumm) </h2>
<p>The <em>exiqsumm</em> utility is a Perl script which reads the output of ‘<samp>exim
-bp</samp>’ and produces a summary of the messages on the queue. Thus, you use it by
running a command such as
</p>
<table><tr><td> </td><td><pre class="example">exim -bp | exiqsumm
</pre></td></tr></table>
<p>The output consists of one line for each domain that has messages waiting for
it, as in the following example:
</p>
<table><tr><td> </td><td><pre class="example">3 2322 74m 66m msn.com.example
</pre></td></tr></table>
<p>Each line lists the number of pending deliveries for a domain, their total
volume, and the length of time that the oldest and the newest messages have
been waiting. Note that the number of pending deliveries is greater than the
number of messages when messages have more than one recipient.
</p>
<p>A summary line is output at the end. By default the output is sorted on the
domain name, but <em>exiqsumm</em> has the options <code>-a</code> and <code>-c</code>, which cause
the output to be sorted by oldest message and by count of messages,
respectively. There are also three options that split the messages for each
domain into two or more subcounts: <code>-b</code> separates bounce messages, <code>-f</code>
separates frozen messages, and <code>-s</code> separates messages according to their
sender.
</p>
<p>The output of <em>exim -bp</em> contains the original addresses in the message, so
this also applies to the output from <em>exiqsumm</em>. No domains from addresses
generated by aliasing or forwarding are included (unless the <code>one_time</code>
option of the <code>redirect</code> router has been used to convert them into "top
level" addresses).
</p>
<hr size="6">
<a name="Extracting-specific-information-from-the-log-_005bexigrep_005d"></a>
<a name="SEC456"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#SEC455" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#SEC457" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#SEC452" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#SEC452" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="spec_51.html#SEC468" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="spec.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[Contents]</td>
<td valign="middle" align="left">[<a href="spec_55.html#SEC493" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="spec_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h2 class="section"> 50.4 Extracting specific information from the log (exigrep) </h2>
<p>The <em>exigrep</em> utility is a Perl script that searches one or more main log
files for entries that match a given pattern. When it finds a match, it
extracts all the log entries for the relevant message, not just those that
match the pattern. Thus, <em>exigrep</em> can extract complete log entries for a
given message, or all mail for a given user, or for a given host, for example.
The input files can be in Exim log format or syslog format.
If a matching log line is not associated with a specific message, it is
included in <em>exigrep</em>'s output without any additional lines. The usage is:
</p>
<table><tr><td> </td><td><pre class="display">exigrep [-t<n>] [-I] [-l] [-v] <pattern> [<log file>] ...
</pre></td></tr></table>
<p>If no log file names are given on the command line, the standard input is read.
</p>
<p>The <code>-t</code> argument specifies a number of seconds. It adds an additional
condition for message selection. Messages that are complete are shown only if
they spent more than <<em>n</em>> seconds on the queue.
</p>
<p>By default, <em>exigrep</em> does case-insensitive matching. The <code>-I</code> option
makes it case-sensitive. This may give a performance improvement when searching
large log files. Without <code>-I</code>, the Perl pattern matches use Perl's ‘<samp>/i</samp>’
option; with <code>-I</code> they do not. In both cases it is possible to change the
case sensitivity within the pattern by using ‘<samp>(?i)</samp>’ or ‘<samp>(?-i)</samp>’.
</p>
<p>The <code>-l</code> option means "literal", that is, treat all characters in the
pattern as standing for themselves. Otherwise the pattern must be a Perl
regular expression.
</p>
<p>The <code>-v</code> option inverts the matching condition. That is, a line is selected
if it does <em>not</em> match the pattern.
</p>
<p>If the location of a <em>zcat</em> command is known from the definition of
ZCAT_COMMAND in ‘<tt>Local/Makefile</tt>’, <em>exigrep</em> automatically passes any file
whose name ends in COMPRESS_SUFFIX through <em>zcat</em> as it searches it.
</p>
<hr size="6">
<a name="Selecting-messages-by-various-criteria-_005bexipick_005d"></a>
<a name="SEC457"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#SEC456" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#SEC458" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#SEC452" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#SEC452" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="spec_51.html#SEC468" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="spec.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[Contents]</td>
<td valign="middle" align="left">[<a href="spec_55.html#SEC493" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="spec_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h2 class="section"> 50.5 Selecting messages by various criteria (exipick) </h2>
<p>John Jetmore's <em>exipick</em> utility is included in the Exim distribution. It
lists messages from the queue according to a variety of criteria. For details
of <em>exipick</em>'s facilities, visit the web page at
<strong><a href="http://www.exim.org/eximwiki/ToolExipickManPage">http://www.exim.org/eximwiki/ToolExipickManPage</a></strong> or run <em>exipick</em> with
the <code>--help</code> option.
</p>
<hr size="6">
<a name="Cycling-log-files-_005bexicyclog_005d"></a>
<a name="SEC458"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#SEC457" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#SEC459" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#SEC452" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#SEC452" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="spec_51.html#SEC468" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="spec.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[Contents]</td>
<td valign="middle" align="left">[<a href="spec_55.html#SEC493" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="spec_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h2 class="section"> 50.6 Cycling log files (exicyclog) </h2>
<p>The <em>exicyclog</em> script can be used to cycle (rotate) <em>mainlog</em> and
<em>rejectlog</em> files. This is not necessary if only syslog is being used, or if
you are using log files with datestamps in their names (see section
<a href="spec_49.html#SEC438">Datestamped log files</a>). Some operating systems have their own standard mechanisms
for log cycling, and these can be used instead of <em>exicyclog</em> if preferred.
There are two command line options for <em>exicyclog</em>:
</p>
<ul class="toc">
<li>
<code>-k</code> <<em>count</em>> specifies the number of log files to keep, overriding the
default that is set when Exim is built. The default default is 10.
</li><li>
<code>-l</code> <<em>path</em>> specifies the log file path, in the same format as Exim's
<code>log_file_path</code> option (for example, ‘<samp>/var/log/exim_%slog</samp>’), again
overriding the script's default, which is to find the setting from Exim's
configuration.
</li></ul>
<p>Each time <em>exicyclog</em> is run the file names get "shuffled down" by one. If
the main log file name is ‘<tt>mainlog</tt>’ (the default) then when <em>exicyclog</em> is
run ‘<tt>mainlog</tt>’ becomes ‘<tt>mainlog.01</tt>’, the previous ‘<tt>mainlog.01</tt>’ becomes
‘<tt>mainlog.02</tt>’ and so on, up to the limit that is set in the script or by the
<code>-k</code> option. Log files whose numbers exceed the limit are discarded. Reject
logs are handled similarly.
</p>
<p>If the limit is greater than 99, the script uses 3-digit numbers such as
‘<tt>mainlog.001</tt>’, ‘<tt>mainlog.002</tt>’, etc. If you change from a number less than 99
to one that is greater, or <em>vice versa</em>, you will have to fix the names of
any existing log files.
</p>
<p>If no ‘<tt>mainlog</tt>’ file exists, the script does nothing. Files that "drop off"
the end are deleted. All files with numbers greater than 01 are compressed,
using a compression command which is configured by the COMPRESS_COMMAND
setting in ‘<tt>Local/Makefile</tt>’. It is usual to run <em>exicyclog</em> daily from a
root <code>crontab</code> entry of the form
</p>
<table><tr><td> </td><td><pre class="example">1 0 * * * su exim -c /usr/exim/bin/exicyclog
</pre></td></tr></table>
<p>assuming you have used the name "exim" for the Exim user. You can run
<em>exicyclog</em> as root if you wish, but there is no need.
</p>
<hr size="6">
<a name="Mail-statistics-_005beximstats_005d"></a>
<a name="SEC459"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#SEC458" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#SEC460" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#SEC452" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#SEC452" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="spec_51.html#SEC468" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="spec.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[Contents]</td>
<td valign="middle" align="left">[<a href="spec_55.html#SEC493" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="spec_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h2 class="section"> 50.7 Mail statistics (eximstats) </h2>
<p>A Perl script called <em>eximstats</em> is provided for extracting statistical
information from log files. The output is either plain text, or HTML.
Exim log files are also supported by the <em>Lire</em> system produced by the
LogReport Foundation <strong><a href="http://www.logreport.org">http://www.logreport.org</a></strong>.
</p>
<p>The <em>eximstats</em> script has been hacked about quite a bit over time. The
latest version is the result of some extensive revision by Steve Campbell. A
lot of information is given by default, but there are options for suppressing
various parts of it. Following any options, the arguments to the script are a
list of files, which should be main log files. For example:
</p>
<table><tr><td> </td><td><pre class="example">eximstats -nr /var/spool/exim/log/mainlog.01
</pre></td></tr></table>
<p>By default, <em>eximstats</em> extracts information about the number and volume of
messages received from or delivered to various hosts. The information is sorted
both by message count and by volume, and the top fifty hosts in each category
are listed on the standard output. Similar information, based on email
addresses or domains instead of hosts can be requested by means of various
options. For messages delivered and received locally, similar statistics are
also produced per user.
</p>
<p>The output also includes total counts and statistics about delivery errors, and
histograms showing the number of messages received and deliveries made in each
hour of the day. A delivery with more than one address in its envelope (for
example, an SMTP transaction with more than one RCPT command) is counted
as a single delivery by <em>eximstats</em>.
</p>
<p>Though normally more deliveries than receipts are reported (as messages may
have multiple recipients), it is possible for <em>eximstats</em> to report more
messages received than delivered, even though the queue is empty at the start
and end of the period in question. If an incoming message contains no valid
recipients, no deliveries are recorded for it. A bounce message is handled as
an entirely separate message.
</p>
<p><em>eximstats</em> always outputs a grand total summary giving the volume and number
of messages received and deliveries made, and the number of hosts involved in
each case. It also outputs the number of messages that were delayed (that is,
not completely delivered at the first attempt), and the number that had at
least one address that failed.
</p>
<p>The remainder of the output is in sections that can be independently disabled
or modified by various options. It consists of a summary of deliveries by
transport, histograms of messages received and delivered per time interval
(default per hour), information about the time messages spent on the queue,
a list of relayed messages, lists of the top fifty sending hosts, local
senders, destination hosts, and destination local users by count and by volume,
and a list of delivery errors that occurred.
</p>
<p>The relay information lists messages that were actually relayed, that is, they
came from a remote host and were directly delivered to some other remote host,
without being processed (for example, for aliasing or forwarding) locally.
</p>
<p>There are quite a few options for <em>eximstats</em> to control exactly what it
outputs. These are documented in the Perl script itself, and can be extracted
by running the command <code>perldoc</code> on the script. For example:
</p>
<table><tr><td> </td><td><pre class="example">perldoc /usr/exim/bin/eximstats
</pre></td></tr></table>
<hr size="6">
<a name="Checking-access-policy-_005bexim_005fcheckaccess_005d"></a>
<a name="SEC460"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#SEC459" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#SEC461" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#SEC452" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#SEC452" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="spec_51.html#SEC468" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="spec.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[Contents]</td>
<td valign="middle" align="left">[<a href="spec_55.html#SEC493" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="spec_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h2 class="section"> 50.8 Checking access policy (exim_checkaccess) </h2>
<p>The <code>-bh</code> command line argument allows you to run a fake SMTP session with
debugging output, in order to check what Exim is doing when it is applying
policy controls to incoming SMTP mail. However, not everybody is sufficiently
familiar with the SMTP protocol to be able to make full use of <code>-bh</code>, and
sometimes you just want to answer the question "Does this address have
access?" without bothering with any further details.
</p>
<p>The <em>exim_checkaccess</em> utility is a "packaged" version of <code>-bh</code>. It takes
two arguments, an IP address and an email address:
</p>
<table><tr><td> </td><td><pre class="example">exim_checkaccess 10.9.8.7 A.User@a.domain.example
</pre></td></tr></table>
<p>The utility runs a call to Exim with the <code>-bh</code> option, to test whether the
given email address would be accepted in a RCPT command in a TCP/IP
connection from the host with the given IP address. The output of the utility
is either the word "accepted", or the SMTP error response, for example:
</p>
<table><tr><td> </td><td><pre class="example">Rejected:
550 Relay not permitted
</pre></td></tr></table>
<p>When running this test, the utility uses ‘<samp><></samp>’ as the envelope sender address
for the MAIL command, but you can change this by providing additional
options. These are passed directly to the Exim command. For example, to specify
that the test is to be run with the sender address <em>himself@there.example</em>
you can use:
</p>
<table><tr><td> </td><td><pre class="example">exim_checkaccess 10.9.8.7 A.User@a.domain.example \
-f himself@there.example
</pre></td></tr></table>
<p>Note that these additional Exim command line items must be given after the two
mandatory arguments.
</p>
<p>Because the <code>exim_checkaccess</code> uses <code>-bh</code>, it does not perform callouts
while running its checks. You can run checks that include callouts by using
<code>-bhc</code>, but this is not yet available in a "packaged" form.
</p>
<hr size="6">
<a name="Making-DBM-files-_005bexim_005fdbmbuild_005d"></a>
<a name="SEC461"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#SEC460" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#SEC462" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#SEC452" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#SEC452" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="spec_51.html#SEC468" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="spec.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[Contents]</td>
<td valign="middle" align="left">[<a href="spec_55.html#SEC493" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="spec_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h2 class="section"> 50.9 Making DBM files (exim_dbmbuild) </h2>
<p>The <em>exim_dbmbuild</em> program reads an input file containing keys and data in
the format used by the <code>lsearch</code> lookup (see section
<a href="spec_9.html#SEC92">Single-key lookup types</a>). It writes a DBM file using the lower-cased alias
names as keys and the remainder of the information as data. The lower-casing
can be prevented by calling the program with the <code>-nolc</code> option.
</p>
<p>A terminating zero is included as part of the key string. This is expected by
the <code>dbm</code> lookup type. However, if the option <code>-nozero</code> is given,
<em>exim_dbmbuild</em> creates files without terminating zeroes in either the key
strings or the data strings. The <code>dbmnz</code> lookup type can be used with such
files.
</p>
<p>The program requires two arguments: the name of the input file (which can be a
single hyphen to indicate the standard input), and the name of the output file.
It creates the output under a temporary name, and then renames it if all went
well.
</p>
<a name="IDX2831"></a>
<p>If the native DB interface is in use (USE_DB is set in a compile-time
configuration file - this is common in free versions of Unix) the two file
names must be different, because in this mode the Berkeley DB functions create
a single output file using exactly the name given. For example,
</p>
<table><tr><td> </td><td><pre class="example">exim_dbmbuild /etc/aliases /etc/aliases.db
</pre></td></tr></table>
<p>reads the system alias file and creates a DBM version of it in
‘<tt>/etc/aliases.db</tt>’.
</p>
<p>In systems that use the <em>ndbm</em> routines (mostly proprietary versions of
Unix), two files are used, with the suffixes ‘<tt>.dir</tt>’ and ‘<tt>.pag</tt>’. In this
environment, the suffixes are added to the second argument of
<em>exim_dbmbuild</em>, so it can be the same as the first. This is also the case
when the Berkeley functions are used in compatibility mode (though this is not
recommended), because in that case it adds a ‘<tt>.db</tt>’ suffix to the file name.
</p>
<p>If a duplicate key is encountered, the program outputs a warning, and when it
finishes, its return code is 1 rather than zero, unless the <code>-noduperr</code>
option is used. By default, only the first of a set of duplicates is used -
this makes it compatible with <code>lsearch</code> lookups. There is an option
<code>-lastdup</code> which causes it to use the data for the last duplicate instead.
There is also an option <code>-nowarn</code>, which stops it listing duplicate keys to
<code>stderr</code>. For other errors, where it doesn't actually make a new file, the
return code is 2.
</p>
<hr size="6">
<a name="Finding-individual-retry-times-_005bexinext_005d"></a>
<a name="SEC462"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#SEC461" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#SEC463" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#SEC452" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#SEC452" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="spec_51.html#SEC468" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="spec.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[Contents]</td>
<td valign="middle" align="left">[<a href="spec_55.html#SEC493" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="spec_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h2 class="section"> 50.10 Finding individual retry times (exinext) </h2>
<p>A utility called <em>exinext</em> (mostly a Perl script) provides the ability to
fish specific information out of the retry database. Given a mail domain (or a
complete address), it looks up the hosts for that domain, and outputs any retry
information for the hosts or for the domain. At present, the retry information
is obtained by running <em>exim_dumpdb</em> (see below) and post-processing the
output. For example:
</p>
<table><tr><td> </td><td><pre class="example">$ exinext piglet@milne.fict.example
kanga.milne.example:192.168.8.1 error 146: Connection refused
first failed: 21-Feb-1996 14:57:34
last tried: 21-Feb-1996 14:57:34
next try at: 21-Feb-1996 15:02:34
roo.milne.example:192.168.8.3 error 146: Connection refused
first failed: 20-Jan-1996 13:12:08
last tried: 21-Feb-1996 11:42:03
next try at: 21-Feb-1996 19:42:03
past final cutoff time
</pre></td></tr></table>
<p>You can also give <em>exinext</em> a local part, without a domain, and it
will give any retry information for that local part in your default domain.
A message id can be used to obtain retry information pertaining to a specific
message. This exists only when an attempt to deliver a message to a remote host
suffers a message-specific error (see section <a href="spec_45.html#SEC407">Errors in outgoing SMTP</a>).
<em>exinext</em> is not particularly efficient, but then it is not expected to be
run very often.
</p>
<p>The <em>exinext</em> utility calls Exim to find out information such as the location
of the spool directory. The utility has <code>-C</code> and <code>-D</code> options, which are
passed on to the <em>exim</em> commands. The first specifies an alternate Exim
configuration file, and the second sets macros for use within the configuration
file. These features are mainly to help in testing, but might also be useful in
environments where more than one configuration file is in use.
</p>
<hr size="6">
<a name="Hints-database-maintenance"></a>
<a name="SEC463"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#SEC462" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#SEC464" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#SEC452" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#SEC452" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="spec_51.html#SEC468" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="spec.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[Contents]</td>
<td valign="middle" align="left">[<a href="spec_55.html#SEC493" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="spec_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h2 class="section"> 50.11 Hints database maintenance </h2>
<p>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:
</p>
<ul class="toc">
<li>
<em>retry</em>: the database of retry information
</li><li>
<em>wait-</em><<em>transport name</em>>: databases of information about messages waiting
for remote hosts
</li><li>
<em>callout</em>: the callout cache
</li><li>
<em>ratelimit</em>: the data for implementing the ratelimit ACL condition
</li><li>
<em>misc</em>: other hints data
</li></ul>
<p>The <em>misc</em> database is used for
</p>
<ul class="toc">
<li>
Serializing ETRN runs (when <code>smtp_etrn_serialize</code> is set)
</li><li>
Serializing delivery to a specific host (when <code>serialize_hosts</code> is set in an
<code>smtp</code> transport)
</li></ul>
<hr size="6">
<a name="exim_005fdumpdb"></a>
<a name="SEC464"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#SEC463" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#SEC465" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#SEC452" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#SEC452" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="spec_51.html#SEC468" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="spec.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[Contents]</td>
<td valign="middle" align="left">[<a href="spec_55.html#SEC493" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="spec_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h2 class="section"> 50.12 exim_dumpdb </h2>
<p>The entire contents of a database are written to the standard output by the
<em>exim_dumpdb</em> program, which has no options or arguments other than the
spool and database names. For example, to dump the retry database:
</p>
<table><tr><td> </td><td><pre class="example">exim_dumpdb /var/spool/exim retry
</pre></td></tr></table>
<p>Two lines of output are produced for each entry:
</p>
<table><tr><td> </td><td><pre class="example">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 *
</pre></td></tr></table>
<p>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 <code>retry_include_ip_address</code> is set false on the <code>smtp</code>
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.
</p>
<p>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.
</p>
<p>Each output line from <em>exim_dumpdb</em> for the <em>wait-xxx</em> 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.
</p>
<hr size="6">
<a name="exim_005ftidydb"></a>
<a name="SEC465"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#SEC464" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#SEC466" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#SEC452" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#SEC452" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="spec_51.html#SEC468" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="spec.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[Contents]</td>
<td valign="middle" align="left">[<a href="spec_55.html#SEC493" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="spec_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h2 class="section"> 50.13 exim_tidydb </h2>
<p>The <em>exim_tidydb</em> 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 <em>not</em> 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.
</p>
<p>The cutoff date can be altered by means of the <code>-t</code> option, which must be
followed by a time. For example, to remove all records older than a week from
the retry database:
</p>
<table><tr><td> </td><td><pre class="example">exim_tidydb -t 7d /var/spool/exim retry
</pre></td></tr></table>
<p>Both the <em>wait-xxx</em> and <em>retry</em> 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 <em>exim_tidydb</em> 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
<em>wait-xxx</em> records, and if this leaves any records empty, they are deleted.
For the <em>retry</em> database, records whose keys are non-existent message ids are
removed. The <em>exim_tidydb</em> utility outputs comments on the standard output
whenever it removes information from the database.
</p>
<p>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.
</p>
<p>It is important, therefore, to run <em>exim_tidydb</em> 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.
</p>
<p><strong>Warning</strong>: If you never run <em>exim_tidydb</em>, the space used by the hints
databases is likely to keep on increasing.
</p>
<hr size="6">
<a name="exim_005ffixdb"></a>
<a name="SEC466"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#SEC465" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#SEC467" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#SEC452" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#SEC452" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="spec_51.html#SEC468" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="spec.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[Contents]</td>
<td valign="middle" align="left">[<a href="spec_55.html#SEC493" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="spec_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h2 class="section"> 50.14 exim_fixdb </h2>
<p>The <em>exim_fixdb</em> 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.
</p>
<p>If "d" is typed at the next prompt, the entire record is deleted. For all
except the <em>retry</em> database, that is the only operation that can be carried
out. For the <em>retry</em> 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:
</p>
<table><tr><td> </td><td><pre class="example">> 4 951102:1000
</pre></td></tr></table>
<p>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.
</p>
<hr size="6">
<a name="Mailbox-maintenance-_005bexim_005flock_005d"></a>
<a name="SEC467"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#SEC466" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="spec_51.html#SEC468" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#SEC452" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#SEC452" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="spec_51.html#SEC468" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="spec.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[Contents]</td>
<td valign="middle" align="left">[<a href="spec_55.html#SEC493" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="spec_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h2 class="section"> 50.15 Mailbox maintenance (exim_lock) </h2>
<p>The <em>exim_lock</em> utility locks a mailbox file using the same algorithm as
Exim. For a discussion of locking issues, see section <a href="spec_26.html#SEC225">Operational details for appending</a>.
<em>Exim_lock</em> can be used to prevent any modification of a mailbox by Exim or
a user agent while investigating a problem. The utility requires the name of
the file as its first argument. If the locking is successful, the second
argument is run as a command (using C's <code>system()</code> function); if there is no
second argument, the value of the SHELL environment variable is used; if this
is unset or empty, ‘<tt>/bin/sh</tt>’ is run. When the command finishes, the mailbox
is unlocked and the utility ends. The following options are available:
</p>
<dl compact="compact">
<dt> <code>-fcntl</code></dt>
<dd><p>Use <code>fcntl()</code> locking on the open mailbox.
</p>
</dd>
<dt> <code>-flock</code></dt>
<dd><p>Use <code>flock()</code> locking on the open mailbox, provided the operating system
supports it.
</p>
</dd>
<dt> <code>-interval</code></dt>
<dd><p>This must be followed by a number, which is a number of seconds; it sets the
interval to sleep between retries (default 3).
</p>
</dd>
<dt> <code>-lockfile</code></dt>
<dd><p>Create a lock file before opening the mailbox.
</p>
</dd>
<dt> <code>-mbx</code></dt>
<dd><p>Lock the mailbox using MBX rules.
</p>
</dd>
<dt> <code>-q</code></dt>
<dd><p>Suppress verification output.
</p>
</dd>
<dt> <code>-retries</code></dt>
<dd><p>This must be followed by a number; it sets the number of times to try to get
the lock (default 10).
</p>
</dd>
<dt> <code>-restore_time</code></dt>
<dd><p>This option causes <code>exim_lock</code> to restore the modified and read times to the
locked file before exiting. This allows you to access a locked mailbox (for
example, to take a backup copy) without disturbing the times that the user
subsequently sees.
</p>
</dd>
<dt> <code>-timeout</code></dt>
<dd><p>This must be followed by a number, which is a number of seconds; it sets a
timeout to be used with a blocking <code>fcntl()</code> lock. If it is not set (the
default), a non-blocking call is used.
</p>
</dd>
<dt> <code>-v</code></dt>
<dd><p>Generate verbose output.
</p></dd>
</dl>
<p>If none of <code>-fcntl</code>, <code>-flock</code>, <code>-lockfile</code> or <code>-mbx</code> are given, the
default is to create a lock file and also to use <code>fcntl()</code> locking on the
mailbox, which is the same as Exim's default. The use of <code>-flock</code> or
<code>-fcntl</code> requires that the file be writeable; the use of <code>-lockfile</code>
requires that the directory containing the file be writeable. Locking by lock
file does not last for ever; Exim assumes that a lock file is expired if it is
more than 30 minutes old.
</p>
<p>The <code>-mbx</code> option can be used with either or both of <code>-fcntl</code> or
<code>-flock</code>. It assumes <code>-fcntl</code> by default. MBX locking causes a shared lock
to be taken out on the open mailbox, and an exclusive lock on the file
‘<tt>/tmp/.n.m</tt>’ where <em>n</em> and <em>m</em> are the device number and inode
number of the mailbox file. When the locking is released, if an exclusive lock
can be obtained for the mailbox, the file in ‘<tt>/tmp</tt>’ is deleted.
</p>
<p>The default output contains verification of the locking that takes place. The
<code>-v</code> option causes some additional information to be given. The <code>-q</code> option
suppresses all output except error messages.
</p>
<p>A command such as
</p>
<table><tr><td> </td><td><pre class="example">exim_lock /var/spool/mail/spqr
</pre></td></tr></table>
<p>runs an interactive shell while the file is locked, whereas
</p>
<table><tr><td> </td><td><pre class="display">exim_lock -q /var/spool/mail/spqr <<End
<some commands>
End
</pre></td></tr></table>
<p>runs a specific non-interactive sequence of commands while the file is locked,
suppressing all verification output. A single command can be run by a command
such as
</p>
<table><tr><td> </td><td><pre class="example">exim_lock -q /var/spool/mail/spqr \
"cp /var/spool/mail/spqr /some/where"
</pre></td></tr></table>
<p>Note that if a command is supplied, it must be entirely contained within the
second argument - hence the quotes.
<a name="IDX2832"></a>
</p>
<hr size="6">
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#SEC452" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="spec_51.html#SEC468" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="spec.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[Contents]</td>
<td valign="middle" align="left">[<a href="spec_55.html#SEC493" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="spec_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<p>
<font size="-1">
This document was generated on <i>September, 10 2009</i> using <a href="http://www.nongnu.org/texi2html/"><i>texi2html 1.78</i></a>.
</font>
<br>
</p>
</body>
</html>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
a4080654d049ad31b216b761b9173c1f
>
files
>
155
