+The \freeze\ command is ignored if the message has been manually unfrozen and
+not manually frozen since. This means that automatic freezing by a system
+filter can be used as a way of checking out suspicious messages. If a message
+is found to be all right, manually unfreezing it allows it to be delivered.
+
+.index log||\fail\ command log line
+.index \fail\||log line, reducing
+The text given with a fail command is used as part of the bounce message as
+well as being written to the log. If the message is quite long, this can fill
+up a lot of log space when such failures are common. To reduce the size of the
+log message, Exim interprets the text in a special way if it starts with the
+two characters \"@<@<"\ and contains \"@>@>"\ later. The text between these two
+strings is written to the log, and the rest of the text is used in the bounce
+message. For example:
+.display asis
+fail "<<filter test 1>>Your message is rejected \
+ because it contains attachments that we are \
+ not prepared to receive."
+.endd
+
+.index loop||caused by \fail\
+Take great care with the \fail\ command when basing the decision to fail on the
+contents of the message, because the bounce message will of course include the
+contents of the original message and will therefore trigger the \fail\ command
+again (causing a mail loop) unless steps are taken to prevent this. Testing the
+\error@_message\ condition is one way to prevent this. You could use, for
+example
+.display asis
+if $message_body contains "this is spam" and not error_message
+ then fail text "spam is not wanted here" endif
+.endd
+though of course that might let through unwanted bounce messages. The
+alternative is clever checking of the body and/or headers to detect bounces
+generated by the filter.
+
+The interpretation of a system filter file ceases after a
+\defer\,
+\freeze\, or \fail\ command is obeyed. However, any deliveries that were set up
+earlier in the filter file are honoured, so you can use a sequence such as
+.display asis
+mail ...
+freeze
+.endd
+to send a specified message when the system filter is freezing (or deferring or
+failing) a message. The normal deliveries for the message do not, of course,
+take place.
+
+
+.section Adding and removing headers in a system filter
+.rset SECTaddremheasys "~~chapter.~~section"
+.index header lines||adding, in system filter
+.index header lines||removing, in system filter
+.index filter||header lines, adding/removing
+Two filter commands that are available only in system filters are:
+.display
+headers add <<string>>
+headers remove <<string>>
+.endd
+The argument for the \headers add\ is a string that is expanded and then added
+to the end of the message's headers. It is the responsibility of the filter
+maintainer to make sure it conforms to RFC 2822 syntax. Leading white space is
+ignored, and if the string is otherwise empty, or if the expansion is forced to
+fail, the command has no effect.
+
+You can use `@\n' within the string, followed by white space, to specify
+continued header lines. More than one header may be added in one command by
+including `@\n' within the string without any following white space. For
+example:
+.display asis
+headers add "X-header-1: ....\n \
+ continuation of X-header-1 ...\n\
+ X-header-2: ...."
+.endd
+Note that the header line continuation white space after the first newline must
+be placed before the backslash that continues the input string, because white
+space after input continuations is ignored.
+
+The argument for \headers remove\ is a colon-separated list of header names.
+This command applies only to those headers that are stored with the message;
+those that are added at delivery time (such as ::Envelope-To:: and
+::Return-Path::) cannot be removed by this means. If there is more than one
+header with the same name, they are all removed.
+
+.em
+The \headers\ command in a system filter makes an immediate change to the set
+of header lines that was received with the message (with possible additions
+from ACL processing). Subsequent commands in the system filter operate on the
+modified set, which also forms the basis for subsequent message delivery.
+Unless further modified during routing or transporting, this set of headers is
+used for all recipients of the message.
+
+During routing and transporting, the variables that refer to the contents of
+header lines refer only to those lines that are in this set. Thus, header lines
+that are added by a system filter are visible to users' filter files and to all
+routers and transports. This contrasts with the manipulation of header lines by
+routers and transports, which is not immediate, but which instead is saved up
+until the message is actually being written (see section ~~SECTheadersaddrem).
+
+If the message is not delivered at the first attempt, header lines that were
+added by the system filter are stored with the message, and so are still
+present at the next delivery attempt. Header lines that were removed are still
+present, but marked `deleted' so that they are not transported with the
+message. For this reason, it is usual to make the \headers\ command conditional
+on \first@_delivery\ so that the set of header lines is not modified more than
+once.
+
+Because header modification in a system filter acts immediately, you have to
+use an indirect approach if you want to modify the contents of a header line.
+For example:
+.display asis
+headers add "Old-Subject: $h_subject:"
+headers remove "Subject"
+headers add "Subject: new subject (was: $h_old-subject:)"
+headers remove "Old-Subject"
+.endd
+.nem
+
+
+
+.section Setting an errors address in a system filter
+.index envelope sender
+In a system filter, if a \deliver\ command is followed by
+.display
+errors@_to <<some address>>
+.endd
+in order to change the envelope sender (and hence the error reporting) for that
+delivery, any address may be specified. (In a user filter, only the current
+user's address can be set.) For example, if some mail is being monitored, you
+might use
+.display asis
+unseen deliver monitor@spying.example errors_to root@local.example
+.endd
+to take a copy which would not be sent back to the normal error reporting
+address if its delivery failed.
+
+
+.section Per-address filtering
+.rset SECTperaddfil "~~chapter.~~section"
+In contrast to the system filter, which is run just once per message for each
+delivery attempt, it is also possible to set up a system-wide filtering
+operation that runs once for each recipient address. In this case, variables
+such as \$local@_part$\ and \$domain$\ can be used, and indeed, the choice of
+filter file could be made dependent on them. This is an example of a router
+which implements such a filter:
+.display asis
+central_filter:
+.newline
+ check_local_user
+.newline
+ driver = redirect
+ domains = +local_domains
+ file = /central/filters/$local_part
+ no_verify
+ allow_filter
+ allow_freeze
+.endd
+The filter is run in a separate process under its own uid. Therefore, either
+\check@_local@_user\ must be set (as above), in which case the filter is run as
+the local user, or the \user\ option must be used to specify which user to use.
+If both are set, \user\ overrides.
+
+Care should be taken to ensure that none of the commands in the filter file
+specify a significant delivery if the message is to go on to be delivered to
+its intended recipient. The router will not then claim to have dealt with the
+address, so it will be passed on to subsequent routers to be delivered in the
+normal way.
+
+
+
+
+
+
+.
+.
+.
+.
+. ============================================================================
+.chapter Message processing
+.set runningfoot "message processing"
+.rset CHAPmsgproc "~~chapter"
+.index message||general processing
+Exim performs various transformations on the sender and recipient addresses of
+all messages that it handles, and also on the messages' header lines. Some of
+these are optional and configurable, while others always take place. All of
+this processing, except rewriting as a result of routing, and the addition or
+removal of header lines while delivering, happens when a message is received,
+before it is placed on Exim's queue.
+
+Some of the automatic processing takes place by default only for
+`locally-originated' messages. This adjective is used to describe messages that
+are not received over TCP/IP, but instead are passed to an Exim process on its
+standard input. This includes the interactive `local SMTP' case that is set up
+by the \-bs-\ command line option.
+
+\**Note**\: messages received over TCP/IP on the loopback interface (127.0.0.1
+or @:@:1) are not considered to be locally-originated. Exim does not treat the
+loopback interface specially in any way.
+.em
+If you want the loopback interface to be treated specially, you must ensure
+that there are appropriate entries in your ACLs.
+.nem
+
+
+.section Submission mode for non-local messages
+.rset SECTsubmodnon "~~chapter.~~section"
+.index message||submission
+.index submission mode
+.em
+Processing that happens automatically for locally-originated messages can also
+be requested for other messages. The term `submission mode' is used to describe
+this state. Submisssion mode is set by the modifier
+.display asis
+control = submission
+.endd
+in a \\MAIL\\, \\RCPT\\, or pre-data ACL for an incoming SMTP message (see
+sections ~~SECTACLmodi and ~~SECTcontrols). This makes Exim treat the message
+as a local submission, and is normally used when the source of the message is
+known to be an MUA running on a client host (as opposed to an MTA). For
+example, to set submission mode for messages originating on the IPv4 loopback
+interface, you could include the following in the \\MAIL\\ ACL:
+.display asis
+warn hosts = 127.0.0.1
+ control = submission
+.endd
+There are some options that can be used when setting submission mode. A slash
+is used to separate options. For example:
+.display asis
+control = submission/sender_retain
+.endd
+Specifying \sender@_retain\ has the effect of setting \local@_sender@_retain\
+true and \local@_from@_check\ false for the current incoming message. The first
+of these allows an existing ::Sender:: header in the message to remain, and the
+second suppresses the check to ensure that ::From:: matches the authenticated
+sender. With this setting, Exim still fixes up messages by adding ::Date:: and
+::Message-ID:: header lines if they are missing, but makes no attempt to check
+sender authenticity in header lines.
+
+A submission mode setting may also specify a domain to be used when generating
+a ::From:: or ::Sender:: header. For example:
+.display asis
+control = submission/domain=some.domain
+.endd
+The domain may be empty. How this value is used is described in sections
+~~SECTthefrohea and ~~SECTthesenhea.
+.nem
+
+
+
+.section Line endings
+.rset SECTlineendings "~~chapter.~~section"
+.index line endings
+.index carriage return
+.index linefeed
+RFC 2821 specifies that CRLF (two characters: carriage-return, followed by
+linefeed) is the line ending for messages transmitted over the Internet using
+SMTP over TCP/IP. However, within individual operating systems, different
+conventions are used. For example, Unix-like systems use just LF, but others
+use CRLF or just CR.
+
+Exim was designed for Unix-like systems, and internally, it stores messages
+using the system's convention of a single LF as a line terminator. When
+receiving a message, all line endings are translated to this standard format.
+Originally, it was thought that programs that passed messages directly to an
+MTA within an operating system would use that system's convention. Experience
+has shown that this is not the case; for example, there are Unix applications
+that use CRLF in this circumstance. For this reason, and for compatibility with
+other MTAs, the way Exim handles line endings for all messages is now as
+follows:
+.numberpars $.
+LF not preceded by CR is treated as a line ending.
+.nextp
+CR is treated as a line ending; if it is immediately followed by LF, the LF
+is ignored.
+.nextp
+The sequence `CR, dot, CR' does not terminate an incoming SMTP message,
+nor a local message in the state where a line containing only a dot is a
+terminator.
+.nextp
+If a bare CR is encountered within a header line, an extra space is added after
+the line terminator so as not to end the header line. The reasoning behind this
+is that bare CRs in header lines are most likely either to be mistakes, or
+people trying to play silly games.
+.nextp
+If the first header line received in a message ends with CRLF, a subsequent
+bare LF in a header line is treated in the same way as a bare CR in a header
+line.
+.endp
+
+
+
+.section Unqualified addresses
+.index unqualified addresses
+.index address||qualification
+By default, Exim expects every envelope address it receives from an external
+host to be fully qualified. Unqualified addresses cause negative responses to
+SMTP commands. However, because SMTP is used as a means of transporting
+messages from MUAs running on personal workstations, there is sometimes a
+requirement to accept unqualified addresses from specific hosts or IP networks.
+
+Exim has two options that separately control which hosts may send unqualified
+sender or receipient addresses in SMTP commands, namely
+\sender__unqualified__hosts\ and \recipient__unqualified__hosts\. In both
+cases, if an unqualified address is accepted, it is qualified by adding the
+value of \qualify__domain\ or \qualify__recipient\, as appropriate.
+.index \qualify@_domain\
+.index \qualify@_recipient\
+
+.em
+Unqualified addresses in header lines are automatically qualified for messages
+that are locally originated, unless the \-bnq-\ option is given on the command
+line. For messages received over SMTP, unqualified addresses in header lines
+are qualified only if unqualified addresses are permitted in SMTP commands. In
+other words, such qualification is also controlled by
+\sender__unqualified__hosts\ and \recipient__unqualified__hosts\,
+.nem
+
+
+.section The UUCP From line
+.index `From' line
+.index UUCP||`From' line
+.index sender||address
+.index \uucp@_from@_pattern\
+.index \uucp@_from@_sender\
+.index envelope sender
+.index Sendmail compatibility||`From' line
+Messages that have come from UUCP (and some other applications) often begin
+with a line containing the envelope sender and a timestamp, following the word
+`From'. Examples of two common formats are:
+.display asis
+From a.oakley@berlin.mus Fri Jan 5 12:35 GMT 1996
+From f.butler@berlin.mus Fri, 7 Jan 97 14:00:00 GMT
+.endd
+This line precedes the RFC 2822 header lines. For compatibility with Sendmail,
+Exim recognizes such lines at the start of messages that are submitted to it
+via the command line (that is, on the standard input). It does not recognize
+such lines in incoming SMTP messages, unless the sending host matches
+\ignore@_fromline@_hosts\ or the \-bs-\ option was used for a local message and
+\ignore@_fromline@_local\ is set. The recognition is controlled by a regular
+expression that is defined by the \uucp@_from@_pattern\ option, whose default
+value matches the two common cases shown above and puts the address that
+follows `From' into \$1$\.
+
+.index numerical variables (\$1$\, \$2$\, etc)||in `From ' line handling
+When the caller of Exim for a non-SMTP message that contains a `From' line is a
+trusted user, the message's sender address is constructed by expanding the
+contents of \uucp@_sender@_address\, whose default value is `@$1'. This is then
+parsed as an RFC 2822 address. If there is no domain, the local part is
+qualified with \qualify@_domain\ unless it is the empty string. However, if the
+command line \-f-\ option is used, it overrides the `From' line.
+
+If the caller of Exim is not trusted, the `From' line is recognized, but the
+sender address is not changed. This is also the case for incoming SMTP messages
+that are permitted to contain `From' lines.
+
+Only one `From' line is recognized. If there is more than one, the second is
+treated as a data line that starts the body of the message, as it is not valid
+as a header line. This also happens if a `From' line is present in an incoming
+SMTP message from a source that is not permitted to send them.
+
+
+.section Resent- header lines
+.index \Resent@-\ header lines
+RFC 2822 makes provision for sets of header lines starting with the string
+\"Resent-"\ to be added to a message when it is resent by the original
+recipient to somebody else. These headers are ::Resent-Date::, ::Resent-From::,
+::Resent-Sender::, ::Resent-To::, ::Resent-Cc::, ::Resent-Bcc:: and
+::Resent-Message-ID::. The RFC says:
+
+\*Resent fields are strictly informational. They MUST NOT be used in the normal
+processing of replies or other such automatic actions on messages.*\
+
+This leaves things a bit vague as far as other processing actions such as
+address rewriting are concerned. Exim treats \Resent@-\ header lines as
+follows:
+.numberpars $.
+A ::Resent-From:: line that just contains the login id of the submitting user
+is automatically rewritten in the same way as ::From:: (see below).
+.nextp
+If there's a rewriting rule for a particular header line, it is also applied to
+\Resent@-\ header lines of the same type. For example, a rule that rewrites
+::From:: also rewrites ::Resent-From::.
+.nextp
+For local messages, if ::Sender:: is removed on input, ::Resent-Sender:: is also
+removed.
+.nextp
+For a locally-submitted message,
+if there are any \Resent@-\ header lines but no ::Resent-Date::,
+::Resent-From::, or ::Resent-Message-Id::, they are added as necessary. It is
+the contents of ::Resent-Message-Id:: (rather than ::Message-Id::) which are
+included in log lines in this case.
+.nextp
+The logic for adding ::Sender:: is duplicated for ::Resent-Sender:: when any
+\Resent@-\ header lines are present.
+.endp
+
+
+.section The Auto-Submitted: header line
+Whenever Exim generates a bounce or a delay warning message, it includes the
+header line
+.display asis
+Auto-Submitted: auto-generated
+.endd
+
+
+.section The Bcc: header line
+.index ::Bcc:: header line
+If Exim is called with the \-t-\ option, to take recipient addresses from a
+message's header, it removes any ::Bcc:: header line that may exist (after
+extracting its addresses). If \-t-\ is not present on the command line, any
+existing ::Bcc:: is not removed.
+
+.section The Date: header line
+.index ::Date:: header line
+If a locally-generated
+or submission-mode
+message has no ::Date:: header line, Exim adds one, using the current date and
+time.
+
+.section The Delivery-date: header line
+.index ::Delivery-date:: header line
+.index \delivery@_date@_remove\
+::Delivery-date:: header lines are not part of the standard RFC 2822 header
+set. Exim can be configured to add them to the final delivery of messages. (See
+the generic \delivery@_date@_add\ transport option.) They should not be present
+in messages in transit. If the \delivery@_date@_remove\ configuration option is
+set (the default), Exim removes ::Delivery-date:: header lines from incoming
+messages.
+
+.section The Envelope-to: header line
+.index ::Envelope-to:: header line
+.index \envelope@_to@_remove\
+::Envelope-to:: header lines are not part of the standard RFC 2822 header set.
+Exim can be configured to add them to the final delivery of messages. (See the
+generic \envelope@_to@_add\ transport option.) They should not be present in
+messages in transit. If the \envelope@_to@_remove\ configuration option is set
+(the default), Exim removes ::Envelope-to:: header lines from incoming
+messages.
+
+.section The From: header line
+.rset SECTthefrohea "~~chapter.~~section"
+.index ::From:: header line
+.index Sendmail compatibility||`From' line
+.index message||submission
+.index submission mode
+If a submission-mode message does not contain a ::From:: header line, Exim adds
+one if either of the following conditions is true:
+.numberpars $.
+The envelope sender address is not empty (that is, this is not a bounce
+message). The added header line copies the envelope sender address.
+.nextp
+The SMTP session is authenticated and \$authenticated@_id$\ is not empty.
+.em
+.numberpars alpha
+If no domain is specified by the submission control, the local part is
+\$authenticated@_id$\ and the domain is \$qualify@_domain$\.
+.nextp
+If a non-empty domain is specified by the submission control, the local part is
+\$authenticated@_id$\, and the the domain is the specified domain.
+.nextp
+If an empty domain is specified by the submission control,
+\$authenticated@_id$\ is assumed to be the complete address.
+.endp
+.nem
+.endp
+A non-empty envelope sender takes precedence.
+
+If a locally-generated incoming message does not contain a ::From:: header
+line, Exim adds one containing the sender's address. The calling user's login
+name and full name are used to construct the address, as described in section
+~~SECTconstr. They are obtained from the password data by calling
+\*getpwuid()*\ (but see the \unknown@_login\ configuration option). The address
+is qualified with \qualify@_domain\.
+
+For compatibility with Sendmail, if an incoming, non-SMTP message has a
+::From:: header line containing just the unqualified login name of the calling
+user, this is replaced by an address containing the user's login name and full
+name as described in section ~~SECTconstr.
+
+.section The Message-ID: header line
+.index ::Message-ID:: header line
+.index message||submission
+If a locally-generated or submission-mode incoming message does not contain a
+::Message-ID:: or ::Resent-Message-ID:: header line, Exim adds one to the
+message. If there are any ::Resent-:: headers in the message, it creates
+::Resent-Message-ID::. The id is constructed from Exim's internal message id,
+preceded by the letter E to ensure it starts with a letter, and followed by @@
+and the primary host name. Additional information can be included in this
+header line by setting the
+.index \message@_id@_header@_text\
+\message@_id@_header@_text\ and/or \message__id__header__domain\ options.
+
+
+.section The Received: header line
+.index ::Received:: header line
+A ::Received:: header line is added at the start of every message. The contents
+are defined by the \received@_header@_text\ configuration option, and Exim
+automatically adds a semicolon and a timestamp to the configured string.
+
+The ::Received:: header is generated as soon as the message's header lines have
+been received. At this stage, the timestamp in the ::Received:: header line is
+the time that the message started to be received. This is the value that is
+seen by the \\DATA\\ ACL and by the \*local@_scan()*\ function.
+
+Once a message is accepted, the timestamp in the ::Received:: header line is
+changed to the time of acceptance, which is (apart from a small delay while the
+-H spool file is written) the earliest time at which delivery could start.
+
+
+.section The Return-path: header line
+.index ::Return-path:: header line
+.index \return@_path@_remove\
+::Return-path:: header lines are defined as something an MTA may insert when
+it does the final delivery of messages. (See the generic \return@_path@_add\
+transport option.) Therefore, they should not be present in messages in
+transit. If the \return@_path@_remove\ configuration option is set (the
+default), Exim removes ::Return-path:: header lines from incoming messages.
+
+
+.section The Sender: header line
+.rset SECTthesenhea "~~chapter.~~section"
+.index ::Sender:: header line
+.index message||submission
+For a locally-originated message from an untrusted user, Exim may remove an
+existing ::Sender:: header line, and it may add a new one. You can modify these
+actions by setting \local@_sender@_retain\ true or \local@_from@_check\ false.
+
+When a local message is received from an untrusted user and
+\local@_from@_check\ is true (the default), a check is made to see if the
+address given in the ::From:: header line is the correct (local) sender of the
+message. The address that is expected has the login name as the local part and
+the value of \qualify@_domain\ as the domain. Prefixes and suffixes for the
+local part can be permitted by setting \local@_from@_prefix\ and
+\local@_from@_suffix\ appropriately. If ::From:: does not contain the correct
+sender, a ::Sender:: line is added to the message.
+
+If you set \local@_from@_check\ false, this checking does not occur. However,
+the removal of an existing ::Sender:: line still happens, unless you also set
+\local@_sender@_retain\ to be true. It is not possible to set both of these
+options true at the same time.
+
+.em
+.index submission mode
+By default, no processing of ::Sender:: header lines is done for messages
+received over TCP/IP or for messages submitted by trusted users. However, when
+a message is received over TCP/IP in submission mode, and \sender@_retain\ is
+not specified on the submission control, the following processing takes place:
+
+First, any existing ::Sender:: lines are removed. Then, if the SMTP session is
+authenticated, and \$authenticated@_id$\ is not empty, a sender address is
+created as follows:
+.numberpars $.
+If no domain is specified by the submission control, the local part is
+\$authenticated@_id$\ and the domain is \$qualify@_domain$\.
+.nextp
+If a non-empty domain is specified by the submission control, the local part is
+\$authenticated@_id$\, and the the domain is the specified domain.
+.nextp
+If an empty domain is specified by the submission control,
+\$authenticated@_id$\ is assumed to be the complete address.
+.endp
+This address is compared with the address in the ::From:: header line. If they
+are different, a ::Sender:: header line containing the created address is
+added. Prefixes and suffixes for the local part in ::From:: can be permitted by
+setting \local@_from@_prefix\ and \local@_from@_suffix\ appropriately.
+.nem
+
+
+.section Adding and removing header lines in routers and transports
+.index header lines||adding, in router or transport
+.index header lines||removing, in router or transport
+.rset SECTheadersaddrem "~~chapter.~~section"
+.em
+When a message is delivered, the addition and removal of header lines can be
+specified in a system filter, or on any of the routers and transports that
+process the message. Section ~~SECTaddremheasys contains details about
+modifying headers in a system filter.
+
+In contrast to what happens in a system filter, header modifications that are
+specified on routers and transports apply only to the particular recipient
+addresses that are being processed by those routers and transports. These
+changes do not actually take place until a copy of the message is being
+transported. Therefore, they do not affect the basic set of header lines, and
+they do not affect the values of the variables that refer to header lines.
+
+For both routers and transports, the result of expanding a \headers@_add\
+option must be in the form of one or more RFC 2822 header lines, separated by
+newlines (coded as `@\n'). For example:
+.display asis
+headers_add = X-added-header: added by $primary_hostname\n\
+ X-added-second: another added header line
+.endd
+Exim does not check the syntax of these added header lines.
+
+The result of expanding \headers@_remove\ must consist of a colon-separated
+list of header names. This is confusing, because header names themselves are
+often terminated by colons. In this case, the colons are the list separators,
+not part of the names. For example:
+.display asis
+headers_remove = return-receipt-to:acknowledge-to
+.endd
+
+When \headers@_add\ or \headers@_remove\ is specified on a router, its value is
+expanded at routing time, and then associated with all addresses that are
+accepted by that router, and also with any new addresses that it generates. If
+an address passes through several routers as a result of aliasing or
+forwarding, the changes are cumulative.
+.index \unseen\ option
+However, this does not apply to multiple routers that result from the use of
+the \unseen\ option. Any header modifications that were specified by the
+`unseen' router or its predecessors apply only to the `unseen' delivery.
+
+Addresses that end up with different \headers@_add\ or \headers@_remove\
+settings cannot be delivered together in a batch, so a transport is always
+dealing with a set of addresses that have the same header-processing
+requirements.
+
+The transport starts by writing the original set of header lines that arrived
+with the message, possibly modified by the system filter. As it writes out
+these lines, it consults the list of header names that were attached to the
+recipient address(es) by \headers@_remove\ options in routers, and it also
+consults the transport's own \headers@_remove\ option. Header lines whose names
+are on either of these lists are not written out. If there are multiple
+instances of any listed header, they are all skipped.
+
+After the remaining original header lines have been written, new header
+lines that were specified by routers' \headers@_add\ options are written, in
+the order in which they were attached to the address. These are followed by any
+header lines specified by the transport's \headers@_add\ option.
+
+This way of handling header line modifications in routers and transports has
+the following consequences:
+.numberpars $.
+The original set of header lines, possibly modified by the system filter,
+remains `visible', in the sense that the \$header@_$\\*xxx*\ variables refer to
+it, at all times.
+.nextp
+Header lines that are added by a router's
+\headers@_add\ option are not accessible by means of the \$header@_$\\*xxx*\
+expansion syntax in subsequent routers or the transport.
+.nextp
+Conversely, header lines that are specified for removal by \headers@_remove\ in
+a router remain visible to subsequent routers and the transport.
+.nextp
+Headers added to an address by \headers@_add\ in a router cannot be removed by
+a later router or by a transport.
+.nextp
+An added header can refer to the contents of an original header that is to be
+removed, even it has the same name as the added header. For example:
+.display asis
+headers_remove = subject
+headers_add = Subject: new subject (was: $h_subject:)
+.endd
+.endp
+
+\**Warning**\: The \headers@_add\ and \headers@_remove\ options cannot be used
+for a \%redirect%\ router that has the \one@_time\ option set.
+.nem
+
+
+
+.section Constructed addresses
+.rset SECTconstr "~~chapter.~~section"
+.index address||constructed
+.index constructed address
+When Exim constructs a sender address for a locally-generated message, it uses
+the form
+.display
+<<user name>> <$$<<login>>@@<<qualify@_domain>>$$>
+.endd
+For example:
+.display asis
+Zaphod Beeblebrox <zaphod@end.univ.example>
+.endd
+The user name is obtained from the \-F-\ command line option if set, or
+otherwise by looking up the calling user by \*getpwuid()*\ and extracting the
+`gecos' field from the password entry. If the `gecos' field contains an
+ampersand character, this is replaced by the login name with the first letter
+upper cased, as is conventional in a number of operating systems. See the
+\gecos@_name\ option for a way to tailor the handling of the `gecos' field. The
+\unknown@_username\ option can be used to specify user names in cases when
+there is no password file entry.
+
+In all cases, the user name is made to conform to RFC 2822 by quoting all or
+parts of it if necessary. In addition, if it contains any non-printing
+characters, it is encoded as described in RFC 2047, which defines a way of
+including non-ASCII characters in header lines.
+The value of the \headers@_charset\ option specifies the name of the encoding
+that is used (the characters are assumed to be in this encoding).
+The setting of \print@_topbitchars\ controls whether characters with the top
+bit set (that is, with codes greater than 127) count as printing characters or
+not.
+
+
+.section Case of local parts
+.index case of local parts
+.index local part||case of
+RFC 2822 states that the case of letters in the local parts of addresses cannot
+be assumed to be non-significant. Exim preserves the case of local parts of
+addresses, but by default it uses a lower-cased form when it is routing,
+because on most Unix systems, usernames are in lower case and case-insensitive
+routing is required. However, any particular router can be made to use the
+original case for local parts by setting the \caseful@_local@_part\ generic
+router option.
+
+.index mixed-case login names
+If you must have mixed-case user names on your system, the best way to proceed,
+assuming you want case-independent handling of incoming email, is to set up
+your first router to convert incoming local parts in your domains to the
+correct case by means of a file lookup. For example:
+.display asis
+correct_case:
+ driver = redirect
+ domains = +local_domains
+ data = ${lookup{$local_part}cdb\
+ {/etc/usercased.cdb}{$value}fail}\
+ @$domain
+.endd
+For this router, the local part is forced to lower case by the default action
+(\caseful@_local@_part\ is not set). The lower-cased local part is used to look
+up a new local part in the correct case. If you then set \caseful@_local@_part\
+on any subsequent routers which process your domains, they will operate on
+local parts with the correct case in a case-sensitive manner.
+
+
+.section Dots in local parts
+.index dot||in local part
+.index local part||dots in
+RFC 2822 forbids empty components in local parts. That is, an unquoted local
+part may not begin or end with a dot, nor have two consecutive dots in the
+middle. However, it seems that many MTAs do not enforce this, so Exim permits
+empty components for compatibility.
+
+
+.section Rewriting addresses
+.index rewriting||addresses
+Rewriting of sender and recipient addresses, and addresses in headers, can
+happen automatically, or as the result of configuration options, as described
+in chapter ~~CHAPrewrite. The headers that may be affected by this are ::Bcc::,
+::Cc::, ::From::, ::Reply-To::, ::Sender::, and ::To::.
+
+Automatic rewriting includes qualification, as mentioned above. The other case
+in which it can happen is when an incomplete non-local domain is given. The
+routing process may cause this to be expanded into the full domain name. For
+example, a header such as
+.display asis
+To: hare@teaparty
+.endd
+might get rewritten as
+.display asis
+To: hare@teaparty.wonderland.fict.example
+.endd
+Rewriting as a result of routing is the one kind of message processing that
+does not happen at input time, as it cannot be done until the address has
+been routed.
+
+Strictly, one should not do $it{any} deliveries of a message until all its
+addresses have been routed, in case any of the headers get changed as a
+result of routing. However, doing this in practice would hold up many
+deliveries for unreasonable amounts of time, just because one address could not
+immediately be routed. Exim therefore does not delay other deliveries when
+routing of one or more addresses is deferred.
+
+
+.
+.
+.
+.
+. ============================================================================
+.chapter SMTP processing
+.set runningfoot "smtp processing"
+.rset CHAPSMTP ~~chapter
+.index SMTP||processing details
+.index LMTP||processing details
+Exim supports a number of different ways of using the SMTP protocol, and its
+LMTP variant, which is an interactive protocol for transferring messages into a
+closed mail store application. This chapter contains details of how SMTP is
+processed. For incoming mail, the following are available:
+.numberpars $.
+SMTP over TCP/IP (Exim daemon or \*inetd*\);
+.nextp
+SMTP over the standard input and output (the \-bs-\ option);
+.nextp
+Batched SMTP on the standard input (the \-bS-\ option).
+.endp
+For mail delivery, the following are available:
+.numberpars $.
+SMTP over TCP/IP (the \%smtp%\ transport);
+.nextp
+LMTP over TCP/IP (the \%smtp%\ transport with the \protocol\ option set to
+`lmtp');
+.nextp
+LMTP over a pipe to a process running in the local host (the \%lmtp%\
+transport);
+.nextp
+Batched SMTP to a file or pipe (the \%appendfile%\ and \%pipe%\ transports with
+the \use@_bsmtp\ option set).
+.endp
+\*Batched SMTP*\ is the name for a process in which batches of messages are
+stored in or read from files (or pipes), in a format in which SMTP commands are
+used to contain the envelope information.
+
+
+.section Outgoing SMTP and LMTP over TCP/IP
+.rset SECToutSMTPTCP "~~chapter.~~section"
+.index SMTP||outgoing over TCP/IP
+.index outgoing SMTP over TCP/IP
git://git.exim.org / exim.git / blobdiff