<!DOCTYPE html PUBLIC "XSLT-compat"> <html lang="en-GB"> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> <link rel="stylesheet" type="text/css" href="../../../../common.css"> <meta name="author" content="The Exim Project. <http://www.exim.org/>"> <meta name="copyright" content="Copyright ©2010 The Exim Project. All rights reserved"> <meta name="description" content="Exim is a message transfer agent (MTA) developed at the University of Cambridge for use on Unix systems connected to the Internet."> <meta name="keywords" content="exim,smtp,mta,email"> <meta name="robots" content="noodp,noydir,index,follow"> <meta name="viewport" content="width=device-width"> <title>50. Exim utilities</title> <link rel="stylesheet" type="text/css" href="../../../../doc/chapter.css"> <link rel="canonical" href="http://www.exim.org/exim-html-current/doc/html/spec_html/ch50.html"> </head> <body> <h1 id="header"><a href="../../../..">Exim Internet Mailer</a></h1> <div id="outer"> <ul id="nav_flow" class="nav"> <li><a href="../../../../index.html">Home</a></li> <li><a href="../../../../mirrors.html">Download</a></li> <li><a href="../../../../docs.html">Documentation</a></li> <li><a href="../../../../maillist.html">Mailing Lists</a></li> <li><a href="http://wiki.exim.org/">Wiki</a></li> <li><a href="http://www.exim.org/bugzilla/">Bugs</a></li> <li><a href="../../../../credits.html">Credits</a></li> <li class="search"><form action="http://www.google.com/search" method="get"> <span class="search_field_container"><input type="search" name="q" placeholder="Search Docs" class="search_field"></span><input type="hidden" name="hl" value="en"><input type="hidden" name="ie" value="UTF-8"><input type="hidden" name="as_qdr" value="all"><input type="hidden" name="q" value="site:www.exim.org"><input type="hidden" name="q" value="inurl:exim-html-current"> </form></li> </ul> <div id="inner"><div id="content"> <a class="previous_page" href="ch49.html"><-previous</a><a class="next_page" href="ch51.html">next-></a><div id="chapter" class="chapter"> <h2 id="CHAPutils" class="">Chapter 50 - Exim utilities</h2> <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> <a href="ch50.html#SECTfinoutwha" title="50. Exim utilities">50.1</a> </td> <td><span class="docbook_emphasis">exiwhat</span></td> <td>list what Exim processes are doing</td> </tr> <tr> <td> <a href="ch50.html#SECTgreptheque" title="50. Exim utilities">50.2</a> </td> <td><span class="docbook_emphasis">exiqgrep</span></td> <td>grep the queue</td> </tr> <tr> <td> <a href="ch50.html#SECTsumtheque" title="50. Exim utilities">50.3</a> </td> <td><span class="docbook_emphasis">exiqsumm</span></td> <td>summarize the queue</td> </tr> <tr> <td> <a href="ch50.html#SECTextspeinf" title="50. Exim utilities">50.4</a> </td> <td><span class="docbook_emphasis">exigrep</span></td> <td>search the main log</td> </tr> <tr> <td> <a href="ch50.html#SECTexipick" title="50. Exim utilities">50.5</a> </td> <td><span class="docbook_emphasis">exipick</span></td> <td>select messages on various criteria</td> </tr> <tr> <td> <a href="ch50.html#SECTcyclogfil" title="50. Exim utilities">50.6</a> </td> <td><span class="docbook_emphasis">exicyclog</span></td> <td>cycle (rotate) log files</td> </tr> <tr> <td> <a href="ch50.html#SECTmailstat" title="50. Exim utilities">50.7</a> </td> <td><span class="docbook_emphasis">eximstats</span></td> <td>extract statistics from the log</td> </tr> <tr> <td> <a href="ch50.html#SECTcheckaccess" title="50. Exim utilities">50.8</a> </td> <td><span class="docbook_emphasis">exim_checkaccess</span></td> <td>check address acceptance from given IP</td> </tr> <tr> <td> <a href="ch50.html#SECTdbmbuild" title="50. Exim utilities">50.9</a> </td> <td><span class="docbook_emphasis">exim_dbmbuild</span></td> <td>build a DBM file</td> </tr> <tr> <td> <a href="ch50.html#SECTfinindret" title="50. Exim utilities">50.10</a> </td> <td><span class="docbook_emphasis">exinext</span></td> <td>extract retry information</td> </tr> <tr> <td> <a href="ch50.html#SECThindatmai" title="50. Exim utilities">50.11</a> </td> <td><span class="docbook_emphasis">exim_dumpdb</span></td> <td>dump a hints database</td> </tr> <tr> <td> <a href="ch50.html#SECThindatmai" title="50. Exim utilities">50.11</a> </td> <td><span class="docbook_emphasis">exim_tidydb</span></td> <td>clean up a hints database</td> </tr> <tr> <td> <a href="ch50.html#SECThindatmai" title="50. Exim utilities">50.11</a> </td> <td><span class="docbook_emphasis">exim_fixdb</span></td> <td>patch a hints database</td> </tr> <tr> <td> <a href="ch50.html#SECTmailboxmaint" title="50. Exim utilities">50.15</a> </td> <td><span class="docbook_emphasis">exim_lock</span></td> <td>lock a mailbox file</td> </tr> </table> <p> Another utility that might be of use to sites with many MTAs is Tom Kistner’s <span class="docbook_emphasis">exilog</span>. It provides log visualizations across multiple Exim servers. See <span class="docbook_emphasis"><a href="http://duncanthrax.net/exilog/">http://duncanthrax.net/exilog/</a></span> for details. </p> <div class="section"> <h3 id="SECTfinoutwha" class="">1. Finding out what Exim processes are doing (exiwhat)</h3> <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 <span class="docbook_filename">exim-process.info</span> in the Exim spool directory. The <span class="docbook_emphasis">exiwhat</span> 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 <span class="docbook_emphasis">exiwhat</span> successfully you have to have sufficient privilege to send the signal to the Exim processes, so it is normally run as root. </p> <p> <span class="docbook_emphasis">Warning</span>: 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 <span class="docbook_emphasis">ps</span> command that <span class="docbook_emphasis">exiwhat</span> 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 <span class="docbook_emphasis">exiwhat</span> works. If it doesn’t seem to be working for you, check the following compile-time options: </p> <div class="docbook_literallayout"><pre> <code class="docbook_literal">EXIWHAT_PS_CMD </code> the command for running <span class="docbook_emphasis">ps</span> <code class="docbook_literal">EXIWHAT_PS_ARG </code> the argument for <span class="docbook_emphasis">ps</span> <code class="docbook_literal">EXIWHAT_EGREP_ARG </code> the argument for <span class="docbook_emphasis">egrep</span> to select from <span class="docbook_emphasis">ps</span> output <code class="docbook_literal">EXIWHAT_KILL_ARG </code> the argument for the <span class="docbook_emphasis">kill</span> command </pre></div> <p> An example of typical output from <span class="docbook_emphasis">exiwhat</span> is </p> <div class="docbook_literallayout"><pre> 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></div> <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> </div> <div class="section"> <h3 id="SECTgreptheque" class="">2. Selective queue listing (exiqgrep)</h3> <p> This utility is a Perl script contributed by Matt Hubbard. It runs </p> <div class="docbook_literallayout"><pre> exim -bpu </pre></div> <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> <dt> <span class="docbook_emphasis">-f</span> <<span class="docbook_emphasis">regex</span>></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> <div class="docbook_literallayout"><pre> exiqgrep -f '^<>$' </pre></div> </dd> <dt> <span class="docbook_emphasis">-r</span> <<span class="docbook_emphasis">regex</span>></dt> <dd> <p> Match a recipient address. The field that is tested is not enclosed in angle brackets. </p> </dd> <dt> <span class="docbook_emphasis">-s</span> <<span class="docbook_emphasis">regex</span>></dt> <dd> <p> Match against the size field. </p> </dd> <dt> <span class="docbook_emphasis">-y</span> <<span class="docbook_emphasis">seconds</span>></dt> <dd> <p> Match messages that are younger than the given time. </p> </dd> <dt> <span class="docbook_emphasis">-o</span> <<span class="docbook_emphasis">seconds</span>></dt> <dd> <p> Match messages that are older than the given time. </p> </dd> <dt><span class="docbook_emphasis">-z</span></dt> <dd> <p> Match only frozen messages. </p> </dd> <dt><span class="docbook_emphasis">-x</span></dt> <dd> <p> Match only non-frozen messages. </p> </dd> </dl> <p> The following options control the format of the output: </p> <dl> <dt><span class="docbook_emphasis">-c</span></dt> <dd> <p> Display only the count of matching messages. </p> </dd> <dt><span class="docbook_emphasis">-l</span></dt> <dd> <p> Long format – display the full message information as output by Exim. This is the default. </p> </dd> <dt><span class="docbook_emphasis">-i</span></dt> <dd> <p> Display message ids only. </p> </dd> <dt><span class="docbook_emphasis">-b</span></dt> <dd> <p> Brief format – one line per message. </p> </dd> <dt><span class="docbook_emphasis">-R</span></dt> <dd> <p> Display messages in reverse order. </p> </dd> </dl> <p> There is one more option, <span class="docbook_option">-h</span>, which outputs a list of options. </p> </div> <div class="section"> <h3 id="SECTsumtheque" class="">3. Summarizing the queue (exiqsumm)</h3> <p> The <span class="docbook_emphasis">exiqsumm</span> utility is a Perl script which reads the output of <code class="docbook_literal">exim -bp</code> and produces a summary of the messages on the queue. Thus, you use it by running a command such as </p> <div class="docbook_literallayout"><pre> exim -bp | exiqsumm </pre></div> <p> The output consists of one line for each domain that has messages waiting for it, as in the following example: </p> <div class="docbook_literallayout"><pre> 3 2322 74m 66m msn.com.example </pre></div> <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 <span class="docbook_emphasis">exiqsumm</span> has the options <span class="docbook_option">-a</span> and <span class="docbook_option">-c</span>, 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: <span class="docbook_option">-b</span> separates bounce messages, <span class="docbook_option">-f</span> separates frozen messages, and <span class="docbook_option">-s</span> separates messages according to their sender. </p> <p> The output of <span class="docbook_emphasis">exim -bp</span> contains the original addresses in the message, so this also applies to the output from <span class="docbook_emphasis">exiqsumm</span>. No domains from addresses generated by aliasing or forwarding are included (unless the <span class="docbook_option">one_time</span> option of the <span class="docbook_command">redirect</span> router has been used to convert them into “top level” addresses). </p> </div> <div class="section"> <h3 id="SECTextspeinf" class="">4. Extracting specific information from the log (exigrep)</h3> <p> The <span class="docbook_emphasis">exigrep</span> 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, <span class="docbook_emphasis">exigrep</span> 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 <span class="docbook_emphasis">exigrep</span>’s output without any additional lines. The usage is: </p> <div class="docbook_literallayout"><pre> <code class="docbook_literal">exigrep [-t<</code><span class="docbook_emphasis">n</span><code class="docbook_literal">>] [-I] [-l] [-v] <</code><span class="docbook_emphasis">pattern</span><code class="docbook_literal">> [<</code><span class="docbook_emphasis">log file</span><code class="docbook_literal">>] ...</code> </pre></div> <p> If no log file names are given on the command line, the standard input is read. </p> <p> The <span class="docbook_option">-t</span> 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 <<span class="docbook_emphasis">n</span>> seconds on the queue. </p> <p> By default, <span class="docbook_emphasis">exigrep</span> does case-insensitive matching. The <span class="docbook_option">-I</span> option makes it case-sensitive. This may give a performance improvement when searching large log files. Without <span class="docbook_option">-I</span>, the Perl pattern matches use Perl’s <code class="docbook_literal">/i</code> option; with <span class="docbook_option">-I</span> they do not. In both cases it is possible to change the case sensitivity within the pattern by using <code class="docbook_literal">(?i)</code> or <code class="docbook_literal">(?-i)</code>. </p> <p> The <span class="docbook_option">-l</span> 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 <span class="docbook_option">-v</span> option inverts the matching condition. That is, a line is selected if it does <span class="docbook_emphasis">not</span> match the pattern. </p> <p> If the location of a <span class="docbook_emphasis">zcat</span> command is known from the definition of ZCAT_COMMAND in <span class="docbook_filename">Local/Makefile</span>, <span class="docbook_emphasis">exigrep</span> automatically passes any file whose name ends in COMPRESS_SUFFIX through <span class="docbook_emphasis">zcat</span> as it searches it. </p> </div> <div class="section"> <h3 id="SECTexipick" class="">5. Selecting messages by various criteria (exipick)</h3> <p> John Jetmore’s <span class="docbook_emphasis">exipick</span> utility is included in the Exim distribution. It lists messages from the queue according to a variety of criteria. For details of <span class="docbook_emphasis">exipick</span>’s facilities, visit the web page at <span class="docbook_emphasis"><a href="http://www.exim.org/eximwiki/ToolExipickManPage">http://www.exim.org/eximwiki/ToolExipickManPage</a></span> or run <span class="docbook_emphasis">exipick</span> with the <span class="docbook_option">--help</span> option. </p> </div> <div class="section"> <h3 id="SECTcyclogfil" class="">6. Cycling log files (exicyclog)</h3> <p> The <span class="docbook_emphasis">exicyclog</span> script can be used to cycle (rotate) <span class="docbook_emphasis">mainlog</span> and <span class="docbook_emphasis">rejectlog</span> 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="ch49.html#SECTdatlogfil" title="49. Log files">49.3</a>). Some operating systems have their own standard mechanisms for log cycling, and these can be used instead of <span class="docbook_emphasis">exicyclog</span> if preferred. There are two command line options for <span class="docbook_emphasis">exicyclog</span>: </p> <ul> <li> <p> <span class="docbook_option">-k</span> <<span class="docbook_emphasis">count</span>> specifies the number of log files to keep, overriding the default that is set when Exim is built. The default default is 10. </p> </li> <li> <p> <span class="docbook_option">-l</span> <<span class="docbook_emphasis">path</span>> specifies the log file path, in the same format as Exim’s <span class="docbook_option">log_file_path</span> option (for example, <code class="docbook_literal">/var/log/exim_%slog</code>), again overriding the script’s default, which is to find the setting from Exim’s configuration. </p> </li> </ul> <p> Each time <span class="docbook_emphasis">exicyclog</span> is run the file names get “shuffled down” by one. If the main log file name is <span class="docbook_filename">mainlog</span> (the default) then when <span class="docbook_emphasis">exicyclog</span> is run <span class="docbook_filename">mainlog</span> becomes <span class="docbook_filename">mainlog.01</span>, the previous <span class="docbook_filename">mainlog.01</span> becomes <span class="docbook_filename">mainlog.02</span> and so on, up to the limit that is set in the script or by the <span class="docbook_option">-k</span> 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 <span class="docbook_filename">mainlog.001</span>, <span class="docbook_filename">mainlog.002</span>, etc. If you change from a number less than 99 to one that is greater, or <span class="docbook_emphasis">vice versa</span>, you will have to fix the names of any existing log files. </p> <p> If no <span class="docbook_filename">mainlog</span> 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 <span class="docbook_filename">Local/Makefile</span>. It is usual to run <span class="docbook_emphasis">exicyclog</span> daily from a root <span class="docbook_option">crontab</span> entry of the form </p> <div class="docbook_literallayout"><pre> 1 0 * * * su exim -c /usr/exim/bin/exicyclog </pre></div> <p> assuming you have used the name “exim” for the Exim user. You can run <span class="docbook_emphasis">exicyclog</span> as root if you wish, but there is no need. </p> </div> <div class="section"> <h3 id="SECTmailstat" class="">7. Mail statistics (eximstats)</h3> <p> A Perl script called <span class="docbook_emphasis">eximstats</span> 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 <span class="docbook_emphasis">Lire</span> system produced by the LogReport Foundation <span class="docbook_emphasis"><a href="http://www.logreport.org">http://www.logreport.org</a></span>. </p> <p> The <span class="docbook_emphasis">eximstats</span> 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> <div class="docbook_literallayout"><pre> eximstats -nr /var/spool/exim/log/mainlog.01 </pre></div> <p> By default, <span class="docbook_emphasis">eximstats</span> 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 <span class="docbook_emphasis">eximstats</span>. </p> <p> Though normally more deliveries than receipts are reported (as messages may have multiple recipients), it is possible for <span class="docbook_emphasis">eximstats</span> 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> <span class="docbook_emphasis">eximstats</span> 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 <span class="docbook_emphasis">eximstats</span> to control exactly what it outputs. These are documented in the Perl script itself, and can be extracted by running the command <span class="docbook_command">perldoc</span> on the script. For example: </p> <div class="docbook_literallayout"><pre> perldoc /usr/exim/bin/eximstats </pre></div> </div> <div class="section"> <h3 id="SECTcheckaccess" class="">8. Checking access policy (exim_checkaccess)</h3> <p> The <span class="docbook_option">-bh</span> 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 <span class="docbook_option">-bh</span>, and sometimes you just want to answer the question “Does this address have access?” without bothering with any further details. </p> <p> The <span class="docbook_emphasis">exim_checkaccess</span> utility is a “packaged” version of <span class="docbook_option">-bh</span>. It takes two arguments, an IP address and an email address: </p> <div class="docbook_literallayout"><pre> exim_checkaccess 10.9.8.7 A.User@a.domain.example </pre></div> <p> The utility runs a call to Exim with the <span class="docbook_option">-bh</span> 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> <div class="docbook_literallayout"><pre> Rejected: 550 Relay not permitted </pre></div> <p> When running this test, the utility uses <code class="docbook_literal"><></code> 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 <span class="docbook_emphasis">himself@there.example</span> you can use: </p> <div class="docbook_literallayout"><pre> exim_checkaccess 10.9.8.7 A.User@a.domain.example \ -f himself@there.example </pre></div> <p> Note that these additional Exim command line items must be given after the two mandatory arguments. </p> <p> Because the <span class="docbook_option">exim_checkaccess</span> uses <span class="docbook_option">-bh</span>, it does not perform callouts while running its checks. You can run checks that include callouts by using <span class="docbook_option">-bhc</span>, but this is not yet available in a “packaged” form. </p> </div> <div class="section"> <h3 id="SECTdbmbuild" class="">9. Making DBM files (exim_dbmbuild)</h3> <p> The <span class="docbook_emphasis">exim_dbmbuild</span> program reads an input file containing keys and data in the format used by the <span class="docbook_command">lsearch</span> lookup (see section <a href="ch09.html#SECTsinglekeylookups" title="9. File and database lookups">9.3</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 <span class="docbook_option">-nolc</span> option. </p> <p> A terminating zero is included as part of the key string. This is expected by the <span class="docbook_command">dbm</span> lookup type. However, if the option <span class="docbook_option">-nozero</span> is given, <span class="docbook_emphasis">exim_dbmbuild</span> creates files without terminating zeroes in either the key strings or the data strings. The <span class="docbook_command">dbmnz</span> 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> <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> <div class="docbook_literallayout"><pre> exim_dbmbuild /etc/aliases /etc/aliases.db </pre></div> <p> reads the system alias file and creates a DBM version of it in <span class="docbook_filename">/etc/aliases.db</span>. </p> <p> In systems that use the <span class="docbook_emphasis">ndbm</span> routines (mostly proprietary versions of Unix), two files are used, with the suffixes <span class="docbook_filename">.dir</span> and <span class="docbook_filename">.pag</span>. In this environment, the suffixes are added to the second argument of <span class="docbook_emphasis">exim_dbmbuild</span>, 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 <span class="docbook_filename">.db</span> 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 <span class="docbook_option">-noduperr</span> option is used. By default, only the first of a set of duplicates is used – this makes it compatible with <span class="docbook_command">lsearch</span> lookups. There is an option <span class="docbook_option">-lastdup</span> which causes it to use the data for the last duplicate instead. There is also an option <span class="docbook_option">-nowarn</span>, which stops it listing duplicate keys to <span class="docbook_option">stderr</span>. For other errors, where it doesn’t actually make a new file, the return code is 2. </p> </div> <div class="section"> <h3 id="SECTfinindret" class="">10. Finding individual retry times (exinext)</h3> <p> A utility called <span class="docbook_emphasis">exinext</span> (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 <span class="docbook_emphasis">exim_dumpdb</span> (see below) and post-processing the output. For example: </p> <div class="docbook_literallayout"><pre> $ 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></div> <p> You can also give <span class="docbook_emphasis">exinext</span> 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="ch45.html#SECToutSMTPerr" title="45. SMTP processing">45.2</a>). <span class="docbook_emphasis">exinext</span> is not particularly efficient, but then it is not expected to be run very often. </p> <p> The <span class="docbook_emphasis">exinext</span> utility calls Exim to find out information such as the location of the spool directory. The utility has <span class="docbook_option">-C</span> and <span class="docbook_option">-D</span> options, which are passed on to the <span class="docbook_emphasis">exim</span> 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> </div> <div class="section"> <h3 id="SECThindatmai" class="">11. Hints database maintenance</h3> <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> <li> <p> <span class="docbook_emphasis">retry</span>: the database of retry information </p> </li> <li> <p> <span class="docbook_emphasis">wait-</span><<span class="docbook_emphasis">transport name</span>>: databases of information about messages waiting for remote hosts </p> </li> <li> <p> <span class="docbook_emphasis">callout</span>: the callout cache </p> </li> <li> <p> <span class="docbook_emphasis">ratelimit</span>: the data for implementing the ratelimit ACL condition </p> </li> <li> <p> <span class="docbook_emphasis">misc</span>: other hints data </p> </li> </ul> <p> The <span class="docbook_emphasis">misc</span> database is used for </p> <ul> <li> <p> Serializing ETRN runs (when <span class="docbook_option">smtp_etrn_serialize</span> is set) </p> </li> <li> <p> Serializing delivery to a specific host (when <span class="docbook_option">serialize_hosts</span> is set in an <span class="docbook_command">smtp</span> transport) </p> </li> </ul> </div> <div class="section"> <h3 id="SECID261" class="">12. exim_dumpdb</h3> <p> The entire contents of a database are written to the standard output by the <span class="docbook_emphasis">exim_dumpdb</span> program, which has no options or arguments other than the spool and database names. For example, to dump the retry database: </p> <div class="docbook_literallayout"><pre> exim_dumpdb /var/spool/exim retry </pre></div> <p> Two lines of output are produced for each entry: </p> <div class="docbook_literallayout"><pre> 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></div> <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 <span class="docbook_option">retry_include_ip_address</span> is set false on the <span class="docbook_command">smtp</span> 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 <span class="docbook_emphasis">exim_dumpdb</span> for the <span class="docbook_emphasis">wait-xxx</span> 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> </div> <div class="section"> <h3 id="SECID262" class="">13. exim_tidydb</h3> <p> The <span class="docbook_emphasis">exim_tidydb</span> 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 <span class="docbook_emphasis">not</span> 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 <span class="docbook_option">-t</span> option, which must be followed by a time. For example, to remove all records older than a week from the retry database: </p> <div class="docbook_literallayout"><pre> exim_tidydb -t 7d /var/spool/exim retry </pre></div> <p> Both the <span class="docbook_emphasis">wait-xxx</span> and <span class="docbook_emphasis">retry</span> 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 <span class="docbook_emphasis">exim_tidydb</span> 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 <span class="docbook_emphasis">wait-xxx</span> records, and if this leaves any records empty, they are deleted. For the <span class="docbook_emphasis">retry</span> database, records whose keys are non-existent message ids are removed. The <span class="docbook_emphasis">exim_tidydb</span> 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 <span class="docbook_emphasis">exim_tidydb</span> 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> <span class="docbook_emphasis">Warning</span>: If you never run <span class="docbook_emphasis">exim_tidydb</span>, the space used by the hints databases is likely to keep on increasing. </p> </div> <div class="section"> <h3 id="SECID263" class="">14. exim_fixdb</h3> <p> The <span class="docbook_emphasis">exim_fixdb</span> 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 <span class="docbook_emphasis">retry</span> database, that is the only operation that can be carried out. For the <span class="docbook_emphasis">retry</span> 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> <div class="docbook_literallayout"><pre> > 4 951102:1000 </pre></div> <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> </div> <div class="section"> <h3 id="SECTmailboxmaint" class="">15. Mailbox maintenance (exim_lock)</h3> <p> The <span class="docbook_emphasis">exim_lock</span> utility locks a mailbox file using the same algorithm as Exim. For a discussion of locking issues, see section <a href="ch26.html#SECTopappend" title="26. The appendfile transport">26.3</a>. <span class="docbook_emphasis">Exim_lock</span> 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 <span class="docbook_function">system()</span> function); if there is no second argument, the value of the SHELL environment variable is used; if this is unset or empty, <span class="docbook_filename">/bin/sh</span> is run. When the command finishes, the mailbox is unlocked and the utility ends. The following options are available: </p> <dl> <dt><span class="docbook_option">-fcntl</span></dt> <dd> <p> Use <span class="docbook_function">fcntl()</span> locking on the open mailbox. </p> </dd> <dt><span class="docbook_option">-flock</span></dt> <dd> <p> Use <span class="docbook_function">flock()</span> locking on the open mailbox, provided the operating system supports it. </p> </dd> <dt><span class="docbook_option">-interval</span></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><span class="docbook_option">-lockfile</span></dt> <dd> <p> Create a lock file before opening the mailbox. </p> </dd> <dt><span class="docbook_option">-mbx</span></dt> <dd> <p> Lock the mailbox using MBX rules. </p> </dd> <dt><span class="docbook_option">-q</span></dt> <dd> <p> Suppress verification output. </p> </dd> <dt><span class="docbook_option">-retries</span></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><span class="docbook_option">-restore_time</span></dt> <dd> <p> This option causes <span class="docbook_option">exim_lock</span> 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><span class="docbook_option">-timeout</span></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 <span class="docbook_function">fcntl()</span> lock. If it is not set (the default), a non-blocking call is used. </p> </dd> <dt><span class="docbook_option">-v</span></dt> <dd> <p> Generate verbose output. </p> </dd> </dl> <p> If none of <span class="docbook_option">-fcntl</span>, <span class="docbook_option">-flock</span>, <span class="docbook_option">-lockfile</span> or <span class="docbook_option">-mbx</span> are given, the default is to create a lock file and also to use <span class="docbook_function">fcntl()</span> locking on the mailbox, which is the same as Exim’s default. The use of <span class="docbook_option">-flock</span> or <span class="docbook_option">-fcntl</span> requires that the file be writeable; the use of <span class="docbook_option">-lockfile</span> 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 <span class="docbook_option">-mbx</span> option can be used with either or both of <span class="docbook_option">-fcntl</span> or <span class="docbook_option">-flock</span>. It assumes <span class="docbook_option">-fcntl</span> by default. MBX locking causes a shared lock to be taken out on the open mailbox, and an exclusive lock on the file <span class="docbook_filename">/tmp/.n.m</span> where <span class="docbook_emphasis">n</span> and <span class="docbook_emphasis">m</span> 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 <span class="docbook_filename">/tmp</span> is deleted. </p> <p> The default output contains verification of the locking that takes place. The <span class="docbook_option">-v</span> option causes some additional information to be given. The <span class="docbook_option">-q</span> option suppresses all output except error messages. </p> <p> A command such as </p> <div class="docbook_literallayout"><pre> exim_lock /var/spool/mail/spqr </pre></div> <p> runs an interactive shell while the file is locked, whereas </p> <div class="docbook_literallayout"><pre> <code class="docbook_literal">exim_lock -q /var/spool/mail/spqr <<End</code> <<span class="docbook_emphasis">some commands</span>> <code class="docbook_literal">End</code> </pre></div> <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> <div class="docbook_literallayout"><pre> exim_lock -q /var/spool/mail/spqr \ "cp /var/spool/mail/spqr /some/where" </pre></div> <p> Note that if a command is supplied, it must be entirely contained within the second argument – hence the quotes. </p> </div> </div> <a class="previous_page" href="ch49.html"><-previous</a><a class="next_page" href="ch51.html">next-></a> </div></div> <iframe id="branding" name="branding" src="../../../../branding/branding.html" height="0" frameborder="no" scrolling="no"></iframe><div id="footer">Website design by <a href="https://secure.grepular.com/">Mike Cardwell</a>, of <a href="http://cardwellit.com/">Cardwell IT Ltd.</a> </div> <div class="left_bar"></div> <div class="right_bar"></div> <div id="toc"> <ul class="hidden"></ul> <img src="../../../../doc/contents.png" width="16" height="155"> </div> </div> <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.4/jquery.min.js"></script><script type="text/javascript" src="../../../../common.js"></script><script type="text/javascript" src="../../../../doc/chapter.js"></script> </body> </html>