\input texinfo @set{wmYear} 1997 @set{wmAuthor} Philip Hazel @set{wmAuthor_email} @set{COPYRIGHT1} Copyright @copyright{} @value{wmYear} University of Cambridge @c %**start of header @setfilename spec.info @settitle Exim Specification @paragraphindent 0 @c %**end of header @titlepage @title The Exim Mail Transfer Agent @author @value{wmAuthor} @page @vskip 0pt plus 1filll Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. @sp2 @value{COPYRIGHT1}@* @end titlepage @node Top, 1[[[]]] Introduction, (dir), (dir) @top The Exim Mail Transfer Agent@* **************************** The specification of the Exim Mail Transfer Agent is converted mechanically into Texinfo format from its original marked-up source. Some typographic representations are changed, chapters and sections cannot be numbered, and Texinfo lacks the ability to mark updated parts of the specification with change bars. Because the chapters and sections are unnumbered, cross references are set to their names. This makes the English a bit odd, with phrases like `see chapter "Retry configuration"' but it seemed very cumbersome to change this to `see the chapter entitled "Retry configuration"' each time. Each chapter, section, and configuration option has been placed in a separate Texinfo node. Texinfo doesn't allow commas, colons, or apostrophes in node names, which is a rather nasty restriction. I have arranged not to use colons or apostrophes in section titles, but cannot bring myself to omit them from titles such as "The foo, bar and baz commands". For the corresponding node names I have just used multiple occurrences of "and", though it looks very ugly. If a chapter or section continues after a list of configuration options that is not in a new section, a new node is started, using the chapter's or section's name plus `(continued)'. The `Up' operation from a section or configuration option returns to the start of the current chapter; the `Up' operation at a chapter start returns to the top of the document; the `Up' in a list of configuration options within a section returns to the top of that section. A number of drivers have options with the same name, so they have been disambiguated by adding the name of the driver to the option's name. Thus, for example, the specification of the `prefix' option of the `appendfile' transport is in a node called `prefix (appendfile)'. @menu * 1[[[]]] Introduction:: * 2[[[]]] Incorporated code:: * 3[[[]]] How Exim delivers mail:: * 4[[[]]] Building and installing Exim:: * 5[[[]]] The Exim command line:: * 6[[[]]] File and database lookups:: * 7[[[]]] The Exim configuration file:: * 8[[[]]] Regular expressions:: * 9[[[]]] String expansions:: * 10[[[]]] Embedded Perl:: * 11[[[]]] Main configuration:: * 12[[[]]] Driver specifications:: * 13[[[]]] Environment for running local transports:: * 14[[[]]] Generic options for transports:: * 15[[[]]] The appendfile transport:: * 16[[[]]] The autoreply transport:: * 17[[[]]] The lmtp transport:: * 18[[[]]] The pipe transport:: * 19[[[]]] The smtp transport:: * 20[[[]]] Generic options common to both directors and routers:: * 21[[[]]] Additional generic options for directors:: * 22[[[]]] Options common to the aliasfile and forwardfile directors:: * 23[[[]]] The aliasfile director:: * 24[[[]]] The forwardfile director:: * 25[[[]]] The localuser director:: * 26[[[]]] The smartuser director:: * 27[[[]]] Additional generic options for routers:: * 28[[[]]] The domainlist router:: * 29[[[]]] The ipliteral router:: * 30[[[]]] The iplookup router:: * 31[[[]]] The lookuphost router:: * 32[[[]]] The queryprogram router:: * 33[[[]]] Retry configuration:: * 34[[[]]] Address rewriting:: * 35[[[]]] SMTP authentication:: * 36[[[]]] The plaintext authenticator:: * 37[[[]]] The cram_md5 authenticator:: * 38[[[]]] Encrypted SMTP connections using TLS/SSL:: * 39[[[]]] Customizing error and warning messages:: * 40[[[]]] The default configuration file:: * 41[[[]]] Multiple user mailboxes:: * 42[[[]]] Using Exim to handle mailing lists:: * 43[[[]]] Virtual domains:: * 44[[[]]] Intermittently connected hosts:: * 45[[[]]] Verification of incoming mail:: * 46[[[]]] Other policy controls on incoming mail:: * 47[[[]]] System-wide message filtering:: * 48[[[]]] SMTP processing:: * 49[[[]]] Message processing:: * 50[[[]]] Automatic mail processing:: * 51[[[]]] Log files:: * 52[[[]]] Day-to-day management:: * 53[[[]]] Exim utilities:: * 54[[[]]] The Exim monitor:: * 55[[[]]] Security considerations:: * 56[[[]]] Format of spool files:: * 57[[[]]] Adding new drivers or lookup types:: * Concept Index:: @end menu @node 1[[[]]] Introduction, Incorporated code, Top, Top @chapter 1[[[]]] Introduction @dfn{If I have seen further it is by standing on the shoulders of giants.} [(br)](Isaac Newton). @sp 4 Exim is a mail transfer agent (MTA) for Unix systems connected to the Internet. Configuration files currently exist for the following operating systems: AIX, BSDI, [(font color=green)] Darwin (Mac OS X), [(/font)] DGUX, FreeBSD, GNU/Hurd, GNU/Linux, HI-OSF (Hitachi), HP-UX, IRIX, MIPS RISCOS, NetBSD, OpenBSD, QNX, SCO, SCO SVR4.2 (aka UNIX-SV), Solaris (aka SunOS5), SunOS4, Tru64-Unix (formerly Digital UNIX, formerly DEC-OSF1), Ultrix, and Unixware. However, code is not available for determining system load averages under Ultrix. The terms and conditions for the use and distribution of Exim are contained in the file @file{NOTICE}. Exim is distributed under the terms of the GNU General Public Licence, a copy of which may be found in the file @file{LICENCE}. The use, supply or promotion of Exim for the purpose of sending bulk, unsolicited electronic mail is incompatible with the basic aims of the program, which revolve around the free provision of a service that enhances the quality of personal communications. The author of Exim regards indiscriminate mass-mailing as an antisocial, irresponsible abuse of the Internet. Exim owes a great deal to Smail 3 and its author, Ron Karr. Without the experience of running and working on the Smail 3 code, I could never have contemplated starting to write a new mailer. Many of the ideas and user interfaces [(font color=green)] were originally taken from Smail 3, though the actual code of Exim is entirely new, and has developed far beyond the initial concept. [(/font)] Many people, both in Cambridge and around the world, have contributed to the development and the testing of Exim, and to porting it to various operating systems. I am grateful to them all. This document is very much a reference manual; it is not a tutorial. Although there are some discussions and examples in places, the information is mostly organized in a way that makes it easy to look up, rather than in a natural order for sequential reading. Furthermore, the manual aims to cover every aspect of Exim in detail, including a number of rarely-used, special-purpose features that are unlikely to be of very wide interest. [(font color=green)] An `easier' discussion of Exim which provides more in-depth explanatory, introductory, and tutorial material can be found in my book @dfn{Exim The Mail Transport Agent}, published by O'Reilly (ISBN 0-596-00098-7). Inevitably, however, the book is unlikely to be fully up-to-date with the latest release. This specification is the definitive reference. [(/font)] This edition of the Exim specification applies to version 3.30 of Exim. Substantive changes from the 3.20 edition are marked by bars in the right-hand margin in the PostScript, PDF, and plain text versions of the document. Changes are not marked in the Texinfo version, because Texinfo doesn't support change bars. In the HTML version, a different colour is used. Minor corrections and rewordings are not marked. As the program is still developing, there may be features in later versions of the program that have not yet made it into this document, which is updated only when the most significant digit of the fractional part of the version number changes. However, all changes are noted briefly in the file called @file{doc/ChangeLog}, and specifications of new features that are not yet in this manual are placed in @file{doc/NewStuff}. Complete lists of options are maintained in @file{doc/OptionsLists.txt}. [(font color=green)] All these files can be found within the Exim source distribution. [(/font)] @sp 2 @menu * Web site and Mailing list:: * Availability:: * Limitations:: * Features:: * Support for IPv6:: * Calling interface:: * Terminology:: @end menu @node Web site and Mailing list, Availability, 1[[[]]] Introduction, 1[[[]]] Introduction @section 1[[[]]]1 Web site and Mailing list There is a web site at http://www.exim.org by courtesy of [(font color=green)] Energis Squared, formerly Planet Online Ltd, [(/font)] who are situated in the UK. The site is mirrored in the USA and a number of of other countries; links to the mirrors are listed on the home page. [(font color=green)] Energis also provide resources for the following mailing lists: [(/font)] @display @dfn{exim-users@@exim.org} general discussion list @dfn{exim-announce@@exim.org} moderated, low volume announcements list @dfn{pop-imap@@exim.org} discussion of POP/IMAP issues @end display You can subscribe to these lists, change your existing subscription, and view or search the archives via the `mailing lists' link on the Exim home page. By courtesy of Martin Hamilton, there is also an archive of the @dfn{exim-users} list in plain text form at http://www.roads.lut.ac.uk/lists/exim-users/exim-users.archive and in HTML via Hypermail at http://www.roads.lut.ac.uk/lists/exim-users/. The list is also forwarded to http://www.egroups.com/list/exim-users, which is another archiving system with searching capabilities. @node Availability, Limitations, Web site and Mailing list, 1[[[]]] Introduction @section 1[[[]]]2 Availability The master ftp site for the Exim distribution is @example ftp://ftp.csx.cam.ac.uk/pub/software/email/exim @end example Those mirror sites that I know about are listed in the file @example ftp://ftp.csx.cam.ac.uk/pub/software/email/exim/Mirrors @end example The current release of Exim is always to be found in files called @example @file{exim-@dfn{n.nn}.tar.gz} and @file{exim-@dfn{n.nn}.tar.bz2} @end example where @dfn{n.nn} is the highest such version number in the directory. The two files contain identical data; the only difference is the type of compression. The @file{.bz2} file is usually a lot smaller than the @file{.gz} file. When there is only a small amount of change from one version to the next, a patch file may be provided, with a final component name of the form @example @file{exim-patch-@dfn{n.nn}-@dfn{m.mm}.gz} @end example For each released version, the log of changes is made separately available in the directory @example ftp://ftp.csx.cam.ac.uk/pub/software/email/exim/ChangeLogs @end example so that it is possible to find out what has changed without having to download the entire distribution. The main distribution contains ASCII versions of this specification and other documentation; other formats of the documents are available in separate files: @example @file{exim-html-@dfn{n.nn}.tar.gz} @file{exim-pdf-@dfn{n.nn}.tar.gz} @file{exim-postscript-@dfn{n.nn}.tar.gz} @file{exim-texinfo-@dfn{n.nn}.tar.gz} @end example These tar files contain only the @file{/doc} directory, not the complete distribution, and are also available in @file{.bz2} as well as @file{.gz} forms. An FAQ is available in two different formats from @example ftp://ftp.csx.cam.ac.uk/pub/software/email/exim/FAQ.txt.gz ftp://ftp.csx.cam.ac.uk/pub/software/email/exim/FAQ.html.gz @end example The FAQ and other HTML documentation is also available online at the web site and its mirrors. At the ftp site, there is a directory called @example ftp://ftp.csx.cam.ac.uk/pub/software/email/exim/Contrib/ @end example which contains miscellaneous files contributed to the Exim community by Exim users, and there is also a collection of contributed configuration examples in @example ftp://ftp.csx.cam.ac.uk/pub/software/email/exim/config.samples.tar.gz @end example @node Limitations, Features, Availability, 1[[[]]] Introduction @section 1[[[]]]3 Limitations @cindex limitations @itemize @bullet @item Exim is written in ANSI C. This should not be much of a limitation these days. However, to help with systems that lack a true ANSI C library, Exim avoids making any use of the value returned by the @dfn{sprintf()} function, which is one @cindex sprintf of the main incompatibilities. @cindex strerror @cindex memmove @cindex bcopy It has its own version of @dfn{strerror()} for use with SunOS4 and any other system that lacks this function, and a macro can be defined to turn @dfn{memmove()} into @dfn{bcopy()} if necessary. Exim uses file names that are longer than fourteen characters. @item Exim is intended for use as an Internet mailer, and therefore handles addresses in RFC 822 domain format only. @cindex bang paths: It cannot handle `bang paths', though simple two-component bang paths can be converted by a straightforward rewriting configuration. This restriction does not prevent Exim from being interfaced to UUCP, provided domain addresses are used. @item @cindex domainless addresses Exim insists that every address it handles has a domain attached. For incoming local messages, domainless addresses are automatically qualified with a configured domain value. Configuration options specify from which remote systems unqualified addresses are acceptable. These are then qualified on arrival. @item @cindex transport: external @cindex external transports The only external transport currently implemented is an SMTP transport over a TCP/IP network (using sockets, including support for IPv6). However, a pipe transport is available, and there are facilities for writing messages to files and pipes, optionally in @dfn{batched SMTP} format; these facilities can be used to send messages to some other transport mechanism such as UUCP, provided it can handle domain-style addresses. Batched SMTP input is also catered for. @item Exim is not designed for storing mail for dial-in hosts. When the volumes of such mail are large, it is better to get the messages `delivered' into files (that is, off Exim's queue) and subsequently passed on to the dial-in hosts by other means. @item It used not to be easy to set up Exim to rewrite addresses only in some copies of a message and not others, for example, to retain locally-meaningful addresses locally, but rewrite them for any copies of messages that are sent off-site. From release 3.20, doing this has been made a lot simpler by adding a facility for rewriting at transport time. @end itemize @node Features, Support for IPv6, Limitations, 1[[[]]] Introduction @section 1[[[]]]4 Features These are some of the main features of Exim: @itemize @bullet @item Exim follows the same general approach of decentralized control that Smail does. There is no central process doing overall management of mail delivery. However, unlike Smail, the independent delivery processes share data in the form of `hints', which makes delivery more efficient in some cases. The hints are kept in a number of DBM files. If any of these files are lost, the only effect is to change the pattern of delivery attempts and retries. @item Many configuration options can be given as expansion strings, which are transformed in various ways when they are used. As these can include file lookups, much of Exim's operation can be made table-driven if desired. For example, it is possible to do local delivery on a machine on which the users do not have accounts. The ultimate flexibility can be obtained (at a price) by running a Perl interpreter while expanding a string. @item Exim has flexible retry algorithms, applicable to directing and routing addresses as well as to delivery. @item Exim contains header and envelope rewriting facilities. @item Unqualified addresses are accepted only from specified hosts or networks. @item Exim can perform multiple deliveries down the same SMTP channel after deliveries have been delayed. @item Exim can be configured to do local deliveries immediately but to leave remote (SMTP) deliveries until the message is picked up by a queue-runner process. This increases the likelihood of multiple messages being sent down a single SMTP connection. @item Remote deliveries of the same message to different hosts can optionally be done in parallel. @item Incoming SMTP messages start delivery as soon as they are received, without waiting for the SMTP call to close. @item Exim has support for the SMTP AUTH extension for authenticating clients, and for the STARTTLS extension for setting up encrypted connections. @item Perl-compatible regular expressions are available in a number of configuration parameters. @item Domain lists can include file lookups, making it possible to support very large numbers of local domains. @item Exim supports optional checking of incoming return path (sender) and receiver addresses as they are received by SMTP. @item SMTP calls from specific machines, optionally from specific idents, can be locked out, and incoming SMTP messages from specific senders can also be locked out. Exim also supports the use of the Realtime Blackhole List (RBL). @item Hosts that are permitted to relay mail through a machine to another external domain can be controlled by IP number or IP network number. Relay control by recipient domain and sender address is also available. @item Messages on the queue can be `frozen' and `thawed' by the administrator. @item Exim can handle a number of independent local domains on the same machine; each domain can have its own alias files, etc. This facility is sometimes known as `virtual domains'. @item Simple mailing lists can be handled directly by Exim itself (but for `serious' mailing list operations, it is best to use it in conjunction with specialist mailing list software). @item Exim stats a user's home directory before looking for a @file{.forward} file, in order to detect the case of a missing NFS mount. Delivery is delayed if the directory is unavailable. @item Exim contains an optional built-in mail filtering facility. This can be configured to allow users to provide personal filter files, and it is also possible for a system-wide filter file to be applied to every message. @item There is support for multiple user mailboxes controlled by prefixes or suffixes on the user name, either via the filter mechanism or through multiple @file{.forward} files. @item Periodic warnings are automatically sent to messages' senders when delivery is delayed -- the time between warnings is configurable. The warnings can be made conditional on the contents of the message. @item A queue run can be manually started to deliver just a particular portion of the queue, or those messages with a recipient whose address contains a given string. There is support for the @sc{etrn} command in SMTP to interface to this. @item Exim can be configured to run as root all the time, except when performing local deliveries, which it always does in a separate process under an appropriate uid and gid. Alternatively, it can be configured to run as root only when needed; in particular, it need not run as root when receiving incoming messages or when sending out messages over SMTP. See chapter 55 for a discussion of security issues. @item I have tried to make the wording of delivery failure messages clearer and simpler, for the benefit of those less-experienced people who are now using email. Alternative wording for these messages can be provided in a separate file. @item The Exim Monitor is an optional extra; it displays information about Exim's processing in an X window, and an administrator can perform a number of control actions from the window interface. However, all such actions are also available from the command line interface. @end itemize @node Support for IPv6, Calling interface, Features, 1[[[]]] Introduction @section 1[[[]]]5 Support for IPv6 IPv6 is the next generation of IP protocol which will in time replace IPv4; it is currently in an experimental state. A number of vendors have already released IPv6 versions of their systems and networking libraries. If Exim is built with @sc{have_ipv6} set, it uses the IPv6 API for TCP/IP input and output. IP addresses can be given in IPv6 as well as IPv4 notation; incoming IPv4 calls use the embedded IPv6 address notation. In the DNS, two new record types, A6 and AAAA, are used for finding IPv6 addresses. A6 records are supposed, in time, to supersede AAAA records. At present, to be on the safe side, when trying to find host addresses from the DNS, Exim looks for all three record types: A6, AAAA, and A, in that order, and builds a combined list of addresses found (dropping any duplicates). In future this may change (for example, to stop once one kind of address has been found). @node Calling interface, Terminology, Support for IPv6, 1[[[]]] Introduction @section 1[[[]]]6 Calling interface Like many MTAs, Exim has adopted the Sendmail interface so that it can be a straight replacement for @file{/usr/lib/sendmail} or @file{/usr/sbin/sendmail} [(font color=green)] when sending mail. Other compatible options also exist, but those that produce output (for example, -@dfn{bp}, which lists the messages on the queue) do so in Exim's own format. [(/font)] All the relevant Sendmail options are implemented, with two reservations. There are also some additional options that are compatible with Smail 3, and some further options that are new to Exim. The -@dfn{t} option, for taking a list of recipients from a message's headers, is documented (for several versions of Sendmail) as suppressing delivery to any addresses on the command line (see `man' pages on a number of operating systems). However, it appears that this is not the case in practice. For this reason, Exim has an option called @dfn{extract_addresses_remove_arguments} which controls its behaviour in this regard. Sendmail uses the -@dfn{bi} option as a request to rebuild the alias file. As Exim does not have the concept of a single alias file, it cannot mimic this behaviour. It can be configured to run a particular script when this option is received; otherwise the option is ignored. The run time configuration is held in a single text file which is divided into a number of sections. The entries in this file consist of keywords and values, in the style of Smail 3 configuration files. A default configuration file which is suitable for simple installations is provided in the distribution. Control of messages on the queue can be done via certain privileged command line options. There is also an optional monitor program called @dfn{eximon}, which displays current information in an X window, and contains a menu interface to Exim's command line administration options. @node Terminology, , Calling interface, 1[[[]]] Introduction @section 1[[[]]]7 Terminology @cindex local part: definition @cindex domain: definition The term @dfn{local part}, which is taken from RFC 822, is used to refer to that part of an email address that precedes the @@ sign. The part that follows the @@ sign is called the @dfn{domain} or @dfn{mail domain}. The word @dfn{domain} is sometimes used to mean all but the first component of a machine's name. It is @dfn{not} used in that sense here, where it normally refers to the part of an email address following the @@ sign. @cindex local domain, definition @cindex remote domain, definition @dfn{Local domains} are mail domains for which the current host is responsible for handling the entire address; in other words, it has special knowledge of what to do with messages sent to such domains, and normally that means using the local part of the address either to deliver the message on the local host or to transform the address using an alias file or something similar. All other domains are @dfn{remote domains}, which normally cause the message to be transmitted to some other host. The distinction between local and remote domains is not always entirely clear-cut, since a host can have special knowledge about routing for remote domains, and messages for local domains may under some circumstances be passed to other hosts. @cindex local delivery, definition @cindex remote delivery, definition The terms @dfn{local delivery} and @dfn{remote delivery} are used to distinguish delivery to a file or a pipe on the local machine from delivery by SMTP to some remote machine. The type of delivery does not necessarily correspond to the type of address. Mail for a local domain may get passed on to some other host, while mail for a remote domain might get delivered locally to a file or pipe for onward transmission by some other means. However, these are special cases. @cindex default The term @dfn{default} appears frequently in this manual. It is used to qualify a value which is used in the absence of any setting in the configuration. It may also qualify an action which is taken unless a configuration setting specifies otherwise. The term @dfn{defer} is used when the delivery of a message to a specific destination cannot immediately take place for some reason (a remote host may be down, or a user's local mailbox may be full). Such deliveries are @dfn{deferred} until a later time. @cindex mailmaster @cindex postmaster The term @dfn{mailmaster} is used to refer to the person in charge of maintaining the mail software on a given computer. Commonly this will be the same person who fulfils the postmaster role, but this may not always be the case. @cindex queue: definition The term @dfn{queue} is used to refer to the set of messages awaiting delivery, because this term is in widespread use in the context of MTAs. However, in Exim's case the reality is more like a pool than a queue, because there is normally no ordering of waiting messages. @cindex queue-runner The term @dfn{queue-runner} is used to describe a process that scans the queue and attempts to deliver those messages whose retry times have come. This term is used by other MTAs, and also relates to the command @dfn{runq}, but in Exim the waiting messages are normally processed in an unpredictable order. @node 2[[[]]] Incorporated code, How Exim delivers mail, 1[[[]]] Introduction, Top @chapter 2[[[]]] Incorporated code @cindex incorporated code @cindex regular expressions: library @cindex PCRE @cindex RFC 1413 @cindex ident A number of pieces of external code are included in the Exim distribution. @itemize @bullet @item Regular expressions are supported in the main Exim program and in the Exim monitor using the freely-distributable PCRE library, copyright (c) 2000 University of Cambridge. The source is distributed in the directory @file{src/pcre}. @item RFC 1413 callbacks are supported in the main Exim program using the @dfn{libident} library made freely available by Peter Eriksson at ftp://ftp.lysator.liu.se. Some modifications have been made in order to support IPv6. The source is distributed in the directory called @file{src/libident}. @item @cindex cdb Support for the cdb (Constant DataBase) lookup method is provided by code contributed by Nigel Metheringham of Planet Online Ltd. which contains the following statements: --------------------------------------------------------------------@* Copyright (c) 1998 Nigel Metheringham, Planet Online Ltd This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This code implements Dan Bernstein's Constant DataBase (cdb) spec. Information, the spec and sample code for cdb can be obtained from http://www.pobox.com/~djb/cdb.html. This implementation borrows some code from Dan Bernstein's implementation (which has no license restrictions applied to it). --------------------------------------------------------------------@* The implementation is completely contained within the code of Exim. It does not link against an external cdb library. @item @cindex monitor @cindex X-windows @cindex Athena The Exim Monitor program, which is an X-Window application, includes modified versions of the Athena StripChart and TextPop widgets. This code is copyright by DEC and MIT, and their permission notice appears below, in accordance with the conditions expressed therein. @end itemize -------------------------------------------------------------------------@* Copyright 1987, 1988 by Digital Equipment Corporation, Maynard, Massachusetts, and the Massachusetts Institute of Technology, Cambridge, Massachusetts. @sp 1 @center All Rights Reserved @sp 1 Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the names of Digital or MIT not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. DIGITAL DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL DIGITAL BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. -------------------------------------------------------------------------@* @node 3[[[]]] How Exim delivers mail, Building and installing Exim, 2[[[]]] Incorporated code, Top @chapter 3[[[]]] How Exim delivers mail @sp 2 @menu * Philosophy:: * Message reception:: * Life of a message:: * Drivers:: * Delivery in detail:: * Temporary delivery failures:: @end menu @node Philosophy, Message reception, 3[[[]]] How Exim delivers mail, 3[[[]]] How Exim delivers mail @section 3[[[]]]1 Philosophy Exim is designed to work efficiently on systems that are permanently connected to the Internet and are handling a general mix of mail. In such circumstances, most messages can be delivered immediately. Consequently, Exim does not maintain independent queues of messages for specific domains or hosts, though it does try to send several messages in a single SMTP connection after a host has been down, and it also maintains per-host retry information. @node Message reception, Life of a message, Philosophy, 3[[[]]] How Exim delivers mail @section 3[[[]]]2 Message reception @cindex spool: files @cindex mail delivery When Exim receives a message, it writes two files in its spool directory. The first contains the @dfn{envelope} information, the current status of the message, and the headers, while the second contains the body of the message. The envelope information consists of the address of the message's sender and the address(es) of the recipient(s). This information is entirely separate from any addresses contained in the headers. The status of the message includes a list of recipients who have already received the message. The format of the first spool file is described in chapter 56. Address rewriting that is specified in the rewrite section of the configuration (see chapter 34) is done once and for all on incoming addresses, both in the header and the envelope, at the time the message is received. If during the course of delivery additional addresses are generated (for example, via aliasing), these new addresses get rewritten as soon as they are generated. At the time a message is actually delivered (transported) further rewriting can take place; because this is a transport option, it can be different for different forms of delivery. It is also possible to specify the addition or removal of certain headers at the time the message is delivered (see chapters 14 and 20). @cindex message: id @cindex id of message Every message handled by Exim is given a @dfn{message id} which is sixteen characters long. It is divided into three parts, separated by hyphens. Each part is a sequence of letters and digits, representing a number in base 62: @itemize @bullet @item The first six characters are the time the message was received, as a number in seconds -- the normal Unix way of representing a time of day. If the clock goes backwards (due to resetting) in a process that is receiving more than one message, the later time is retained. @item After the first hyphen, the next six characters are the id of the process that received the message. @item The final two characters, after the second hyphen, are used to ensure uniqueness of the id. There are two different formats: @enumerate @item @cindex localhost_number If the @dfn{localhost_number} option is not set, uniqueness is required only within the local host. This portion of the id is `00' except when a process receives more than one message in a single second, when the number is incremented for each additional message. @item If the @dfn{localhost_number} option is set, uniqueness among a set of hosts is required. This portion of the id is set to the base 62 encoding of @example <@dfn{sequence number}> * 256 + <@dfn{host number}> @end example where <@dfn{sequence number}> is the count of messages received by the current process within the current second. As the maximum value of the host number is 255, this allows for a maximum value of 14 for the sequence number. If this limit is reached, a delay of one second is imposed before reading the next message, in order to allow the clock to tick and the sequence number to get reset. @end enumerate @end itemize The names of the two spool files consist of the message id, followed by -H for the file containing the envelope and headers, and -D for the data file. By default all these spool files are held in a single directory called @file{input} inside the general Exim spool directory. Some operating systems do not perform very well if the number of files in a directory gets very large; to improve performance in such cases, the @dfn{split_spool_directory} option can be used. This causes Exim to split up the input files into 62 sub-directories whose names are single letters or digits. Exim can be configured not to start a delivery process when a message is received; this can be unconditional, or depend on the number of incoming SMTP connections or the system load. In these situations, new messages wait on the queue until a queue-runner process picks them up. However, in standard configurations under normal conditions, delivery is started as soon as a message is received. @node Life of a message, Drivers, Message reception, 3[[[]]] How Exim delivers mail @section 3[[[]]]3 Life of a message A message remains in the spool directory until it is completely delivered to its recipients or to an error address, or until it is deleted by an administrator or by the user who originally created it. In cases when delivery cannot proceed -- for example, when a message can neither be delivered to its recipients nor returned to its sender, the message is marked `frozen' on the spool, and no more deliveries are attempted. @cindex frozen messages: thawing An administrator can `thaw' such messages when the problem has been corrected, and can also freeze individual messages by hand if necessary. In addition, an administrator can force a delivery error, causing an error message to be sent. @cindex auto_thaw There is also an @dfn{auto_thaw} option, which can be used to cause Exim to retry frozen messages after a certain time. When this is set, no message will remain on the queue for ever, because the delivery timeout will eventually be reached. @cindex delivery: failure report Delivery failure reports that reach this timeout are discarded. @cindex locking messages [(font color=green)] When an Exim process starts to deliver a message, it takes out a lock on the -D file, to prevent any other Exim process from working on it. [(/font)] @cindex message: log @cindex log: message As delivery proceeds, Exim writes timestamped information about each address to a per-message log file; this includes any delivery error messages. This log is solely for the benefit of the administrator, and is normally deleted with the spool files when processing of a message is complete. However, Exim can be configured to retain it (a dangerous option, as the files can accumulate rapidly on a busy system). Exim also writes delivery messages to its main log file, whose contents are described in chapter 51. @cindex journal file All the information Exim itself needs to set up a delivery is kept in the first spool file with the headers. When a successful delivery occurs, the address is immediately written at the end of a journal file, whose name is the message id followed by -J. At the end of a delivery run, if there are some addresses left to be tried again later, the first spool file (the -H file) is updated to indicate which these are, and the journal file is then deleted. Updating the spool file is done by writing a new file and renaming it, to minimize the possibility of data loss. Should the system or the program crash after a successful delivery but before the spool file has been updated, the journal is left lying around. The next time Exim attempts to deliver the message, it reads the journal file and updates the spool file before proceeding. This minimizes the chances of double deliveries caused by crashes. @node Drivers, Delivery in detail, Life of a message, 3[[[]]] How Exim delivers mail @section 3[[[]]]4 Drivers @cindex drivers @cindex director: @cindex router: @cindex transport: The main delivery processing elements of Exim are called @dfn{directors}, @dfn{routers}, and @dfn{transports}, and collectively these are known as @dfn{drivers}. Code for a number of them is provided, compile-time options specify which ones are included in the binary, and run time options specify which ones are actually used. A @dfn{transport} is a driver that transmits a copy of the message from Exim's spool to some destination. There are two kinds of transport: for a @dfn{local} transport, the destination is a file or a pipe on the local host, whereas for a @dfn{remote} transport the destination is some other host. A message is passed to a specific transport as a result of successful directing or routing. If a message has several recipients, it may be passed to a number of different transports. A @dfn{director} is a driver that operates on a local address, either determining how its delivery should happen, or converting the address into one or more new addresses (for example, via an alias file). A local address is one whose domain matches an entry in the list given in the @dfn{local_domains} option, or has been determined to be local by a router -- see below. The fact that an address is local does not imply that the message has to be delivered locally; it can be directed either to a local or to a remote transport. A @dfn{router} is a driver that operates on an apparently remote address, that is an address whose domain does not match anything in the list given in @dfn{local_domains}. When a router succeeds it can route an address either to a local or to a remote transport, or it can change the domain, and pass the address on to subsequent routers. In exceptional cases, a router may determine that an address is local after all, and cause it to be passed to the directors. This happens automatically if a host lookup expands an abbreviated domain into one that is local. It can also be made to happen (optionally) if an MX record or other routing information points to the local host, though by default this situation is treated as a configuration error. This is the only case in which the directors are used to process an address that may not match anything in @dfn{local_domains}. The diagram below illustrates the relationship between the three kinds of driver. [(img src="drivers.gif" alt="Driver interactions")][(br)] As new features have been added to Exim, the distinction between routers and directors has become less clear-cut than it once was. It is possible that in some future release the difference will be abolished and they will be merged into one type of driver. However, at present, they remain distinct. @node Delivery in detail, Temporary delivery failures, Drivers, 3[[[]]] How Exim delivers mail @section 3[[[]]]5 Delivery in detail When a message is to be delivered, the sequence of events is roughly as follows: @itemize @bullet @item If a system-wide filter file is specified, the message is passed to it. The filter may add recipients to the message, replace the recipients, discard the message, cause a new message to be generated, or cause the message delivery to fail. The format of the filter file is the same as for user filter files, described in the separate document entitled @dfn{Exim's interface to mail filtering}. Some additional features are available in system filters -- see chapter 47 for details. Note that a message is passed to the system filter only once per delivery attempt, however many recipients it has. However, if there are several delivery attempts because one or more addresses could not be immediately delivered, the system filter is run each time. The filter condition @dfn{first_delivery} can be used to detect this. @item Each recipient address is parsed and a check is made to see if it is local, by comparing the domain with the list in the @dfn{local_domains} option. This can contain wildcards and file lookups. @item If an address is local, it is offered to each configured director in turn until one is able to handle it. When a director cannot handle an address, it is said to @dfn{decline}. If no directors can handle the address, that is, if they all decline, the address is failed. Directors can be targeted at particular local domains, so several local domains can be processed entirely independently of each other. @item @cindex directing loop @cindex loop: directing A director that accepts an address may set up a local or a remote transport for it. The transport is not run at this time; the address is placed on a queue for the particular transport, to be run later. Alternatively, the director may generate one or more new addresses (typically from alias, forward, or filter files). New addresses are fed back into this process from the top, but in order to avoid loops, a director ignores any address which has an identically-named ancestor that was processed by itself. @item If an address is not local, it is offered to each configured router in turn, until one is able to handle it. If none can, the address is failed. @item A router that accepts an address may set up a transport for it, or may pass an altered address to subsequent routers, or it may discover that the address is a local address after all. This typically happens when a partial domain name is used and (for example) the DNS lookup is configured to try to extend such names. In this case, the address is passed to the directors. Exim can also be configured to do this for any domain whose lowest MX record or other routing information points to the local host. @item Routers normally set up remote transports for messages that are to be delivered to other machines. However, a router can pass a message to a local transport, and by this means such messages can be routed to transport mechanisms other than SMTP by means of pipes or files. @item When all the directing and routing is done, addresses that have been successfully handled are passed to their assigned transports. When local transports are doing real local deliveries, they handle only one address at a time, but if a local transport is being used as a pseudo-remote transport (for example, to collect batched SMTP messages for transmission by some other means) multiple addresses can be handled. Remote transports can always handle more than one address at once, but can be configured not to do so, or to restrict multiple addresses to the same domain. @item Each local delivery runs in a separate process under a non-privileged uid, and they are run in sequence. Exim can be configured so that remote deliveries run under a uid that is private to Exim, instead of running as root. By default the remote deliveries run one at a time in the main Exim process, but a configuration option is available to allow multiple remote deliveries for a single message to be run simultaneously, each in its own sub-process. @item When it is doing a queue run, Exim checks its retry database to see if there has been a previous temporary delivery failure for the address before running any local transport. If it finds one, it does not attempt a new delivery until the retry time for the address is reached. However, this happens only for delivery attempts that are part of a queue run. Local deliveries are always attempted when delivery immediately follows message reception. @item Remote transports do their own retry handling, since an address may be deliverable to one of a number of hosts, each of which may have a different retry time. If there have been previous temporary failures and no host has reached its retry time, no delivery is attempted, whether in a queue run or not. See chapter 33 for details of retry strategies. @item If there were any errors, a message is returned to an appropriate address (the sender in the common case), with details of the error for each failing address. Exim can be configured to send copies of error messages to other addresses. @item If one or more addresses suffered a temporary failure, the message is left on the queue, to be tried again later. Otherwise the spool files and message log are deleted, though the message log can optionally be preserved if required. @end itemize @cindex queue-runner @cindex delivery: deferral Delivery is said to be @dfn{deferred} when the message remains on the queue for a subsequent delivery attempt after a temporary failure. Such messages get processed again by queue-runner processes that are periodically started, either by an Exim daemon or via @dfn{cron} or by hand. Temporary failures may be detected during routing and directing as well as during the transport stage. Exim uses a set of configured rules to determine when next to retry the failing address (see chapter 33). @cindex delivery: failure These rules also specify when Exim should give up trying to deliver to the address, at which point it generates a failure report. When a delivery is not part of a queue run (typically an immediate delivery on receipt of a message), the directors are always run for local addresses, and local deliveries are always attempted, even if retry times are set for them. This makes for better behaviour if one particular message is causing problems (for example, causing quota overflow, or provoking an error in a filter file). If such a delivery suffers a temporary failure, the retry data gets updated as usual, for use by the next queue-runner process. @cindex delivery: failure report When a message cannot be delivered to some or all of its intended recipients, a delivery failure report is generated. All the addresses that failed in a given delivery attempt are listed in a single failure report. If a message has many recipients, it is possible for some addresses to fail in one delivery attempt and others to fail subsequently, giving rise to more than one failure report for a single message. The wording of delivery failure reports can be customized by the administrator. See chapter 39 for details. @cindex X-Failed-Recipients: header Delivery failure messages contain an @dfn{X-Failed-Recipients:} header, listing all failed addresses, for the benefit of programs that try to analyse such messages automatically. A failure report is normally sent to the sender of the original message, as obtained from the message's envelope. For incoming SMTP messages, this is the address given in the @sc{mail} command. However, when an address is expanded via a forward or alias file, an alternative address can be specified for delivery failures of the generated addresses. For a mailing list expansion (see chapter 42) it is common to direct failure reports to the manager of the list. If a failure report (either locally generated or received from a remote host) itself suffers a delivery failure, the message is left on the queue, but is `frozen', awaiting the attention of an administrator. There are options which can be used to make Exim discard such failure reports, or to keep them for only a short time. @node Temporary delivery failures, , Delivery in detail, 3[[[]]] How Exim delivers mail @section 3[[[]]]6 Temporary delivery failures There are many reasons why a message may not be immediately deliverable to a particular address. Failure to connect to a remote machine (because it, or the connection to it, is down) is one of the most common. Local deliveries may also be delayed if NFS files are unavailable, or if a mailbox is on a file system where the user is over quota. Exim can be configured to impose its own quotas on local mailboxes; where system quotas are set they will also apply. A machine that is connected to the Internet can normally deliver most mail straight away (the usual figure at Cambridge University is 98%). In its default configuration, Exim starts a delivery process whenever it receives a message, and usually this completes the entire delivery. This is a lightweight approach, avoiding the need for any centralized queue managing software. There are those who argue that a central message manager would be able to batch up messages for the same host and send them in a single SMTP call. I do not myself believe this would occur much in general, unless messages were significantly delayed in order to create a batch. However, if a host is unreachable for a period of time, a number of messages may be waiting for it by the time it recovers, and sending them in a single SMTP connection is clearly beneficial. Whenever a delivery to a remote host is deferred, Exim makes a note in its hints database, and whenever a successful SMTP delivery has happened, it looks to see if any other messages are waiting for the same host. If any are found, they are sent over the same SMTP connection, subject to a configuration limit as to the maximum number in any one connection. @node 4[[[]]] Building and installing Exim, The Exim command line, 3[[[]]] How Exim delivers mail, Top @chapter 4[[[]]] Building and installing Exim @cindex building Exim @sp 2 @menu * Unpacking:: * Multiple machine architectures and operating systems:: * DBM libraries:: * Pre-building configuration:: * Including TLS/SSL encryption support:: * Use of tcpwrappers:: * Including support for IPv6:: * The building process:: * Overriding build-time options for Exim:: * OS-specific header files:: * Overriding build-time options for the monitor:: * Installing commands and scripts:: * Installing info documentation:: * Setting up the spool directory:: * Testing:: * Switching Exim on:: * Exim on heavily loaded hosts:: * Stopping Exim on Solaris:: @end menu @node Unpacking, Multiple machine architectures and operating systems, 4[[[]]] Building and installing Exim, 4[[[]]] Building and installing Exim @section 4[[[]]]1 Unpacking Exim is distributed as a gzipped or bzipped tar file which, when upacked, creates a directory with the name of the current release (for example, @file{exim-3.30}) into which the following files are placed: @display @file{CHANGES} contains a reference to where changes are documented @file{LICENCE} the GNU General Public Licence @file{Makefile} top-level make file @file{NOTICE} conditions for the use of Exim @file{README} list of files, directories and simple build instructions @end display Other files whose names begin with @file{README} may also be present. The following subdirectories are created: @display @file{OS} OS-specific files @file{doc} documentation files @file{exim_monitor} source files for the Exim monitor @file{scripts} scripts used in the build process @file{src} remaining source files @file{util} independent utilities @end display Some utilities are contained in the @file{src} directory, and are built with the Exim binary; those distributed in the @file{util} directory are things like the log file analyser, which do not depend on any compile-time configuration. @node Multiple machine architectures and operating systems, DBM libraries, Unpacking, 4[[[]]] Building and installing Exim @section 4[[[]]]2 Multiple machine architectures and operating systems The building process for Exim is arranged to make it easy to build binaries for a number of different architectures and operating systems from the same set of source files. Compilation does not take place in the @file{src} directory. Instead, a @dfn{build directory} is created for each architecture and operating system. @cindex link, symbolic @cindex symbolic link Symbolic links to the sources are installed in this directory, which is where the actual building takes place. In most cases, Exim can discover the machine architecture and operating system for itself, but the defaults can be overridden if necessary. @node DBM libraries, Pre-building configuration, Multiple machine architectures and operating systems, 4[[[]]] Building and installing Exim @section 4[[[]]]3 DBM libraries @cindex DBM libraries Licensed versions of Unix normally contain a library of DBM functions operating via the `ndbm' interface, and this is what Exim expects by default. Free versions of Unix seem to vary in what they contain as standard. In particular, some versions of Linux have no default DBM library, and different distributors have chosen to bundle different libraries with their packaged versions. However, the more recent releases seem to have standardised on the Berkeley DB library. Different DBM libraries have different conventions for naming the files they use. When a program opens a file called @file{dbmfile}, there are four possibilities: @enumerate @item A traditional ndbm implementation, such as that supplied as part of Solaris 2, operates on two files called @file{dbmfile.dir} and @file{dbmfile.pag}. @item The GNU library, @dfn{gdbm}, operates on a single file, but makes two different hard links to it with names @file{dbmfile.dir} and @file{dbmfile.pag}. @item @cindex Berkeley DB The Berkeley DB package, if called via its ndbm compatibility interface, operates on a single file called @file{dbmfile.db}, but otherwise looks to the programmer exactly the same as the traditional ndbm implementation. @item If the Berkeley package is used in its native mode, it operates on a single file called @file{dbmfile}; the programmer's interface is somewhat different to the traditional ndbm interface. @item @cindex tdb Yet another DBM library, called tdb, has become available from @example http://download.sourceforge.net/tdb @end example It has its own interface, and also operates on a single file. @end enumerate @cindex USE_DB Exim and its utilities can be compiled to use any of these interfaces. By default it assumes an interface of type (1), though some operating system configuration files default to assuming (4). In order to use the Berkeley DB package in native mode, it is necessary to set @sc{use_db} in an appropriate configuration file, and to use tdb you must set @sc{use_tdb}. It may also be necessary to set @sc{dbmlib}, as in one of these lines: @example DBMLIB = -ldb DBMLIB = -ltdb @end example To complicate things further, there are now three very different versions of the Berkeley DB package. Version 1.85 has been stable for quite some time, releases 2.x were current for a while, but the latest versions are numbered 3.x. Releases 2 and 3 are very different internally and externally from the 1.85 release. All versions of Berkeley DB can be obtained from @example http://www.sleepycat.com/ @end example but maintenance of version 1.85 has been phased out, and it may not compile on some systems. Maintenance for the 2.x releases will cease shortly. There is further discussion about the various DBM libraries in the file @file{doc/dbm.discuss.txt}. @node Pre-building configuration, Including TLS/SSL encryption support, DBM libraries, 4[[[]]] Building and installing Exim @section 4[[[]]]4 Pre-building configuration @cindex pre-building configuration @cindex configuration: pre-building @cindex Local/Makefile @cindex src/EDITME Before building Exim, a local configuration file that specifies options independent of any operating system has to be created with the name @file{Local/Makefile}. A template for this file is supplied as the file @file{src/EDITME}, and it contains full descriptions of all the option settings therein. If you are building Exim for the first time, the simplest thing to do is to copy @file{src/EDITME} to @file{Local/Makefile}, then read it and edit it appropriately. Default values are supplied for everything except the settings that specify the locations of the run time configuration file and the directory for holding Exim binaries. These must be given, as Exim will not build without them. There are a few parameters that can be specified either at build time or at run time to enable the same binary to be used on a number of different machines. However, if the locations of Exim's spool directory and log file directory (if not within the spool directory) are fixed, it is recommended that you specify them in @file{Local/Makefile} instead of at run time so that errors detected early in Exim's execution (such as a malformed configuration file) can be logged. @cindex Local/eximon.conf @cindex exim_monitor/EDITME If you are going to build the Exim monitor, a similar configuration process is required. The file @file{exim_monitor/EDITME} must be edited appropriately for your installation and saved under the name @file{Local/eximon.conf}. If you are happy with the default settings described in @file{exim_monitor/EDITME}, @file{Local/eximon.conf} can be empty, but it must exist. This is all the configuration that is needed in straightforward cases for known operating systems. However, the building process is set up so that it is easy to override options that are set by default or by operating-system-specific configuration files, for example to change the name of the C compiler, which defaults to @dfn{gcc}. See section 4.9 below for details of how to do this. @node Including TLS/SSL encryption support, Use of tcpwrappers, Pre-building configuration, 4[[[]]] Building and installing Exim @section 4[[[]]]5 Including TLS/SSL encryption support @cindex TLS: @cindex encryption @cindex SUPPORT_TLS Exim can be built to support encrypted SMTP connections, using the @sc{starttls} command (RFC 2487). Before you can do this, you must install the OpenSSL library, which Exim uses for this purpose. There is no cryptographic code in Exim itself. Once OpenSSL is installed, you can set @example SUPPORT_TLS = yes TLS_LIBS=-lssl -lcrypto @end example in @file{Local/Makefile}. You may also need to specify the locations of the OpenSSL library and include files. For example: @example SUPPORT_TLS = yes TLS_LIBS=-L/usr/local/openssl/lib -lssl -lcrypto TLS_INCLUDE=-I/usr/local/openssl/include/ @end example You don't need to set @sc{tls_include} if the relevant directory is already specified in @sc{include}. @node Use of tcpwrappers, Including support for IPv6, Including TLS/SSL encryption support, 4[[[]]] Building and installing Exim @section 4[[[]]]6 Use of tcpwrappers @cindex tcpwrappers @cindex USE_TCP_WRAPPERS Exim can be linked with the @dfn{tcpwrappers} library in order to check incoming SMTP calls using the @dfn{tcpwrappers} control files. This may be a convenient alternative to Exim's own checking facilities for installations that are already making use of @dfn{tcpwrappers} for other purposes. To do this, you should set @sc{use_tcp_wrappers} in @file{Local/Makefile}, arrange for the file @file{tcpd.h} to be available at compile time, and also ensure that the library @file{libwrap.a} is available at link time, typically by including -@dfn{lwrap} in @sc{extralibs_exim}. For example, if @dfn{tcpwrappers} is installed in @file{/usr/local}, you might have @example USE_TCP_WRAPPERS=yes CFLAGS=-O -I/usr/local/include EXTRALIBS_EXIM=-L/usr/local/lib -lwrap @end example in @file{Local/Makefile}. The name to use in the @dfn{tcpwrappers} control files is `exim'. For example, the line @example exim : LOCAL 192.168.0. .friendly.domain @end example in your @file{/etc/hosts.allow} file allows connections from the local host, from the subnet 192.168.0.0/24, and from all hosts in @dfn{friendly.domain}. All other connections are denied. Consult the @dfn{tcpwrappers} documentation for further details. @node Including support for IPv6, The building process, Use of tcpwrappers, 4[[[]]] Building and installing Exim @section 4[[[]]]7 Including support for IPv6 @cindex IPv6 Exim contains code for use on systems that have IPv6 support. Setting @sc{have_ipv6=yes} in @file{Local/Makefile} causes the IPv6 code to be included; it may also be necessary to set @sc{ipv6_include} and @sc{ipv6_libs} on systems where the IPv6 support is not fully integrated into the normal include and library files. @node The building process, Overriding build-time options for Exim, Including support for IPv6, 4[[[]]] Building and installing Exim @section 4[[[]]]8 The building process @cindex make @cindex build directory Once @file{Local/Makefile} (and @file{Local/eximon.conf}, if required) have been created, run @dfn{make} at the top level. It determines the architecture and operating system types, and creates a build directory if one does not exist. For example, on a Sun system running Solaris 2.5.1, the directory @file{build-SunOS5-5.5.1-sparc} is created. @cindex link, symbolic @cindex symbolic link Symbolic links to relevant source files are installed in the build directory. If this is the first time @dfn{make} has been run, it calls a script which builds a make file inside the build directory, using the configuration files from the @file{Local} directory. The new make file is then passed to another instance of @dfn{make} which does the real work, building a number of utility scripts, and then compiling and linking the binaries for the Exim monitor (if configured), a number of utilities, and finally Exim itself. The command @dfn{make makefile} can be used to force a rebuild of the make file in the build directory, should this ever be necessary. If you have problems building Exim, check for any comments there may be in the @file{README} file concerning your operating system, and also take a look at the FAQ, where some common problems are covered. @node Overriding build-time options for Exim, OS-specific header files, The building process, 4[[[]]] Building and installing Exim @section 4[[[]]]9 Overriding build-time options for Exim @cindex overriding build-time options The main make file that is created at the beginning of the building process consists of the concatenation of a number of files which set configuration values, followed by a fixed set of @dfn{make} instructions. If a value is set more than once, the last setting overrides any previous ones. This provides a convenient way of overriding defaults. The files that are concatenated are, in order: @example OS/Makefile-Default OS/Makefile-<@dfn{ostype}> Local/Makefile Local/Makefile-<@dfn{ostype}> Local/Makefile-<@dfn{archtype}> Local/Makefile-<@dfn{ostype}>-<@dfn{archtype}> OS/Makefile-Base @end example @cindex Local/Makefile where <@dfn{ostype}> is the operating system type and <@dfn{archtype}> is the @cindex operating system type @cindex architecture type architecture type. @file{Local/Makefile} is required to exist, and the building process fails if it is absent. The other three @file{Local} files are optional, and are often not needed. The values used for <@dfn{ostype}> and <@dfn{archtype}> are obtained from scripts called @file{scripts/os-type} and @file{scripts/arch-type} respectively. If either of the environment variables @sc{exim_ostype} or @sc{exim_archtype} is set, their values are used, thereby providing a means of forcing particular settings. Otherwise, the scripts try to get values from the @dfn{uname} command. If this fails, the shell variables @sc{ostype} and @sc{archtype} are inspected. A number of @dfn{ad hoc} transformations are then applied, to produce the standard names that Exim expects. You can run these scripts directly from the shell in order to find out what values are being used on your system. @file{OS/Makefile-Default} contains comments about the variables that are set therein. Some (but not all) are mentioned below. If there is something that needs changing, review the contents of this file and the contents of the make file for your operating system (@file{OS/Makefile-<@dfn{ostype}>}) to see what the default values are. If you need to change any of the values that are set in @file{OS/Makefile-Default} or in @file{OS/Makefile-<@dfn{ostype}>}, or to add any new definitions, do so by putting the new values in an appropriate @file{Local} file. For example, to specify that the C compiler is called @dfn{cc} rather than @dfn{gcc} @cindex cc compiler @cindex gcc @cindex compiler name when compiling in the OSF1 operating system, and that it is to be to be called with the flag -@dfn{std1}, create a file called @file{Local/Makefile-OSF1} containing the lines @example CC=cc CFLAGS=-std1 @end example This makes it easy to transfer your configuration settings to new versions of Exim simply by copying the contents of the @file{Local} directory. @cindex NIS @cindex NIS+ @cindex LDAP @cindex lookup: inclusion in binary Exim contains support for doing LDAP, NIS, NIS+, and other kinds of file lookup, but not all systems have these components installed, so the default is not to include the relevant code in the binary. All the different kinds of file and database lookup that Exim supports are implemented as separate code modules which are included only if the relevant compile-time options are set. In the case of LDAP, NIS, and NIS+, the settings for @file{Local/Makefile} are: @example LOOKUP_LDAP=yes LOOKUP_NIS=yes LOOKUP_NISPLUS=yes @end example and similar settings apply to the other lookup types. In most cases the relevant include files and interface libraries need to be installed before compiling Exim. @cindex cdb However, in the case of cdb, which is included in the binary only if @example LOOKUP_CDB=yes @end example is set, the code is entirely contained within Exim, and no external include files or libraries are required. When a lookup type is not included in the binary, attempts to configure Exim to use it cause configuration errors. @cindex Perl: embedded Exim can be linked with an embedded Perl interpreter, allowing Perl subroutines to be called during string expansion. To enable this facility, @example EXIM_PERL=perl.o @end example must be defined in @file{Local/Makefile}. Details of this facility are given in chapter 10. @cindex X11 libraries The location of the X11 libraries is something that varies a lot between operating systems, and of course there are different versions of X11 to cope with. The following three variables are set in @file{OS/Makefile-Default}: @example X11=/usr/X11R5 XINCLUDE=-I$(X11)/include XLFLAGS=-L$(X11)/lib @end example These are overridden in some of the operating-system configuration files. For example, in @file{OS/Makefile-SunOS5} there is @example X11=/usr/openwin XINCLUDE=-I$(X11)/include XLFLAGS=-L$(X11)/lib -R$(X11)/lib @end example If you need to override the default setting for your operating system, place a definition of all three of these variables into your @file{Local/Makefile-<@dfn{ostype}>} file. @cindex EXTRALIBS If you need to add any extra libraries to the link steps, these can be put in a variable called @sc{extralibs}, which appears in all the link commands, but by default is not defined. In contrast, @sc{extralibs_exim} is used only on the command for linking the main Exim binary, and not for any associated utilities. There is also @sc{dbmlib}, which appears in the link commands for binaries that use DBM functions (see also section 4.3). Finally, there is @sc{extralibs_eximon}, which appears only in the link step for the Exim monitor binary, and which can be used, for example, to include additional X11 libraries. @cindex STDERR_FILE Another variable which is not normally defined is @sc{stderr_file}. This defines a file to which debugging output is written if the -@dfn{df} flag is set, and is of use when running Exim under @dfn{inetd}. @cindex ERRNO_QUOTA Yet another variable which should not normally be needed is @sc{errno_quota}. Exim needs to know which error the operating system gives when writing to a file fails because the user is over quota. POSIX specifies an error called @sc{edquot} and @cindex EDQUOT this is present in the latest versions of all the systems Exim has been ported to at the time of writing. However, it is not present in earlier versions of SunOS5, which use @sc{enospc} instead. @cindex ENOSPC The code of Exim defaults to using @sc{edquot} if it is defined, and @sc{enospc} otherwise. You should set @sc{errno_quota} only if your system uses some completely different error code. @cindex editing configuration files @cindex configuration file: editing The make file copes with rebuilding Exim correctly if any of the configuration files are edited. However, if an optional configuration file is deleted, it is necessary to touch the associated non-optional file (that is, @file{Local/Makefile} or @file{Local/eximon.conf}) before rebuilding. @node OS-specific header files, Overriding build-time options for the monitor, Overriding build-time options for Exim, 4[[[]]] Building and installing Exim @section 4[[[]]]10 OS-specific header files @cindex os.h @cindex C header files @cindex header files The @file{OS} directory contains a number of files with names of the form @file{os.h-<@dfn{ostype}>}. These are system-specific C header files that should not normally need to be changed. There is a list of macro settings that are recognized in the file @file{OS/os.configuring}, which should be consulted if you are porting Exim to a new operating system. @node Overriding build-time options for the monitor, Installing commands and scripts, OS-specific header files, 4[[[]]] Building and installing Exim @section 4[[[]]]11 Overriding build-time options for the monitor A similar process is used for overriding things when building the Exim monitor, where the files that are involved are @example OS/eximon.conf-Default OS/eximon.conf-<@dfn{ostype}> Local/eximon.conf Local/eximon.conf-<@dfn{ostype}> Local/eximon.conf-<@dfn{archtype}> Local/eximon.conf-<@dfn{ostype}>-<@dfn{archtype}> @end example @cindex Local/eximon.conf As with Exim itself, the final three files need not exist, and in this case the @file{OS/eximon.conf-<@dfn{ostype}>} file is also optional. The default values in @file{OS/eximon.conf-Default} can be overridden dynamically by setting environment variables of the same name, preceded by @sc{eximon_}. For example, setting @sc{eximon_log_depth} in the environment overrides the value of @sc{log_depth} at run time. @node Installing commands and scripts, Installing info documentation, Overriding build-time options for the monitor, 4[[[]]] Building and installing Exim @section 4[[[]]]12 Installing commands and scripts @cindex installing exim @cindex BIN_DIRECTORY The script @file{scripts/exim_install} copies binaries and utility scripts into the directory whose name is specified by the @sc{bin_directory} setting in @file{Local/Makefile}. Files are copied only if they are newer than any versions already in the binary directory, and old versions are renamed by adding the suffix @file{.O} to their names. The command @dfn{make install} runs the @dfn{exim_install} script with no arguments. It can be run independently with arguments specifying which files are to be copied, from within a build directory. For example, @example (cd build-SunOS5-sparc; ../scripts/exim_install exim) @end example copies just the main binary file. The main @dfn{exim} binary is required to be owned by root and setuid, @cindex setuid for normal configurations. In some special cases (for example, if a host is doing no local deliveries) is is possible to run Exim in other ways. If the binary is run by a root process, the effect is the same as if it were setuid root. The install script tries to set root as the owner of the main binary, and to make it setuid. It should therefore normally be run as root. If you want to see what the script will do before running it for real, use the -@dfn{n} option (for which root is not needed): @example (cd build-SunOS5-5.5.1-sparc; ../scripts/exim_install -n) @end example Exim's run time configuration file is named by the @sc{configure_file} setting @cindex CONFIGURE_FILE in @file{Local/Makefile}. If this file does not exist, the default configuration file @file{src/configure.default} is copied there by the installation script. If a run time configuration file already exists, it is left alone. The default configuration uses the local host's name as the only local domain, and is set up to do local deliveries into the shared directory @file{/var/mail}, running as the local user. Aliases in @file{/etc/aliases} and @file{.forward} files in users' home directories are supported, but no NIS or NIS+ support is configured. Remote domains are routed using the DNS, with delivery over SMTP. @node Installing info documentation, Setting up the spool directory, Installing commands and scripts, 4[[[]]] Building and installing Exim @section 4[[[]]]13 Installing info documentation Not all systems use the GNU @dfn{info} system for documentation, and for this reason, the Texinfo source of Exim's documentation is not included in the main distribution. Instead it is available separately from the ftp site (see section 1.2). If you have defined @sc{info_directory} in @file{Local/Makefile} and the Texinfo source of the documentation is found in the source tree, running @dfn{make install} automatically builds the info files and installs them. @node Setting up the spool directory, Testing, Installing info documentation, 4[[[]]] Building and installing Exim @section 4[[[]]]14 Setting up the spool directory @cindex spool: directory When it starts up, Exim tries to create its spool directory if it does not exist. If a specific Exim uid and gid are specified, these are used for the owner and group of the spool directory. Sub-directories are automatically created in the spool directory as necessary. @node Testing, Switching Exim on, Setting up the spool directory, 4[[[]]] Building and installing Exim @section 4[[[]]]15 Testing @cindex testing: Having installed Exim, you can check that the run time configuration file is syntactically valid by running the command @example exim -bV @end example If there are any errors in the configuration file, Exim will output error messages. Otherwise it just outputs the version number and build date. Some simple routing tests can be done by using the address testing option. For example, @example exim -v -bt <@dfn{local username}> @end example should verify that it recognizes a local mailbox, and @example exim -v -bt <@dfn{remote address}> @end example a remote one. Then try getting it to deliver mail, both locally and remotely. This can be done by passing messages directly to Exim, without going through a user agent. For example: @example exim postmaster@@your.domain From: user@@your.domain To: postmaster@@your.domain Subject: Testing Exim This is a test message. ^D @end example @cindex delivery: problems with If you encounter problems, look at Exim's log files (@dfn{mainlog} and @dfn{paniclog}) to see if there is any relevant information there. Another source of information is running Exim with debugging turned on, by specifying the -@dfn{d} option. The larger the number after -@dfn{d} (up to 9), the more information is output. With -@dfn{d2}, for example, the sequence of directors or routers that process an address is output. If there's a message stuck on Exim's spool, you can force a delivery with debugging turned on by a command of the form @example exim -d9 -M <@dfn{message-id}> @end example @cindex `sticky' bit @cindex lock files One specific problem that has shown up on some sites is the inability to do local deliveries into a single shared mailbox directory that does not have the `sticky bit' set on it. By default, Exim tries to create a lock file before writing to a mailbox file, and if it cannot create the lock file, the delivery is deferred. You can get round this either by setting the `sticky bit' on the directory, or by setting a specific group for local deliveries and allowing that group to create files in the directory (see the comments above the @dfn{local_delivery} transport in the default configuration file). Another approach is to configure Exim not to use lock files, but just to rely on @dfn{fcntl()} locking instead. However, you should do this only if all user agents also use @dfn{fcntl()} locking. For further discussion of locking issues, see chapter 15. One thing that cannot be tested on a system that is already running a mailer is the receipt of incoming SMTP mail on the standard SMTP port. However, the -@dfn{oX} option can be used to run an Exim daemon that listens on some other port, or @dfn{inetd} can be used to do this. The -@dfn{bh} option can be used to check out any policy controls on incoming SMTP mail. Testing a new version on a system that is already running Exim can most easily be done by building a binary with a different @sc{configure_file} setting. From within the run time configuration, all other file and directory names that Exim uses can be altered, in order to keep it entirely clear of the production version. @node Switching Exim on, Exim on heavily loaded hosts, Testing, 4[[[]]] Building and installing Exim @section 4[[[]]]16 Switching Exim on @cindex switching on Building and installing Exim does not of itself put it in general use. The name by which the system message transfer agent is called by mail user agents is either @file{/usr/lib/sendmail}, or @file{/usr/sbin/sendmail} (depending on the operating system), and it is necessary to make this name point to the @dfn{exim} binary in order to get them to use it. This is normally done by renaming any existing file and making @file{/usr/lib/sendmail} or @file{/usr/sbin/sendmail} @cindex symbolic link @cindex link, symbolic a symbolic link to the @dfn{exim} binary. It is a good idea to remove any setuid privilege and executable status from the old MTA. It is then necessary to stop and restart the mailer daemon, if one is running. [(font color=green)] You should consider what to tell your users about the change of MTA. Exim may have different capabilities to what was previously running, and there are various operational differences such as the text of messages produced by command line options and in bounce messages. If you allow your users to make use of Exim's filtering capabilities, you should make the document entitled @dfn{Exim's interface to mail filtering} available to them. [(/font)] @node Exim on heavily loaded hosts, Stopping Exim on Solaris, Switching Exim on, 4[[[]]] Building and installing Exim @section 4[[[]]]17 Exim on heavily loaded hosts @cindex load, heavy @cindex host: heavily loaded @cindex local nameserver If you are running Exim on a heavily loaded host you should consider installing a current release of @dfn{bind} (from http://www.isc.org) as caching nameserver, either locally or on a nearby host with a fast network connection. You should also consider enabling Exim's @dfn{split_spool_directory} if you expect to have large numbers of messages awaiting delivery. @node Stopping Exim on Solaris, , Exim on heavily loaded hosts, 4[[[]]] Building and installing Exim @section 4[[[]]]18 Stopping Exim on Solaris The standard command for stopping the mailer daemon on Solaris is @example /etc/init.d/sendmail stop @end example If @file{/usr/lib/sendmail} has been turned into a symbolic link, this script fails to stop Exim because it uses the command @dfn{ps -e} and greps the output for the text `sendmail'; this is not present because the actual program name (that is, `exim') is given by the @dfn{ps} command with these options. A fix that appears to work on Solaris 2.5 and above is to change the script so that the @dfn{ps} command reads @example ps -e -o pid,comm @end example which causes the name by which the daemon was started (that is, @file{/usr/lib/sendmail}) to be output. However, this fails if the daemon has been restarted with @sc{sighup} because Exim restarts itself using the real file name. A better solution is to replace the line that finds the process id with something like @example pid=`cat /var/spool/exim/exim-daemon.pid` @end example to obtain the daemon's pid directly from the file that Exim saves it in. See the description of the -@dfn{bd} option for details of where Exim writes the daemon's process id file. @node 5[[[]]] The Exim command line, File and database lookups, 4[[[]]] Building and installing Exim, Top @chapter 5[[[]]] The Exim command line @cindex command line options @cindex options: command line Exim's command line takes the standard Unix form of a sequence of options, each starting with a hyphen character, followed by a number of arguments. The options are compatible with the main options of Sendmail, and there are also some additional options, some of which are compatible with Smail 3. Certain combinations of options do not make sense, and provoke an error if used. The form of the arguments depends on which options are set. @sp 2 @menu * Setting options by program name:: * Trusted and admin users:: * Command line options:: @end menu @node Setting options by program name, Trusted and admin users, 5[[[]]] The Exim command line, 5[[[]]] The Exim command line @section 5[[[]]]1 Setting options by program name @cindex mailq If Exim is called under the name @dfn{mailq}, it behaves as if the option -@dfn{bp} were present before any other options. This is for compatibility with some systems that contain a command of that name in one of the standard libraries, @cindex symbolic link @cindex link, symbolic symbolically linked to @file{/usr/lib/sendmail} or @file{/usr/sbin/sendmail}. @cindex rsmtp If Exim is called under the name @dfn{rsmtp} it behaves as if the option -@dfn{bS} were present before any other options, for compatibility with Smail. The -@dfn{bS} option is used for reading in a number of messages in batched SMTP format. @cindex rmail If Exim is called under the name @dfn{rmail} it behaves as if the -@dfn{i} and -@dfn{oee} options were present before any other options, for compatibility with Smail. The name @dfn{rmail} is used as an interface by some UUCP systems. @cindex runq @cindex queue-runner If Exim is called under the name @dfn{runq} it behaves as if the option -@dfn{q} were present before any other options, for compatibility with Smail. The -@dfn{q} option causes a single queue-runner process to be started. @cindex newaliases @cindex alias file: building If Exim is called under the name @dfn{newaliases} it behaves as if the option -@dfn{bi} were present before any other options, for compatibility with Sendmail. This option is used for rebuilding Sendmail's alias file. Exim does not have the concept of a single alias file, but can be configured to run a given command if called with the -@dfn{bi} option. @node Trusted and admin users, Command line options, Setting options by program name, 5[[[]]] The Exim command line @section 5[[[]]]2 Trusted and admin users @cindex trusted user @cindex admin user @cindex users: trusted @cindex users: admin Some Exim options are available only to @dfn{trusted users} and others are available only to @dfn{admin users}. In the description below, the phrases `Exim user' and `Exim group' mean the user and group defined by @sc{exim_uid} and @sc{exim_gid} in @file{Local/Makefile} or set by the @dfn{exim_user} and @dfn{exim_group} options. These do not necessarily have to use the name `exim'. @itemize @bullet @item A trusted user is root or the Exim user or any user listed in the @dfn{trusted_users} configuration option, or any user for whom the currently set group is the Exim group (if defined) or whose current group or any supplementary group is one of those listed in the @dfn{trusted_groups} configuration option. Trusted users are always permitted to use the -@dfn{f} option or a leading `From ' line to specify the envelope sender of a message that is passed to Exim through the local interface (see the -@dfn{bm} and -@dfn{f} options below). For a trusted user, there is never any check on the contents of the @dfn{From:} header line, and a @dfn{Sender:} line is never added. Furthermore, any existing @dfn{Sender:} line in incoming local (non-TCP/IP) messages is not removed. Trusted users may also specify a host name, host address, interface address, protocol name, and ident value. Thus they are able to insert messages into Exim's queue locally that have the characteristics of messages received from a remote host. Untrusted users may in some circumstances use -@dfn{f}, but can never set the other values that trusted users can. @cindex From: header @cindex Sender: header @dfn{From:} headers are not checked to see if @dfn{Sender:} is needed when the caller is trusted. @item An admin user is root or the Exim user or any user that is a member of the Exim group (if defined), or of any group listed in the @dfn{admin_groups} configuration option. The current group does not have to be one of these groups. Admin users are permitted to operate on messages in the queue, for example, to force delivery failures. It is also necessary to be an admin user in order to see the full information provided by the Exim monitor, and full debugging output. By default, the use of the -@dfn{M}, -@dfn{q}, -@dfn{R}, and -@dfn{S} options to cause Exim to attempt delivery of messages on its queue is restricted to admin users. However, this restriction can be relaxed by setting the @dfn{prod_requires_admin} option false (that is, specifying @dfn{no_prod_requires_admin}). Similarly, the use of the -@dfn{bp} option to list all the messages in the queue is restricted to admin users unless @dfn{queue_list_requires_admin} is set false. @end itemize @node Command line options, , Trusted and admin users, 5[[[]]] The Exim command line @section 5[[[]]]3 Command line options The command options are described in alphabetical order below. @sp 2 @menu * --:: * -B<@dfn{type}>:: * -bd:: * -be:: * -bF <@dfn{filename}>:: * -bf <@dfn{filename}>:: * -bh <@dfn{IP address}>:: * -bi:: * -bm:: * -bp:: * -bpa:: * -bpc:: * -bpr:: * -bpra:: * -bpru:: * -bpu:: * -bP:: * -brt:: * -brw:: * -bS:: * -bs:: * -bt:: * -bV:: * -bv:: * -bvs:: * -C <@dfn{filename}>:: * -D<@dfn{macro}>=<@dfn{value}>:: * -d<@dfn{number}>:: * -df:: * -dm:: * -dropcr:: * -E:: * -e@dfn{x}:: * -F <@dfn{string}>:: * -f <@dfn{address}>:: * -h <@dfn{number}>:: * -i:: * -M <@dfn{message id}> <@dfn{message id}>:: * -Mar <@dfn{message id}> <@dfn{address}> <@dfn{address}>:: * -MC <@dfn{transport}> <@dfn{hostname}> <@dfn{sequence number}> <@dfn{message id}>:: * -MCA:: * -MCQ <@dfn{process id}> <@dfn{pipe fd}>:: * -MCS:: * -MCT:: * -Mc <@dfn{message id}> <@dfn{message id}>:: * -Meb <@dfn{message id}>:: * -Mes <@dfn{message id}> <@dfn{address}>:: * -Mf <@dfn{message id}> <@dfn{message id}>:: * -Mg <@dfn{message id}> <@dfn{message id}>:: * -Mmad <@dfn{message id}> <@dfn{message id}>:: * -Mmd <@dfn{message id}> <@dfn{address}> <@dfn{address}>:: * -Mrm <@dfn{message id}> <@dfn{message id}>:: * -Mt <@dfn{message id}> <@dfn{message id}>:: * -Mvb <@dfn{message id}>:: * -Mvh <@dfn{message id}>:: * -Mvl <@dfn{message id}>:: * -m:: * -N:: * -n:: * -oA <@dfn{file name}>:: * -oB <@dfn{n}>:: * -odb:: * -odf:: * -odi:: * -odq:: * -odqr:: * -odqs:: * -oee:: * -oem:: * -oep:: * -oeq:: * -oew:: * -oi:: * -oitrue:: * -oMa <@dfn{host address}>:: * -oMas <@dfn{address}>:: * -oMai <@dfn{string}>:: * -oMi <@dfn{interface address}>:: * -oMr <@dfn{protocol name}>:: * -oMs <@dfn{host name}>:: * -oMt <@dfn{ident string}>:: * -om:: * -oo:: * -or <@dfn{time}>:: * -ov:: * -oX <@dfn{number}>:: * -pd:: * -ps:: * -q:: * -q <@dfn{time}>:: * -qf:: * -qff:: * -qfl:: * -qffl:: * -ql:: * -qq:: * -qR<@dfn{flags}> <@dfn{string}>:: * -qS<@dfn{flags}> <@dfn{string}>:: * -R<@dfn{flags}> <@dfn{string}>:: * -r:: * -S<@dfn{flags}> <@dfn{string}>:: * -t:: * -U:: * -v:: * -x:: @end menu @node --, -B<@dfn{type}>, Command line options, Command line options @findex -- @unnumberedsubsec -- @cindex options: command line, terminating This is a pseudo-option whose only purpose is to terminate the options and therefore to cause subsequent command line items to be treated as arguments rather than options, even if they begin with hyphens. @node -B<@dfn{type}>, -bd, --, Command line options @findex -B<@dfn{type}> @unnumberedsubsec -B<@dfn{type}> @cindex 8-bit characters @cindex top bit This is a Sendmail option for selecting 7 or 8 bit processing. Exim is entirely 8-bit clean; it ignores this option. @node -bd, -be, -B<@dfn{type}>, Command line options @findex -bd @unnumberedsubsec -bd @cindex daemon Run Exim as a daemon, awaiting incoming SMTP connections. This option can be used only by an admin user. If either of the -@dfn{d} or -@dfn{dm} options are set, the daemon does not disconnect from the controlling terminal. By default, Exim listens for incoming connections on all the host's interfaces, but it can be restricted to specific interfaces by setting the @dfn{local_interfaces} option in the configuration file. The standard SMTP port is used, but this can be varied by means of the @dfn{daemon_smtp_port} configuration option or the -@dfn{oX} command line option. Most commonly, the -@dfn{bd} option is combined with the -@dfn{q}<@dfn{time}> option, to cause periodic queue runs to happen as well. @cindex daemon, process id @cindex pid, of daemon @cindex queue-runner The process id of a daemon that is both listening on the standard SMTP port and periodically starting queue runners is written to a file called @file{exim-daemon.pid} in Exim's spool directory. If a non-standard port is used, the file name is @file{exim-daemon.<@dfn{port-number}>.pid}. If a daemon is run with only one of -@dfn{bd} or -@dfn{q}<@dfn{time}>, that option is added on to the end of the file name, allowing sites that run two separate daemons to distinguish them. It is possible to change the directory in which these pid files are written by changing the setting of @sc{pid_file_path} in @file{Local/Makefile}. The files are written while Exim is still running as root. Further details are given in the comments in @file{src/EDITME}. @cindex SIGHUP The @sc{sighup} signal can be used to cause the daemon to re-exec itself. This should be done whenever Exim's configuration file is changed, or a new version of Exim is installed. It is not necessary to do this when other files (for example, alias files) are changed. @node -be, -bF <@dfn{filename}>, -bd, Command line options @findex -be @unnumberedsubsec -be Run Exim in expansion testing mode. Exim discards its root privilege, to prevent ordinary users from using this mode to read otherwise inaccessable files. If no arguments are given, it runs interactively, prompting for lines of data. Each argument (or data line) is passed through the string expansion mechanism, and the result is output. Variable values from the configuration file (for example, $@dfn{qualify_domain}) are available, but no message-specific values (such as $@dfn{domain}) are set because no message is being processed. @node -bF <@dfn{filename}>, -bf <@dfn{filename}>, -be, Command line options @findex -bF <@dfn{filename}> @unnumberedsubsec -bF <@dfn{filename}> @cindex system filter, testing This option is the same as -@dfn{bf} except that it assumes that the filter being tested is a system filter. The additional commands that are available only in system filters are recognized. @node -bf <@dfn{filename}>, -bh <@dfn{IP address}>, -bF <@dfn{filename}>, Command line options @findex -bf <@dfn{filename}> @unnumberedsubsec -bf <@dfn{filename}> @cindex filter: testing @cindex testing: filter file @cindex forward file: testing @cindex testing: forward file Run Exim in filter testing mode; the file is the filter file to be tested, and a test message must be supplied on the standard input. If there are no message-dependent tests in the filter, an empty file can be supplied. If a system filter file is being tested, -@dfn{bF} should be used instead of -@dfn{bf}. If the test file does not begin with the special line @example # Exim filter @end example then it is taken to be a normal @file{.forward} file, and is tested for validity under that interpretation. The result of this command, provided no errors are detected, is a list of the actions that Exim would try to take if presented with the message for real. More details of filter testing are given in the separate document entitled @dfn{Exim's interface to mail filtering}. When testing a filter file, the envelope sender can be set by the -@dfn{f} option, or by a `From ' line at the start of the test message. Various parameters that would normally be taken from the envelope recipient address of the message can be set by means of additional command line options. These are: @example -@dfn{bfd} <@dfn{domain}> default is the qualify domain -@dfn{bfl} <@dfn{local_part}> default is the logged in user -@dfn{bfp} <@dfn{local_part_prefix}> default is null -@dfn{bfs} <@dfn{local_part_suffix}> default is null @end example The local part should always be set to the incoming address with any prefix or suffix stripped, because that is how it appears when a message is actually being delivered. @node -bh <@dfn{IP address}>, -bi, -bf <@dfn{filename}>, Command line options @findex -bh <@dfn{IP address}> @unnumberedsubsec -bh <@dfn{IP address}> @cindex testing: incoming SMTP @cindex SMTP: testing incoming @cindex testing: relay control @cindex relaying: testing configuration This option runs a fake SMTP session as if from the given IP address, using the standard input and output. The IP address may include a port number at the end, after full stop. For example: @example exim -bh 10.9.8.7.1234 exim -bh fe80::a00:20ff:fe86:a061.5678 @end example Comments as to what is going on are written to the standard error file. These include lines beginning with `LOG' for anything that would have been logged. This facility is for testing configuration options for blocking hosts and/or senders and for checking on relaying control. Messages supplied during the testing session are discarded, and nothing is written to any of the real log files. There may be pauses when DNS (and other) lookups are taking place, and of course these may time out. The -@dfn{oMi} option can be used to specify a specific IP interface if this is important. @node -bi, -bm, -bh <@dfn{IP address}>, Command line options @findex -bi @unnumberedsubsec -bi @cindex alias file: building Sendmail interprets the -@dfn{bi} option as a request to rebuild its alias file. Exim does not have the concept of a single alias file, and so it cannot mimic this behaviour. However, calls to @dfn{/usr/lib/sendmail -bi} tend to appear in various scripts such as NIS make files, so the option must be recognized. If -@dfn{bi} is encountered, the command specified by the @dfn{bi_command} configuration option is run, under the uid and gid of the caller of Exim. If the -@dfn{oA} option is used, its value is passed to the command as an argument. The command set by @dfn{bi_command} may not contain arguments. The command can use the @dfn{exim_dbmbuild} utility, or some other means, to rebuild alias files if this is required. If the @dfn{bi_command} option is not set, calling Exim with -@dfn{bi} is a no-op. @node -bm, -bp, -bi, Command line options @findex -bm @unnumberedsubsec -bm @cindex local message reception Accept an incoming, locally-generated message on the current input, and deliver it to the addresses given as the command arguments (except when -@dfn{t} is also given -- see below). Each argument can be a comma-separated list of RFC 822 addresses. This is the default option for selecting the overall action of an Exim call; it is assumed if no other conflicting option is present. @cindex message: format @cindex format: message @cindex `From' @cindex UUCP, `From' line The format of the message must be as defined in RFC 822, except that, for compatibility with Sendmail and Smail, a line in one of the forms @example From sender Fri Jan 5 12:55 GMT 1997 From sender Fri, 5 Jan 97 12:55:01 @end example (with the weekday optional, and possibly with additional text after the date) is permitted to appear at the start of the message. There appears to be no authoritative specification of the format of this line. Exim recognizes it by matching against the regular expression defined by the @dfn{uucp_from_pattern} option, which can be changed if necessary. The specified sender is treated as if it were given as the argument to the -@dfn{f} option, but if a -@dfn{f} option is also present, its argument is used in preference to the address taken from the message. The caller of Exim must be a trusted user for the sender of a message to be set in this way. @node -bp, -bpa, -bm, Command line options @findex -bp @unnumberedsubsec -bp @cindex queue: listing @cindex listing: the queue List the contents of the mail queue on the standard output. If the -@dfn{bp} option is followed by a list of message ids, just those messages are listed. [(font color=green)] By default, this option can be used only by an admin user. However, the @dfn{queue_list_requires_admin} option can be set false to allow any user to see the queue. [(/font)] Each message on the queue is displayed as in the following example: @example 25m 2.9K 0t5C6f-0000c8-00 red.king@@looking-glass.fict.book <@dfn{other addresses}> @end example @cindex message size @cindex size of message The first line contains the length of time the message has been on the queue (in this case 25 minutes), the size of the message (2.9K), the unique local identifier for the message, and the message sender, as contained in the envelope. If the message is a delivery error message, the sender address is empty, and appears as `<>'. If the message was submitted locally by an untrusted user who overrode the default sender address, the user's login name is shown in parentheses before the sender address. @cindex frozen messages: If the message is frozen (attempts to deliver it are suspended) then the text `*** frozen ***' is displayed at the end of this line. The recipients of the message (taken from the envelope, not the headers) are displayed on subsequent lines. Those addresses to which the message has already been delivered are marked with the letter D. If an original address gets expanded into several addresses via an alias or forward file, the original is displayed with a D only when deliveries for all of its child addresses are complete. @node -bpa, -bpc, -bp, Command line options @findex -bpa @unnumberedsubsec -bpa This option operates like -@dfn{bp}, but in addition it shows delivered addresses that were generated from the original top level address(es) in each message by alias or forwarding operations. These addresses are flagged with `+D' instead of just `D'. [(font color=green)] @node -bpc, -bpr, -bpa, Command line options @findex -bpc @unnumberedsubsec -bpc This option counts the number of messages on the queue, and writes the total to the standard output. It is restricted to admin users, unless @dfn{queue_list_requires_admin} is set false. [(/font)] @node -bpr, -bpra, -bpc, Command line options @findex -bpr @unnumberedsubsec -bpr This option operates like -@dfn{bp}, but the output is not sorted into chronological order of message arrival. This can speed it up when there are lots of messages on the queue, and is particularly useful if the output is going to be post-processed in a way that doesn't need the sorting. @node -bpra, -bpru, -bpr, Command line options @findex -bpra @unnumberedsubsec -bpra This option is a combination of -@dfn{bpr} and -@dfn{bpa}. @node -bpru, -bpu, -bpra, Command line options @findex -bpru @unnumberedsubsec -bpru This option is a combination of -@dfn{bpr} and -@dfn{bpu}. @node -bpu, -bP, -bpru, Command line options @findex -bpu @unnumberedsubsec -bpu This option operates like -@dfn{bp} but shows only undelivered top-level addresses for each message displayed. Addresses generated by aliasing or forwarding are not shown, unless the message was deferred after processing by a director with the @dfn{one_time} option set. @node -bP, -brt, -bpu, Command line options @findex -bP @unnumberedsubsec -bP @cindex configuration options @cindex options: configuration If this option is given with no arguments, it causes the values of all Exim's main configuration options to be written to the standard output. The values of one or more specific options can be requested by giving their names as arguments, for example: @example exim -bP qualify_domain local_domains @end example However, any configuration setting that was preceded by the word `hide' is not shown in full, except to an admin user. For other users, output such as @example mysql_servers = @end example is used. If @dfn{configure_file} is given as an argument, the name of the run time configuration file is output. @cindex daemon, process id @cindex pid, of daemon If @dfn{log_file_path} or @dfn{pid_file_path} are given, the names of the directories where log files and daemon pid files are written are output, respectively. If these values are unset, log files are written in a sub-directory of the spool directory called @dfn{log}, and pid files are written directly into the spool directory. @cindex options: director @cindex options: router @cindex options: transport If one of the words @dfn{director}, @dfn{router}, @dfn{transport}, or @dfn{authenticator} is given, followed by the name of an appropriate driver instance, the option settings for that driver are output. For example: @example exim -bP transport local_delivery @end example The generic driver options are output first, followed by the driver's private options. A list of the names of drivers of a particular type can be obtained by using one of the words @dfn{director_list}, @dfn{router_list}, @dfn{transport_list}, or @dfn{authenticator_list}, and a complete list of all drivers with their option settings can be obtained by using @dfn{directors}, @dfn{routers}, @dfn{transports}, or @dfn{authenticators}. @node -brt, -brw, -bP, Command line options @findex -brt @unnumberedsubsec -brt @cindex testing: retry configuration @cindex retry: configuration testing This option is for testing retry rules, and it must be followed by up to three arguments. It causes Exim to look for a retry rule that matches the values and to write it to the standard output. For example: @example exim -brt bach.comp.mus Retry rule: *.comp.mus F,2h,15m; FG,4d,30m; @end example See chapter 33 for a description of Exim's retry rules. The first argument, which is required, can be a complete address in the form @dfn{local_part@@domain}, or it can be just a domain name. The second argument is an optional second domain name; if no retry rule is found for the first argument, the second is tried. This ties in with Exim's behaviour when looking for retry rules for remote hosts -- if no rule is found that matches the host, one that matches the mail domain is sought. The final argument is the name of a specific delivery error, as used in setting up retry rules, for example `quota_3d'. @node -brw, -bS, -brt, Command line options @findex -brw @unnumberedsubsec -brw @cindex testing: rewriting @cindex rewriting: testing This option is for testing address rewriting rules, and it must be followed by a single argument, consisting of either a local part without a domain, or a complete address with a fully qualified domain. Exim outputs how this address would be rewritten for each possible place it might appear. See chapter 34 for further details. @node -bS, -bs, -brw, Command line options @findex -bS @unnumberedsubsec -bS @cindex SMTP: batched incoming @cindex batched SMTP input This option is used for batched SMTP input, where messages have been received from some external source by an alternative transport mechanism. It causes Exim to accept one or more messages by reading SMTP on the standard input, but to generate no responses. If any error is encountered reports are written to the standard output and error streams, and Exim gives up immediately. If the caller is trusted, or @dfn{untrusted_set_sender} is set, the senders in the @sc{mail} commands are believed; otherwise the sender is always the caller of Exim. Unqualified senders and receivers are not rejected (there seems little point) but instead just get qualified. Sender addresses are verified if @dfn{sender_verify} is set, unless @dfn{sender_verify_batch} is unset (which is the default). Receiver verification and administrative rejection is not done, even if configured. @sc{helo} and @sc{ehlo} act as @sc{rset}; @sc{vrfy}, @sc{expn}, @sc{etrn}, @sc{help}, and @sc{debug} act as @sc{noop}; @sc{quit} quits. The return code is 0 if no error was detected; it is 1 if one or more messages were accepted before the error was detected; otherwise it is 2. More details of input using batched SMTP are given in section 48.9. @node -bs, -bt, -bS, Command line options @findex -bs @unnumberedsubsec -bs @cindex SMTP: local input @cindex local SMTP input @cindex inetd This option causes Exim to accept one or more messages by reading SMTP commands on the standard input, and producing SMTP replies on the standard output. Some user agents use this interface as a way of passing locally-generated messages to the MTA. The option can also be used to run Exim from @dfn{inetd}, as an alternative to using a listening daemon, in which case the standard input is the connected socket. Exim distinguishes between the two cases by attempting to read the IP address of the peer connected to the standard input. If it is not a socket, the call to @dfn{getpeername()} fails, and Exim assumes it is dealing with a local message. @cindex sender: source of If the caller of Exim is trusted, or @dfn{untrusted_set_sender} is set, the senders of messages are taken from the SMTP @sc{mail} commands. Otherwise the content of these commands is ignored and the sender is set up as the calling user. @node -bt, -bV, -bs, Command line options @findex -bt @unnumberedsubsec -bt @cindex testing: addresses @cindex address: testing Run in address testing mode, in which each argument is taken as an address to be tested. The results are written to the standard output. If no arguments are given, Exim runs in an interactive manner, prompting with a right angle bracket for addresses to be tested. Each address is handled as if it were the recipient address of a message and passed to the appropriate directors or routers (compare the -@dfn{bv} option); the result is written to the standard output. The return code is 2 if any address failed outright; it is 1 if no address failed outright but at least one could not be resolved for some reason. Return code 0 is given only when all addresses succeed. [(b)]Warning[(/b)]: -@dfn{bt} can only do relatively simple testing. If any of the directors or routers in the configuration makes any tests on the sender address of a message, you can use the -@dfn{f} option to set an appropriate sender when running -@dfn{bt} tests. Without it, the sender is assumed to be the calling user at the default qualifying domain. However, if you have set up (for example) directors and routers whose behaviour depends on the contents of an incoming message, you cannot test those conditions using -@dfn{bt}. The -@dfn{N} option provides a possible way of doing such tests. @node -bV, -bv, -bt, Command line options @findex -bV @unnumberedsubsec -bV @cindex version number Write the current version number, compilation number, and compilation date of the @dfn{exim} binary to the standard output. @node -bv, -bvs, -bV, Command line options @findex -bv @unnumberedsubsec -bv @cindex verifying: addresses @cindex address: verification Verify the addresses that are given as the arguments to the command, and write the results to the standard output. If no arguments are given, Exim runs in an interactive manner, prompting with a right angle bracket for addresses to be tested. Verification differs from address testing (the -@dfn{bt} option) in that directors and routers that have @dfn{no_verify} set are skipped, and if the address is accepted by a director or router that has @dfn{fail_verify} set, verification fails. This is the same logic that is used when verifying addresses of incoming messages (see chapter 45). The address is verified as a recipient if -@dfn{bv} is used; to verify as for a sender address, -@dfn{bvs} should be used. If the -@dfn{v} (or -@dfn{d}) option is not set, the output consists of a single line for each address, stating whether it was verified or not, and giving a reason in the latter case. Otherwise, more details are given of how the address has been handled, and in the case of aliases or forwarding, all the generated addresses are also considered. Otherwise, generating an address by forwarding, or more than one address by aliasing, causes verification to end sucessfully. The return code is 2 if any address failed outright; it is 1 if no address failed outright but at least one could not be resolved for some reason. Return code 0 is given only when all addresses succeed. If any of the directors or routers in the configuration makes any tests on the sender address of a message, you should use the -@dfn{f} option to set an appropriate sender when running -@dfn{bv} tests. Without it, the sender is assumed to be the calling user at the default qualifying domain. @node -bvs, -C <@dfn{filename}>, -bv, Command line options @findex -bvs @unnumberedsubsec -bvs This option acts like -@dfn{bv}, but verifies the address as a sender rather than a recipient address. This affects any rewriting and qualification that might happen. @node -C <@dfn{filename}>, -D<@dfn{macro}>=<@dfn{value}>, -bvs, Command line options @findex -C <@dfn{filename}> @unnumberedsubsec -C <@dfn{filename}> @cindex configuration: run time @cindex run time configuration @cindex CONFIGURE_FILE @cindex alternate configuration file Read the run time configuration from the given file instead of from the default file specified by the @sc{configure_file} compile-time setting. When this option is used by an unprivileged caller and the file name given is different from the compiled-in name, Exim gives up its root privilege immediately, and runs with the real and effective uid and gid set to those of the caller, to avoid any security exposure. It does not do this if the caller is root or the Exim user defined by @sc{exim_uid} in @file{Local/Makefile}. The facility is useful for ensuring that configuration files are syntactically correct, but cannot be used for test deliveries, unless the caller is privileged, or unless it's an exotic configuration that does not require privilege. No check is made on the owner or group of the file specified by this option. @node -D<@dfn{macro}>=<@dfn{value}>, -d<@dfn{number}>, -C <@dfn{filename}>, Command line options @findex -D<@dfn{macro}>=<@dfn{value}> @unnumberedsubsec -D<@dfn{macro}>=<@dfn{value}> @cindex macro setting This option can be used to override macro definitions in the configuration file (see section 7.2). However, like -@dfn{C}, if it is used by an unprivileged caller, it causes Exim to give up its root privilege. This option may be repeated up to 10 times on a command line. @node -d<@dfn{number}>, -df, -D<@dfn{macro}>=<@dfn{value}>, Command line options @findex -d<@dfn{number}> @unnumberedsubsec -d<@dfn{number}> @cindex debugging Set a debug level, causing debugging information to be written to the standard error file. White space between -@dfn{d} and the number is optional. If no number is given, 1 is assumed, and the higher the number, the more output is produced. A value of zero turns debugging output off and is the default. A value of 9 gives the maximum amount of general information, 10 gives in addition details of the interpretation of filter files, and 11 or higher also turns on the debugging option for DNS lookups. For non-admin users, the number is ignored, and a debug level of 1 is always used. This restriction exists because debugging output may show database queries that contain password information, and also the details of users' filter files should be protected. @node -df, -dm, -d<@dfn{number}>, Command line options @findex -df @unnumberedsubsec -df @cindex debugging output @cindex STDERR_FILE @cindex inetd If this option is set and @sc{stderr_file} was defined when Exim was built, debugging information is written to the file defined by that variable instead of to the standard error file. This option provides a way of obtaining debugging information when Exim is run from @dfn{inetd}. @node -dm, -dropcr, -df, Command line options @findex -dm @unnumberedsubsec -dm @cindex memory allocation This option causes information about memory allocation and freeing operations to be written to the standard error file. @node -dropcr, -E, -dm, Command line options @findex -dropcr @unnumberedsubsec -dropcr @cindex CR @cindex LF @cindex carriage return @cindex linefeed @cindex UUCP At least one MUA (dtmail) that calls an MTA via the command line is broken in that it terminates each line with CRLF, instead of just LF, which is the usual Unix convention, and although this bug has been admitted, it apparently won't get fixed. There is also some UUCP software which leaves CR at the ends of lines in messages. As a slight pander to these programs, the -@dfn{dropcr} option causes Exim to drop @dfn{all} CR characters in an incoming non-SMTP message. @node -E, -e@dfn{x}, -dropcr, Command line options @findex -E @unnumberedsubsec -E @cindex error messages: @cindex delivery: failure report This option specifies that an incoming message is a locally-generated delivery failure report. It is used internally by Exim when handling delivery failures and is not intended for external use. Its only effect is to stop Exim generating certain messages to the mailmaster, as otherwise message cascades could occur in some situations. As part of the same option, a message id may follow the characters -@dfn{E}. If it does, the log entry for the receipt of the new message contains the id, following `R=', as a cross-reference. @node -e@dfn{x}, -F <@dfn{string}>, -E, Command line options @findex -e@dfn{x} @unnumberedsubsec -e@dfn{x} There are a number of Sendmail options starting with -@dfn{oe} which seem to be called by various programs without the leading @dfn{o} in the option. For example, the @dfn{vacation} program uses -@dfn{eq}. Exim treats all options of the form -@dfn{e@dfn{x}} as synonymous with the corresponding -@dfn{oe@dfn{x}} options. @node -F <@dfn{string}>, -f <@dfn{address}>, -e@dfn{x}, Command line options @findex -F <@dfn{string}> @unnumberedsubsec -F <@dfn{string}> @cindex sender: name @cindex name of sender Set the sender's full name for use when a locally-generated message is being accepted. In the absence of this option, the user's @dfn{gecos} entry from the password file is used. As users are generally permitted to alter their @dfn{gecos} entries, no security considerations are involved. White space between -@dfn{F} and the <@dfn{string}> is optional. @node -f <@dfn{address}>, -h <@dfn{number}>, -F <@dfn{string}>, Command line options @findex -f <@dfn{address}> @unnumberedsubsec -f <@dfn{address}> @cindex sender: address @cindex address: sender @cindex trusted user Set the address of the envelope sender of a locally-generated message (also known as the return path). This option can normally be used only by root or the Exim user or by one of the configured trusted users, but if @dfn{untrusted_set_sender} is set, its use is not restricted. However, even when @dfn{untrusted_set_sender} is not set, anyone may use it when testing a filter file with -@dfn{bf} or when testing or verifying addresses using the -@dfn{bt} or -@dfn{bv} options. There is also no restriction of the use of the special setting -@dfn{f <>} to send a message with an empty sender; such a message can never provoke a bounce. In other cases, the sender of a local message is set up as the user who ran the @dfn{exim} command, and -@dfn{f} is ignored, Allowing untrusted users to change the sender address does not of itself make it possible to send anonymous mail. Exim still checks that the @dfn{From:} header refers to the local user, and if it does not, it adds a @dfn{Sender:} header, though this can be overridden by setting @dfn{no_local_from_check}. White space between -@dfn{f} and the <@dfn{address}> is optional. The sender of a locally-generated message can also be set (when permitted) by an initial `From ' line in the message -- see the description of -@dfn{bm} above, but if -@dfn{f} is also present, it overrides `From '. @node -h <@dfn{number}>, -i, -f <@dfn{address}>, Command line options @findex -h <@dfn{number}> @unnumberedsubsec -h <@dfn{number}> This option is accepted for compatibility with Sendmail, but at present has no effect. (In Sendmail it overrides the `hop count' obtained by counting @dfn{Received:} headers.) @node -i, -M <@dfn{message id}> <@dfn{message id}>, -h <@dfn{number}>, Command line options @findex -i @unnumberedsubsec -i This option, which has the same effect as -@dfn{oi}, specifies that a dot on a line by itself should not terminate an incoming, non-SMTP message. I can find no documentation for this option in Solaris 2.4 Sendmail, but the @dfn{mailx} command in Solaris 2.4 uses it. @node -M <@dfn{message id}> <@dfn{message id}>, -Mar <@dfn{message id}> <@dfn{address}> <@dfn{address}>, -i, Command line options @findex -M <@dfn{message id}> <@dfn{message id}> @unnumberedsubsec -M <@dfn{message id}> <@dfn{message id}> @cindex forcing delivery @cindex delivery: forcing @cindex frozen messages: forcing delivery Exim runs a delivery attempt on each message in turn. If any of the messages are frozen, they are automatically thawed before the delivery attempt. The settings of @dfn{queue_remote_domains}, @dfn{queue_smtp_domains}, and @dfn{hold_domains} are ignored. Retry hints for any of the addresses are overridden -- Exim tries to deliver even if the normal retry time has not yet been reached. This option requires the caller to be an admin user. However, there is an option called @dfn{prod_requires_admin} which can be set false to relax this restriction (and also the same requirement for the -@dfn{q}, -@dfn{R}, and -@dfn{S} options). @node -Mar <@dfn{message id}> <@dfn{address}> <@dfn{address}>, -MC <@dfn{transport}> <@dfn{hostname}> <@dfn{sequence number}> <@dfn{message id}>, -M <@dfn{message id}> <@dfn{message id}>, Command line options @findex -Mar <@dfn{message id}> <@dfn{address}> <@dfn{address}> @unnumberedsubsec -Mar <@dfn{message id}> <@dfn{address}> <@dfn{address}> @cindex admin user @cindex message: adding recipients @cindex recipients: adding The first argument must be a message id, and the remaining ones must be email addresses. Exim adds the addresses to the list of recipients of the message (`ar' for `add recipients'). However, if the message is active (in the middle of a delivery attempt), its status is not altered. This option can be used only by an admin user. @cindex SMTP: passing channel @cindex SMTP: multiple deliveries @cindex multiple SMTP deliveries @node -MC <@dfn{transport}> <@dfn{hostname}> <@dfn{sequence number}> <@dfn{message id}>, -MCA, -Mar <@dfn{message id}> <@dfn{address}> <@dfn{address}>, Command line options @findex -MC <@dfn{transport}> <@dfn{hostname}> <@dfn{sequence number}> <@dfn{message id}> @unnumberedsubsec -MC <@dfn{transport}> <@dfn{hostname}> <@dfn{sequence number}> <@dfn{message id}> This option is not intended for use by external callers. It is used internally by Exim to invoke another instance of itself to deliver a waiting message using an existing SMTP channel, which is passed as the standard input. Details are given in chapter 48. This must be the final option, and the caller must be root or the Exim user in order to use it. @node -MCA, -MCQ <@dfn{process id}> <@dfn{pipe fd}>, -MC <@dfn{transport}> <@dfn{hostname}> <@dfn{sequence number}> <@dfn{message id}>, Command line options @findex -MCA @unnumberedsubsec -MCA This option is not intended for use by external callers. It is used internally by Exim in conjunction with -@dfn{MC} option. It signifies that the connection to the remote host has been authenticated. @node -MCQ <@dfn{process id}> <@dfn{pipe fd}>, -MCS, -MCA, Command line options @findex -MCQ <@dfn{process id}> <@dfn{pipe fd}> @unnumberedsubsec -MCQ <@dfn{process id}> <@dfn{pipe fd}> This option is not intended for use by external callers. It is used internally by Exim in conjunction with -@dfn{MC} option when the original delivery was started by a queue runner. It passes on the process id of the queue runner, together with the file descriptor number of an open pipe. Closure of the pipe signals the final completion of the sequence of processes that are passing messages through the same SMTP channel. @node -MCS, -MCT, -MCQ <@dfn{process id}> <@dfn{pipe fd}>, Command line options @findex -MCS @unnumberedsubsec -MCS This option is not intended for use by external callers. It is used internally by Exim in conjunction with -@dfn{MC} option, and passes on the fact that the SMTP @sc{size} option should be used on messages delivered down the existing channel. @node -MCT, -Mc <@dfn{message id}> <@dfn{message id}>, -MCS, Command line options @findex -MCT @unnumberedsubsec -MCT This option is not intended for use by external callers. It is used internally by Exim in conjunction with -@dfn{MC} option, and passes on the fact that the host to which Exim is connected supports TLS encryption. @node -Mc <@dfn{message id}> <@dfn{message id}>, -Meb <@dfn{message id}>, -MCT, Command line options @findex -Mc <@dfn{message id}> <@dfn{message id}> @unnumberedsubsec -Mc <@dfn{message id}> <@dfn{message id}> Exim runs a delivery attempt on each message in turn, but unlike the -@dfn{M} option, it does check for retry hints, and respects any that are found. This option is not very useful to external callers. It is provided mainly for internal use by Exim when it needs to re-invoke itself in order to regain root privilege for a delivery (see chapter 55). [(font color=green)] However, -@dfn{Mc} can be useful when testing, in order to run a delivery that respects retry times and other options such as @dfn{hold_domains} that are overridden when -@dfn{M} is used. [(/font)] Such a delivery does not count as a queue run. If you want to run a specific delivery as if in a queue run, you should use -@dfn{q} with a message id argument. A distinction between queue run deliveries and other deliveries is made in one or two places. @node -Meb <@dfn{message id}>, -Mes <@dfn{message id}> <@dfn{address}>, -Mc <@dfn{message id}> <@dfn{message id}>, Command line options @findex -Meb <@dfn{message id}> @unnumberedsubsec -Meb <@dfn{message id}> @cindex message: editing body of @cindex editing message body @cindex body of message: editing This runs, under /bin/sh, the command defined in the shell variable @sc{visual} or, if that is not defined, @sc{editor} or, if that is not defined, the command @dfn{vi}, on a copy of the spool file containing the body of message (`eb' for `edit body'). If the editor exits normally, the result of editing replaces the spool file. The message is locked during this process, so no delivery attempts can occur. Note that the first line of the spool file is its own name; care should be taken not to disturb this. The thinking behind providing this feature is that an administrator who has had to mess around with the addresses to get a message delivered might want to add some comment at the start of the message text. This option can be used only by an admin user. @node -Mes <@dfn{message id}> <@dfn{address}>, -Mf <@dfn{message id}> <@dfn{message id}>, -Meb <@dfn{message id}>, Command line options @findex -Mes <@dfn{message id}> <@dfn{address}> @unnumberedsubsec -Mes <@dfn{message id}> <@dfn{address}> @cindex message: changing sender @cindex sender: changing There must be exactly two arguments. The first argument must be a message id, and the second one an email address. Exim changes the sender address in the message to the given address, which must be a fully qualified address or `<>' (`es' for `edit sender'). However, if the message is active (in the middle of a delivery attempt), its status is not altered. This option can be used only by an admin user. @node -Mf <@dfn{message id}> <@dfn{message id}>, -Mg <@dfn{message id}> <@dfn{message id}>, -Mes <@dfn{message id}> <@dfn{address}>, Command line options @findex -Mf <@dfn{message id}> <@dfn{message id}> @unnumberedsubsec -Mf <@dfn{message id}> <@dfn{message id}> @cindex freezing messages @cindex admin user @cindex frozen messages: Each listed message is marked `frozen'. This prevents any delivery attempts taking place until the message is `thawed', either manually or as a result of the @dfn{auto_thaw} configuration option. However, if any of the messages are active (in the middle of a delivery attempt), their status is not altered. This option can be used only by an admin user. @node -Mg <@dfn{message id}> <@dfn{message id}>, -Mmad <@dfn{message id}> <@dfn{message id}>, -Mf <@dfn{message id}> <@dfn{message id}>, Command line options @findex -Mg <@dfn{message id}> <@dfn{message id}> @unnumberedsubsec -Mg <@dfn{message id}> <@dfn{message id}> @cindex giving up on messages @cindex admin user Exim gives up trying to deliver the listed messages, including any that are frozen. A delivery error message is sent, containing the text `cancelled by administrator'. However, if any of the messages are active, their status is not altered. This option can be used only by an admin user. @node -Mmad <@dfn{message id}> <@dfn{message id}>, -Mmd <@dfn{message id}> <@dfn{address}> <@dfn{address}>, -Mg <@dfn{message id}> <@dfn{message id}>, Command line options @findex -Mmad <@dfn{message id}> <@dfn{message id}> @unnumberedsubsec -Mmad <@dfn{message id}> <@dfn{message id}> @cindex delivery: cancelling all Exim marks all the recipient addresses in the messages as already delivered (`mad' for `mark all delivered'). However, if any message is active (in the middle of a delivery attempt), its status is not altered. This option can be used only by an admin user. @node -Mmd <@dfn{message id}> <@dfn{address}> <@dfn{address}>, -Mrm <@dfn{message id}> <@dfn{message id}>, -Mmad <@dfn{message id}> <@dfn{message id}>, Command line options @findex -Mmd <@dfn{message id}> <@dfn{address}> <@dfn{address}> @unnumberedsubsec -Mmd <@dfn{message id}> <@dfn{address}> <@dfn{address}> @cindex delivery: cancelling by address @cindex recipients: removing @cindex removing recipients The first argument must be a message id, and the remaining ones must be email addresses. Exim marks the given addresses as already delivered (`md' for `mark delivered'). However, if the message is active (in the middle of a delivery attempt), its status is not altered. This option can be used only by an admin user. @node -Mrm <@dfn{message id}> <@dfn{message id}>, -Mt <@dfn{message id}> <@dfn{message id}>, -Mmd <@dfn{message id}> <@dfn{address}> <@dfn{address}>, Command line options @findex -Mrm <@dfn{message id}> <@dfn{message id}> @unnumberedsubsec -Mrm <@dfn{message id}> <@dfn{message id}> @cindex removing messages @cindex abandoning mail @cindex admin user Each message is completely removed from Exim's queue, and forgotten. However, if any of the messages are active, their status is not altered. This option can be used only by an admin user or by the user who originally caused the message to be placed on the queue. @node -Mt <@dfn{message id}> <@dfn{message id}>, -Mvb <@dfn{message id}>, -Mrm <@dfn{message id}> <@dfn{message id}>, Command line options @findex -Mt <@dfn{message id}> <@dfn{message id}> @unnumberedsubsec -Mt <@dfn{message id}> <@dfn{message id}> @cindex thawing messages @cindex unfreezing messages @cindex admin user @cindex frozen messages: thawing Each of the listed messages that was `frozen' is now `thawed', so that delivery attempts can resume. However, if any of the messages are active, their status is not altered. This option can be used only by an admin user. @node -Mvb <@dfn{message id}>, -Mvh <@dfn{message id}>, -Mt <@dfn{message id}> <@dfn{message id}>, Command line options @findex -Mvb <@dfn{message id}> @unnumberedsubsec -Mvb <@dfn{message id}> @cindex listing: message body @cindex message: listing body of The contents of the message body (-D) spool file are written to the standard output. This option can be used only by an admin user. @node -Mvh <@dfn{message id}>, -Mvl <@dfn{message id}>, -Mvb <@dfn{message id}>, Command line options @findex -Mvh <@dfn{message id}> @unnumberedsubsec -Mvh <@dfn{message id}> @cindex listing: message headers @cindex headers: listing The contents of the message headers (-H) spool file are written to the standard output. This option can be used only by an admin user. @node -Mvl <@dfn{message id}>, -m, -Mvh <@dfn{message id}>, Command line options @findex -Mvl <@dfn{message id}> @unnumberedsubsec -Mvl <@dfn{message id}> @cindex listing: message log @cindex message: log listing The contents of the message log spool file are written to the standard output. This option can be used only by an admin user. @node -m, -N, -Mvl <@dfn{message id}>, Command line options @findex -m @unnumberedsubsec -m This is apparently a synonym for -@dfn{om} that is accepted by Sendmail, so Exim treats it that way too. @node -N, -n, -m, Command line options @findex -N @unnumberedsubsec -N This is a debugging option that inhibits delivery of a message at the transport level. It implies at least -@dfn{d1}. Exim goes through many of the motions of delivery -- it just doesn't actually transport the message, but instead behaves as if it had successfully done so. However, it does not make any updates to the retry database, and the log entries for deliveries are flagged with `*>' rather than `=>'. Because -@dfn{N} discards any message to which it applies, only root or the Exim user are allowed to use it with -@dfn{bd}, -@dfn{q}, -@dfn{R} or -@dfn{M}. In other words, an ordinary user can use it only when supplying an incoming message to which it will apply. Although transportation never fails when -@dfn{N} is set, an address may be deferred because of a configuration problem on a transport, or a routing or directing problem. Once -@dfn{N} has been used for a delivery attempt, it sticks to the message, and applies to any subsequent delivery attempts that may happen for that message. @node -n, -oA <@dfn{file name}>, -N, Command line options @findex -n @unnumberedsubsec -n This option is interpreted by Sendmail to mean `no aliasing'. It is ignored by Exim. @node -oA <@dfn{file name}>, -oB <@dfn{n}>, -n, Command line options @findex -oA <@dfn{file name}> @unnumberedsubsec -oA <@dfn{file name}> This option is used by Sendmail in conjunction with -@dfn{bi} to specify an alternative alias file name. Exim handles -@dfn{bi} differently; see the description above. @cindex SMTP: passing channel @node -oB <@dfn{n}>, -odb, -oA <@dfn{file name}>, Command line options @findex -oB <@dfn{n}> @unnumberedsubsec -oB <@dfn{n}> @cindex SMTP: multiple deliveries @cindex multiple SMTP deliveries This is a debugging option which limits the maximum number of multiple SMTP deliveries down one channel to <@dfn{n}>, overriding the value set in the @dfn{smtp} transport. If <@dfn{n}> is omitted, the limit is set to 1 (no batching). @node -odb, -odf, -oB <@dfn{n}>, Command line options @findex -odb @unnumberedsubsec -odb @cindex background delivery This option applies to all modes in which Exim accepts incoming messages, including the listening daemon. It requests `background' delivery of such messages, which means that the accepting process automatically starts another delivery process for each message received. Exim does not wait for such processes to complete (it can take some time to perform SMTP deliveries). This is the default action if none of the -@dfn{od} options are present. @node -odf, -odi, -odb, Command line options @findex -odf @unnumberedsubsec -odf @cindex foreground delivery This option (compatible with Smail) requests `foreground' (synchronous) delivery when Exim has accepted a locally-generated message. (For the daemon it is exactly the same as -@dfn{odb}.) For a single message received on the standard input, if the protection regime permits it (see chapter 55), Exim converts the reception process into a delivery process. In other cases, it creates a new delivery process, and then waits for it to complete before proceeding. @node -odi, -odq, -odf, Command line options @findex -odi @unnumberedsubsec -odi This option is synonymous with -@dfn{odf}. It is provided for compatibility with Sendmail. @node -odq, -odqr, -odi, Command line options @findex -odq @unnumberedsubsec -odq @cindex non-immediate delivery This option applies to all modes in which Exim accepts incoming messages, including the listening daemon. It specifies that the accepting process should not automatically start a delivery attempt for each message received. Messages are placed on the queue, and remain there until a subsequent queue-running process encounters them. The @dfn{queue_only} configuration option has the same effect. @node -odqr, -odqs, -odq, Command line options @findex -odqr @unnumberedsubsec -odqr @cindex local delivery This option applies to all modes in which Exim accepts incoming messages, including the listening daemon. It causes Exim to process local addresses when a message is received, but not even to try routing remote addresses. Contrast with -@dfn{odqs} below, which does the routing, but not the delivery. The remote addresses will be picked up by the next queue runner. The @dfn{queue_remote_domains} configuration option has the same effect for specific domains. @node -odqs, -oee, -odqr, Command line options @findex -odqs @unnumberedsubsec -odqs @cindex SMTP: delaying delivery This option is a hybrid between -@dfn{odb} and -@dfn{odq}. A delivery process is started for each incoming message, the addresses are all processed, and local deliveries are done in the normal way. However, if any SMTP deliveries are required, they are not done at this time. Such messages remain on the queue until a subsequent queue-running process encounters them. Because routing was done, Exim knows which messages are waiting for which hosts, and so a number of messages for the same host will get sent in a single SMTP connection. The @dfn{queue_smtp_domains} configuration option has the same effect for specific domains. See also the -@dfn{qq} option. @node -oee, -oem, -odqs, Command line options @findex -oee @unnumberedsubsec -oee @cindex error reporting If an error is detected while a non-SMTP message is being received (for example, a malformed address), the error is reported to the sender in a mail message. Provided the message is successfully sent, Exim exits with a return code of zero. If not, the return code is 2 if the error was that the message had no recipients, and 1 otherwise. This is the default -@dfn{oe@dfn{x}} option if Exim is called as @dfn{rmail}. @node -oem, -oep, -oee, Command line options @findex -oem @unnumberedsubsec -oem @cindex error reporting This is the same as -@dfn{oee}, except that Exim always exits with a non-zero return code, whether or not the error message was successfully sent. This is the default -@dfn{oe@dfn{x}} option, unless Exim is called as @dfn{rmail}. @node -oep, -oeq, -oem, Command line options @findex -oep @unnumberedsubsec -oep @cindex error reporting If an error is detected while a non-SMTP message is being received, the error is reported by writing a message to the standard error file (stderr). @node -oeq, -oew, -oep, Command line options @findex -oeq @unnumberedsubsec -oeq @cindex error reporting This option is supported for compatibility with Sendmail, but has the same effect as -@dfn{oep}. @node -oew, -oi, -oeq, Command line options @findex -oew @unnumberedsubsec -oew @cindex error reporting This option is supported for compatibility with Sendmail, but has the same effect as -@dfn{oem}. @node -oi, -oitrue, -oew, Command line options @findex -oi @unnumberedsubsec -oi @cindex dot handling This option, which has the same effect as -@dfn{i}, specifies that a dot on a line by itself should not terminate an incoming, non-SMTP message. This is the default if Exim is called as @dfn{rmail}. @node -oitrue, -oMa <@dfn{host address}>, -oi, Command line options @findex -oitrue @unnumberedsubsec -oitrue This option is treated as synonymous with -@dfn{oi}. @node -oMa <@dfn{host address}>, -oMas <@dfn{address}>, -oitrue, Command line options @findex -oMa <@dfn{host address}> @unnumberedsubsec -oMa <@dfn{host address}> @cindex sender: host address @cindex trusted user This option sets the sender host address value, and can be used only by a trusted caller, except in conjunction with the -@dfn{bh}, -@dfn{bf}, -@dfn{bF}, -@dfn{bt}, or -@dfn{bv} testing options. The host address may include a port number at the end, after full stop. For example @example exim -bs -oMa 10.9.8.7.1234 @end example A real incoming connection overrides the address set by -@dfn{oMa}. The value is used in log entries and can appear in @dfn{Received:} headers. The option is intended for use when handing to Exim messages received by other means, either via the command line or by using the -@dfn{bs} option. If -@dfn{oMt} is set then -@dfn{oMa} should normally be set as well. [(font color=green)] @node -oMas <@dfn{address}>, -oMai <@dfn{string}>, -oMa <@dfn{host address}>, Command line options @findex -oMas <@dfn{address}> @unnumberedsubsec -oMas <@dfn{address}> @cindex authentication: sender This option sets the authenticated sender value, and can be used only by a trusted caller. It overrides the sender address that is created from the caller's login for messages from local sources. However, it may be overridden in turn by a message that is received over an authenticated SMTP connection. See chapter 35 for more discussion of authenticated senders. @node -oMai <@dfn{string}>, -oMi <@dfn{interface address}>, -oMas <@dfn{address}>, Command line options @findex -oMai <@dfn{string}> @unnumberedsubsec -oMai <@dfn{string}> @cindex authentication: This option sets the authenticated id value, and can be used only by a trusted caller. It overrides the default value (the caller's login id) for messages from local sources. However, it may be overridden in turn by a successful authentication on an SMTP connection. See chapter 35 for more discussion of authenticated ids. [(/font)] @node -oMi <@dfn{interface address}>, -oMr <@dfn{protocol name}>, -oMai <@dfn{string}>, Command line options @findex -oMi <@dfn{interface address}> @unnumberedsubsec -oMi <@dfn{interface address}> @cindex interface address @cindex trusted user This option sets the IP interface address value, and can be used only by a trusted caller, except in conjunction with the -@dfn{bh}, -@dfn{bf}, -@dfn{bF}, -@dfn{bt}, or -@dfn{bv} testing options. A real incoming connection overrides the address set by -@dfn{oMi}. The option is intended for use when handing to Exim messages received by other means, either via the command line or by using the -@dfn{bs} option. @node -oMr <@dfn{protocol name}>, -oMs <@dfn{host name}>, -oMi <@dfn{interface address}>, Command line options @findex -oMr <@dfn{protocol name}> @unnumberedsubsec -oMr <@dfn{protocol name}> @cindex protocol @cindex trusted user This option sets the received protocol value, and can be used only by a trusted caller, except in conjunction with the -@dfn{bh}, -@dfn{bf}, -@dfn{bF}, -@dfn{bt}, or -@dfn{bv} testing options. The value is used in log entries and can appear in @dfn{Received:} headers. The option is intended for use when handing to Exim messages received by other means. It applies only to non-SMTP and batched SMTP input. @node -oMs <@dfn{host name}>, -oMt <@dfn{ident string}>, -oMr <@dfn{protocol name}>, Command line options @findex -oMs <@dfn{host name}> @unnumberedsubsec -oMs <@dfn{host name}> @cindex sender: host name @cindex trusted user This option sets the sender host name value, and can be used only by a trusted caller, except in conjunction with the -@dfn{bh}, -@dfn{bf}, -@dfn{bF}, -@dfn{bt}, or -@dfn{bv} testing options. The value is used in log entries and can appear in @dfn{Received:} headers. The option is intended for use when handing to Exim messages received by other means. @node -oMt <@dfn{ident string}>, -om, -oMs <@dfn{host name}>, Command line options @findex -oMt <@dfn{ident string}> @unnumberedsubsec -oMt <@dfn{ident string}> @cindex sender: ident string @cindex trusted user This option sets the sender ident value, and can be used only by a trusted caller, except in conjunction with the -@dfn{bh}, -@dfn{bf}, -@dfn{bF}, -@dfn{bt}, or -@dfn{bv} testing options. The value is used in log entries and can appear in @dfn{Received:} headers. The default setting for local callers is the login id of the calling process. This can be overridden by supplying an empty argument. The option is intended for use when handing to Exim messages received by other means. @node -om, -oo, -oMt <@dfn{ident string}>, Command line options @findex -om @unnumberedsubsec -om In Sendmail, this option means `me too', indicating that the sender of a message should receive a copy of the message if the sender appears in an alias expansion. Exim always does this, so the option does nothing. @node -oo, -or <@dfn{time}>, -om, Command line options @findex -oo @unnumberedsubsec -oo This option is ignored. In Sendmail it specifies `old style headers', whatever that means. @node -or <@dfn{time}>, -ov, -oo, Command line options @findex -or <@dfn{time}> @unnumberedsubsec -or <@dfn{time}> @cindex timeout: non-SMTP input This option sets a timeout value for incoming non-SMTP messages. If it is not set, Exim will wait forever for the standard input. The value can also be set using the @dfn{accept_timeout} configuration variable. The format used for specifying times is described in section 7.7. @node -ov, -oX <@dfn{number}>, -or <@dfn{time}>, Command line options @findex -ov @unnumberedsubsec -ov This option has exactly the same effect as -@dfn{v}. @node -oX <@dfn{number}>, -pd, -ov, Command line options @findex -oX <@dfn{number}> @unnumberedsubsec -oX <@dfn{number}> @cindex TCP/IP incoming port @cindex port: receiving TCP/IP This option is relevant only when the -@dfn{bd} option is also given. It overrides any setting of the @dfn{daemon_smtp_port} option, and specifies an alternative TCP/IP port number for the listening daemon. @cindex daemon, process id @cindex pid, of daemon When used, the process number of the daemon is written to a file whose name is @dfn{exim-daemon.<@dfn{number}>.pid} in Exim's spool directory or the directory specified by @sc{pid_file_path} in @file{Local/Makefile}. @node -pd, -ps, -oX <@dfn{number}>, Command line options @findex -pd @unnumberedsubsec -pd @cindex Perl: embedded This option applies when an embedded Perl interpreter is linked with Exim (see chapter 10). It overrides the setting of the @dfn{perl_at_start} option, forcing the starting of the interpreter to be delayed until it is needed. @node -ps, -q, -pd, Command line options @findex -ps @unnumberedsubsec -ps @cindex Perl: embedded This option applies when an embedded Perl interpreter is linked with Exim (see chapter 10). It overrides the setting of the @dfn{perl_at_start} option, forcing the starting of the interpreter to occur as soon as Exim is started. @node -q, -q <@dfn{time}>, -ps, Command line options @findex -q @unnumberedsubsec -q @cindex queue: running @cindex queue-runner If the -@dfn{q} option is not followed by a time value, it requests a single queue run operation. This option requires the caller to be an admin user. However, there is an option called @dfn{prod_requires_admin} which can be set false to relax this restriction (and also the same requirement for the -@dfn{M}, -@dfn{R}, and -@dfn{S} options). Exim starts up a delivery process for each (inactive) message on the queue in turn, and waits for it to finish before starting the next one. @cindex SMTP: passed channel @cindex SMTP: multiple deliveries @cindex multiple SMTP deliveries If the delivery process spawns other processes to deliver other messages down passed SMTP connections, the queue runner waits for these to finish before proceeding. When all the queued messages have been considered, the original process terminates. In other words, a single pass is made over the waiting mail, one message at a time. Use -@dfn{q} with a time (see below) if you want this to be repeated periodically. Exim processes the waiting messages in an unpredictable order. It isn't very random, but it is likely to be different each time, which is all that matters. If one particular message screws up a remote MTA, other messages to the same MTA have a chance of getting through if they get tried first. It is possible to cause the messages to be processed in lexical message id order, which is essentially the order in which they arrived, by setting the @dfn{queue_run_in_order} option, but this is not recommended for normal use. When scanning the queue (either randomly or in order), Exim can be made to skip over messages whose ids are lexically less than a given value by following the -@dfn{q} option with a starting message id. For example: @example exim -q 0t5C6f-0000c8-00 @end example Messages that arrived earlier than 0t5C6f-0000c8-00 are not inspected. If a second message id is given, messages whose ids are lexically greater than it are also skipped. If the same id is given twice, for example, @example exim -q 0t5C6f-0000c8-00 0t5C6f-0000c8-00 @end example just one delivery process is started, for that message. This differs from -@dfn{M} in that retry data is respected, and it also differs from -@dfn{Mc} in that it counts as a delivery from a queue run. Note that the selection mechanism does not affect the order in which the messages are scanned. There are also other ways of selecting specific sets of messages for delivery in a queue run -- see -@dfn{R} and -@dfn{S}. @node -q <@dfn{time}>, -qf, -q, Command line options @findex -q <@dfn{time}> @unnumberedsubsec -q <@dfn{time}> @cindex queue: running @cindex periodic queue running This version of the -@dfn{q} option (which again can be run only by an admin user) causes Exim to run as a daemon, starting a queue-runner process at intervals specified by the given time value (whose format is described in section 7.7). This form of the -@dfn{q} option is commonly combined with the -@dfn{bd} option, in which case a single daemon process handles both functions. A common way of starting up a combined daemon at system boot time is to use a command such as @example /opt/exim/bin/exim -bd -q30m @end example @cindex queue-runner Such a daemon listens for incoming SMTP calls, and also fires up a queue-runner process every 30 minutes. The process id of such a daemon is written to a file @cindex daemon, process id @cindex pid, of daemon called @dfn{exim-daemon.pid} in Exim's spool directory, unless the -@dfn{oX} option has been used, in which case the file is called @dfn{exim-daemon.<@dfn{port-number}>.pid}. The location of the pid file can be changed by defining @sc{pid_file_path} in @file{Local/Makefile}. If a daemon is started without -@dfn{bd} then the -@dfn{q} option used to start it is added to the pid file name. @node -qf, -qff, -q <@dfn{time}>, Command line options @findex -qf @unnumberedsubsec -qf @cindex queue: forcing This option operates like -@dfn{q}, and may appear with or without a following time. The difference is that a delivery attempt is forced for each non-frozen message, whereas with -@dfn{q} only those non-frozen addresses that have passed their retry times are tried. @node -qff, -qfl, -qf, Command line options @findex -qff @unnumberedsubsec -qff @cindex thawing messages @cindex frozen messages: thawing This option operates like -@dfn{qf} and may appear with or without a following time. The difference is that any frozen messages are automatically thawed, and delivery is attempted for them. @node -qfl, -qffl, -qff, Command line options @findex -qfl @unnumberedsubsec -qfl This option operates like -@dfn{ql}, and may appear with or without a following time. The difference is that a delivery attempt is forced for the local addresses in each non-frozen message, whereas with -@dfn{ql} only those non-frozen local addresses that have passed their retry times are tried. @node -qffl, -ql, -qfl, Command line options @findex -qffl @unnumberedsubsec -qffl @cindex frozen messages: thawing This option operates like -@dfn{qfl} and may appear with or without a following time. The difference is that any frozen messages are automatically thawed, and delivery is attempted for any local addresses in them. @node -ql, -qq, -qffl, Command line options @findex -ql @unnumberedsubsec -ql @cindex queue: local address delivery @cindex local address delivery This option operates like -@dfn{q}, and may appear with or without a following time. The difference is that only local addresses (those with domains that match @dfn{local_domains}) are considered for delivery. Note that -@dfn{ql} cannot detect apparently remote addresses that actually turn out to be local when their domains get fully qualified. @node -qq, -qR<@dfn{flags}> <@dfn{string}>, -ql, Command line options @findex -qq @unnumberedsubsec -qq @cindex queue: double scanning @cindex queue: routing @cindex routing whole queue If any command line option starting with -@dfn{q} is specified with an additional @dfn{q} (for example, -@dfn{qqf}) then all the resulting queue runs are done in two stages. In the first stage, the queue is scanned as if the @dfn{queue_smtp_domains} option matched every domain. This causes remote addresses to be routed, but no transportation to be done. The database that remembers which messages are waiting for specific hosts is updated, as if delivery to those hosts had been deferred. After this is complete, a second, normal queue scan happens, and normal directing, routing, and delivery takes place. Messages which are routed to the same host should mostly be delivered down a single SMTP @cindex SMTP: passed channel @cindex SMTP: multiple deliveries @cindex multiple SMTP deliveries connection because of the hints that were set up during the first queue scan. This option may be useful for hosts that are connected to the Internet intermittently. @node -qR<@dfn{flags}> <@dfn{string}>, -qS<@dfn{flags}> <@dfn{string}>, -qq, Command line options @findex -qR<@dfn{flags}> <@dfn{string}> @unnumberedsubsec -qR<@dfn{flags}> <@dfn{string}> This option is synonymous with -@dfn{R}. It is provided for Sendmail compatibility. @node -qS<@dfn{flags}> <@dfn{string}>, -R<@dfn{flags}> <@dfn{string}>, -qR<@dfn{flags}> <@dfn{string}>, Command line options @findex -qS<@dfn{flags}> <@dfn{string}> @unnumberedsubsec -qS<@dfn{flags}> <@dfn{string}> This option is synonymous with -@dfn{S}. @node -R<@dfn{flags}> <@dfn{string}>, -r, -qS<@dfn{flags}> <@dfn{string}>, Command line options @findex -R<@dfn{flags}> <@dfn{string}> @unnumberedsubsec -R<@dfn{flags}> <@dfn{string}> @cindex queue: running @cindex delivery: to given domain @cindex domain: delivery to The <@dfn{flags}> may be empty, in which case the white space before the string is optional, unless the string is `f', `ff', `r', `rf', or `rff', which are the possible values for <@dfn{flags}>. White space is required if <@dfn{flags}> is not empty. This option is similar to -@dfn{q} with no time value, that is, it causes Exim to perform a single queue run, except that, when scanning the messages on the queue, Exim processes only those that have at least one undelivered address containing the given string, which is checked in a case-independent way. If the <@dfn{flags}> start with `r', <@dfn{string}> is interpreted as a regular expression; otherwise it is a literal string. @cindex frozen messages: forcing delivery If the <@dfn{flags}> contain `ff' then frozen messages are included; otherwise they are omitted. Once a message is selected, all its addresses are processed. For the first selected message, Exim overrides any retry information and forces a delivery attempt for each undelivered address. [(font color=green)] This means that if delivery of any address in the first message is successful, any existing retry information is deleted, and so delivery attempts for that address in subsequently selected messages (which are processed without forcing) will run. However, if delivery of any address does not succeed, the retry information is updated, and in subsequently selected messages, the failing address will be skipped. [(/font)] If the <@dfn{flags}> contain `f' or `ff' then the delivery forcing applies to all selected messages, not just the first. The -@dfn{R} option makes it straightforward to initiate delivery of all messages to a given domain after a host has been down for some time. When the SMTP command @sc{etrn} is permitted (see the @dfn{smtp_etrn_hosts} option), its default effect is to run Exim with the -@dfn{R} option, but it can be configured to run an arbitrary command instead. @node -r, -S<@dfn{flags}> <@dfn{string}>, -R<@dfn{flags}> <@dfn{string}>, Command line options @findex -r @unnumberedsubsec -r This is a documented (for Sendmail) obsolete alternative name for -@dfn{f}. @cindex delivery: from given sender @node -S<@dfn{flags}> <@dfn{string}>, -t, -r, Command line options @findex -S<@dfn{flags}> <@dfn{string}> @unnumberedsubsec -S<@dfn{flags}> <@dfn{string}> This option acts like -@dfn{R} except that it checks the string against each message's sender instead of against the recipients. If -@dfn{R} is also set, both conditions must be met for a message to be selected. If either of the options has `f' or `ff' in its flags, the associated action is taken. @node -t, -U, -S<@dfn{flags}> <@dfn{string}>, Command line options @findex -t @unnumberedsubsec -t @cindex recipients: @cindex Bcc: header @cindex Cc: header @cindex To: header When Exim is receiving a locally-generated, non-SMTP message on the current input, the -@dfn{t} option causes the recipients of the message to be obtained from the @dfn{To:}, @dfn{Cc:}, and @dfn{Bcc:} headers in the message instead of from the command arguments. The addresses are extracted before any rewriting takes place. If there are in fact any arguments, they specify addresses to which the message is @dfn{not} to be delivered. That is, the argument addresses are removed from the recipients list obtained from the headers. This is compatible with Smail 3 and in accordance with the documented behaviour of several versions of Sendmail, as described in man pages on a number of operating systems (e.g. Solaris 2.6, IRIX 6.5, HP-UX 11). However, some versions of Sendmail @dfn{add} argument addresses to those obtained from the headers, and a 1994 Sendmail book documents it that way. Exim can be made to behave in this way by setting the option @dfn{extract_addresses_remove_arguments} false. If a @dfn{Bcc:} header is present, it is removed from the message unless there is no @dfn{To:} or @dfn{Cc:} header, in which case a @dfn{Bcc:} header with no data is created, in accordance with RFC 822. @node -U, -v, -t, Command line options @findex -U @unnumberedsubsec -U Sendmail uses this option for `initial message submission', and its documentation states that in future releases, it may complain about syntactically invalid messages rather than fixing them when this flag is not set. Exim ignores this option. @node -v, -x, -U, Command line options @findex -v @unnumberedsubsec -v This option has exactly the same effect as -@dfn{d1}; it causes Exim to be `verbose' and produce some output describing what it is doing on the standard error file. In particular, if an SMTP connection is made, the SMTP dialogue is shown. @node -x, , -v, Command line options @findex -x @unnumberedsubsec -x AIX uses -@dfn{x} for a private purpose (`mail from a local mail program has National Language Support extended characters in the body of the mail item'). It sets -@dfn{x} when calling the MTA from its @dfn{mail} command. Exim ignores this option. @node 6[[[]]] File and database lookups, The Exim configuration file, 5[[[]]] The Exim command line, Top @chapter 6[[[]]] File and database lookups @cindex file: lookup @cindex database: lookup @cindex lookup: Exim can be configured to look up data in files or databases in a number of different circumstances (see 6.4 below). Two different styles of data lookup are implemented: @itemize @bullet @item The @dfn{single-key} style requires the specification of a file in which to look, and a single key to search for. The lookup type determines how the file is searched. @item The @dfn{query} style accepts a generalized database query, which may contain one or more keys. @end itemize The code for each lookup type is in a separate source file which is compiled and included in the binary of Exim only if the corresponding compile-time option is set. The default settings in @file{src/EDITME} are: @example LOOKUP_DBM=yes LOOKUP_LSEARCH=yes @end example which means that only linear searching and DBM lookups are included by default. @sp 2 @menu * Single-key lookup types:: * An lsearch file is not an item list:: * Query-style lookup types:: * Use of data lookups:: * Temporary errors in lookups:: * Default values in single-key lookups:: * Partial matching in single-key lookups:: * Lookup caching:: * Quoting lookup data:: * More about NIS+:: * More about LDAP:: * More about MySQL and PostgreSQL:: * More about dnsdb:: @end menu @node Single-key lookup types, An lsearch file is not an item list, 6[[[]]] File and database lookups, 6[[[]]] File and database lookups @section 6[[[]]]1 Single-key lookup types @cindex lookup: single key The following single-key lookup types are implemented: @itemize @bullet @item @cindex linear search @cindex lookup: lsearch @dfn{lsearch}: The given file is a text file which is searched linearly for a line beginning with the single key, terminated by a colon or white space or the end of the line. White space between the key and the colon is permitted. The remainder of the line, with leading and trailing white space removed, is the data. This can be continued onto subsequent lines by starting them with any amount of white space, but only a single space character is included in the data at such a junction. If the data begins with a colon, the key must be terminated by a colon, for example: @example baduser: :fail: @end example Empty lines and lines beginning with # are ignored, even if they occur in the middle of an item. This is the traditional textual format of alias files. @item @cindex DBM @cindex lookup: dbm @dfn{dbm}: Calls to DBM library functions are used to extract data from the given DBM file by looking up the record with the given key. The terminating binary zero is included in the key that is passed to the DBM library. @item [(font color=green)] @cindex lookup: dbmnz @cindex lookup: dbm, terminating zero @cindex Courier @dfn{dbmnz}: This is the same as @dfn{dbm}, except that the terminating binary zero is not included in the key that is passed to the DBM library. You may need this if you want to look up data in files that are created by or shared with some other application that does not use terminating zeros. For example, you need to use @dfn{dbmnz} rather than @dfn{dbm} if you want to authenticate incoming SMTP calls using the passwords from Courier's @dfn{/etc/userdbshadow.dat} file. Exim's utility program for creating DBM files (@dfn{exim_dbmbuild}) includes the zeros by default, but has an option to omit them (see section 53.5). [(/font)] @item @cindex NIS @cindex lookup: NIS @dfn{nis}: The given file is the name of a NIS map, and a NIS lookup is done with the given key, excluding the terminating binary zero. There is a variant called @dfn{nis0} which does include the terminating binary zero in the key. This is reportedly needed for Sun-style alias files. Exim does not recognize NIS aliases; the full map names must be used. @item @cindex cdb @cindex lookup: cdb @dfn{cdb}: The given file is searched as a Constant DataBase file, using the key string without the terminating binary zero. The cdb format is designed for indexed files that are read frequently and never updated, except by total re-creation. As such, it is particulary suitable for large files containing aliases or other indexed data referenced by an MTA. Information about cdb can be found at @example http://www.pobox.com/~djb/cdb.html @end example The cdb distribution is not needed in order to build Exim with cdb support, as the code for reading cdb files is included directly in Exim itself. However, no means of building or testing cdb files is provided with Exim because these are available within the cdb distribution. @end itemize @node An lsearch file is not an item list, Query-style lookup types, Single-key lookup types, 6[[[]]] File and database lookups @section 6[[[]]]2 An lsearch file is not an item list There has been some confusion about the way @dfn{lsearch} lookups work, in particular in domain and host lists. An item in one of these lists may be a plain file name, or a file name preceded by a search type, and these behave differently. For a plain file name, for example @example local_domains = /etc/local-mail-domains @end example each line of the file is treated as if it appeared as an item in the list, and negated items, wild cards, and regular expressions may be present. However, if an item is specified as an @dfn{lsearch} lookup, for example @example local_domains = lsearch;/etc/local-mail-domains @end example then negated items, wild cards, and regular expressions may not be used, because @dfn{lsearch} is an indexed lookup method which, when given a key (the domain in the above example), yields a data value that corresponds to that key. The fact that the file is searched linearly does not make this kind of search any different from the other single-key lookup types, and an @dfn{lsearch} file can always be directly converted into one of the other types without change of function. Thus, the keys in @dfn{lsearch}ed files are literal strings and are not interpreted in any way. @node Query-style lookup types, Use of data lookups, An lsearch file is not an item list, 6[[[]]] File and database lookups @section 6[[[]]]3 Query-style lookup types The following query-style lookup types are implemented: @itemize @bullet @item @cindex NIS+ @cindex lookup: NIS+ @dfn{nisplus}: This does a NIS+ lookup using a query that may contain any number of keys, and which can specify the name of the field to be returned. See section 6.10 below. @item @cindex LDAP @cindex lookup: LDAP @dfn{ldap}: This does an LDAP lookup using a query in the form of a URL, and returns attributes from a single entry. There is a variant called @dfn{ldapm} which permits values from multiple entries to be returned. A third variant called @dfn{ldapdn} returns the Distinguished Name of a single entry instead of any attribute values. See section 6.11 below. @item @cindex MySQL @cindex lookup: MySQL @dfn{mysql}: The format of the query is an SQL statement that is passed to a MySQL database. See section 6.12 below. @item @cindex PostgreSQL @cindex lookup: PostgreSQL @dfn{pgsql}: The format of the query is an SQL statement that is passed to a PostgreSQL database. See section 6.12 below. @item @cindex DNS @cindex lookup: DNS @dfn{dnsdb}: This does a DNS search for a record whose domain name is the supplied query. The resulting data is the contents of the record. See section 6.13 below. @item @dfn{testdb}: This is a lookup type which is for use in debugging Exim. It is not likely to be useful in normal operation. @end itemize @node Use of data lookups, Temporary errors in lookups, Query-style lookup types, 6[[[]]] File and database lookups @section 6[[[]]]4 Use of data lookups There are three different types of configuration item in which data lookups can be specified: @enumerate @item Any string that is to be expanded may contain explicit lookup requests. String expansions are described in chapter 9. @item Some drivers can be configured directly to look up data in files. @item Lists of domains and other items can contain lookup requests as a way of avoiding excessively long linear lists. In this case, any data that is returned by the lookup is normally discarded; whether the lookup succeeds or fails is all that counts. However, in the case of the @dfn{domains} and @dfn{local_parts} options for directors and routers, the data is preserved in variables for later use. See sections 7.12, 7.13, and 7.16 for descriptions of the different list types. @end enumerate In a string expansion, all the parameters of the lookup are specified explicitly, while for the other types there is always one implicit key involved. For example, the @dfn{local_domains} option contains a list of local domains; when it is being searched there is some domain name that is an implicit key. This is not a problem for single-key lookups; the relevant file name is specified, and the key is implicit. For example, the list of local domains could be given as @example local_domains = dbm;/local/domain/list @end example However, for query-style lookups the entire query has to be specified, and to do this, some means of including the implicit key is required. @cindex $key The special expansion variable $@dfn{key} is provided for this purpose. NIS+ could be used to look up local domains by a setting such as @example local_domains = nisplus;[domain=$key],domains.org_dir @end example In cases where drivers can be configured to do lookups, there are always three alternative configuration options: @dfn{file} is used for single-key lookups, using an implicit key, and @dfn{query} or @dfn{queries} is specified for query-style lookups. In these cases the query is an expanded string, and the implicit key that would be used for @dfn{file} is always available as one of the normal expansion variables. The difference between @dfn{query} and @dfn{queries} is that in the latter case the string is treated as a colon-separated list of queries that are tried in order until one succeeds. @node Temporary errors in lookups, Default values in single-key lookups, Use of data lookups, 6[[[]]] File and database lookups @section 6[[[]]]5 Temporary errors in lookups @cindex lookup: temporary error Lookup functions can return temporary error codes if the lookup cannot be completed. (For example, a NIS or LDAP database might be unavailable.) For this reason, it is not advisable to use a lookup that might do this for critical options such as (to give an extreme example) @dfn{local_domains}. When a lookup cannot be completed in a transport, director, or router, delivery of the message is deferred, as for any other temporary error. In other circumstances Exim may assume the lookup has failed, or may give up altogether. These are some specific cases: @itemize @bullet @item @dfn{local_domains}, @dfn{hold_domains}, or @dfn{queue_remote_domains} during delivery: the address it is checking is deferred; other addresses may succeed if they match something earlier in the list. @item @dfn{domains}, @dfn{local_parts}, @dfn{senders}, or @dfn{condition} on a router or director: delivery is deferred. @item @dfn{local_domains}, @dfn{percent_hack_domains}, or @dfn{relay_domains} while receiving SMTP: a 451 temporary error is given to the RCPT command. @item @dfn{local_domains} during verification: a temporary error given. @item @dfn{mx_domains} during lookuphost: delivery is deferred. @item @dfn{mx_domains} in the smtp transport (for hosts specified on the transport): treat as not matching. @item @dfn{queue_smtp_domains} in the smtp transport: treat as not matching -- otherwise all SMTP deliveries would be held up. @end itemize @node Default values in single-key lookups, Partial matching in single-key lookups, Temporary errors in lookups, 6[[[]]] File and database lookups @section 6[[[]]]6 Default values in single-key lookups @cindex wildcard lookups @cindex lookup: default values @cindex lookup: wildcard @cindex lookup: * @cindex defaults for lookups In this context, a `default value' is a value specified by the administrator that is to be used if a lookup fails. If `*' is added to a single-key lookup type (for example, @dfn{lsearch*}) and the initial lookup fails, the key `*' is looked up in the file to provide a default value. See also the section on partial matching below. @cindex *@@ @cindex lookup: *@@ @cindex alias file: per-domain default Alternatively, if `*@@' is added to a single-key lookup type (for example @dfn{dbm*@@}) then, if the initial lookup fails and the key contains an @@ character, a second lookup is done with everything before the last @@ replaced by *. This makes it possible to provide per-domain defaults in alias files that include the domains in the keys. If the second lookup fails (or doesn't take place because there is no @@ in the key), `*' is looked up. @node Partial matching in single-key lookups, Lookup caching, Default values in single-key lookups, 6[[[]]] File and database lookups @section 6[[[]]]7 Partial matching in single-key lookups @cindex partial matching @cindex wildcard lookups @cindex lookup: partial matching The normal operation of a single-key lookup is to search the file for an exact match with the given key. However, in a number of situations where domains are being looked up, it is useful to be able to do partial matching. In this case, information in the file that has a key starting with `*.' is matched by any domain that ends with the components that follow the full stop. For example, if a key in a DBM file is @example *.dates.fict.book @end example then when partial matching is enabled this is matched by (amongst others) @dfn{2001.dates.fict.book} and @dfn{1984.dates.fict.book}. It is also matched by @dfn{dates.fict.book}, if that does not appear as a separate key in the file. Partial matching is implemented by doing a series of separate lookups using keys constructed by modifying the original subject key. This means that it can be used with any of the single-key lookup types, provided that the special partial-matching keys beginning with `*.' are included in the data file. Keys in the file that do not begin with `*.' are matched only by unmodified subject keys when partial matching is in use. Partial matching is requested by adding the string `partial-' to the front of the name of a single-key lookup type, for example, @dfn{partial-dbm}. When this is done, the subject key is first looked up unmodified; if that fails, `*.' is added at the start of the subject key, and it is looked up again. If that fails, further lookups are tried with dot-separated components removed from the start of the subject key, one-by-one, and `*.' added on the front of what remains. A minimum number of two non-* components are required. This can be adjusted by including a number before the hyphen in the search type. For example, @dfn{partial3-lsearch} specifies a minimum of three non-* components in the modified keys. Omitting the number is equivalent to `partial2-'. If the subject key is @dfn{2250.dates.fict.book} then the following keys are looked up when the minimum number of non-* components is two: @example 2250.dates.fict.book *.2250.dates.fict.book *.dates.fict.book *.fict.book @end example As soon as one key in the sequence is successfully looked up, the lookup finishes. If `partial0-' is used, the original key gets shortened right down to the null string, and the final lookup is for `*' on its own. If the search type ends in `*' or `*@@' (see section 6.6 above), the search for an ultimate default that this implies happens after all partial lookups have failed. If `partial0-' is specified, adding `*' to the search type has no effect, because the `*' key is already included in the sequence of partial lookups. The use of `*' in lookup partial matching differs from its use as a wildcard in domain lists and the like. Partial matching works only in terms of dot-separated components; a key such as @file{*fict.book} in a database file is useless, because the asterisk in a partial matching subject key is always followed by a dot. @node Lookup caching, Quoting lookup data, Partial matching in single-key lookups, 6[[[]]] File and database lookups @section 6[[[]]]8 Lookup caching @cindex lookup: caching @cindex caching lookup data Exim caches the most recent lookup result on a per-file basis for single-key lookup types, and keeps the relevant files open. In some types of configuration this can lead to many files being kept open for messages with many recipients. To avoid hitting the operating system limit on the number of simultaneously open files, Exim closes the least recently used file when it needs to open more files than its own internal limit, which can be changed via the @dfn{lookup_open_max} option. For query-style lookups, a single data cache per lookup type is kept. The files are closed and the caches flushed at strategic points during delivery -- for example, after all directing and routing is complete. @node Quoting lookup data, More about NIS+, Lookup caching, 6[[[]]] File and database lookups @section 6[[[]]]9 Quoting lookup data @cindex lookup: quoting @cindex quoting: in lookups When data from an incoming message is included in a query-style lookup, there is the possibility of special characters in the data messing up the syntax of the query. For example, a NIS+ query that contains @example [name=$local_part] @end example will be broken if the local part happens to contain a closing square bracket. For NIS+, data can be enclosed in double quotes like this: @example [name="$local_part"] @end example but this still leaves the problem of a double quote in the data. The rule for NIS+ is that double quotes must be doubled. Other lookup types have different rules, and to cope with the differing requirements, an expansion operator of the following form is provided: @example $@{quote_<@dfn{lookup-type}>:<@dfn{string}>@} @end example For example, the safest way to write the NIS+ query is @example [name="$@{quote_nisplus:$local_part@}"] @end example See chapter 9 for full coverage of string expansions. The quote operator can be used for all lookup types, but has no effect for single-key lookups, since no quoting is ever needed in their key strings. @node More about NIS+, More about LDAP, Quoting lookup data, 6[[[]]] File and database lookups @section 6[[[]]]10 More about NIS+ @cindex NIS+ @cindex lookup: NIS+ NIS+ queries consist of a NIS+ @dfn{indexed name} followed by an optional colon and field name. If this is given, the result of a successful query is the contents of the named field; otherwise the result consists of a concatenation of @dfn{field-name=field-value} pairs, separated by spaces. Empty values and values containing spaces are quoted. For example, the query @example [name=mg1456],passwd.org_dir @end example might return the string @example name=mg1456 passwd="" uid=999 gid=999 gcos="Martin Guerre" home=/home/mg1456 shell=/bin/bash shadow="" @end example (split over two lines here to fit on the page), whereas @example [name=mg1456],passwd.org_dir:gcos @end example would just return @example Martin Guerre @end example with no quotes. A NIS+ lookup fails if NIS+ returns more than one table entry for the given indexed key. The effect of the @dfn{quote_nisplus} expansion operator is to double any quote characters within the text. @node More about LDAP, More about MySQL and PostgreSQL, More about NIS+, 6[[[]]] File and database lookups @section 6[[[]]]11 More about LDAP @cindex LDAP @cindex lookup: LDAP The original LDAP implementation came from the University of Michigan; this has become `Open LDAP', and there are now two different releases. Another implementation comes from Netscape, and Solaris 7 and subsequent releases contain inbuilt LDAP support. Unfortunately, though these are all compatible at the lookup function level, their error handling is different. For this reason it is necessary to set a compile-time variable when building Exim with LDAP, to indicate which LDAP library is in use. One of the following should appear in your @file{Local/Makefile}: @example LDAP_LIB_TYPE=UMICHIGAN LDAP_LIB_TYPE=OPENLDAP1 LDAP_LIB_TYPE=OPENLDAP2 LDAP_LIB_TYPE=NETSCAPE LDAP_LIB_TYPE=SOLARIS @end example If @sc{ldap_lib_type} is not set, Exim assumes OpenLDAP 1, which has the same interface as the University of Michigan version. There are three LDAP lookup types, which behave slightly differently in the way they handle the results of a query. @itemize @bullet @item @dfn{ldap} requires the result to contain just one entry; if there are more, it gives an error. @item @dfn{ldapdn} also requires the result to contain just one entry, but it is the Distinguished Name that is returned rather than any attribute values. @item @dfn{ldapm} permits the result to contain more than one entry; the attributes from all of them are returned. @end itemize An LDAP query takes the form of a URL as defined in RFC 2255. For example, in the configuration of an @dfn{aliasfile} director one might have these settings: @example search_type = ldap query = ldap:///cn=$local_part,o=University%20of%20Cambridge,\ c=UK?mailbox?base? @end example Two levels of quoting are required in LDAP queries, the first for LDAP and the second because the LDAP query is represented as a URL. The @dfn{quote_ldap} expansion operator implements the following rules: @itemize @bullet @item For LDAP quoting, the characters #,+"\<>;*() have to be preceded by a backslash. (In fact, only some of these need to be quoted in Distinguished Names, and others in LDAP filters, but it does no harm to have a single quoting rule for all of them.) @item For URL quoting, all characters except alphanumerics and !$'()*+-._ are replaced by %@dfn{xx} where @dfn{xx} is the hexadecimal character code. Note that backslash has to be quoted in a URL, so characters that are escaped for LDAP end up preceded by %5C in the final encoding. @end itemize The example above does not specify an LDAP server. A server can be specified in a query by starting it with @example ldap://<@dfn{hostname}>:<@dfn{port}>/... @end example If the port (and preceding colon) are omitted, the standard LDAP port (389) is used. When, however, no server is specified in a query, a list of default servers is taken from the @dfn{ldap_default_servers} configuration option. This supplies a colon-separated list of servers which are tried in turn until one successfully handles a query, or there is a serious error. Successful handling either returns the requested data, or indicates that it does not exist. Serious errors are syntactical, or multiple values when only a single value is expected. Errors which cause the next server to be tried are connection failures, bind failures, and timeouts. For each server name in the list, a port number can be given. The standard way of specifing a host and port is to use a colon separator (RFC 1738). Because @dfn{ldap_default_servers} is a colon-separated list, such colons have to be doubled. For example @example ldap_default_servers = ldap1.example.com::145:ldap2.example.com @end example If @dfn{ldap_default_servers} is unset, a URL with no server name is passed to the LDAP library with no server name, and the library's default (normally the local host) is used. The LDP URL syntax provides no way of passing authentication and other control information to the server. To make this possible, the URL in an LDAP query may be preceded by any number of `<@dfn{name}>=<@dfn{value}>' settings, separated by spaces. If a value contains spaces it must be enclosed in double quotes, and when double quotes are used, backslash is interpreted in the usual way inside them. The following names are recognized: @example USER set the DN, for authenticating the LDAP bind PASS set the password, likewise SIZE set the limit for the number of entries returned TIME set the maximum waiting time for a query @end example The values may be given in any order. The default is no time limit, and no limit on the number of entries returned. Here is an example of an LDAP query in an Exim lookup which uses some of these values. This is a single line, folded for ease of reading: @example $@{lookup ldap @{user="cn=manager,o=University of Cambridge,c=UK" pass=secret ldap:///o=University%20of%20Cambridge,c=UK?sn?sub?(cn=foo)@} @{$value@}fail@} @end example The encoding of spaces as %20 is a URL thing which should not be done for any of the auxiliary data. Exim configuration settings that include lookups which contain password information should be preceded by `hide' to prevent non-admin users from using the -@dfn{bP} option to see their values. The @dfn{ldapdn} lookup type returns the Distinguished Name from a single entry as a sequence of values, for example @example cn=manager, o=University of Cambridge, c=UK @end example For @dfn{ldap} and @dfn{ldapm}, if a query finds only entries with no attributes, Exim behaves as if the entry did not exist, and the lookup fails. The @dfn{ldap} lookup type generates an error if more than one entry matches the search filter, whereas @dfn{ldapm} permits this case, and inserts a newline in the result between the data from different entries. It is possible for multiple values to be returned for both @dfn{ldap} and @dfn{ldapm}, but in the former case you know that whatever values are returned all came from a single entry in the directory. In the common case where you specify a single attribute in your LDAP query, the result is not quoted, and if there are multiple values, they are separated by commas. If you specify multiple attributes, they are returned as space-separated strings, quoted if necessary, preceded by the attribute name. For example, @example ldap:///o=base?attr1,attr2?sub?(uid=fred) @end example might yield @example attr1="value one" attr2=value2 @end example If you do not specify any attributes in the search, the same format is used for all attributes in the entry. For example, @example ldap:///o=base??sub?(uid=fred) @end example might yield @example objectClass=top attr1="value one" attr2=value2 @end example The @dfn{extract} operator in string expansions can be used to pick out individual fields from such data. @node More about MySQL and PostgreSQL, More about dnsdb, More about LDAP, 6[[[]]] File and database lookups @section 6[[[]]]12 More about MySQL and PostgreSQL @cindex MySQL @cindex PostgreSQL @cindex lookup: MySQL @cindex PostgreSQL If any MySQL or PostgreSQL lookups are used, the @dfn{mysql_servers} or @dfn{pgsql_servers} option (as appropriate) must be set to a colon-separated list of slash-separated host, database, user, password, tuples. Because password data is sensitive, you should precede the setting with `hide', to prevent non-admin users from obtaining the setting via the -@dfn{bP} option. For example: @example hide mysql_servers = localhost/users/root/secret:\ otherhost/users/root/othersecret @end example [(font color=green)] For MySQL, an empty server name causes a connection to the server on the local host by means of a Unix domain socket. [(/font)] For each query, these parameter groups are tried in order until a connection and a query succeeds. For MySQL, no database need be supplied -- if it is absent, it must be given in the queries. A host may be specified as <@dfn{name}>:<@dfn{port}> but because this is a colon-separated list, the colon has to be doubled. Queries are SQL statements, so an example might be @example $@{lookup mysql@{select mailbox from users where id='ph10'@}@{$value@}fail@} @end example If the result of the query contains more than one field, the data for each field in the row is returned, preceded by its name, so the result of @example $@{lookup pgsql@{select home,name from users where id='ph10'@}@{$value@}@} @end example might be @example home=/home/ph10 name="Philip Hazel" @end example Values containing spaces and empty values are double quoted, with embedded quotes escaped by a backslash. If the result of the query contains just one field, the value is passed back verbatim, without a field name, for example: @example Philip Hazel @end example If the result of the query yields more than one row, it is all concatenated, with a newline between the data for each row. The @dfn{quote_mysql} and @dfn{quote_pgsql} expansion operators convert newline, tab, carriage return, and backspace to \n, \t, \r, and \b respectively, and the characters single-quote, double-quote, and backslash are escaped with backslashes. The @dfn{quote_pgsql} expansion operator, in addition, escapes the percent and underscore characters. This cannot be done for MySQL because these escapes are not recognized in contexts where these characters are not special. @node More about dnsdb, , More about MySQL and PostgreSQL, 6[[[]]] File and database lookups @section 6[[[]]]13 More about dnsdb @cindex dnsdb @cindex lookup: dnsdb The @dfn{dnsdb} lookup type uses the DNS as its database. A query consists of a record type and a domain name, separated by an equals sign. For example, an expansion string could contain: @example $@{lookup dnsdb@{mx=a.b.example@}@{$value@}fail@} @end example The supported record types are A, CNAME, MX, NS, PTR, and TXT, and, when Exim is compiled with IPv6 support, AAAA and A6. If no type is given, TXT is assumed. When the type is PTR, the address should be given as normal; it gets converted to the necessary inverted format internally. For example: @example $@{lookup dnsdb@{ptr=192.168.4.5@}@{$value@}fail@} @end example For MX records, both the preference value and the host name are returned, separated by a space. If multiple records are found (or, for A6 lookups, if a single record leads to multiple addresses), the data is returned as a concatenation, separated by newlines. The order, of course, depends on the DNS resolver. @node 7[[[]]] The Exim configuration file, Regular expressions, 6[[[]]] File and database lookups, Top @chapter 7[[[]]] The Exim configuration file @cindex run time configuration @cindex configuration: run time @cindex CONFIGURE_FILE Exim uses a single run time configuration file which is read whenever an Exim binary is executed. The name of the file is compiled into the binary for security reasons, and is specified by the @sc{configure_file} compilation option. @cindex configuration file: alternate Some sites may wish to use the same Exim binary on different machines that share a file system, but to use different configuration files on each machine. If @sc{configure_file_use_node} is defined in @file{Local/Makefile}, Exim first looks for a file whose name is the configuration file name followed by a dot and the machine's node name, as obtained from the @dfn{uname()} function. If this file does not exist, the standard name is tried. In some esoteric situations different versions of Exim may be run under different effective uids and the @sc{configure_file_use_euid} is defined to help with this. See the comments in @file{src/EDITME} for details. @cindex EXIM_USER @cindex EXIM_GROUP @cindex configuration file: ownership @cindex ownership: configuration file The run time configuration file must be owned by root or by the user that is specified at compile time by the @sc{exim_uid} option, and it must not be world-writeable or group-writeable, unless its group is the one specified at compile time by the @sc{exim_gid} option. @cindex alternate configuration file @cindex configuration file: alternate Macros in the configuration file can be overridden by the -@dfn{D} command line option, and a one-off alternative configuration file can be specified by the -@dfn{C} command line option, but if either of these options are used, Exim immediately gives up its root privilege, unless called by root or the Exim user. -@dfn{C} is useful mainly for checking the syntax of configuration files before installing them. No owner or group checks are done on a configuration file specified by -@dfn{C}. A default configuration file, which will work correctly in simple situations, is provided in the file @dfn{src/configure.default}. The installation process copies this into @sc{configure_file} if there is no previously-existing configuration file. @cindex configuration file: errors @cindex errors: in configuration file If a syntax error is detected while reading the configuration file, Exim writes a message on the standard error, and exists with a non-zero return code. The message is also written to the panic log. @sp 2 @menu * Configuration file format:: * Macros in the configuration file:: * Common option syntax:: * Integer:: * Octal integer:: * Fixed point number:: * Time interval:: * String:: * Expanded strings:: * User and group names:: * List construction:: * Domain lists:: * Host lists:: * Mixing host names and addresses in host lists:: * Use of RFC 1413 identification in host lists:: * Address lists:: * Case of letters in address lists:: @end menu @node Configuration file format, Macros in the configuration file, 7[[[]]] The Exim configuration file, 7[[[]]] The Exim configuration file @section 7[[[]]]1 Configuration file format @cindex configuration file: format @cindex format: configuration file Exim's configuration file is in seven parts, which must appear in the correct order in the file, separated by lines containing just the word `end'. However, any parts at the end of the file that are not required may be omitted. The file contains: @itemize @bullet @item Main configuration settings: options for controlling input, and other overall parameters that are not specific to any of the drivers. @item Configuration settings for the transport drivers. Transports define mechanisms for copying messages to destinations. @item Configuration settings for the director drivers. Directors process local addresses, that is, those with domains that match @dfn{local_domains}. These are typically (but not necessarily) delivered on the local host. @item Configuration settings for the router drivers. Routers process remote addresses, that is, those with domains that do not match @dfn{local_domains}. @item Retry rules, for use when a message cannot be immediately delivered. @item Address rewriting rules, for use when a message arrives and when new addresses are generated during delivery. @item Configuration settings for the authenticator drivers. These are concerned with the SMTP @sc{auth} command (see chapter 35), and this part of the configuration can be omitted when @sc{auth} is not in use. @end itemize Blank lines in the file, and lines starting with a # character (ignoring leading white space) are treated as comments and are ignored. Note that a # character other than at the beginning of a line is not treated specially, and does not introduce a comment. Any non-comment line can be continued by ending it with a backslash. Trailing white space after the backslash is ignored, and leading white space at the start of continuation lines is also ignored. Comment lines may appear in the middle of a sequence of continuation lines. A convenient way to create a configuration file is to start from the default, which is supplied in @dfn{src/configure.default}, and add, delete, or change settings as required. The retry and rewriting rules have their own syntax which is described in chapters 33 and 34, respectively. The other parts of the configuration file (whose settings are described in chapters 11--32 and 35--37) have some syntactic items in common, and these are described below, from section 7.3 onwards. Before that, the simple macro facility is introduced. @node Macros in the configuration file, Common option syntax, Configuration file format, 7[[[]]] The Exim configuration file @section 7[[[]]]2 Macros in the configuration file @cindex macros in configuration file @cindex configuration file: macros If a line in the main part of the configuration (that is, before the first `end' line) begins with an upper-case letter, it is taken as a macro definition, and must be of the form @example <@dfn{name}> = <@dfn{rest of line}> @end example The name must consist of letters, digits, and underscores, and need not all be in upper-case, though that is recommended. The rest of the line, including any continuations, is the replacement text, and has leading and trailing white space removed. Quotes are not removed. The replacement text can never end with a backslash character, but this doesn't seem to be a serious limitation. Once a macro is defined, all subsequent lines in the file are scanned for the macro name; if there are several macros, the line is scanned for each in turn, in the order in which they are defined. The replacement text is not re-scanned for the current macro, though it will be for subsequently defined macros. For this reason, a macro name may not contain the name of a previously defined macro as a substring. You could, for example, define @example ABCD_XYZ = <> ABCD = <> @end example but putting the definitions in the opposite order would provoke a configuration error. As an example of macro usage, suppose you have lots of local domains, but they fall into three different categories. You could set up @example LOCAL1 = domain1:\ domain2 LOCAL2 = domain3:domain4 LOCAL3 = dbm;/list/of/other/domains local_domains = LOCAL1:LOCAL2:LOCAL3 @end example and then use the @dfn{domains} option on appropriate directors to handle each set of domains differently. This avoids having to list each domain in more than one place. [(b)]Warning[(/b)]: This technique is convenient only for positive lists. Because it is just a textual replacement, preceding a macro name in a list with ! has the effect of negating just the first item within the macro, not all of them. @node Common option syntax, Integer, Macros in the configuration file, 7[[[]]] The Exim configuration file @section 7[[[]]]3 Common option syntax @cindex common option syntax @cindex syntax of common options @cindex configuration file: common option syntax For the main set of options and for driver options, each setting is on a line by itself, and starts with a name consisting of lower-case letters and underscores. Many options require a data value, and in these cases the name must be followed by an equals sign (with optional white space) and then the value. For example: @example qualify_domain = mydomain.example.com @end example Some option settings may contain sensitive data, for example, passwords for accessing databases. To stop non-admin users from using the -@dfn{bP} command line option to read their values, you can precede them with the word `hide'. For example: @example hide mysql_servers = localhost/users/admin/secret-password @end example For non-admin users, such options are displayed like this: @example mysql_servers = @end example If `hide' is used on a driver option, it hides the value of that option on all instances of the same driver. Options whose type is given as boolean are on/off switches that are not always followed by a data value. If the option name is specified on its own without data, the switch is turned on; if it is preceded by `no_' or `not_' the switch is turned off. However, boolean options may be followed by an equals sign and one of the words `true', `false', `yes', or `no'. For example: @example sender_verify no_smtp_verify queue_only = true @end example The types of data that are used by non-boolean options are described in the following sections. @node Integer, Octal integer, Common option syntax, 7[[[]]] The Exim configuration file @section 7[[[]]]4 Integer @cindex integer format @cindex format: integer If a numerical data item starts with the characters `0x', the remainder of it is interpreted as a hexadecimal number. Otherwise, it is treated as octal if it starts with the digit 0, and decimal if not. If an integer value is followed by the letter K, it is multiplied by 1024; if it is followed by the letter M, it is multiplied by 1024x1024. When the values of integer option settings are output, values which are an exact multiple of 1024 or 1024x1024 are printed using the letters K and M. The printing style is independent of the actual input format that was used. @node Octal integer, Fixed point number, Integer, 7[[[]]] The Exim configuration file @section 7[[[]]]5 Octal integer @cindex integer format @cindex format: octal integer The value of an option specified as an octal integer is always interpreted in octal, whether or not it starts with the digit zero. Such options are always output in octal. @node Fixed point number, Time interval, Octal integer, 7[[[]]] The Exim configuration file @section 7[[[]]]6 Fixed point number @cindex fixed point format @cindex format: fixed point A fixed point number consists of a decimal integer, optionally followed by a decimal point and up to three further digits. @node Time interval, String, Fixed point number, 7[[[]]] The Exim configuration file @section 7[[[]]]7 Time interval @cindex time interval format @cindex format: time interval A time interval is specified as a sequence of numbers, each followed by one of the following letters, with no intervening white space: @display @dfn{s} seconds @dfn{m} minutes @dfn{h} hours @dfn{d} days @dfn{w} weeks @end display For example, `3h50m' specifies 3 hours and 50 minutes. The values of time intervals are output in the same format. @node String, Expanded strings, Time interval, 7[[[]]] The Exim configuration file @section 7[[[]]]8 String @cindex string: format @cindex format: string If a string data item does not start with a double-quote character, it is taken as consisting of the remainder of the line plus any continuation lines, starting at the first character after any white space, with trailing white space characters removed, and with no interpretation of the characters therein. Because Exim removes comment lines (those beginning with #) at an early stage, they can appear in the middle of a multi-line string. The following settings are therefore equivalent: @example trusted_users = uucp:mail trusted_users = uucp:\ # This comment line is ignored mail @end example If a string does start with a double-quote, it must end with a closing double-quote, and any backslash characters other than those used for line continuation are interpreted as escape characters, as follows: @example \\ single backslash \n newline \r carriage return \t tab \<@dfn{octal digits}> up to 3 octal digits specify one character \x<@dfn{hex digits}> up to 2 hexadecimal digits specify one character @end example If a backslash is followed by some other character, including a double-quote character, that character replaces the pair. Quoting is necessary only if you want to make use of the backslash escapes to insert special characters, or if you need to specify a value with leading or trailing spaces. However, in versions of Exim before 3.14, quoting was required in order to continue lines, so you may come across older configuration files and examples that apparently quote unnecessarily. @node Expanded strings, User and group names, String, 7[[[]]] The Exim configuration file @section 7[[[]]]9 Expanded strings Some strings in the configuration file are subjected to @dfn{string expansion}, by which means various parts of the string may be changed according to the circumstances (see chapter 9). The input syntax for such strings is as just described; in particular, the handling of backslashes in quoted strings is done as part of the input process, before expansion takes place. However, backslash is also an escape character for the expander, so any backslashes that are required for that reason must be doubled if they are within a quoted configuration string. @node User and group names, List construction, Expanded strings, 7[[[]]] The Exim configuration file @section 7[[[]]]10 User and group names @cindex user name format @cindex format: user name @cindex group name format @cindex format: group name User and group names are specified as strings, using the syntax described above, but the strings are interpreted specially. In the main section of the configuration file, a user or group name must either consist entirely of digits, or be a name that can be looked up using the @dfn{getpwnam()} or @dfn{getgrnam()} function, as appropriate. When a user or group is specified as an option for a driver, it may alternatively be a string that gets expanded each time the user or group value is required. The presence of a @dfn{$} character in the string causes this action to happen. Each time the string is expanded, the result must either be a digit string, or a name that can be looked up using @dfn{getpwnam()} or @dfn{getgrnam()}, as appropriate. @node List construction, Domain lists, User and group names, 7[[[]]] The Exim configuration file @section 7[[[]]]11 List construction @cindex list: construction @cindex format: list Some configuration settings accept a colon-separated list of items. In these cases, the entire list is treated as a single string as far as the input syntax is concerned. The @dfn{trusted_users} setting in section 7.8 above is an example. If a colon is actually needed in an item in a list, it must be entered as two colons. Leading and trailing white space on each item in a list is ignored. This makes it possible to include items that start with a colon, and in particular, certain forms of IPv6 address. For example, the list @example local_interfaces = 127.0.0.1 : ::::1 @end example contains two IP addresses, the IPv4 address 127.0.0.1 and the IPv6 address ::1. IPv6 addresses are going to become more and more common as the new protocol gets more widely deployed. @cindex list: separator, changing @cindex IPv6 addresses in lists Doubling their colons is an unwelcome chore, so a mechanism was introduced to allow the separator character to be changed. If a list begins with a left angle bracket, followed by any punctuation character, that character is used instead of colon as the list separator. For example, the list above can be rewritten to use a semicolon separator like this: @example local_interfaces = <; 127.0.0.1 ; ::1 @end example This facility applies to all lists, with the exception of the lists in @dfn{log_file_path} and @dfn{tls_verify_ciphers}. It is recommended that the use of non-colon separators be confined to circumstances where they really are needed. @node Domain lists, Host lists, List construction, 7[[[]]] The Exim configuration file @section 7[[[]]]12 Domain lists @cindex domain: list format @cindex format: domain list @cindex list: domain list Domain lists are constructed as described in section 7.11. They contain patterns that are to be matched against a mail domain. For example, the @dfn{local_domains} option is a domain list, one of whose patterns must match every domain that Exim is to treat as local. @cindex negation: in domain lists @cindex list: negation Items in a domain list may be positive or negative. Negative items are indicated by a leading exclamation mark, which may be followed by optional white space. The list is scanned from left to right. If the domain matches a positive item, it is in the set of domains which the list defines; if it matches a negative item, it is not in the set. If the end of the list is reached without the domain having matched any of the patterns, it is accepted if the last item was a negative one, but not if it was a positive one. For example, @example relay_domains = !a.b.c : *.b.c @end example matches any domain ending in @file{.b.c} except for @file{a.b.c}. Domains that match neither @file{a.b.c} nor @file{*.b.c} are not accepted, because the last item in the list is positive. However, if the setting were @example relay_domains = !a.b.c @end example then all domains other than @file{a.b.c} would be accepted because the last item in the list is negative. In effect, a list that ends with a negative item behaves as if it had @file{: *} appended to it. The following types of item may appear in domain lists: @itemize @bullet @item @cindex primary host name @cindex host: name @cindex primary_hostname If an item in a domain list is a plain absolute file name (beginning with a slash character), each line of the file is read and processed as if it were an independent item in the list, except that further plain file names are not allowed. This happens each time the list is searched. If a # character appears anywhere in a line of the file, it and all following characters are ignored. Blank lines are also ignored. Wild cards, negation, and regular expressions may be used in the lines of the file, just as in the main list. For example, if @example local_domains = /etc/local-domains @end example then the file could contain lines like @example ^.*\d@{3@}\.mydomain\.com$ @end example If a plain file name is preceded by an exclamation mark, the sense of any match within the file is inverted. For example, if @example hold_domains = !/etc/nohold-domains @end example and the file contains the lines @example !a.b.c *.b.c @end example then @file{a.b.c} is in the set of domains defined by @dfn{hold_domains}, whereas any domain matching @file{*.b.c} is not. @item If a pattern consists of a single @@ character, it matches the local host name, as set in the @dfn{primary_hostname} option. This makes it possible to use the same configuration file on several different hosts that differ only in their names. @item If a pattern starts with an asterisk, the remaining characters of the pattern are compared with the terminating characters of the domain. The use of `*' in domain lists differs from its use in partial matching lookups. In a domain list, the character following the asterisk need not be a dot, whereas partial matching works only in terms of dot-separated components. For example, a domain list item such as @file{*key.ex} matches @file{donkey.ex} as well as @file{cipher.key.ex}. @item @cindex regular expressions: in domain list If a pattern starts with a circumflex character, it is treated as a regular expression, and matched against the domain using a regular expression matching function. The circumflex is treated as part of the regular expression. References to descriptions of the syntax of regular expressions are given in chapter 8, but note that if a backslash is required in the regular expression, it must be given as two backslashes if the string is in quotes. There are some cases where a domain list is the result of string expansion, for example the @dfn{domains} option in routers and directors. In these cases you must escape any backslash and dollar characters in regular expressions, to prevent them from being interpreted by the string expander, and if the string is specified in quotes, the resulting backslashes must themselves also be escaped. @item If a pattern starts with the name of a single-key lookup type followed by a semicolon (for example, `dbm;' or `lsearch;') then the remainder of the pattern must be a file name in a suitable format for the lookup type. For example, for [(font color=green)] `cdb;' it must be an absolute path: @example local_domains = cdb;/etc/mail/local_domains.cdb @end example The appropriate type of lookup is done on the file using the domain name as the key. In most cases, the data that is looked up is not used; Exim is interested only in whether or not the key is present in the file. However, when a lookup is used for the @dfn{domains} option on a director or router, the data is preserved in the $@dfn{domain_data} variable and can be referred to in other options. [(/font)] Note that this type of entry is not an `include' facility when the lookup type is `lsearch'. The keys in the file are not interpreted specially, as they would be if they appeared as individual items in the domain list, or as lines in a file referenced without a search type. @item Any of the single-key lookup type names may be preceded by `partial<@dfn{n}>-', where the <@dfn{n}> is optional, for example, @example partial-dbm;/partial/domains @end example This causes partial matching logic to be invoked; a description of how this works is given in section 6.7. @item Any of the single-key lookup types may be followed by an asterisk. This causes a default lookup for a key consisting of a single asterisk to be done if the original lookup fails. This is not a useful feature when using a domain list to select particular domains (because any domain would match), but it might have value if the result of the lookup is being used via the $@dfn{domain_data} expansion variable. @item If the pattern starts with the name of a query-style lookup type followed by a semicolon (for example, `nisplus;' or `ldap;'), the remainder of the pattern must be an appropriate query for the lookup type, as described in chapter 6. @cindex $key The query is expanded before use, and the expansion substitution $@dfn{key} can be used to insert the domain that is being tested into the query. [(font color=green)] For example: @example local_domains = mysql;select domain from domainlist \ where domain = '$key'; @end example In most cases, the data that is looked up is not used (so for an SQL query, for example, it doesn't matter what field you select). Exim is interested only in whether or not the key is present in the file. However, when a lookup is used for the @dfn{domains} option on a director or router, the data is preserved in the $@dfn{domain_data} variable and can be referred to in other options. [(/font)] @item If none of the above cases apply, a caseless textual comparison is made between the pattern and the domain. @end itemize Here is an example which uses several different kinds of pattern: @example local_domains = @@:\ lib.unseen.edu:\ *.foundation.fict.book:\ ^[1-2]\d@{3@}\.fict\.book$:\ partial-dbm;/opt/data/penguin/book:\ nis;domains.byname:\ nisplus;[name=$key,status=local],domains.org_dir @end example There are obvious processing trade-offs among the various matching modes. Using an asterisk is faster than a regular expression, and listing a few names explicitly probably is too. The use of a file or database lookup is expensive, but may be the only option if hundreds of names are required. Because the patterns are tested in order, it makes sense to put the most commonly matched patterns earlier. @node Host lists, Mixing host names and addresses in host lists, Domain lists, 7[[[]]] The Exim configuration file @section 7[[[]]]13 Host lists @cindex host: list format @cindex format: host list @cindex list: host list Host lists are constructed as described in section 7.11. They contain patterns which are matched against host names or IP addresses. Host lists are used to control what remote hosts are allowed to do (for example, use the local host as a relay). Their patterns define a set of hosts that the list matches. @cindex negation: in host lists Items in the list may be positive or negative. Negation is indicated by preceding an item with an exclamation mark. A plain absolute file name (beginning with a slash) can be used to include items from a file. Negation and included files operate exactly as for domain lists -- see section 7.12 for examples. The following types of pattern may appear in a host list: @itemize @bullet @item If the entire item is `*' it matches any host. @item If the item is in the form of an IP address, it is matched against the IP address of the subject host. The presence of a colon is taken as an indication that it is an IPv6 address (when IPv6 support is compiled into Exim); such colons have to be doubled when colon is the item separator in the list (the default). @item If the item is in the form of an IP address followed by a slash and a mask length (for example 10.11.0.0/16) then it is matched against the IP address of the subject host under the given mask, which specifies the number of address bits that must match, starting from the most significant end. Thus an entire network of hosts can be included (or excluded) by a single item. IPv4 addresses are given in the normal `dotted-quad' notation. IPv6 addresses are given in colon-separated format, but the colons have to be doubled so as not to be taken as item separators. This example shows both kinds of address: @example receiver_unqualified_hosts = 172.16.0.0/12: \ 5f03::1200::836f::::/48 @end example The doubling of list separator characters applies only when such addresses appear inline in a host list. It is not required when indirecting via a file. For example, @example receiver_unqualified_hosts = /opt/exim/unqualnets @end example could make use of a file containing @example 172.16.0.0/12 5f03:1200:836f::/48 @end example to have exactly the same effect as the previous example. When listing small numbers of IPv6 addresses inline, is is usually more convenient to use the facility for changing separator characters. This list contains the same two addresses: @example receiver_unqualified_hosts = <; 172.16.0.0/12; \ 5f03:1200:836f::/48 @end example If an IPv4 host calls an IPv6 host, the incoming address actually appears in the IPv6 host as `::ffff:<@dfn{v4address}>'. When such an address is tested against a host list, it is converted into a traditional IPv4 address first. @item @cindex IP address: masking @cindex mask: IP address If the item is of the form @example net<@dfn{number}>-<@dfn{search-type}>;<@dfn{search-data}> @end example for example: @example net24-dbm;/networks.db @end example then the IP address of the subject host is masked using <@dfn{number}> as the mask length; a textual string is then constructed from the masked value, followed by the mask, and this is then used as the key for the lookup. For example, if the host's IP address is 192.168.34.6 then the key that is looked up for the above example is `192.168.34.0/24'. IPv6 addresses are converted to a text value using lower case letters and full stops (periods) as separators instead of the more usual colon, because colon is the key terminator in @dfn{lsearch} files. Full, unabbreviated IPv6 addresses are always used. @item If the item is of the form @example net-<@dfn{search-type}>;<@dfn{search-data}> @end example then the text form of the IP address of the subject host is used unmasked as the lookup key. This is not the same as specifying @dfn{net32} for an IPv4 address or @dfn{net128} for an IPv6 address, because the mask value is not included in the key. However, IPv6 addresses are still converted to an unabbreviated form, using lower case letters and full stops as separators. @item If the entire item is `@@' the primary host name is used as the match item, and the following applies: @item If the item is a plain domain name, Exim calls @dfn{gethostbyname()} to find its IP address(es). This typically causes a forward DNS lookup of the name. The result is compared with the IP address of the subject host. @end itemize The remaining items are wildcarded patterns for matching against the host name. @cindex host: lookup failures @cindex unknown host name If the host name is not already known, Exim calls @dfn{gethostbyaddr()} to obtain it from the IP address. This typically causes a reverse DNS lookup to occur. If the lookup fails, Exim takes a hard line by default and access is not permitted. If the list is an `accept' list, Exim behaves as if the current host is not in the set defined by the list, whereas if it is a `reject' list, it behaves as if it is. @cindex +allow_unknown To change this behaviour, the special item `+allow_unknown' may appear in the list (at top level -- it is not recognized in an indirected file). If any subsequent items require a host name, and the reverse DNS lookup fails, Exim permits the access, that is, its behaviour is the opposite to the default. For example, @example host_reject = +allow_unknown:*.enemy.ex @end example rejects connections from any host whose name matches @file{*.enemy.ex}, but only if it can find a host name from the incoming IP address. @cindex +warn_unknown If `+warn_unknown' is used instead of `+allow_unknown', the effect is the same, except that Exim writes an entry to its log when it accepts a host whose name it cannot look up. @cindex host: alias @cindex alias for host As a result of aliasing, hosts may have more than one name. When processing any of the following items, all the host's names are checked. @itemize @bullet @item If the item starts with `*' then the remainder of the item must match the end of the host name. For example, @file{*.b.c} matches all hosts whose names end in @file{.b.c}. This special simple form is provided because this is a very common requirement. Other kinds of wildcarding require the use of a regular expression. @item If the item starts with `^' then it is taken to be a regular expression which is matched against the host name. For example, @example ^(a|b)\.c\.d$ @end example matches either of the two hosts @dfn{a.c.d} or @dfn{b.c.d}. If the option string in which this occurs is given in quotes, the backslash characters must be doubled, because they are significant in quoted strings. The following two settings are exactly equivalent: @example host_reject = ^(a|b)\.c\.d$ host_reject = "^(a|b)\\.c\\.d$" @end example @item If the item is of the form @example <@dfn{search-type}>;<@dfn{filename or query}> @end example for example @example dbm;/host/accept/list @end example then the host name is looked up using the search type and file name or query (as appropriate). If the lookup succeeds, the host matches the item. The actual data that is looked up is not used. [(b)]Warning[(/b)]: when using this kind of lookup, you must have host @dfn{names} as keys in the file, not IP addresses. If you want to do lookups based on IP addresses, you must precede the search type with `net-' (see above). There is, however, no reason why you could not use two items in a list, one doing an address lookup and one doing a name lookup, both using the same file. @end itemize @node Mixing host names and addresses in host lists, Use of RFC 1413 identification in host lists, Host lists, 7[[[]]] The Exim configuration file @section 7[[[]]]14 Mixing host names and addresses in host lists If you have both names and IP addresses in the same host list, you should normally put the IP addresses first. For example: @example host_accept_relay = 10.9.8.7 : *.friends.domain @end example The reason for this lies in the left-to-right way that Exim processes lists. It can test IP addresses without doing any DNS lookups, but when it reaches an item that requires a DNS lookup, it normally fails if the DNS lookup fails, because it cannot find a host name to compare with the pattern. (There is the `+allow_unknown' facility -- described above -- for changing this, but it is not recommended.) If the above list were in the other order, Exim would reject relaying from any host whose name could not be found, even if it were 10.9.8.7. @node Use of RFC 1413 identification in host lists, Address lists, Mixing host names and addresses in host lists, 7[[[]]] The Exim configuration file @section 7[[[]]]15 Use of RFC 1413 identification in host lists @cindex RFC 1413 @cindex ident Any item in a host list (other than a plain file name or `+allow_unknown') can optionally be preceded by @example <@dfn{ident}>@@ or !<@dfn{ident}>@@ @end example where <@dfn{ident}> is an RFC 1413 identification string. For example, @example host_reject = !exim@@my.mail.gate:192.168.111.111:!root@@public.host @end example If an <@dfn{ident}> string is present, it must match the RFC 1413 identification sent by the remote host, unless it is preceded by an exclamation mark, in which case it must @dfn{not} match. The remainder of the item, following the @@, may be either positive or negative. @node Address lists, Case of letters in address lists, Use of RFC 1413 identification in host lists, 7[[[]]] The Exim configuration file @section 7[[[]]]16 Address lists @cindex address list format @cindex format: address list @cindex list: address list @cindex negation: in address lists Address lists are constructed as described in section 7.11. They contain patterns which are matched against mail addresses. As in the case of domain lists, the list is searched from left to right, any item may be preceded by an exclamation mark to negate it, and a plain file name may appear as an entire item, causing each line of the file to be read and treated as a separate pattern. Because local parts may legitimately contain # characters, a comment in the file is recognized only if # is followed by white space or the end of the line. The following kinds of pattern may appear inline or as lines in an included file: @itemize @bullet @item If a pattern starts with ^ then a regular expression match is done against the complete address, using the entire pattern as the regular expression. @item Otherwise, if there is no @@ in the pattern, it is first matched against the domain part of the subject address, the local part being ignored. This match is done exactly as for an entry in a domain list, so, for example, the item may begin with * or it may be a (partial) lookup (see section 7.12). If there is no match, and the pattern consists of a single lookup, the entire subject address is looked up in the file, with partial matching disabled. This means that an item such as @example sender_reject_recipients = partial-dbm;/black/list @end example can reference a single file whose keys are a mixture of complete domains, partial domains, and individual mail addresses. Note that this is not an `include' facility when the lookup type is @dfn{lsearch}. The keys in the file are not interpreted specially, as they would be if they appeared as individual items in the address list, or lines in a file given as a plain file name without a search type. You might think of using a lookup type ending in *@@ (as described in section 6.6) to match entries in a file of the form @example *@@penguin.book @end example However, this does not currently work, because the presence of an @@ in the pattern causes Exim to think the item is one of the forms described below. In some future release this may be changed. Meanwhile, the effect you want (matching any local part at a particular domain) is achieved by simply listing the domain name in the file. @item If the pattern starts with `@@@@' (for example, `@@@@lsearch;/some/file'), the address that is being checked is split into a local part and a domain. The domain is looked up in the file. If it is not found, there is no match. If it is found, the data that is looked up from the file is treated as a colon-separated list of local part patterns, each of which is matched against the subject local part in turn. The lookup may be a partial one, and/or one involving a search for a default keyed by `*'. The local part patterns that are looked up can be regular expressions or begin with `*', or even be further lookups. They may also be independently negated. For example, with @example sender_reject_recipients = @@@@dbm;/etc/reject-by-domain @end example the data from which DBM file is built could contain lines like @example baddomain.com: !postmaster : * @end example @cindex local part: starting with ! If a local part that actually begins with an exclamation mark is required, it has to be specified using a regular expression. In @dfn{lsearch} files, an entry may be split over several lines by indenting the second and subsequent lines, but the separating colon must still be included at line breaks. White space surrounding the colons is ignored. For example: @example aol.com: spammer1 : spammer2 : ^[0-9]+$ : spammer3 : spammer4 @end example As in all colon-separated lists in Exim, a colon can be included in an item by doubling. If the last item in the list starts with a right angle-bracket, the remainder of the item is taken as a new key to look up in order to obtain a continuation list of local parts. The new key can be any sequence of characters. Thus one might have entries like @example aol.com: spammer1 : spammer 2 : >* xyz.com: spammer3 : >* *: ^\d@{8@}$ @end example in a file that was searched with @dfn{@@@@dbm*}, to specify a match for 8-digit local parts for all domains, in addition to the specific local parts listed for each domain. Of course, using this feature costs another lookup each time a chain is followed, but the effort needed to maintain the data is reduced. @cindex loop: in lookups It is possible to construct loops using this facility, and in order to catch them, the chains may be no more than fifty items long. @item If none of the above cases apply, the local part of the subject address is compared with the local part of the pattern, which may start with an asterisk. If the local parts match, the domains are compared in exactly the same way as entries in a domain list, except that a regular expression is not permitted for a domain only. However, file lookups are permitted. For example: @example sender_reject = *@@*.spamming.site:\ bozo@@partial-lsearch;/list/of/dodgy/sites @end example The domain may be given as a single @@ character, as in a domain list, standing for the local host name, leading to items of the form `user@@@@'. @cindex local part: starting with ! If a local part that actually begins with an exclamation mark is required, it has to be specified using a regular expression, as otherwise the exclamation mark is treated as a sign of negation. @end itemize @node Case of letters in address lists, , Address lists, 7[[[]]] The Exim configuration file @section 7[[[]]]17 Case of letters in address lists @cindex case of local parts @cindex address list case forcing @cindex case forcing in address lists Domains in email addresses are always handled caselessly, but for local parts case may be significant on some systems (see @dfn{locally_caseless} for how Exim deals with this when processing local addresses). However, RFC 2505 (@dfn{Anti-Spam Recommendations for SMTP MTAs}) suggests that matching of addresses to blocking lists should be done in a case-independent manner. Since most address lists in Exim are used for this kind of control, Exim attempts to do this by default. The domain portion of an address is always lowercased before matching it to an address list. The local part is lowercased by default, and any string comparisons that take place are done caselessly. This means that the data in the address list itself, in files included as plain file names, and in any file that is looked up using the `@@@@' mechanism, can be in any case. However, the keys in files that are looked up by a search type other than @dfn{lsearch} (which works caselessly) must be in lower case, because these lookups are not case-independent. @cindex +caseful To allow for the possibility of caseful address list matching, if an item in the list is the string `+caseful' then the original case of the local part is restored for any comparisons that follow, and string comparisons are no longer case-independent. [(font color=green)] This does not affect the domain, which remains in lower case. However, although independent matches on the domain alone are still performed caselessly, regular expressions that match against an entire address are by default caseful after `+caseful' has been seen. [(/font)] @node 8[[[]]] Regular expressions, String expansions, 7[[[]]] The Exim configuration file, Top @chapter 8[[[]]] Regular expressions @cindex regular expressions: library Exim uses the PCRE regular expression library; this provides regular expression matching that is compatible with Perl 5. The syntax and semantics of these regular expressions is discussed in many Perl reference books, and also in Jeffrey Friedl's @dfn{Mastering Regular Expressions} (O'Reilly, ISBN 1-56592-257-3). The documentation for PCRE, in plain text and HTML, is included in the @dfn{doc} directory of the Exim distribution. This describes the features of the regular expressions that PCRE supports, so no further description is included here. The PCRE functions are called from Exim using the default option settings, except that the @sc{pcre_caseless} option is set when the matching is required to be independent of the case of letters. @sp 2 @menu * Testing regular expressions:: @end menu @node Testing regular expressions, , 8[[[]]] Regular expressions, 8[[[]]] Regular expressions @section 8[[[]]]1 Testing regular expressions @cindex testing: regular expressions A program called @dfn{pcretest} forms part of the PCRE distribution and is built with PCRE during the process of building Exim. It is primarily intended for testing PCRE itself, but it can also be used for experimenting with regular expressions. The binary can be found in the @dfn{util} sub-directory of the Exim build directory. There is documentation of various options in @dfn{doc/pcretest.txt}, but for simple testing, none are needed. This is the output of a sample run of @dfn{pcretest}: @example re> /^([^@@]+)@@.+\.(ac|edu)\.(?!kr)[a-z]@{2@}$/ data> x@@y.ac.uk 0: x@@y.ac.uk 1: x 2: ac data> x@@y.ac.kr No match data> x@@y.edu.com No match data> x@@y.edu.co 0: x@@y.edu.co 1: x 2: edu @end example After the `re>' prompt, a regular expression enclosed in delimiters is expected. If this compiles without error, `data>' prompts are given for strings against which the expression is matched. An empty data line causes a new regular expression to be read. If the match is successful, the captured substring values (that is, what would be in the variables $@dfn{0}, $@dfn{1}, $@dfn{2}, etc.) are shown. The above example tests for an email address whose domain ends with either `ac' or `edu' followed by a two-character top-level domain that is not `kr'. The local part is captured in $@dfn{1} and the `ac' or `edu' in $@dfn{2}. @node 9[[[]]] String expansions, Embedded Perl, 8[[[]]] Regular expressions, Top @chapter 9[[[]]] String expansions @cindex string: expansions @cindex expansion of strings: A number of configuration strings are expanded before use. Some of them are expanded every time they are used; others are expanded only once. Expanded strings are copied verbatim from left to right except when a dollar or backslash character is encountered. A dollar specifies the start of a portion of the string which is interpreted and replaced as described below. An uninterpreted dollar can be included in the string by putting a backslash in front of it -- if the string appears in quotes in the configuration file, two backslashes are required because the quotes themselves cause interpretation of backslashes when the string is read in. A backslash can be used to prevent any special character being treated specially in an expansion, including itself. A backslash followed by one of the letters `n', `r', or `t' is recognized as an escape sequence for the character newline, carriage return, or tab, respectively. A backslash followed by up to three octal digits is recognized as an octal encoding for a single character, while a backslash followed by `x' and up to two hexadecimal digits is a hexadecimal encoding. A backslash followed by any other character causes that character to be added to the output string uninterpreted. These escape sequences are also recognized in quoted strings as they are read in; their interpretation in expansions as well is useful for unquoted strings and other cases such as looked-up strings that are then expanded. @sp 2 @menu * Testing string expansions:: * Expansion items:: * Expansion operators:: * Expansion conditions:: * Expansion variables:: @end menu @node Testing string expansions, Expansion items, 9[[[]]] String expansions, 9[[[]]] String expansions @section 9[[[]]]1 Testing string expansions @cindex expansion of strings: testing @cindex testing: string expansion Many expansions can be tested by calling Exim with the -@dfn{be} option. This takes the command arguments, or lines from the standard input if there are no arguments, runs them through the string expansion code, and writes the results to the standard output. Variables based on configuration values are set up, but since no message is being processed, variables such as $@dfn{local_part} have no value. Nevertheless the -@dfn{be} option can be useful for checking out file and database lookups, and the use of expansion operators such as @dfn{substr} and @dfn{hash}. Exim gives up its root privilege when it is called with the -@dfn{be} option, and instead runs under the uid and gid it was called with, to prevent users from using -@dfn{be} for reading files to which they normally do not have access. @node Expansion items, Expansion operators, Testing string expansions, 9[[[]]] String expansions @section 9[[[]]]2 Expansion items The following items are recognized in expanded strings. White space may be used between sub-items that are keywords or substrings enclosed in braces inside an outer set of braces, to improve readability. Within braces, however, white space is significant. @example [(font color=blue)]______________________________________________________________[(/font)] [(b)]$<@dfn{variable name}> or $@{<@dfn{variable name}>@}[(/b)] @end example @cindex expansion of strings: variables Substitute the contents of the named variable, for example @example $local_part $@{domain@} @end example The second form can be used to separate the name from subsequent alphanumeric characters. This form (using curly brackets) is available only for variables; it does @dfn{not} apply to message headers. The names of the variables are given in section 9.5 below. If the name of a non-existent variable is given, the expansion fails. @example [(font color=blue)]______________________________________________________________[(/font)] [(b)]$header_<@dfn{header name}>: or $h_<@dfn{header name}>:[(/b)] @end example @cindex expansion of strings: headers Substitute the contents of the named message header line, for example @example $header_reply-to: @end example The header names follow the syntax of RFC 822, which states that they may contain any printing characters except space and colon. Consequently, curly brackets @dfn{do not} terminate header names, and should not be used to enclose them as if they were variables. Attempting to do so causes a syntax error. Upper-case and lower-case letters are synonymous in header names. If the following character is white space, the terminating colon may be omitted, but this is not recommended, because you may then forget it when it is needed. When white space terminates the header name, it is included in the expanded string. If the message does not contain the given header, the expansion item is replaced by an empty string. (See the @dfn{def} condition in section 9.4 for a means of testing for the existence of a header.) If there is more than one header with the same name, they are all concatenated to form the substitution string, with a newline character between each of them. However, if the length of this string exceeds 64K, any further headers of the same name are ignored. @example [(font color=blue)]______________________________________________________________[(/font)] [(b)]$@{<@dfn{op}>:<@dfn{string}>@}[(/b)] @end example @cindex expansion of strings: operators The string is first itself expanded, and then the operation specified by <@dfn{op}> is applied to it. For example, @example $@{lc:$local_part@} @end example A list of operators is given in section 9.3 below. The string starts with the first character after the colon, which may be leading white space. @example [(font color=blue)]______________________________________________________________[(/font)] [(b)]$@{extract@{<@dfn{key}>@}@{<@dfn{string1}>@}@{<@dfn{string2}>@}@{<@dfn{string3}>@}@}[(/b)] @end example The key and <@dfn{string1}> are first expanded separately. The key must not consist entirely of digits. For the string, the result must be of the form: @example <@dfn{key1}> = <@dfn{value1}> <@dfn{key2}> = <@dfn{value2}> ... @end example where the equals signs and spaces are optional. If any of the values contain white space, they must be enclosed in double quotes, and any values that are enclosed in double quotes are subject to escape processing as described in section 7.8. The expanded <@dfn{string1}> is searched for the value that corresponds to the key. If it is found, <@dfn{string2}> is expanded, and replaces the whole item; otherwise <@dfn{string3}> is used. During the expansion of <@dfn{string2}> the variable $@dfn{value} contains the value that has been extracted. Afterwards, it is restored to any previous value it might have had. If @{<@dfn{string3}>@} is omitted, the item is replaced by an empty string if the key is not found. If @{<@dfn{string2}>@} is also omitted, the value that was looked up is used. Thus, for example, these two expansions are identical, and yield `2001': @example $@{extract@{gid@}@{uid=1984 gid=2001@}@} $@{extract@{gid@}@{uid=1984 gid=2001@}@{$value@}@} @end example Instead of @{<@dfn{string3}>@} the word `fail' (not in curly brackets) can appear, for example: @example $@{extract@{Z@}@{A=... B=...@}@{$value@} fail @} @end example @{<@dfn{string2}>@} must be present for `fail' to be recognized. When this syntax is used, if the extraction fails, the entire string expansion fails in a way that can be detected by the code in Exim which requested the expansion. This is called `forced expansion failure', and its consequences depend on the circumstances. In some cases it is no different from any other expansion failure, but in others a different action may be taken. See for example the @dfn{new_address} option of the @dfn{smartuser} director. @example [(font color=blue)]______________________________________________________________[(/font)] [(b)]$@{extract@{<@dfn{number}>@}@{<@dfn{separators}>@}@{<@dfn{string1}>@}@{<@dfn{string2}>@}@{<@dfn{string3}>@}@}[(/b)] @end example The <@dfn{number}> argument must consist entirely of decimal digits. This is what distinguishes this form of @dfn{extract} from the previous kind. It behaves in the same way, except that, instead of extracting a named field, it extracts from <@dfn{string1}> the field whose number is given as the first argument. The first field is numbered one. If the number is greater than the number of fields in the string, [(font color=green)] the result is the expansion of <@dfn{string3}>, or the empty string if <@dfn{string3}> is not provided. [(/font)] If the number is zero, the entire string is returned. The fields in the string are separated by any one of the characters in the separator string. For example: @example $@{extract@{2@}@{:@}@{x:42:99:& Mailer::/bin/bash@}@} @end example yields `42'. Two successive separators mean that the field between them is empty (for example, the fifth field above). @example [(font color=blue)]______________________________________________________________[(/font)] [(b)]$@{if <@dfn{condition}> @{<@dfn{string1}>@}@{<@dfn{string2}>@}@}[(/b)] @end example @cindex expansion of strings: conditions If <@dfn{condition}> is true, <@dfn{string1}> is expanded and replaces the whole item; otherwise <@dfn{string2}> is used. For example, @example $@{if eq @{$local_part@}@{postmaster@} @{yes@}@{no@} @} @end example The second string need not be present; if it is not and the condition is not true, the item is replaced with nothing. Alternatively, the word `fail' may be present instead of the second string (without any curly brackets). In this case, the expansion is forced to fail if the condition is not true. The available conditions are described in section 9.4 below. @example [(font color=blue)]______________________________________________________________[(/font)] [(b)]$@{lookup@{<@dfn{key}>@} <@dfn{search type}> @{<@dfn{file}>@} @{<@dfn{string1}>@} @{<@dfn{string2}>@}@}[(/b)] @end example @example [(b)]$@{lookup <@dfn{search type}> @{<@dfn{query}>@} @{<@dfn{string1}>@} @{<@dfn{string2}>@}@}[(/b)] @end example @cindex expansion of strings: query lookup @cindex expansion of strings: file lookup @cindex file: lookup @cindex lookup, in expanded string These items specify data lookups in files and databases, as discussed in chapter 6. The first form is used for single-key lookups, and the second is used for query-style lookups. The <@dfn{key}>, <@dfn{file}>, and <@dfn{query}> strings are expanded before use. If there is any white space in a lookup item which is part of a filter command, a rewrite rule, a routing rule for the @dfn{domainlist} router, or any other place where white space is significant, the lookup item must be enclosed in double quotes. The use of data lookups in users' filter files may be locked out by the system administrator. @cindex $value If the lookup succeeds, <@dfn{string1}> is expanded and replaces the entire item. During its expansion, the variable $@dfn{value} contains the data returned by the lookup. Afterwards it reverts to the value it had previously (at the outer level it is empty). If the lookup fails, <@dfn{string2}> is expanded and replaces the entire item. If @{<@dfn{string2}>@} is omitted, the replacement is null on failure. Alternatively, <@dfn{string2}> can itself be a nested lookup, thus providing a mechanism for looking up a default value when the original lookup fails. If a nested lookup is used as part of <@dfn{string1}>, $@dfn{value} contains the data for the outer lookup while the parameters of the second lookup are expanded, and also while <@dfn{string2}> of the second lookup is expanded, should the second lookup fail. Instead of @{<@dfn{string2}>@} the word `fail' can appear, and in this case, if the lookup fails, the entire expansion is forced to fail. If both @{<@dfn{string1}>@} and @{<@dfn{string2}>@} are omitted, the result is the looked up value in the case of a successful lookup, and nothing in the case of failure. For single-key lookups, the string `partial-' is permitted to precede the search type in order to do partial matching, and * or *@@ may follow a search type to request default lookups if the key does not match (see sections 6.6 and 6.7). If a partial search is used, the variables $@dfn{1} and $@dfn{2} contain the wild and non-wild parts of the key during the expansion of the replacement text. They return to their previous values at the end of the lookup item. This example looks up the postmaster alias in the conventional alias file. @example $@{lookup @{postmaster@} lsearch @{/etc/aliases@} @{$value@}@} @end example This example uses NIS+ to look up the full name of the user corresponding to the local part of an address, forcing the expansion to fail if it is not found. @example "$@{lookup nisplus @{[name=$local_part],passwd.org_dir:gcos@} \ @{$value@}fail@}" @end example @example [(font color=blue)]______________________________________________________________[(/font)] [(b)]$@{lookup@{<@dfn{key:subkey}>@} <@dfn{search type}> @{<@dfn{file}>@} @{<@dfn{string1}>@} @{<@dfn{string2}>@}@}[(/b)] @end example This is just a syntactic variation for a single-key lookup, surrounded by an @dfn{extract} item. It searches for <@dfn{key}> in the file as described above for single-key lookups; if it succeeds, it extracts from the data a subfield which is identified by the <@dfn{subkey}>. For example, if a line in a linearly searched file contains @example alice: uid=1984 gid=2001 @end example then expanding the string @example $@{lookup@{alice:uid@}lsearch@{<@dfn{file name}>@}@{$value@}@} @end example yields the string `1984'. If the subkey is not found in the looked up data, then <@dfn{string2}>, if present, is expanded and replaces the entire item. Otherwise the replacement is null. The example above could equally well be written like this: @example $@{extract@{uid@}@{$@{lookup@{alice@}lsearch@{<@dfn{file name}>@}@}@}@} @end example and this is recommended, because this approach can also be used with query-style lookups. @example [(font color=blue)]______________________________________________________________[(/font)] [(b)]$@{perl@{<@dfn{subroutine}>@}@{<@dfn{arg}>@}@{<@dfn{arg}>@}...@}[(/b)] @end example @cindex Perl: use in expanded string This item is available only if Exim has been built to include an embedded Perl interpreter. The subroutine name and the arguments are first separately expanded, and then the Perl subroutine is called with those arguments. No arguments need be given; the maximum number permitted is eight. The return value of the subroutine is inserted into the expanded string, unless the return value is @dfn{undef}. In that case, the expansion fails in the same way as an explicit `fail' on a lookup item. If the subroutine exits by calling Perl's @dfn{die} function, the expansion fails with the error message that was passed to @dfn{die}. More details of the embedded Perl facility are given in chapter 10. @example [(font color=blue)]______________________________________________________________[(/font)] [(b)]$@{sg@{<@dfn{subject}>@}@{<@dfn{regex}>@}@{<@dfn{replacement}>@}@}[(/b)] @end example @cindex expansion of strings: substitution This item works like Perl's substitution operator (s) with the global (/g) option; hence its name. It takes three arguments: the subject string, a regular expression, and a substitution string. For example @example $@{sg@{abcdefabcdef@}@{abc@}@{xyz@}@} @end example yields `xyzdefxyzdef'. Because all three arguments are expanded before use, if any $ or \ characters are required in the regular expression or in the substitution string, they have to be escaped. For example @example $@{sg@{abcdef@}@{^(...)(...)\$@}@{\$2\$1@}@} @end example yields `defabc', and @example $@{sg@{1=A 4=D 3=C@}@{(\\d+)=@}@{K\$1=@}@} @end example yields `K1=A K4=D K3=C'. @example [(font color=blue)]______________________________________________________________[(/font)] [(b)]$@{tr@{<@dfn{subject}>@}@{<@dfn{characters}>@}@{<@dfn{replacements}>@}@}[(/b)] @end example @cindex expansion of strings: character translation This item does single-character translation on its subject string. The second argument is a list of characters to be translated in the subject string. Each matching character is replaced by the corresponding character from the replacement list. For example @example $@{tr@{abcdea@}@{ac@}@{13@}@} @end example yields `1b3de1'. If there are duplicates in the second character string, the last occurrence is used. If the third string is shorter than the second, its last character is replicated. However, if it is empty, no translation takes place. @node Expansion operators, Expansion conditions, Expansion items, 9[[[]]] String expansions @section 9[[[]]]3 Expansion operators @cindex expansion of strings: operators The following operations can be performed on portions of an expanded string. The substring is first expanded before the operation is applied to it. @example [(font color=blue)]______________________________________________________________[(/font)] [(b)]$@{domain:<@dfn{string}>@}[(/b)] @end example @cindex domain: extraction The string is interpreted as an RFC 822 address and the domain is extracted from it. If the string does not parse successfully, the result is empty. @example [(font color=blue)]______________________________________________________________[(/font)] [(b)]$@{escape:<@dfn{string}>@}[(/b)] @end example If the string contains any non-printing characters, they are converted to escape sequences starting with a backslash. Whether characters with the most significant bit set (so-called `8-bit characters') count as printing or not is controlled by the @dfn{print_topbitchars} option. @example [(font color=blue)]______________________________________________________________[(/font)] [(b)]$@{expand:<@dfn{string}>@}[(/b)] @end example The @dfn{expand} operator causes a string to be expanded for a second time. For example, @example $@{expand:$@{lookup@{$domain@}dbm@{/some/file@}@{$value@}@}@} @end example first looks up a string in a file while expanding the operand for @dfn{expand}, and then re-expands what it has found. @example [(font color=blue)]______________________________________________________________[(/font)] [(b)]$@{hash_<@dfn{n}>_<@dfn{m}>:<@dfn{string}>@}[(/b)] @end example @cindex hash function: textual The two items <@dfn{n}> and <@dfn{m}> are numbers. If <@dfn{n}> is greater than or equal to the length of the string, the operator returns the string. Otherwise it computes a new string of length <@dfn{n}> by applying a hashing function to the string. The new string consists of characters taken from the first <@dfn{m}> characters of the string @example abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQWRSTUVWXYZ0123456789 @end example and if <@dfn{m}> is not present the value 26 is used, so that only lower case letters appear. These examples: @example $@{hash_3:monty@} $@{hash_5:monty@} $@{hash_4_62:monty python@} @end example yield @example jmg monty fbWx @end example respectively. The abbreviation @dfn{h} can be used instead of @dfn{hash}. @example [(font color=blue)]______________________________________________________________[(/font)] [(b)]$@{nhash_<@dfn{n}>:<@dfn{string}>@}[(/b)] @end example @cindex hash function: numeric @cindex string: hashing The string is processed by a hash function which returns a numeric value in the range 0--<@dfn{n}>-1. @example [(font color=blue)]______________________________________________________________[(/font)] [(b)]$@{nhash_<@dfn{n}>_<@dfn{m}>:<@dfn{string}>@}[(/b)] @end example The string is processed by a div/mod hash function which returns two numbers, separated by a slash, in the ranges 0--<@dfn{n}>-1 and 0--<@dfn{m}>-1, respectively. For example, @example $@{nhash_8_64:supercalifragilisticexpialidocious@} @end example returns the string `6/33'. [(font color=green)] @cindex MD5 hash @example [(font color=blue)]______________________________________________________________[(/font)] [(b)]$@{md5:<@dfn{string}>@}[(/b)] @end example The @dfn{md5} operator computes the MD5 hash value of the string, and returns it as a 32-digit hexadecimal number. [(/font)] @cindex case forcing in strings @cindex string: case forcing @cindex lower casing @example [(font color=blue)]______________________________________________________________[(/font)] [(b)]$@{lc:<@dfn{string}>@}[(/b)] @end example This forces the letters in the string into lower-case, for example: @example $@{lc:$local_part@} @end example @cindex upper casing @example [(font color=blue)]______________________________________________________________[(/font)] [(b)]$@{uc:<@dfn{string}>@}[(/b)] @end example This forces the letters in the string into upper-case. @example [(b)]$@{length_<@dfn{number}>:<@dfn{string}>@}[(/b)] @end example The @dfn{length} operator can be used to extract the initial portion of a string. It is followed by an underscore and the number of characters required. For example @example $@{length_50:$message_body@} @end example The result of this operator is either the first <@dfn{number}> characters or the whole string, whichever is the shorter. The abbreviation @dfn{l} can be used instead of @dfn{length}. @example [(font color=blue)]______________________________________________________________[(/font)] [(b)]$@{local_part:<@dfn{string}>@}[(/b)] @end example The string is interpreted as an RFC 822 address and the local part is extracted from it. If the string does not parse successfully, the result is empty. @example [(b)]$@{mask:<@dfn{IP address}>/<@dfn{bit count}>@}[(/b)] @end example @cindex mask: IP address @cindex IP address: masking If the form of the string to be operated on is not an IP address followed by a slash and an integer, the expansion fails. Otherwise, this operator converts the IP address to binary, masks off the least significant bits according to the bit count, and converts the result back to text, with mask appended. For example, @example $@{mask:10.111.131.206/28@} @end example returns the string `10.111.131.192/28'. Since this operation is expected to be mostly used for looking up masked addresses in files, the result for an IPv6 address uses fullstops (periods) to separate components instead of colons, because colon terminates a key string in lsearch files. So, for example, @example $@{mask:5f03:1200:836f:0a00:000a:0800:200a:c031/99@} @end example returns the string @example 5f03.1200.836f.0a00.000a.0800.2000.0000/99 @end example Letters in IPv6 addresses are always output in lower case. @example [(font color=blue)]______________________________________________________________[(/font)] [(b)]$@{quote:<@dfn{string}>@}[(/b)] @end example @cindex quoting: in string expansions The @dfn{quote} operator puts its argument into double quotes if it contains anything other than letters, digits, underscores, full stops (periods), and hyphens. Any occurrences of double quotes and backslashes are escaped with a backslash. For example, @example $@{quote:ab"*"cd@} @end example becomes @example "ab\"*\"cd" @end example The place where this is useful is when the argument is a substitution from a variable or a message header. @example [(font color=blue)]______________________________________________________________[(/font)] [(b)]$@{quote_<@dfn{lookup-type}>:<@dfn{string}>@}[(/b)] @end example @cindex quoting: lookup-specific This operator applies lookup-specific quoting rules to the string. Each query-style lookup type has its own quoting rules which are described with the lookups in chapter 6. For example, @example $@{quote_ldap:two + two@} @end example returns `two%20%5C+%20two'. For single-key lookup types, no quoting is necessary and this operator yields an unchanged string. @example [(font color=blue)]______________________________________________________________[(/font)] [(b)]$@{rxquote:<@dfn{string}>@}[(/b)] @end example @cindex quoting: regular expressions @cindex regular expressions: quoting The @dfn{rxquote} operator inserts a backslash before any non-alphanumeric characters in its argument. This is useful when substituting the values of variables or headers inside regular expressions. @example [(font color=blue)]______________________________________________________________[(/font)] [(b)]$@{substr_<@dfn{start}>_<@dfn{length}>:<@dfn{string}>@}[(/b)] @end example @cindex substr @cindex substring extraction The @dfn{substr} operator can be used to extract more general substrings than @dfn{length}. It is followed by an underscore and the starting offset, then a second underscore and the length required. For example @example $@{substr_3_2:$local_part@} @end example If the starting offset is greater than the string length the result is the null string; if the length plus starting offset is greater than the string length, the result is the right-hand part of the string, starting from the given offset. The first character in the string has offset zero. The abbreviation @dfn{s} can be used instead of @dfn{substr}. The @dfn{substr} expansion operator can take negative offset values to count from the righthand end of its operand. The last character is offset -1, the second-last is offset -2, and so on. Thus, for example, @example $@{substr_-5_2:1234567@} @end example yields `34'. If the absolute value of a negative offset is greater than the length of the string, the substring starts at the beginning of the string, and the length is reduced by the amount of overshoot. Thus, for example, @example $@{substr_-5_2:12@} @end example yields an empty string, but @example $@{substr_-3_2:12@} @end example yields `1'. If the second number is omitted from @dfn{substr}, the remainder of the string is taken if the offset was positive. If it was negative, all characters in the string preceding the offset point are taken. For example, an offset of -1 and no length yields all but the last character of the string. @node Expansion conditions, Expansion variables, Expansion operators, 9[[[]]] String expansions @section 9[[[]]]4 Expansion conditions @cindex expansion of strings: conditions The following conditions are available for testing by the @dfn{$@{if} construct while expanding strings: @example [(font color=blue)]______________________________________________________________[(/font)] [(b)]!<@dfn{condition}>[(/b)] @end example Preceding any condition with an exclamation mark negates the result of the condition. @example [(b)]<@dfn{symbolic operator}> @{<@dfn{string1}>@}@{<@dfn{string2}>@}[(/b)] @end example @cindex numeric comparison @cindex expansion of strings: numeric comparison There are a number of symbolic operators for doing numeric comparisons. They are: @example = equal == equal > greater >= greater or equal < less <= less or equal @end example For example, @example $@{if >@{$message_size@}@{10M@} ... @end example Note that the general negation operator provides for inequality testing. The two strings must take the form of optionally signed decimal integers, optionally followed by one of the letters `K' or `M' (in either upper or lower case), signifying multiplication by 1024 or 1024*1024, respectively. @example [(font color=blue)]______________________________________________________________[(/font)] [(b)]def:<@dfn{variable name}>[(/b)] @end example The @dfn{def} condition must be followed by the name of one of the expansion variables defined in section 5. The condition is true if the named expansion variable does not contain the empty string, for example @example $@{if def:sender_ident @{from $sender_ident@}@} @end example Note that the variable name is given without a leading @dfn{$} character. If the variable does not exist, the expansion fails. @example [(font color=blue)]______________________________________________________________[(/font)] [(b)]def:header_<@dfn{header name}>: or def:h_<@dfn{header name}>:[(/b)] @end example This condition is true if a message is being processed and the named header exists in the message. For example, @example $@{if def:header_reply-to:@{$h_reply-to:@}@{$h_from:@}@} @end example Note that no @dfn{$} appears before @dfn{header_} or @dfn{h_} in the condition, and that header names must be terminated by colons if white space does not follow. @example [(font color=blue)]______________________________________________________________[(/font)] [(b)]exists @{<@dfn{file name}>@}[(/b)] @end example The substring is first expanded and then interpreted as an absolute path. The condition is true if the named file (or directory) exists. The existence test is done by calling the @dfn{stat()} function. The use of the @dfn{exists} test in users' filter files may be locked out by the system administrator. @example [(b)]eq @{<@dfn{string1}>@}@{<@dfn{string2}>@}[(/b)] @end example @cindex string: comparison @cindex expansion of strings: string comparison The two substrings are first expanded. The condition is true if the two resulting strings are identical, including the case of letters. @example [(font color=blue)]______________________________________________________________[(/font)] [(b)]crytpeq @{<@dfn{string1}>@}@{<@dfn{string2}>@}[(/b)] @end example @cindex encrypted comparison This condition is included in the Exim binary if it is built to support any authentication mechanisms (see chapter 35). Otherwise, it is necessary to define @sc{support_crypteq} in @file{Local/Makefile} to get @dfn{crypteq} included in the binary. The @dfn{crypteq} condition has two arguments. The first is encrypted and compared against the second, which is already encrypted. The second string may be in the LDAP form for storing encrypted strings, which starts with the encryption type in curly brackets, followed by the data. For example: @cindex MD5 hash @example @{md5@}CY9rzUYh03PK3k6DJie09g== @end example If such a string appears directly in an expansion, the curly brackets have to be quoted, because they are part of the expansion syntax. For example: @example $@{if crypteq @{test@}@{\@{md5\@}CY9rzUYh03PK3k6DJie09g==@}@{yes@}@{no@}@} @end example Two encryption types are currently supported: @itemize @bullet @item @dfn{md5} first computes the MD5 digest of the string, and then expresses this as printable characters by means of base64 encoding. @item @dfn{crypt} calls the @dfn{crypt()} function as used for encrypting login passwords. @end itemize If the second string does not begin with `@{' it is assumed to be encrypted with @dfn{crypt()}, since such strings cannot begin with `@{'. Typically this will be a field from a password file. @example [(font color=blue)]______________________________________________________________[(/font)] [(b)]match @{<@dfn{string1}>@}@{<@dfn{string2}>@}[(/b)] @end example The two substrings are first expanded. The second is then treated as a regular expression and applied to the first. Because of the pre-expansion, if the regular expression contains dollar, or backslash characters, they must be escaped with backslashes. Care must also be taken if the regular expression contains braces (curly brackets). A closing brace must be escaped so that it is not taken as a premature termination of <@dfn{string2}>. It does no harm to escape opening braces, but this is not strictly necessary. For example, @example $@{if match @{$local_part@}@{^\\d\@{3\@}@} ... @end example If the whole expansion string is in double quotes, further escaping of backslashes is also required. The condition is true if the regular expression match succeeds. At the start of an @dfn{if} expansion the values of the numeric variable substitutions $@dfn{1} etc. are remembered. Obeying a @dfn{match} condition that succeeds causes them to be reset to the substrings of that condition and they will have these values during the expansion of the success string. At the end of the @dfn{if} expansion, the previous values are restored. After testing a combination of conditions using @dfn{or}, the subsequent values of the numeric variables are those of the condition that succeeded. @cindex PAM @example [(font color=blue)]______________________________________________________________[(/font)] [(b)]pam @{<@dfn{string1}>:<@dfn{string2}>:...@}[(/b)] @end example @dfn{Pluggable Authentication Modules} [(font color=green)] (http://www.kernel.org/pub/linux/libs/pam/) [(/font)] are a facility which is available in the latest releases of Solaris and in some GNU/Linux distributions. The Exim support, which is intended for use in conjunction with the SMTP @sc{auth} command, is available only if Exim is compiled with @example SUPPORT_PAM=yes @end example in @file{Local/Makefile}. You probably need to add -@dfn{lpam} to @sc{extralibs}, and in some releases of GNU/Linux -@dfn{ldl} is also needed. The argument string is first expanded, and the result must be a colon-separated list of strings. The PAM module is initialized with the service name `exim' and the user name taken from the first item in the colon-separated data string (i.e. <@dfn{string1}>). The remaining items in the data string are passed over in response to requests from the authentication function. In the simple case there will only be one request, for a password, so the data will consist of just two strings. There can be problems if any of the strings are permitted to contain colon characters. In the usual way, these have to be doubled to avoid being taken as separators. If the data is being inserted from a variable, the @dfn{sg} expansion item can be used to double any existing colons. For example, the configuration of a LOGIN authenticator might contain this setting: @example server_condition = $@{if pam@{$1:$@{sg@{$2@}@{:@}@{::@}@}@}@{yes@}@{no@}@} @end example @example [(font color=blue)]______________________________________________________________[(/font)] [(b)]first_delivery[(/b)] @end example @cindex delivery: first @cindex first delivery This condition, which has no data, is true during a message's first delivery attempt. It is false during any subsequent delivery attempts. @example [(font color=blue)]______________________________________________________________[(/font)] [(b)]queue_running[(/b)] @end example @cindex queue: running, detecting This condition, which has no data, is true during delivery attempts that are initiated by queue-runner processes, and false otherwise. @example [(font color=blue)]______________________________________________________________[(/font)] [(b)]or @{@{<@dfn{cond1}>@}@{<@dfn{cond2}>@}...@}[(/b)] @end example The sub-conditions are evaluated from left to right. The condition is true if any one of the sub-conditions is true. For example, @example $@{if or @{@{eq@{$local_part@}@{spqr@}@}@{eq@{$domain@}@{testing.com@}@}@}... @end example When a true sub-condition is found, the following ones are parsed but not evaluated. If there are several `match' sub-conditions the values of the numeric variables afterwards are taken from the first one that succeeds. @example [(font color=blue)]______________________________________________________________[(/font)] [(b)]and @{@{<@dfn{cond1}>@}@{<@dfn{cond2}>@}...@}[(/b)] @end example The sub-conditions are evaluated from left to right. The condition is true if all of the sub-conditions are true. If there are several `match' sub-conditions, the values of the numeric variables afterwards are taken from the last one. When a false sub-condition is found, the following ones are parsed but not evaluated. Note that @dfn{and} and @dfn{or} are complete conditions on their own, and precede their lists of sub-conditions. Each sub-condition must be enclosed in braces within the overall braces that contain the list. No repetition of @dfn{if} is used. @node Expansion variables, , Expansion conditions, 9[[[]]] String expansions @section 9[[[]]]5 Expansion variables @cindex expansion of strings: variables The variable substitutions that are available for use in expansion strings are: $@dfn{0}, $@dfn{1}, etc: When a @dfn{matches} expansion condition succeeds, these variables contain the captured substrings identified by the regular expression during subsequent processing of the success string of the containing @dfn{if} expansion item. They may also be set externally by some other matching process which precedes the expansion of the string. For example, the commands available in Exim filter files include an @dfn{if} command with its own regular expression matching condition. $@dfn{address_file}: When, as a result of aliasing or forwarding, a message is directed to a specific file, this variable holds the name of the file when the transport is running. For example, using the default configuration, if user @dfn{r2d2} has a @file{.forward} file containing @example /home/r2d2/savemail @end example then when the @dfn{address_file} transport is running, $@dfn{address_file} contains `/home/r2d2/savemail'. At other times, the variable is empty. $@dfn{address_pipe}: When, as a result of aliasing or forwarding, a message is directed to a pipe, this variable holds the pipe command when the transport is running. @cindex authentication: id $@dfn{authenticated_id}: When a server successfully authenticates a client it may be configured to preserve some of the authentication information in the variable $@dfn{authenticated_id} (see chapter 35). For example, a user/password authenticator configuration might preserve the user name for use in the directors or routers. @cindex sender: authenticated @cindex authentication: sender $@dfn{authenticated_sender}: When a client host has authenticated itself, Exim pays attention to the @sc{auth=} parameter on the SMTP @sc{mail} command, [(font color=green)] provided the setting of @dfn{server_mail_auth_condition} (see chapter 35) permits it. [(/font)] Otherwise, it accepts the syntax, but ignores the data. Unless the data is the string `<>', it is set as the authenticated sender of the message, and the value is available during delivery in the $@dfn{authenticated_sender} variable. @cindex message: body line count @cindex body of message: line count $@dfn{body_linecount}: When a message is being received or delivered, this variable contains the number of lines in the message's body. @cindex gid: caller $@dfn{caller_gid}: The group id under which the process that called Exim was running. This is not the same as the group id of the originator of a message (see $@dfn{originator_gid}). If Exim re-execs itself, this variable in the new incarnation normally contains the Exim gid. @cindex uid: caller $@dfn{caller_uid}: The user id under which the process that called Exim was running. This is not the same as the user id of the originator of a message (see $@dfn{originator_uid}). If Exim re-execs itself, this variable in the new incarnation normally contains the Exim uid. $@dfn{compile_date}: The date on which the Exim binary was compiled. $@dfn{compile_number}: The building process for Exim keeps a count of the number of times it has been compiled. This serves to distinguish different compilations of the same version of the program. $@dfn{domain}: When an address is being directed, routed, or delivered on its own, this variable contains the domain. In particular, it is set during user filtering, but not during system filtering, since a message may have many recipients and the system filter is called just once. For remote addresses, the domain that is being routed can change as routing proceeds, as a result of router actions (see, for example, the @dfn{domainlist} router). However, the value of $@dfn{domain} remains as the original domain. The current routing domain can often be accessed by other means. When a remote or local delivery is taking place, if all the addresses that are being handled simultaneously contain the same domain, it is placed in $@dfn{domain}. Otherwise this variable is empty. Transports should be restricted to handling only one domain at once if its value is required at transport time -- this is the default for local transports. For further details of the environment in which local transports are run, see chapter 13. @cindex delay_warning_condition At the end of a delivery, if all deferred addresses have the same domain, it is set in $@dfn{domain} during the expansion of @dfn{delay_warning_condition}. Because configured address rewriting happens at the time a message is received, $@dfn{domain} normally contains the value after rewriting. However, when a rewrite item is actually being processed (see chapter 34) $@dfn{domain} contains the domain portion of the address that is being rewritten; it can be used in the expansion of the replacement address, for example, to rewrite domains by file lookup. @cindex ETRN @cindex smtp_etrn_command When the @dfn{smtp_etrn_command} option is being expanded, $@dfn{domain} contains the complete argument of the @sc{etrn} command (see section 48.6). $@dfn{domain_data}: When a director or a router has a setting of the @dfn{domains} generic option, and that involves a lookup which succeeds, the data read by the lookup is available during the running of the director or router as $@dfn{domain_data}. In addition, if the driver directs or routes the address to a transport, the value is available in that transport. In all other situations, this variable expands to nothing. $@dfn{errmsg_recipient}: This is set to the recipient address of an error message while Exim is creating it. It is useful if a customized error message text file is in use (see chapter 39). $@dfn{home}: A home directory may be set during a local delivery, either by the transport or by the director that handled the address. When this is the case, $@dfn{home} contains its value and may be used in any expanded options for the transport. The @dfn{forwardfile} director also makes use of $@dfn{home}. Full details are given in chapter 24. When interpreting a user's filter file, Exim is normally configured so that $@dfn{home} contains the user's home directory. When running a filter test via the -@dfn{bf} option, $@dfn{home} is set to the value of the environment variable @sc{home}. $@dfn{host}: When the @dfn{smtp} transport is expanding its options for encryption using TLS, $@dfn{host} contains the name of the host to which it is connected. Likewise, when used in the client part of an authenticator configuration (see chapter 35), $@dfn{host} contains the name of the server to which the client is connected. @cindex transport: filter @cindex filter: transport filter When used in a transport filter (see chapter 14) $@dfn{host} refers to the host involved in the current connection. When a local transport is run as a result of routing a remote address, this variable is available to access the host name that the router defined. A router may set up many hosts; in this case $@dfn{host} refers to the first one. It is expected that this usage will be mainly via the domainlist router, setting up a single host for batched SMTP output, for example. $@dfn{host_address}: This variable is set to the remote host's IP address whenever $@dfn{host} is set for a remote connection. $@dfn{host_lookup_failed}: This variable contains `1' if the message came from a remote host and there was an attempt to look up the host's name from its IP address, but the attempt failed. Otherwise the value of the variable is `0'. $@dfn{interface_address}: For a message received over a TCP/IP connection, this variable contains the address of the IP interface that was used. See also the -@dfn{oMi} command line option. @cindex $key $@dfn{key}: When a domain, host, or address list is being searched, this variable contains the value of the key, so that it can be inserted into strings for query-style lookups. See section 6.4 for further details and an example. In other circumstances this variable is empty. $@dfn{local_part}: When an address is being directed, routed, or delivered on its own, this variable contains the local part. If a local part prefix or suffix has been recognized, it is not included in the value. When a number of addresses are being delivered in a batch by a local or remote transport, $@dfn{local_part} is not set. When a message is being delivered to a pipe, file, or autoreply transport as a result of aliasing or forwarding, $@dfn{local_part} is set to the local part of the parent address. [(font color=green)] In all cases, all quoting is removed from the local part. For example, for both the addresses @example "abc:xyz"@@test.example abc\:xyz@@test.example @end example the value of $@dfn{local_part} is @example abc:xyz @end example If you use this variable to create another address, for example, in the @dfn{new_address} option of a @dfn{smartuser} director, you should always wrap it inside a quoting operator: @example new_address = $@{quote:$local_part@}@@new.domain @end example [(/font)] Because global address rewriting happens at the time a message is received, $@dfn{local_part} normally contains the value after rewriting. However, when a rewrite item is actually being processed (see chapter 34) $@dfn{local_part} contains the local part of the address that is being rewritten; it can be used in the expansion of the replacement address, for example, to rewrite local parts by file lookup. $@dfn{local_part_data}: When a director or a router has a setting of the @dfn{local_parts} generic option, and that involves a lookup which succeeds, the data read by the lookup is available during the running of the director or router as $@dfn{local_part_data}. In addition, if the driver directs or routes the address to a transport, the value is available in that transport. In all other situations, this variable expands to nothing. $@dfn{local_part_prefix}: When an address is being directed or delivered locally, and a specific prefix for the local part was recognized, it is available in this variable. Otherwise it is empty. $@dfn{local_part_suffix}: When an address is being directed or delivered locally, and a specific suffix for the local part was recognized, it is available in this variable. Otherwise it is empty. $@dfn{localhost_number}: This contains the expanded value of the @dfn{localhost_number} option. The expansion happens after the main options have been read. @cindex message: age of $@dfn{message_age}: This variable is set at the start of a delivery attempt to contain the number of seconds since the message was received. It does not change during a single delivery attempt. @cindex body of message: expansion variable @cindex message: body in expansion $@dfn{message_body}: This variable contains the initial portion of a message's body while it is being delivered, and is intended mainly for use in filter files. The maximum number of characters of the body that are used is set by the @dfn{message_body_visible} configuration option; the default is 500. Newlines are converted into spaces to make it easier to search for phrases that might be split over a line break. @cindex body of message: expansion variable @cindex message: body in expansion $@dfn{message_body_end}: This variable contains the final portion of a message's body while it is being delivered. The format and maximum size are as for $@dfn{message_body}. @cindex body of message: size @cindex message: body size $@dfn{message_body_size}: When a message is being received or delivered, this variable contains the size of the body in bytes. The count starts from the character after the blank line that separates the body from the header. Newlines are included in the count. See also $@dfn{message_size} and $@dfn{body_linecount}. $@dfn{message_headers}: This variable contains a concatenation of all the header lines when a message is being processed. They are separated by newline characters. $@dfn{message_id}: When a message is being received or delivered, this variable contains the unique message id which is used by Exim to identify the message. $@dfn{message_precedence}: When a message is being delivered, the value of any @dfn{Precedence:} header is made available in this variable. If there is no such header, the value is the null string. @cindex size of message @cindex message: size $@dfn{message_size}: When a message is being received or delivered, this variable contains its size in bytes. In most cases, the size includes those headers that were received with the message, but not those (such as @dfn{Envelope-to:}) that are added to individual deliveries as they are written. However, there is one special case: during the expansion of the @dfn{maildir_tag} option in the @dfn{appendfile} transport while doing a delivery in maildir format, the value of $@dfn{message_size} is the precise size of the file that has been written. See also $@dfn{message_body_size} and $@dfn{body_linecount}. $@dfn{n0} -- $@dfn{n9}: These variables are counters that can be incremented by means of the @dfn{add} command in filter files. $@dfn{original_domain}: When a top-level address is being processed for delivery, this contains the same value as $@dfn{domain}. However, if a `child' address (for example, generated by an alias, forward, or filter file) is being processed, this variable contains the domain of the original address. This differs from $@dfn{parent_domain} when there is more than one level of aliasing or forwarding. When more than one address is being delivered in a batch by a local or remote transport, $@dfn{original_domain} is not set. Address rewriting happens as a message is received. Once it has happened, the previous form of the address is no longer accessible. It is the rewritten top-level address whose domain appears in this variable. $@dfn{original_local_part}: When a top-level address is being processed for delivery, this contains the same value as $@dfn{local_part}. However, if a `child' address (for example, generated by an alias, forward, or filter file) is being processed, this variable contains the local part of the original address. This differs from $@dfn{parent_local_part} when there is more than one level of aliasing or forwarding. When more than one address is being delivered in a batch by a local or remote transport, $@dfn{original_local_part} is not set. Address rewriting happens as a message is received. Once it has happened, the previous form of the address is no longer accessible. It is the rewritten top-level address whose local part appears in this variable. @cindex gid: of originating user @cindex sender: gid $@dfn{originator_gid}: The value of $@dfn{caller_gid} that was set when the message was received. For messages received via the command line, this is the gid of the sending user. For messages received by SMTP over TCP/IP, this is normally the gid of the Exim user. @cindex uid: of originating user @cindex sender: uid $@dfn{originator_uid}: The value of $@dfn{caller_uid} that was set when the message was received. For messages received via the command line, this is the uid of the sending user. For messages received by SMTP over TCP/IP, this is normally the uid of the Exim user. $@dfn{parent_domain}: This variable is empty, except when a `child' address (generated by aliasing or forwarding, for example) is being processed, in which case it contains the domain of the immediately preceding parent address. $@dfn{parent_local_part}: This variable is empty, except when a `child' address (generated by aliasing or forwarding, for example) is being processed, in which case it contains the local part of the immediately preceding parent address. @cindex filter: transport filter @cindex transport: filter $@dfn{pipe_addresses}: This is not an expansion variable, but is mentioned here because the string `$pipe_addresses' is handled specially in the command specification for the @dfn{pipe} transport and in transport filters. It cannot be used in general expansion strings, and provokes an `unknown variable' error if encountered. $@dfn{primary_hostname}: The value set in the configuration file, or read by the @dfn{uname()} function. $@dfn{prohibition_reason}: This variable is set only during the expansion of prohibition messages. See section 46.5 for details. $@dfn{qualify_domain}: The value set for this option in the configuration file. $@dfn{qualify_recipient}: The value set for this option in the configuration file, or if not set, the value of $@dfn{qualify_domain}. $@dfn{rbl_domain}: While expanding @dfn{prohibition_message} when rejecting a recipient because of an RBL failure (see section 46.5), $@dfn{rbl_domain} contains the name of the RBL domain that caused the rejection. $@dfn{rbl_text}: While expanding @dfn{prohibition_message} when rejecting a recipient because of an RBL failure (see section 46.5), $@dfn{rbl_text} contains the text of a DNS TXT record that is associated with the block, if one exists. $@dfn{received_for}: If there is only a single recipient address in an incoming message, then when the @dfn{Received:} header line is being built, this variable contains that address. Otherwise it is empty. $@dfn{received_protocol}: When a message is being processed, this variable contains the name of the protocol by which it was received. $@dfn{recipients}: This variable contains a list of envelope recipients for a message, but is recognized only in the system filter file, to prevent exposure of Bcc recipients to ordinary users. A comma and a space separate the addresses in the replacement text. $@dfn{recipients_count}: When a message is being processed, this variable contains the number of envelope recipients that came with the message. Duplicates are not excluded from the count. $@dfn{reply_address}: When a message is being processed, this variable contains the contents of the @dfn{Reply-To:} header line if one exists, or otherwise the contents of the @dfn{From:} header line. However, if the message contains a set of @file{Resent-} header lines, their contents are used in preference. $@dfn{return_path}: When a message is being delivered, this variable contains the return path -- the sender field that will be sent as part of the envelope. It is not enclosed in <> characters. In many cases, $@dfn{return_path} has the same value as $@dfn{sender_address}, but if, for example, an incoming message to a mailing list has been expanded by a director which specifies a specific address for delivery error messages, $@dfn{return_path} contains the new error address, while $@dfn{sender_address} contains the original sender address that was received with the message. $@dfn{return_size_limit}: This contains the value set in the @dfn{return_size_limit} option, rounded up to a multiple of 1000. It is useful when a customized error message text file is in use (see chapter 39). $@dfn{route_option}: A router may set up an arbitrary string to be passed to a transport via this variable. Currently, only the @dfn{queryprogram} router has the ability to do so. $@dfn{self_hostname}: The generic router option @dfn{self} can be set to the values `local' or [(font color=green)] `pass' [(/font)] (amongst others). These cause the address to be passed over to the directors, as if its domain were a local domain, or to be passed on to the next router, respectively. While subsequently directing or routing (and doing any deliveries) $@dfn{self_hostname} is set to the name of the local host that the router encountered. In other circumstances its contents are null. $@dfn{sender_address}: When a message is being processed, this variable contains the sender's address that was received in the message's envelope. For delivery failure reports, the value of this variable is the empty string. $@dfn{sender_address_domain}: The domain portion of $@dfn{sender_address}. $@dfn{sender_address_local_part}: The local part portion of $@dfn{sender_address}. $@dfn{sender_fullhost}: When a message is received from a remote host, this variable contains the host name and IP address in a single string, which always ends with the IP address in square brackets. If @dfn{log_incoming_port} is set, the port number on the remote host is added to the IP address, separated by a full stop. The format of the rest of the string depends on whether the host issued a @sc{helo} or @sc{ehlo} SMTP command, and whether the host name was verified by looking up its IP address. (Looking up the IP address can be forced by the @dfn{host_lookup} option, independent of verification.) A plain host name at the start of the string is a verified host name; if this is not present, verification either failed or was not requested. A host name in parentheses is the argument of a @sc{helo} or @sc{ehlo} command. This is omitted if it is identical to the verified host name or to the host's IP address in square brackets. $@dfn{sender_helo_name}: When a message is received from a remote host that has issued a @sc{helo} or @sc{ehlo} command, the first item in the argument of that command is placed in this variable. It is also set if @sc{helo} or @sc{ehlo} is used when a message is received using SMTP locally via the -@dfn{bs} or -@dfn{bS} options. $@dfn{sender_host_address}: When a message is received from a remote host, this variable contains that host's IP address. The value is set as soon as the connection is established, so it is available, for example, during the expansion of @dfn{prohibition_message}. $@dfn{sender_host_authenticated}: During message delivery, this variable contains the name (not the public name) of the authenticator driver which successfully authenticated the client from which the message was received. It is empty if there was no successful authentication. $@dfn{sender_host_name}: When a message is received from a remote host, this variable contains the host's name as verified by looking up its IP address. If verification failed, or was not requested, this variable contains the empty string. $@dfn{sender_host_port}: When a message is received from a remote host, this variable contains the port number that was used on the remote host. $@dfn{sender_ident}: When a message is received from a remote host, this variable contains the identification received in response to an RFC 1413 request. When a message has been received locally, this variable contains the login name of the user that called Exim. $@dfn{sender_rcvhost}: This is provided specifically for use in @dfn{Received:} headers. It starts with either the verified host name (as obtained from a @cindex DNS reverse lookup @cindex reverse DNS lookup reverse DNS lookup) or, if there is no verified host name, the IP address in square brackets. After that there may be text in parentheses. When the first item is a verified host name, the first thing in the parentheses is the IP address in square brackets. There may also be items of the form `helo=@dfn{xxxx}' if @sc{helo} or @sc{ehlo} was used and its argument was not identical to the real host name or IP address, and `ident=@dfn{xxxx}' if an RFC 1413 ident string is available. If all three items are present in the parentheses, a newline and tab are inserted into the string, to improve the formatting of the @dfn{Received:} header. $@dfn{sn0} -- $@dfn{sn9}: These variables are copies of the values of the $@dfn{n0} -- $@dfn{n9} accumulators that were current at the end of the system filter file. This allows a system filter file to set values that can be tested in users' filter files. For example, a system filter could set a value indicating how likely it is that a message is junk mail. $@dfn{spool_directory}: The name of Exim's spool directory. $@dfn{thisaddress}: This variable is set only during the processing of the @dfn{foranyaddress} command in a filter file. Its use is explained in the description of that command. $@dfn{tls_cipher}: When a message is received from a remote host over an encrypted SMTP connection, this variable is set to the cipher that was negotiated, for example DES-CBC3-SHA. See chapter 38. $@dfn{tls_peerdn}: When a message is received from a remote host over an encrypted SMTP connection, and Exim is configured to request a certificate from the client, the value of the Distinguished Name of the certificate is made available in the $@dfn{tls_peerdn} during subsequent processing. $@dfn{tod_bsdinbox}: The time of day and date, in the format required for BSD-style mailbox files, for example: Thu Oct 17 17:14:09 1995. $@dfn{tod_full}: A full version of the time and date, for example: Wed, 16 Oct 1995 09:51:40 +0100. The timezone is always given as a numerical offset from GMT. $@dfn{tod_log}: The time and date in the format used for writing Exim's log files, for example: 1995-10-12 15:32:29. @cindex $value $@dfn{value}: This variable contains the result of an expansion lookup [(font color=green)] or extraction [(/font)] operation, as described above. Also, if a @dfn{domainlist} router has a lookup pattern in a route item, $@dfn{value} contains the data that was looked up during the expansion of the host list. If $@dfn{value} is used in other circumstances, its contents are null. $@dfn{version_number}: The version number of Exim. $@dfn{warnmsg_delay}: This variable is set only during the creation of a message warning about a delivery delay. Details of its use are explained in section 39.2. $@dfn{warnmsg_recipients}: This variable is set only during the creation of a message warning about a delivery delay. Details of its use are explained in section 39.2. @node 10[[[]]] Embedded Perl, Main configuration, 9[[[]]] String expansions, Top @chapter 10[[[]]] Embedded Perl @cindex Perl: embedded @cindex Perl: calling from Exim Exim can be built to include an embedded Perl interpreter. When this is done, Perl subroutines can be called as part of the string expansion process. To make use of the Perl support, you need version 5.004 or later of Perl installed on your system. To include the embedded interpreter in the Exim binary, include the line @example EXIM_PERL = perl.o @end example in your @file{Local/Makefile} and then build Exim in the normal way. Access to Perl subroutines is via a global configuration option called @cindex perl_startup @dfn{perl_startup} and an expansion string operator @dfn{$@{perl ...@}}. If there is no @dfn{perl_startup} option in the Exim configuration file then no Perl interpreter is started and there is almost no overhead for Exim (since none of the Perl library will be paged in unless used). If there is a @dfn{perl_startup} option then the associated value is taken to be Perl code which is executed in a newly created Perl interpreter. The value of @dfn{perl_startup} is not expanded in the Exim sense, so you do not need backslashes before any characters to escape special meanings. The option should usually be something like @example perl_startup = do '/etc/exim.pl' @end example where @dfn{/etc/exim.pl} is Perl code which defines any subroutines you want to use from Exim. Exim can be configured either to start up a Perl interpreter as soon as it is entered, or to wait until the first time it is needed. Starting the interpreter at the beginning ensures that it is done while Exim still has its setuid privilege, but can impose an unnecessary overhead if Perl is not in fact used in a particular run. Also, note that this does not mean that Exim is necessarily running as root when Perl is called at a later time. By default, the interpreter is started only when it is needed, but this can be changed in two ways: @itemize @bullet @item @cindex perl_at_start Setting @dfn{perl_at_start} (a boolean option) in the configuration requests a startup when Exim is entered. @item The command line option -@dfn{ps} also requests a startup when Exim is entered, overriding the setting of @dfn{perl_at_start}. @end itemize There is also a command line option -@dfn{pd} (for delay) which suppresses the initial startup, even if @dfn{perl_at_start} is set. When the configuration file includes a @dfn{perl_startup} option you can make use of the string expansion item to call the Perl subroutines that are defined by the @dfn{perl_startup} code. The operator is used in any of the following forms: @example $@{perl@{foo@}@} $@{perl@{foo@}@{argument@}@} $@{perl@{foo@}@{argument1@}@{argument2@} ... @} @end example which calls the subroutine @dfn{foo} with the given arguments. A maximum of eight arguments may be passed. Passing more than this results in an expansion failure with an error message of the form @example Too many arguments passed to Perl subroutine "foo" (max is 8) @end example The return value of the subroutine is inserted into the expanded string, unless the return value is @dfn{undef}. In that case, the expansion fails in the same way as an explicit `fail' on an @dfn{$@{if ...@}} or @dfn{$@{lookup...@}} item. If the subroutine aborts by obeying Perl's @dfn{die} function, the expansion fails with the error message that was passed to @dfn{die}. Within any Perl code called from Exim, the function @dfn{Exim::expand_string} is available to call back into Exim's string expansion function. For example, the Perl code @example my $lp = Exim::expand_string('$local_part'); @end example makes the current Exim $@dfn{local_part} available in the Perl variable $@dfn{lp}. Note those are single quotes and not double quotes to protect against $@dfn{local_part} being interpolated as a Perl variable. If the string expansion is forced to fail by a `fail' item, the result of @dfn{Exim::expand_string} is @dfn{undef}. If there is a syntax error in the expansion string, the Perl call from the original expansion string fails with an appropriate error message, in the same way as if @dfn{die} were used. @node 11[[[]]] Main configuration, Driver specifications, 10[[[]]] Embedded Perl, Top @chapter 11[[[]]] Main configuration @cindex configuration: main @cindex main configuration The first part of the run time configuration file contains the main configuration settings. Each setting occupies one line of the file, possibly continued by a terminating backslash. If any setting is preceded by the word `hide', the -@dfn{bP} option displays its value to admin users only (see section 7.3). All macro definitions must be in this part of the file -- they differ from options settings by starting with an upper-case letter (see section 7.2). The available options are listed in alphabetical order below, along with their types and default values. @sp 2 @menu * accept_8bitmime:: * accept_timeout:: * admin_groups:: * allow_mx_to_ip:: * always_bcc:: * auth_always_advertise:: * auth_hosts:: * auth_over_tls_hosts:: * auto_thaw:: * bi_command:: * check_log_inodes:: * check_log_space:: * check_spool_inodes:: * check_spool_space:: * collapse_source_routes:: * daemon_smtp_port:: * daemon_smtp_service:: * debug_level:: * delay_warning:: * delay_warning_condition:: * deliver_load_max:: * deliver_queue_load_max:: * delivery_date_remove:: * dns_again_means_nonexist:: * dns_check_names:: * dns_check_names_pattern:: * dns_retrans:: * dns_ipv4_lookup:: * dns_retry:: * envelope_to_remove:: * errmsg_text:: * errmsg_file:: * errors_address:: * errors_copy:: * errors_reply_to:: * exim_group:: * exim_path:: * exim_user:: * extract_addresses_remove_arguments:: * finduser_retries:: * forbid_domain_literals:: * freeze_tell_mailmaster:: * gecos_name:: * gecos_pattern:: * headers_check_syntax:: * headers_checks_fail:: * headers_sender_verify:: * headers_sender_verify_errmsg:: * helo_accept_junk_hosts:: * helo_strict_syntax:: * helo_verify:: * hold_domains:: * host_accept_relay:: * host_auth_accept_relay:: * host_lookup:: * host_reject:: * host_reject_recipients:: * hosts_treat_as_local:: * ignore_errmsg_errors:: * ignore_errmsg_errors_after:: * ignore_fromline_hosts:: * ignore_fromline_local:: * keep_malformed:: * kill_ip_options:: * ldap_default_servers:: * local_domains:: * local_domains_include_host:: * local_domains_include_host_literals:: * local_from_check:: * local_from_prefix:: * local_from_suffix:: * local_interfaces:: * localhost_number:: * locally_caseless:: * log_all_parents:: * log_arguments:: * log_file_path:: * log_incoming_port:: * log_ip_options:: * log_level:: * log_queue_run_level:: * log_received_recipients:: * log_received_sender:: * log_refused_recipients:: * log_rewrites:: * log_sender_on_delivery:: * log_smtp_confirmation:: * log_smtp_connections:: * log_smtp_syntax_errors:: * log_subject:: * lookup_open_max:: * max_username_length:: * message_body_visible:: * message_filter:: * message_filter_directory_transport:: * message_filter_directory2_transport:: * message_filter_file_transport:: * message_filter_group:: * message_filter_pipe_transport:: * message_filter_reply_transport:: * message_filter_user:: * message_id_header_text:: * message_size_limit:: * message_size_limit_count_recipients:: * move_frozen_messages:: * mysql_servers:: * never_users:: * nobody_group:: * nobody_user:: * percent_hack_domains:: * perl_at_start:: * perl_startup:: * pgsql_servers:: * pid_file_path:: * preserve_message_logs:: * primary_hostname:: * print_topbitchars:: * prod_requires_admin:: * prohibition_message:: * qualify_domain:: * qualify_recipient:: * queue_list_requires_admin:: * queue_only:: * queue_only_file:: * queue_only_load:: * queue_remote_domains:: * queue_run_in_order:: * queue_run_max:: * queue_smtp_domains:: * rbl_domains:: * rbl_hosts:: * rbl_log_headers:: * rbl_log_rcpt_count:: * rbl_reject_recipients:: * rbl_warn_header:: * received_header_text:: * received_headers_max:: * receiver_try_verify:: * receiver_unqualified_hosts:: * receiver_verify:: * receiver_verify_addresses:: * receiver_verify_hosts:: * receiver_verify_senders:: * recipients_max:: * recipients_max_reject:: * recipients_reject_except:: * recipients_reject_except_senders:: * refuse_ip_options:: * relay_domains:: * relay_domains_include_local_mx:: * relay_match_host_or_sender:: * remote_max_parallel:: * remote_sort:: * retry_data_expire:: * retry_interval_max:: * return_path_remove:: * return_size_limit:: * rfc1413_hosts:: * rfc1413_query_timeout:: * security:: * sender_address_relay:: * sender_address_relay_hosts:: * sender_reject:: * sender_reject_recipients:: * sender_try_verify:: * sender_unqualified_hosts:: * sender_verify:: * sender_verify_batch:: * sender_verify_callback_domains:: * sender_verify_callback_timeout:: * sender_verify_fixup:: * sender_verify_hosts:: * sender_verify_hosts_callback:: * sender_verify_max_retry_rate:: * sender_verify_reject:: * smtp_accept_keepalive:: * smtp_accept_max:: * smtp_accept_max_per_host:: * smtp_accept_queue:: * smtp_accept_queue_per_connection:: * smtp_accept_reserve:: * smtp_banner:: * smtp_check_spool_space:: * smtp_connect_backlog:: * smtp_etrn_command:: * smtp_etrn_hosts:: * smtp_etrn_serialize:: * smtp_expn_hosts:: * smtp_load_reserve:: * smtp_receive_timeout:: * smtp_reserve_hosts:: * smtp_verify:: * split_spool_directory:: * spool_directory:: * strip_excess_angle_brackets:: * strip_trailing_dot:: * syslog_timestamp:: * timeout_frozen_after:: * timestamps_utc:: * timezone:: * tls_advertise_hosts:: * tls_certificate:: * tls_dhparam:: * tls_host_accept_relay:: * tls_hosts:: * tls_log_cipher:: * tls_log_peerdn:: * tls_privatekey:: * tls_verify_certificates:: * tls_verify_ciphers:: * tls_verify_hosts:: * trusted_groups:: * trusted_users:: * unknown_login:: * unknown_username:: * untrusted_set_sender:: * uucp_from_pattern:: * uucp_from_sender:: * warnmsg_file:: @end menu @node accept_8bitmime, accept_timeout, 11[[[]]] Main configuration, 11[[[]]] Main configuration @findex accept_8bitmime @unnumberedsubsec accept_8bitmime Type: boolean@* Default: false @cindex 8BITMIME @cindex 8-bit characters @cindex top bit This option causes Exim to send @sc{8bitmime} in its response to an SMTP @sc{ehlo} command, and to accept the @sc{body=} parameter on @sc{mail} commands. However, though Exim is 8-bit clean, it is not a protocol converter, and it takes no steps to do anything special with messages received by this route. Consequently, this option is turned off by default. @node accept_timeout, admin_groups, accept_8bitmime, 11[[[]]] Main configuration @findex accept_timeout @unnumberedsubsec accept_timeout Type: time@* Default: 0s @cindex timeout: local message This sets the timeout for accepting a non-SMTP message, that is, the maximum time that Exim waits when reading a message on the standard input. If the value is zero, it will wait for ever. This setting is overridden by the -@dfn{or} command option. The timeout for incoming SMTP messages is controlled by @dfn{smtp_receive_timeout}. @node admin_groups, allow_mx_to_ip, accept_timeout, 11[[[]]] Main configuration @findex admin_groups @unnumberedsubsec admin_groups Type: string list@* Default: unset @cindex admin user If the current group or any of the supplementary groups of the caller is in this list, the caller has admin privileges. If all your system programmers are in a specific group, for example, you can give them all Exim admin privileges by putting that group in @dfn{admin_groups}. However, this does not permit them to read Exim's spool files (whose group owner is the Exim gid). To permit this, you have to add individuals to the Exim group. @node allow_mx_to_ip, always_bcc, admin_groups, 11[[[]]] Main configuration @findex allow_mx_to_ip @unnumberedsubsec allow_mx_to_ip Type: boolean@* Default: false @cindex MX pointing to IP address It appears that more and more DNS zones are breaking the rules and putting IP addresses on the right hand side of MX records. Exim follows the rules and rejects this, giving an error message that explains the mis-configuration. However, some other MTAs support this practice, so to avoid `Why can't Exim do this?' complaints, @dfn{allow_mx_to_ip} exists, in order to enable this heinous activity. It is not recommended, except when you have no other choice. @node always_bcc, auth_always_advertise, allow_mx_to_ip, 11[[[]]] Main configuration @findex always_bcc @unnumberedsubsec always_bcc Type: boolean@* Default: false @cindex To: header @cindex Cc: header @cindex Bcc: header Exim adds a @dfn{To:} header to messages whose recipients are given on the command line when there is no @dfn{To:}, @dfn{Cc:}, or @dfn{Bcc:} in the message. In other cases of missing recipient headers, it just adds an empty @dfn{Bcc:} header to make the message conform with RFC 822. Setting @dfn{always_bcc} causes it to add an empty @dfn{Bcc:} in all cases. This can be helpful in conjunction with mailing list software that passes recipient addresses on the command line. @node auth_always_advertise, auth_hosts, always_bcc, 11[[[]]] Main configuration @findex auth_always_advertise @unnumberedsubsec auth_always_advertise Type: boolean@* Default: true @cindex authentication: advertising This option is available only when Exim is compiled with authentication support. Normally, if any server authentication mechanisms are configured, Exim advertises them in response to any @sc{ehlo} command. However, if @dfn{auth_always_advertise} is set false, Exim advertises availability of the @sc{auth} command only if the calling host is in @dfn{auth_hosts}, or if it is in @dfn{host_auth_accept_relay} and not in @dfn{host_accept_relay}. In other words, it advertises only when the host is required always to authenticate or to authenticate in order to relay. Otherwise, Exim does not advertise @sc{auth}, though it is always prepared to accept it. Certain mail clients (for example, Netscape) require the user to provide a name and password for authentication if @sc{auth} is advertised, even though it may not be needed (the host may be in @dfn{host_accept_relay}). Unsetting @dfn{auth_always_advertise} makes these clients more friendly in these circumstances, while still allowing you to use combinations such as @example host_auth_accept_relay = * host_accept_relay = 10.9.8.0/24 @end example without needing to fill up @dfn{host_auth_accept_relay} with exceptions. @node auth_hosts, auth_over_tls_hosts, auth_always_advertise, 11[[[]]] Main configuration @findex auth_hosts @unnumberedsubsec auth_hosts Type: host list@* Default: unset Any hosts in this list that connect to an Exim server as clients are required to authenticate themselves using the SMTP @sc{auth} command before any commands other than @sc{helo}, @sc{ehlo}, @sc{help}, @sc{auth}, @sc{noop}, @sc{rset}, or @sc{quit} are accepted. See chapter 35 for details of SMTP authentication. [(font color=green)] @node auth_over_tls_hosts, auto_thaw, auth_hosts, 11[[[]]] Main configuration @findex auth_over_tls_hosts @unnumberedsubsec auth_over_tls_hosts Type: host list@* Default: unset Any hosts in this list must start an encrypted TLS session before issuing an SMTP @sc{auth} command, but it does not of itself require them to authenticate. See chapter 38 for details of SMTP encryption. [(/font)] @node auto_thaw, bi_command, auth_over_tls_hosts, 11[[[]]] Main configuration @findex auto_thaw @unnumberedsubsec auto_thaw Type: time@* Default: 0s @cindex thawing messages @cindex unfreezing messages If this option is set to a time greater than zero, a queue runner will try a new delivery attempt on any frozen message if this much time has passed since it was frozen. This may result in the message being re-frozen if nothing has changed since the last attempt. It is a way of saying `keep on trying, even though there are big problems'. See also @dfn{timeout_frozen_after}, @dfn{ignore_errmsg_errors}, and @dfn{ignore_errmsg_errors_after}. @node bi_command, check_log_inodes, auto_thaw, 11[[[]]] Main configuration @findex bi_command @unnumberedsubsec bi_command Type: string@* Default: unset This option supplies the name of a command that is run when Exim is called with the -@dfn{bi} option (see chapter 5). The string value is just the command name, it is not a complete command line. If an argument is required, it must come from the -@dfn{oA} command line option. @node check_log_inodes, check_log_space, bi_command, 11[[[]]] Main configuration @findex check_log_inodes @unnumberedsubsec check_log_inodes Type: integer@* Default: 0 See @dfn{check_spool_space} below. @node check_log_space, check_spool_inodes, check_log_inodes, 11[[[]]] Main configuration @findex check_log_space @unnumberedsubsec check_log_space Type: integer@* Default: 0 See @dfn{check_spool_space} below. @node check_spool_inodes, check_spool_space, check_log_space, 11[[[]]] Main configuration @findex check_spool_inodes @unnumberedsubsec check_spool_inodes Type: integer@* Default: 0 See @dfn{check_spool_space} below. @node check_spool_space, collapse_source_routes, check_spool_inodes, 11[[[]]] Main configuration @findex check_spool_space @unnumberedsubsec check_spool_space Type: integer@* Default: 0 @cindex checking disc space @cindex disc space, checking @cindex spool: checking space The four @dfn{check_...} options allow for checking of disc resources before a message is accepted: @dfn{check_spool_space} and @dfn{check_spool_inodes} check the spool partition if either value is greater than zero, for example: @example check_spool_space = 10M check_spool_inodes = 100 @end example The spool partition is the one which contains the directory defined by @sc{spool_directory} in @file{Local/Makefile}. @dfn{check_log_space} and @dfn{check_log_inodes} check the partition in which log files are written if either is greater than zero. These should be set only if @dfn{log_file_path} and @dfn{spool_directory} refer to different partitions. If there is less space or fewer inodes than requested, Exim refuses to accept incoming mail. In the case of SMTP input this is done by giving a 452 temporary error response to the @sc{mail} command. If ESMTP is in use and there was a @sc{size} parameter on the @sc{mail} command, its value is added to the @dfn{check_spool_space} value, and the check is performed even if @dfn{check_spool_space} is zero, unless @dfn{no_smtp_check_spool_space} is set. For non-SMTP input and for batched SMTP input, the test is done at start-up; on failure a message is written to stderr and Exim exits with a non-zero code, as it obviously cannot send an error message of any kind. @node collapse_source_routes, daemon_smtp_port, check_spool_space, 11[[[]]] Main configuration @findex collapse_source_routes @unnumberedsubsec collapse_source_routes Type: boolean@* Default: false @cindex source routing: in email address @cindex address: source-routed From version 3.10, this option is obsolete and does nothing. Formerly, it caused source-routed mail addresses to be stripped down to their final components. This now happens automatically, and cannot be suppressed. @node daemon_smtp_port, daemon_smtp_service, collapse_source_routes, 11[[[]]] Main configuration @findex daemon_smtp_port @unnumberedsubsec daemon_smtp_port Type: string@* Default: unset This option specifies the numerical port number or the service name equivalent on which the daemon is to listen for incoming SMTP calls. It is overridden by -@dfn{oX} on the command line. If this option is not set, the service name `smtp' is used. @node daemon_smtp_service, debug_level, daemon_smtp_port, 11[[[]]] Main configuration @findex daemon_smtp_service @unnumberedsubsec daemon_smtp_service Type: string@* Default: unset This option is a synonym for @dfn{daemon_smtp_port}. @node debug_level, delay_warning, daemon_smtp_service, 11[[[]]] Main configuration @findex debug_level @unnumberedsubsec debug_level Type: integer@* Default: 0 This option sets the debug level, thus enabling it to be set when calling Exim from an MUA, but it is overridden by the use of -@dfn{d} on the command line. @node delay_warning, delay_warning_condition, debug_level, 11[[[]]] Main configuration @findex delay_warning @unnumberedsubsec delay_warning Type: time list@* Default: 24h @cindex warning of delay When a message is delayed, Exim sends a warning message to the sender at intervals specified by this option. If it is set to a zero, no warnings are sent. The data is a colon-separated list of times after which to send warning messages. Up to 10 times may be given. If a message has been on the queue for longer than the last time, the last interval between the times is used to compute subsequent warning times. For example, with @example delay_warning = 4h:8h:24h @end example the first message is sent after 4 hours, the second after 8 hours, and subsequent ones every 16 hours thereafter. To stop warnings after a given time, set a huge subsequent time. @node delay_warning_condition, deliver_load_max, delay_warning, 11[[[]]] Main configuration @findex delay_warning_condition @unnumberedsubsec delay_warning_condition Type: string, expanded@* Default: see below The string is expanded at the time a warning message might be sent. If all the deferred addresses have the same domain, it is set in $@dfn{domain} during the expansion. Otherwise $@dfn{domain} is empty. If the result of the expansion is a forced failure, an empty string, or a string matching any of `0', `no' or `false' (the comparison being done caselessly) then the warning message is not sent. The default is @example delay_warning_condition = \ $@{if match@{$h_precedence:@}@{(?i)bulk|list|junk@}@{no@}@{yes@}@} @end example which suppresses the sending of warnings about messages that have `bulk', `list' or `junk' in a @dfn{Precedence:} header. Note that the colon to terminate the header name cannot be omitted, because brace characters may legally occur in header names. @node deliver_load_max, deliver_queue_load_max, delay_warning_condition, 11[[[]]] Main configuration @findex deliver_load_max @unnumberedsubsec deliver_load_max Type: fixed-point@* Default: unset @cindex load average When this option is set, no message deliveries are ever done if the system load average is greater than its value, except for deliveries forced with the -@dfn{M} option. If @dfn{deliver_queue_load_max} is not set and the load gets this high during a queue run, the run is abandoned. There are some operating systems for which Exim cannot determine the load average (see chapter 1); for these this option has no effect. @node deliver_queue_load_max, delivery_date_remove, deliver_load_max, 11[[[]]] Main configuration @findex deliver_queue_load_max @unnumberedsubsec deliver_queue_load_max Type: fixed-point@* Default: unset If this option is set, its value is used to determine whether to abandon a queue run, instead of the value of @dfn{deliver_load_max}. @node delivery_date_remove, dns_again_means_nonexist, deliver_queue_load_max, 11[[[]]] Main configuration @findex delivery_date_remove @unnumberedsubsec delivery_date_remove Type: boolean@* Default: true @cindex Delivery-date: header Exim's transports have an option for adding a @dfn{Delivery-date:} header to a message when it is delivered -- in exactly the same way as @dfn{Return-path:} is handled. @dfn{Delivery-date:} records the actual time of delivery. Such headers should not be present in incoming messages, and this option causes them to be removed, to avoid any problems that might occur when a delivered message is subsequently sent on to some other recipient. @node dns_again_means_nonexist, dns_check_names, delivery_date_remove, 11[[[]]] Main configuration @findex dns_again_means_nonexist @unnumberedsubsec dns_again_means_nonexist Type: domain list@* Default: unset DNS lookups give a `try again' response for the DNS error `non-Authoritive host found or @sc{serverfail}'. This can cause Exim to keep trying to deliver a message, or to give repeated temporary errors to incoming mail. Sometimes the effect is caused by a badly set up nameserver and may persist for a long time. If a domain which exhibits this problem matches anything in @dfn{dns_again_means_nonexist} then it is treated as if it did not exist. This option should be used with care. @node dns_check_names, dns_check_names_pattern, dns_again_means_nonexist, 11[[[]]] Main configuration @findex dns_check_names @unnumberedsubsec dns_check_names Type: boolean@* Default: true This option causes Exim to check domain names for illegal characters before handing them to the DNS resolver, because some resolvers give temporary errors for bad names. If a domain name contains any illegal characters, a `not found' result is forced. The check is done by matching the domain name against the regular expression specified by the @dfn{dns_check_names_pattern} option. @node dns_check_names_pattern, dns_retrans, dns_check_names, 11[[[]]] Main configuration @findex dns_check_names_pattern @unnumberedsubsec dns_check_names_pattern Type: string@* Default: see below This option defines the regular expression that is used when the @dfn{dns_check_names} option is set. The default value is @example dns_check_names_pattern = \ (?i)^(?>(?(1)\.|())[^\W_](?>[a-z0-9-]*[^\W_])?)+$ @end example which permits only letters, digits, and hyphens in components, but they may not start or end with a hyphen. @node dns_retrans, dns_ipv4_lookup, dns_check_names_pattern, 11[[[]]] Main configuration @findex dns_retrans @unnumberedsubsec dns_retrans Type: time@* Default: 0s The options @dfn{dns_retrans} and @dfn{dns_retry} can be used to set the retransmission and retry parameters for DNS lookups. Values of zero (the defaults) leave the system default settings unchanged. The first value is the time between retries, and the second is the number of retries. It isn't totally clear exactly how these settings affect the total time a DNS lookup may take. I haven't found any documentation about timeouts on DNS lookups; these parameter values are available in the external resolver interface structure, but nowhere does it seem to describe how they are used or what you might want to set in them. @node dns_ipv4_lookup, dns_retry, dns_retrans, 11[[[]]] Main configuration @findex dns_ipv4_lookup @unnumberedsubsec dns_ipv4_lookup Type: boolean@* Default: false @cindex IPv6 DNS lookup When Exim is compiled with IPv6 support, it looks for IPv6 address records (AAAA and A6) as well as IPv4 address records when trying to find IP addresses for hosts. However, if @dfn{dns_ipv4_lookup} is set, it disables DNS lookups for AAAA and A6 records. This is a fudge to help with name servers that give big delays or otherwise do not work for these new record types. If Exim is handed either of these record types as part of an MX lookup (for example), it still handles them, and may as a result make outgoing IPv6 calls. All this option does is to make it look only for IPv4-style A records when it needs to find an IP address for a host name. In due course, when the world's name servers have all been upgraded, there should be no need for this option. @node dns_retry, envelope_to_remove, dns_ipv4_lookup, 11[[[]]] Main configuration @findex dns_retry @unnumberedsubsec dns_retry Type: integer@* Default: 0 See @dfn{dns_retrans} above. @node envelope_to_remove, errmsg_text, dns_retry, 11[[[]]] Main configuration @findex envelope_to_remove @unnumberedsubsec envelope_to_remove Type: boolean@* Default: true @cindex Envelope-to: header Exim's transports have an option for adding an @dfn{Envelope-to:} header to a message when it is delivered -- in exactly the same way as @dfn{Return-path:} is handled. @dfn{Envelope-to:} records the original recipient address in the envelope that caused the delivery. Such headers should not be present in incoming messages, and this option causes them to be removed, to avoid any problems that might occur when a delivered message is subsequently sent on to some other recipient. @node errmsg_text, errmsg_file, envelope_to_remove, 11[[[]]] Main configuration @findex errmsg_text @unnumberedsubsec errmsg_text Type: string@* Default: unset If @dfn{errmsg_text} is set, its contents are included in the default error message immediately after `This message was created automatically by mail delivery software.' It is not used if @dfn{errmsg_file} is set. @node errmsg_file, errors_address, errmsg_text, 11[[[]]] Main configuration @findex errmsg_file @unnumberedsubsec errmsg_file Type: string@* Default: unset @cindex error messages: customizing @cindex delivery: failure report This option defines a template file containing paragraphs of text to be used for constructing the message which is sent by Exim in the case of a delivery failure. Details of the file's contents are given in chapter 39. See also @dfn{warnmsg_file}. @node errors_address, errors_copy, errmsg_file, 11[[[]]] Main configuration @findex errors_address @unnumberedsubsec errors_address Type: string@* Default: "postmaster" @cindex postmaster The mail address to which Exim will send certain error reports. As the default is specified without a domain, it will be sent to the domain specified by the @dfn{qualify_recipient} option. If this address is specified with a domain, it must be a fully qualified domain. There are actually only a few situations where this address is used: @itemize @bullet @item When @dfn{freeze_tell_mailmaster} is set, and a message that is not a failing, locally generated bounce message is frozen. However, if the @dfn{errors_address} is one of the recipients of the frozen message, nothing is sent, in order to avoid potential loops. @item Delivery failed, and there is no other address to which a bounce message can be sent, except for bounce messages that are timing out (they are just discarded). @item -@dfn{Mg} was used to cancel delivery, and there is no other address to which to send a message. @end itemize @node errors_copy, errors_reply_to, errors_address, 11[[[]]] Main configuration @findex errors_copy @unnumberedsubsec errors_copy Type: string list, expanded@* Default: unset @cindex delivery: failure report Setting this option causes Exim to send bcc copies of delivery failure reports that it generates to other addresses. The value is a colon-separated list of items; each item consists of a pattern and an address list, separated by white space. If the pattern matches the recipient of the delivery error report, the message is copied to the addresses on the list. The items are scanned in order, and once a matching one is found, no further items are examined. For example: @example errors_copy = spqr@@mydomain postmaster@@mydomain :\ rqps@@mydomain mailmaster@@mydomain,\ postmaster@@mydomain @end example Each pattern can be a single regular expression, indicated by starting it with a circumflex; alternatively, either portion (local part, domain) can start with an asterisk, or the domain can be in any format that is acceptable as an item in a domain list, including a file lookup. A regular expression is matched against the entire (fully qualified) recipient; non-regular expressions must contain both a local part and domain, separated by @@. The address list is a string which is expanded, and must end up as a comma-separated list of addresses. It is used to construct a @dfn{Bcc:} header which is added to the error message. The expansion variables $@dfn{local_part} and $@dfn{domain} are set from the original recipient of the error message, and if there was any wildcard matching, the expansion variables $@dfn{0}, $@dfn{1}, etc. are set in the normal way. @node errors_reply_to, exim_group, errors_copy, 11[[[]]] Main configuration @findex errors_reply_to @unnumberedsubsec errors_reply_to Type: string@* Default: unset Exim's delivery error messages contain the header @example From: Mail Delivery System @end example (where string expansion notation is used to show a variable substitution). Experience shows that a large number of people reply to such messages. If the @dfn{errors_reply_to} option is set, a @dfn{Reply-To:} header is added. The option must specify the complete header body. @node exim_group, exim_path, errors_reply_to, 11[[[]]] Main configuration @findex exim_group @unnumberedsubsec exim_group Type: string@* Default: compile-time configured (can be unset) @cindex gid: Exim's own This option sets the gid under which Exim runs when it gives up root privilege. It is used only when @dfn{exim_user} is also set. Unless it consists entirely of digits, the string is looked up using @dfn{getgrnam()}, and failure causes a configuration error. See chapter 55 for a discussion of security issues. @node exim_path, exim_user, exim_group, 11[[[]]] Main configuration @findex exim_path @unnumberedsubsec exim_path Type: string@* Default: see below This option specifies the path name of the Exim binary, which is used when Exim needs to re-exec itself. The default is set up to point to the file @dfn{exim} in the directory configured at compile time by the @sc{bin_directory} setting. It is necessary to change @dfn{exim_path} if Exim is run from some other place. @node exim_user, extract_addresses_remove_arguments, exim_path, 11[[[]]] Main configuration @findex exim_user @unnumberedsubsec exim_user Type: string@* Default: compile-time configured (can be unset) @cindex uid: Exim's own This option sets the uid under which Exim runs when it gives up root privilege. However, unless there is some compelling reason for not doing so, it is best to specify the uid by setting @sc{exim_uid} in @file{Local/Makefile} rather than using this option, because ownership of the run time configuration file and the use of the -@dfn{C} and -@dfn{D} command line options is checked against the compile-time setting of this parameter, not what is set here. Unless it consists entirely of digits, the string is looked up using @dfn{getpwnam()}, and failure causes a configuration error. If @dfn{exim_group} is not also supplied, the gid is taken from the result of @dfn{getpwnam()} if it is used. If the resulting uid is the root uid, it has the effect of unsetting this option. See chapter 55 for a discussion of security issues. @node extract_addresses_remove_arguments, finduser_retries, exim_user, 11[[[]]] Main configuration @findex extract_addresses_remove_arguments @unnumberedsubsec extract_addresses_remove_arguments Type: boolean@* Default: true According to Sendmail documentation, if any addresses are present on the command line when the -@dfn{t} option is used to build an envelope from a message's headers, they are removed from the recipients list. This is also how Smail behaves. However, it has been reported that some versions of Sendmail in fact add the argument addresses to the recipients list. By default Exim follows the documented behaviour, but if this option is set false it adds rather than removes argument addresses. @node finduser_retries, forbid_domain_literals, extract_addresses_remove_arguments, 11[[[]]] Main configuration @findex finduser_retries @unnumberedsubsec finduser_retries Type: integer@* Default: 0 On systems running NIS or other schemes in which user and group information is distributed from a remote system, there can be times when @dfn{getpwnam()} and related functions fail, even when given valid data, because things time out. Unfortunately these failures cannot be distinguished from genuine `not found' errors. If @dfn{finduser_retries} is set greater than zero, Exim will try that many extra times to find a user or a group, waiting for one second between tries. @node forbid_domain_literals, freeze_tell_mailmaster, finduser_retries, 11[[[]]] Main configuration @findex forbid_domain_literals @unnumberedsubsec forbid_domain_literals Type: boolean@* Default: false @cindex domain literal If this option is set, the RFC 822 domain literal format is not permitted in addresses. The option is set in the default configuration file, because the domain literal format is not normally required these days, and few people know about it. It has, however, been exploited by mail abusers. @node freeze_tell_mailmaster, gecos_name, forbid_domain_literals, 11[[[]]] Main configuration @findex freeze_tell_mailmaster @unnumberedsubsec freeze_tell_mailmaster Type: boolean@* Default: false On encountering certain errors, Exim freezes a message, which means that no further delivery attempts take place until an administrator thaws it. If this option is set, a message is sent to @dfn{errors_address} every time a message is frozen, unless the message is itself a delivery error message. (Without this exception there is the possibility of looping.) If several of the message's addresses cause freezing, only a single message is sent to the mail administrator. The reason(s) for freezing will be found in the message log. @node gecos_name, gecos_pattern, freeze_tell_mailmaster, 11[[[]]] Main configuration @findex gecos_name @unnumberedsubsec gecos_name Type: string, expanded@* Default: unset @cindex HP-UX Some operating systems, notably HP-UX, use the `gecos' field in the system password file to hold other information in addition to users' real names. Exim looks up this field for use when it is creating @dfn{Sender:} or @dfn{From:} headers. If either @dfn{gecos_pattern} or @dfn{gecos_name} are unset, the contents of the field are used unchanged, except that, if an ampersand is encountered, it is replaced by the user's login name with the first character forced to upper-case, since this is a convention that is observed on many systems. When these options are set, @dfn{gecos_pattern} is treated as a regular expression that is to be applied to the field (again with & replaced by the login name), and if it matches, @dfn{gecos_name} is expanded and used as the user's name. Numeric variables such as $@dfn{1}, $@dfn{2}, etc. can be used in the expansion to pick up sub-fields that were matched by the pattern. In HP-UX, where the user's name terminates at the first comma, the following can be used: @example gecos_pattern = ([^,]*) gecos_name = $1 @end example @node gecos_pattern, headers_check_syntax, gecos_name, 11[[[]]] Main configuration @findex gecos_pattern @unnumberedsubsec gecos_pattern Type: string@* Default: unset See @dfn{gecos_name} above. @node headers_check_syntax, headers_checks_fail, gecos_pattern, 11[[[]]] Main configuration @findex headers_check_syntax @unnumberedsubsec headers_check_syntax Type: boolean@* Default: false @cindex header syntax checking @cindex syntax checking headers This option causes Exim to check the syntax of all headers that can contain lists of addresses (@dfn{Sender:}, @dfn{From:}, @dfn{Reply-To:}, @dfn{To:}, @dfn{Cc:}, and @dfn{Bcc:}) on all incoming messages (both local and SMTP). This is a syntax check only, to catch real junk such as @example To: user@@ @end example Like the @dfn{headers_sender_verify} options, the rejection happens after the end of the data, but it is also controlled by @dfn{headers_checks_fail}; if that is unset, the message is accepted and a warning is written to the reject log. If the message contains any headers starting with @file{Resent-} then it is that set of headers which is checked. @node headers_checks_fail, headers_sender_verify, headers_check_syntax, 11[[[]]] Main configuration @findex headers_checks_fail @unnumberedsubsec headers_checks_fail Type: boolean@* Default: true If this option is true, failure of any header check (see below) causes the message to be rejected. If it is false, a warning message is written to the reject log. @node headers_sender_verify, headers_sender_verify_errmsg, headers_checks_fail, 11[[[]]] Main configuration @findex headers_sender_verify @unnumberedsubsec headers_sender_verify Type: boolean@* Default: false @cindex header verification @cindex verifying: headers If this option is set with @dfn{sender_verify}, and the sending host matches @dfn{sender_verify_hosts}, Exim insists on there being at least one verifyable address in one of the @dfn{Sender:}, @dfn{Reply-To:}, or @dfn{From:} headers (which are checked in that order) on all incoming SMTP messages. If one cannot be found, the message is rejected, unless @dfn{headers_checks_fail} is unset, in which case a warning entry is written to the reject log. If there are any headers whose names start with @file{Resent-}, it is that set of headers which is checked. If there is more than one instance of a particular header, all of them are checked. Unfortunately, because it has to read the message before doing this check, the rejection happens after the end of the data, and it is known that some mailers do not treat hard (5xx) errors correctly at this point -- they keep the message on their spools and try again later, but that is their problem, though it does waste some resources. @node headers_sender_verify_errmsg, helo_accept_junk_hosts, headers_sender_verify, 11[[[]]] Main configuration @findex headers_sender_verify_errmsg @unnumberedsubsec headers_sender_verify_errmsg Type: boolean@* Default: false This option acts like @dfn{headers_sender_verify}, except that it applies only to messages whose envelope sender is `<>', that is, delivery error messages whose sender cannot be verified at the time the SMTP @sc{mail} command is received. @node helo_accept_junk_hosts, helo_strict_syntax, headers_sender_verify_errmsg, 11[[[]]] Main configuration @findex helo_accept_junk_hosts @unnumberedsubsec helo_accept_junk_hosts Type: host list@* Default: unset @cindex HELO @cindex EHLO Exim checks the syntax of @sc{helo} and @sc{ehlo} commands for incoming SMTP mail, and gives an error response for invalid data. Unfortunately, there are some SMTP clients that send syntactic junk. They can be accommodated by setting this option. @node helo_strict_syntax, helo_verify, helo_accept_junk_hosts, 11[[[]]] Main configuration @findex helo_strict_syntax @unnumberedsubsec helo_strict_syntax Type: boolean@* Default: false Because so many systems have been found to use underscores in the names they send in the SMTP @sc{helo} command, Exim by default permits them, though it is not in fact legal to use underscores in domain names in SMTP. If @dfn{helo_strict_syntax} is set, underscores are not permitted in @sc{helo} or @sc{ehlo} commands. @node helo_verify, hold_domains, helo_strict_syntax, 11[[[]]] Main configuration @findex helo_verify @unnumberedsubsec helo_verify Type: host list@* Default: unset The RFCs mandate that a server must not reject a message because it doesn't like the @sc{helo} or @sc{ehlo} command. However, some sites like to be stricter. If @dfn{helo_verify} is set, Exim checks each incoming call from any host that matches it, and accepts the call only if: @itemize @bullet @item A @sc{helo} or @sc{ehlo} command is received; @end itemize and @itemize @bullet @item The host name given in that command either: @enumerate a @item is an IP literal matching the calling address of the host (the RFCs specifically allow this), or @item @cindex DNS reverse lookup @cindex reverse DNS lookup matches the host name that Exim obtains by doing a reverse lookup of the calling host address, or @item when looked up using @dfn{gethostbyname()} yields the calling host address. @end enumerate @end itemize If no @sc{helo} or @sc{ehlo} is given, @sc{mail} commands are rejected; if a bad @sc{helo} or @sc{ehlo} is given, it is rejected with a 550 error. Rejections are logged in the main and reject logs. @node hold_domains, host_accept_relay, helo_verify, 11[[[]]] Main configuration @findex hold_domains @unnumberedsubsec hold_domains Type: domain list@* Default: unset This option allows mail for particular domains to be held on the queue manually. The option is overridden if a message delivery is forced with the -@dfn{M}, -@dfn{qf}, -@dfn{Rf} or -@dfn{Sf} options. Otherwise, if a domain matches an item in @dfn{hold_domains}, no routing or delivery for that address is done, and it is deferred every time the message is looked at. This option is intended as a temporary operational measure for delaying the delivery of mail while some problem is being sorted out, or some new configuration tested. It does not override Exim's message clearing away code, which removes messages from the queue if they have been there longer than the longest retry time in any retry rule. If you want to hold messages for longer than the normal retry times, insert a dummy retry rule with a long retry time. @node host_accept_relay, host_auth_accept_relay, hold_domains, 11[[[]]] Main configuration @findex host_accept_relay @unnumberedsubsec host_accept_relay Type: host list@* Default: unset @cindex mail relaying @cindex relaying: control of This option provides a list of hosts that are permitted to relay via the local host to any arbitrary domains. Section 46.4 contains a discussion of relay control. @node host_auth_accept_relay, host_lookup, host_accept_relay, 11[[[]]] Main configuration @findex host_auth_accept_relay @unnumberedsubsec host_auth_accept_relay Type: host list@* Default: unset 7 This option provides a list of hosts that are permitted to relay via the local host to any arbitrary domains, provided the calling host has authenticated itself. Section 46.4 contains a discussion of relay control, and chapter 35 discusses authentication. @node host_lookup, host_reject, host_auth_accept_relay, 11[[[]]] Main configuration @findex host_lookup @unnumberedsubsec host_lookup Type: host list@* Default: unset @cindex host: name Exim does not look up the name of a calling host from its IP address unless it is required to compare against some host list, or @dfn{helo_verify} is set, or the address matches this option (which normally contains IP addresses rather than host names, since the presence of names in itself implies a DNS lookup). The default configuration file contains @example host_lookup = * @end example which causes a lookup to happen for all hosts. If the expense of these lookups is felt to be too great, the setting can be changed or removed. However, Exim always does a lookup if the domain name quoted in a @sc{helo} or @sc{ehlo} command is the local host's own name or any of its local mail domains. @node host_reject, host_reject_recipients, host_lookup, 11[[[]]] Main configuration @findex host_reject @unnumberedsubsec host_reject Type: host list@* Default: unset If this option is set, incoming SMTP calls from the hosts listed (possibly also qualified by an RFC 1413 identification) are rejected as soon as the connection is made. See chapter 46 for more details. @node host_reject_recipients, hosts_treat_as_local, host_reject, 11[[[]]] Main configuration @findex host_reject_recipients @unnumberedsubsec host_reject_recipients Type: host list@* Default: unset If this option is set, all recipients in incoming SMTP calls from the hosts listed, possibly also qualified by an RFC 1413 identification, are rejected. Chapter 46 contains details of this facility, which differs from @dfn{host_reject} only in the point in the SMTP dialogue at which the rejection occurs. @node hosts_treat_as_local, ignore_errmsg_errors, host_reject_recipients, 11[[[]]] Main configuration @findex hosts_treat_as_local @unnumberedsubsec hosts_treat_as_local Type: domain list@* Default: unset @cindex local host: domains treated as If this option is set, any host names that match the domain list are treated as if they were the local host when Exim is scanning host lists obtained from MX records, and also at other times when it is checking whether a host to which a message has been routed is the local host. If it is required that the matching host names also be treated as local domains for mail delivery, they must appear in @dfn{local_domains} as well as in this option. See also the @dfn{allow_localhost} option in the @dfn{smtp} transport. Both these options are needed in a setup with different hosts for incoming and outgoing mail if the resulting system is used for MX backup. @node ignore_errmsg_errors, ignore_errmsg_errors_after, hosts_treat_as_local, 11[[[]]] Main configuration @findex ignore_errmsg_errors @unnumberedsubsec ignore_errmsg_errors Type: boolean@* Default: false @cindex error messages: discarding @cindex delivery: failure report, discarding If this option is set, failed addresses in error reports (that is, bounce messages, whose senders are `<>') are discarded (with a log entry). The default action is to freeze such messages for human attention. @node ignore_errmsg_errors_after, ignore_fromline_hosts, ignore_errmsg_errors, 11[[[]]] Main configuration @findex ignore_errmsg_errors_after @unnumberedsubsec ignore_errmsg_errors_after Type: time@* Default: 0s @cindex error messages: discarding @cindex delivery: failure report, discarding This option, if it is set to a non-zero time, acts as a delayed version of @dfn{ignore_errmsg_errors}, which must be unset for this option to take effect. When an error message that was frozen because of delivery failure has been on the queue for more than the given time, it is unfrozen at the next queue run, and a further delivery is attempted. If delivery fails again, the error message is discarded. This makes it possible to keep failed error messages around for a shorter time than the normal maximum retry time for frozen messages. For example, @example ignore_errmsg_errors_after = 12h @end example retries failed error message deliveries after 12 hours, discarding any further failures. For ways of automatically dealing with other kinds of frozen message, see @dfn{auto_thaw} and @dfn{timeout_frozen_after}. @node ignore_fromline_hosts, ignore_fromline_local, ignore_errmsg_errors_after, 11[[[]]] Main configuration @findex ignore_fromline_hosts @unnumberedsubsec ignore_fromline_hosts Type: host list@* Default: unset @cindex `From' @cindex UUCP, `From' line Some broken SMTP clients insist on sending a UUCP-like `From' line before the headers of a message. By default this is treated as the start of the message's body, which means that any following headers are not recognized as such. Exim can be made to ignore it by setting @dfn{ignore_fromline_hosts} to match those hosts that insist on sending it. If the sender is actually a local process rather than a remote host, and is using -@dfn{bs} to inject the messages, @dfn{ignore_fromline_local} can be set to deal with this case. @node ignore_fromline_local, keep_malformed, ignore_fromline_hosts, 11[[[]]] Main configuration @findex ignore_fromline_local @unnumberedsubsec ignore_fromline_local Type: boolean@* Default: false See @dfn{ignore_fromline_hosts} above. @node keep_malformed, kill_ip_options, ignore_fromline_local, 11[[[]]] Main configuration @findex keep_malformed @unnumberedsubsec keep_malformed Type: time@* Default: 4d This option specifies the length of time to keep messages whose spool files have been corrupted in some way. This should, of course, never happen. At the next attempt to deliver such a message, it gets removed. The incident is logged. @node kill_ip_options, ldap_default_servers, keep_malformed, 11[[[]]] Main configuration @findex kill_ip_options @unnumberedsubsec kill_ip_options Type: boolean@* Default: true @cindex IP options @cindex IP source routing @cindex source routing: in IP packets IP packets can contain options which are @dfn{source routing} data that enables one host to pretend to be another. (Don't confuse IP source routing with source-routed mail addresses, which are something entirely different.) IP source routing is an obvious security risk, and many sites lock out such packets in their routers. Also, some operating systems are able to disable IP source routing at the kernel level. If Exim receives an SMTP call with IP options set, it logs the options if @dfn{log_ip_options} is set. Then, if @dfn{refuse_ip_options} is set, it drops the call; otherwise, if @dfn{kill_ip_options} is set, it unsets the options on the outgoing socket and attempts to continue. @cindex SunOS4 To read the IP options, @dfn{getsockopt()} is used. On some versions of SunOS 4.1 this causes system crashes. There is a patch that fixes this problem, but it can be avoided by setting all three Exim options false. @node ldap_default_servers, local_domains, kill_ip_options, 11[[[]]] Main configuration @findex ldap_default_servers @unnumberedsubsec ldap_default_servers Type: string list@* Default: unset This option provides a list of LDAP servers which are tried in turn when an LDAP query does not contain a server. See section 6.11. The option is available only when Exim has been built with LDAP support. @node local_domains, local_domains_include_host, ldap_default_servers, 11[[[]]] Main configuration @findex local_domains @unnumberedsubsec local_domains Type: domain list@* Default: see below This specifies a list of domains which are recognized as `local', that is, their delivery is handled in a special way by this MTA using directors rather than routers. If this option is not set, it defaults to the value of @dfn{qualify_recipient}. The name of the local host is not by default recognized as a local mail domain; either it must be included in @dfn{local_domains}, or the @dfn{local_domains_include_host} option must be set. @cindex domain literal If you want to accept mail addressed to your host in RFC 822 domain literal format, @dfn{local_domains} must also include the appropriate `domains', consisting of IP addresses enclosed in square brackets. The @dfn{local_domains_include_host_literals} option can be set to add all IP addresses automatically. It is possible to specify @dfn{no} local domains by specifying no data for this option, for example, @example local_domains = @end example If there are very many local domains, they can be stored in a file and looked up whenever this string is searched. See the discussion of domain lists in section 7.12. @node local_domains_include_host, local_domains_include_host_literals, local_domains, 11[[[]]] Main configuration @findex local_domains_include_host @unnumberedsubsec local_domains_include_host Type: boolean@* Default: false If this option is set, the value of @dfn{primary_hostname} is added to the value of @dfn{local_domains}, unless it is already present. This makes it possible to use the same configuration file on a number of different hosts. The same effect can be obtained by including the conventional item `@@' (which matches the primary host name) in @dfn{local_domains}. @node local_domains_include_host_literals, local_from_check, local_domains_include_host, 11[[[]]] Main configuration @findex local_domains_include_host_literals @unnumberedsubsec local_domains_include_host_literals Type: boolean@* Default: false @cindex domain literal @cindex network interfaces @cindex IP address: If this option is set and @dfn{local_interfaces} is unset, the IP addresses of all the interfaces on the local host, with the exception of 127.0.0.1 (and ::1 on IPv6 systems), are added to the value of @dfn{local_domains}, in domain literal format, that is, as strings enclosed in square brackets. If @dfn{local_interfaces} is set, only those addresses it contains (again excluding 127.0.0.1 and ::1) are used. @node local_from_check, local_from_prefix, local_domains_include_host_literals, 11[[[]]] Main configuration @findex local_from_check @unnumberedsubsec local_from_check Type: boolean@* Default: true @cindex Sender: header @cindex From: header When a message is submitted locally (that is, not over a TCP/IP connection) by a non-trusted user, Exim checks that the @dfn{From:} header line matches the login of the calling user, and if not, it adds a @dfn{Sender:} header. If @dfn{local_from_check} is set false, this checking is disabled, and no @dfn{Sender:} header is ever added. Nevertheless, the envelope sender is still forced to be the login id at the qualify domain. @node local_from_prefix, local_from_suffix, local_from_check, 11[[[]]] Main configuration @findex local_from_prefix @unnumberedsubsec local_from_prefix Type: string@* Default: unset When Exim checks the @dfn{From:} header line of locally submitted messages for matching the login id (see @dfn{local_from_check} above), it can be configured to ignore certain prefixes and suffixes in the local part of the address. This is done by setting @dfn{local_from_prefix} and/or @dfn{local_from_suffix} to appropriate lists, in the same form as the prefix and suffix options of directors (see chapter 21). For example, if @example local_from_prefix = *- @end example is set, then a @dfn{From:} line containing @example From: anything-user@@your.domain @end example will not cause a @dfn{Sender:} header to be added if @dfn{user@@your.domain} matches the actual sender address that is constructed from the login name and qualify domain. @node local_from_suffix, local_interfaces, local_from_prefix, 11[[[]]] Main configuration @findex local_from_suffix @unnumberedsubsec local_from_suffix Type: string@* Default: unset See @dfn{local_from_prefix} above. @node local_interfaces, localhost_number, local_from_suffix, 11[[[]]] Main configuration @findex local_interfaces @unnumberedsubsec local_interfaces Type: string list@* Default: unset @cindex network interfaces @cindex interfaces, network @cindex IP address: @cindex daemon The string must contain a list of IP addresses, in dotted-quad format for IPv4 addresses, or in colon-separated format (with colons doubled) for IPv6 addresses. These are used for two different purposes: @itemize @bullet @item When a daemon is started to listen for incoming SMTP calls, it listens only on the interfaces identified here, that is, @cindex IP address: binding @cindex bind IP address it calls @dfn{bind()} for these interfaces only. An error occurs if it is unable to bind a listening socket to any interface. @item @cindex loop: local host Only the IP addresses listed here are taken as the local host's addresses when routing mail and checking for mail loops. @end itemize If @dfn{local_interfaces} is unset, the daemon issues a generic @dfn{listen()} that accepts incoming calls from any interface, and it also gets a complete list of available interfaces and treats them all as local when routing mail. On most systems the default action is what is wanted. However, some systems set up large numbers of virtual interfaces in order to provide many different virtual web servers. In these cases @dfn{local_interfaces} can be used to restrict SMTP traffic to one or two interfaces only. See also @dfn{hosts_treat_as_local}. @node localhost_number, locally_caseless, local_interfaces, 11[[[]]] Main configuration @findex localhost_number @unnumberedsubsec localhost_number Type: string@* Default: unset @cindex host: locally unique number @cindex message: id Exim's message ids are normally unique only within the local host. If uniqueness among a set of hosts is required, each host must set a different value for the @dfn{localhost_number} option. The string is expanded immediately after reading the configuration file (so that a number can be computed from the host name, for example) and the result of the expansion must be a number in the range 0--255. This is available in subsequent string expansions via the variable $@dfn{localhost_number}. The final two characters of the message id, instead of just being a sequence count of the number of messages received by one process in one second, are the base 62 encoding of @example <@dfn{sequence count}> * 256 + <@dfn{local host number}> @end example This reduces the possible range of the sequence count to 0--14. If the count ever reaches 14 in a receiving process, a delay of one second is imposed to allow the clock to tick, thereby allowing the count to be reset to zero. @node locally_caseless, log_all_parents, localhost_number, 11[[[]]] Main configuration @findex locally_caseless @unnumberedsubsec locally_caseless Type: boolean@* Default: true @cindex local part: case of @cindex lower casing Domains in mail addresses are specified as being case-independent, but this it not true of local parts. For most Unix systems, however, it is desirable that local parts of local mail addresses be treated in a case-independent manner, since most users expect that mail to @dfn{OBailey} and @dfn{obailey}, for example, will end up in the same mailbox. By default, when it is processing an address whose domain is local, Exim lower-cases the local part at the start of processing, on the assumption that account names in the password file are in lower-case. For installations that want to draw case distinctions, this option is provided. When turned off, local local parts are handled verbatim during delivery. If there are names containing upper case letters in the password file, the most convenient way to provide for caseless mail delivery is to set up a @dfn{smartuser} director as the first director, and to make it do a lowercased lookup of the local part, in order to translate it to the correctly cased version, using the @dfn{new_address} option. @node log_all_parents, log_arguments, locally_caseless, 11[[[]]] Main configuration @findex log_all_parents @unnumberedsubsec log_all_parents Type: boolean@* Default: false @cindex log: all expanded addresses This option applies to deliveries of local addresses, where the original envelope address may be converted by (for example) an alias file into a `child' address which might itself be an alias. Thus in general there can be a chain of several addresses between the original one and the address to which the actual delivery is made. By default Exim logs the final address, followed by the original address in angle bracket. Turning @dfn{log_all_parents} on causes all intermediate addresses between the original envelope address and the final delivery address to be included in delivery log lines in parentheses after the first address. Without this, intermediate addresses are not included, except that if the final delivery is to a pipe or file or autoreply, the immediately preceding parent address is listed. @node log_arguments, log_file_path, log_all_parents, 11[[[]]] Main configuration @findex log_arguments @unnumberedsubsec log_arguments Type: boolean@* Default: false @cindex arguments, logging @cindex log: arguments Setting this option causes Exim to write the arguments with which it was called to the main log. This is a debugging feature, added to make it easy to find out with what arguments certain MUAs call @dfn{/usr/lib/sendmail}. The logging does not happen if Exim has given up root privilege because it was called with the -@dfn{C} or -@dfn{D} options. This facility cannot log illegal arguments, because the arguments are checked before the configuration file is read. The only way to log such cases is to interpose a script such as @dfn{util/logargs.sh} between the caller and Exim. @node log_file_path, log_incoming_port, log_arguments, 11[[[]]] Main configuration @findex log_file_path @unnumberedsubsec log_file_path Type: string list@* Default: set at compile time This option sets the path which is used to determine the names of Exim's log files, or indicates that logging is to be to @dfn{syslog}, or both. Chapter 51 contains further details. If this string is fixed at your installation (contains no expansion variables) it is recommended that you do not set this option in the configuration file, but instead supply the path using @sc{log_file_path} in @file{Local/Makefile} so that it is available to Exim for logging errors detected early on -- in particular failure to read the configuration file. If no specific path is set for the log files, they are written in a sub-directory called @dfn{log} in Exim's spool directory. @node log_incoming_port, log_ip_options, log_file_path, 11[[[]]] Main configuration @findex log_incoming_port @unnumberedsubsec log_incoming_port Type: boolean@* Default: false @cindex port: logging If this option is set, the remote port number (separated by a dot) is added to the IP address of incoming calls in all log entries, and in @dfn{Received:} header lines. For example: @example 127.0.0.1.48433 ::1.48433 @end example This is implemented by changing the value that is put in the $@dfn{sender_fullhost} and $@dfn{sender_rcvhost} variables. Recording the remote port number has become more important with the widening use of NAT (see RFC 2505). @node log_ip_options, log_level, log_incoming_port, 11[[[]]] Main configuration @findex log_ip_options @unnumberedsubsec log_ip_options Type: boolean@* Default: true See @dfn{kill_ip_options} above. @node log_level, log_queue_run_level, log_ip_options, 11[[[]]] Main configuration @findex log_level @unnumberedsubsec log_level Type: integer@* Default: 5 This controls the amount of data written to the main log and to the individual message logs (see section 51.10). The higher the number, the more is written. At present a value of 6 or higher causes all possible messages to appear. @node log_queue_run_level, log_received_recipients, log_level, 11[[[]]] Main configuration @findex log_queue_run_level @unnumberedsubsec log_queue_run_level Type: integer@* Default: 0 @cindex queue: log level for run @cindex log: level for queue run This option specifies the log level for the messages `start queue run' and `end queue run'. Setting it higher than the value of @dfn{log_level} causes them to be suppressed. @node log_received_recipients, log_received_sender, log_queue_run_level, 11[[[]]] Main configuration @findex log_received_recipients @unnumberedsubsec log_received_recipients Type: boolean@* Default: false When this option is set, the recipients of a message are listed in the main log as soon as the message is received. The list appears at the end of the log line that is written when a message is received, preceded by the word `for'. The addresses are listed after they have been qualified, but before any rewriting has taken place. @node log_received_sender, log_refused_recipients, log_received_recipients, 11[[[]]] Main configuration @findex log_received_sender @unnumberedsubsec log_received_sender Type: boolean@* Default: false If this option is set, the unrewritten original sender of a message is added to the end of the log line that records the message's arrival, after the word `from' (before the recipients if @dfn{log_received_recipients} is also set). @node log_refused_recipients, log_rewrites, log_received_sender, 11[[[]]] Main configuration @findex log_refused_recipients @unnumberedsubsec log_refused_recipients Type: boolean@* Default: false If this option is set, an entry is written in the main and reject logs for each recipient that is refused for policy reasons. Otherwise cases where all recipients are to be refused just cause a single log entry for the message. @node log_rewrites, log_sender_on_delivery, log_refused_recipients, 11[[[]]] Main configuration @findex log_rewrites @unnumberedsubsec log_rewrites Type: boolean@* Default: false @cindex rewriting: testing @cindex testing: rewriting This option causes all address rewriting to get logged, as an aid to debugging rewriting rules. [(font color=green)] @node log_sender_on_delivery, log_smtp_confirmation, log_rewrites, 11[[[]]] Main configuration @findex log_sender_on_delivery @unnumberedsubsec log_sender_on_delivery Type: boolean@* Default: false Setting @dfn{log_sender_on_delivery} causes Exim to add an @file{F=} item to delivery and bounce log lines (F is for `envelope from' -- the same letter as is used in rewriting rules). By default, the sender is not shown on these lines. [(/font)] @node log_smtp_confirmation, log_smtp_connections, log_sender_on_delivery, 11[[[]]] Main configuration @findex log_smtp_confirmation @unnumberedsubsec log_smtp_confirmation Type: boolean@* Default: false This option causes the response to the final `.' in the SMTP dialog for outgoing messages to be added to delivery log lines in the form `C="<@dfn{text}>"'. A number of MTAs (including Exim from release 1.60) return an identifying string in this response, so logging this information allows messages to be tracked more easily. This global option applies to all SMTP transports. @node log_smtp_connections, log_smtp_syntax_errors, log_smtp_confirmation, 11[[[]]] Main configuration @findex log_smtp_connections @unnumberedsubsec log_smtp_connections Type: boolean@* Default: false @cindex log: SMTP connections @cindex SMTP: logging connections This option turns on more verbose logging of incoming SMTP connections, at log level 4. This does not apply to batch SMTP, but it does apply to SMTP connections from local processes that use the -@dfn{bs} option, including incoming calls using @dfn{inetd}. A log line is written whenever a connection is established or closed. If a connection is dropped in the middle of a message, a log line is always written, but otherwise nothing is written at the start and end of connections unless @dfn{log_smtp_connections} is set. @node log_smtp_syntax_errors, log_subject, log_smtp_connections, 11[[[]]] Main configuration @findex log_smtp_syntax_errors @unnumberedsubsec log_smtp_syntax_errors Type: boolean@* Default: false @cindex SMTP: logging syntax errors @cindex SMTP: syntax errors, logging @cindex SMTP: unknown commands, logging @cindex log: unknown SMTP commands @cindex log: SMTP syntax errors If this option is set, syntax errors in incoming SMTP commands are logged at level 4. An unrecognized command is treated as a syntax error. For an external connection, the host identity is given; for an internal connection using -@dfn{bs} the sender identification (normally the calling user) is given. @node log_subject, lookup_open_max, log_smtp_syntax_errors, 11[[[]]] Main configuration @findex log_subject @unnumberedsubsec log_subject Type: boolean@* Default: false This option causes a message's subject to be included in the arrival log line, in the form `T="<@dfn{subject text}>"'. T stands for `topic' (S is already used for `size'). @node lookup_open_max, max_username_length, log_subject, 11[[[]]] Main configuration @findex lookup_open_max @unnumberedsubsec lookup_open_max Type: integer@* Default: 25 @cindex too many open files @cindex open files, too many @cindex file: too many open This option limits the number of simultaneously open lookup files. Exim normally keeps files open during directing and routing, since often the same file is required several times. This limit applies only to those lookup types which use regular files, namely lsearch, dbm, and cdb. If the limit is reached, Exim closes the least recently used file. Note that if you are using the NDBM library, it actually opens two files for each logical DBM database, though it still counts as one for the purposes of @dfn{lookup_open_max}. If you are getting `too many open files' errors with NDBM, you need to reduce the value of @dfn{lookup_open_max}. @node max_username_length, message_body_visible, lookup_open_max, 11[[[]]] Main configuration @findex max_username_length @unnumberedsubsec max_username_length Type: integer@* Default: 0 @cindex length of login name @cindex user name, maximum length Some operating systems are broken in that they truncate the argument to @dfn{getpwnam()} to eight characters, instead of returning `no such user'. If this option is set greater than zero, any attempt to call @dfn{getpwnam()} with an argument that is longer behaves as if @dfn{getpwnam()} failed. @node message_body_visible, message_filter, max_username_length, 11[[[]]] Main configuration @findex message_body_visible @unnumberedsubsec message_body_visible Type: integer@* Default: 500 @cindex body of message: visible size @cindex message: body, visible size This option specifies how much of a message's body is to be included in the @dfn{message_body} expansion variable. @node message_filter, message_filter_directory_transport, message_body_visible, 11[[[]]] Main configuration @findex message_filter @unnumberedsubsec message_filter Type: string@* Default: unset @cindex filter: system filter This option specifies a filter file which is applied to all messages before any routing or directing is done. This is called the `system message filter'. If the filter generates any deliveries to files or pipes, or any new mail messages, the appropriate @dfn{message_filter_..._transport} option(s) must be set, to define which transports are to be used. Details of this facility are given in chapter 47. @node message_filter_directory_transport, message_filter_directory2_transport, message_filter, 11[[[]]] Main configuration @findex message_filter_directory_transport @unnumberedsubsec message_filter_directory_transport Type: string@* Default: unset This sets the name of the transport driver that is to be used when the @dfn{save} command in a system message filter specifies a path ending in `/', implying delivery of each message into a separate file in some directory. @node message_filter_directory2_transport, message_filter_file_transport, message_filter_directory_transport, 11[[[]]] Main configuration @findex message_filter_directory2_transport @unnumberedsubsec message_filter_directory2_transport Type: string@* Default: unset This sets the name of the transport driver that is to be used when the @dfn{save} command in a system message filter specifies a path ending in `//'. The reason for having both @dfn{message_filter_directory} and @dfn{message_filter_directory2} is to allow for the rare circumstance in which both maildir and non-maildir format delivery is required. @node message_filter_file_transport, message_filter_group, message_filter_directory2_transport, 11[[[]]] Main configuration @findex message_filter_file_transport @unnumberedsubsec message_filter_file_transport Type: string@* Default: unset @cindex file: transport This sets the name of the transport driver that is to be used when the @dfn{save} command in a system message filter specifies a path not ending in `/'. @cindex gid: system filter @node message_filter_group, message_filter_pipe_transport, message_filter_file_transport, 11[[[]]] Main configuration @findex message_filter_group @unnumberedsubsec message_filter_group Type: string@* Default: unset This option sets the gid under which the system message filter is run. The @dfn{seteuid()} or @dfn{setresuid()} function must be available in the operating system for a temporary change to be possible. If the filter generates any pipe, file, or reply addresses, the gid under which the filter is run is used when delivering to them. Unless the string consists entirely of digits, it is looked up using @dfn{getgrnam()}, and failure causes a configuration error. If the option is not set, and either @dfn{message_filter_user} is unset or consists entirely of digits, the gid is not changed when running the filter. Otherwise the group is taken from the result of @dfn{getpwnam()}. @node message_filter_pipe_transport, message_filter_reply_transport, message_filter_group, 11[[[]]] Main configuration @findex message_filter_pipe_transport @unnumberedsubsec message_filter_pipe_transport Type: string@* Default: unset 7 @cindex pipe transport This sets the name of the transport driver that is to be used when a @dfn{pipe} command is used in a system message filter. @node message_filter_reply_transport, message_filter_user, message_filter_pipe_transport, 11[[[]]] Main configuration @findex message_filter_reply_transport @unnumberedsubsec message_filter_reply_transport Type: string@* Default: unset @cindex autoreply transport This sets the name of the transport driver that is to be used when a @dfn{mail} command is used in a system message filter. @cindex uid: system filter @node message_filter_user, message_id_header_text, message_filter_reply_transport, 11[[[]]] Main configuration @findex message_filter_user @unnumberedsubsec message_filter_user Type: string@* Default: unset This option sets the uid under which the system message filter is run. The @dfn{seteuid()} or @dfn{setresuid()} function must be available in the operating system for a temporary change to be possible. If the filter generates any pipe, file, or reply addresses, the uid under which the filter is run is used when delivering to them. Unless it consists entirely of digits, the string is looked up using @dfn{getpwnam()}, and failure causes a configuration error. If the option is not set, the uid is not changed from the Exim user (or root if there is no Exim user) when running the system filter. @node message_id_header_text, message_size_limit, message_filter_user, 11[[[]]] Main configuration @findex message_id_header_text @unnumberedsubsec message_id_header_text Type: string, expanded@* Default: unset If this variable is set, the string is expanded and used to augment the text of the @dfn{Message-id:} header that Exim creates if an incoming message does not have one. The text of this header is required by RFC 822 to take the form of an address. By default, Exim uses its internal message id as the local part, and the primary host name as the domain. If this option is set, it is expanded and provided the expansion does not yield an empty string, is is inserted into the header immediately before the @@, separated from the internal message id by a dot. Any characters that are illegal in an address are automatically converted into hyphens. This means that constructions like @dfn{$@{tod_log@}} can be used, as the spaces and colons will become hyphens. @node message_size_limit, message_size_limit_count_recipients, message_id_header_text, 11[[[]]] Main configuration @findex message_size_limit @unnumberedsubsec message_size_limit Type: integer@* Default: 0 @cindex message size limit @cindex size limit @cindex size of message This option limits the maximum size of message that Exim will process. Zero means no limit. It should be set somewhat larger than @dfn{return_size_limit} if the latter is non-zero. Incoming SMTP messages are failed with a 552 error if the limit is exceeded; locally-generated messages either get a stderr message or a delivery failure message to the sender, depending on the -@dfn{oe} setting, in the normal way. Rejection of an oversized message is logged in both the main and the reject logs. See also the generic transport option @dfn{message_size_limit}, which limits the size of message that an individual transport can process. @node message_size_limit_count_recipients, move_frozen_messages, message_size_limit, 11[[[]]] Main configuration @findex message_size_limit_count_recipients @unnumberedsubsec message_size_limit_count_recipients Type: boolean@* Default: false If this option is set, the value of @dfn{message_size_limit} is a maximum for the size of a message times the number of envelope recipients it has. For example, if @dfn{message_size_limit} is set to 10M, a message with 4 recipients can be no bigger than 2.5M, and a message with 100 recipients is limited to around 100K. @node move_frozen_messages, mysql_servers, message_size_limit_count_recipients, 11[[[]]] Main configuration @findex move_frozen_messages @unnumberedsubsec move_frozen_messages Type: boolean@* Default: false @cindex frozen messages: moving This option, which is available only if Exim has been built with the setting @example SUPPORT_MOVE_FROZEN_MESSAGES=yes @end example in @file{Local/Makefile}, causes frozen messages and their message logs to be moved from the @dfn{input} and @dfn{msglog} directories on the spool to @dfn{Finput} and @dfn{Fmsglog}. There is currently no support in Exim or the standard utilities for handling such moved messages, and they do not show up in lists generated by -@dfn{bp} or by the Exim monitor. @node mysql_servers, never_users, move_frozen_messages, 11[[[]]] Main configuration @findex mysql_servers @unnumberedsubsec mysql_servers Type: string list@* Default: unset This option provides a list of MySQL servers and associated connection data, to be used in conjunction with @dfn{mysql} lookups (see section 6.12). The option is available only if Exim has been built with MySQL support. @node never_users, nobody_group, mysql_servers, 11[[[]]] Main configuration @findex never_users @unnumberedsubsec never_users Type: string list@* Default: unset Local mail deliveries are run in processes that are setuid to the recipient. However, it is usually desirable to lock out root from this, as a safety precaution. If a message is to be delivered locally as any of the users on the @dfn{never_users} list, the process is run as `nobody' instead (see @dfn{nobody_user} below). A common example is @example never_users = root:daemon:bin:exim @end example This option overrides the @dfn{pipe_as_creator} option of the @dfn{pipe} transport driver. If Exim is unable to find a uid for `nobody', it panics. @node nobody_group, nobody_user, never_users, 11[[[]]] Main configuration @findex nobody_group @unnumberedsubsec nobody_group Type: string@* Default: unset This specifies the group to use when a process is to be run as `nobody'. If it is unset, the value of the `nobody' user's default group is used. @node nobody_user, percent_hack_domains, nobody_group, 11[[[]]] Main configuration @findex nobody_user @unnumberedsubsec nobody_user Type: string@* Default: unset This specifies the user to use when a process is to be run as `nobody'. If it is unset, Exim looks up the user `nobody' using @dfn{getpwnam()}. If this fails, Exim panics, writing a message to the panic log and exiting immediately. @node percent_hack_domains, perl_at_start, nobody_user, 11[[[]]] Main configuration @findex percent_hack_domains @unnumberedsubsec percent_hack_domains Type: domain list@* Default: unset @cindex `percent hack' @cindex source routing: in email address @cindex address: source-routed The `percent hack' is the convention whereby a local part containing a percent sign is re-interpreted as a remote address, with the percent replaced by @@. This is sometimes called `source routing', though that term is also applied to RFC 822 addresses that begin with an @@ character. If this option is set, Exim implements the percent facility for those local domains listed, but no others. The option can be set to `*' to allow the percent hack for all local domains. If options are set to control message relaying from incoming SMTP envelopes, they are also applied to relaying that is requested via the `percent hack'. See section 46.4. @node perl_at_start, perl_startup, percent_hack_domains, 11[[[]]] Main configuration @findex perl_at_start @unnumberedsubsec perl_at_start Type: boolean@* Default: false This option is available only when Exim is built with an embedded Perl interpreter. See chapter 10 for details of its use. @node perl_startup, pgsql_servers, perl_at_start, 11[[[]]] Main configuration @findex perl_startup @unnumberedsubsec perl_startup Type: string@* Default: unset This option is available only when Exim is built with an embedded Perl interpreter. See chapter 10 for details of its use. @node pgsql_servers, pid_file_path, perl_startup, 11[[[]]] Main configuration @findex pgsql_servers @unnumberedsubsec pgsql_servers Type: string list@* Default: unset This option provides a list of PostgreSQL servers and associated connection data, to be used in conjunction with @dfn{pgsql} lookups (see section 6.12). The option is available only if Exim has been built with PostgreSQL support. @node pid_file_path, preserve_message_logs, pgsql_servers, 11[[[]]] Main configuration @findex pid_file_path @unnumberedsubsec pid_file_path Type: string@* Default: set at compile time This option sets the path which is used to determine the name of the file to which the Exim daemon writes its process id. The string is expanded, so it can contain, for example, references to the host name. After expansion it must contain the string `%s' somewhere within it; this will be replaced by the null string or a non-standard port number to form the final file name. For example, @example pid_file_path = /var/log/$@{primary_hostname@}/exim%s.pid @end example If no specific path is set for the file, it is written in Exim's spool directory. @node preserve_message_logs, primary_hostname, pid_file_path, 11[[[]]] Main configuration @findex preserve_message_logs @unnumberedsubsec preserve_message_logs Type: boolean@* Default: false If this option is set, message log files are not deleted when messages are completed. Instead, they are moved to a sub-directory of the spool directory called @dfn{msglog.OLD}, where they remain available for statistical or debugging purposes. This is a dangerous option to set on systems with any appreciable volume of mail. Use with care! @node primary_hostname, print_topbitchars, preserve_message_logs, 11[[[]]] Main configuration @findex primary_hostname @unnumberedsubsec primary_hostname Type: string@* Default: see below This specifies the name of the current host. This is used in the @sc{helo} command for outgoing SMTP messages, and as the default for @dfn{qualify_domain}. If it is not set, Exim calls @dfn{uname()} to find it. If this fails, Exim panics and dies. If the name returned by @dfn{uname()} contains only one component, Exim passes it to @dfn{gethostbyname()} in order to obtain the fully qualified version. @node print_topbitchars, prod_requires_admin, primary_hostname, 11[[[]]] Main configuration @findex print_topbitchars @unnumberedsubsec print_topbitchars Type: boolean@* Default: false @cindex printing characters @cindex 8-bit characters @cindex top bit @cindex character code By default, Exim considers only those characters whose codes lie in the range 32--126 to be printing characters. In a number of circumstances (for example, when writing log entries) non-printing characters are converted into escape sequences, primarily to avoid messing up the layout. If @dfn{print_topbitchars} is set, code values of 128 and above are also considered to be printing characters. @node prod_requires_admin, prohibition_message, print_topbitchars, 11[[[]]] Main configuration @findex prod_requires_admin @unnumberedsubsec prod_requires_admin Type: boolean@* Default: true The -@dfn{M}, -@dfn{R}, and -@dfn{q} command-line options require the caller to be an admin user unless @dfn{prod_requires_admin} is set false. See also @dfn{queue_list_requires_admin}. @node prohibition_message, qualify_domain, prod_requires_admin, 11[[[]]] Main configuration @findex prohibition_message @unnumberedsubsec prohibition_message Type: string, expanded@* Default: unset This option adds a site-specific message to the error response that is sent when an SMTP command fails for policy reasons, for example if the sending host is in a host reject list. Details of this facility are given in chapter 46. @node qualify_domain, qualify_recipient, prohibition_message, 11[[[]]] Main configuration @findex qualify_domain @unnumberedsubsec qualify_domain Type: string@* Default: see below This specifies the domain name that is added to any sender addresses that do not have a domain qualification. It also applies to recipient addresses if @dfn{qualify_recipient} is not set. Such addresses are accepted by default only for locally-generated messages -- messages from external sources must always contain fully qualified addresses, unless the sending host matches one of the @dfn{receiver_unqualified} or @dfn{sender_unqualified} options. If @dfn{qualify_domain} is not set, it defaults to the @dfn{primary_hostname} value. @node qualify_recipient, queue_list_requires_admin, qualify_domain, 11[[[]]] Main configuration @findex qualify_recipient @unnumberedsubsec qualify_recipient Type: string@* Default: see below This specifies the domain name that is added to any recipient addresses that do not have a domain qualification. Such addresses are accepted by default only for locally-generated messages -- messages from external sources must always contain fully qualified addresses, unless the sending host matches one of the @dfn{receiver_unqualified} or @dfn{sender_unqualified} options (see below). If @dfn{qualify_recipient} is not set, it defaults to the @dfn{qualify_domain} value. @node queue_list_requires_admin, queue_only, qualify_recipient, 11[[[]]] Main configuration @findex queue_list_requires_admin @unnumberedsubsec queue_list_requires_admin Type: boolean@* Default: true The -@dfn{bp} command-line option requires the caller to be an admin user unless @dfn{queue_list_requires_admin} is set false. Otherwise, only messages that the caller submitted are displayed. See also @dfn{prod_requires_admin}. @node queue_only, queue_only_file, queue_list_requires_admin, 11[[[]]] Main configuration @findex queue_only @unnumberedsubsec queue_only Type: boolean@* Default: false @cindex queueing incoming messages @cindex message: queueing If @dfn{queue_only} is set (which is equivalent to the -@dfn{odq} command line option), a delivery process is not automatically started whenever a message has been received. Instead, the message waits on the queue for the next queue run. Even if @dfn{queue_only} is false, incoming SMTP messages may not get delivered immediately if a lot of them arrive at once -- see the @dfn{queue_only_load} and @dfn{smtp_accept_queue} options. @node queue_only_file, queue_only_load, queue_only, 11[[[]]] Main configuration @findex queue_only_file @unnumberedsubsec queue_only_file Type: string@* Default: unset @cindex queueing incoming messages @cindex message: queueing This option can be set to a colon-separated list of absolute path names, each one optionally preceded by `remote' or `smtp'. When it is receiving a message, Exim tests for the existence of each listed path using a call to @dfn{stat()}, and if this succeeds, the corresponding queuing option is set. If there is no prefix to the path, @dfn{queue_only} is set; `remote' corresponds to @dfn{queue_remote_domains} and `smtp' to @dfn{queue_smtp_domains}. So, for example, @example queue_only_file = remote/some/file @end example causes Exim to behave as if @dfn{queue_remote_domains} were set to `*' whenever @dfn{/some/file} exists. @node queue_only_load, queue_remote_domains, queue_only_file, 11[[[]]] Main configuration @findex queue_only_load @unnumberedsubsec queue_only_load Type: fixed-point@* Default: unset @cindex load average @cindex queueing incoming messages @cindex message: queueing If the system load average is higher than this value, all incoming messages are queued, and no automatic deliveries are started. If this happens during local or remote SMTP input, all subsequent messages on the same connection are queued. Deliveries will subsequently be performed by queue running processes, unless the load is higher than @dfn{deliver_load_max}. There are some operating systems for which Exim cannot determine the load average (see chapter 1); for these this option has no effect. See also @dfn{smtp_accept_queue} and @dfn{smtp_load_reserve}. @node queue_remote_domains, queue_run_in_order, queue_only_load, 11[[[]]] Main configuration @findex queue_remote_domains @unnumberedsubsec queue_remote_domains Type: domain list@* Default: unset This option lists domains for which local delivery is not immediately required. It is checked against the domains supplied in the incoming addresses, before any widening is done (because that is part of routing). The -@dfn{odqr} option is equivalent to setting @dfn{queue_remote_domains} to `*'. A delivery process is started whenever a message is received, but only local addresses are handled, and only local deliveries take place. All remote deliveries wait until the next queue run. See also @dfn{queue_smtp_domains}, which is subtly different. @node queue_run_in_order, queue_run_max, queue_remote_domains, 11[[[]]] Main configuration @findex queue_run_in_order @unnumberedsubsec queue_run_in_order Type: boolean@* Default: false If this option is set, queue runs happen in order of message arrival instead of in an arbitrary order. In order for this to happen, a complete list of the entire queue must be set up before the deliveries start. When the queue is all in a single directory (the default), this happens anyway, but if @dfn{split_spool_directory} is set it does not -- for delivery in random order, the sub-directories are processed one at a time (in random order), to avoid setting up one huge list. Thus, setting @dfn{queue_run_in_order} with @dfn{split_spool_directory} may degrade performance when the queue is large. In most situations, @dfn{queue_run_in_order} should not be set. @node queue_run_max, queue_smtp_domains, queue_run_in_order, 11[[[]]] Main configuration @findex queue_run_max @unnumberedsubsec queue_run_max Type: integer@* Default: 5 @cindex queue-runners, maximum number of This controls the maximum number of queue-running processes that an Exim daemon will run simultaneously. This does not mean that it starts them all at once, but rather that if the maximum number are still running when the time comes to start another one, it refrains from starting it. This can happen with very large queues and/or very sluggish deliveries. This option does not, however, interlock with other processes, so additional queue-runners can be started by other means, or by killing and restarting the daemon. @node queue_smtp_domains, rbl_domains, queue_run_max, 11[[[]]] Main configuration @findex queue_smtp_domains @unnumberedsubsec queue_smtp_domains Type: domain list@* Default: unset When this option is set, a delivery process is started whenever a message is received, directing and routing is performed, and local deliveries take place. However, if any SMTP deliveries are required for domains that match @dfn{queue_smtp_domains}, they are not immediately delivered, but instead the message waits on the queue for the next queue run. Since routing of the message has taken place, Exim knows to which remote hosts it must be delivered, and so when the queue run happens, multiple messages for the same host are delivered over a single SMTP connection. This option is checked against the domains supplied in the incoming addresses, before any widening is done (because that is part of routing). The -@dfn{odqs} command line option causes all SMTP deliveries to be queued in this way, and is equivalent to setting @dfn{queue_smtp_domains} to `*'. See also @dfn{queue_remote_domains}, which is subtly different. @node rbl_domains, rbl_hosts, queue_smtp_domains, 11[[[]]] Main configuration @findex rbl_domains @unnumberedsubsec rbl_domains Type: string list@* Default: unset @cindex RBL @cindex realtime blocking list This option is part of the support for Realtime Blackhole Lists (RBL). It can be set to a colon-separated list of DNS domains in which to look up the IP address of a calling host. A full description of how this is used is given in section 46.1. @node rbl_hosts, rbl_log_headers, rbl_domains, 11[[[]]] Main configuration @findex rbl_hosts @unnumberedsubsec rbl_hosts Type: host list@* Default: * @cindex exceptions: RBL checking This option specifies the set of hosts for which RBL checking is to be performed when @dfn{rbl_domains} is set. The default matches all hosts. The normal usage of this option is to specify exceptions to RBL checking by means of negated items in the host list. @node rbl_log_headers, rbl_log_rcpt_count, rbl_hosts, 11[[[]]] Main configuration @findex rbl_log_headers @unnumberedsubsec rbl_log_headers Type: boolean@* Default: false When this option is set, the headers of each message received from a host that matches an RBL domain are written to the reject log. This can occur only if the recipients of the message are not rejected, that is, if the RBL check is configured to warn only. @node rbl_log_rcpt_count, rbl_reject_recipients, rbl_log_headers, 11[[[]]] Main configuration @findex rbl_log_rcpt_count @unnumberedsubsec rbl_log_rcpt_count Type: boolean@* Default: false When this option is set and @dfn{rbl_reject_recipients} is false, the number of @sc{rcpt} commands for each message received from a host that is in the RBL is written to the reject log. This may be greater than the number of valid recipients in the message. @node rbl_reject_recipients, rbl_warn_header, rbl_log_rcpt_count, 11[[[]]] Main configuration @findex rbl_reject_recipients @unnumberedsubsec rbl_reject_recipients Type: boolean@* Default: true This option controls the action taken when a remote host is found in an RBL domain that has neither `/warn' nor `/reject' following it. The default value specifies rejection. @node rbl_warn_header, received_header_text, rbl_reject_recipients, 11[[[]]] Main configuration @findex rbl_warn_header @unnumberedsubsec rbl_warn_header Type: boolean@* Default: true When this option is set and a message from an RBL-matching host is not rejected, an @dfn{X-RBL-Warning:} header is added. The header contains the contents of the DNS TXT record, if one was found. Scanning of further RBL domains continues, which means that more than one @dfn{X-RBL-Warning:} header may be added to a message. @cindex customizing: Received: header @node received_header_text, received_headers_max, rbl_warn_header, 11[[[]]] Main configuration @findex received_header_text @unnumberedsubsec received_header_text Type: string, expanded@* Default: see below This string defines the contents of the @dfn{Received:} message header that is added to each message, except for the timestamp, which is automatically added on at the end, preceded by a semicolon. The string is expanded each time it is used, and the default is: @example received_header_text = "Received: \ $@{if def:sender_rcvhost @{from $@{sender_rcvhost@}\n\t@}\ @{$@{if def:sender_ident @{from $@{sender_ident@} @}@}\ $@{if def:sender_helo_name @{(helo=$@{sender_helo_name@})\n\t@}@}@}@}\ by $@{primary_hostname@} \ $@{if def:received_protocol @{with $@{received_protocol@}@}@} \ $@{if def:tls_cipher @{($tls_cipher)\n\t@}@}\ (Exim $@{version_number@} #$@{compile_number@})\n\t\ id $@{message_id@}\ $@{if def:received_for @{\n\tfor $received_for@}@}" @end example Note the use of quotes, to allow the sequences @file{\n} and @file{\t} to be used for newlines and tabs, respectively. The reference to the TLS cipher is omitted when Exim is built without TLS support. The use of conditional expansions ensures that this works for both locally generated messages and messages received from remote hosts, giving header lines such as the following: @example Received: from scrooge.carol.book ([240.1.12.25] ident=root) by marley.carol.book with smtp (Exim 3.30 #1) id E0tS3Ga-0005C5-00 for cratchit@@dickens.book; Mon, 25 Dec 2000 14:43:44 +0000 Received: by scrooge.carol.book with local (Exim 3.30 #1) id E0tS3GW-0005C2-00; Mon, 25 Dec 2000 14:43:41 +0000 @end example Note the automatic addition of the date and time in the required format. @node received_headers_max, receiver_try_verify, received_header_text, 11[[[]]] Main configuration @findex received_headers_max @unnumberedsubsec received_headers_max Type: integer@* Default: 30 @cindex loop: prevention @cindex mail loop prevention When a message is to be delivered, the number of @dfn{Received:} headers is counted, and if it is greater than this parameter, a mail loop is assumed to have occurred, the delivery is abandoned, and an error message is generated. This applies to both local and remote deliveries. Earlier versions of Exim did this test only for remote deliveries, but because local deliveries (as Exim sees them) may in fact still cause a message to be transported to a remote host, it was changed. @node receiver_try_verify, receiver_unqualified_hosts, received_headers_max, 11[[[]]] Main configuration @findex receiver_try_verify @unnumberedsubsec receiver_try_verify Type: boolean@* Default: false See @dfn{receiver_verify}. @node receiver_unqualified_hosts, receiver_verify, receiver_try_verify, 11[[[]]] Main configuration @findex receiver_unqualified_hosts @unnumberedsubsec receiver_unqualified_hosts Type: host list@* Default: unset @cindex unqualified addresses This option lists those hosts from which Exim is prepared to accept unqualified receiver addresses in message envelopes. The addresses are made fully qualified by the addition of the @dfn{qualify_recipient} value. Typically the hosts are local ones, but if you want to imitate the behaviour of mailers that accept unqualified addresses from anywhere, specify @example receiver_unqualified_hosts = * @end example This option also affects message header lines. Exim does not reject unqualified receiver addresses in headers, but qualifies them only if the message came from a host that matches @dfn{receiver_unqualified_hosts}. @node receiver_verify, receiver_verify_addresses, receiver_unqualified_hosts, 11[[[]]] Main configuration @findex receiver_verify @unnumberedsubsec receiver_verify Type: boolean@* Default: false @cindex verifying: receivers When this option is set, the addresses of recipients received from a remote host are verified as they are received, provided the sending host matches @dfn{receiver_verify_hosts}, the incoming address matches @dfn{receiver_verify_addresses}, and the sender address matches @dfn{receiver_verify_senders}, if either of the last two are set. If an address is invalid, an incoming SMTP call gets an error response to the @sc{rcpt} command. If an address cannot immediately be verified, a temporary error code is given. The @dfn{receiver_try_verify} option is less severe: it operates in the same way, except that an address is accepted if it cannot immediately be verified. Verification failures are logged. @node receiver_verify_addresses, receiver_verify_hosts, receiver_verify, 11[[[]]] Main configuration @findex receiver_verify_addresses @unnumberedsubsec receiver_verify_addresses Type: address list@* Default: unset If set, this option restricts receiver verification to those addresses it matches. The option is inspected only if @dfn{receiver_verify} or @dfn{receiver_try_verify} is set. @node receiver_verify_hosts, receiver_verify_senders, receiver_verify_addresses, 11[[[]]] Main configuration @findex receiver_verify_hosts @unnumberedsubsec receiver_verify_hosts Type: host list@* Default: * See @dfn{receiver_verify} above. @node receiver_verify_senders, recipients_max, receiver_verify_hosts, 11[[[]]] Main configuration @findex receiver_verify_senders @unnumberedsubsec receiver_verify_senders Type: address list@* Default: unset This option, if set, allows receiver verification to be conditional upon the sender. It is inspected only if @dfn{receiver_verify} or @dfn{receiver_try_verify} is set. If the null sender is required in the list of addresses, it must not be the last item, as a null last item in a list is ignored. It is best placed at the start of the list. For example, to restrict receiver verification to messages with null senders and senders in the @dfn{.com} and @dfn{.org} domains, you could have @example receiver_verify receiver_verify_senders = :*.com:*.org @end example If the null sender is the only entry required, the list should consist of a single colon. @node recipients_max, recipients_max_reject, receiver_verify_senders, 11[[[]]] Main configuration @findex recipients_max @unnumberedsubsec recipients_max Type: integer@* Default: 0 @cindex maximum recipients @cindex recipients: maximum If this is set greater than zero, it specifies the maximum number of recipients for any message. This applies to the original list of recipients supplied with the message. SMTP messages get a 452 response for all recipients over the limit; earlier recipients are delivered as normal. Non-SMTP messages with too many recipients are failed, and no deliveries are done. Note that the RFCs specify that an SMTP server should accept at least 100 @sc{rcpt} commands in a single message. @node recipients_max_reject, recipients_reject_except, recipients_max, 11[[[]]] Main configuration @findex recipients_max_reject @unnumberedsubsec recipients_max_reject Type: boolean@* Default: false If this option is set true, Exim rejects SMTP messages containing too many recipients by giving 552 errors to the surplus @sc{rcpt} commands, and a 554 error to the eventual @sc{data} command. Otherwise (the default) it gives a 452 error to the surplus @sc{rcpt} commands and accepts the message on behalf of the initial set of recipients. The remote server should then re-send the message for the remaining recipients at a later time. @node recipients_reject_except, recipients_reject_except_senders, recipients_max_reject, 11[[[]]] Main configuration @findex recipients_reject_except @unnumberedsubsec recipients_reject_except Type: address list@* Default: unset @cindex exceptions: rejected recipients This option lists recipient addresses which are exceptions to any policy for recipient rejection, that is, as a result of @dfn{sender_reject_recipients}, etc. This option is entirely independent of any checks for unwanted message relaying. However, it does interact with the RBL options. @node recipients_reject_except_senders, refuse_ip_options, recipients_reject_except, 11[[[]]] Main configuration @findex recipients_reject_except_senders @unnumberedsubsec recipients_reject_except_senders Type: address list@* Default: unset This option lists sender addresses for which recipients are excepted from any policy rejections. That is, if a message comes from any of these senders, all its recipients are excepted from policy rejections. @node refuse_ip_options, relay_domains, recipients_reject_except_senders, 11[[[]]] Main configuration @findex refuse_ip_options @unnumberedsubsec refuse_ip_options Type: boolean@* Default: true See @dfn{kill_ip_options} above. @node relay_domains, relay_domains_include_local_mx, refuse_ip_options, 11[[[]]] Main configuration @findex relay_domains @unnumberedsubsec relay_domains Type: domain list@* Default: unset This option lists domains for which the local host is prepared to relay. See section 46.4 for details of relay control. @node relay_domains_include_local_mx, relay_match_host_or_sender, relay_domains, 11[[[]]] Main configuration @findex relay_domains_include_local_mx @unnumberedsubsec relay_domains_include_local_mx Type: boolean@* Default: false This option permits any host to relay to any domain that has an MX record pointing at the local host. It causes any domain with an MX record pointing at the local host to be treated as if it were in @dfn{relay_domains}. See section 46.4 for details of relay control. @node relay_match_host_or_sender, remote_max_parallel, relay_domains_include_local_mx, 11[[[]]] Main configuration @findex relay_match_host_or_sender @unnumberedsubsec relay_match_host_or_sender Type: boolean@* Default: false By default, if relaying controls are specified on both the remote host and the sender address, a message is accepted only if both conditions are met. If @dfn{relay_match_host_or_sender} is set, either condition is good enough. It does not make sense to set this option without setting @dfn{sender_address_relay}, since if that option is unset it matches all senders. Exim therefore diagnoses a configuration error in this case. See section 46.4 for details of relay control. @node remote_max_parallel, remote_sort, relay_match_host_or_sender, 11[[[]]] Main configuration @findex remote_max_parallel @unnumberedsubsec remote_max_parallel Type: integer@* Default: 1 This option controls parallel delivery to remote sites. If the value is less than 2, parallel delivery is disabled, and Exim does all the remote deliveries for a message one by one, from a single delivery process. Otherwise, if a message has to be delivered to more than one remote host, or if several copies have to be sent to the same remote host, then up to @dfn{remote_max_parallel} deliveries are done simultaneously, each in a separate process. If more than @dfn{remote_max_parallel} deliveries are required, the maximum number of processes are started, and as each one finishes, another is begun. The order of starting processes is the same as if sequential delivery were being done, and can be controlled by the @dfn{remote_sort} option. If parallel delivery takes place while running with debugging turned on, the debugging output from each delivery process is tagged with its process id. The overhead in doing this is a fork to set up a separate process for each delivery, and the associated management of the subprocess (including getting back the result of the delivery attempt). As well as the process overhead, there may be a small additional penalty paid for parallel delivery. If a host is found to be down, this fact cannot be communicated to any deliveries that are running in parallel, though it will be passed on to any that start afterwards. This is no worse than if there were two separate messages being delivered simultaneously. The option controls only the maximum number of parallel deliveries from one Exim process. Since Exim has no central queue manager, there is no way of controlling the total number of simultaneous deliveries if the configuration allows a delivery attempt as soon as a message is received. @cindex number of deliveries @cindex deliveries, maximum number of If you want to control the total number of deliveries on the system, you need to set the @dfn{queue_only} option, which ensures that all incoming messages are simply added to the queue. Then set up an Exim daemon to start queue runner processes at appropriate intervals (probably fairly often, for example, every minute), and limit the total number of queue runners by setting the @dfn{queue_run_max} parameter. Because each queue runner delivers only one message at a time, the maximum number of deliveries that can then take place at once is @dfn{queue_run_max} multiplied by @dfn{remote_max_parallel}. If it is purely remote deliveries you want to control, use @dfn{queue_smtp} instead of @dfn{queue_only}. This has the added benefit of doing the SMTP routing before queuing, so that several messages for the same host will eventually get delivered down the same connection. @node remote_sort, retry_data_expire, remote_max_parallel, 11[[[]]] Main configuration @findex remote_sort @unnumberedsubsec remote_sort Type: domain list@* Default: unset @cindex sorting remote deliveries @cindex delivery: sorting remote When there are a number of remote deliveries for a message, they are sorted by domain into the order given by this list. For example, @example remote_sort = *.cam.ac.uk:*.uk @end example would attempt to deliver to all addresses in the @dfn{cam.ac.uk} domain first, then to those in the @dfn{uk} domain, then to any others. @node retry_data_expire, retry_interval_max, remote_sort, 11[[[]]] Main configuration @findex retry_data_expire @unnumberedsubsec retry_data_expire Type: time@* Default: 7d This option sets a `use before' time on retry information in Exim's hints database. Any older retry data is ignored. This means that, for example, once a host has not been tried for 7 days, Exim behaves as if it has no knowledge of past failures. @node retry_interval_max, return_path_remove, retry_data_expire, 11[[[]]] Main configuration @findex retry_interval_max @unnumberedsubsec retry_interval_max Type: time@* Default: 24h Chapter 33 describes Exim's mechanisms for controlling the intervals between delivery attempts for messages that cannot be delivered straight away. This option sets an overall limit to the length of time between retries. @node return_path_remove, return_size_limit, retry_interval_max, 11[[[]]] Main configuration @findex return_path_remove @unnumberedsubsec return_path_remove Type: boolean@* Default: true @cindex Return-path: header RFC 822 states that the @dfn{Return-path:} header is `added by the final transport system that delivers the message to its recipient' (section 4.3.1), which implies that this header should not be present in an incoming message, where the return path is carried in the envelope. If this option is true, any existing @dfn{Return-path:} headers are removed from messages as they are read. Exim's transports have options for adding @dfn{Return-path:} headers at the time of delivery. They are normally used only for final local deliveries. @node return_size_limit, rfc1413_hosts, return_path_remove, 11[[[]]] Main configuration @findex return_size_limit @unnumberedsubsec return_size_limit Type: integer@* Default: 100K @cindex message size limit @cindex size limit of bounce @cindex size of message @cindex delivery: failure report This option sets a limit in bytes on the size of messages that are returned to senders. If it is set to zero there is no limit. If the body of any message that is to be included in an error report is greater than the limit, it is truncated, and a comment pointing this out is added at the top. The actual cutoff may be greater than the value given, owing to the use of buffering for transferring the message in chunks. The idea is just to save bandwidth on those undeliverable 15-megabyte messages. If either the global or generic transport @dfn{message_size_limit} is set, the value of @dfn{return_size_limit} should be somewhat smaller. @node rfc1413_hosts, rfc1413_query_timeout, return_size_limit, 11[[[]]] Main configuration @findex rfc1413_hosts @unnumberedsubsec rfc1413_hosts Type: host list@* Default: * @cindex RFC 1413 @cindex ident RFC 1413 identification calls are made to any host which matches an item in the list. The items in the host list should not themselves contain ident data. @node rfc1413_query_timeout, security, rfc1413_hosts, 11[[[]]] Main configuration @findex rfc1413_query_timeout @unnumberedsubsec rfc1413_query_timeout Type: time@* Default: 30s This sets the timeout on RFC 1413 identification calls. If it is set to zero, no RFC 1413 calls are ever made. @node security, sender_address_relay, rfc1413_query_timeout, 11[[[]]] Main configuration @findex security @unnumberedsubsec security Type: string@* Default: see below When @dfn{exim_user} is set non-zero in the run time configuration or an Exim uid is compiled into the binary, Exim gives up root privilege for some of the time. As there are trade-offs between increased security and efficiency, this option is provided to control exactly how this is done. The option can be set to one of the strings `seteuid', `setuid', `setuid+seteuid' or `unprivileged', provided that a uid for Exim is defined. Otherwise it must be left unset. A full description of what these values mean is given in chapter 55. The default for this option is unset if no special Exim uid is defined, otherwise it is either `setuid+seteuid' or `setuid', depending on whether the @dfn{seteuid()} function is configured as being available or not. @node sender_address_relay, sender_address_relay_hosts, security, 11[[[]]] Main configuration @findex sender_address_relay @unnumberedsubsec sender_address_relay Type: address list@* Default: unset This option specifies a set of address patterns, one of which the sender of a message must match in order for the message to be accepted for [(font color=green)] outgoing relaying, that is, relaying from specified hosts to arbitrary domains. The check does not operate for incoming relaying, that is, for addresses that match @dfn{relay_domains}. [(/font)] If this option is not set, all sender addresses are permitted. By default, the check operates in addition to any relaying checks on the sending host (see @dfn{host_accept_relay} above). However, if @dfn{relay_match_host_or_sender} is set, @dfn{either} a host match @dfn{or} a sender match is sufficient to allow the relaying to proceed. For this reason, @dfn{sender_address_relay} is required to be set if @dfn{relay_match_host_or_sender} is set. [(b)]Warning[(/b)]: Sender addresses can be trivially forged. For this reason, setting @dfn{relay_match_host_or_sender} is strongly discouraged. The rewrite flag X (see section 34.9) provides a special-purpose facility we have a use for in Cambridge. It adds additional checking to @dfn{sender_address_relay}. Whenever a sender address passes the check, if there are any rewriting rules with the X flag set, the address is rewritten using those rules, and if this makes any change to the address, the new address must verify successfully for the relaying to be permitted. @node sender_address_relay_hosts, sender_reject, sender_address_relay, 11[[[]]] Main configuration @findex sender_address_relay_hosts @unnumberedsubsec sender_address_relay_hosts Type: host list@* Default: * The hosts to which @dfn{sender_address_relay} is applied can be controlled by this option. This is useful in a cluster where one host is delegated as a fallback to hold all the delayed deliveries. It needs to be able to relay from the other hosts without sender checking (for example, for messages forwarded by local users) but might want to check senders in messages relayed from other hosts. @node sender_reject, sender_reject_recipients, sender_address_relay_hosts, 11[[[]]] Main configuration @findex sender_reject @unnumberedsubsec sender_reject Type: address list@* Default: unset This option can be set in order to reject mail from certain senders. The check is done on the sender's address as given in the @sc{mail} command in SMTP, but not for local senders where the logged-in user's address is going to override anyway. The check is not done for batch SMTP input. If the check fails, a 550 return code is given to @sc{mail}. This doesn't always stop remote mailers from trying again. See @dfn{sender_reject_recipients} for an alternative. Typical examples of the use of this option might be: @example sender_reject = spamuser@@some.domain:spam.domain sender_reject = partial-dbm;/etc/mail/blocked/senders @end example Note that this check operates on sender address domains independently of the sending host; @dfn{host_reject} can be used to block all mail from particular hosts, while @dfn{host_accept_relay}, and @dfn{sender_address_relay} can be used to prevent unwanted relaying. @node sender_reject_recipients, sender_try_verify, sender_reject, 11[[[]]] Main configuration @findex sender_reject_recipients @unnumberedsubsec sender_reject_recipients Type: address list@* Default: unset This operates in exactly the same way as @dfn{sender_reject} except that the rejection is given in the form of a 550 error code to every @sc{rcpt} command instead of rejecting @sc{mail}. This seems to be the only way of saying `no' to some mailers. Note that this is not an option for rejecting specific recipients. The way to do that is to set @dfn{receiver_verify} and arrange for those recipients to fail verification. @node sender_try_verify, sender_unqualified_hosts, sender_reject_recipients, 11[[[]]] Main configuration @findex sender_try_verify @unnumberedsubsec sender_try_verify Type: boolean@* Default: false See @dfn{sender_verify}. @node sender_unqualified_hosts, sender_verify, sender_try_verify, 11[[[]]] Main configuration @findex sender_unqualified_hosts @unnumberedsubsec sender_unqualified_hosts Type: host list@* Default: unset @cindex unqualified addresses This option lists those hosts from which Exim is prepared to accept unqualified sender addresses. The addresses are made fully qualified by the addition of @dfn{qualify_domain}. Typically the hosts are local ones, but if you want to imitate the behaviour of mailers that accept unqualified addresses from anywhere, specify @example sender_unqualified_hosts = * @end example This option also affects message header lines. Exim does not reject unqualified addresses in headers containing sender addresses, but qualifies them only if the message came from a host that matches @dfn{sender_unqualified_hosts}. @node sender_verify, sender_verify_batch, sender_unqualified_hosts, 11[[[]]] Main configuration @findex sender_verify @unnumberedsubsec sender_verify Type: boolean@* Default: false @cindex verifying: senders @cindex sender: verification If this option is true, envelope sender addresses on incoming SMTP messages are checked to ensure that they are valid. Messages with invalid envelope senders are rejected with a permanent error code if @dfn{sender_verify_reject} is set (the default). Otherwise a warning is logged. See section 45.2 for details of the rejection, which can happen at three different points in the SMTP dialogue. If a sender cannot immediately be verified, a temporary error code is returned after reading the data (so the headers can be logged). The @dfn{sender_try_verify} option is less severe: it operates in exactly the same way as @dfn{sender_verify} except that if an address cannot immediately be verified, it is accepted instead of being temporarily rejected. @node sender_verify_batch, sender_verify_callback_domains, sender_verify, 11[[[]]] Main configuration @findex sender_verify_batch @unnumberedsubsec sender_verify_batch Type: boolean@* Default: false If this option is unset, the @dfn{sender_verify} options are not applied to batched SMTP input. [(font color=green)] @cindex verifying: sender callback @cindex callback for verification @node sender_verify_callback_domains, sender_verify_callback_timeout, sender_verify_batch, 11[[[]]] Main configuration @findex sender_verify_callback_domains @unnumberedsubsec sender_verify_callback_domains Type: domain list@* Default: unset When a sender address is being verified, an SMTP `callback' to one of the hosts that handle mail for its domain occurs if the sender's domain matches @dfn{sender_verify_callback_domains} and the sending host matches @dfn{sender_verify_hosts_callback} (in addition to @dfn{sender_verify_hosts}). See section 45.3 for details. @node sender_verify_callback_timeout, sender_verify_fixup, sender_verify_callback_domains, 11[[[]]] Main configuration @findex sender_verify_callback_timeout @unnumberedsubsec sender_verify_callback_timeout Type: time@* Default: 30s This option specifies a timeout for sender verification callbacks. [(/font)] @node sender_verify_fixup, sender_verify_hosts, sender_verify_callback_timeout, 11[[[]]] Main configuration @findex sender_verify_fixup @unnumberedsubsec sender_verify_fixup Type: boolean@* Default: false @cindex verifying: senders Experience shows that many messages are sent out onto the Internet with invalid sender addresses in the envelopes (that is, in the @sc{mail} command of the SMTP dialogue), but with valid addresses in the @dfn{Sender:}, @dfn{From:}, or @dfn{Reply-To:} header fields. If @dfn{sender_verify} and @dfn{sender_verify_reject} are true and this option is also true, an invalid envelope sender or one that cannot immediately be verified is replaced by a valid value from the headers. If @dfn{sender_verify_reject} is false, the envelope sender is not changed, but Exim writes a log entry giving the correction it would have made. See chapter 45 for details. @node sender_verify_hosts, sender_verify_hosts_callback, sender_verify_fixup, 11[[[]]] Main configuration @findex sender_verify_hosts @unnumberedsubsec sender_verify_hosts Type: host list@* Default: * @cindex verifying: senders If @dfn{sender_verify} or @dfn{sender_try_verify} is true, this option specifies a list of hosts and RFC 1413 identifications to which sender verification applies. The check caused by @dfn{headers_sender_verify} also happens only for matching hosts. See chapter 45 for further details. [(font color=green)] @node sender_verify_hosts_callback, sender_verify_max_retry_rate, sender_verify_hosts, 11[[[]]] Main configuration @findex sender_verify_hosts_callback @unnumberedsubsec sender_verify_hosts_callback Type: host list@* Default: unset See @dfn{sender_verify_callback_domains} above. [(/font)] @node sender_verify_max_retry_rate, sender_verify_reject, sender_verify_hosts_callback, 11[[[]]] Main configuration @findex sender_verify_max_retry_rate @unnumberedsubsec sender_verify_max_retry_rate Type: integer@* Default: 12 If this option is greater than zero, and the rate of temporary rejection of a specific incoming sender address from a specific host, in units of rejections per hour, exceeds it, the temporary error is converted into a permanent verification error. Temporary rejections most commonly occur when a sender address cannot be verified because a DNS lookup fails to complete. The intent of this option is to stop hosts hammering too frequently with temporarily failing sender addresses. The default value of 12 means that a sender address that has a temporary verification error more than once every 5 minutes will eventually get permanently rejected. Once permanent rejection has been triggered, subsequent temporary failures all cause permanent errors, until there has been an interval of at least 24 hours since the last failure. After 24 hours, the hint expires. @node sender_verify_reject, smtp_accept_keepalive, sender_verify_max_retry_rate, 11[[[]]] Main configuration @findex sender_verify_reject @unnumberedsubsec sender_verify_reject Type: boolean@* Default: true @cindex verifying: senders When this is set, a message is rejected if sender verification fails. If it is not set, a warning message is written to the main and reject logs, and the message is accepted (unless some other error occurs). @node smtp_accept_keepalive, smtp_accept_max, sender_verify_reject, 11[[[]]] Main configuration @findex smtp_accept_keepalive @unnumberedsubsec smtp_accept_keepalive Type: boolean@* Default: true This option controls the setting of the @sc{so_keepalive} option on incoming TCP/IP socket connections. This causes the kernel periodically to send some OOB (out-of-band) data on idle connections. The reason for doing this is that it has the beneficial effect of freeing up certain types of connection that can get stuck when the remote host is disconnected without tidying up the TCP/IP call properly. @node smtp_accept_max, smtp_accept_max_per_host, smtp_accept_keepalive, 11[[[]]] Main configuration @findex smtp_accept_max @unnumberedsubsec smtp_accept_max Type: integer@* Default: 20 @cindex maximum incoming SMTP @cindex SMTP: incoming call count @cindex inetd This specifies the maximum number of simultaneous incoming SMTP calls that Exim will accept. It applies only to the listening daemon; there is no control (in Exim) when incoming SMTP is being handled by @dfn{inetd}. If the value is set to zero, no limit is applied. However, it is required to be non-zero if @dfn{smtp_accept_max_per_host} or @dfn{smtp_accept_queue} is set. @node smtp_accept_max_per_host, smtp_accept_queue, smtp_accept_max, 11[[[]]] Main configuration @findex smtp_accept_max_per_host @unnumberedsubsec smtp_accept_max_per_host Type: integer@* Default: 0 This option restricts the number of simultaneous IP connections from a single host (strictly, from a single IP address) to the Exim daemon. Once the limit is reached, additional connection attempts are rejected with error code 421. The default value of zero imposes no limit. If this option is not zero, it is required that @dfn{smtp_accept_max} also be non-zero. @node smtp_accept_queue, smtp_accept_queue_per_connection, smtp_accept_max_per_host, 11[[[]]] Main configuration @findex smtp_accept_queue @unnumberedsubsec smtp_accept_queue Type: integer@* Default: 0 @cindex SMTP: incoming call count @cindex queueing incoming messages @cindex message: queueing If the number of simultaneous incoming SMTP calls handled via the listening daemon exceeds this value, messages received are simply placed on the queue, and no delivery processes are started automatically. A value of zero implies no limit, and clearly any non-zero value is useful only if it is less than the @dfn{smtp_accept_max} value (unless that is zero). See also @dfn{queue_only}, @dfn{queue_only_load}, @dfn{queue_smtp_domains}, and the various -@dfn{od} command line options. @node smtp_accept_queue_per_connection, smtp_accept_reserve, smtp_accept_queue, 11[[[]]] Main configuration @findex smtp_accept_queue_per_connection @unnumberedsubsec smtp_accept_queue_per_connection Type: integer@* Default: 10 @cindex queueing incoming messages @cindex message: queueing This option limits the number of delivery processes that Exim starts automatically when receiving messages via SMTP, whether via the daemon or by the use of -@dfn{bs} or -@dfn{bS}. If the value of the option is greater than zero, and the number of messages received in a single SMTP session exceeds this number, subsequent messages are placed on the spool, but no delivery process is started. This helps to limit the number of Exim processes when a server restarts after downtime and there is a lot of mail waiting for it on other systems. On large systems the default should probably be increased, while on dial-in client systems it should probably be set to zero (that is, disabled). @node smtp_accept_reserve, smtp_banner, smtp_accept_queue_per_connection, 11[[[]]] Main configuration @findex smtp_accept_reserve @unnumberedsubsec smtp_accept_reserve Type: integer@* Default: 0 @cindex SMTP: incoming call count When @dfn{smtp_accept_max} is set greater than zero, this option specifies a number of SMTP connections that are reserved for connections from the hosts that are specified in @dfn{smtp_reserve_hosts}. The value set in @dfn{smtp_accept_max} includes this reserve pool. For example, if @dfn{smtp_accept_max} is set to 50 and @dfn{smtp_accept_reserve} is set to 5, once there are 45 active connections, new ones are accepted only from hosts listed in @dfn{smtp_reserve_hosts}. @node smtp_banner, smtp_check_spool_space, smtp_accept_reserve, 11[[[]]] Main configuration @findex smtp_banner @unnumberedsubsec smtp_banner Type: string, expanded@* Default: see below @cindex SMTP: welcome banner @cindex banner for SMTP @cindex welcome banner for SMTP @cindex customizing: SMTP banner This string, which is expanded every time it is used, is output as the initial positive response to an SMTP connection. The default setting is: @example smtp_banner = $primary_hostname ESMTP Exim $version_number \ #$compile_number $tod_full @end example Failure to expand the string causes a panic error. If you want to create a multiline response to the initial SMTP connection, use `\n' in the string at appropriate points, but not at the end. Note that the 220 code is not included in this string. Exim adds it automatically (several times in the case of a multiline response). @node smtp_check_spool_space, smtp_connect_backlog, smtp_banner, 11[[[]]] Main configuration @findex smtp_check_spool_space @unnumberedsubsec smtp_check_spool_space Type: boolean@* Default: true @cindex checking disc space @cindex disc space, checking @cindex spool: checking space When this option is set, if an incoming SMTP session encounters the @sc{size} option on a @sc{mail} command, it checks that there is enough space in the spool directory's partition to accept a message of that size, while still leaving free the amount specified by @dfn{check_spool_space} (even if that value is zero). If there isn't enough space, a temporary error code is returned. @node smtp_connect_backlog, smtp_etrn_command, smtp_check_spool_space, 11[[[]]] Main configuration @findex smtp_connect_backlog @unnumberedsubsec smtp_connect_backlog Type: integer@* Default: 5 @cindex connection backlog @cindex backlog of connections This specifies a maximum number of waiting SMTP connections. Exim passes this value to the TCP/IP system when it sets up its listener. Once this number of connections are waiting for the daemon's attention, subsequent connection attempts are refused at the TCP/IP level. At least, that is what the manuals say. In Solaris 2.4 such connection attempts have been observed to time out. The default value of 5 is a conservative one, suitable for older and smaller systems. For large systems is it probably a good idea to increase this, possibly substantially (to 50, say). It also gives some protection against denial-of-service attacks by SYN flooding. @node smtp_etrn_command, smtp_etrn_hosts, smtp_connect_backlog, 11[[[]]] Main configuration @findex smtp_etrn_command @unnumberedsubsec smtp_etrn_command Type: string, expanded@* Default: unset @cindex ETRN @cindex ETRN: command If this option is set, the given command is run whenever an SMTP @sc{etrn} command is received from a host that is permitted to issue such commands (see @dfn{smtp_etrn_hosts} below). The string is split up into separate arguments which are independently expanded. The expansion variable $@dfn{domain} is set to the argument of the @sc{etrn} command, and no syntax checking is done on it. For example: @example smtp_etrn_command = /etc/etrn_command $domain $sender_host_address @end example A new process is created to run the command, and Exim does not wait for it to complete. Consequently, its status cannot be checked. If the @dfn{exec} of the command fails, a line is written to the panic log, but the @sc{etrn} caller still receives a 250 success response. Exim is normally running under its own uid when receiving SMTP, so it is not possible for it to change the uid before running the command. You must disable @dfn{smtp_etrn_serialize} if you use this option to run something other than a call of Exim with the -@dfn{R} option, because otherwise the serialization lock never gets removed. @node smtp_etrn_hosts, smtp_etrn_serialize, smtp_etrn_command, 11[[[]]] Main configuration @findex smtp_etrn_hosts @unnumberedsubsec smtp_etrn_hosts Type: host list@* Default: unset @cindex ETRN @cindex SMTP: ETRN This option lists hosts that are permitted to issue an SMTP @sc{etrn} to the local host. See section 48.6 for details. @node smtp_etrn_serialize, smtp_expn_hosts, smtp_etrn_hosts, 11[[[]]] Main configuration @findex smtp_etrn_serialize @unnumberedsubsec smtp_etrn_serialize Type: boolean@* Default: true @cindex ETRN: serializing When this option is set, it prevents the simultaneous execution of more than one queue run for the same argument string as a result of an @sc{etrn} command. See section 48.6 for details. @node smtp_expn_hosts, smtp_load_reserve, smtp_etrn_serialize, 11[[[]]] Main configuration @findex smtp_expn_hosts @unnumberedsubsec smtp_expn_hosts Type: host list@* Default: unset @cindex EXPN The SMTP @sc{expn} command is supported only if the calling host matches @dfn{smtp_expn_hosts}. You must add `localhost' explicitly if you want calls to 127.0.0.1 to be able to use it. A single-level expansion of the address is done, as if the address were being tested using the -@dfn{bt} option. If an unqualified local part is given, it is qualified with @dfn{qualify_domain}. There is a generic option for directors which permits them to be skipped when processing an @sc{expn} command (compare with verification). @node smtp_load_reserve, smtp_receive_timeout, smtp_expn_hosts, 11[[[]]] Main configuration @findex smtp_load_reserve @unnumberedsubsec smtp_load_reserve Type: fixed-point@* Default: unset @cindex load average If the system load average ever gets higher than this, incoming SMTP calls are accepted only from those hosts that match an entry in @dfn{smtp_reserve_hosts}. If @dfn{smtp_reserve_hosts} is not set, no incoming SMTP calls are accepted when the load is over the limit. There are some operating systems for which Exim cannot determine the load average (see chapter 1); for these this option has no effect. @node smtp_receive_timeout, smtp_reserve_hosts, smtp_load_reserve, 11[[[]]] Main configuration @findex smtp_receive_timeout @unnumberedsubsec smtp_receive_timeout Type: time@* Default: 5m @cindex timeout: SMTP @cindex SMTP: timeout This sets a timeout value for SMTP reception. If a line of input (either an SMTP command or a data line) is not received within this time, the SMTP connection is dropped and the message is abandoned. For non-SMTP input, the reception timeout is controlled by @dfn{accept_timeout}. @node smtp_reserve_hosts, smtp_verify, smtp_receive_timeout, 11[[[]]] Main configuration @findex smtp_reserve_hosts @unnumberedsubsec smtp_reserve_hosts Type: host list@* Default: unset This option defines hosts for which SMTP connections are reserved; see @dfn{smtp_accept_reserve} and @dfn{smtp_load_reserve} above. @node smtp_verify, split_spool_directory, smtp_reserve_hosts, 11[[[]]] Main configuration @findex smtp_verify @unnumberedsubsec smtp_verify Type: boolean@* Default: false @cindex VRFY If this option is true, the SMTP command @sc{vrfy} is supported on incoming SMTP connections; otherwise it is not. @node split_spool_directory, spool_directory, smtp_verify, 11[[[]]] Main configuration @findex split_spool_directory @unnumberedsubsec split_spool_directory Type: boolean@* Default: false @cindex split spool directories @cindex multiple spool directories @cindex spool: multiple directories @cindex spool: splitting directory @cindex directories, multiple If this option is set, it causes Exim to split its input directory into 62 subdirectories, each with a single alphanumeric character as its name. The sixth character of the message id is used to allocate messages to subdirectories; this is the least significant base-62 digit of the time of arrival of the message. Splitting up the spool in this way may provide better performance on systems where there are long mail queues, by reducing the number of files in any one directory. The msglog directory is also split up in a similar way to the input directory; however, if @dfn{preserve_message_logs} is set, all old msglog files are still placed in the single directory @dfn{msglog.OLD}. It is not necessary to take any special action for existing messages when changing @dfn{split_spool_directory}. Exim notices messages that are in the `wrong' place, and continues to process them. If the option is turned off after a period of being on, the subdirectories will eventually empty and be automatically deleted. When @dfn{split_spool_directory} is set, the behaviour of queue runner processes changes. Instead of creating a list of all messages in the queue, and then trying to deliver each one in turn, it constructs a list of those in one sub-directory and tries to deliver them, before moving on to the next sub-directory. The sub-directories are processed in a random order. This spreads out the scanning of the input directories, and is beneficial when there are lots of messages on the queue. However, if @dfn{queue_run_in_order} is set, none of this new processing happens. The entire queue is scanned and sorted before any deliveries start. @node spool_directory, strip_excess_angle_brackets, split_spool_directory, 11[[[]]] Main configuration @findex spool_directory @unnumberedsubsec spool_directory Type: string@* Default: set at compile time This defines the directory in which Exim keeps its mail spool. The default value is taken from the compile-time configuration setting, if there is one. If not, this option must be set. The string is expanded, so it can contain, for example, a reference to $@dfn{primary_hostname}. If the spool directory name is fixed on your installation, it is recommended that you set it at build time rather than from this option, particularly if the log files are being written to the spool directory (see @dfn{log_file_path}). Otherwise log files cannot be used for errors that are detected early on, such as failures in the configuration file. Even with a compiled-in path, however, this option makes it possible to run testing configurations of Exim without using the standard spool. @node strip_excess_angle_brackets, strip_trailing_dot, spool_directory, 11[[[]]] Main configuration @findex strip_excess_angle_brackets @unnumberedsubsec strip_excess_angle_brackets Type: boolean@* Default: false @cindex angle brackets, excess If this option is set, redundant pairs of angle brackets round `route-addr' items in addresses are stripped. For example, @dfn{<>} is treated as @dfn{}. If this is in the envelope and the message is passed on to another MTA, the excess angle brackets are not passed on. If this option is not set, multiple pairs of angle brackets cause a syntax error. @node strip_trailing_dot, syslog_timestamp, strip_excess_angle_brackets, 11[[[]]] Main configuration @findex strip_trailing_dot @unnumberedsubsec strip_trailing_dot Type: boolean@* Default: false @cindex trailing period @cindex trailing dot @cindex dot handling If this option is set, a trailing dot at the end of a domain in an address is ignored. If this is in the envelope and the message is passed on to another MTA, the dot is not passed on. If this option is not set, a dot at the end of a domain causes a syntax error. [(font color=green)] @node syslog_timestamp, timeout_frozen_after, strip_trailing_dot, 11[[[]]] Main configuration @findex syslog_timestamp @unnumberedsubsec syslog_timestamp Type: boolean@* Default: true If @dfn{syslog_timestamp} is set false, the timestamps on Exim's log lines are omitted when these lines are sent to syslog. See chapter 51 for details of Exim's logging. [(/font)] @node timeout_frozen_after, timestamps_utc, syslog_timestamp, 11[[[]]] Main configuration @findex timeout_frozen_after @unnumberedsubsec timeout_frozen_after Type: time@* Default: 0s @cindex frozen messages: timing out @cindex timeout: frozen messages If @dfn{timeout_frozen_after} is set to a time greater than zero, a frozen message of any description that has been on the queue for longer than the given time is automatically cancelled at the next queue run. If it is a bounce message, it is just discarded; otherwise, a bounce is sent to the sender, in a similar manner to cancellation by the -@dfn{Mg} command line option. If you want to timeout frozen bounce messages earlier than other kinds of frozen message, see @dfn{ignore_errmsg_errors_after}. @node timestamps_utc, timezone, timeout_frozen_after, 11[[[]]] Main configuration @findex timestamps_utc @unnumberedsubsec timestamps_utc Type: boolean@* Default: false @cindex timestamps @cindex UTC If @dfn{timestamps_utc} is set, all timestamps generated by Exim (for example, in log entries and @dfn{Received:} header lines) are in UTC (aka GMT) rather than in local wall-clock time. @node timezone, tls_advertise_hosts, timestamps_utc, 11[[[]]] Main configuration @findex timezone @unnumberedsubsec timezone Type: string@* Default: unset @cindex time zone When @dfn{timestamps_utc} is not set, the value of @dfn{timezone} is used to set the environment variable @sc{tz} while running Exim (if it is different on entry). This ensures that all timestamps created by Exim are in the required timezone. The default value is taken from @sc{timezone_default} in @file{Local/Makefile}, or, if that is not set, from the value of the TZ environment variable when Exim is built. If @dfn{timezone} is set to the empty string, either at build or run time, then any existing @sc{tz} variable is removed from the environment when Exim runs. This is appropriate behaviour for obtaining wall-clock time on some, but unfortunately not all, operating systems. @node tls_advertise_hosts, tls_certificate, timezone, 11[[[]]] Main configuration @findex tls_advertise_hosts @unnumberedsubsec tls_advertise_hosts Type: host list@* Default: unset @cindex TLS: @cindex encrypted SMTP connections @cindex SMTP: encrypted connection @cindex SMTP: STARTTLS command When Exim is built with support for TLS encrypted connections, the availability of the @sc{starttls} command to set up an encrypted session is advertised only to those client hosts that match this option. See chapter 38 for details of Exim's support for TLS. @node tls_certificate, tls_dhparam, tls_advertise_hosts, 11[[[]]] Main configuration @findex tls_certificate @unnumberedsubsec tls_certificate Type: string, expanded@* Default: unset The value of this option is expanded, and must then be the absolute path to a file which contains the server's certificate. @node tls_dhparam, tls_host_accept_relay, tls_certificate, 11[[[]]] Main configuration @findex tls_dhparam @unnumberedsubsec tls_dhparam Type: string, expanded@* Default: unset The value of this option is expanded, and must then be the absolute path to a file which contains the server's DH parameter values. @node tls_host_accept_relay, tls_hosts, tls_dhparam, 11[[[]]] Main configuration @findex tls_host_accept_relay @unnumberedsubsec tls_host_accept_relay Type: host list@* Default: unset Client hosts which match this list are allowed to relay, provided they make use of TLS to send the message over an encrypted channel. @node tls_hosts, tls_log_cipher, tls_host_accept_relay, 11[[[]]] Main configuration @findex tls_hosts @unnumberedsubsec tls_hosts Type: host list@* Default: unset Client hosts which match this list are required to use TLS to set up an encrypted channel before Exim will accept any messages from them. @node tls_log_cipher, tls_log_peerdn, tls_hosts, 11[[[]]] Main configuration @findex tls_log_cipher @unnumberedsubsec tls_log_cipher Type: boolean@* Default: true If this option is set, the cipher which was used to transmit a message is logged using the tag `X='. This applies to both incoming and outgoing messages. @node tls_log_peerdn, tls_privatekey, tls_log_cipher, 11[[[]]] Main configuration @findex tls_log_peerdn @unnumberedsubsec tls_log_peerdn Type: boolean@* Default: false If this option is set, the Distinguished Name of the server's certificate is logged, using the tag `DN=', for all outgoing messages delivered over TLS. For incoming messages, the DN from the client's certificate is logged if a certificate was requested from the client (see @dfn{tls_verify_certificates}). @node tls_privatekey, tls_verify_certificates, tls_log_peerdn, 11[[[]]] Main configuration @findex tls_privatekey @unnumberedsubsec tls_privatekey Type: string, expanded@* Default: unset The value of this option is expanded, and must then be the absolute path to a file which contains the server's private key. @node tls_verify_certificates, tls_verify_ciphers, tls_privatekey, 11[[[]]] Main configuration @findex tls_verify_certificates @unnumberedsubsec tls_verify_certificates Type: string, expanded@* Default: unset The value of this option is expanded, and must then be the absolute path to a file or a directory containing permitted certificates for clients that match @dfn{tls_verify_hosts}. @node tls_verify_ciphers, tls_verify_hosts, tls_verify_certificates, 11[[[]]] Main configuration @findex tls_verify_ciphers @unnumberedsubsec tls_verify_ciphers Type: string, expanded@* Default: unset [(font color=green)] The value of this option is expanded, and must then be a colon-separated list of permitted ciphers for the clients that match @dfn{tls_verify_hosts}. Exim's syntax for alternate separator characters cannot be used for this list, because it is passed directly to the SSL library. [(/font)] @node tls_verify_hosts, trusted_groups, tls_verify_ciphers, 11[[[]]] Main configuration @findex tls_verify_hosts @unnumberedsubsec tls_verify_hosts Type: host list@* Default: unset Any client that matches this list is constrained by @dfn{tls_verify_certificates} and @dfn{tls_verify_ciphers}, that is, it must use one of the permitted ciphers, and present one of the listed certificates. Client hosts that do not match the list are not so constrained. @node trusted_groups, trusted_users, tls_verify_hosts, 11[[[]]] Main configuration @findex trusted_groups @unnumberedsubsec trusted_groups Type: string list@* Default: unset If this option is set, any process that is running in one of the listed groups, or which has one of them as a supplementary group, is trusted. See section 5.2 for details of what trusted callers are permitted to do. If neither @dfn{trusted_groups} nor @dfn{trusted_users} is set, only root and the Exim user are trusted. @node trusted_users, unknown_login, trusted_groups, 11[[[]]] Main configuration @findex trusted_users @unnumberedsubsec trusted_users Type: string list@* Default: unset If this option is set, any process that is running as one of the listed users is trusted. See section 5.2 for details of what trusted callers are permitted to do. If neither @dfn{trusted_groups} nor @dfn{trusted_users} is set, only root and the Exim user are trusted. @cindex uid: unknown caller @node unknown_login, unknown_username, trusted_users, 11[[[]]] Main configuration @findex unknown_login @unnumberedsubsec unknown_login Type: string@* Default: unset This is a specialized feature for use in unusual configurations. By default, if the uid of the caller of Exim cannot be looked up using @dfn{getpwuid()}, Exim gives up. The @dfn{unknown_login} option can be used to set a login name to be used in this circumstance. It is expanded, so values like @dfn{user$caller_uid} can be set. When @dfn{unknown_login} is used, the value of @dfn{unknown_username} is used for the user's real name (gecos field), unless this has been set by the -@dfn{F} option. @node unknown_username, untrusted_set_sender, unknown_login, 11[[[]]] Main configuration @findex unknown_username @unnumberedsubsec unknown_username Type: string@* Default: unset See @dfn{unknown_login}. @node untrusted_set_sender, uucp_from_pattern, unknown_username, 11[[[]]] Main configuration @findex untrusted_set_sender @unnumberedsubsec untrusted_set_sender Type: boolean@* Default: false @cindex trusted user By default, the only form in which untrusted users can use the -@dfn{f} command line option when submitting a local message is with an empty address, to declare that a message should never generate any bounces. If @dfn{untrusted_set_sender} is true, this restriction is lifted, and untrusted users may set any sender value using -@dfn{f}. This does not make all users trusted; they may use only -@dfn{f}, not the other options which override message parameters. Furthermore, this does not stop Exim from adding a @dfn{Sender:} header if necessary (unless this is disabled by @dfn{no_local_from_check}). The log line for a message's arrival shows the envelope sender following `<='. For local messages, the user's login always follows, after `U='. In -@dfn{bp} displays, and in the Exim monitor, if an untrusted user sets a sender address by this method, the user's login is shown in parentheses after the sender address. @node uucp_from_pattern, uucp_from_sender, untrusted_set_sender, 11[[[]]] Main configuration @findex uucp_from_pattern @unnumberedsubsec uucp_from_pattern Type: string@* Default: see below @cindex `From' @cindex UUCP, `From' line Some applications that pass messages to an MTA via a command line interface use an initial line starting with `From' to pass the envelope sender. In particular, this is used by UUCP software. Exim recognizes such a line by means of a regular expression that is set in @dfn{uucp_from_pattern}, and when the pattern matches, the sender address is constructed by expanding the contents of @dfn{uucp_from_sender}, provided that the caller of Exim is a trusted user. The default pattern recognizes lines in the following two forms: @example From ph10 Fri Jan 5 12:35 GMT 1996 From ph10 Fri, 7 Jan 97 14:00:00 GMT @end example The pattern can be seen by running `exim -bP uucp_from_pattern'. It checks only up to the hours and minutes, and allows for a 2-digit or 4-digit year in the second case. The first word after `From' is matched in the regular expression by a parenthesized subpattern. The default value for @dfn{uucp_from_sender} is `$1', which therefore just uses this first word (`ph10' in the example above) as the message's sender. See also @dfn{ignore_fromline_hosts}. @node uucp_from_sender, warnmsg_file, uucp_from_pattern, 11[[[]]] Main configuration @findex uucp_from_sender @unnumberedsubsec uucp_from_sender Type: string, expanded@* Default: "$1" See @dfn{uucp_from_pattern} above. @node warnmsg_file, , uucp_from_sender, 11[[[]]] Main configuration @findex warnmsg_file @unnumberedsubsec warnmsg_file Type: string@* Default: unset @cindex warning of delay, customizing This option defines a template file containing paragraphs of text to be used for constructing the warning message which is sent by Exim when a message has been on the queue for a specified amount of time, as specified by @dfn{delay_warning}. Details of the file's contents are given in chapter 39. See also @dfn{errmsg_file}. @node 12[[[]]] Driver specifications, Environment for running local transports, 11[[[]]] Main configuration, Top @chapter 12[[[]]] Driver specifications @cindex driver specifications The second, third, and fourth parts of Exim's configuration file specify which transport, director, and router drivers are to be used. Directors and routers are similar, in that an address is passed to a list of them in the order in which they are defined, whereas the order in which transports are specified is immaterial, because a transport is invoked only after being passed an address by a director or a router. Section 3.4 discusses how the different kinds of delivery driver interact. The seventh part of the configuration file (if present) specifies the authenticators that are to be used for SMTP connections (see chapter 35). These are a somewhat different kind of `driver' to the others, but they are configured in a similar way. The format of the configuration data is the same for all four types of driver, and is as follows: @example <@dfn{instance name}>: <@dfn{option}> ... <@dfn{option}> @end example @cindex generic options: @cindex options: generic There are two kinds of option: @dfn{generic} and @dfn{private}. The generic options are those that apply to all drivers of the same type (that is, all directors, all routers, all transports or all authenticators). There is always at least one generic option, called @dfn{driver}, which specifies which particular driver is being used. @cindex private options The private options are particular to each driver, and none need appear. The options may appear in any order, except that the @dfn{driver} option must precede any private options, since these depend on the particular driver. For this reason, it is recommended that @dfn{driver} always be the first option. In earlier versions of Exim, commas were used between options, and the generic options had to precede the private ones and be terminated by a semicolon. This has not been the case for some time, and at release 3.00 the backwards-compatibility code for ignoring commas and semicolons was removed. Each instance of a driver is given an identifying @dfn{instance name} name for reference in logging and elsewhere. The name can be any sequence of letters, digits, and underscores (starting with a letter) and must be unique among drivers of the same type. A router and a transport (for example) can each have the same name, but no two router instances can have the same name. The name of a driver instance should not be confused with the name of the underlying driver. The configuration lines @example remote_smtp: driver = smtp @end example create an instance of the @dfn{smtp} transport driver whose name is @dfn{remote_smtp}. The same driver code can be used more than once, with different instance names and different option settings each time. A second instance of the @dfn{smtp} transport, with different options, might be defined thus: @example special_smtp: driver = smtp port = 1234 command_timeout = 10s @end example The names @dfn{remote_smtp} and @dfn{special_smtp} would be used to reference these driver instances from directors or routers, and would appear in log lines. Comment lines may appear in the middle of driver specifications. The full list of option settings for any particular driver instance, including all the defaults, can be extracted by making use of the -@dfn{bP} command line option (see chapter 5). The next chapter describes the environment in which local deliveries are done, and how this is affected by the configurations of the relevant directors, routers, and transports. Then there is a chapter describing the generic options for transports, followed by descriptions of the available transport drivers. Directors and routers have some generic options in common, and these are covered in chapter 20 before the descriptions of the generic options that are specific to each type of driver, and the drivers themselves. The SMTP AUTH mechanism for client authentication is described in chapter 35, which is followed by descriptions of the available authenticators. @node 13[[[]]] Environment for running local transports, Generic options for transports, 12[[[]]] Driver specifications, Top @chapter 13[[[]]] Environment for running local transports @cindex local transports: environment @cindex environment for local transports Local transports handle deliveries to files and pipes. (The @dfn{autoreply} transport can be thought of as similar to a pipe.) Whenever a local transport is run, Exim forks a subprocess for it. @cindex uid: local delivery @cindex gid: local delivery Before running the transport code, it sets a specific uid and gid by calling @dfn{setuid()} and @dfn{setgid()}. It also sets a current file directory; for some transports a home directory setting is also relevant. The @dfn{pipe} transport is the only one which sets up environment variables; see section 18.3 for details. The values used for the uid, gid, and the directories may come from several different places. In many cases the director that handles the address associates settings with that address. However, values may also be given in the transport's own configuration, and these override anything that comes with the address. The sections below contain a summary of the possible sources of the values, and how they interact with each other. @sp 2 @menu * Uids and gids:: * Current and home directories:: * Expansion variables derived from the address:: @end menu @node Uids and gids, Current and home directories, 13[[[]]] Environment for running local transports, 13[[[]]] Environment for running local transports @section 13[[[]]]1 Uids and gids @cindex local transports: uid and gid @cindex transport: local All local transports have the options @dfn{group} and @dfn{user}. If @dfn{group} is set, it overrides any group that may be set in the address, even if @dfn{user} is not set. This makes it possible, for example, to run local mail delivery under the uid of the recipient, but in a special group. For example: @example group_delivery: driver = appendfile file = /var/spool/mail/$local_part group = mail @end example If @dfn{user} is set for a transport, its value overrides what is set in the address. If @dfn{user} is non-numeric and @dfn{group} is not set, the gid associated with the user is used. If @dfn{user} is numeric, @dfn{group} must be set. @cindex pipe transport The @dfn{pipe} transport contains the special option @dfn{pipe_as_creator}. If this is set and @dfn{user} is not set, the uid of the process that called Exim to receive the message is used, and if @dfn{group} is not set, the corresponding original gid is also used. @cindex initgroups option When the uid is taken from the transport's configuration, the @dfn{initgroups()} function is called for the groups associated with that uid if the @dfn{initgroups} option is set for the transport; @dfn{pipe} is the only transport that has such an option. When the uid is not specified by the transport, but is associated with the address by a director or router, the option for calling @dfn{initgroups()} is taken from the director or router configuration. All directors and routers have @dfn{group}, @dfn{user}, and @dfn{initgroups} options, which are used as follows: @cindex aliasfile director For the @dfn{aliasfile} director they specify the uid and gid for local deliveries generated directly -- that is, deliveries to pipes or files. They have no effect on generated addresses that are processed independently. @cindex forwardfile director The @dfn{forwardfile} director's @dfn{check_local_user} option causes a password file lookup for the local part of an address. The uid and gid obtained from this lookup are used for any directly generated local deliveries, but they can be overridden by the @dfn{group} and @dfn{user} options of the director. As for @dfn{aliasfile}, these values are not used for generated addresses that are processed independently. @cindex localuser director The @dfn{localuser} director looks up local parts in the password file, and sets the uid and gid from that file for local deliveries, but these values can be overridden by the director's options. @cindex smartuser director For the @dfn{smartuser} director and all the routers, the @dfn{group}, @dfn{user}, and @dfn{initgroups} options are used only if the driver sets up a delivery to a local transport. @node Current and home directories, Expansion variables derived from the address, Uids and gids, 13[[[]]] Environment for running local transports @section 13[[[]]]2 Current and home directories @cindex current directory @cindex home directory The @dfn{pipe} transport has a @dfn{home_directory} option. If this is set, it overrides any home directory set by the director for the address. The value of the home directory is set in the environment variable @sc{home} while running the pipe. It need not be set, in which case @sc{home} is not defined. The @dfn{appendfile} transport does not have a @dfn{home_directory} option. The only uses for a home directory in this transport are the appearance of the expansion variable $@dfn{home} in one of its options, and the `inhome' or `belowhome' settings of the @dfn{create_file} option. In both cases the value set by the director is used. @cindex appendfile transport @cindex pipe transport The @dfn{appendfile} and @dfn{pipe} transports have a @dfn{current_directory} option. If this is set, it overrides any current directory set by the director for the address. If neither the director nor the transport sets a current directory, then Exim uses the value of the home directory, if set. Otherwise it sets the current directory to `/' before running a local transport. @cindex aliasfile director @cindex forwardfile director @cindex localuser director All directors have @dfn{current_directory} and @dfn{home_directory} options, which are associated with any addresses they explicitly direct to a local transport. For @dfn{forwardfile}, if @dfn{home_directory} is not set and there is a @dfn{file_directory} value, that is used instead. If it too is not set, but @dfn{check_local_user} is set, the user's home directory is used. For @dfn{localuser}, if @dfn{home_directory} is not set, the home directory is taken from the password file entry that this director looks up. There are no defaults for @dfn{current_directory} in the directors, because it defaults to the value of @dfn{home_directory} if it is not set at transport time. Routers have no means of setting up home and current directory strings; consequently any local transport that they use must specify them for itself if they are required. @node Expansion variables derived from the address, , Current and home directories, 13[[[]]] Environment for running local transports @section 13[[[]]]3 Expansion variables derived from the address Normally a local delivery is handling a single address, and in that case the variables such as $@dfn{domain} and $@dfn{local_part} are set during local deliveries. However, in some circumstances more than one address may be handled at once (for example, while writing batch SMTP for onward transmission by some other means). In this case, the variables associated with the local part are never set, $@dfn{domain} is set only if all the addresses have the same domain, and $@dfn{original_domain} is never set. @node 14[[[]]] Generic options for transports, The appendfile transport, 13[[[]]] Environment for running local transports, Top @chapter 14[[[]]] Generic options for transports @cindex generic options: transport @cindex options: generic transport The generic options for transports are as follows: @sp 2 @menu * body_only (transport):: * debug_print (transport):: * delivery_date_add (transport):: * driver (transport):: * envelope_to_add (transport):: * headers_add (transport):: * headers_only (transport):: * headers_remove (transport):: * headers_rewrite (transport):: * message_size_limit (transport):: * return_path (transport):: * return_path_add (transport):: * shadow_condition (transport):: * shadow_transport (transport):: * transport_filter (transport):: @end menu @node body_only (transport), debug_print (transport), 14[[[]]] Generic options for transports, 14[[[]]] Generic options for transports @findex body_only (transport) @unnumberedsubsec body_only (transport) Type: boolean@* Default: false @cindex transport: body only @cindex message: transporting body only @cindex body of message: transporting If this option is set, the message's headers are not transported. It is mutually exclusive with @dfn{headers_only}. If it is used with the @dfn{appendfile} or @dfn{pipe} transports, the settings of @dfn{prefix} and @dfn{suffix} should be checked, since this option does not automatically suppress them. @node debug_print (transport), delivery_date_add (transport), body_only (transport), 14[[[]]] Generic options for transports @findex debug_print (transport) @unnumberedsubsec debug_print (transport) Type: string@* Default: unset @cindex testing: variables in drivers If this option is set and debugging is enabled (see -@dfn{d}, -@dfn{v}, and @dfn{debug_level}), the string is expanded and included in the debugging output when the transport is run. This is to help with checking out the values of variables and so on when debugging driver configurations. For example, if a @dfn{headers_add} option is not working properly, @dfn{debug_print} could be used to output the variables it references. A newline is added to the text if it does not end with one. @node delivery_date_add (transport), driver (transport), debug_print (transport), 14[[[]]] Generic options for transports @findex delivery_date_add (transport) @unnumberedsubsec delivery_date_add (transport) Type: boolean@* Default: false If this option is true, a @dfn{Delivery-date:} header @cindex Delivery-date: header is added to the message. This gives the actual time the delivery was made. As this is not a standard header, Exim has a configuration option (@dfn{delivery_date_remove}) which requests its removal from incoming messages, so that delivered messages can safely be resent to other recipients. @node driver (transport), envelope_to_add (transport), delivery_date_add (transport), 14[[[]]] Generic options for transports @findex driver (transport) @unnumberedsubsec driver (transport) Type: string@* Default: unset This specifies which of the available transport drivers is to be used. For example: @example driver = smtp @end example There is no default, and this option must be set for every transport. @node envelope_to_add (transport), headers_add (transport), driver (transport), 14[[[]]] Generic options for transports @findex envelope_to_add (transport) @unnumberedsubsec envelope_to_add (transport) Type: boolean@* Default: false If this option is true, an @dfn{Envelope-to:} header @cindex Envelope-to: header is added to the message. This gives the original address(es) in the incoming envelope that caused this delivery to happen. More than one address may be present if @dfn{batch} or @dfn{bsmtp} is set on transports that support them, or if more than one original address was aliased or forwarded to the same final address. As this is not a standard header, Exim has a configuration option (@dfn{envelope_to_remove}) which requests its removal from incoming messages, so that delivered messages can safely be resent to other recipients. @node headers_add (transport), headers_only (transport), envelope_to_add (transport), 14[[[]]] Generic options for transports @findex headers_add (transport) @unnumberedsubsec headers_add (transport) Type: string@* Default: unset @cindex headers: adding This option specifies a string of text which is expanded and added to the header portion of a message as it is transported. If the result of the expansion is an empty string, or if the expansion is forced to fail, no action is taken. Other expansion failures are treated as errors and cause the delivery to be deferred. The expanded string should be in the form of one or more RFC 822 header lines, separated by newlines (coded as `\n' inside a quoted string), for example: @example headers_add = "X-added: this is a header added at $tod_log\n\ X-added: this is another" @end example Exim does not check the syntax of these added headers. A newline is supplied at the end if one is not present. The text is added at the end of any existing headers. If you include a blank line within the string, you can subvert this facility into adding text at the start of the message's body. The name @dfn{add_headers} was formerly used for this option, and is retained as a synonym for backward compatibility. Additional headers can also be specified by directors and routers. See chapter 20 and section 49.13. @node headers_only (transport), headers_remove (transport), headers_add (transport), 14[[[]]] Generic options for transports @findex headers_only (transport) @unnumberedsubsec headers_only (transport) Type: boolean@* Default: false @cindex transport: headers only @cindex message: transporting headers only @cindex headers: transporting If this option is set, the message's body is not transported. It is mutually exclusive with @dfn{body_only}. If it is used with the @dfn{appendfile} or @dfn{pipe} transports, the settings of @dfn{prefix} and @dfn{suffix} should be checked, since this option does not automatically suppress them. @node headers_remove (transport), headers_rewrite (transport), headers_only (transport), 14[[[]]] Generic options for transports @findex headers_remove (transport) @unnumberedsubsec headers_remove (transport) Type: string@* Default: unset @cindex headers: removing This option is expanded; the result must consist of a colon-separated list of header names, not including the terminating colon, for example: @example headers_remove = return-receipt-to:acknowledge-to @end example Any existing headers matching those names are not included in any message that transmitted by the transport. However, added headers may have these names. Thus it is possible to replace a header by specifying it in @dfn{headers_remove} and supplying the replacement in @dfn{add_headers}. The name @dfn{remove_headers} was formerly used for this option, and is retained as a synonym for backward compatibility. Headers to be removed can also be specified by directors and routers. See chapter 20 and section 49.13. @node headers_rewrite (transport), message_size_limit (transport), headers_remove (transport), 14[[[]]] Generic options for transports @findex headers_rewrite (transport) @unnumberedsubsec headers_rewrite (transport) Type: string@* Default: unset @cindex transport: header rewriting @cindex rewriting: at transport time This option allows addresses in header lines to be rewritten at transport time, that is, as the message is being copied to its destination. The contents of the option are a colon-separated list of rewriting rules. Each rule is in exactly the same form as one of the general rewriting rules that are applied when a message is received. These are described in chapter 34. For example, @example headers_rewrite = a@@b c@@d f : \ x@@y w@@z @end example changes @dfn{a@@b} into @dfn{c@@d} in @dfn{From:} header lines, and @dfn{x@@y} into @dfn{w@@z} in all address-bearing header lines. The rules are applied to the header lines just before they are written out at transport time, so they affect only those copies of the message that pass through the transport. However, only the message's original header lines, and any that were added by a system filter, are rewritten. If a router, director, or transport adds header lines, these are not affected. These rewriting rules are @dfn{not} applied to the envelope. You can change the return path using @dfn{return_path}; you cannot change envelope recipients at this time. @node message_size_limit (transport), return_path (transport), headers_rewrite (transport), 14[[[]]] Generic options for transports @findex message_size_limit (transport) @unnumberedsubsec message_size_limit (transport) Type: integer@* Default: 0 This option controls the size of messages passed through the transport. If its value is greater than zero and the size of a message message exceeds the limit, the address is failed. If there is any chance that the resulting bounce message could be routed to the same transport, you should ensure that @dfn{return_size_limit} is less than the transport's @dfn{message_size_limit}, as otherwise the bounce message will fail to get delivered. @node return_path (transport), return_path_add (transport), message_size_limit (transport), 14[[[]]] Generic options for transports @findex return_path (transport) @unnumberedsubsec return_path (transport) Type: string, expanded@* Default: unset If this option is set, the string is expanded at transport time and replaces the existing return path (envelope sender) value. The expansion can refer to the existing value via $@dfn{return_path}. If the expansion is forced to fail, no replacement occurs; if it fails for another reason, Exim panics. This option can be used to support VERP (Variable Envelope Return Paths) -- see chapter 48. @node return_path_add (transport), shadow_condition (transport), return_path (transport), 14[[[]]] Generic options for transports @findex return_path_add (transport) @unnumberedsubsec return_path_add (transport) Type: boolean@* Default: false If this option is true, a @dfn{Return-path:} header @cindex Return-path: header is added to the message. Although the return path is normally available in the prefix line of BSD mailboxes, this is commonly not displayed by MUAs, and so the user does not have easy access to it. RFC 822 states that the @dfn{Return-path:} header is `added by the final transport system that delivers the message to its recipient' (section 4.3.1), which implies that this header should not be present in incoming messages. Exim has a configuration option, @dfn{return_path_remove}, which requests removal of this header from incoming messages, so that delivered messages can safely be resent to other recipients. @node shadow_condition (transport), shadow_transport (transport), return_path_add (transport), 14[[[]]] Generic options for transports @findex shadow_condition (transport) @unnumberedsubsec shadow_condition (transport) Type: string, expanded@* Default: unset See @dfn{shadow_transport} below. @node shadow_transport (transport), transport_filter (transport), shadow_condition (transport), 14[[[]]] Generic options for transports @findex shadow_transport (transport) @unnumberedsubsec shadow_transport (transport) Type: string@* Default: unset @cindex shadow transport @cindex transport: shadow This facility is somewhat experimental, and may change in future. A local transport may set the @dfn{shadow_transport} option to the name of another, previously-defined, local transport. Shadow remote transports are not supported. Whenever a delivery to the main transport succeeds, and either @dfn{shadow_condition} is unset, or its expansion does not result in a forced expansion failure or the empty string or one of the strings `0' or `no' or `false', the message is also passed to the shadow transport, with the same delivery address or addresses. However, the result of the shadow transport is discarded and does not affect the subsequent processing of the message. Only a single level of shadowing is provided; the @dfn{shadow_transport} option is ignored on any transport when it is running as a shadow. Options concerned with output from pipes are also ignored. The log line for the successful delivery has an item added on the end, of the form @example ST=<@dfn{shadow transport name}> @end example If the shadow transport did not succeed, the error message is put in parentheses afterwards. Shadow transports can be used for a number of different purposes, including keeping more detailed log information than Exim normally provides, and implementing automatic acknowledgement policies based on message headers that some sites insist on. @node transport_filter (transport), , shadow_transport (transport), 14[[[]]] Generic options for transports @findex transport_filter (transport) @unnumberedsubsec transport_filter (transport) Type: string@* Default: unset @cindex transport: filter @cindex filter: transport filter This option sets up a filtering (in the Unix shell sense) process for messages at transport time. It should not be confused with mail filtering as set up by individual users or via a system filter. When the message is about to be written out, the command specified by @dfn{transport_filter} is started up in a separate process, and the entire message, including the headers, is passed to it on its standard input (this in fact is done from a third process, to avoid deadlock). This happens before any SMTP-specific processing, such as turning `\n' into `\r\n' and escaping lines beginning with a dot, and also before any processing implied by the settings of @dfn{check_string} and @dfn{escape_string} in the @dfn{appendfile} or @dfn{pipe} transports. The filter's standard output is read and written to the message's destination. The filter can perform any transformations it likes, but of course should take care not to break RFC 822 syntax. A demonstration Perl script is provided in @dfn{util/transport-filter.pl}; this makes a few arbitrary modifications just to show the possibilities. Exim does not check the result, except to test for a final newline when SMTP is in use. All messages transmitted over SMTP must end with a newline, so Exim supplies one if it is missing. @cindex SMTP: SIZE A problem might arise if the filter increases the size of a message that is being sent down an SMTP channel. If the receiving SMTP server has indicated support for the @sc{size} parameter, Exim will have sent the size of the message at the start of the SMTP session. If what is actually sent is substantially more, the server might reject the message. This can be worked round by setting the @dfn{size_addition} option on the @dfn{smtp} transport, either to allow for additions to the message, or to disable the use of @sc{size} altogether. The value of the option is the command string for starting up the filter, which is run directly from Exim, not under a shell. The string is parsed by Exim in the same way as a command string for the @dfn{pipe} transport: Exim breaks it up into arguments and then expands each argument separately. The special argument $@dfn{pipe_addresses} is replaced by a number of arguments, one for each address that applies to this delivery. (This isn't an ideal name for this feature here, but as it was already implemented for the @dfn{pipe} transport, it seemed sensible not to change it.) The expansion variables $@dfn{host} and $@dfn{host_address} are available when the transport is a remote one. They are set only for the expansion of a transport filter command, as that is the only thing that is expanded after a connection has been set up. For example: @example transport_filter = /some/directory/transport-filter.pl \ $host $host_address $sender_address $pipe_addresses @end example The filter process is run under the same uid and gid as the normal delivery. For remote deliveries this is the exim uid/gid if they are defined. If a transport filter is set on an autoreply transport, the original message is passed through the filter as it is being copied into the newly generated message, which happens if the @dfn{return_message} option is set. @node 15[[[]]] The appendfile transport, The autoreply transport, 14[[[]]] Generic options for transports, Top @chapter 15[[[]]] The appendfile transport @cindex appendfile transport @cindex transport: appendfile @cindex directory creation @cindex creating directories The @dfn{appendfile} transport delivers a message by appending it to a file in the local file system, 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, @dfn{inter alia}. 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 @dfn{create_directory} is set. The code for the optional formats is not included in the Exim binary by default. It is necessary to set @sc{support_mbx}, @sc{support_maildir} and/or @sc{support_mailstore} in @file{Local/Makefile} to have the appropriate code included. @dfn{Appendfile} can be used by routers as a pseudo-remote transport for putting messages into files for remote delivery by some means other than Exim, though it is more commonly used by directors for local deliveries to users' mailboxes. It is also used for delivering messages to files or directories whose names are obtained directly from alias, forwarding, or filtering operations. In these cases, $@dfn{local_part} contains the local part that was aliased or forwarded, while $@dfn{address_file} contains the name of the file or directory. As @dfn{appendfile} is a local transport, it is always run in a separate process, under a non-privileged uid and gid, which are set by @dfn{setuid()}. In the common local delivery case, these are the uid and gid belonging to the user to whom the mail is being delivered. The current directory is also normally set to the user's home directory. See chapter 13 for a discussion of the local delivery environment. If the transport fails for any reason, the message remains on the input queue so that there can be another delivery attempt later. 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. Exim supports a local quota, for use when the system facility is unavailable or cannot be used for some reason. 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. @sp 2 @menu * Private options for appendfile:: * Operational details for appending:: * Operational details for delivery to a new file:: @end menu @node Private options for appendfile, Operational details for appending, 15[[[]]] The appendfile transport, 15[[[]]] The appendfile transport @section 15[[[]]]1 Private options for appendfile @cindex options: appendfile @sp 2 @menu * allow_fifo (appendfile):: * allow_symlink (appendfile):: * batch (appendfile):: * batch_max (appendfile):: * bsmtp (appendfile):: * bsmtp_helo (appendfile):: * check_group (appendfile):: * check_owner (appendfile):: * check_string (appendfile):: * create_directory (appendfile):: * create_file (appendfile):: * current_directory (appendfile):: * directory (appendfile):: * directory_mode (appendfile):: * escape_string (appendfile):: * file (appendfile):: * file_format (appendfile):: * file_must_exist (appendfile):: * from_hack (appendfile):: * group (appendfile):: * lock_fcntl_timeout (appendfile):: * lock_interval (appendfile):: * lock_retries (appendfile):: * lockfile_mode (appendfile):: * lockfile_timeout (appendfile):: * maildir_format (appendfile):: * maildir_retries (appendfile):: * maildir_tag (appendfile):: * mailstore_format (appendfile):: * mailstore_prefix (appendfile):: * mailstore_suffix (appendfile):: * mbx_format (appendfile):: * mode (appendfile):: * mode_fail_narrower (appendfile):: * notify_comsat (appendfile):: * prefix (appendfile):: * quota (appendfile):: * quota_filecount (appendfile):: * quota_is_inclusive (appendfile):: * quota_size_regex (appendfile):: * quota_warn_message (appendfile):: * quota_warn_threshold (appendfile):: * require_lockfile (appendfile):: * retry_use_local_part (appendfile):: * suffix (appendfile):: * use_crlf (appendfile):: * use_fcntl_lock (appendfile):: * use_lockfile (appendfile):: * use_mbx_lock (appendfile):: * user (appendfile):: @end menu @node allow_fifo (appendfile), allow_symlink (appendfile), Private options for appendfile, Private options for appendfile @findex allow_fifo (appendfile) @unnumberedsubsec allow_fifo (appendfile) Type: boolean@* Default: false @cindex fifo (named pipe) @cindex named pipe (fifo) @cindex pipe: named (fifo) 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. @node allow_symlink (appendfile), batch (appendfile), allow_fifo (appendfile), Private options for appendfile @findex allow_symlink (appendfile) @unnumberedsubsec allow_symlink (appendfile) Type: boolean@* Default: false @cindex link, symbolic @cindex symbolic link @cindex mailbox: symbolic link By default, @dfn{appendfile} 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. @node batch (appendfile), batch_max (appendfile), allow_symlink (appendfile), Private options for appendfile @findex batch (appendfile) @unnumberedsubsec batch (appendfile) Type: string@* Default: "none" Normally, each address that is directed or routed to an @dfn{appendfile} transport is handled separately. In special cases it may be desirable to handle several addresses at once, for example, when passing a message with several addresses to a different mail regime (for example, UUCP), though this is more often done using the @dfn{pipe} transport. If this option is set to the string `domain', all addresses with the same domain that are directed or routed to the transport are handled in a single delivery. If it is set to `all' then multiple domains are batched. The list of addresses is included in the @dfn{Envelope-to:} header @cindex Envelope-to: header if the generic @dfn{envelope_to_add} option is set. When more than one address is being delivered, $@dfn{local_part} is not set, and $@dfn{domain} is set only if they all have the same domain. The only difference between this option and @dfn{bsmtp} is the inclusion of SMTP command lines in the output for @dfn{bsmtp}, and the escaping of lines that begin with a full stop (period). @node batch_max (appendfile), bsmtp (appendfile), batch (appendfile), Private options for appendfile @findex batch_max (appendfile) @unnumberedsubsec batch_max (appendfile) Type: integer@* Default: 100 This limits the number of addresses that can be handled in a batch, and applies to both the @dfn{batch} and the @dfn{bsmtp} options. @node bsmtp (appendfile), bsmtp_helo (appendfile), batch_max (appendfile), Private options for appendfile @findex bsmtp (appendfile) @unnumberedsubsec bsmtp (appendfile) Type: string@* Default: "none" This option is used to set up an @dfn{appendfile} transport as a pseudo-remote transport for delivering messages into local files in batch SMTP format for onward transmission by some non-Exim means. It is usually necessary to suppress the default settings of the @dfn{prefix} and @dfn{suffix} options when using batch SMTP. The @dfn{check_string} and @dfn{escape_string} options are forced to the values @example check_string = "." escape_string = ".." @end example when batched SMTP is in use. The value of @dfn{bsmtp} must be one of the strings `none', `one', `domain', or `all'. The first of these turns the feature off. A full description of the batch SMTP mechanism is given in section 48.8. When @dfn{bstmp} is set, the @dfn{batch} option automatically takes the same value. See also the @dfn{use_crlf} option. @node bsmtp_helo (appendfile), check_group (appendfile), bsmtp (appendfile), Private options for appendfile @findex bsmtp_helo (appendfile) @unnumberedsubsec bsmtp_helo (appendfile) Type: boolean@* Default: false When this option is set, a @sc{helo} line is added to the output at the start of each message written in batch SMTP format. Some software that reads batch SMTP is unhappy without this. @node check_group (appendfile), check_owner (appendfile), bsmtp_helo (appendfile), Private options for appendfile @findex check_group (appendfile) @unnumberedsubsec check_group (appendfile) Type: boolean@* Default: false The group owner of the file is checked to see that it is the same as the group under which the delivery process is running when this option is set. The default setting is false because the default file mode is 0600, which means that the group is irrelevant. @node check_owner (appendfile), check_string (appendfile), check_group (appendfile), Private options for appendfile @findex check_owner (appendfile) @unnumberedsubsec check_owner (appendfile) Type: boolean@* Default: true The owner of the file is checked to ensure that it is the same as the user under which the delivery process is running when this option is set. @node check_string (appendfile), create_directory (appendfile), check_owner (appendfile), Private options for appendfile @findex check_string (appendfile) @unnumberedsubsec check_string (appendfile) Type: string@* Default: "From " @cindex `From' As @dfn{appendfile} writes the message, the start of each line is tested for matching @dfn{check_string}, and if it does, the initial matching characters are replaced by the contents of @dfn{escape_string}. The value of @dfn{check_string} is a literal string, not a regular expression, and the case of any letters it contains is significant. For backwards compatibility, if @dfn{no_from_hack} is specified, the values of @dfn{check_string} and @dfn{escape_string} are forced to be unset. The default settings, along with @dfn{prefix} and @dfn{suffix}, 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: @cindex MMDF format mailbox @cindex mailbox: MMDF format @example check_string = "\1\1\1\1\n" escape_string = "\1\1\1\1 \n" prefix = "\1\1\1\1\n" suffix = "\1\1\1\1\n" @end example When the @dfn{bsmtp} option is set, the contents of @dfn{check_string} and @dfn{escape_string} are forced to values that implement the SMTP escaping protocol. Any settings made in the configuration file are ignored. @cindex directory creation @node create_directory (appendfile), create_file (appendfile), check_string (appendfile), Private options for appendfile @findex create_directory (appendfile) @unnumberedsubsec create_directory (appendfile) Type: boolean@* Default: true When this option is true, Exim creates any missing superior directories for the file that it is about to write. A created directory's mode is given by the @dfn{directory_mode} option. @node create_file (appendfile), current_directory (appendfile), create_directory (appendfile), Private options for appendfile @findex create_file (appendfile) @unnumberedsubsec create_file (appendfile) Type: string@* Default: "anywhere" This option constrains the location of files that are created by this transport. It 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 up for the address by the director that handled it. This option isn't useful when an explicit file name is given for normal mailbox deliveries; it is intended for the case when file names have been generated from user's @file{.forward} files, which are usually handled by an @dfn{appendfile} transport called @dfn{address_file}. See also @dfn{file_must_exist}. @node current_directory (appendfile), directory (appendfile), create_file (appendfile), Private options for appendfile @findex current_directory (appendfile) @unnumberedsubsec current_directory (appendfile) Type: string, expanded@* Default: unset If this option is set, it specifies the directory to make current when running the delivery process. The string is expanded at the time the transport is run. See chapter 13 for details of the local delivery environment. @node directory (appendfile), directory_mode (appendfile), current_directory (appendfile), Private options for appendfile @findex directory (appendfile) @unnumberedsubsec directory (appendfile) Type: string, expanded@* Default: unset This option is mutually exclusive with the @dfn{file} option. When it 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 @dfn{maildir_format} and @dfn{mailstore_format}), and see section 15.3 for further details of this form of delivery. @node directory_mode (appendfile), escape_string (appendfile), directory (appendfile), Private options for appendfile @findex directory_mode (appendfile) @unnumberedsubsec directory_mode (appendfile) Type: octal integer@* Default: 0700 If @dfn{appendfile} creates any directories as a result of the @dfn{create_directory} option, their mode is specified by this option. @node escape_string (appendfile), file (appendfile), directory_mode (appendfile), Private options for appendfile @findex escape_string (appendfile) @unnumberedsubsec escape_string (appendfile) Type: string@* Default: ">From " See @dfn{check_string} above. @node file (appendfile), file_format (appendfile), escape_string (appendfile), Private options for appendfile @findex file (appendfile) @unnumberedsubsec file (appendfile) Type: string, expanded@* Default: unset This option is mutually exclusive with the @dfn{directory} option. It need not be set when @dfn{appendfile} is being used to deliver to files whose names are obtained from forwarding, filtering, or aliasing address expansions (by default under the instance name @dfn{address_file}), as in those cases the file name is associated with the address. Otherwise, the @dfn{file} option must be set unless the @dfn{directory} option is set. Either @dfn{use_fcntl_lock} or @dfn{use_lockfile} (or both) must be set with @dfn{file}. @cindex NFS: lock file @cindex locking files @cindex lock files If you are using more than one host to deliver over NFS into the same mailboxes, you should always use lock files. 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: @example file = /var/spool/mail/$local_part file = /home/$local_part/inbox file = $home/inbox @end example @cindex `sticky' bit In the first example, all deliveries are done into the same directory. If Exim is configured to use lock files (see @dfn{use_lockfile} 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 @dfn{group} option can be used to run the delivery under a group id which has write access to the directory. If there is no file name, or the expansion fails, or a local part contains a forward slash character, a delivery error occurs. @node file_format (appendfile), file_must_exist (appendfile), file (appendfile), Private options for appendfile @findex file_format (appendfile) @unnumberedsubsec file_format (appendfile) Type: string@* Default: unset @cindex file: checking existing format 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. A list of check strings may be given, and associated with each is the 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. There should always be an even number of items in a @dfn{file_format} setting. For example, if the standard @dfn{local_delivery} transport has this added to it: @example file_format = "From : local_delivery :\ \1\1\1\1\n : local_mmdf_delivery" @end example then mailboxes that begin with `From' are handled by this transport, but if a mailbox begins with four binary ones followed by a newline, control is passed to a transport called @dfn{local_mmdf_delivery} 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. @node file_must_exist (appendfile), from_hack (appendfile), file_format (appendfile), Private options for appendfile @findex file_must_exist (appendfile) @unnumberedsubsec file_must_exist (appendfile) Type: boolean@* Default: false If this option is true, the file specified by the @dfn{file} option must exist, and an error occurs if it does not. Otherwise, it is created if it does not exist. @node from_hack (appendfile), group (appendfile), file_must_exist (appendfile), Private options for appendfile @findex from_hack (appendfile) @unnumberedsubsec from_hack (appendfile) Type: boolean@* Default: true This option is obsolete and is retained only for backwards compatibility. It has been replaced by @dfn{check_string} and @dfn{escape_string}. If it is explicitly unset (that is, if @dfn{no_from_hack} is specified), it causes both the new options to be unset. Otherwise it is ignored. @node group (appendfile), lock_fcntl_timeout (appendfile), from_hack (appendfile), Private options for appendfile @findex group (appendfile) @unnumberedsubsec group (appendfile) Type: string@* Default: unset @cindex gid: local delivery If this option is set, it specifies the group under whose gid the delivery process is to be run, and, if @dfn{check_group} is set, the group owner of an existing file to which the message is to be appended. If the option is not set, a value associated with a user may be used (see below); otherwise a value must have been associated with the address by the director which handled it. If the string contains no $ characters, it is resolved when Exim starts up. Otherwise, the string is expanded at the time the transport is run, and must yield either a digit string or a name which can be looked up using @dfn{getgrnam()}. The @dfn{group} option is commonly set for local deliveries on systems where the set of user mailboxes is in a single directory owned by a group such as `mail'. Note that it should @dfn{not} be set on the instance of @dfn{appendfile} that is used for deliveries to files specified by users in their forward files (called @dfn{address_file} in the default configuration), because such deliveries should take place under the individual users' personal uids and gids. @node lock_fcntl_timeout (appendfile), lock_interval (appendfile), group (appendfile), Private options for appendfile @findex lock_fcntl_timeout (appendfile) @unnumberedsubsec lock_fcntl_timeout (appendfile) Type: time@* Default: 0s @cindex timeout: blocking @cindex timeout: non-blocking @cindex locking files By default, the @dfn{appendfile} transport uses non-blocking calls to @dfn{fcntl()} when locking an open mailbox file. If the call fails, it sleeps for @dfn{lock_interval} and tries again, up to @dfn{lock_retries} 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. 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. If @dfn{lock_fcntl_timeout} 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 @example (lock_retries * lock_interval) / lock_fcntl_timeout @end example rounded up to the next whole number. In other words, the total time during which @dfn{appendfile} is trying to get a lock is roughly the same, unless @dfn{lock_fcntl_timeout} is set very large. You should consider setting this option if you are getting a lot of delayed local deliveries because of errors of the form @example failed to lock mailbox /some/file (fcntl) @end example @node lock_interval (appendfile), lock_retries (appendfile), lock_fcntl_timeout (appendfile), Private options for appendfile @findex lock_interval (appendfile) @unnumberedsubsec lock_interval (appendfile) Type: time@* Default: 3s This specifies the time to wait between attempts to lock the file. See below for details of locking. @node lock_retries (appendfile), lockfile_mode (appendfile), lock_interval (appendfile), Private options for appendfile @findex lock_retries (appendfile) @unnumberedsubsec lock_retries (appendfile) Type: integer@* Default: 10 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. @node lockfile_mode (appendfile), lockfile_timeout (appendfile), lock_retries (appendfile), Private options for appendfile @findex lockfile_mode (appendfile) @unnumberedsubsec lockfile_mode (appendfile) Type: octal integer@* Default: 0600 This specifies the mode of the created lock file, when a lock file is being used (see @dfn{use_lockfile}). @node lockfile_timeout (appendfile), maildir_format (appendfile), lockfile_mode (appendfile), Private options for appendfile @findex lockfile_timeout (appendfile) @unnumberedsubsec lockfile_timeout (appendfile) Type: time@* Default: 30m When a lock file is being used (see @dfn{use_lockfile}), 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. @node maildir_format (appendfile), maildir_retries (appendfile), lockfile_timeout (appendfile), Private options for appendfile @findex maildir_format (appendfile) @unnumberedsubsec maildir_format (appendfile) Type: boolean@* Default: false If this option is set with the @dfn{directory} option, the delivery is into a new file in the `maildir' format that is used by some other mail software. The option is available only if @sc{support_maildir} is present in @file{Local/Makefile}. See section 15.3 below for further details. @node maildir_retries (appendfile), maildir_tag (appendfile), maildir_format (appendfile), Private options for appendfile @findex maildir_retries (appendfile) @unnumberedsubsec maildir_retries (appendfile) Type: integer@* Default: 10 This option specifies the number of times to retry when writing a file in `maildir' format. See section 15.3 below. @node maildir_tag (appendfile), mailstore_format (appendfile), maildir_retries (appendfile), Private options for appendfile @findex maildir_tag (appendfile) @unnumberedsubsec maildir_tag (appendfile) Type: string, expanded@* Default: unset This option applies only to deliveries in maildir format, and is described in section 15.3 below. @node mailstore_format (appendfile), mailstore_prefix (appendfile), maildir_tag (appendfile), Private options for appendfile @findex mailstore_format (appendfile) @unnumberedsubsec mailstore_format (appendfile) Type: boolean@* Default: false If this option is set with the @dfn{directory} option, the delivery is into two new files in `mailstore' format. The option is available only if @sc{support_mailstore} is present in @file{Local/Makefile}. See section 15.3 below for further details. @node mailstore_prefix (appendfile), mailstore_suffix (appendfile), mailstore_format (appendfile), Private options for appendfile @findex mailstore_prefix (appendfile) @unnumberedsubsec mailstore_prefix (appendfile) Type: string, expanded@* Default: unset This option applies only to deliveries in mailstore format, and is described in section 15.3 below. @node mailstore_suffix (appendfile), mbx_format (appendfile), mailstore_prefix (appendfile), Private options for appendfile @findex mailstore_suffix (appendfile) @unnumberedsubsec mailstore_suffix (appendfile) Type: string, expanded@* Default: unset This option applies only to deliveries in mailstore format, and is described in section 15.3 below. @node mbx_format (appendfile), mode (appendfile), mailstore_suffix (appendfile), Private options for appendfile @findex mbx_format (appendfile) @unnumberedsubsec mbx_format (appendfile) Type: boolean@* Default: false @cindex locking files @cindex file: locking @cindex file: MBX format This option is available only if Exim has been compiled with @sc{support_mbx} set in @file{Local/Makefile}. If @dfn{mbx_format} is set with the @dfn{file} 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, and is implemented by the @dfn{c-client} library that they all use. The @dfn{prefix} and @dfn{suffix} options are not automatically changed by the use of @dfn{mbx_format}; they should normally be set empty. If none of the locking options are mentioned in the configuration, @dfn{use_mbx_lock} is assumed and the other locking options default to false. It is possible to specify the other kinds of locking with @dfn{mbx_format}, but @dfn{use_fcntl_lock} and @dfn{use_mbx_lock} are mutually exclusive. MBX locking inter~works with @dfn{c-client}, 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. If you set @dfn{use_fcntl_lock} with an MBX-format mailbox, you cannot use the standard version of @dfn{c-client}, 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. @node mode (appendfile), mode_fail_narrower (appendfile), mbx_format (appendfile), Private options for appendfile @findex mode (appendfile) @unnumberedsubsec mode (appendfile) Type: octal integer@* Default: 0600 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 @dfn{mode_fail_narrower} is false. However, if the delivery is the result of a @dfn{save} command in a filter file specifing a particular mode, the mode of the output file is always forced to take that value, and this option is ignored. @node mode_fail_narrower (appendfile), notify_comsat (appendfile), mode (appendfile), Private options for appendfile @findex mode_fail_narrower (appendfile) @unnumberedsubsec mode_fail_narrower (appendfile) Type: boolean@* Default: true This option applies in the case when an existing mailbox file has a narrower mode than that specified by the @dfn{mode} option. If @dfn{mode_fail_narrower} is true, the delivery is frozen (`mailbox has the wrong mode'); otherwise Exim continues with the delivery attempt, using the existing mode of the file. @node notify_comsat (appendfile), prefix (appendfile), mode_fail_narrower (appendfile), Private options for appendfile @findex notify_comsat (appendfile) @unnumberedsubsec notify_comsat (appendfile) Type: boolean@* Default: false If this option is true, the @dfn{comsat} daemon is notified after every successful delivery to a user mailbox. This is the daemon that notifies logged on users about incoming mail. @node prefix (appendfile), quota (appendfile), notify_comsat (appendfile), Private options for appendfile @findex prefix (appendfile) @unnumberedsubsec prefix (appendfile) Type: string, expanded@* Default: see below The string specified here is expanded and output at the start of every message. The default is @example prefix = "From $@{if def:return_path@{$return_path@}@{MAILER-DAEMON@}@}\ $@{tod_bsdinbox@}\n" @end example This line can be suppressed by setting @example prefix = @end example and this is usually necessary when doing batch SMTP deliveries, or delivering into individual files or MBX-format mailboxes. @node quota (appendfile), quota_filecount (appendfile), prefix (appendfile), Private options for appendfile @findex quota (appendfile) @unnumberedsubsec quota (appendfile) Type: string, expanded@* Default: unset @cindex quota: imposed by Exim 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 if the @dfn{directory} option is set. In the latter case, computation of the space used is expensive, as all the files in the directory (and any sub-directories) have to be individually inspected and their sizes summed (but see @dfn{quota_size_regex} below). Also, there is no interlock against two simultaneous deliveries into a multi-file mailbox. For single-file mailboxes, of course, an interlock is a necessity. A file's size is take as its @dfn{used} value. Because of blocking effects, this may be a lot less than the actual amount of disc 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 @dfn{used} figure, because this is the obvious value which users will understand most easily. 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 or M. The expansion happens while Exim is running as root or the Exim user, before @dfn{setuid()} is called for the delivery, so 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. 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 @dfn{quota_is_inclusive} 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 @dfn{quota_warn_threshold}. @node quota_filecount (appendfile), quota_is_inclusive (appendfile), quota (appendfile), Private options for appendfile @findex quota_filecount (appendfile) @unnumberedsubsec quota_filecount (appendfile) Type: integer@* Default: 0 This option applies when the @dfn{directory} 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 @dfn{quota} is also set. @node quota_is_inclusive (appendfile), quota_size_regex (appendfile), quota_filecount (appendfile), Private options for appendfile @findex quota_is_inclusive (appendfile) @unnumberedsubsec quota_is_inclusive (appendfile) Type: boolean@* Default: true See @dfn{quota} above. @node quota_size_regex (appendfile), quota_warn_message (appendfile), quota_is_inclusive (appendfile), Private options for appendfile @findex quota_size_regex (appendfile) @unnumberedsubsec quota_size_regex (appendfile) Type: string@* Default: unset 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 @dfn{quota_size_regex}. 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. 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 @dfn{maildir_tag} to add the file length to the file name. For example: @example maildir_tag = ,S=$message_size quota_size_regex = S=(\d+)$ @end example The string is not expanded. @node quota_warn_message (appendfile), quota_warn_threshold (appendfile), quota_size_regex (appendfile), Private options for appendfile @findex quota_warn_message (appendfile) @unnumberedsubsec quota_warn_message (appendfile) Type: string, expanded@* Default: see below See below for the use of this option. If it is not set when @dfn{quota_warn_threshold} is set, it defaults to @example 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" @end example @node quota_warn_threshold (appendfile), require_lockfile (appendfile), quota_warn_message (appendfile), Private options for appendfile @findex quota_warn_threshold (appendfile) @unnumberedsubsec quota_warn_threshold (appendfile) Type: string, expanded@* Default: "0" @cindex quota: warning threshold @cindex mailbox: size warning @cindex size of mailbox This option is expanded in the same way as @dfn{quota} (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 @dfn{quota} is also set, the threshold may be specified as a percentage of it by following the value with a percent sign. For example: [(font color=green)] @example quota = 10M quota_warn_threshold = 75% @end example If @dfn{quota} is not set, a setting of @dfn{quota_warn_threshold} that ends with a percent sign is ignored. [(/font)] The warning message itself is specified by the @dfn{quota_warn_message} option, and it must start with a @dfn{To:} header line containing the recipient(s). A @dfn{Subject:} line should also normally be supplied. The @dfn{quota} 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. @node require_lockfile (appendfile), retry_use_local_part (appendfile), quota_warn_threshold (appendfile), Private options for appendfile @findex require_lockfile (appendfile) @unnumberedsubsec require_lockfile (appendfile) Type: boolean@* Default: true When a lock file is being used (see @dfn{use_lockfile}) and @dfn{require_lockfile} is true, a lock file must be created before delivery can proceed. If the option is not true, failure to create a lock file because of a `permission denied' error is not treated as an error, though failure of the @dfn{fcntl()} locking function is. This option should always be set when delivering from more than one host over NFS. @cindex NFS: lock file It is required to be set if the @dfn{file} option is set and @dfn{use_fcntl_lock} is not set, except when @dfn{mbx_format} is set. @node retry_use_local_part (appendfile), suffix (appendfile), require_lockfile (appendfile), Private options for appendfile @findex retry_use_local_part (appendfile) @unnumberedsubsec retry_use_local_part (appendfile) Type: boolean@* Default: true When a local delivery suffers a temporary failure, both the local part and the domain are normally used to form a key that is used to determine when next to try the address. This handles common cases such as exceeding a quota, where the failure applies to the specific local part. However, when local delivery is being used to collect messages for onward transmission by some other means, a temporary failure may not depend on the local part at all. Setting this option false causes Exim to use only the domain when handling retries for this transport. @node suffix (appendfile), use_crlf (appendfile), retry_use_local_part (appendfile), Private options for appendfile @findex suffix (appendfile) @unnumberedsubsec suffix (appendfile) Type: string, expanded@* Default: "\n" The string specified here is expanded and output at the end of every message. The default blank line can be suppressed by setting @example suffix = @end example and this is usually necessary when doing batch SMTP deliveries, or delivering into individual files or MBX-format mailboxes. @node use_crlf (appendfile), use_fcntl_lock (appendfile), suffix (appendfile), Private options for appendfile @findex use_crlf (appendfile) @unnumberedsubsec use_crlf (appendfile) Type: boolean@* Default: false @cindex CR @cindex LF @cindex carriage return @cindex linefeed 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. The contents of the @dfn{prefix} and @dfn{suffix} options are written verbatim, so must contain their own carriage return characters if these are needed. Since the default values for both @dfn{prefix} and @dfn{suffix} end with a single linefeed, their values almost always need to be changed if @dfn{use_crlf} is set. @node use_fcntl_lock (appendfile), use_lockfile (appendfile), use_crlf (appendfile), Private options for appendfile @findex use_fcntl_lock (appendfile) @unnumberedsubsec use_fcntl_lock (appendfile) Type: boolean@* Default: see below This option controls the use of the @dfn{fcntl()} function to lock a file for exclusive use when a message is being appended. It is set by default unless @dfn{use_mbx_lock} is set. Otherwise, it should be turned off only if you know that all your MUAs use lock file locking. When @dfn{use_fcntl_lock} is off, @dfn{use_lockfile} and @dfn{require_lockfile} must both be on if @dfn{mbx_format} is not set. @node use_lockfile (appendfile), use_mbx_lock (appendfile), use_fcntl_lock (appendfile), Private options for appendfile @findex use_lockfile (appendfile) @unnumberedsubsec use_lockfile (appendfile) Type: boolean@* Default: see below If this option is turned off, Exim does not attempt to create a lock file when appending to a file. Thus the only locking is by @dfn{fcntl()}. This option is set by default unless @dfn{use_mbx_lock} is set. It is not possible to turn both @dfn{use_lockfile} and @dfn{use_fcntl_lock} off, except when @dfn{mbx_format} is set. You should only turn @dfn{use_lockfile} off if you are absolutely sure that every MUA that is ever going to look at your users' mailboxes uses @dfn{fcntl()} rather than a lock file, and even then only when you are not delivering over NFS from more than one host. @cindex NFS: lock file In order to append to an NFS file safely from more than one host, it is necessary to take out a lock @dfn{before} opening the file, and the lock file achieves this. Otherwise, even with @dfn{fcntl()} locking, there is a risk of file corruption. See also the @dfn{require_lockfile} option. @node use_mbx_lock (appendfile), user (appendfile), use_lockfile (appendfile), Private options for appendfile @findex use_mbx_lock (appendfile) @unnumberedsubsec use_mbx_lock (appendfile) Type: boolean@* Default: see below This option is available only if Exim has been compiled with @sc{support_mbx} set in @file{Local/Makefile}. Setting the option specifies that special MBX locking rules be used. It is set by default if @dfn{mbx_format} is set and none of the locking options are mentioned in the configuration. The locking rules are the same as are used by the @dfn{c-client} library that underlies Pine4 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. @node user (appendfile), , use_mbx_lock (appendfile), Private options for appendfile @findex user (appendfile) @unnumberedsubsec user (appendfile) Type: string@* Default: unset @cindex uid: local delivery If this option is set, it specifies the user under whose uid the delivery process is to be run, and which must be the owner of an existing file to which the message is appended. If the option is not set, a value must have been associated with the address by the director that handled it. If the string contains no $ characters, it is resolved when Exim starts up. Otherwise, the string is expanded at the time the transport is run, and must yield either a digit string or a name which can be looked up using @dfn{getpwnam()}. When @dfn{getpwnam()} is used, either at start-up time or later, the group id value associated with the user is taken as the value to be used if the @dfn{group} option is not set. @node Operational details for appending, Operational details for delivery to a new file, Private options for appendfile, 15[[[]]] The appendfile transport @section 15[[[]]]2 Operational details for appending @cindex appending to a file @cindex file: appending Before appending to a file, Exim proceeds as follows: @itemize @bullet @item If the name of the file is @dfn{/dev/null}, no action is taken, and a success return is given. @item @cindex directory creation If any directories on the file's path are missing, Exim creates them if the @dfn{create_directory} option is set. A created directory's mode is given by the @dfn{directory_mode} option. @item If @dfn{file_format} 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. @item @cindex file: locking @cindex locking files @cindex NFS: lock file If @dfn{use_lockfile} is set, a lock file is built in a way that will work reliably over NFS, as follows: @itemize @bullet @item 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, the message is frozen unless @dfn{require_lockfile} is false. Otherwise delivery is deferred. @item Close the hitching post file, and hard link it to the lock file name. @item If the call to @dfn{link()} succeeds, creation of the lock file has succeeded. Unlink the hitching post name. @item Otherwise, use @dfn{stat()} 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 @dfn{link()} call. @item If creation of the lock file failed, wait for @dfn{lock_interval} and try again, up to @dfn{lock_retries} 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 @dfn{lockfile_timeout} Exim attempts to unlink it before trying again. @end itemize @item A call is made to @dfn{lstat()} to discover whether the main file exists, and if so, what its characteristics are. If @dfn{lstat()} fails for any reason other than non-existence, delivery is deferred. @item @cindex symbolic link @cindex link, symbolic @cindex mailbox: symbolic link If the file does exist and is a symbolic link, delivery is deferred and the message is frozen, unless the @dfn{allow_symlinks} option is set, in which case the ownership of the link is checked, and then @dfn{stat()} 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. @item 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 @dfn{check_group} above) are different from the user and group under which the delivery is running, delivery is deferred, and the message is frozen. @item If the file's permissions are more generous than specified, they are reduced. If they are insufficient, delivery is deferred, and the message is frozen, unless @dfn{mode_fail_narrower} is set false, in which case the delivery is tried using the existing permissions. @item The file's inode number is saved, and it is then opened for appending. If this fails because the file has vanished, @dfn{appendfile} behaves as if it hadn't existed (see below). If the open failure is @sc{ewouldblock}, just defer delivery; otherwise defer and freeze the message. @item 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 and freeze the message. @item If the file did not exist originally, defer delivery and freeze the message if the @dfn{file_must_exist} option is set. Otherwise, check that the file is being created in a permitted directory if the @dfn{create_file} option is set (deferring and freezing on failure), and then open for writing as a new file, with the @sc{o_excl} and @sc{o_creat} options, except when dealing with a symbolic link (the @dfn{allow_symlinks} 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 @sc{o_creat} but not @sc{o_excl}, because that prevents link following. @item @cindex loop: while file testing 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. @item If opening fails with any other error, defer delivery. @item @cindex file: locking @cindex locking files Once the file is open, unless both @dfn{use_fcntl_lock} and @dfn{use_mbx_lock} are false, it is locked using @dfn{fcntl()}. In the former case, an exclusive lock is requested, while in the latter, Exim takes out a shared lock on the open file, and an exclusive lock on the file whose name is @example /tmp/.<@dfn{device-number}>.<@dfn{inode-number}> @end example using the device and inode numbers of the open mailbox file, in accordance with the MBX locking rules. If @dfn{fcntl()} locking fails, there are two possible courses of action, depending on the value of @dfn{lock_fcntl_timeout}. If its value is zero, the file is closed, Exim waits for @dfn{lock_interval} and then goes back and re-opens it as above and tries to lock it again. This happens up to @dfn{lock_retries} times, after which the delivery is deferred. If @dfn{loc