<?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>26. The appendfile transport</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="ch25.html" title="25. Address batching in local transports" /><link rel="next" href="ch27.html" title="27. The autoreply transport" /></head><body><div class="navheader">
<table width="100%" summary="Navigation header"><tr><td width="20%" align="left"><a accesskey="p" href="ch25.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="ch27.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#toc0222" id="CHAPappendfile">26. The appendfile transport</a></h2></div>
</div>
</div>
<p>
<a id="IIDapptra1" class="indexterm"></a>
<a id="IIDapptra2" class="indexterm"></a>
<a id="id586229" class="indexterm"></a>
<a id="id586241" class="indexterm"></a>
The <span><strong class="command">appendfile</strong></span> transport delivers a message by appending it to an existing
file, or by creating an entirely new file in a specified directory. Single
files to which messages are appended can be in the traditional Unix mailbox
format, or optionally in the MBX format supported by the Pine MUA and
University of Washington IMAP daemon, <span class="emphasis"><em>inter alia</em></span>. When each message is
being delivered as a separate file, “<span class="quote">maildir</span>” format can optionally be used
to give added protection against failures that happen part-way through the
delivery. A third form of separate-file delivery known as “<span class="quote">mailstore</span>” is also
supported. For all file formats, Exim attempts to create as many levels of
directory as necessary, provided that <span><strong class="option">create_directory</strong></span> is set.
</p>
<p>
The code for the optional formats is not included in the Exim binary by
default. It is necessary to set SUPPORT_MBX, SUPPORT_MAILDIR and/or
SUPPORT_MAILSTORE in <em class="filename">Local/Makefile</em> to have the appropriate code
included.
</p>
<p>
<a id="id586300" class="indexterm"></a>
Exim recognizes system quota errors, and generates an appropriate message. Exim
also supports its own quota control within the transport, for use when the
system facility is unavailable or cannot be used for some reason.
</p>
<p>
If there is an error while appending to a file (for example, quota exceeded or
partition filled), Exim attempts to reset the file’s length and last
modification time back to what they were before. If there is an error while
creating an entirely new file, the new file is removed.
</p>
<p>
Before appending to a file, a number of security checks are made, and the
file is locked. A detailed description is given below, after the list of
private options.
</p>
<p>
The <span><strong class="command">appendfile</strong></span> transport is most commonly used for local deliveries to
users’ mailboxes. However, it can also be used as a pseudo-remote transport for
putting messages into files for remote delivery by some means other than Exim.
“<span class="quote">Batch SMTP</span>” format is often used in this case (see the <span><strong class="option">use_bsmtp</strong></span>
option).
</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#toc0223" id="SECTfildiropt">26.1 The file and directory options</a></h3></div>
</div>
</div>
<p>
The <span><strong class="option">file</strong></span> option specifies a single file, to which the message is appended;
the <span><strong class="option">directory</strong></span> option specifies a directory, in which a new file containing
the message is created. Only one of these two options can be set, and for
normal deliveries to mailboxes, one of them <span class="emphasis"><em>must</em></span> be set.
</p>
<p>
<a id="id586375" class="indexterm"></a>
<a id="id586387" class="indexterm"></a>
However, <span><strong class="command">appendfile</strong></span> is also used for delivering messages to files or
directories whose names (or parts of names) are obtained from alias,
forwarding, or filtering operations (for example, a <span><strong class="option">save</strong></span> command in a
user’s Exim filter). When such a transport is running, <em class="varname">$local_part</em> contains
the local part that was aliased or forwarded, and <em class="varname">$address_file</em> contains the
name (or partial name) of the file or directory generated by the redirection
operation. There are two cases:
</p>
<div class="itemizedlist">
<ul type="disc"><li><p>
If neither <span><strong class="option">file</strong></span> nor <span><strong class="option">directory</strong></span> is set, the redirection operation
must specify an absolute path (one that begins with <code class="literal">/</code>). This is the most
common case when users with local accounts use filtering to sort mail into
different folders. See for example, the <span><strong class="command">address_file</strong></span> transport in the
default configuration. If the path ends with a slash, it is assumed to be the
name of a directory. A delivery to a directory can also be forced by setting
<span><strong class="option">maildir_format</strong></span> or <span><strong class="option">mailstore_format</strong></span>.
</p>
</li><li><p>
If <span><strong class="option">file</strong></span> or <span><strong class="option">directory</strong></span> is set for a delivery from a redirection, it is
used to determine the file or directory name for the delivery. Normally, the
contents of <em class="varname">$address_file</em> are used in some way in the string expansion.
</p>
</li></ul></div>
<p>
<a id="id586490" class="indexterm"></a>
<a id="id586509" class="indexterm"></a>
As an example of the second case, consider an environment where users do not
have home directories. They may be permitted to use Exim filter commands of the
form:
</p>
<pre class="literallayout">save folder23
</pre><p>
or Sieve filter commands of the form:
</p>
<pre class="literallayout">require "fileinto";
fileinto "folder23";
</pre><p>
In this situation, the expansion of <span><strong class="option">file</strong></span> or <span><strong class="option">directory</strong></span> in the transport
must transform the relative path into an appropriate absolute file name. In the
case of Sieve filters, the name <span class="emphasis"><em>inbox</em></span> must be handled. It is the name that
is used as a result of a “<span class="quote">keep</span>” action in the filter. This example shows one
way of handling this requirement:
</p>
<pre class="literallayout">file = ${if eq{$address_file}{inbox} \
{/var/mail/$local_part} \
{${if eq{${substr_0_1:$address_file}}{/} \
{$address_file} \
{$home/mail/$address_file} \
}} \
}
</pre><p>
With this setting of <span><strong class="option">file</strong></span>, <span class="emphasis"><em>inbox</em></span> refers to the standard mailbox
location, absolute paths are used without change, and other folders are in the
<em class="filename">mail</em> directory within the home directory.
</p>
<p>
<span class="bold"><strong>Note 1</strong></span>: While processing an Exim filter, a relative path such as
<em class="filename">folder23</em> is turned into an absolute path if a home directory is known to
the router. In particular, this is the case if <span><strong class="option">check_local_user</strong></span> is set. If
you want to prevent this happening at routing time, you can set
<span><strong class="option">router_home_directory</strong></span> empty. This forces the router to pass the relative
path to the transport.
</p>
<p>
<span class="bold"><strong>Note 2</strong></span>: An absolute path in <em class="varname">$address_file</em> is not treated specially;
the <span><strong class="option">file</strong></span> or <span><strong class="option">directory</strong></span> option is still used if it is set.
</p>
</div>
<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#toc0224" id="SECID134">26.2 Private options for appendfile</a></h3></div>
</div>
</div>
<p>
<a id="id586664" class="indexterm"></a>
</p>
<p>
<a id="id586686" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">allow_fifo</strong></span></td><td align="center">Use: <span class="emphasis"><em>appendfile</em></span></td><td align="center">Type: <span class="emphasis"><em>boolean</em></span></td><td align="right">Default: <span class="emphasis"><em>false</em></span></td></tr></tbody></table></div>
<p>
<a id="id586768" class="indexterm"></a>
<a id="id586779" class="indexterm"></a>
<a id="id586790" class="indexterm"></a>
Setting this option permits delivery to named pipes (FIFOs) as well as to
regular files. If no process is reading the named pipe at delivery time, the
delivery is deferred.
</p>
<p>
<a id="id586811" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">allow_symlink</strong></span></td><td align="center">Use: <span class="emphasis"><em>appendfile</em></span></td><td align="center">Type: <span class="emphasis"><em>boolean</em></span></td><td align="right">Default: <span class="emphasis"><em>false</em></span></td></tr></tbody></table></div>
<p>
<a id="id586893" class="indexterm"></a>
<a id="id586908" class="indexterm"></a>
By default, <span><strong class="command">appendfile</strong></span> will not deliver if the path name for the file is
that of a symbolic link. Setting this option relaxes that constraint, but there
are security issues involved in the use of symbolic links. Be sure you know
what you are doing if you set this. Details of exactly what this option affects
are included in the discussion which follows this list of options.
</p>
<p>
<a id="id586937" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">batch_id</strong></span></td><td align="center">Use: <span class="emphasis"><em>appendfile</em></span></td><td align="center">Type: <span class="emphasis"><em>string</em></span>†<span class="emphasis"><em></em></span></td><td align="right">Default: <span class="emphasis"><em>unset</em></span></td></tr></tbody></table></div>
<p>
See the description of local delivery batching in chapter <a href="ch25.html" title="25. Address batching in local transports">25</a>.
However, batching is automatically disabled for <span><strong class="command">appendfile</strong></span> deliveries that
happen as a result of forwarding or aliasing or other redirection directly to a
file.
</p>
<p>
<a id="id587040" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">batch_max</strong></span></td><td align="center">Use: <span class="emphasis"><em>appendfile</em></span></td><td align="center">Type: <span class="emphasis"><em>integer</em></span></td><td align="right">Default: <span class="emphasis"><em>1</em></span></td></tr></tbody></table></div>
<p>
See the description of local delivery batching in chapter <a href="ch25.html" title="25. Address batching in local transports">25</a>.
</p>
<p>
<a id="id587132" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">check_group</strong></span></td><td align="center">Use: <span class="emphasis"><em>appendfile</em></span></td><td align="center">Type: <span class="emphasis"><em>boolean</em></span></td><td align="right">Default: <span class="emphasis"><em>false</em></span></td></tr></tbody></table></div>
<p>
When this option is set, the group owner of the file defined by the <span><strong class="option">file</strong></span>
option is checked to see that it is the same as the group under which the
delivery process is running. The default setting is false because the default
file mode is 0600, which means that the group is irrelevant.
</p>
<p>
<a id="id587226" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">check_owner</strong></span></td><td align="center">Use: <span class="emphasis"><em>appendfile</em></span></td><td align="center">Type: <span class="emphasis"><em>boolean</em></span></td><td align="right">Default: <span class="emphasis"><em>true</em></span></td></tr></tbody></table></div>
<p>
When this option is set, the owner of the file defined by the <span><strong class="option">file</strong></span> option
is checked to ensure that it is the same as the user under which the delivery
process is running.
</p>
<p>
<a id="id587317" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">check_string</strong></span></td><td align="center">Use: <span class="emphasis"><em>appendfile</em></span></td><td align="center">Type: <span class="emphasis"><em>string</em></span></td><td align="right">Default: <span class="emphasis"><em>see below</em></span></td></tr></tbody></table></div>
<p>
<a id="id587400" class="indexterm"></a>
As <span><strong class="command">appendfile</strong></span> writes the message, the start of each line is tested for
matching <span><strong class="option">check_string</strong></span>, and if it does, the initial matching characters are
replaced by the contents of <span><strong class="option">escape_string</strong></span>. The value of <span><strong class="option">check_string</strong></span> is
a literal string, not a regular expression, and the case of any letters it
contains is significant.
</p>
<p>
If <span><strong class="option">use_bsmtp</strong></span> is set the values of <span><strong class="option">check_string</strong></span> and <span><strong class="option">escape_string</strong></span>
are forced to “<span class="quote">.</span>” and “<span class="quote">..</span>” respectively, and any settings in the
configuration are ignored. Otherwise, they default to “<span class="quote">From </span>” and
“<span class="quote">>From </span>” when the <span><strong class="option">file</strong></span> option is set, and unset when any of the
<span><strong class="option">directory</strong></span>, <span><strong class="option">maildir</strong></span>, or <span><strong class="option">mailstore</strong></span> options are set.
</p>
<p>
The default settings, along with <span><strong class="option">message_prefix</strong></span> and <span><strong class="option">message_suffix</strong></span>, are
suitable for traditional “<span class="quote">BSD</span>” mailboxes, where a line beginning with
“<span class="quote">From </span>” indicates the start of a new message. All four options need changing
if another format is used. For example, to deliver to mailboxes in MMDF format:
<a id="id587503" class="indexterm"></a>
<a id="id587514" class="indexterm"></a>
</p>
<pre class="literallayout">check_string = "\1\1\1\1\n"
escape_string = "\1\1\1\1 \n"
message_prefix = "\1\1\1\1\n"
message_suffix = "\1\1\1\1\n"
</pre><p>
<a id="id587541" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">create_directory</strong></span></td><td align="center">Use: <span class="emphasis"><em>appendfile</em></span></td><td align="center">Type: <span class="emphasis"><em>boolean</em></span></td><td align="right">Default: <span class="emphasis"><em>true</em></span></td></tr></tbody></table></div>
<p>
<a id="id587624" class="indexterm"></a>
When this option is true, Exim attempts to create any missing superior
directories for the file that it is about to write. A created directory’s mode
is given by the <span><strong class="option">directory_mode</strong></span> option.
</p>
<p>
The group ownership of a newly created directory is highly dependent on the
operating system (and possibly the file system) that is being used. For
example, in Solaris, if the parent directory has the setgid bit set, its group
is propagated to the child; if not, the currently set group is used. However,
in FreeBSD, the parent’s group is always used.
</p>
<p>
<a id="id587652" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">create_file</strong></span></td><td align="center">Use: <span class="emphasis"><em>appendfile</em></span></td><td align="center">Type: <span class="emphasis"><em>string</em></span></td><td align="right">Default: <span class="emphasis"><em>anywhere</em></span></td></tr></tbody></table></div>
<p>
This option constrains the location of files and directories that are created
by this transport. It applies to files defined by the <span><strong class="option">file</strong></span> option and
directories defined by the <span><strong class="option">directory</strong></span> option. In the case of maildir
delivery, it applies to the top level directory, not the maildir directories
beneath.
</p>
<p>
The option must be set to one of the words “<span class="quote">anywhere</span>”, “<span class="quote">inhome</span>”, or
“<span class="quote">belowhome</span>”. In the second and third cases, a home directory must have been
set for the transport. This option is not useful when an explicit file name is
given for normal mailbox deliveries. It is intended for the case when file
names are generated from users’ <em class="filename">.forward</em> files. These are usually handled
by an <span><strong class="command">appendfile</strong></span> transport called <span><strong class="option">address_file</strong></span>. See also
<span><strong class="option">file_must_exist</strong></span>.
</p>
<p>
<a id="id587782" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">directory</strong></span></td><td align="center">Use: <span class="emphasis"><em>appendfile</em></span></td><td align="center">Type: <span class="emphasis"><em>string</em></span>†<span class="emphasis"><em></em></span></td><td align="right">Default: <span class="emphasis"><em>unset</em></span></td></tr></tbody></table></div>
<p>
This option is mutually exclusive with the <span><strong class="option">file</strong></span> option, but one of <span><strong class="option">file</strong></span>
or <span><strong class="option">directory</strong></span> must be set, unless the delivery is the direct result of a
redirection (see section <a href="ch26.html#SECTfildiropt" title="26.1 The file and directory options">26.1</a>).
</p>
<p>
When <span><strong class="option">directory</strong></span> is set, the string is expanded, and the message is delivered
into a new file or files in or below the given directory, instead of being
appended to a single mailbox file. A number of different formats are provided
(see <span><strong class="option">maildir_format</strong></span> and <span><strong class="option">mailstore_format</strong></span>), and see section
<a href="ch26.html#SECTopdir" title="26.4 Operational details for delivery to a new file">26.4</a> for further details of this form of delivery.
</p>
<p>
<a id="id587914" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">directory_file</strong></span></td><td align="center">Use: <span class="emphasis"><em>appendfile</em></span></td><td align="center">Type: <span class="emphasis"><em>string</em></span>†<span class="emphasis"><em></em></span></td><td align="right">Default: <span class="emphasis"><em>see below</em></span></td></tr></tbody></table></div>
<p>
<a id="id587998" class="indexterm"></a>
<a id="id588009" class="indexterm"></a>
When <span><strong class="option">directory</strong></span> is set, but neither <span><strong class="option">maildir_format</strong></span> nor
<span><strong class="option">mailstore_format</strong></span> is set, <span><strong class="command">appendfile</strong></span> delivers each message into a file
whose name is obtained by expanding this string. The default value is:
</p>
<pre class="literallayout">q${base62:$tod_epoch}-$inode
</pre><p>
This generates a unique name from the current time, in base 62 form, and the
inode of the file. The variable <em class="varname">$inode</em> is available only when expanding this
option.
</p>
<p>
<a id="id588061" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">directory_mode</strong></span></td><td align="center">Use: <span class="emphasis"><em>appendfile</em></span></td><td align="center">Type: <span class="emphasis"><em>octal integer</em></span></td><td align="right">Default: <span class="emphasis"><em>0700</em></span></td></tr></tbody></table></div>
<p>
If <span><strong class="command">appendfile</strong></span> creates any directories as a result of the
<span><strong class="option">create_directory</strong></span> option, their mode is specified by this option.
</p>
<p>
<a id="id588158" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">escape_string</strong></span></td><td align="center">Use: <span class="emphasis"><em>appendfile</em></span></td><td align="center">Type: <span class="emphasis"><em>string</em></span></td><td align="right">Default: <span class="emphasis"><em>see description</em></span></td></tr></tbody></table></div>
<p>
See <span><strong class="option">check_string</strong></span> above.
</p>
<p>
<a id="id588248" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">file</strong></span></td><td align="center">Use: <span class="emphasis"><em>appendfile</em></span></td><td align="center">Type: <span class="emphasis"><em>string</em></span>†<span class="emphasis"><em></em></span></td><td align="right">Default: <span class="emphasis"><em>unset</em></span></td></tr></tbody></table></div>
<p>
This option is mutually exclusive with the <span><strong class="option">directory</strong></span> option, but one of
<span><strong class="option">file</strong></span> or <span><strong class="option">directory</strong></span> must be set, unless the delivery is the direct result
of a redirection (see section <a href="ch26.html#SECTfildiropt" title="26.1 The file and directory options">26.1</a>). The <span><strong class="option">file</strong></span> option
specifies a single file, to which the message is appended. One or more of
<span><strong class="option">use_fcntl_lock</strong></span>, <span><strong class="option">use_flock_lock</strong></span>, or <span><strong class="option">use_lockfile</strong></span> must be set with
<span><strong class="option">file</strong></span>.
</p>
<p>
<a id="id588374" class="indexterm"></a>
<a id="id588388" class="indexterm"></a>
<a id="id588399" class="indexterm"></a>
If you are using more than one host to deliver over NFS into the same
mailboxes, you should always use lock files.
</p>
<p>
The string value is expanded for each delivery, and must yield an absolute
path. The most common settings of this option are variations on one of these
examples:
</p>
<pre class="literallayout">file = /var/spool/mail/$local_part
file = /home/$local_part/inbox
file = $home/inbox
</pre><p>
<a id="id588431" class="indexterm"></a>
In the first example, all deliveries are done into the same directory. If Exim
is configured to use lock files (see <span><strong class="option">use_lockfile</strong></span> below) it must be able to
create a file in the directory, so the “<span class="quote">sticky</span>” bit must be turned on for
deliveries to be possible, or alternatively the <span><strong class="option">group</strong></span> option can be used to
run the delivery under a group id which has write access to the directory.
</p>
<p>
<a id="id588464" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">file_format</strong></span></td><td align="center">Use: <span class="emphasis"><em>appendfile</em></span></td><td align="center">Type: <span class="emphasis"><em>string</em></span></td><td align="right">Default: <span class="emphasis"><em>unset</em></span></td></tr></tbody></table></div>
<p>
<a id="id588546" class="indexterm"></a>
This option requests the transport to check the format of an existing file
before adding to it. The check consists of matching a specific string at the
start of the file. The value of the option consists of an even number of
colon-separated strings. The first of each pair is the test string, and the
second is the name of a transport. If the transport associated with a matched
string is not the current transport, control is passed over to the other
transport. For example, suppose the standard <span><strong class="command">local_delivery</strong></span> transport has
this added to it:
</p>
<pre class="literallayout">file_format = "From : local_delivery :\
\1\1\1\1\n : local_mmdf_delivery"
</pre><p>
Mailboxes that begin with “<span class="quote">From</span>” are still handled by this transport, but if
a mailbox begins with four binary ones followed by a newline, control is passed
to a transport called <span><strong class="option">local_mmdf_delivery</strong></span>, which presumably is configured
to do the delivery in MMDF format. If a mailbox does not exist or is empty, it
is assumed to match the current transport. If the start of a mailbox doesn’t
match any string, or if the transport named for a given string is not defined,
delivery is deferred.
</p>
<p>
<a id="id588603" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">file_must_exist</strong></span></td><td align="center">Use: <span class="emphasis"><em>appendfile</em></span></td><td align="center">Type: <span class="emphasis"><em>boolean</em></span></td><td align="right">Default: <span class="emphasis"><em>false</em></span></td></tr></tbody></table></div>
<p>
If this option is true, the file specified by the <span><strong class="option">file</strong></span> option must exist.
A temporary error occurs if it does not, causing delivery to be deferred.
If this option is false, the file is created if it does not exist.
</p>
<p>
<a id="id588696" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">lock_fcntl_timeout</strong></span></td><td align="center">Use: <span class="emphasis"><em>appendfile</em></span></td><td align="center">Type: <span class="emphasis"><em>time</em></span></td><td align="right">Default: <span class="emphasis"><em>0s</em></span></td></tr></tbody></table></div>
<p>
<a id="id588778" class="indexterm"></a>
<a id="id588793" class="indexterm"></a>
<a id="id588808" class="indexterm"></a>
By default, the <span><strong class="command">appendfile</strong></span> transport uses non-blocking calls to <em class="function">fcntl()</em>
when locking an open mailbox file. If the call fails, the delivery process
sleeps for <span><strong class="option">lock_interval</strong></span> and tries again, up to <span><strong class="option">lock_retries</strong></span> times.
Non-blocking calls are used so that the file is not kept open during the wait
for the lock; the reason for this is to make it as safe as possible for
deliveries over NFS in the case when processes might be accessing an NFS
mailbox without using a lock file. This should not be done, but
misunderstandings and hence misconfigurations are not unknown.
</p>
<p>
On a busy system, however, the performance of a non-blocking lock approach is
not as good as using a blocking lock with a timeout. In this case, the waiting
is done inside the system call, and Exim’s delivery process acquires the lock
and can proceed as soon as the previous lock holder releases it.
</p>
<p>
If <span><strong class="option">lock_fcntl_timeout</strong></span> is set to a non-zero time, blocking locks, with that
timeout, are used. There may still be some retrying: the maximum number of
retries is
</p>
<pre class="literallayout">(lock_retries * lock_interval) / lock_fcntl_timeout
</pre><p>
rounded up to the next whole number. In other words, the total time during
which <span><strong class="command">appendfile</strong></span> is trying to get a lock is roughly the same, unless
<span><strong class="option">lock_fcntl_timeout</strong></span> is set very large.
</p>
<p>
You should consider setting this option if you are getting a lot of delayed
local deliveries because of errors of the form
</p>
<pre class="literallayout">failed to lock mailbox /some/file (fcntl)
</pre><p>
<a id="id588908" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">lock_flock_timeout</strong></span></td><td align="center">Use: <span class="emphasis"><em>appendfile</em></span></td><td align="center">Type: <span class="emphasis"><em>time</em></span></td><td align="right">Default: <span class="emphasis"><em>0s</em></span></td></tr></tbody></table></div>
<p>
This timeout applies to file locking when using <em class="function">flock()</em> (see
<span><strong class="option">use_flock</strong></span>); the timeout operates in a similar manner to
<span><strong class="option">lock_fcntl_timeout</strong></span>.
</p>
<p>
<a id="id589008" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">lock_interval</strong></span></td><td align="center">Use: <span class="emphasis"><em>appendfile</em></span></td><td align="center">Type: <span class="emphasis"><em>time</em></span></td><td align="right">Default: <span class="emphasis"><em>3s</em></span></td></tr></tbody></table></div>
<p>
This specifies the time to wait between attempts to lock the file. See below
for details of locking.
</p>
<p>
<a id="id589095" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">lock_retries</strong></span></td><td align="center">Use: <span class="emphasis"><em>appendfile</em></span></td><td align="center">Type: <span class="emphasis"><em>integer</em></span></td><td align="right">Default: <span class="emphasis"><em>10</em></span></td></tr></tbody></table></div>
<p>
This specifies the maximum number of attempts to lock the file. A value of zero
is treated as 1. See below for details of locking.
</p>
<p>
<a id="id589182" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">lockfile_mode</strong></span></td><td align="center">Use: <span class="emphasis"><em>appendfile</em></span></td><td align="center">Type: <span class="emphasis"><em>octal integer</em></span></td><td align="right">Default: <span class="emphasis"><em>0600</em></span></td></tr></tbody></table></div>
<p>
This specifies the mode of the created lock file, when a lock file is being
used (see <span><strong class="option">use_lockfile</strong></span> and <span><strong class="option">use_mbx_lock</strong></span>).
</p>
<p>
<a id="id589277" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">lockfile_timeout</strong></span></td><td align="center">Use: <span class="emphasis"><em>appendfile</em></span></td><td align="center">Type: <span class="emphasis"><em>time</em></span></td><td align="right">Default: <span class="emphasis"><em>30m</em></span></td></tr></tbody></table></div>
<p>
<a id="id589359" class="indexterm"></a>
When a lock file is being used (see <span><strong class="option">use_lockfile</strong></span>), if a lock file already
exists and is older than this value, it is assumed to have been left behind by
accident, and Exim attempts to remove it.
</p>
<p>
<a id="id589384" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">mailbox_filecount</strong></span></td><td align="center">Use: <span class="emphasis"><em>appendfile</em></span></td><td align="center">Type: <span class="emphasis"><em>string</em></span>†<span class="emphasis"><em></em></span></td><td align="right">Default: <span class="emphasis"><em>unset</em></span></td></tr></tbody></table></div>
<p>
<a id="id589469" class="indexterm"></a>
<a id="id589483" class="indexterm"></a>
If this option is set, it is expanded, and the result is taken as the current
number of files in the mailbox. It must be a decimal number, optionally
followed by K or M. This provides a way of obtaining this information from an
external source that maintains the data.
</p>
<p>
<a id="id589505" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">mailbox_size</strong></span></td><td align="center">Use: <span class="emphasis"><em>appendfile</em></span></td><td align="center">Type: <span class="emphasis"><em>string</em></span>†<span class="emphasis"><em></em></span></td><td align="right">Default: <span class="emphasis"><em>unset</em></span></td></tr></tbody></table></div>
<p>
<a id="id589590" class="indexterm"></a>
<a id="id589605" class="indexterm"></a>
If this option is set, it is expanded, and the result is taken as the current
size the mailbox. It must be a decimal number, optionally followed by K or M.
This provides a way of obtaining this information from an external source that
maintains the data. This is likely to be helpful for maildir deliveries where
it is computationally expensive to compute the size of a mailbox.
</p>
<p>
<a id="id589629" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">maildir_format</strong></span></td><td align="center">Use: <span class="emphasis"><em>appendfile</em></span></td><td align="center">Type: <span class="emphasis"><em>boolean</em></span></td><td align="right">Default: <span class="emphasis"><em>false</em></span></td></tr></tbody></table></div>
<p>
<a id="id589711" class="indexterm"></a>
If this option is set with the <span><strong class="option">directory</strong></span> option, the delivery is into a new
file, in the “<span class="quote">maildir</span>” format that is used by other mail software. When the
transport is activated directly from a <span><strong class="command">redirect</strong></span> router (for example, the
<span><strong class="command">address_file</strong></span> transport in the default configuration), setting
<span><strong class="option">maildir_format</strong></span> causes the path received from the router to be treated as a
directory, whether or not it ends with <code class="literal">/</code>. This option is available only if
SUPPORT_MAILDIR is present in <em class="filename">Local/Makefile</em>. See section
<a href="ch26.html#SECTmaildirdelivery" title="26.5 Maildir delivery">26.5</a> below for further details.
</p>
<p>
<a id="id589774" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">maildir_quota_directory_regex</strong></span></td><td align="center">Use: <span class="emphasis"><em>appendfile</em></span></td><td align="center">Type: <span class="emphasis"><em>string</em></span></td><td align="right">Default: <span class="emphasis"><em>See below</em></span></td></tr></tbody></table></div>
<p>
<a id="id589856" class="indexterm"></a>
<a id="id589871" class="indexterm"></a>
This option is relevant only when <span><strong class="option">maildir_use_size_file</strong></span> is set. It defines
a regular expression for specifying directories, relative to the quota
directory (see <span><strong class="option">quota_directory</strong></span>), that should be included in the quota
calculation. The default value is:
</p>
<pre class="literallayout">maildir_quota_directory_regex = ^(?:cur|new|\..*)$
</pre><p>
This includes the <em class="filename">cur</em> and <em class="filename">new</em> directories, and any maildir++ folders
(directories whose names begin with a dot). If you want to exclude the
<em class="filename">Trash</em>
folder from the count (as some sites do), you need to change this setting to
</p>
<pre class="literallayout">maildir_quota_directory_regex = ^(?:cur|new|\.(?!Trash).*)$
</pre><p>
This uses a negative lookahead in the regular expression to exclude the
directory whose name is <em class="filename">.Trash</em>. When a directory is excluded from quota
calculations, quota processing is bypassed for any messages that are delivered
directly into that directory.
</p>
<p>
<a id="id589955" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">maildir_retries</strong></span></td><td align="center">Use: <span class="emphasis"><em>appendfile</em></span></td><td align="center">Type: <span class="emphasis"><em>integer</em></span></td><td align="right">Default: <span class="emphasis"><em>10</em></span></td></tr></tbody></table></div>
<p>
This option specifies the number of times to retry when writing a file in
“<span class="quote">maildir</span>” format. See section <a href="ch26.html#SECTmaildirdelivery" title="26.5 Maildir delivery">26.5</a> below.
</p>
<p>
<a id="id590052" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">maildir_tag</strong></span></td><td align="center">Use: <span class="emphasis"><em>appendfile</em></span></td><td align="center">Type: <span class="emphasis"><em>string</em></span>†<span class="emphasis"><em></em></span></td><td align="right">Default: <span class="emphasis"><em>unset</em></span></td></tr></tbody></table></div>
<p>
This option applies only to deliveries in maildir format, and is described in
section <a href="ch26.html#SECTmaildirdelivery" title="26.5 Maildir delivery">26.5</a> below.
</p>
<p>
<a id="id590147" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">maildir_use_size_file</strong></span></td><td align="center">Use: <span class="emphasis"><em>appendfile</em></span></td><td align="center">Type: <span class="emphasis"><em>boolean</em></span></td><td align="right">Default: <span class="emphasis"><em>false</em></span></td></tr></tbody></table></div>
<p>
<a id="id590229" class="indexterm"></a>
Setting this option true enables support for <em class="filename">maildirsize</em> files. Exim
creates a <em class="filename">maildirsize</em> file in a maildir if one does not exist, taking the
quota from the <span><strong class="option">quota</strong></span> option of the transport. If <span><strong class="option">quota</strong></span> is unset, the
value is zero. See <span><strong class="option">maildir_quota_directory_regex</strong></span> above and section
<a href="ch26.html#SECTmaildirdelivery" title="26.5 Maildir delivery">26.5</a> below for further details.
</p>
<p>
<a id="id590284" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">maildirfolder_create_regex</strong></span></td><td align="center">Use: <span class="emphasis"><em>appendfile</em></span></td><td align="center">Type: <span class="emphasis"><em>string</em></span></td><td align="right">Default: <span class="emphasis"><em>unset</em></span></td></tr></tbody></table></div>
<p>
<a id="id590367" class="indexterm"></a>
<a id="id590386" class="indexterm"></a>
The value of this option is a regular expression. If it is unset, it has no
effect. Otherwise, before a maildir delivery takes place, the pattern is
matched against the name of the maildir directory, that is, the directory
containing the <em class="filename">new</em> and <em class="filename">tmp</em> subdirectories that will be used for the
delivery. If there is a match, Exim checks for the existence of a file called
<em class="filename">maildirfolder</em> in the directory, and creates it if it does not exist.
See section <a href="ch26.html#SECTmaildirdelivery" title="26.5 Maildir delivery">26.5</a> for more details.
</p>
<p>
<a id="id590435" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">mailstore_format</strong></span></td><td align="center">Use: <span class="emphasis"><em>appendfile</em></span></td><td align="center">Type: <span class="emphasis"><em>boolean</em></span></td><td align="right">Default: <span class="emphasis"><em>false</em></span></td></tr></tbody></table></div>
<p>
<a id="id590518" class="indexterm"></a>
If this option is set with the <span><strong class="option">directory</strong></span> option, the delivery is into two
new files in “<span class="quote">mailstore</span>” format. The option is available only if
SUPPORT_MAILSTORE is present in <em class="filename">Local/Makefile</em>. See section <a href="ch26.html#SECTopdir" title="26.4 Operational details for delivery to a new file">26.4</a>
below for further details.
</p>
<p>
<a id="id590558" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">mailstore_prefix</strong></span></td><td align="center">Use: <span class="emphasis"><em>appendfile</em></span></td><td align="center">Type: <span class="emphasis"><em>string</em></span>†<span class="emphasis"><em></em></span></td><td align="right">Default: <span class="emphasis"><em>unset</em></span></td></tr></tbody></table></div>
<p>
This option applies only to deliveries in mailstore format, and is described in
section <a href="ch26.html#SECTopdir" title="26.4 Operational details for delivery to a new file">26.4</a> below.
</p>
<p>
<a id="id590653" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">mailstore_suffix</strong></span></td><td align="center">Use: <span class="emphasis"><em>appendfile</em></span></td><td align="center">Type: <span class="emphasis"><em>string</em></span>†<span class="emphasis"><em></em></span></td><td align="right">Default: <span class="emphasis"><em>unset</em></span></td></tr></tbody></table></div>
<p>
This option applies only to deliveries in mailstore format, and is described in
section <a href="ch26.html#SECTopdir" title="26.4 Operational details for delivery to a new file">26.4</a> below.
</p>
<p>
<a id="id590749" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">mbx_format</strong></span></td><td align="center">Use: <span class="emphasis"><em>appendfile</em></span></td><td align="center">Type: <span class="emphasis"><em>boolean</em></span></td><td align="right">Default: <span class="emphasis"><em>false</em></span></td></tr></tbody></table></div>
<p>
<a id="id590831" class="indexterm"></a>
<a id="id590842" class="indexterm"></a>
<a id="id590856" class="indexterm"></a>
<a id="id590870" class="indexterm"></a>
This option is available only if Exim has been compiled with SUPPORT_MBX
set in <em class="filename">Local/Makefile</em>. If <span><strong class="option">mbx_format</strong></span> is set with the <span><strong class="option">file</strong></span> option,
the message is appended to the mailbox file in MBX format instead of
traditional Unix format. This format is supported by Pine4 and its associated
IMAP and POP daemons, by means of the <span class="emphasis"><em>c-client</em></span> library that they all use.
</p>
<p>
<span class="bold"><strong>Note</strong></span>: The <span><strong class="option">message_prefix</strong></span> and <span><strong class="option">message_suffix</strong></span> options are not
automatically changed by the use of <span><strong class="option">mbx_format</strong></span>. They should normally be set
empty when using MBX format, so this option almost always appears in this
combination:
</p>
<pre class="literallayout">mbx_format = true
message_prefix =
message_suffix =
</pre><p>
If none of the locking options are mentioned in the configuration,
<span><strong class="option">use_mbx_lock</strong></span> is assumed and the other locking options default to false. It
is possible to specify the other kinds of locking with <span><strong class="option">mbx_format</strong></span>, but
<span><strong class="option">use_fcntl_lock</strong></span> and <span><strong class="option">use_mbx_lock</strong></span> are mutually exclusive. MBX locking
interworks with <span class="emphasis"><em>c-client</em></span>, providing for shared access to the mailbox. It
should not be used if any program that does not use this form of locking is
going to access the mailbox, nor should it be used if the mailbox file is NFS
mounted, because it works only when the mailbox is accessed from a single host.
</p>
<p>
If you set <span><strong class="option">use_fcntl_lock</strong></span> with an MBX-format mailbox, you cannot use
the standard version of <span class="emphasis"><em>c-client</em></span>, because as long as it has a mailbox open
(this means for the whole of a Pine or IMAP session), Exim will not be able to
append messages to it.
</p>
<p>
<a id="id590984" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">message_prefix</strong></span></td><td align="center">Use: <span class="emphasis"><em>appendfile</em></span></td><td align="center">Type: <span class="emphasis"><em>string</em></span>†<span class="emphasis"><em></em></span></td><td align="right">Default: <span class="emphasis"><em>see below</em></span></td></tr></tbody></table></div>
<p>
<a id="id591068" class="indexterm"></a>
The string specified here is expanded and output at the start of every message.
The default is unset unless <span><strong class="option">file</strong></span> is specified and <span><strong class="option">use_bsmtp</strong></span> is not set,
in which case it is:
</p>
<pre class="literallayout">message_prefix = "From ${if def:return_path{$return_path}\
{MAILER-DAEMON}} $tod_bsdinbox\n"
</pre><p>
<span class="bold"><strong>Note:</strong></span> If you set <span><strong class="option">use_crlf</strong></span> true, you must change any occurrences of
<code class="literal">\n</code> to <code class="literal">\r\n</code> in <span><strong class="option">message_prefix</strong></span>.
</p>
<p>
<a id="id591132" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">message_suffix</strong></span></td><td align="center">Use: <span class="emphasis"><em>appendfile</em></span></td><td align="center">Type: <span class="emphasis"><em>string</em></span>†<span class="emphasis"><em></em></span></td><td align="right">Default: <span class="emphasis"><em>see below</em></span></td></tr></tbody></table></div>
<p>
The string specified here is expanded and output at the end of every message.
The default is unset unless <span><strong class="option">file</strong></span> is specified and <span><strong class="option">use_bsmtp</strong></span> is not set,
in which case it is a single newline character. The suffix can be suppressed by
setting
</p>
<pre class="literallayout">message_suffix =
</pre><p>
<span class="bold"><strong>Note:</strong></span> If you set <span><strong class="option">use_crlf</strong></span> true, you must change any occurrences of
<code class="literal">\n</code> to <code class="literal">\r\n</code> in <span><strong class="option">message_suffix</strong></span>.
</p>
<p>
<a id="id591267" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">mode</strong></span></td><td align="center">Use: <span class="emphasis"><em>appendfile</em></span></td><td align="center">Type: <span class="emphasis"><em>octal integer</em></span></td><td align="right">Default: <span class="emphasis"><em>0600</em></span></td></tr></tbody></table></div>
<p>
If the output file is created, it is given this mode. If it already exists and
has wider permissions, they are reduced to this mode. If it has narrower
permissions, an error occurs unless <span><strong class="option">mode_fail_narrower</strong></span> is false. However,
if the delivery is the result of a <span><strong class="option">save</strong></span> command in a filter file specifying
a particular mode, the mode of the output file is always forced to take that
value, and this option is ignored.
</p>
<p>
<a id="id591367" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">mode_fail_narrower</strong></span></td><td align="center">Use: <span class="emphasis"><em>appendfile</em></span></td><td align="center">Type: <span class="emphasis"><em>boolean</em></span></td><td align="right">Default: <span class="emphasis"><em>true</em></span></td></tr></tbody></table></div>
<p>
This option applies in the case when an existing mailbox file has a narrower
mode than that specified by the <span><strong class="option">mode</strong></span> option. If <span><strong class="option">mode_fail_narrower</strong></span> is
true, the delivery is deferred (“<span class="quote">mailbox has the wrong mode</span>”); otherwise Exim
continues with the delivery attempt, using the existing mode of the file.
</p>
<p>
<a id="id591468" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">notify_comsat</strong></span></td><td align="center">Use: <span class="emphasis"><em>appendfile</em></span></td><td align="center">Type: <span class="emphasis"><em>boolean</em></span></td><td align="right">Default: <span class="emphasis"><em>false</em></span></td></tr></tbody></table></div>
<p>
If this option is true, the <span class="emphasis"><em>comsat</em></span> daemon is notified after every
successful delivery to a user mailbox. This is the daemon that notifies logged
on users about incoming mail.
</p>
<p>
<a id="id591560" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">quota</strong></span></td><td align="center">Use: <span class="emphasis"><em>appendfile</em></span></td><td align="center">Type: <span class="emphasis"><em>string</em></span>†<span class="emphasis"><em></em></span></td><td align="right">Default: <span class="emphasis"><em>unset</em></span></td></tr></tbody></table></div>
<p>
<a id="id591644" class="indexterm"></a>
This option imposes a limit on the size of the file to which Exim is appending,
or to the total space used in the directory tree when the <span><strong class="option">directory</strong></span> option
is set. In the latter case, computation of the space used is expensive, because
all the files in the directory (and any sub-directories) have to be
individually inspected and their sizes summed. (See <span><strong class="option">quota_size_regex</strong></span> and
<span><strong class="option">maildir_use_size_file</strong></span> for ways to avoid this in environments where users
have no shell access to their mailboxes).
</p>
<p>
As there is no interlock against two simultaneous deliveries into a
multi-file mailbox, it is possible for the quota to be overrun in this case.
For single-file mailboxes, of course, an interlock is a necessity.
</p>
<p>
A file’s size is taken as its <span class="emphasis"><em>used</em></span> value. Because of blocking effects, this
may be a lot less than the actual amount of disk space allocated to the file.
If the sizes of a number of files are being added up, the rounding effect can
become quite noticeable, especially on systems that have large block sizes.
Nevertheless, it seems best to stick to the <span class="emphasis"><em>used</em></span> figure, because this is
the obvious value which users understand most easily.
</p>
<p>
The value of the option is expanded, and must then be a numerical value
(decimal point allowed), optionally followed by one of the letters K, M, or G,
for kilobytes, megabytes, or gigabytes. If Exim is running on a system with
large file support (Linux and FreeBSD have this), mailboxes larger than 2G can
be handled.
</p>
<p>
<span class="bold"><strong>Note</strong></span>: A value of zero is interpreted as “<span class="quote">no quota</span>”.
</p>
<p>
The expansion happens while Exim is running as root, before it changes uid for
the delivery. This means that files that are inaccessible to the end user can
be used to hold quota values that are looked up in the expansion. When delivery
fails because this quota is exceeded, the handling of the error is as for
system quota failures.
</p>
<p>
By default, Exim’s quota checking mimics system quotas, and restricts the
mailbox to the specified maximum size, though the value is not accurate to the
last byte, owing to separator lines and additional headers that may get added
during message delivery. When a mailbox is nearly full, large messages may get
refused even though small ones are accepted, because the size of the current
message is added to the quota when the check is made. This behaviour can be
changed by setting <span><strong class="option">quota_is_inclusive</strong></span> false. When this is done, the check
for exceeding the quota does not include the current message. Thus, deliveries
continue until the quota has been exceeded; thereafter, no further messages are
delivered. See also <span><strong class="option">quota_warn_threshold</strong></span>.
</p>
<p>
<a id="id591752" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">quota_directory</strong></span></td><td align="center">Use: <span class="emphasis"><em>appendfile</em></span></td><td align="center">Type: <span class="emphasis"><em>string</em></span>†<span class="emphasis"><em></em></span></td><td align="right">Default: <span class="emphasis"><em>unset</em></span></td></tr></tbody></table></div>
<p>
This option defines the directory to check for quota purposes when delivering
into individual files. The default is the delivery directory, or, if a file
called <em class="filename">maildirfolder</em> exists in a maildir directory, the parent of the
delivery directory.
</p>
<p>
<a id="id591849" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">quota_filecount</strong></span></td><td align="center">Use: <span class="emphasis"><em>appendfile</em></span></td><td align="center">Type: <span class="emphasis"><em>string</em></span>†<span class="emphasis"><em></em></span></td><td align="right">Default: <span class="emphasis"><em>0</em></span></td></tr></tbody></table></div>
<p>
This option applies when the <span><strong class="option">directory</strong></span> option is set. It limits the total
number of files in the directory (compare the inode limit in system quotas). It
can only be used if <span><strong class="option">quota</strong></span> is also set. The value is expanded; an expansion
failure causes delivery to be deferred. A value of zero is interpreted as
“<span class="quote">no quota</span>”.
</p>
<p>
<a id="id591952" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">quota_is_inclusive</strong></span></td><td align="center">Use: <span class="emphasis"><em>appendfile</em></span></td><td align="center">Type: <span class="emphasis"><em>boolean</em></span></td><td align="right">Default: <span class="emphasis"><em>true</em></span></td></tr></tbody></table></div>
<p>
See <span><strong class="option">quota</strong></span> above.
</p>
<p>
<a id="id592041" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">quota_size_regex</strong></span></td><td align="center">Use: <span class="emphasis"><em>appendfile</em></span></td><td align="center">Type: <span class="emphasis"><em>string</em></span></td><td align="right">Default: <span class="emphasis"><em>unset</em></span></td></tr></tbody></table></div>
<p>
This option applies when one of the delivery modes that writes a separate file
for each message is being used. When Exim wants to find the size of one of
these files in order to test the quota, it first checks <span><strong class="option">quota_size_regex</strong></span>.
If this is set to a regular expression that matches the file name, and it
captures one string, that string is interpreted as a representation of the
file’s size. The value of <span><strong class="option">quota_size_regex</strong></span> is not expanded.
</p>
<p>
This feature is useful only when users have no shell access to their mailboxes
– otherwise they could defeat the quota simply by renaming the files. This
facility can be used with maildir deliveries, by setting <span><strong class="option">maildir_tag</strong></span> to add
the file length to the file name. For example:
</p>
<pre class="literallayout">maildir_tag = ,S=$message_size
quota_size_regex = ,S=(\d+)
</pre><p>
An alternative to <em class="varname">$message_size</em> is <em class="varname">$message_linecount</em>, which contains the
number of lines in the message.
</p>
<p>
The regular expression should not assume that the length is at the end of the
file name (even though <span><strong class="option">maildir_tag</strong></span> puts it there) because maildir MUAs
sometimes add other information onto the ends of message file names.
</p>
<p>
<a id="id592189" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">quota_warn_message</strong></span></td><td align="center">Use: <span class="emphasis"><em>appendfile</em></span></td><td align="center">Type: <span class="emphasis"><em>string</em></span>†<span class="emphasis"><em></em></span></td><td align="right">Default: <span class="emphasis"><em>see below</em></span></td></tr></tbody></table></div>
<p>
See below for the use of this option. If it is not set when
<span><strong class="option">quota_warn_threshold</strong></span> is set, it defaults to
</p>
<pre class="literallayout">quota_warn_message = "\
To: $local_part@$domain\n\
Subject: Your mailbox\n\n\
This message is automatically created \
by mail delivery software.\n\n\
The size of your mailbox has exceeded \
a warning threshold that is\n\
set by the system administrator.\n"
</pre><p>
<a id="id592294" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">quota_warn_threshold</strong></span></td><td align="center">Use: <span class="emphasis"><em>appendfile</em></span></td><td align="center">Type: <span class="emphasis"><em>string</em></span>†<span class="emphasis"><em></em></span></td><td align="right">Default: <span class="emphasis"><em>0</em></span></td></tr></tbody></table></div>
<p>
<a id="id592379" class="indexterm"></a>
<a id="id592394" class="indexterm"></a>
<a id="id592408" class="indexterm"></a>
This option is expanded in the same way as <span><strong class="option">quota</strong></span> (see above). If the
resulting value is greater than zero, and delivery of the message causes the
size of the file or total space in the directory tree to cross the given
threshold, a warning message is sent. If <span><strong class="option">quota</strong></span> is also set, the threshold
may be specified as a percentage of it by following the value with a percent
sign. For example:
</p>
<pre class="literallayout">quota = 10M
quota_warn_threshold = 75%
</pre><p>
If <span><strong class="option">quota</strong></span> is not set, a setting of <span><strong class="option">quota_warn_threshold</strong></span> that ends with a
percent sign is ignored.
</p>
<p>
The warning message itself is specified by the <span><strong class="option">quota_warn_message</strong></span> option,
and it must start with a <span class="emphasis"><em>To:</em></span> header line containing the recipient(s) of the
warning message. These do not necessarily have to include the recipient(s) of
the original message. A <span class="emphasis"><em>Subject:</em></span> line should also normally be supplied. You
can include any other header lines that you want. If you do not include a
<span class="emphasis"><em>From:</em></span> line, the default is:
</p>
<pre class="literallayout">From: Mail Delivery System <mailer-daemon@$qualify_domain_sender>
</pre><p>
<a id="id592494" class="indexterm"></a>
If you supply a <span class="emphasis"><em>Reply-To:</em></span> line, it overrides the global <span><strong class="option">errors_reply_to</strong></span>
option.
</p>
<p>
The <span><strong class="option">quota</strong></span> option does not have to be set in order to use this option; they
are independent of one another except when the threshold is specified as a
percentage.
</p>
<p>
<a id="id592526" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">use_bsmtp</strong></span></td><td align="center">Use: <span class="emphasis"><em>appendfile</em></span></td><td align="center">Type: <span class="emphasis"><em>boolean</em></span></td><td align="right">Default: <span class="emphasis"><em>false</em></span></td></tr></tbody></table></div>
<p>
<a id="id592608" class="indexterm"></a>
If this option is set true, <span><strong class="command">appendfile</strong></span> writes messages in “<span class="quote">batch SMTP</span>”
format, with the envelope sender and recipient(s) included as SMTP commands. If
you want to include a leading HELO command with such messages, you can do
so by setting the <span><strong class="option">message_prefix</strong></span> option. See section <a href="ch45.html#SECTbatchSMTP" title="45.10 Outgoing batched SMTP">45.10</a>
for details of batch SMTP.
</p>
<p>
<a id="id592645" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">use_crlf</strong></span></td><td align="center">Use: <span class="emphasis"><em>appendfile</em></span></td><td align="center">Type: <span class="emphasis"><em>boolean</em></span></td><td align="right">Default: <span class="emphasis"><em>false</em></span></td></tr></tbody></table></div>
<p>
<a id="id592727" class="indexterm"></a>
<a id="id592738" class="indexterm"></a>
This option causes lines to be terminated with the two-character CRLF sequence
(carriage return, linefeed) instead of just a linefeed character. In the case
of batched SMTP, the byte sequence written to the file is then an exact image
of what would be sent down a real SMTP connection.
</p>
<p>
<span class="bold"><strong>Note:</strong></span> The contents of the <span><strong class="option">message_prefix</strong></span> and <span><strong class="option">message_suffix</strong></span> options
(which are used to supply the traditional “<span class="quote">From </span>” and blank line separators
in Berkeley-style mailboxes) are written verbatim, so must contain their own
carriage return characters if these are needed. In cases where these options
have non-empty defaults, the values end with a single linefeed, so they must be
changed to end with <code class="literal">\r\n</code> if <span><strong class="option">use_crlf</strong></span> is set.
</p>
<p>
<a id="id592793" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">use_fcntl_lock</strong></span></td><td align="center">Use: <span class="emphasis"><em>appendfile</em></span></td><td align="center">Type: <span class="emphasis"><em>boolean</em></span></td><td align="right">Default: <span class="emphasis"><em>see below</em></span></td></tr></tbody></table></div>
<p>
This option controls the use of the <em class="function">fcntl()</em> function to lock a file for
exclusive use when a message is being appended. It is set by default unless
<span><strong class="option">use_flock_lock</strong></span> is set. Otherwise, it should be turned off only if you know
that all your MUAs use lock file locking. When both <span><strong class="option">use_fcntl_lock</strong></span> and
<span><strong class="option">use_flock_lock</strong></span> are unset, <span><strong class="option">use_lockfile</strong></span> must be set.
</p>
<p>
<a id="id592903" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">use_flock_lock</strong></span></td><td align="center">Use: <span class="emphasis"><em>appendfile</em></span></td><td align="center">Type: <span class="emphasis"><em>boolean</em></span></td><td align="right">Default: <span class="emphasis"><em>false</em></span></td></tr></tbody></table></div>
<p>
This option is provided to support the use of <em class="function">flock()</em> for file locking, for
the few situations where it is needed. Most modern operating systems support
<em class="function">fcntl()</em> and <em class="function">lockf()</em> locking, and these two functions interwork with
each other. Exim uses <em class="function">fcntl()</em> locking by default.
</p>
<p>
This option is required only if you are using an operating system where
<em class="function">flock()</em> is used by programs that access mailboxes (typically MUAs), and
where <em class="function">flock()</em> does not correctly interwork with <em class="function">fcntl()</em>. You can use
both <em class="function">fcntl()</em> and <em class="function">flock()</em> locking simultaneously if you want.
</p>
<p>
<a id="id593052" class="indexterm"></a>
Not all operating systems provide <em class="function">flock()</em>. Some versions of Solaris do not
have it (and some, I think, provide a not quite right version built on top of
<em class="function">lockf()</em>). If the OS does not have <em class="function">flock()</em>, Exim will be built without
the ability to use it, and any attempt to do so will cause a configuration
error.
</p>
<p>
<span class="bold"><strong>Warning</strong></span>: <em class="function">flock()</em> locks do not work on NFS files (unless <em class="function">flock()</em>
is just being mapped onto <em class="function">fcntl()</em> by the OS).
</p>
<p>
<a id="id593123" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">use_lockfile</strong></span></td><td align="center">Use: <span class="emphasis"><em>appendfile</em></span></td><td align="center">Type: <span class="emphasis"><em>boolean</em></span></td><td align="right">Default: <span class="emphasis"><em>see below</em></span></td></tr></tbody></table></div>
<p>
If this option is turned off, Exim does not attempt to create a lock file when
appending to a mailbox file. In this situation, the only locking is by
<em class="function">fcntl()</em>. You should only turn <span><strong class="option">use_lockfile</strong></span> off if you are absolutely
sure that every MUA that is ever going to look at your users’ mailboxes uses
<em class="function">fcntl()</em> rather than a lock file, and even then only when you are not
delivering over NFS from more than one host.
</p>
<p>
<a id="id593233" class="indexterm"></a>
In order to append to an NFS file safely from more than one host, it is
necessary to take out a lock <span class="emphasis"><em>before</em></span> opening the file, and the lock file
achieves this. Otherwise, even with <em class="function">fcntl()</em> locking, there is a risk of
file corruption.
</p>
<p>
The <span><strong class="option">use_lockfile</strong></span> option is set by default unless <span><strong class="option">use_mbx_lock</strong></span> is set.
It is not possible to turn both <span><strong class="option">use_lockfile</strong></span> and <span><strong class="option">use_fcntl_lock</strong></span> off,
except when <span><strong class="option">mbx_format</strong></span> is set.
</p>
<p>
<a id="id593287" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">use_mbx_lock</strong></span></td><td align="center">Use: <span class="emphasis"><em>appendfile</em></span></td><td align="center">Type: <span class="emphasis"><em>boolean</em></span></td><td align="right">Default: <span class="emphasis"><em>see below</em></span></td></tr></tbody></table></div>
<p>
This option is available only if Exim has been compiled with SUPPORT_MBX
set in <em class="filename">Local/Makefile</em>. Setting the option specifies that special MBX
locking rules be used. It is set by default if <span><strong class="option">mbx_format</strong></span> is set and none
of the locking options are mentioned in the configuration. The locking rules
are the same as are used by the <span class="emphasis"><em>c-client</em></span> library that underlies Pine and
the IMAP4 and POP daemons that come with it (see the discussion below). The
rules allow for shared access to the mailbox. However, this kind of locking
does not work when the mailbox is NFS mounted.
</p>
<p>
You can set <span><strong class="option">use_mbx_lock</strong></span> with either (or both) of <span><strong class="option">use_fcntl_lock</strong></span> and
<span><strong class="option">use_flock_lock</strong></span> to control what kind of locking is used in implementing the
MBX locking rules. The default is to use <em class="function">fcntl()</em> if <span><strong class="option">use_mbx_lock</strong></span> is set
without <span><strong class="option">use_fcntl_lock</strong></span> or <span><strong class="option">use_flock_lock</strong></span>.
</p>
</div>
<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#toc0225" id="SECTopappend">26.3 Operational details for appending</a></h3></div>
</div>
</div>
<p>
<a id="id593437" class="indexterm"></a>
<a id="id593448" class="indexterm"></a>
Before appending to a file, the following preparations are made:
</p>
<div class="itemizedlist">
<ul type="disc"><li><p>
If the name of the file is <em class="filename">/dev/null</em>, no action is taken, and a success
return is given.
</p>
</li><li><p>
<a id="id593485" class="indexterm"></a>
If any directories on the file’s path are missing, Exim creates them if the
<span><strong class="option">create_directory</strong></span> option is set. A created directory’s mode is given by the
<span><strong class="option">directory_mode</strong></span> option.
</p>
</li><li><p>
If <span><strong class="option">file_format</strong></span> is set, the format of an existing file is checked. If this
indicates that a different transport should be used, control is passed to that
transport.
</p>
</li><li><p>
<a id="id593529" class="indexterm"></a>
<a id="id593543" class="indexterm"></a>
<a id="id593554" class="indexterm"></a>
If <span><strong class="option">use_lockfile</strong></span> is set, a lock file is built in a way that will work
reliably over NFS, as follows:
</p>
<div class="orderedlist">
<ol type="1"><li><p>
Create a “<span class="quote">hitching post</span>” file whose name is that of the lock file with the
current time, primary host name, and process id added, by opening for writing
as a new file. If this fails with an access error, delivery is deferred.
</p>
</li><li><p>
Close the hitching post file, and hard link it to the lock file name.
</p>
</li><li><p>
If the call to <em class="function">link()</em> succeeds, creation of the lock file has succeeded.
Unlink the hitching post name.
</p>
</li><li><p>
Otherwise, use <em class="function">stat()</em> to get information about the hitching post file, and
then unlink hitching post name. If the number of links is exactly two, creation
of the lock file succeeded but something (for example, an NFS server crash and
restart) caused this fact not to be communicated to the <em class="function">link()</em> call.
</p>
</li><li><p>
If creation of the lock file failed, wait for <span><strong class="option">lock_interval</strong></span> and try again,
up to <span><strong class="option">lock_retries</strong></span> times. However, since any program that writes to a
mailbox should complete its task very quickly, it is reasonable to time out old
lock files that are normally the result of user agent and system crashes. If an
existing lock file is older than <span><strong class="option">lockfile_timeout</strong></span> Exim attempts to unlink
it before trying again.
</p>
</li></ol></div>
</li><li><p>
A call is made to <em class="function">lstat()</em> to discover whether the main file exists, and if
so, what its characteristics are. If <em class="function">lstat()</em> fails for any reason other
than non-existence, delivery is deferred.
</p>
</li><li><p>
<a id="id593692" class="indexterm"></a>
<a id="id593707" class="indexterm"></a>
If the file does exist and is a symbolic link, delivery is deferred, unless the
<span><strong class="option">allow_symlink</strong></span> option is set, in which case the ownership of the link is
checked, and then <em class="function">stat()</em> is called to find out about the real file, which
is then subjected to the checks below. The check on the top-level link
ownership prevents one user creating a link for another’s mailbox in a sticky
directory, though allowing symbolic links in this case is definitely not a good
idea. If there is a chain of symbolic links, the intermediate ones are not
checked.
</p>
</li><li><p>
If the file already exists but is not a regular file, or if the file’s owner
and group (if the group is being checked – see <span><strong class="option">check_group</strong></span> above) are
different from the user and group under which the delivery is running,
delivery is deferred.
</p>
</li><li><p>
If the file’s permissions are more generous than specified, they are reduced.
If they are insufficient, delivery is deferred, unless <span><strong class="option">mode_fail_narrower</strong></span>
is set false, in which case the delivery is tried using the existing
permissions.
</p>
</li><li><p>
The file’s inode number is saved, and the file is then opened for appending.
If this fails because the file has vanished, <span><strong class="command">appendfile</strong></span> behaves as if it
hadn’t existed (see below). For any other failures, delivery is deferred.
</p>
</li><li><p>
If the file is opened successfully, check that the inode number hasn’t
changed, that it is still a regular file, and that the owner and permissions
have not changed. If anything is wrong, defer delivery and freeze the message.
</p>
</li><li><p>
If the file did not exist originally, defer delivery if the <span><strong class="option">file_must_exist</strong></span>
option is set. Otherwise, check that the file is being created in a permitted
directory if the <span><strong class="option">create_file</strong></span> option is set (deferring on failure), and then
open for writing as a new file, with the O_EXCL and O_CREAT options,
except when dealing with a symbolic link (the <span><strong class="option">allow_symlink</strong></span> option must be
set). In this case, which can happen if the link points to a non-existent file,
the file is opened for writing using O_CREAT but not O_EXCL, because
that prevents link following.
</p>
</li><li><p>
<a id="id593827" class="indexterm"></a>
If opening fails because the file exists, obey the tests given above for
existing files. However, to avoid looping in a situation where the file is
being continuously created and destroyed, the exists/not-exists loop is broken
after 10 repetitions, and the message is then frozen.
</p>
</li><li><p>
If opening fails with any other error, defer delivery.
</p>
</li><li><p>
<a id="id593861" class="indexterm"></a>
<a id="id593875" class="indexterm"></a>
Once the file is open, unless both <span><strong class="option">use_fcntl_lock</strong></span> and <span><strong class="option">use_flock_lock</strong></span>
are false, it is locked using <em class="function">fcntl()</em> or <em class="function">flock()</em> or both. If
<span><strong class="option">use_mbx_lock</strong></span> is false, an exclusive lock is requested in each case.
However, if <span><strong class="option">use_mbx_lock</strong></span> is true, Exim takes out a shared lock on the open
file, and an exclusive lock on the file whose name is
</p>
<pre class="literallayout">/tmp/.<device-number>.<inode-number>
</pre><p>
using the device and inode numbers of the open mailbox file, in accordance with
the MBX locking rules. This file is created with a mode that is specified by
the <span><strong class="option">lockfile_mode</strong></span> option.
</p>
<p>
If Exim fails to lock the file, there are two possible courses of action,
depending on the value of the locking timeout. This is obtained from
<span><strong class="option">lock_fcntl_timeout</strong></span> or <span><strong class="option">lock_flock_timeout</strong></span>, as appropriate.
</p>
<p>
If the timeout value is zero, the file is closed, Exim waits for
<span><strong class="option">lock_interval</strong></span>, and then goes back and re-opens the file as above and tries
to lock it again. This happens up to <span><strong class="option">lock_retries</strong></span> times, after which the
delivery is deferred.
</p>
<p>
If the timeout has a value greater than zero, blocking calls to <em class="function">fcntl()</em> or
<em class="function">flock()</em> are used (with the given timeout), so there has already been some
waiting involved by the time locking fails. Nevertheless, Exim does not give up
immediately. It retries up to
</p>
<pre class="literallayout">(lock_retries * lock_interval) / <timeout>
</pre><p>
times (rounded up).
</p>
</li></ul></div>
<p>
At the end of delivery, Exim closes the file (which releases the <em class="function">fcntl()</em>
and/or <em class="function">flock()</em> locks) and then deletes the lock file if one was created.
</p>
</div>
<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#toc0226" id="SECTopdir">26.4 Operational details for delivery to a new file</a></h3></div>
</div>
</div>
<p>
<a id="id594296" class="indexterm"></a>
<a id="id594310" class="indexterm"></a>
When the <span><strong class="option">directory</strong></span> option is set instead of <span><strong class="option">file</strong></span>, each message is
delivered into a newly-created file or set of files. When <span><strong class="command">appendfile</strong></span> is
activated directly from a <span><strong class="command">redirect</strong></span> router, neither <span><strong class="option">file</strong></span> nor
<span><strong class="option">directory</strong></span> is normally set, because the path for delivery is supplied by the
router. (See for example, the <span><strong class="command">address_file</strong></span> transport in the default
configuration.) In this case, delivery is to a new file if either the path name
ends in <code class="literal">/</code>, or the <span><strong class="option">maildir_format</strong></span> or <span><strong class="option">mailstore_format</strong></span> option is set.
</p>
<p>
No locking is required while writing the message to a new file, so the various
locking options of the transport are ignored. The “<span class="quote">From</span>” line that by default
separates messages in a single file is not normally needed, nor is the escaping
of message lines that start with “<span class="quote">From</span>”, and there is no need to ensure a
newline at the end of each message. Consequently, the default values for
<span><strong class="option">check_string</strong></span>, <span><strong class="option">message_prefix</strong></span>, and <span><strong class="option">message_suffix</strong></span> are all unset when
any of <span><strong class="option">directory</strong></span>, <span><strong class="option">maildir_format</strong></span>, or <span><strong class="option">mailstore_format</strong></span> is set.
</p>
<p>
If Exim is required to check a <span><strong class="option">quota</strong></span> setting, it adds up the sizes of all
the files in the delivery directory by default. However, you can specify a
different directory by setting <span><strong class="option">quota_directory</strong></span>. Also, for maildir
deliveries (see below) the <em class="filename">maildirfolder</em> convention is honoured.
</p>
<p>
<a id="id594438" class="indexterm"></a>
<a id="id594449" class="indexterm"></a>
There are three different ways in which delivery to individual files can be
done, controlled by the settings of the <span><strong class="option">maildir_format</strong></span> and
<span><strong class="option">mailstore_format</strong></span> options. Note that code to support maildir or mailstore
formats is not included in the binary unless SUPPORT_MAILDIR or
SUPPORT_MAILSTORE, respectively, is set in <em class="filename">Local/Makefile</em>.
</p>
<p>
<a id="id594482" class="indexterm"></a>
In all three cases an attempt is made to create the directory and any necessary
sub-directories if they do not exist, provided that the <span><strong class="option">create_directory</strong></span>
option is set (the default). The location of a created directory can be
constrained by setting <span><strong class="option">create_file</strong></span>. A created directory’s mode is given by
the <span><strong class="option">directory_mode</strong></span> option. If creation fails, or if the
<span><strong class="option">create_directory</strong></span> option is not set when creation is required, delivery is
deferred.
</p>
</div>
<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#toc0227" id="SECTmaildirdelivery">26.5 Maildir delivery</a></h3></div>
</div>
</div>
<p>
<a id="id594529" class="indexterm"></a>
If the <span><strong class="option">maildir_format</strong></span> option is true, Exim delivers each message by writing
it to a file whose name is <em class="filename">tmp/<stime>.H<mtime>P<pid>.<host></em> in the
directory that is defined by the <span><strong class="option">directory</strong></span> option (the “<span class="quote">delivery
directory</span>”). If the delivery is successful, the file is renamed into the
<em class="filename">new</em> subdirectory.
</p>
<p>
In the file name, <<span class="emphasis"><em>stime</em></span>> is the current time of day in seconds, and
<<span class="emphasis"><em>mtime</em></span>> is the microsecond fraction of the time. After a maildir delivery,
Exim checks that the time-of-day clock has moved on by at least one microsecond
before terminating the delivery process. This guarantees uniqueness for the
file name. However, as a precaution, Exim calls <em class="function">stat()</em> for the file before
opening it. If any response other than ENOENT (does not exist) is given,
Exim waits 2 seconds and tries again, up to <span><strong class="option">maildir_retries</strong></span> times.
</p>
<p>
Before Exim carries out a maildir delivery, it ensures that subdirectories
called <em class="filename">new</em>, <em class="filename">cur</em>, and <em class="filename">tmp</em> exist in the delivery directory. If they
do not exist, Exim tries to create them and any superior directories in their
path, subject to the <span><strong class="option">create_directory</strong></span> and <span><strong class="option">create_file</strong></span> options. If the
<span><strong class="option">maildirfolder_create_regex</strong></span> option is set, and the regular expression it
contains matches the delivery directory, Exim also ensures that a file called
<em class="filename">maildirfolder</em> exists in the delivery directory. If a missing directory or
<em class="filename">maildirfolder</em> file cannot be created, delivery is deferred.
</p>
<p>
These features make it possible to use Exim to create all the necessary files
and directories in a maildir mailbox, including subdirectories for maildir++
folders. Consider this example:
</p>
<pre class="literallayout">maildir_format = true
directory = /var/mail/$local_part\
${if eq{$local_part_suffix}{}{}\
{/.${substr_1:$local_part_suffix}}}
maildirfolder_create_regex = /\.[^/]+$
</pre><p>
If <em class="varname">$local_part_suffix</em> is empty (there was no suffix for the local part),
delivery is into a toplevel maildir with a name like <em class="filename">/var/mail/pimbo</em> (for
the user called <span class="emphasis"><em>pimbo</em></span>). The pattern in <span><strong class="option">maildirfolder_create_regex</strong></span> does
not match this name, so Exim will not look for or create the file
<em class="filename">/var/mail/pimbo/maildirfolder</em>, though it will create
<em class="filename">/var/mail/pimbo/{cur,new,tmp}</em> if necessary.
</p>
<p>
However, if <em class="varname">$local_part_suffix</em> contains <code class="literal">-eximusers</code> (for example),
delivery is into the maildir++ folder <em class="filename">/var/mail/pimbo/.eximusers</em>, which
does match <span><strong class="option">maildirfolder_create_regex</strong></span>. In this case, Exim will create
<em class="filename">/var/mail/pimbo/.eximusers/maildirfolder</em> as well as the three maildir
directories <em class="filename">/var/mail/pimbo/.eximusers/{cur,new,tmp}</em>.
</p>
<p>
<span class="bold"><strong>Warning:</strong></span> Take care when setting <span><strong class="option">maildirfolder_create_regex</strong></span> that it does
not inadvertently match the toplevel maildir directory, because a
<em class="filename">maildirfolder</em> file at top level would completely break quota calculations.
</p>
<p>
<a id="id594761" class="indexterm"></a>
<a id="id594776" class="indexterm"></a>
If Exim is required to check a <span><strong class="option">quota</strong></span> setting before a maildir delivery, and
<span><strong class="option">quota_directory</strong></span> is not set, it looks for a file called <em class="filename">maildirfolder</em> in
the maildir directory (alongside <em class="filename">new</em>, <em class="filename">cur</em>, <em class="filename">tmp</em>). If this exists,
Exim assumes the directory is a maildir++ folder directory, which is one level
down from the user’s top level mailbox directory. This causes it to start at
the parent directory instead of the current directory when calculating the
amount of space used.
</p>
<p>
One problem with delivering into a multi-file mailbox is that it is
computationally expensive to compute the size of the mailbox for quota
checking. Various approaches have been taken to reduce the amount of work
needed. The next two sections describe two of them. A third alternative is to
use some external process for maintaining the size data, and use the expansion
of the <span><strong class="option">mailbox_size</strong></span> option as a way of importing it into Exim.
</p>
</div>
<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#toc0228" id="SECID135">26.6 Using tags to record message sizes</a></h3></div>
</div>
</div>
<p>
If <span><strong class="option">maildir_tag</strong></span> is set, the string is expanded for each delivery.
When the maildir file is renamed into the <em class="filename">new</em> sub-directory, the
tag is added to its name. However, if adding the tag takes the length of the
name to the point where the test <em class="function">stat()</em> call fails with ENAMETOOLONG,
the tag is dropped and the maildir file is created with no tag.
</p>
<p>
<a id="id594870" class="indexterm"></a>
Tags can be used to encode the size of files in their names; see
<span><strong class="option">quota_size_regex</strong></span> above for an example. The expansion of <span><strong class="option">maildir_tag</strong></span>
happens after the message has been written. The value of the <em class="varname">$message_size</em>
variable is set to the number of bytes actually written. If the expansion is
forced to fail, the tag is ignored, but a non-forced failure causes delivery to
be deferred. The expanded tag may contain any printing characters except “<span class="quote">/</span>”.
Non-printing characters in the string are ignored; if the resulting string is
empty, it is ignored. If it starts with an alphanumeric character, a leading
colon is inserted.
</p>
</div>
<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#toc0229" id="SECID136">26.7 Using a maildirsize file</a></h3></div>
</div>
</div>
<p>
<a id="id594920" class="indexterm"></a>
<a id="id594934" class="indexterm"></a>
If <span><strong class="option">maildir_use_size_file</strong></span> is true, Exim implements the maildir++ rules for
storing quota and message size information in a file called <em class="filename">maildirsize</em>
within the toplevel maildir directory. If this file does not exist, Exim
creates it, setting the quota from the <span><strong class="option">quota</strong></span> option of the transport. If
the maildir directory itself does not exist, it is created before any attempt
to write a <em class="filename">maildirsize</em> file.
</p>
<p>
The <em class="filename">maildirsize</em> file is used to hold information about the sizes of
messages in the maildir, thus speeding up quota calculations. The quota value
in the file is just a cache; if the quota is changed in the transport, the new
value overrides the cached value when the next message is delivered. The cache
is maintained for the benefit of other programs that access the maildir and
need to know the quota.
</p>
<p>
If the <span><strong class="option">quota</strong></span> option in the transport is unset or zero, the <em class="filename">maildirsize</em>
file is maintained (with a zero quota setting), but no quota is imposed.
</p>
<p>
A regular expression is available for controlling which directories in the
maildir participate in quota calculations when a <em class="filename">maildirsizefile</em> is in use.
See the description of the <span><strong class="option">maildir_quota_directory_regex</strong></span> option above for
details.
</p>
</div>
<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#toc0230" id="SECID137">26.8 Mailstore delivery</a></h3></div>
</div>
</div>
<p>
<a id="id595039" class="indexterm"></a>
If the <span><strong class="option">mailstore_format</strong></span> option is true, each message is written as two
files in the given directory. A unique base name is constructed from the
message id and the current delivery process, and the files that are written use
this base name plus the suffixes <em class="filename">.env</em> and <em class="filename">.msg</em>. The <em class="filename">.env</em> file
contains the message’s envelope, and the <em class="filename">.msg</em> file contains the message
itself. The base name is placed in the variable <em class="varname">$mailstore_basename</em>.
</p>
<p>
During delivery, the envelope is first written to a file with the suffix
<em class="filename">.tmp</em>. The <em class="filename">.msg</em> file is then written, and when it is complete, the
<em class="filename">.tmp</em> file is renamed as the <em class="filename">.env</em> file. Programs that access messages in
mailstore format should wait for the presence of both a <em class="filename">.msg</em> and a <em class="filename">.env</em>
file before accessing either of them. An alternative approach is to wait for
the absence of a <em class="filename">.tmp</em> file.
</p>
<p>
The envelope file starts with any text defined by the <span><strong class="option">mailstore_prefix</strong></span>
option, expanded and terminated by a newline if there isn’t one. Then follows
the sender address on one line, then all the recipient addresses, one per line.
There can be more than one recipient only if the <span><strong class="option">batch_max</strong></span> option is set
greater than one. Finally, <span><strong class="option">mailstore_suffix</strong></span> is expanded and the result
appended to the file, followed by a newline if it does not end with one.
</p>
<p>
If expansion of <span><strong class="option">mailstore_prefix</strong></span> or <span><strong class="option">mailstore_suffix</strong></span> ends with a forced
failure, it is ignored. Other expansion errors are treated as serious
configuration errors, and delivery is deferred. The variable
<em class="varname">$mailstore_basename</em> is available for use during these expansions.
</p>
</div>
<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#toc0231" id="SECID138">26.9 Non-special new file delivery</a></h3></div>
</div>
</div>
<p>
If neither <span><strong class="option">maildir_format</strong></span> nor <span><strong class="option">mailstore_format</strong></span> is set, a single new
file is created directly in the named directory. For example, when delivering
messages into files in batched SMTP format for later delivery to some host (see
section <a href="ch45.html#SECTbatchSMTP" title="45.10 Outgoing batched SMTP">45.10</a>), a setting such as
</p>
<pre class="literallayout">directory = /var/bsmtp/$host
</pre><p>
might be used. A message is written to a file with a temporary name, which is
then renamed when the delivery is complete. The final name is obtained by
expanding the contents of the <span><strong class="option">directory_file</strong></span> option.
<a id="id595225" class="indexterm"></a>
<a id="id595238" 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="ch25.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="ch27.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>
