X-Git-Url: https://git.exim.org/exim.git/blobdiff_plain/03d5892bcac72a75433b2fa1280d81976772ba1b..3555c705d667038a1037d72511b277473f1a7248:/doc/doc-docbook/spec.xfpt diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt index e30f17cc0..331e56021 100644 --- a/doc/doc-docbook/spec.xfpt +++ b/doc/doc-docbook/spec.xfpt @@ -45,14 +45,14 @@ . Update the Copyright year (only) when changing content. . ///////////////////////////////////////////////////////////////////////////// -.set previousversion "4.87" +.set previousversion "4.91" .include ./local_params .set ACL "access control lists (ACLs)" .set I "    " .macro copyyear -2016 +2018 .endmacro . ///////////////////////////////////////////////////////////////////////////// @@ -392,7 +392,7 @@ very wide interest. An &"easier"& discussion of Exim which provides more in-depth explanatory, introductory, and tutorial material can be found in a book entitled &'The Exim SMTP Mail Server'& (second edition, 2007), published by UIT Cambridge -(&url(http://www.uit.co.uk/exim-book/)). +(&url(https://www.uit.co.uk/exim-book/)). This book also contains a chapter that gives a general introduction to SMTP and Internet mail. Inevitably, however, the book is unlikely to be fully up-to-date @@ -436,6 +436,7 @@ directory are: .row &_filter.txt_& "specification of the filter language" .row &_Exim3.upgrade_& "upgrade notes from release 2 to release 3" .row &_Exim4.upgrade_& "upgrade notes from release 3 to release 4" +.row &_openssl.txt_& "installing a current OpenSSL release" .endtable The main specification and the specification of the filtering language are also @@ -447,26 +448,25 @@ available in other formats (HTML, PostScript, PDF, and Texinfo). Section .section "FTP and web sites" "SECID2" .cindex "web site" .cindex "FTP site" -The primary site for Exim source distributions is currently the University of -Cambridge's FTP site, whose contents are described in &'Where to find the Exim -distribution'& below. In addition, there is a web site and an FTP site at -&%exim.org%&. These are now also hosted at the University of Cambridge. The -&%exim.org%& site was previously hosted for a number of years by Energis -Squared, formerly Planet Online Ltd, whose support I gratefully acknowledge. +The primary site for Exim source distributions is the &%exim.org%& FTP site, +available over HTTPS, HTTP and FTP. These services, and the &%exim.org%& +website, are hosted at the University of Cambridge. .cindex "wiki" .cindex "FAQ" As well as Exim distribution tar files, the Exim web site contains a number of differently formatted versions of the documentation. A recent addition to the -online information is the Exim wiki (&url(http://wiki.exim.org)), +online information is the Exim wiki (&url(https://wiki.exim.org)), which contains what used to be a separate FAQ, as well as various other examples, tips, and know-how that have been contributed by Exim users. +The wiki site should always redirect to the correct place, which is currently +provided by GitHub, and is open to editing by anyone with a GitHub account. .cindex Bugzilla -An Exim Bugzilla exists at &url(http://bugs.exim.org). You can use +An Exim Bugzilla exists at &url(https://bugs.exim.org). You can use this to report bugs, and also to add items to the wish list. Please search first to check that you are not duplicating a previous entry. - +Please do not ask for configuration help in the bug-tracker. .section "Mailing lists" "SECID3" @@ -487,23 +487,16 @@ If you are using a Debian distribution of Exim, you may wish to subscribe to the Debian-specific mailing list &'pkg-exim4-users@lists.alioth.debian.org'& via this web page: .display -&url(http://lists.alioth.debian.org/mailman/listinfo/pkg-exim4-users) +&url(https://alioth-lists.debian.net/cgi-bin/mailman/listinfo/pkg-exim4-users) .endd Please ask Debian-specific questions on this list and not on the general Exim lists. -.section "Exim training" "SECID4" -.cindex "training courses" -Training courses in Cambridge (UK) used to be run annually by the author of -Exim, before he retired. At the time of writing, there are no plans to run -further Exim courses in Cambridge. However, if that changes, relevant -information will be posted at &url(http://www-tus.csx.cam.ac.uk/courses/exim/). - .section "Bug reports" "SECID5" .cindex "bug reports" .cindex "reporting bugs" Reports of obvious bugs can be emailed to &'bugs@exim.org'& or reported -via the Bugzilla (&url(http://bugs.exim.org)). However, if you are unsure +via the Bugzilla (&url(https://bugs.exim.org)). However, if you are unsure whether some behaviour is a bug or not, the best thing to do is to post a message to the &'exim-dev'& mailing list and have it discussed. @@ -511,30 +504,41 @@ message to the &'exim-dev'& mailing list and have it discussed. .section "Where to find the Exim distribution" "SECTavail" .cindex "FTP site" +.cindex "HTTPS download site" .cindex "distribution" "ftp site" -The master ftp site for the Exim distribution is +.cindex "distribution" "https site" +The master distribution site for the Exim distribution is .display -&*ftp://ftp.csx.cam.ac.uk/pub/software/email/exim*& +&url(https://downloads.exim.org/) .endd -This is mirrored by -.display -&*ftp://ftp.exim.org/pub/exim*& -.endd -The file references that follow are relative to the &_exim_& directories at -these sites. There are now quite a number of independent mirror sites around +The service is available over HTTPS, HTTP and FTP. +We encourage people to migrate to HTTPS. + +The content served at &url(https://downloads.exim.org/) is identical to the +content served at &url(https://ftp.exim.org/pub/exim) and +&url(ftp://ftp.exim.org/pub/exim). + +If accessing via a hostname containing &'ftp'&, then the file references that +follow are relative to the &_exim_& directories at these sites. +If accessing via the hostname &'downloads'& then the subdirectories described +here are top-level directories. + +There are now quite a number of independent mirror sites around the world. Those that I know about are listed in the file called &_Mirrors_&. -Within the &_exim_& directory there are subdirectories called &_exim3_& (for +Within the top exim directory there are subdirectories called &_exim3_& (for previous Exim 3 distributions), &_exim4_& (for the latest Exim 4 distributions), and &_Testing_& for testing versions. In the &_exim4_& subdirectory, the current release can always be found in files called .display +&_exim-n.nn.tar.xz_& &_exim-n.nn.tar.gz_& &_exim-n.nn.tar.bz2_& .endd -where &'n.nn'& is the highest such version number in the directory. The two +where &'n.nn'& is the highest such version number in the directory. The three files contain identical data; the only difference is the type of compression. -The &_.bz2_& file is usually a lot smaller than the &_.gz_& file. +The &_.xz_& file is usually the smallest, while the &_.gz_& file is the +most portable to old systems. .cindex "distribution" "signing details" .cindex "distribution" "public key" @@ -548,17 +552,14 @@ PGP key, a version of which can be found in the release directory in the file &_nigel-pubkey.asc_&. All keys used will be available in public keyserver pools, such as &'pool.sks-keyservers.net'&. -At time of last update, releases were being made by Phil Pennock and signed with -key &'0x403043153903637F'&, although that key is expected to be replaced in 2013. -A trust path from Nigel's key to Phil's can be observed at -&url(https://www.security.spodhuis.org/exim-trustpath). - -Releases have also been authorized to be performed by Todd Lyons who signs with -key &'0xC4F4F94804D29EBA'&. A direct trust path exists between previous RE Phil -Pennock and Todd Lyons through a common associate. +At time of last update, releases were being made by Jeremy Harris and signed +with key &'0xBCE58C8CE41F32DF'&. Other recent keys used for signing are those +of Heiko Schlittermann, &'0x26101B62F69376CE'&, +and of Phil Pennock, &'0x4D1E900E14C1CC04'&. The signatures for the tar bundles are in: .display +&_exim-n.nn.tar.xz.asc_& &_exim-n.nn.tar.gz.asc_& &_exim-n.nn.tar.bz2.asc_& .endd @@ -577,7 +578,7 @@ inside the &_exim4_& directory of the FTP site: &_exim-texinfo-n.nn.tar.gz_& .endd These tar files contain only the &_doc_& directory, not the complete -distribution, and are also available in &_.bz2_& as well as &_.gz_& forms. +distribution, and are also available in &_.bz2_& and &_.xz_& forms. .section "Limitations" "SECID6" @@ -770,7 +771,7 @@ 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 -&url(http://www.pobox.com/~djb/cdb.html). This implementation borrows +&url(https://cr.yp.to/cdb.html). This implementation borrows some code from Dan Bernstein's implementation (which has no license restrictions applied to it). .endblockquote @@ -824,7 +825,7 @@ Redistributions of any form whatsoever must retain the following acknowledgment: &"This product includes software developed by Computing Services -at Carnegie Mellon University (&url(http://www.cmu.edu/computing/)."& +at Carnegie Mellon University (&url(https://www.cmu.edu/computing/)."& CARNEGIE MELLON UNIVERSITY DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY @@ -1363,6 +1364,7 @@ order in which they are tested. The individual configuration options are described in more detail in chapter &<>&. .ilist +.cindex affix "router precondition" The &%local_part_prefix%& and &%local_part_suffix%& options can specify that the local parts handled by the router may or must have certain prefixes and/or suffixes. If a mandatory affix (prefix or suffix) is not present, the router is @@ -1399,6 +1401,7 @@ of domains that it defines. .vindex "&$local_part_prefix$&" .vindex "&$local_part$&" .vindex "&$local_part_suffix$&" +.cindex affix "router precondition" If the &%local_parts%& option is set, the local part of the address must be in the set of local parts that it defines. If &%local_part_prefix%& or &%local_part_suffix%& is in use, the prefix or suffix is removed from the local @@ -1677,6 +1680,9 @@ 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. +.cindex compiler requirements +.cindex compiler version +A C99-capable compiler will be required for the build. .section "PCRE library" "SECTpcre" @@ -1692,7 +1698,7 @@ or set PCRE_CONFIG=yes to use the installed &(pcre-config)& command. If your operating system has no PCRE support then you will need to obtain and build the current PCRE from &url(ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/). -More information on PCRE is available at &url(http://www.pcre.org/). +More information on PCRE is available at &url(https://www.pcre.org/). .section "DBM libraries" "SECTdb" .cindex "DBM libraries" "discussion of" @@ -1745,14 +1751,18 @@ the traditional &'ndbm'& interface. .next To complicate things further, there are several very different versions of the Berkeley DB package. Version 1.85 was stable for a very long time, releases -2.&'x'& and 3.&'x'& were current for a while, but the latest versions are now -numbered 4.&'x'&. Maintenance of some of the earlier releases has ceased. All -versions of Berkeley DB can be obtained from -&url(http://www.sleepycat.com/). +2.&'x'& and 3.&'x'& were current for a while, but the latest versions when Exim last revamped support were numbered 4.&'x'&. +Maintenance of some of the earlier releases has ceased. All versions of +Berkeley DB could be obtained from +&url(http://www.sleepycat.com/), which is now a redirect to their new owner's +page with far newer versions listed. +It is probably wise to plan to move your storage configurations away from +Berkeley DB format, as today there are smaller and simpler alternatives more +suited to Exim's usage model. .next .cindex "&'tdb'& DBM library" Yet another DBM library, called &'tdb'&, is available from -&url(http://download.sourceforge.net/tdb). It has its own interface, and also +&url(https://sourceforge.net/projects/tdb/files/). It has its own interface, and also operates on a single file. .endlist @@ -1865,7 +1875,7 @@ supports the &[iconv()]& function. However, some of the operating systems that supply &[iconv()]& do not support very many conversions. The GNU &%libiconv%& library (available from -&url(http://www.gnu.org/software/libiconv/)) can be installed on such +&url(https://www.gnu.org/software/libiconv/)) can be installed on such systems to remedy this deficiency, as well as on systems that do not supply &[iconv()]& at all. After installing &%libiconv%&, you should add .code @@ -2627,6 +2637,8 @@ users to set envelope senders. .cindex "&'From:'& header line" .cindex "&'Sender:'& header line" +.cindex "header lines" "From:" +.cindex "header lines" "Sender:" For a trusted user, there is never any check on the contents of the &'From:'& header line, and a &'Sender:'& line is never added. Furthermore, any existing &'Sender:'& line in incoming local (non-TCP/IP) messages is not removed. @@ -2796,6 +2808,11 @@ files or databases you are using, you must exit and restart Exim before trying the same lookup again. Otherwise, because each Exim process caches the results of lookups, you will just get the same result as before. +Macro processing is done on lines before string-expansion: new macros can be +defined and macros will be expanded. +Because macros in the config file are often used for secrets, those are only +available to admin users. + .vitem &%-bem%&&~<&'filename'&> .oindex "&%-bem%&" .cindex "testing" "string expansion" @@ -2885,12 +2902,14 @@ actually being delivered. .vitem &%-bfp%&&~<&'prefix'&> .oindex "&%-bfp%&" +.cindex affix "filter testing" This sets the prefix of the local part of the recipient address when a filter file is being tested by means of the &%-bf%& option. The default is an empty prefix. .vitem &%-bfs%&&~<&'suffix'&> .oindex "&%-bfs%&" +.cindex affix "filter testing" This sets the suffix of the local part of the recipient address when a filter file is being tested by means of the &%-bf%& option. The default is an empty suffix. @@ -2946,7 +2965,7 @@ acceptable or not. See section &<>&. Features such as authentication and encryption, where the client input is not plain text, cannot easily be tested with &%-bh%&. Instead, you should use a specialized SMTP test program such as -&url(http://jetmore.org/john/code/#swaks,swaks). +&url(https://www.jetmore.org/john/code/swaks/,swaks). .vitem &%-bhc%&&~<&'IP&~address'&> .oindex "&%-bhc%&" @@ -3049,7 +3068,8 @@ trusted user for the sender of a message to be set in this way. .oindex "&%-bmalware%&" .cindex "testing", "malware" .cindex "malware scan test" -This debugging option causes Exim to scan the given file, +This debugging option causes Exim to scan the given file or directory +(depending on the used scanner interface), using the malware scanning framework. The option of &%av_scanner%& influences this option, so if &%av_scanner%&'s value is dependent upon an expansion then the expansion should have defaults which apply to this invocation. ACLs are @@ -3161,6 +3181,8 @@ If invoked by an admin user, then &%macro%&, &%macro_list%& and &%macros%& are available, similarly to the drivers. Because macros are sometimes used for storing passwords, this option is restricted. The output format is one item per line. +For the "-bP macro " form, if no such macro is found +the exit status will be nonzero. .vitem &%-bp%& .oindex "&%-bp%&" @@ -3598,7 +3620,8 @@ are: &<>&) &`lookup `& general lookup code and all lookups &`memory `& memory handling -&`pid `& add pid to debug output lines +&`noutf8 `& modifier: avoid UTF-8 line-drawing +&`pid `& modifier: add pid to debug output lines &`process_info `& setting info for the process log &`queue_run `& queue runs &`receive `& general message reception logic @@ -3606,7 +3629,7 @@ are: &`retry `& retry handling &`rewrite `& address rewriting &`route `& address routing -&`timestamp `& add timestamp to debug output lines +&`timestamp `& modifier: add timestamp to debug output lines &`tls `& TLS logic &`transport `& transports &`uid `& changes of uid/gid and looking up uid/gid @@ -3638,6 +3661,15 @@ The &`timestamp`& selector causes the current time to be inserted at the start of all debug output lines. This can be useful when trying to track down delays in processing. +.new +.cindex debugging "UTF-8 in" +.cindex UTF-8 "in debug output" +The &`noutf8`& selector disables the use of +UTF-8 line-drawing characters to group related information. +When disabled. ascii-art is used instead. +Using the &`+all`& option does not set this modifier, +.wen + If the &%debug_print%& option is set in any driver, it produces output whenever any debugging is selected, or if &%-v%& is used. @@ -3824,6 +3856,18 @@ This option is not intended for use by external callers. It is used internally by Exim in conjunction with the &%-MC%& option. It signifies that the remote host supports the ESMTP &_DSN_& extension. +.vitem &%-MCG%&&~<&'queue&~name'&> +.oindex "&%-MCG%&" +This option is not intended for use by external callers. It is used internally +by Exim in conjunction with the &%-MC%& option. It signifies that an +alternate queue is used, named by the following argument. + +.vitem &%-MCK%& +.oindex "&%-MCK%&" +This option is not intended for use by external callers. It is used internally +by Exim in conjunction with the &%-MC%& option. It signifies that a +remote host supports the ESMTP &_CHUNKING_& extension. + .vitem &%-MCP%& .oindex "&%-MCP%&" This option is not intended for use by external callers. It is used internally @@ -3852,6 +3896,13 @@ This option is not intended for use by external callers. It is used internally by Exim in conjunction with the &%-MC%& option, and passes on the fact that the host to which Exim is connected supports TLS encryption. +.vitem &%-MCt%&&~<&'IP&~address'&>&~<&'port'&>&~<&'cipher'&> +.oindex "&%-MCt%&" +This option is not intended for use by external callers. It is used internally +by Exim in conjunction with the &%-MC%& option, and passes on the fact that the +connection is being proxied by a parent process for handling TLS encryption. +The arguments give the local address and port being proxied, and the TLS cipher. + .vitem &%-Mc%&&~<&'message&~id'&>&~<&'message&~id'&>&~... .oindex "&%-Mc%&" .cindex "hints database" "not overridden by &%-Mc%&" @@ -3933,8 +3984,17 @@ 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. +. .new +. .vitem &%-MS%& +. .oindex "&%-MS%&" +. .cindex REQUIRETLS +. This option is used to request REQUIRETLS processing on the message. +. It is used internally by Exim in conjunction with -E when generating +. a bounce message. +. .wen + .vitem &%-Mset%&&~<&'message&~id'&> -.oindex "&%-Mset%& +.oindex "&%-Mset%&" .cindex "testing" "string expansion" .cindex "expansion" "testing" This option is useful only in conjunction with &%-be%& (that is, when testing @@ -4260,7 +4320,7 @@ or &%-bs%& is used. For &%-bh%&, the protocol is forced to one of the standard SMTP protocol names (see the description of &$received_protocol$& in section &<>&). For &%-bs%&, the protocol is always &"local-"& followed by one of those same names. For &%-bS%& (batched SMTP) however, the protocol can -be set by &%-oMr%&. +be set by &%-oMr%&. Repeated use of this option is not supported. .vitem &%-oMs%&&~<&'host&~name'&> .oindex "&%-oMs%&" @@ -4360,6 +4420,7 @@ host name and its colon can be omitted when only the protocol is to be set. Note the Exim already has two private options, &%-pd%& and &%-ps%&, that refer to embedded Perl. It is therefore impossible to set a protocol value of &`d`& or &`s`& using this option (but that does not seem a real limitation). +Repeated use of this option is not supported. .vitem &%-q%& .oindex "&%-q%&" @@ -4370,7 +4431,8 @@ relax this restriction (and also the same requirement for the &%-M%&, &%-R%&, and &%-S%& options). .cindex "queue runner" "description of operation" -The &%-q%& option starts one queue runner process. This scans the queue of +If other commandline options do not specify an action, +the &%-q%& option starts one queue runner process. This scans the queue of waiting messages, and runs a delivery process for each one in turn. It waits for each delivery process to finish before starting the next one. A delivery process may not actually do any deliveries if the retry times for the addresses @@ -4455,8 +4517,27 @@ The &'l'& (the letter &"ell"&) flag specifies that only local deliveries are to be done. If a message requires any remote deliveries, it remains on the queue for later delivery. -.vitem &%-q%&<&'qflags'&>&~<&'start&~id'&>&~<&'end&~id'&> +.vitem &%-q[q][i][f[f]][l][G[/