<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><style xmlns="" type="text/css">
div.added { background-color: #ffff99; }
div.deleted { text-decoration: line-through;
background-color: #FF7F7F; }
div.changed { background-color: #99ff99; }
div.off { }
span.added { background-color: #ffff99; }
span.deleted { text-decoration: line-through;
background-color: #FF7F7F; }
span.changed { background-color: #99ff99; }
span.off { }
pre.literallayout {
background-color: #E8E8D0;
padding-left: 0.5cm;
padding-top: 5px;
padding-bottom: 5px;
}
div[class=changed] pre.literallayout {
background-color: #99ff99;
padding-left: 0.5cm;
padding-top: 5px;
padding-bottom: 5px;
}
div.literallayout {
background-color: #E8E8D0;
padding-left: 0.5cm;
padding-top: 5px;
padding-bottom: 5px;
}
div[class=changed] div.literallayout {
background-color: #99ff99;
padding-left: 0.5cm;
padding-top: 5px;
padding-bottom: 5px;
}
</style><title>53. Format of spool files</title><meta name="generator" content="DocBook XSL Stylesheets V1.72.0" /><link rel="start" href="index.html" title="Specification of the Exim Mail Transfer Agent" /><link rel="up" href="index.html" title="Specification of the Exim Mail Transfer Agent" /><link rel="prev" href="ch52.html" title="52. Security considerations" /><link rel="next" href="ch54.html" title="54. Adding new drivers or lookup types" /></head><body><div class="navheader">
<table width="100%" summary="Navigation header"><tr><td width="20%" align="left"><a accesskey="p" href="ch52.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="ch54.html">Next</a></td></tr></table></div>
<div class="chapter" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h2 class="title"><a href="index.html#toc0490" id="CHAPspool">53. Format of spool files</a></h2></div>
</div>
</div>
<p>
<a id="IIDforspo1" class="indexterm"></a>
<a id="IIDforspo2" class="indexterm"></a>
<a id="IIDforspo3" class="indexterm"></a>
<a id="id658907" class="indexterm"></a>
A message on Exim’s queue consists of two files, whose names are the message id
followed by -D and -H, respectively. The data portion of the message is kept in
the -D file on its own. The message’s envelope, status, and headers are all
kept in the -H file, whose format is described in this chapter. Each of these
two files contains the final component of its own name as its first line. This
is insurance against disk crashes where the directory is lost but the files
themselves are recoverable.
</p>
<p>
Some people are tempted into editing -D files in order to modify messages. You
need to be extremely careful if you do this; it is not recommended and you are
on your own if you do it. Here are some of the pitfalls:
</p>
<div class="itemizedlist">
<ul type="disc"><li><p>
You must ensure that Exim does not try to deliver the message while you are
fiddling with it. The safest way is to take out a write lock on the -D file,
which is what Exim itself does, using <em class="function">fcntl()</em>. If you update the file in
place, the lock will be retained. If you write a new file and rename it, the
lock will be lost at the instant of rename.
</p>
</li><li><p>
<a id="id658955" class="indexterm"></a>
If you change the number of lines in the file, the value of
<em class="varname">$body_linecount</em>, which is stored in the -H file, will be incorrect. At
present, this value is not used by Exim, but there is no guarantee that this
will always be the case.
</p>
</li><li><p>
If the message is in MIME format, you must take care not to break it.
</p>
</li><li><p>
If the message is cryptographically signed, any change will invalidate the
signature.
</p>
</li></ul></div>
<p>
All in all, modifying -D files is fraught with danger.
</p>
<p>
Files whose names end with -J may also be seen in the <em class="filename">input</em> directory (or
its subdirectories when <span><strong class="option">split_spool_directory</strong></span> is set). These are journal
files, used to record addresses to which the message has been delivered during
the course of a delivery attempt. If there are still undelivered recipients at
the end, the -H file is updated, and the -J file is deleted. If, however, there
is some kind of crash (for example, a power outage) before this happens, the -J
file remains in existence. When Exim next processes the message, it notices the
-J file and uses it to update the -H file before starting the next delivery
attempt.
</p>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="index.html#toc0491" id="SECID282">53.1 Format of the -H file</a></h3></div>
</div>
</div>
<p>
<a id="id659023" class="indexterm"></a>
<a id="id659037" class="indexterm"></a>
The second line of the -H file contains the login name for the uid of the
process that called Exim to read the message, followed by the numerical uid and
gid. For a locally generated message, this is normally the user who sent the
message. For a message received over TCP/IP via the daemon, it is
normally the Exim user.
</p>
<p>
The third line of the file contains the address of the message’s sender as
transmitted in the envelope, contained in angle brackets. The sender address is
empty for bounce messages. For incoming SMTP mail, the sender address is given
in the MAIL command. For locally generated mail, the sender address is
created by Exim from the login name of the current user and the configured
<span><strong class="option">qualify_domain</strong></span>. However, this can be overridden by the <span><strong class="option">-f</strong></span> option or a
leading “<span class="quote">From </span>” line if the caller is trusted, or if the supplied address is
“<span class="quote"><></span>” or an address that matches <span><strong class="option">untrusted_set_senders</strong></span>.
</p>
<p>
The fourth line contains two numbers. The first is the time that the message
was received, in the conventional Unix form – the number of seconds since the
start of the epoch. The second number is a count of the number of messages
warning of delayed delivery that have been sent to the sender.
</p>
<p>
There follow a number of lines starting with a hyphen. These can appear in any
order, and are omitted when not relevant:
</p>
<div class="variablelist">
<dl><dt><span class="term"><span><strong class="option">-acl</strong></span> <<span class="emphasis"><em>number</em></span>> <<span class="emphasis"><em>length</em></span>></span></dt><dd><p>
This item is obsolete, and is not generated from Exim release 4.61 onwards;
<span><strong class="option">-aclc</strong></span> and <span><strong class="option">-aclm</strong></span> are used instead. However, <span><strong class="option">-acl</strong></span> is still
recognized, to provide backward compatibility. In the old format, a line of
this form is present for every ACL variable that is not empty. The number
identifies the variable; the <span><strong class="option">acl_c</strong></span><span class="bold"><strong>x</strong></span> variables are numbered 0–9 and
the <span><strong class="option">acl_m</strong></span><span class="bold"><strong>x</strong></span> variables are numbered 10–19. The length is the length of
the data string for the variable. The string itself starts at the beginning of
the next line, and is followed by a newline character. It may contain internal
newlines.
</p>
</dd><dt><span class="term"><span><strong class="option">-aclc</strong></span> <<span class="emphasis"><em>rest-of-name</em></span>> <<span class="emphasis"><em>length</em></span>></span></dt><dd><p>
A line of this form is present for every ACL connection variable that is
defined. Note that there is a space between <span><strong class="option">-aclc</strong></span> and the rest of the name.
The length is the length of the data string for the variable. The string itself
starts at the beginning of the next line, and is followed by a newline
character. It may contain internal newlines.
</p>
</dd><dt><span class="term"><span><strong class="option">-aclm</strong></span> <<span class="emphasis"><em>rest-of-name</em></span>> <<span class="emphasis"><em>length</em></span>></span></dt><dd><p>
A line of this form is present for every ACL message variable that is defined.
Note that there is a space between <span><strong class="option">-aclm</strong></span> and the rest of the name. The
length is the length of the data string for the variable. The string itself
starts at the beginning of the next line, and is followed by a newline
character. It may contain internal newlines.
</p>
</dd><dt><span class="term"><span><strong class="option">-active_hostname</strong></span> <<span class="emphasis"><em>hostname</em></span>></span></dt><dd><p>
This is present if, when the message was received over SMTP, the value of
<em class="varname">$smtp_active_hostname</em> was different to the value of <em class="varname">$primary_hostname</em>.
</p>
</dd><dt><span class="term"><span><strong class="option">-allow_unqualified_recipient</strong></span></span></dt><dd><p>
This is present if unqualified recipient addresses are permitted in header
lines (to stop such addresses from being qualified if rewriting occurs at
transport time). Local messages that were input using <span><strong class="option">-bnq</strong></span> and remote
messages from hosts that match <span><strong class="option">recipient_unqualified_hosts</strong></span> set this flag.
</p>
</dd><dt><span class="term"><span><strong class="option">-allow_unqualified_sender</strong></span></span></dt><dd><p>
This is present if unqualified sender addresses are permitted in header lines
(to stop such addresses from being qualified if rewriting occurs at transport
time). Local messages that were input using <span><strong class="option">-bnq</strong></span> and remote messages from
hosts that match <span><strong class="option">sender_unqualified_hosts</strong></span> set this flag.
</p>
</dd><dt><span class="term"><span><strong class="option">-auth_id</strong></span> <<span class="emphasis"><em>text</em></span>></span></dt><dd><p>
The id information for a message received on an authenticated SMTP connection
– the value of the <em class="varname">$authenticated_id</em> variable.
</p>
</dd><dt><span class="term"><span><strong class="option">-auth_sender</strong></span> <<span class="emphasis"><em>address</em></span>></span></dt><dd><p>
The address of an authenticated sender – the value of the
<em class="varname">$authenticated_sender</em> variable.
</p>
</dd><dt><span class="term"><span><strong class="option">-body_linecount</strong></span> <<span class="emphasis"><em>number</em></span>></span></dt><dd><p>
This records the number of lines in the body of the message, and is always
present.
</p>
</dd><dt><span class="term"><span><strong class="option">-body_zerocount</strong></span> <<span class="emphasis"><em>number</em></span>></span></dt><dd><p>
This records the number of binary zero bytes in the body of the message, and is
present if the number is greater than zero.
</p>
</dd><dt><span class="term"><span><strong class="option">-deliver_firsttime</strong></span></span></dt><dd><p>
This is written when a new message is first added to the spool. When the spool
file is updated after a deferral, it is omitted.
</p>
</dd><dt><span class="term"><span><strong class="option">-frozen</strong></span> <<span class="emphasis"><em>time</em></span>></span></dt><dd><p>
<a id="id659416" class="indexterm"></a>
The message is frozen, and the freezing happened at <<span class="emphasis"><em>time</em></span>>.
</p>
</dd><dt><span class="term"><span><strong class="option">-helo_name</strong></span> <<span class="emphasis"><em>text</em></span>></span></dt><dd><p>
This records the host name as specified by a remote host in a HELO or EHLO
command.
</p>
</dd><dt><span class="term"><span><strong class="option">-host_address</strong></span> <<span class="emphasis"><em>address</em></span>>.<<span class="emphasis"><em>port</em></span>></span></dt><dd><p>
This records the IP address of the host from which the message was received and
the remote port number that was used. It is omitted for locally generated
messages.
</p>
</dd><dt><span class="term"><span><strong class="option">-host_auth</strong></span> <<span class="emphasis"><em>text</em></span>></span></dt><dd><p>
If the message was received on an authenticated SMTP connection, this records
the name of the authenticator – the value of the
<em class="varname">$sender_host_authenticated</em> variable.
</p>
</dd><dt><span class="term"><span><strong class="option">-host_lookup_failed</strong></span></span></dt><dd><p>
This is present if an attempt to look up the sending host’s name from its IP
address failed. It corresponds to the <em class="varname">$host_lookup_failed</em> variable.
</p>
</dd><dt><span class="term"><span><strong class="option">-host_name</strong></span> <<span class="emphasis"><em>text</em></span>></span></dt><dd><p>
<a id="id659542" class="indexterm"></a>
<a id="id659553" class="indexterm"></a>
This records the name of the remote host from which the message was received,
if the host name was looked up from the IP address when the message was being
received. It is not present if no reverse lookup was done.
</p>
</dd><dt><span class="term"><span><strong class="option">-ident</strong></span> <<span class="emphasis"><em>text</em></span>></span></dt><dd><p>
For locally submitted messages, this records the login of the originating user,
unless it was a trusted user and the <span><strong class="option">-oMt</strong></span> option was used to specify an
ident value. For messages received over TCP/IP, this records the ident string
supplied by the remote host, if any.
</p>
</dd><dt><span class="term"><span><strong class="option">-interface_address</strong></span> <<span class="emphasis"><em>address</em></span>>.<<span class="emphasis"><em>port</em></span>></span></dt><dd><p>
This records the IP address of the local interface and the port number through
which a message was received from a remote host. It is omitted for locally
generated messages.
</p>
</dd><dt><span class="term"><span><strong class="option">-local</strong></span></span></dt><dd><p>
The message is from a local sender.
</p>
</dd><dt><span class="term"><span><strong class="option">-localerror</strong></span></span></dt><dd><p>
The message is a locally-generated bounce message.
</p>
</dd><dt><span class="term"><span><strong class="option">-local_scan</strong></span> <<span class="emphasis"><em>string</em></span>></span></dt><dd><p>
This records the data string that was returned by the <em class="function">local_scan()</em> function
when the message was received – the value of the <em class="varname">$local_scan_data</em>
variable. It is omitted if no data was returned.
</p>
</dd><dt><span class="term"><span><strong class="option">-manual_thaw</strong></span></span></dt><dd><p>
The message was frozen but has been thawed manually, that is, by an explicit
Exim command rather than via the auto-thaw process.
</p>
</dd><dt><span class="term"><span><strong class="option">-N</strong></span></span></dt><dd><p>
A testing delivery process was started using the <span><strong class="option">-N</strong></span> option to suppress any
actual deliveries, but delivery was deferred. At any further delivery attempts,
<span><strong class="option">-N</strong></span> is assumed.
</p>
</dd><dt><span class="term"><span><strong class="option">-received_protocol</strong></span></span></dt><dd><p>
This records the value of the <em class="varname">$received_protocol</em> variable, which contains
the name of the protocol by which the message was received.
</p>
</dd><dt><span class="term"><span><strong class="option">-sender_set_untrusted</strong></span></span></dt><dd><p>
The envelope sender of this message was set by an untrusted local caller (used
to ensure that the caller is displayed in queue listings).
</p>
</dd><dt><span class="term"><span><strong class="option">-spam_score_int</strong></span> <<span class="emphasis"><em>number</em></span>></span></dt><dd><p>
If a message was scanned by SpamAssassin, this is present. It records the value
of <em class="varname">$spam_score_int</em>.
</p>
</dd><dt><span class="term"><span><strong class="option">-tls_certificate_verified</strong></span></span></dt><dd><p>
A TLS certificate was received from the client that sent this message, and the
certificate was verified by the server.
</p>
</dd><dt><span class="term"><span><strong class="option">-tls_cipher</strong></span> <<span class="emphasis"><em>cipher name</em></span>></span></dt><dd><p>
When the message was received over an encrypted connection, this records the
name of the cipher suite that was used.
</p>
</dd><dt><span class="term"><span><strong class="option">-tls_peerdn</strong></span> <<span class="emphasis"><em>peer DN</em></span>></span></dt><dd><p>
When the message was received over an encrypted connection, and a certificate
was received from the client, this records the Distinguished Name from that
certificate.
</p>
</dd></dl></div>
<p>
Following the options there is a list of those addresses to which the message
is not to be delivered. This set of addresses is initialized from the command
line when the <span><strong class="option">-t</strong></span> option is used and <span><strong class="option">extract_addresses_remove_arguments</strong></span>
is set; otherwise it starts out empty. Whenever a successful delivery is made,
the address is added to this set. The addresses are kept internally as a
balanced binary tree, and it is a representation of that tree which is written
to the spool file. If an address is expanded via an alias or forward file, the
original address is added to the tree when deliveries to all its child
addresses are complete.
</p>
<p>
If the tree is empty, there is a single line in the spool file containing just
the text “<span class="quote">XX</span>”. Otherwise, each line consists of two letters, which are either
Y or N, followed by an address. The address is the value for the node of the
tree, and the letters indicate whether the node has a left branch and/or a
right branch attached to it, respectively. If branches exist, they immediately
follow. Here is an example of a three-node tree:
</p>
<pre class="literallayout">YY darcy@austen.fict.example
NN alice@wonderland.fict.example
NN editor@thesaurus.ref.example
</pre><p>
After the non-recipients tree, there is a list of the message’s recipients.
This is a simple list, preceded by a count. It includes all the original
recipients of the message, including those to whom the message has already been
delivered. In the simplest case, the list contains one address per line. For
example:
</p>
<pre class="literallayout">4
editor@thesaurus.ref.example
darcy@austen.fict.example
rdo@foundation
alice@wonderland.fict.example
</pre><p>
However, when a child address has been added to the top-level addresses as a
result of the use of the <span><strong class="option">one_time</strong></span> option on a <span><strong class="command">redirect</strong></span> router, each
line is of the following form:
</p>
<div class="literallayout">
<<span class="emphasis"><em>top-level address</em></span>> <<span class="emphasis"><em>errors_to address</em></span>> <<span class="emphasis"><em>length</em></span>>,<<span class="emphasis"><em>parent number</em></span>>#<<span class="emphasis"><em>flag bits</em></span>><br />
</div>
<p>
The 01 flag bit indicates the presence of the three other fields that follow
the top-level address. Other bits may be used in future to support additional
fields. The <<span class="emphasis"><em>parent number</em></span>> is the offset in the recipients list of the
original parent of the “<span class="quote">one time</span>” address. The first two fields are the
envelope sender that is associated with this address and its length. If the
length is zero, there is no special envelope sender (there are then two space
characters in the line). A non-empty field can arise from a <span><strong class="command">redirect</strong></span> router
that has an <span><strong class="option">errors_to</strong></span> setting.
</p>
<p>
A blank line separates the envelope and status information from the headers
which follow. A header may occupy several lines of the file, and to save effort
when reading it in, each header is preceded by a number and an identifying
character. The number is the number of characters in the header, including any
embedded newlines and the terminating newline. The character is one of the
following:
</p>
<div class="informaltable">
<table border="0"><colgroup><col align="left" /><col align="left" /></colgroup><tbody><tr><td align="left"><<span class="emphasis"><em>blank</em></span>></td><td align="left">header in which Exim has no special interest</td></tr><tr><td align="left"><code class="literal">B</code></td><td align="left"><span class="emphasis"><em>Bcc:</em></span> header</td></tr><tr><td align="left"><code class="literal">C</code></td><td align="left"><span class="emphasis"><em>Cc:</em></span> header</td></tr><tr><td align="left"><code class="literal">F</code></td><td align="left"><span class="emphasis"><em>From:</em></span> header</td></tr><tr><td align="left"><code class="literal">I</code></td><td align="left"><span class="emphasis"><em>Message-id:</em></span> header</td></tr><tr><td align="left"><code class="literal">P</code></td><td align="left"><span class="emphasis"><em>Received:</em></span> header – P for “<span class="quote">postmark</span>”</td></tr><tr><td align="left"><code class="literal">R</code></td><td align="left"><span class="emphasis"><em>Reply-To:</em></span> header</td></tr><tr><td align="left"><code class="literal">S</code></td><td align="left"><span class="emphasis"><em>Sender:</em></span> header</td></tr><tr><td align="left"><code class="literal">T</code></td><td align="left"><span class="emphasis"><em>To:</em></span> header</td></tr><tr><td align="left"><code class="literal">*</code></td><td align="left">replaced or deleted header</td></tr></tbody></table></div>
<p>
Deleted or replaced (rewritten) headers remain in the spool file for debugging
purposes. They are not transmitted when the message is delivered. Here is a
typical set of headers:
</p>
<pre class="literallayout">111P Received: by hobbit.fict.example with local (Exim 4.00)
id 14y9EI-00026G-00; Fri, 11 May 2001 10:28:59 +0100
049 Message-Id: <E14y9EI-00026G-00@hobbit.fict.example>
038* X-rewrote-sender: bb@hobbit.fict.example
042* From: Bilbo Baggins <bb@hobbit.fict.example>
049F From: Bilbo Baggins <B.Baggins@hobbit.fict.example>
099* To: alice@wonderland.fict.example, rdo@foundation,
darcy@austen.fict.example, editor@thesaurus.ref.example
104T To: alice@wonderland.fict.example, rdo@foundation.example,
darcy@austen.fict.example, editor@thesaurus.ref.example
038 Date: Fri, 11 May 2001 10:28:59 +0100
</pre><p>
The asterisked headers indicate that the envelope sender, <span class="emphasis"><em>From:</em></span> header, and
<span class="emphasis"><em>To:</em></span> header have been rewritten, the last one because routing expanded the
unqualified domain <span class="emphasis"><em>foundation</em></span>.
<a id="id660193" class="indexterm"></a>
<a id="id660203" class="indexterm"></a>
<a id="id660216" class="indexterm"></a>
</p>
</div>
</div>
<div class="navfooter">
<table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch52.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="ch54.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div>
</body></html>
