<!DOCTYPE html PUBLIC "XSLT-compat"> <html lang="en-GB"> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> <link rel="stylesheet" type="text/css" href="../../../../common.css"> <meta name="author" content="The Exim Project. <http://www.exim.org/>"> <meta name="copyright" content="Copyright ©2010 The Exim Project. All rights reserved"> <meta name="description" content="Exim is a message transfer agent (MTA) developed at the University of Cambridge for use on Unix systems connected to the Internet."> <meta name="keywords" content="exim,smtp,mta,email"> <meta name="robots" content="noodp,noydir,index,follow"> <meta name="viewport" content="width=device-width"> <title>26. The appendfile transport</title> <link rel="stylesheet" type="text/css" href="../../../../doc/chapter.css"> <link rel="canonical" href="http://www.exim.org/exim-html-current/doc/html/spec_html/ch26.html"> </head> <body> <h1 id="header"><a href="../../../..">Exim Internet Mailer</a></h1> <div id="outer"> <ul id="nav_flow" class="nav"> <li><a href="../../../../index.html">Home</a></li> <li><a href="../../../../mirrors.html">Download</a></li> <li><a href="../../../../docs.html">Documentation</a></li> <li><a href="../../../../maillist.html">Mailing Lists</a></li> <li><a href="http://wiki.exim.org/">Wiki</a></li> <li><a href="http://www.exim.org/bugzilla/">Bugs</a></li> <li><a href="../../../../credits.html">Credits</a></li> <li class="search"><form action="http://www.google.com/search" method="get"> <span class="search_field_container"><input type="search" name="q" placeholder="Search Docs" class="search_field"></span><input type="hidden" name="hl" value="en"><input type="hidden" name="ie" value="UTF-8"><input type="hidden" name="as_qdr" value="all"><input type="hidden" name="q" value="site:www.exim.org"><input type="hidden" name="q" value="inurl:exim-html-current"> </form></li> </ul> <div id="inner"><div id="content"> <a class="previous_page" href="ch25.html"><-previous</a><a class="next_page" href="ch27.html">next-></a><div id="chapter" class="chapter"> <h2 id="CHAPappendfile" class="">Chapter 26 - The appendfile transport</h2> <p> The <span class="docbook_command">appendfile</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="docbook_emphasis">inter alia</span>. When each message is being delivered as a separate file, “maildir” 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 “mailstore” is also supported. For all file formats, Exim attempts to create as many levels of directory as necessary, provided that <span class="docbook_option">create_directory</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 <span class="docbook_filename">Local/Makefile</span> to have the appropriate code included. </p> <p> 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 class="docbook_command">appendfile</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. “Batch SMTP” format is often used in this case (see the <span class="docbook_option">use_bsmtp</span> option). </p> <div class="section"> <h3 id="SECTfildiropt" class="">1. The file and directory options</h3> <p> The <span class="docbook_option">file</span> option specifies a single file, to which the message is appended; the <span class="docbook_option">directory</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="docbook_emphasis">must</span> be set. </p> <p> However, <span class="docbook_command">appendfile</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 class="docbook_option">save</span> command in a user’s Exim filter). When such a transport is running, $local_part contains the local part that was aliased or forwarded, and $address_file contains the name (or partial name) of the file or directory generated by the redirection operation. There are two cases: </p> <ul> <li> <p> If neither <span class="docbook_option">file</span> nor <span class="docbook_option">directory</span> is set, the redirection operation must specify an absolute path (one that begins with <code class="docbook_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 class="docbook_command">address_file</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 class="docbook_option">maildir_format</span> or <span class="docbook_option">mailstore_format</span>. </p> </li> <li> <p> If <span class="docbook_option">file</span> or <span class="docbook_option">directory</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 $address_file are used in some way in the string expansion. </p> </li> </ul> <p> 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> <div class="docbook_literallayout"><pre> save folder23 </pre></div> <p> or Sieve filter commands of the form: </p> <div class="docbook_literallayout"><pre> require "fileinto"; fileinto "folder23"; </pre></div> <p> In this situation, the expansion of <span class="docbook_option">file</span> or <span class="docbook_option">directory</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="docbook_emphasis">inbox</span> must be handled. It is the name that is used as a result of a “keep” action in the filter. This example shows one way of handling this requirement: </p> <div class="docbook_literallayout"><pre> file = ${if eq{$address_file}{inbox} \ {/var/mail/$local_part} \ {${if eq{${substr_0_1:$address_file}}{/} \ {$address_file} \ {$home/mail/$address_file} \ }} \ } </pre></div> <p> With this setting of <span class="docbook_option">file</span>, <span class="docbook_emphasis">inbox</span> refers to the standard mailbox location, absolute paths are used without change, and other folders are in the <span class="docbook_filename">mail</span> directory within the home directory. </p> <p> <span class="docbook_emphasis">Note 1</span>: While processing an Exim filter, a relative path such as <span class="docbook_filename">folder23</span> is turned into an absolute path if a home directory is known to the router. In particular, this is the case if <span class="docbook_option">check_local_user</span> is set. If you want to prevent this happening at routing time, you can set <span class="docbook_option">router_home_directory</span> empty. This forces the router to pass the relative path to the transport. </p> <p> <span class="docbook_emphasis">Note 2</span>: An absolute path in $address_file is not treated specially; the <span class="docbook_option">file</span> or <span class="docbook_option">directory</span> option is still used if it is set. </p> </div> <div class="section"> <h3 id="SECID134" class="">2. Private options for appendfile</h3> <p> </p> <p> </p> <table> <tr> <td><span class="docbook_option">allow_fifo</span></td> <td>Use: <span class="docbook_emphasis">appendfile</span> </td> <td>Type: <span class="docbook_emphasis">boolean</span> </td> <td>Default: <span class="docbook_emphasis">false</span> </td> </tr> </table> <p> 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> </p> <table> <tr> <td><span class="docbook_option">allow_symlink</span></td> <td>Use: <span class="docbook_emphasis">appendfile</span> </td> <td>Type: <span class="docbook_emphasis">boolean</span> </td> <td>Default: <span class="docbook_emphasis">false</span> </td> </tr> </table> <p> By default, <span class="docbook_command">appendfile</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> </p> <table> <tr> <td><span class="docbook_option">batch_id</span></td> <td>Use: <span class="docbook_emphasis">appendfile</span> </td> <td>Type: <span class="docbook_emphasis">string</span>†<span class="docbook_emphasis"></span> </td> <td>Default: <span class="docbook_emphasis">unset</span> </td> </tr> </table> <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 class="docbook_command">appendfile</span> deliveries that happen as a result of forwarding or aliasing or other redirection directly to a file. </p> <p> </p> <table> <tr> <td><span class="docbook_option">batch_max</span></td> <td>Use: <span class="docbook_emphasis">appendfile</span> </td> <td>Type: <span class="docbook_emphasis">integer</span> </td> <td>Default: <span class="docbook_emphasis">1</span> </td> </tr> </table> <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> </p> <table> <tr> <td><span class="docbook_option">check_group</span></td> <td>Use: <span class="docbook_emphasis">appendfile</span> </td> <td>Type: <span class="docbook_emphasis">boolean</span> </td> <td>Default: <span class="docbook_emphasis">false</span> </td> </tr> </table> <p> When this option is set, the group owner of the file defined by the <span class="docbook_option">file</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> </p> <table> <tr> <td><span class="docbook_option">check_owner</span></td> <td>Use: <span class="docbook_emphasis">appendfile</span> </td> <td>Type: <span class="docbook_emphasis">boolean</span> </td> <td>Default: <span class="docbook_emphasis">true</span> </td> </tr> </table> <p> When this option is set, the owner of the file defined by the <span class="docbook_option">file</span> option is checked to ensure that it is the same as the user under which the delivery process is running. </p> <p> </p> <table> <tr> <td><span class="docbook_option">check_string</span></td> <td>Use: <span class="docbook_emphasis">appendfile</span> </td> <td>Type: <span class="docbook_emphasis">string</span> </td> <td>Default: <span class="docbook_emphasis">see below</span> </td> </tr> </table> <p> As <span class="docbook_command">appendfile</span> writes the message, the start of each line is tested for matching <span class="docbook_option">check_string</span>, and if it does, the initial matching characters are replaced by the contents of <span class="docbook_option">escape_string</span>. The value of <span class="docbook_option">check_string</span> is a literal string, not a regular expression, and the case of any letters it contains is significant. </p> <p> If <span class="docbook_option">use_bsmtp</span> is set the values of <span class="docbook_option">check_string</span> and <span class="docbook_option">escape_string</span> are forced to “.” and “..” respectively, and any settings in the configuration are ignored. Otherwise, they default to “From ” and “>From ” when the <span class="docbook_option">file</span> option is set, and unset when any of the <span class="docbook_option">directory</span>, <span class="docbook_option">maildir</span>, or <span class="docbook_option">mailstore</span> options are set. </p> <p> The default settings, along with <span class="docbook_option">message_prefix</span> and <span class="docbook_option">message_suffix</span>, are suitable for traditional “BSD” mailboxes, where a line beginning with “From ” 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: </p> <div class="docbook_literallayout"><pre> 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></div> <p> </p> <table> <tr> <td><span class="docbook_option">create_directory</span></td> <td>Use: <span class="docbook_emphasis">appendfile</span> </td> <td>Type: <span class="docbook_emphasis">boolean</span> </td> <td>Default: <span class="docbook_emphasis">true</span> </td> </tr> </table> <p> 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 class="docbook_option">directory_mode</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> </p> <table> <tr> <td><span class="docbook_option">create_file</span></td> <td>Use: <span class="docbook_emphasis">appendfile</span> </td> <td>Type: <span class="docbook_emphasis">string</span> </td> <td>Default: <span class="docbook_emphasis">anywhere</span> </td> </tr> </table> <p> This option constrains the location of files and directories that are created by this transport. It applies to files defined by the <span class="docbook_option">file</span> option and directories defined by the <span class="docbook_option">directory</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 “anywhere”, “inhome”, or “belowhome”. 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’ <span class="docbook_filename">.forward</span> files. These are usually handled by an <span class="docbook_command">appendfile</span> transport called <span class="docbook_option">address_file</span>. See also <span class="docbook_option">file_must_exist</span>. </p> <p> </p> <table> <tr> <td><span class="docbook_option">directory</span></td> <td>Use: <span class="docbook_emphasis">appendfile</span> </td> <td>Type: <span class="docbook_emphasis">string</span>†<span class="docbook_emphasis"></span> </td> <td>Default: <span class="docbook_emphasis">unset</span> </td> </tr> </table> <p> This option is mutually exclusive with the <span class="docbook_option">file</span> option, but one of <span class="docbook_option">file</span> or <span class="docbook_option">directory</span> must be set, unless the delivery is the direct result of a redirection (see section <a href="ch26.html#SECTfildiropt" title="26. The appendfile transport">26.1</a>). </p> <p> When <span class="docbook_option">directory</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 class="docbook_option">maildir_format</span> and <span class="docbook_option">mailstore_format</span>), and see section <a href="ch26.html#SECTopdir" title="26. The appendfile transport">26.4</a> for further details of this form of delivery. </p> <p> </p> <table> <tr> <td><span class="docbook_option">directory_file</span></td> <td>Use: <span class="docbook_emphasis">appendfile</span> </td> <td>Type: <span class="docbook_emphasis">string</span>†<span class="docbook_emphasis"></span> </td> <td>Default: <span class="docbook_emphasis">see below</span> </td> </tr> </table> <p> When <span class="docbook_option">directory</span> is set, but neither <span class="docbook_option">maildir_format</span> nor <span class="docbook_option">mailstore_format</span> is set, <span class="docbook_command">appendfile</span> delivers each message into a file whose name is obtained by expanding this string. The default value is: </p> <div class="docbook_literallayout"><pre> q${base62:$tod_epoch}-$inode </pre></div> <p> This generates a unique name from the current time, in base 62 form, and the inode of the file. The variable $inode is available only when expanding this option. </p> <p> </p> <table> <tr> <td><span class="docbook_option">directory_mode</span></td> <td>Use: <span class="docbook_emphasis">appendfile</span> </td> <td>Type: <span class="docbook_emphasis">octal integer</span> </td> <td>Default: <span class="docbook_emphasis">0700</span> </td> </tr> </table> <p> If <span class="docbook_command">appendfile</span> creates any directories as a result of the <span class="docbook_option">create_directory</span> option, their mode is specified by this option. </p> <p> </p> <table> <tr> <td><span class="docbook_option">escape_string</span></td> <td>Use: <span class="docbook_emphasis">appendfile</span> </td> <td>Type: <span class="docbook_emphasis">string</span> </td> <td>Default: <span class="docbook_emphasis">see description</span> </td> </tr> </table> <p> See <span class="docbook_option">check_string</span> above. </p> <p> </p> <table> <tr> <td><span class="docbook_option">file</span></td> <td>Use: <span class="docbook_emphasis">appendfile</span> </td> <td>Type: <span class="docbook_emphasis">string</span>†<span class="docbook_emphasis"></span> </td> <td>Default: <span class="docbook_emphasis">unset</span> </td> </tr> </table> <p> This option is mutually exclusive with the <span class="docbook_option">directory</span> option, but one of <span class="docbook_option">file</span> or <span class="docbook_option">directory</span> must be set, unless the delivery is the direct result of a redirection (see section <a href="ch26.html#SECTfildiropt" title="26. The appendfile transport">26.1</a>). The <span class="docbook_option">file</span> option specifies a single file, to which the message is appended. One or more of <span class="docbook_option">use_fcntl_lock</span>, <span class="docbook_option">use_flock_lock</span>, or <span class="docbook_option">use_lockfile</span> must be set with <span class="docbook_option">file</span>. </p> <p> 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> <div class="docbook_literallayout"><pre> file = /var/spool/mail/$local_part file = /home/$local_part/inbox file = $home/inbox </pre></div> <p> In the first example, all deliveries are done into the same directory. If Exim is configured to use lock files (see <span class="docbook_option">use_lockfile</span> below) it must be able to create a file in the directory, so the “sticky” bit must be turned on for deliveries to be possible, or alternatively the <span class="docbook_option">group</span> option can be used to run the delivery under a group id which has write access to the directory. </p> <p> </p> <table> <tr> <td><span class="docbook_option">file_format</span></td> <td>Use: <span class="docbook_emphasis">appendfile</span> </td> <td>Type: <span class="docbook_emphasis">string</span> </td> <td>Default: <span class="docbook_emphasis">unset</span> </td> </tr> </table> <p> 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 class="docbook_command">local_delivery</span> transport has this added to it: </p> <div class="docbook_literallayout"><pre> file_format = "From : local_delivery :\ \1\1\1\1\n : local_mmdf_delivery" </pre></div> <p> Mailboxes that begin with “From” 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 class="docbook_option">local_mmdf_delivery</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> </p> <table> <tr> <td><span class="docbook_option">file_must_exist</span></td> <td>Use: <span class="docbook_emphasis">appendfile</span> </td> <td>Type: <span class="docbook_emphasis">boolean</span> </td> <td>Default: <span class="docbook_emphasis">false</span> </td> </tr> </table> <p> If this option is true, the file specified by the <span class="docbook_option">file</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> </p> <table> <tr> <td><span class="docbook_option">lock_fcntl_timeout</span></td> <td>Use: <span class="docbook_emphasis">appendfile</span> </td> <td>Type: <span class="docbook_emphasis">time</span> </td> <td>Default: <span class="docbook_emphasis">0s</span> </td> </tr> </table> <p> By default, the <span class="docbook_command">appendfile</span> transport uses non-blocking calls to <span class="docbook_function">fcntl()</span> when locking an open mailbox file. If the call fails, the delivery process sleeps for <span class="docbook_option">lock_interval</span> and tries again, up to <span class="docbook_option">lock_retries</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 class="docbook_option">lock_fcntl_timeout</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> <div class="docbook_literallayout"><pre> (lock_retries * lock_interval) / lock_fcntl_timeout </pre></div> <p> rounded up to the next whole number. In other words, the total time during which <span class="docbook_command">appendfile</span> is trying to get a lock is roughly the same, unless <span class="docbook_option">lock_fcntl_timeout</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> <div class="docbook_literallayout"><pre> failed to lock mailbox /some/file (fcntl) </pre></div> <p> </p> <table> <tr> <td><span class="docbook_option">lock_flock_timeout</span></td> <td>Use: <span class="docbook_emphasis">appendfile</span> </td> <td>Type: <span class="docbook_emphasis">time</span> </td> <td>Default: <span class="docbook_emphasis">0s</span> </td> </tr> </table> <p> This timeout applies to file locking when using <span class="docbook_function">flock()</span> (see <span class="docbook_option">use_flock</span>); the timeout operates in a similar manner to <span class="docbook_option">lock_fcntl_timeout</span>. </p> <p> </p> <table> <tr> <td><span class="docbook_option">lock_interval</span></td> <td>Use: <span class="docbook_emphasis">appendfile</span> </td> <td>Type: <span class="docbook_emphasis">time</span> </td> <td>Default: <span class="docbook_emphasis">3s</span> </td> </tr> </table> <p> This specifies the time to wait between attempts to lock the file. See below for details of locking. </p> <p> </p> <table> <tr> <td><span class="docbook_option">lock_retries</span></td> <td>Use: <span class="docbook_emphasis">appendfile</span> </td> <td>Type: <span class="docbook_emphasis">integer</span> </td> <td>Default: <span class="docbook_emphasis">10</span> </td> </tr> </table> <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> </p> <table> <tr> <td><span class="docbook_option">lockfile_mode</span></td> <td>Use: <span class="docbook_emphasis">appendfile</span> </td> <td>Type: <span class="docbook_emphasis">octal integer</span> </td> <td>Default: <span class="docbook_emphasis">0600</span> </td> </tr> </table> <p> This specifies the mode of the created lock file, when a lock file is being used (see <span class="docbook_option">use_lockfile</span> and <span class="docbook_option">use_mbx_lock</span>). </p> <p> </p> <table> <tr> <td><span class="docbook_option">lockfile_timeout</span></td> <td>Use: <span class="docbook_emphasis">appendfile</span> </td> <td>Type: <span class="docbook_emphasis">time</span> </td> <td>Default: <span class="docbook_emphasis">30m</span> </td> </tr> </table> <p> When a lock file is being used (see <span class="docbook_option">use_lockfile</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> </p> <table> <tr> <td><span class="docbook_option">mailbox_filecount</span></td> <td>Use: <span class="docbook_emphasis">appendfile</span> </td> <td>Type: <span class="docbook_emphasis">string</span>†<span class="docbook_emphasis"></span> </td> <td>Default: <span class="docbook_emphasis">unset</span> </td> </tr> </table> <p> 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> </p> <table> <tr> <td><span class="docbook_option">mailbox_size</span></td> <td>Use: <span class="docbook_emphasis">appendfile</span> </td> <td>Type: <span class="docbook_emphasis">string</span>†<span class="docbook_emphasis"></span> </td> <td>Default: <span class="docbook_emphasis">unset</span> </td> </tr> </table> <p> 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> </p> <table> <tr> <td><span class="docbook_option">maildir_format</span></td> <td>Use: <span class="docbook_emphasis">appendfile</span> </td> <td>Type: <span class="docbook_emphasis">boolean</span> </td> <td>Default: <span class="docbook_emphasis">false</span> </td> </tr> </table> <p> If this option is set with the <span class="docbook_option">directory</span> option, the delivery is into a new file, in the “maildir” format that is used by other mail software. When the transport is activated directly from a <span class="docbook_command">redirect</span> router (for example, the <span class="docbook_command">address_file</span> transport in the default configuration), setting <span class="docbook_option">maildir_format</span> causes the path received from the router to be treated as a directory, whether or not it ends with <code class="docbook_literal">/</code>. This option is available only if SUPPORT_MAILDIR is present in <span class="docbook_filename">Local/Makefile</span>. See section <a href="ch26.html#SECTmaildirdelivery" title="26. The appendfile transport">26.5</a> below for further details. </p> <p> </p> <table> <tr> <td><span class="docbook_option">maildir_quota_directory_regex</span></td> <td>Use: <span class="docbook_emphasis">appendfile</span> </td> <td>Type: <span class="docbook_emphasis">string</span> </td> <td>Default: <span class="docbook_emphasis">See below</span> </td> </tr> </table> <p> This option is relevant only when <span class="docbook_option">maildir_use_size_file</span> is set. It defines a regular expression for specifying directories, relative to the quota directory (see <span class="docbook_option">quota_directory</span>), that should be included in the quota calculation. The default value is: </p> <div class="docbook_literallayout"><pre> maildir_quota_directory_regex = ^(?:cur|new|\..*)$ </pre></div> <p> This includes the <span class="docbook_filename">cur</span> and <span class="docbook_filename">new</span> directories, and any maildir++ folders (directories whose names begin with a dot). If you want to exclude the <span class="docbook_filename">Trash</span> folder from the count (as some sites do), you need to change this setting to </p> <div class="docbook_literallayout"><pre> maildir_quota_directory_regex = ^(?:cur|new|\.(?!Trash).*)$ </pre></div> <p> This uses a negative lookahead in the regular expression to exclude the directory whose name is <span class="docbook_filename">.Trash</span>. When a directory is excluded from quota calculations, quota processing is bypassed for any messages that are delivered directly into that directory. </p> <p> </p> <table> <tr> <td><span class="docbook_option">maildir_retries</span></td> <td>Use: <span class="docbook_emphasis">appendfile</span> </td> <td>Type: <span class="docbook_emphasis">integer</span> </td> <td>Default: <span class="docbook_emphasis">10</span> </td> </tr> </table> <p> This option specifies the number of times to retry when writing a file in “maildir” format. See section <a href="ch26.html#SECTmaildirdelivery" title="26. The appendfile transport">26.5</a> below. </p> <p> </p> <table> <tr> <td><span class="docbook_option">maildir_tag</span></td> <td>Use: <span class="docbook_emphasis">appendfile</span> </td> <td>Type: <span class="docbook_emphasis">string</span>†<span class="docbook_emphasis"></span> </td> <td>Default: <span class="docbook_emphasis">unset</span> </td> </tr> </table> <p> This option applies only to deliveries in maildir format, and is described in section <a href="ch26.html#SECTmaildirdelivery" title="26. The appendfile transport">26.5</a> below. </p> <p> </p> <table> <tr> <td><span class="docbook_option">maildir_use_size_file</span></td> <td>Use: <span class="docbook_emphasis">appendfile</span> </td> <td>Type: <span class="docbook_emphasis">boolean</span> </td> <td>Default: <span class="docbook_emphasis">false</span> </td> </tr> </table> <p> Setting this option true enables support for <span class="docbook_filename">maildirsize</span> files. Exim creates a <span class="docbook_filename">maildirsize</span> file in a maildir if one does not exist, taking the quota from the <span class="docbook_option">quota</span> option of the transport. If <span class="docbook_option">quota</span> is unset, the value is zero. See <span class="docbook_option">maildir_quota_directory_regex</span> above and section <a href="ch26.html#SECTmaildirdelivery" title="26. The appendfile transport">26.5</a> below for further details. </p> <p> </p> <table> <tr> <td><span class="docbook_option">maildirfolder_create_regex</span></td> <td>Use: <span class="docbook_emphasis">appendfile</span> </td> <td>Type: <span class="docbook_emphasis">string</span> </td> <td>Default: <span class="docbook_emphasis">unset</span> </td> </tr> </table> <p> 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 <span class="docbook_filename">new</span> and <span class="docbook_filename">tmp</span> subdirectories that will be used for the delivery. If there is a match, Exim checks for the existence of a file called <span class="docbook_filename">maildirfolder</span> in the directory, and creates it if it does not exist. See section <a href="ch26.html#SECTmaildirdelivery" title="26. The appendfile transport">26.5</a> for more details. </p> <p> </p> <table> <tr> <td><span class="docbook_option">mailstore_format</span></td> <td>Use: <span class="docbook_emphasis">appendfile</span> </td> <td>Type: <span class="docbook_emphasis">boolean</span> </td> <td>Default: <span class="docbook_emphasis">false</span> </td> </tr> </table> <p> If this option is set with the <span class="docbook_option">directory</span> option, the delivery is into two new files in “mailstore” format. The option is available only if SUPPORT_MAILSTORE is present in <span class="docbook_filename">Local/Makefile</span>. See section <a href="ch26.html#SECTopdir" title="26. The appendfile transport">26.4</a> below for further details. </p> <p> </p> <table> <tr> <td><span class="docbook_option">mailstore_prefix</span></td> <td>Use: <span class="docbook_emphasis">appendfile</span> </td> <td>Type: <span class="docbook_emphasis">string</span>†<span class="docbook_emphasis"></span> </td> <td>Default: <span class="docbook_emphasis">unset</span> </td> </tr> </table> <p> This option applies only to deliveries in mailstore format, and is described in section <a href="ch26.html#SECTopdir" title="26. The appendfile transport">26.4</a> below. </p> <p> </p> <table> <tr> <td><span class="docbook_option">mailstore_suffix</span></td> <td>Use: <span class="docbook_emphasis">appendfile</span> </td> <td>Type: <span class="docbook_emphasis">string</span>†<span class="docbook_emphasis"></span> </td> <td>Default: <span class="docbook_emphasis">unset</span> </td> </tr> </table> <p> This option applies only to deliveries in mailstore format, and is described in section <a href="ch26.html#SECTopdir" title="26. The appendfile transport">26.4</a> below. </p> <p> </p> <table> <tr> <td><span class="docbook_option">mbx_format</span></td> <td>Use: <span class="docbook_emphasis">appendfile</span> </td> <td>Type: <span class="docbook_emphasis">boolean</span> </td> <td>Default: <span class="docbook_emphasis">false</span> </td> </tr> </table> <p> This option is available only if Exim has been compiled with SUPPORT_MBX set in <span class="docbook_filename">Local/Makefile</span>. If <span class="docbook_option">mbx_format</span> is set with the <span class="docbook_option">file</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="docbook_emphasis">c-client</span> library that they all use. </p> <p> <span class="docbook_emphasis">Note</span>: The <span class="docbook_option">message_prefix</span> and <span class="docbook_option">message_suffix</span> options are not automatically changed by the use of <span class="docbook_option">mbx_format</span>. They should normally be set empty when using MBX format, so this option almost always appears in this combination: </p> <div class="docbook_literallayout"><pre> mbx_format = true message_prefix = message_suffix = </pre></div> <p> If none of the locking options are mentioned in the configuration, <span class="docbook_option">use_mbx_lock</span> is assumed and the other locking options default to false. It is possible to specify the other kinds of locking with <span class="docbook_option">mbx_format</span>, but <span class="docbook_option">use_fcntl_lock</span> and <span class="docbook_option">use_mbx_lock</span> are mutually exclusive. MBX locking interworks with <span class="docbook_emphasis">c-client</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 class="docbook_option">use_fcntl_lock</span> with an MBX-format mailbox, you cannot use the standard version of <span class="docbook_emphasis">c-client</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> </p> <table> <tr> <td><span class="docbook_option">message_prefix</span></td> <td>Use: <span class="docbook_emphasis">appendfile</span> </td> <td>Type: <span class="docbook_emphasis">string</span>†<span class="docbook_emphasis"></span> </td> <td>Default: <span class="docbook_emphasis">see below</span> </td> </tr> </table> <p> The string specified here is expanded and output at the start of every message. The default is unset unless <span class="docbook_option">file</span> is specified and <span class="docbook_option">use_bsmtp</span> is not set, in which case it is: </p> <div class="docbook_literallayout"><pre> message_prefix = "From ${if def:return_path{$return_path}\ {MAILER-DAEMON}} $tod_bsdinbox\n" </pre></div> <p> <span class="docbook_emphasis">Note:</span> If you set <span class="docbook_option">use_crlf</span> true, you must change any occurrences of <code class="docbook_literal">\n</code> to <code class="docbook_literal">\r\n</code> in <span class="docbook_option">message_prefix</span>. </p> <p> </p> <table> <tr> <td><span class="docbook_option">message_suffix</span></td> <td>Use: <span class="docbook_emphasis">appendfile</span> </td> <td>Type: <span class="docbook_emphasis">string</span>†<span class="docbook_emphasis"></span> </td> <td>Default: <span class="docbook_emphasis">see below</span> </td> </tr> </table> <p> The string specified here is expanded and output at the end of every message. The default is unset unless <span class="docbook_option">file</span> is specified and <span class="docbook_option">use_bsmtp</span> is not set, in which case it is a single newline character. The suffix can be suppressed by setting </p> <div class="docbook_literallayout"><pre> message_suffix = </pre></div> <p> <span class="docbook_emphasis">Note:</span> If you set <span class="docbook_option">use_crlf</span> true, you must change any occurrences of <code class="docbook_literal">\n</code> to <code class="docbook_literal">\r\n</code> in <span class="docbook_option">message_suffix</span>. </p> <p> </p> <table> <tr> <td><span class="docbook_option">mode</span></td> <td>Use: <span class="docbook_emphasis">appendfile</span> </td> <td>Type: <span class="docbook_emphasis">octal integer</span> </td> <td>Default: <span class="docbook_emphasis">0600</span> </td> </tr> </table> <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 class="docbook_option">mode_fail_narrower</span> is false. However, if the delivery is the result of a <span class="docbook_option">save</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> </p> <table> <tr> <td><span class="docbook_option">mode_fail_narrower</span></td> <td>Use: <span class="docbook_emphasis">appendfile</span> </td> <td>Type: <span class="docbook_emphasis">boolean</span> </td> <td>Default: <span class="docbook_emphasis">true</span> </td> </tr> </table> <p> This option applies in the case when an existing mailbox file has a narrower mode than that specified by the <span class="docbook_option">mode</span> option. If <span class="docbook_option">mode_fail_narrower</span> is true, the delivery is deferred (“mailbox has the wrong mode”); otherwise Exim continues with the delivery attempt, using the existing mode of the file. </p> <p> </p> <table> <tr> <td><span class="docbook_option">notify_comsat</span></td> <td>Use: <span class="docbook_emphasis">appendfile</span> </td> <td>Type: <span class="docbook_emphasis">boolean</span> </td> <td>Default: <span class="docbook_emphasis">false</span> </td> </tr> </table> <p> If this option is true, the <span class="docbook_emphasis">comsat</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> </p> <table> <tr> <td><span class="docbook_option">quota</span></td> <td>Use: <span class="docbook_emphasis">appendfile</span> </td> <td>Type: <span class="docbook_emphasis">string</span>†<span class="docbook_emphasis"></span> </td> <td>Default: <span class="docbook_emphasis">unset</span> </td> </tr> </table> <p> 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 class="docbook_option">directory</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 class="docbook_option">quota_size_regex</span> and <span class="docbook_option">maildir_use_size_file</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="docbook_emphasis">used</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="docbook_emphasis">used</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="docbook_emphasis">Note</span>: A value of zero is interpreted as “no quota”. </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 class="docbook_option">quota_is_inclusive</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 class="docbook_option">quota_warn_threshold</span>. </p> <p> </p> <table> <tr> <td><span class="docbook_option">quota_directory</span></td> <td>Use: <span class="docbook_emphasis">appendfile</span> </td> <td>Type: <span class="docbook_emphasis">string</span>†<span class="docbook_emphasis"></span> </td> <td>Default: <span class="docbook_emphasis">unset</span> </td> </tr> </table> <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 <span class="docbook_filename">maildirfolder</span> exists in a maildir directory, the parent of the delivery directory. </p> <p> </p> <table> <tr> <td><span class="docbook_option">quota_filecount</span></td> <td>Use: <span class="docbook_emphasis">appendfile</span> </td> <td>Type: <span class="docbook_emphasis">string</span>†<span class="docbook_emphasis"></span> </td> <td>Default: <span class="docbook_emphasis">0</span> </td> </tr> </table> <p> This option applies when the <span class="docbook_option">directory</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 class="docbook_option">quota</span> is also set. The value is expanded; an expansion failure causes delivery to be deferred. A value of zero is interpreted as “no quota”. </p> <p> </p> <table> <tr> <td><span class="docbook_option">quota_is_inclusive</span></td> <td>Use: <span class="docbook_emphasis">appendfile</span> </td> <td>Type: <span class="docbook_emphasis">boolean</span> </td> <td>Default: <span class="docbook_emphasis">true</span> </td> </tr> </table> <p> See <span class="docbook_option">quota</span> above. </p> <p> </p> <table> <tr> <td><span class="docbook_option">quota_size_regex</span></td> <td>Use: <span class="docbook_emphasis">appendfile</span> </td> <td>Type: <span class="docbook_emphasis">string</span> </td> <td>Default: <span class="docbook_emphasis">unset</span> </td> </tr> </table> <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 class="docbook_option">quota_size_regex</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 class="docbook_option">quota_size_regex</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 class="docbook_option">maildir_tag</span> to add the file length to the file name. For example: </p> <div class="docbook_literallayout"><pre> maildir_tag = ,S=$message_size quota_size_regex = ,S=(\d+) </pre></div> <p> An alternative to $message_size is $message_linecount, 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 class="docbook_option">maildir_tag</span> puts it there) because maildir MUAs sometimes add other information onto the ends of message file names. </p> <p> </p> <table> <tr> <td><span class="docbook_option">quota_warn_message</span></td> <td>Use: <span class="docbook_emphasis">appendfile</span> </td> <td>Type: <span class="docbook_emphasis">string</span>†<span class="docbook_emphasis"></span> </td> <td>Default: <span class="docbook_emphasis">see below</span> </td> </tr> </table> <p> See below for the use of this option. If it is not set when <span class="docbook_option">quota_warn_threshold</span> is set, it defaults to </p> <div class="docbook_literallayout"><pre> 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></div> <p> </p> <table> <tr> <td><span class="docbook_option">quota_warn_threshold</span></td> <td>Use: <span class="docbook_emphasis">appendfile</span> </td> <td>Type: <span class="docbook_emphasis">string</span>†<span class="docbook_emphasis"></span> </td> <td>Default: <span class="docbook_emphasis">0</span> </td> </tr> </table> <p> This option is expanded in the same way as <span class="docbook_option">quota</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 class="docbook_option">quota</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> <div class="docbook_literallayout"><pre> quota = 10M quota_warn_threshold = 75% </pre></div> <p> If <span class="docbook_option">quota</span> is not set, a setting of <span class="docbook_option">quota_warn_threshold</span> that ends with a percent sign is ignored. </p> <p> The warning message itself is specified by the <span class="docbook_option">quota_warn_message</span> option, and it must start with a <span class="docbook_emphasis">To:</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="docbook_emphasis">Subject:</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="docbook_emphasis">From:</span> line, the default is: </p> <div class="docbook_literallayout"><pre> From: Mail Delivery System <mailer-daemon@$qualify_domain_sender> </pre></div> <p> If you supply a <span class="docbook_emphasis">Reply-To:</span> line, it overrides the global <span class="docbook_option">errors_reply_to</span> option. </p> <p> The <span class="docbook_option">quota</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> </p> <table> <tr> <td><span class="docbook_option">use_bsmtp</span></td> <td>Use: <span class="docbook_emphasis">appendfile</span> </td> <td>Type: <span class="docbook_emphasis">boolean</span> </td> <td>Default: <span class="docbook_emphasis">false</span> </td> </tr> </table> <p> If this option is set true, <span class="docbook_command">appendfile</span> writes messages in “batch SMTP” 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 class="docbook_option">message_prefix</span> option. See section <a href="ch45.html#SECTbatchSMTP" title="45. SMTP processing">45.10</a> for details of batch SMTP. </p> <p> </p> <table> <tr> <td><span class="docbook_option">use_crlf</span></td> <td>Use: <span class="docbook_emphasis">appendfile</span> </td> <td>Type: <span class="docbook_emphasis">boolean</span> </td> <td>Default: <span class="docbook_emphasis">false</span> </td> </tr> </table> <p> 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="docbook_emphasis">Note:</span> The contents of the <span class="docbook_option">message_prefix</span> and <span class="docbook_option">message_suffix</span> options (which are used to supply the traditional “From ” 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="docbook_literal">\r\n</code> if <span class="docbook_option">use_crlf</span> is set. </p> <p> </p> <table> <tr> <td><span class="docbook_option">use_fcntl_lock</span></td> <td>Use: <span class="docbook_emphasis">appendfile</span> </td> <td>Type: <span class="docbook_emphasis">boolean</span> </td> <td>Default: <span class="docbook_emphasis">see below</span> </td> </tr> </table> <p> This option controls the use of the <span class="docbook_function">fcntl()</span> function to lock a file for exclusive use when a message is being appended. It is set by default unless <span class="docbook_option">use_flock_lock</span> is set. Otherwise, it should be turned off only if you know that all your MUAs use lock file locking. When both <span class="docbook_option">use_fcntl_lock</span> and <span class="docbook_option">use_flock_lock</span> are unset, <span class="docbook_option">use_lockfile</span> must be set. </p> <p> </p> <table> <tr> <td><span class="docbook_option">use_flock_lock</span></td> <td>Use: <span class="docbook_emphasis">appendfile</span> </td> <td>Type: <span class="docbook_emphasis">boolean</span> </td> <td>Default: <span class="docbook_emphasis">false</span> </td> </tr> </table> <p> This option is provided to support the use of <span class="docbook_function">flock()</span> for file locking, for the few situations where it is needed. Most modern operating systems support <span class="docbook_function">fcntl()</span> and <span class="docbook_function">lockf()</span> locking, and these two functions interwork with each other. Exim uses <span class="docbook_function">fcntl()</span> locking by default. </p> <p> This option is required only if you are using an operating system where <span class="docbook_function">flock()</span> is used by programs that access mailboxes (typically MUAs), and where <span class="docbook_function">flock()</span> does not correctly interwork with <span class="docbook_function">fcntl()</span>. You can use both <span class="docbook_function">fcntl()</span> and <span class="docbook_function">flock()</span> locking simultaneously if you want. </p> <p> Not all operating systems provide <span class="docbook_function">flock()</span>. Some versions of Solaris do not have it (and some, I think, provide a not quite right version built on top of <span class="docbook_function">lockf()</span>). If the OS does not have <span class="docbook_function">flock()</span>, 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="docbook_emphasis">Warning</span>: <span class="docbook_function">flock()</span> locks do not work on NFS files (unless <span class="docbook_function">flock()</span> is just being mapped onto <span class="docbook_function">fcntl()</span> by the OS). </p> <p> </p> <table> <tr> <td><span class="docbook_option">use_lockfile</span></td> <td>Use: <span class="docbook_emphasis">appendfile</span> </td> <td>Type: <span class="docbook_emphasis">boolean</span> </td> <td>Default: <span class="docbook_emphasis">see below</span> </td> </tr> </table> <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 <span class="docbook_function">fcntl()</span>. You should only turn <span class="docbook_option">use_lockfile</span> off if you are absolutely sure that every MUA that is ever going to look at your users’ mailboxes uses <span class="docbook_function">fcntl()</span> rather than a lock file, and even then only when you are not delivering over NFS from more than one host. </p> <p> In order to append to an NFS file safely from more than one host, it is necessary to take out a lock <span class="docbook_emphasis">before</span> opening the file, and the lock file achieves this. Otherwise, even with <span class="docbook_function">fcntl()</span> locking, there is a risk of file corruption. </p> <p> The <span class="docbook_option">use_lockfile</span> option is set by default unless <span class="docbook_option">use_mbx_lock</span> is set. It is not possible to turn both <span class="docbook_option">use_lockfile</span> and <span class="docbook_option">use_fcntl_lock</span> off, except when <span class="docbook_option">mbx_format</span> is set. </p> <p> </p> <table> <tr> <td><span class="docbook_option">use_mbx_lock</span></td> <td>Use: <span class="docbook_emphasis">appendfile</span> </td> <td>Type: <span class="docbook_emphasis">boolean</span> </td> <td>Default: <span class="docbook_emphasis">see below</span> </td> </tr> </table> <p> This option is available only if Exim has been compiled with SUPPORT_MBX set in <span class="docbook_filename">Local/Makefile</span>. Setting the option specifies that special MBX locking rules be used. It is set by default if <span class="docbook_option">mbx_format</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="docbook_emphasis">c-client</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 class="docbook_option">use_mbx_lock</span> with either (or both) of <span class="docbook_option">use_fcntl_lock</span> and <span class="docbook_option">use_flock_lock</span> to control what kind of locking is used in implementing the MBX locking rules. The default is to use <span class="docbook_function">fcntl()</span> if <span class="docbook_option">use_mbx_lock</span> is set without <span class="docbook_option">use_fcntl_lock</span> or <span class="docbook_option">use_flock_lock</span>. </p> </div> <div class="section"> <h3 id="SECTopappend" class="">3. Operational details for appending</h3> <p> Before appending to a file, the following preparations are made: </p> <ul> <li> <p> If the name of the file is <span class="docbook_filename">/dev/null</span>, no action is taken, and a success return is given. </p> </li> <li> <p> If any directories on the file’s path are missing, Exim creates them if the <span class="docbook_option">create_directory</span> option is set. A created directory’s mode is given by the <span class="docbook_option">directory_mode</span> option. </p> </li> <li> <p> If <span class="docbook_option">file_format</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> If <span class="docbook_option">use_lockfile</span> is set, a lock file is built in a way that will work reliably over NFS, as follows: </p> <ol> <li> <p> Create a “hitching post” 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 <span class="docbook_function">link()</span> succeeds, creation of the lock file has succeeded. Unlink the hitching post name. </p> </li> <li> <p> Otherwise, use <span class="docbook_function">stat()</span> 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 <span class="docbook_function">link()</span> call. </p> </li> <li> <p> If creation of the lock file failed, wait for <span class="docbook_option">lock_interval</span> and try again, up to <span class="docbook_option">lock_retries</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 class="docbook_option">lockfile_timeout</span> Exim attempts to unlink it before trying again. </p> </li> </ol> </li> <li> <p> A call is made to <span class="docbook_function">lstat()</span> to discover whether the main file exists, and if so, what its characteristics are. If <span class="docbook_function">lstat()</span> fails for any reason other than non-existence, delivery is deferred. </p> </li> <li> <p> If the file does exist and is a symbolic link, delivery is deferred, unless the <span class="docbook_option">allow_symlink</span> option is set, in which case the ownership of the link is checked, and then <span class="docbook_function">stat()</span> 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 class="docbook_option">check_group</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 class="docbook_option">mode_fail_narrower</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 class="docbook_command">appendfile</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 class="docbook_option">file_must_exist</span> option is set. Otherwise, check that the file is being created in a permitted directory if the <span class="docbook_option">create_file</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 class="docbook_option">allow_symlink</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> 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> Once the file is open, unless both <span class="docbook_option">use_fcntl_lock</span> and <span class="docbook_option">use_flock_lock</span> are false, it is locked using <span class="docbook_function">fcntl()</span> or <span class="docbook_function">flock()</span> or both. If <span class="docbook_option">use_mbx_lock</span> is false, an exclusive lock is requested in each case. However, if <span class="docbook_option">use_mbx_lock</span> is true, Exim takes out a shared lock on the open file, and an exclusive lock on the file whose name is </p> <div class="docbook_literallayout"><pre> /tmp/.<device-number>.<inode-number> </pre></div> <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 class="docbook_option">lockfile_mode</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 class="docbook_option">lock_fcntl_timeout</span> or <span class="docbook_option">lock_flock_timeout</span>, as appropriate. </p> <p> If the timeout value is zero, the file is closed, Exim waits for <span class="docbook_option">lock_interval</span>, and then goes back and re-opens the file as above and tries to lock it again. This happens up to <span class="docbook_option">lock_retries</span> times, after which the delivery is deferred. </p> <p> If the timeout has a value greater than zero, blocking calls to <span class="docbook_function">fcntl()</span> or <span class="docbook_function">flock()</span> 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> <div class="docbook_literallayout"><pre> (lock_retries * lock_interval) / <timeout> </pre></div> <p> times (rounded up). </p> </li> </ul> <p> At the end of delivery, Exim closes the file (which releases the <span class="docbook_function">fcntl()</span> and/or <span class="docbook_function">flock()</span> locks) and then deletes the lock file if one was created. </p> </div> <div class="section"> <h3 id="SECTopdir" class="">4. Operational details for delivery to a new file</h3> <p> When the <span class="docbook_option">directory</span> option is set instead of <span class="docbook_option">file</span>, each message is delivered into a newly-created file or set of files. When <span class="docbook_command">appendfile</span> is activated directly from a <span class="docbook_command">redirect</span> router, neither <span class="docbook_option">file</span> nor <span class="docbook_option">directory</span> is normally set, because the path for delivery is supplied by the router. (See for example, the <span class="docbook_command">address_file</span> transport in the default configuration.) In this case, delivery is to a new file if either the path name ends in <code class="docbook_literal">/</code>, or the <span class="docbook_option">maildir_format</span> or <span class="docbook_option">mailstore_format</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 “From” line that by default separates messages in a single file is not normally needed, nor is the escaping of message lines that start with “From”, and there is no need to ensure a newline at the end of each message. Consequently, the default values for <span class="docbook_option">check_string</span>, <span class="docbook_option">message_prefix</span>, and <span class="docbook_option">message_suffix</span> are all unset when any of <span class="docbook_option">directory</span>, <span class="docbook_option">maildir_format</span>, or <span class="docbook_option">mailstore_format</span> is set. </p> <p> If Exim is required to check a <span class="docbook_option">quota</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 class="docbook_option">quota_directory</span>. Also, for maildir deliveries (see below) the <span class="docbook_filename">maildirfolder</span> convention is honoured. </p> <p> There are three different ways in which delivery to individual files can be done, controlled by the settings of the <span class="docbook_option">maildir_format</span> and <span class="docbook_option">mailstore_format</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 <span class="docbook_filename">Local/Makefile</span>. </p> <p> 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 class="docbook_option">create_directory</span> option is set (the default). The location of a created directory can be constrained by setting <span class="docbook_option">create_file</span>. A created directory’s mode is given by the <span class="docbook_option">directory_mode</span> option. If creation fails, or if the <span class="docbook_option">create_directory</span> option is not set when creation is required, delivery is deferred. </p> </div> <div class="section"> <h3 id="SECTmaildirdelivery" class="">5. Maildir delivery</h3> <p> If the <span class="docbook_option">maildir_format</span> option is true, Exim delivers each message by writing it to a file whose name is <span class="docbook_filename">tmp/<stime>.H<mtime>P<pid>.<host></span> in the directory that is defined by the <span class="docbook_option">directory</span> option (the “delivery directory”). If the delivery is successful, the file is renamed into the <span class="docbook_filename">new</span> subdirectory. </p> <p> In the file name, <<span class="docbook_emphasis">stime</span>> is the current time of day in seconds, and <<span class="docbook_emphasis">mtime</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 <span class="docbook_function">stat()</span> 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 class="docbook_option">maildir_retries</span> times. </p> <p> Before Exim carries out a maildir delivery, it ensures that subdirectories called <span class="docbook_filename">new</span>, <span class="docbook_filename">cur</span>, and <span class="docbook_filename">tmp</span> 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 class="docbook_option">create_directory</span> and <span class="docbook_option">create_file</span> options. If the <span class="docbook_option">maildirfolder_create_regex</span> option is set, and the regular expression it contains matches the delivery directory, Exim also ensures that a file called <span class="docbook_filename">maildirfolder</span> exists in the delivery directory. If a missing directory or <span class="docbook_filename">maildirfolder</span> 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> <div class="docbook_literallayout"><pre> maildir_format = true directory = /var/mail/$local_part\ ${if eq{$local_part_suffix}{}{}\ {/.${substr_1:$local_part_suffix}}} maildirfolder_create_regex = /\.[^/]+$ </pre></div> <p> If $local_part_suffix is empty (there was no suffix for the local part), delivery is into a toplevel maildir with a name like <span class="docbook_filename">/var/mail/pimbo</span> (for the user called <span class="docbook_emphasis">pimbo</span>). The pattern in <span class="docbook_option">maildirfolder_create_regex</span> does not match this name, so Exim will not look for or create the file <span class="docbook_filename">/var/mail/pimbo/maildirfolder</span>, though it will create <span class="docbook_filename">/var/mail/pimbo/{cur,new,tmp}</span> if necessary. </p> <p> However, if $local_part_suffix contains <code class="docbook_literal">-eximusers</code> (for example), delivery is into the maildir++ folder <span class="docbook_filename">/var/mail/pimbo/.eximusers</span>, which does match <span class="docbook_option">maildirfolder_create_regex</span>. In this case, Exim will create <span class="docbook_filename">/var/mail/pimbo/.eximusers/maildirfolder</span> as well as the three maildir directories <span class="docbook_filename">/var/mail/pimbo/.eximusers/{cur,new,tmp}</span>. </p> <p> <span class="docbook_emphasis">Warning:</span> Take care when setting <span class="docbook_option">maildirfolder_create_regex</span> that it does not inadvertently match the toplevel maildir directory, because a <span class="docbook_filename">maildirfolder</span> file at top level would completely break quota calculations. </p> <p> If Exim is required to check a <span class="docbook_option">quota</span> setting before a maildir delivery, and <span class="docbook_option">quota_directory</span> is not set, it looks for a file called <span class="docbook_filename">maildirfolder</span> in the maildir directory (alongside <span class="docbook_filename">new</span>, <span class="docbook_filename">cur</span>, <span class="docbook_filename">tmp</span>). 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 class="docbook_option">mailbox_size</span> option as a way of importing it into Exim. </p> </div> <div class="section"> <h3 id="SECID135" class="">6. Using tags to record message sizes</h3> <p> If <span class="docbook_option">maildir_tag</span> is set, the string is expanded for each delivery. When the maildir file is renamed into the <span class="docbook_filename">new</span> 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 <span class="docbook_function">stat()</span> call fails with ENAMETOOLONG, the tag is dropped and the maildir file is created with no tag. </p> <p> Tags can be used to encode the size of files in their names; see <span class="docbook_option">quota_size_regex</span> above for an example. The expansion of <span class="docbook_option">maildir_tag</span> happens after the message has been written. The value of the $message_size 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 “/”. 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"> <h3 id="SECID136" class="">7. Using a maildirsize file</h3> <p> If <span class="docbook_option">maildir_use_size_file</span> is true, Exim implements the maildir++ rules for storing quota and message size information in a file called <span class="docbook_filename">maildirsize</span> within the toplevel maildir directory. If this file does not exist, Exim creates it, setting the quota from the <span class="docbook_option">quota</span> option of the transport. If the maildir directory itself does not exist, it is created before any attempt to write a <span class="docbook_filename">maildirsize</span> file. </p> <p> The <span class="docbook_filename">maildirsize</span> 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 class="docbook_option">quota</span> option in the transport is unset or zero, the <span class="docbook_filename">maildirsize</span> 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 <span class="docbook_filename">maildirsizefile</span> is in use. See the description of the <span class="docbook_option">maildir_quota_directory_regex</span> option above for details. </p> </div> <div class="section"> <h3 id="SECID137" class="">8. Mailstore delivery</h3> <p> If the <span class="docbook_option">mailstore_format</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 <span class="docbook_filename">.env</span> and <span class="docbook_filename">.msg</span>. The <span class="docbook_filename">.env</span> file contains the message’s envelope, and the <span class="docbook_filename">.msg</span> file contains the message itself. The base name is placed in the variable $mailstore_basename. </p> <p> During delivery, the envelope is first written to a file with the suffix <span class="docbook_filename">.tmp</span>. The <span class="docbook_filename">.msg</span> file is then written, and when it is complete, the <span class="docbook_filename">.tmp</span> file is renamed as the <span class="docbook_filename">.env</span> file. Programs that access messages in mailstore format should wait for the presence of both a <span class="docbook_filename">.msg</span> and a <span class="docbook_filename">.env</span> file before accessing either of them. An alternative approach is to wait for the absence of a <span class="docbook_filename">.tmp</span> file. </p> <p> The envelope file starts with any text defined by the <span class="docbook_option">mailstore_prefix</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 class="docbook_option">batch_max</span> option is set greater than one. Finally, <span class="docbook_option">mailstore_suffix</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 class="docbook_option">mailstore_prefix</span> or <span class="docbook_option">mailstore_suffix</span> ends with a forced failure, it is ignored. Other expansion errors are treated as serious configuration errors, and delivery is deferred. The variable $mailstore_basename is available for use during these expansions. </p> </div> <div class="section"> <h3 id="SECID138" class="">9. Non-special new file delivery</h3> <p> If neither <span class="docbook_option">maildir_format</span> nor <span class="docbook_option">mailstore_format</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. SMTP processing">45.10</a>), a setting such as </p> <div class="docbook_literallayout"><pre> directory = /var/bsmtp/$host </pre></div> <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 class="docbook_option">directory_file</span> option. </p> </div> </div> <a class="previous_page" href="ch25.html"><-previous</a><a class="next_page" href="ch27.html">next-></a> </div></div> <iframe id="branding" name="branding" src="../../../../branding/branding.html" height="0" frameborder="no" scrolling="no"></iframe><div id="footer">Website design by <a href="https://secure.grepular.com/">Mike Cardwell</a>, of <a href="http://cardwellit.com/">Cardwell IT Ltd.</a> </div> <div class="left_bar"></div> <div class="right_bar"></div> <div id="toc"> <ul class="hidden"></ul> <img src="../../../../doc/contents.png" width="16" height="155"> </div> </div> <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.4/jquery.min.js"></script><script type="text/javascript" src="../../../../common.js"></script><script type="text/javascript" src="../../../../doc/chapter.js"></script> </body> </html>