1 $Cambridge: exim/doc/doc-txt/NewStuff,v 1.3 2004/10/19 11:04:26 ph10 Exp $
6 This file contains descriptions of new features that have been added to Exim,
7 but have not yet made it into the main manual (which is most conveniently
8 updated when there is a relatively large batch of changes). The doc/ChangeLog
9 file contains a listing of all changes, including bug fixes.
15 1. There is a new build-time option called CONFIGURE_GROUP which works like
16 CONFIGURE_OWNER. It specifies one additional group that is permitted for
17 the runtime configuration file when the group write permission is set.
19 2. The "control=submission" facility has a new option /retain_sender. This
20 has the effect of setting local_sender_retain true and local_from_check
21 false for the incoming message in which it is encountered.
27 1. There is a new Boolean global option called mua_wrapper, defaulting false.
28 This causes Exim to run an a restricted mode, in order to provide a very
31 Background: On a personal computer, it is a common requirement for all
32 email to be sent to a smarthost. There are plenty of MUAs that can be
33 configured to operate that way, for all the popular operating systems.
34 However, there are MUAs for Unix-like systems that cannot be so configured:
35 they submit messages using the command line interface of
36 /usr/sbin/sendmail. In addition, utility programs such as cron submit
39 Requirement: The requirement is for something that can provide the
40 /usr/sbin/sendmail interface and deliver messages to a smarthost, but not
41 provide any queueing or retrying facilities. Furthermore, the delivery to
42 the smarthost should be synchronous, so that if it fails, the sending MUA
43 is immediately informed. In other words, we want something that in effect
44 converts a command-line MUA into a TCP/SMTP MUA.
46 Solutions: There are a number of applications (for example, ssmtp) that do
47 this job. However, people have found them to be lacking in various ways.
48 For instance, some sites want to allow aliasing and forwarding before
49 sending to the smarthost.
51 Using Exim: Exim already had the necessary infrastructure for doing this
52 job. Just a few tweaks were needed to make it behave as required, though it
53 is somewhat of an overkill to use a fully-featured MTA for this purpose.
55 Setting mua_wrapper=true causes Exim to run in a special mode where it
56 assumes that it is being used to "wrap" a command-line MUA in the manner
59 If you set mua_wrapper=true, you also need to provide a compatible router
60 and transport configuration. Typically there will be just one router and
61 one transport, sending everything to a smarthost.
63 When run in MUA wrapping mode, the behaviour of Exim changes in the
66 (a) A daemon cannot be run, nor will Exim accept incoming messages from
67 inetd. In other words, the only way to submit messages is via the
70 (b) Each message is synchonously delivered as soon as it is received (-odi
71 is assumed). All queueing options (queue_only, queue_smtp_domains,
72 control=queue, control=freeze in an ACL etc.) are quietly ignored. The
73 Exim reception process does not finish until the delivery attempt is
74 complete. If the delivery was successful, a zero return code is given.
76 (c) Address redirection is permitted, but the final routing for all
77 addresses must be to the same remote transport, and to the same list of
78 hosts. Furthermore, the return_address must be the same for all
79 recipients, as must any added or deleted header lines. In other words,
80 it must be possible to deliver the message in a single SMTP
81 transaction, however many recipients there are.
83 (d) If the conditions in (c) are not met, or if routing any address results
84 in a failure or defer status, or if Exim is unable to deliver all the
85 recipients successfully to one of the hosts immediately, delivery of
86 the entire message fails.
88 (e) Because no queueing is allowed, all failures are treated as permanent;
89 there is no distinction between 4xx and 5xx SMTP response codes from
90 the smarthost. Furthermore, because only a single yes/no response can
91 be given to the caller, it is not possible to deliver to some
92 recipients and not others. If there is an error (temporary or
93 permanent) for any recipient, all are failed.
95 (f) If more than one host is listed, Exim will try another host after a
96 connection failure or a timeout, in the normal way. However, if this
97 kind of failure happens for all the hosts, the delivery fails.
99 (g) When delivery fails, an error message is written to the standard error
100 stream (as well as to Exim's log), and Exim exits to the caller with a
101 return code value 1. The message is expunged from Exim's spool files.
102 No bounce messages are ever generated.
104 (h) No retry data is maintained, and any retry rules are ignored.
106 (i) A number of Exim options are overridden: deliver_drop_privilege is
107 forced true, max_rcpt in the smtp transport is forced to "unlimited",
108 remote_max_parallel is forced to one, and fallback hosts are ignored.
110 The overall effect is that Exim makes a single synchronous attempt to
111 deliver the message, failing if there is any kind of problem. Because no
112 local deliveries are done and no daemon can be run, Exim does not need root
113 privilege. It should be possible to run it setuid=exim instead of
114 setuid=root. See section 48.3 in the 4.40 manual for a general discussion
115 about the advantages and disadvantages of running without root privilege.
117 2. There have been problems with DNS servers when SRV records are looked up.
118 Some mis-behaving servers return a DNS error or timeout when a non-existent
119 SRV record is sought. Similar problems have in the past been reported for
120 MX records. The global dns_again_means_nonexist option can help with this
121 problem, but it is heavy-handed because it is a global option. There are
122 now two new options for the dnslookup router. They are called
123 srv_fail_domains and mx_fail_domains. In each case, the value is a domain
124 list. If an attempt to look up an SRV or MX record results in a DNS failure
125 or "try again" response, and the domain matches the relevant list, Exim
126 behaves as if the DNS had responded "no such record". In the case of an SRV
127 lookup, this means that the router proceeds to look for MX records; in the
128 case of an MX lookup, it proceeds to look for A or AAAA records, unless the
129 domain matches mx_domains.
131 3. The following functions are now available in the local_scan() API:
133 (a) void header_remove(int occurrence, uschar *name)
135 This function removes header lines. If "occurrence" is zero or negative,
136 all occurrences of the header are removed. If occurrence is greater
137 than zero, that particular instance of the header is removed. If no
138 header(s) can be found that match the specification, the function does
141 (b) BOOL header_testname(header_line *hdr, uschar *name, int length,
144 This function tests whether the given header has the given name. It
145 is not just a string comparison, because whitespace is permitted
146 between the name and the colon. If the "notdel" argument is TRUE, a
147 FALSE return is forced for all "deleted" headers; otherwise they are
148 not treated specially. For example:
150 if (header_testname(h, US"X-Spam", 6, TRUE)) ...
152 (c) void header_add_at_position(BOOL after, uschar *name, BOOL topnot,
153 int type, char *format, ...)
155 This function adds a new header line at a specified point in the header
156 chain. If "name" is NULL, the new header is added at the end of the
157 chain if "after" is TRUE, or at the start if "after" is FALSE. If
158 "name" is not NULL, the headers are searched for the first non-deleted
159 header that matches the name. If one is found, the new header is added
160 before it if "after" is FALSE. If "after" is true, the new header is
161 added after the found header and any adjacent subsequent ones with the
162 same name (even if marked "deleted"). If no matching non-deleted header
163 is found, the "topnot" option controls where the header is added. If it
164 is TRUE, addition is at the top; otherwise at the bottom. Thus, to add
165 a header after all the Received: headers, or at the top if there are no
166 Received: headers, you could use
168 header_add_at_position(TRUE, US"Received", TRUE, ' ', "X-xxx: ...");
170 Normally, there is always at least one non-deleted Received: header,
171 but there may not be if received_header_text expands to an empty
174 (d) BOOL receive_remove_recipient(uschar *recipient)
176 This is a convenience function to remove a named recipient from the
177 list of recipients. It returns TRUE if a recipient was removed, and
178 FALSE if no matching recipient could be found. The argument must be a
179 complete email address.
181 4. When an ACL "warn" statement adds one or more header lines to a message,
182 they are added at the end of the existing header lines by default. It is
183 now possible to specify that any particular header line should be added
184 right at the start (before all the Received: lines) or immediately after
185 the first block of Received: lines in the message. This is done by
186 specifying :at_start: or :after_received: (or, for completeness, :at_end:)
187 before the text of the header line. (Header text cannot start with a colon,
188 as there has to be a header name first.) For example:
190 warn message = :after_received:X-My-Header: something or other...
192 If more than one header is supplied in a single warn statement, each one is
193 treated independently and can therefore be placed differently. If you add
194 more than one line at the start, or after the Received: block, they will
195 end up in reverse order.
197 Warning: This facility currently applies only to header lines that are
198 added in an ACL. It does NOT work for header lines that are added in a
199 system filter or in a router or transport.
201 5. There is now a new error code that can be used in retry rules. Its name is
202 "rcpt_4xx", and there are three forms. A literal "rcpt_4xx" matches any 4xx
203 error received for an outgoing SMTP RCPT command; alternatively, either the
204 first or both of the x's can be given as digits, for example: "rcpt_45x" or
205 "rcpt_436". If you want (say) to recognize 452 errors given to RCPT
206 commands by a particular host, and have only a one-hour retry for them, you
207 can set up a retry rule of this form:
209 the.host.name rcpt_452 F,1h,10m
211 Naturally, this rule must come before any others that would match.
213 These new errors apply to both outgoing SMTP (the smtp transport) and
214 outgoing LMTP (either the lmtp transport, or the smtp transport in LMTP
215 mode). Note, however, that they apply only to responses to RCPT commands.
217 6. The "postmaster" option of the callout feature of address verification has
218 been extended to make it possible to use a non-empty MAIL FROM address when
219 checking a postmaster address. The new suboption is called "postmaster_
220 mailfrom", and you use it like this:
222 require verify = sender/callout=postmaster_mailfrom=abc@x.y.z
224 Providing this suboption causes the postmaster check to be done using the
225 given address. The original "postmaster" option is equivalent to
227 require verify = sender/callout=postmaster_mailfrom=
229 If both suboptions are present, the rightmost one overrides.
233 (1) If you use a non-empty sender address for postmaster checking, there is
234 the likelihood that the remote host will itself initiate a callout
235 check back to your host to check that address. As this is a "normal"
236 callout check, the sender will most probably be empty, thus avoiding
237 possible callout loops. However, to be on the safe side it would be
238 best to set up your own ACLs so that they do not do sender verification
239 checks when the recipient is the address you use for postmaster callout
242 (2) The caching arrangements for postmaster checking do NOT take account of
243 the sender address. It is assumed that either the empty address, or a
244 fixed non-empty address will be used. All that Exim remembers is that
245 the postmaster check for the domain succeeded or failed.
247 7. When verifying addresses in header lines using the verify=header_sender
248 option, Exim behaves by default as if the addresses are envelope sender
249 addresses from a message. Callout verification therefore tests to see
250 whether a bounce message could be delivered, by using an empty address in
251 the MAIL FROM command. However, it is arguable that these addresses might
252 never be used as envelope senders, and could therefore justifiably reject
253 bounce messages (empty senders). There is now an additional callout option
254 for verify=header_sender that allows you to specify what address to use in
255 the MAIL FROM command. You use it as in this example:
257 require verify = header_sender/callout=mailfrom=abcd@x.y.z
261 (1) As in the case of postmaster_mailfrom (see above), you should think
262 about possible loops.
264 (2) In this case, as in the case of recipient callouts with non-empty
265 senders (the use_sender option), caching is done on the basis of a
266 recipient/sender pair.
268 8. If you build Exim with USE_READLINE=yes in Local/Makefile, it will try to
269 load libreadline dynamically whenever the -be (test expansion) option is
270 used without command line arguments. If successful, it will then use
271 readline() for reading the test data. A line history is supported. By the
272 time Exim does this, it is running as the calling user, so this should not
273 cause any security problems. Security is the reason why this is NOT
274 supported for -bt or -bv, when Exim is running as root or exim,
275 respectively. Note that this option adds to the size of the Exim binary,
276 because the dynamic loading library is not otherwise included. On my
277 desktop it adds about 2.5K. You may need to add -ldl to EXTRA_LIBS when you
278 set USE_READLINE=yes.
280 9. Added ${str2b64:<string>} to the expansion operators. This operator
281 converts an arbitrary string into one that is base64 encoded.
283 10. A new authenticator, called cyrus_sasl, has been added. This requires
284 the presence of the Cyrus SASL library; it authenticates by calling this
285 library, which supports a number of authentication mechanisms, including
286 PLAIN and LOGIN, but also several others that Exim does not support
287 directly. The code for this authenticator was provided by Matthew
288 Byng-Maddick of A L Digital Ltd (http://www.aldigital.co.uk). Here follows
291 xx. THE CYRUS_SASL AUTHENTICATOR
293 The cyrus_sasl authenticator provides server support for the Cyrus library
294 Implementation of the RFC 2222 "Simple Authentication and Security Layer".
295 It provides a gatewaying mechanism directly to the Cyrus interface, so if
296 your Cyrus library can do, for example, CRAM-MD5, then so can the
297 cyrus_sasl authenticator. By default it uses the public name of the driver
298 to determine which mechanism to support.
300 Where access to some kind of secret file is required, for example in GSSAPI
301 or CRAM-MD5, it is worth noting that the authenticator runs as the exim
302 user, and that the Cyrus SASL library has no way of escalating privileges
303 by default. You may also find you need to set environment variables,
304 depending on the driver you are using.
306 xx.1 Using cyrus_sasl as a server
308 The cyrus_sasl authenticator has four private options. It puts the username
309 (on a successful authentication) into $1.
311 server_hostname Type: string* Default: $primary_hostname
313 This option selects the hostname that is used when communicating with
314 the library. It is up to the underlying SASL plug-in what it does with
317 server_mech Type: string Default: public_name
319 This option selects the authentication mechanism this driver should
320 use. It allows you to use a different underlying mechanism from the
321 advertised name. For example:
325 public_name = X-ANYTHING
326 server_mech = CRAM-MD5
329 server_realm Type: string Default: unset
331 This is the SASL realm that the server is claiming to be in.
333 server_service Type: string Default: "smtp"
335 This is the SASL service that the server claims to implement.
337 For straigthforward cases, you do not need to set any of the
338 authenticator's private options. All you need to do is to specify an
339 appropriate mechanism as the public name. Thus, if you have a SASL library
340 that supports CRAM-MD5 and PLAIN, you might have two authenticators as
345 public_name = CRAM-MD5
353 11. There is a new global option called tls_on_connect_ports. Its value must be
354 a list of port numbers; the most common use is expected to be
356 tls_on_connect_ports = 465
358 Setting this option has the same effect as -tls-on-connect on the command
359 line, but only for the specified ports. It applies to all connections, both
360 via the daemon and via inetd. You still need to specify all the ports for
361 the daemon (using daemon_smtp_ports or local_interfaces or the -X command
362 line option) because this option does not add an extra port -- rather, it
363 specifies different behaviour on a port that is defined elsewhere. The
364 -tls-on-connect command line option overrides tls_on_connect_ports, and
365 forces tls-on-connect for all ports.
367 12. There is a new ACL that is run when a DATA command is received, before the
368 data itself is received. The ACL is defined by acl_smtp_predata. (Compare
369 acl_smtp_data, which is run after the data has been received.)
370 This new ACL allows a negative response to be given to the DATA command
371 itself. Header lines added by MAIL or RCPT ACLs are not visible at this
372 time, but any that are defined here are visible when the acl_smtp_data ACL
375 13. The "control=submission" ACL modifier has an option "/domain=xxx" which
376 specifies the domain to be used when creating From: or Sender: lines using
377 the authenticated id as a local part. If the option is supplied with an
378 empty domain, that is, just "/domain=", Exim assumes that the authenticated
379 id is a complete email address, and it uses it as is when creating From:
382 14. It is now possible to make retry rules that apply only when the failing
383 message has a specific sender. In particular, this can be used to define
384 retry rules that apply only to bounce messages. The syntax is to add a new
385 third item to a retry rule, of the form "senders=<address list>". The retry
386 timings themselves then become the fourth item. For example:
388 * * senders=: F,1h,30m
390 would match all bounce messages. If the address list contains white space,
391 it must be enclosed in quotes. For example:
393 a.domain timeout senders="x@b.dom : y@c.dom" G,8h,10m,1.5
395 When testing retry rules using -brt, you can supply a sender using the -f
396 command line option, like this:
398 exim -f "" -brt user@dom.ain
400 If you do not set -f with -brt, a retry rule that contains a senders list
401 will never be matched.
403 15. Two new control modifiers have been added to ACLs: "control = enforce_sync"
404 and "control = no_enforce_sync". This makes it possible to be selective
405 about when SMTP synchronization is enforced. The global option
406 smtp_enforce_sync now specifies the default state of the switch. These
407 controls can appear in any ACL, but the most obvious place to put them is
408 in the ACL defined by acl_smtp_connect, which is run at the start of an
409 incoming SMTP connection, before the first synchronization check.
411 16. Another two new control modifiers are "control = caseful_local_part" and
412 "control = caselower_local_part". These are permitted only in the ACL
413 specified by acl_smtp_rcpt (i.e. during RCPT processing). By default, the
414 contents of $local_part are lower cased before ACL processing.
415 After "control = caseful_local_part", any uppercase letters in the original
416 local part are restored in $local_part for the rest of the ACL, or until
417 "control = caselower_local_part" is encountered. However, this applies only
418 to local part handling that takes place directly in the ACL (for example,
419 as a key in lookups). If a "verify = recipient" test is obeyed, the
420 case-related handling of the local part during the verification is
421 controlled by the router configuration (see the caseful_local_part generic
424 This facility could be used, for example, to add a spam score to local
425 parts containing upper case letters. For example, using $acl_m4 to
426 accumulate the spam score:
428 warn control = caseful_local_part
429 set acl_m4 = ${eval:\
431 ${if match{$local_part}{[A-Z]}{1}{0}}\
433 control = caselower_local_part
435 Notice that we put back the lower cased version afterwards, assuming that
436 is what is wanted for subsequent tests.
438 17. The option hosts_connection_nolog is provided so that certain hosts can be
439 excepted from logging when the +smtp_connection log selector is set. For
440 example, you might want not to log SMTP connections from local processes,
441 or from 127.0.0.1, or from your local LAN. The option is a host list with
442 an unset default. Because it is consulted in the main loop of the daemon,
443 you should strive to restrict its value to a short inline list of IP
444 addresses and networks. To disable logging SMTP connections from local
445 processes, you must create a host list with an empty item. For example:
447 hosts_connection_nolog = :
449 If the +smtp_connection log selector is not set, this option has no effect.
451 18. There is now an acl called acl_smtp_quit, which is run for the QUIT
452 command. The outcome of the ACL does not affect the response code to QUIT,
453 which is always 221. Thus, the ACL does not in fact control any access.
454 For this reason, the only verbs that are permitted are "accept" and "warn".
456 The ACL can be used for tasks such as custom logging at the end of an SMTP
457 session. For example, you can use ACL variables in other ACLs to count
458 messages, recipients, etc., and log the totals at QUIT time using one or
459 more "logwrite" modifiers on a "warn" command.
461 You do not need to have a final "accept", but if you do, you can use a
462 "message" modifier to specify custom text that is sent as part of the 221
465 This ACL is run only for a "normal" QUIT. For certain kinds of disastrous
466 failure (for example, failure to open a log file, or when Exim is bombing
467 out because it has detected an unrecoverable error), all SMTP commands
468 from the client are given temporary error responses until QUIT is received
469 or the connection is closed. In these special cases, the ACL is not run.
471 19. The appendfile transport has two new options, mailbox_size and mailbox_
472 filecount. If either these options are set, it is expanded, and the result
473 is taken as the current size of the mailbox or the number of files in the
474 mailbox, respectively. This makes it possible to use some external means of
475 maintaining the data about the size of a mailbox for enforcing quota
476 limits. The result of expanding these option values must be a decimal
477 number, optionally followed by "K" or "M".
479 20. It seems that there are broken clients in use that cannot handle multiline
480 SMTP responses. Can't people who implement these braindead programs read?
481 RFC 821 mentions multiline responses, and it is over 20 years old. They
482 must handle multiline responses for EHLO, or do they still use HELO?
483 Anyway, here is YAWFAB (yet another workaround for asinine brokenness).
484 There's a new ACL switch that can be set by
486 control = no_multiline_responses
488 If this is set, it suppresses multiline SMTP responses from ACL rejections.
489 One way of doing this would have been just to put out these responses as
490 one long line. However, RFC 2821 specifies a maximum of 512 bytes per
491 response ("use multiline responses for more" it says), and some of the
492 responses might get close to that. So I have implemented this by doing two
495 (1) Extra information that is normally output as part of a rejection
496 caused by sender verification failure is omitted. Only the final line
497 (typically "sender verification failed") is now sent.
499 (2) If a "message" modifier supplies a multiline response, only the first
502 The setting of the switch can, of course, be made conditional on the
505 21. There is now support for the libradius library that comes with FreeBSD.
506 This is an alternative to the radiusclient library that Exim already
507 supports. To use the FreeBSD library, you need to set
509 RADIUS_LIB_TYPE=RADLIB
511 in Local/Makefile, in addition to RADIUS_CONFIGURE_FILE, and you probably
512 also need -libradius in EXTRALIBS.
518 1. The "personal" filter test is brought up-to-date with recommendations from
519 the Sieve specification: (a) The list of non-personal From: addresses now
520 includes "listserv", "majordomo", and "*-request"; (b) If the message
521 contains any header line starting with "List=-" it is treated as
524 2. The Sieve functionality has been extended to support the "copy" and
525 "vacation" extensions, and comparison tests.
527 3. There is now an overall timeout for performing a callout verification. It
528 defaults to 4 times the callout timeout, which applies to individual SMTP
529 commands during the callout. The overall timeout applies when there is more
530 than one host that can be tried. The timeout is checked before trying the
531 next host. This prevents very long delays if there are a large number of
532 hosts and all are timing out (e.g. when the network connections are timing
533 out). The value of the overall timeout can be changed by specifying an
534 additional sub-option for "callout", called "maxwait". For example:
536 verify = sender/callout=5s,maxwait=20s
538 4. Changes to the "personal" filter test:
540 (1) The list of non-personal local parts in From: addresses has been
541 extended to include "listserv", "majordomo", "*-request", and "owner-*",
542 taken from the Sieve specification recommendations.
544 (2) If the message contains any header line starting with "List-" it is
545 treated as non-personal.
547 (3) The test for "circular" in the Subject: header line has been removed
548 because it now seems ill-conceived.
550 5. The autoreply transport has a new option called never_mail. This is an
551 address list. If any run of the transport creates a message with a
552 recipient that matches any item in the list, that recipient is quietly
553 discarded. If all recipients are discarded, no message is created.
559 The documentation is up-to-date for the 4.40 release. What follows here is a
560 brief list of the new features that have been added since 4.30.
562 1. log_incoming_interface affects more log lines.
564 2. New ACL modifier "control = submission".
566 3. CONFIGURE_OWNER can be set at build time to define an alternative owner for
567 the configuration file, in addition to root and exim.
569 4. Added expansion variables $body_zerocount, $recipient_data, and
572 5. The time of last modification of the "new" subdirectory is now used as the
573 "mailbox time last read" when there is a quota error for a maildir
576 6. The special item "+ignore_unknown" may now appear in host lists.
578 7. The special domain-matching patterns @mx_any, @mx_primary, and
579 @mx_secondary can now be followed by "/ignore=<ip list>".
581 8. New expansion conditions: match_domain, match_address, match_local_part,
582 lt, lti, le, lei, gt, gti, ge, and new expansion operators time_interval,
585 9. New lookup type called "iplsearch".
587 10. New log selectors ident_timeout, tls_certificate_verified, queue_time,
588 deliver_time, outgoing_port, return_path_on_delivery.
590 11. New global options smtp_active_hostname and tls_require_ciphers.
592 12. Exinext has -C and -D options.
594 13. "domainlist_cache" forces caching of an apparently variable list.
596 14. For compatibility with Sendmail, the command line option -prval:sval
597 is equivalent to -oMr rval -oMs sval.
599 15. New callout options use_sender and use_postmaster for use when verifying
602 16. John Jetmore's "exipick" utility has been added to the distribution.
604 17. The TLS code now supports CRLs.
606 18. The dnslookup router and the dnsdb lookup type now support the use of SRV
609 19. The redirect router has a new option called qualify_domain.
611 20. exigrep's output now also includes lines that are not related to any
612 particular message, but which do match the pattern.
614 21. New global option write_rejectlog. If it is set false, Exim no longer
615 writes anything to the reject log.
projects / exim.git / blob