X-Git-Url: https://git.exim.org/exim.git/blobdiff_plain/93afd6be7efaf2acae325968b38484b0f4dc40a0..2b2cfa838f206b5d97a120722861f42780bc6a6a:/doc/doc-docbook/spec.xfpt diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt index 2363e7880..bca6689b6 100644 --- a/doc/doc-docbook/spec.xfpt +++ b/doc/doc-docbook/spec.xfpt @@ -1,6 +1,6 @@ . ///////////////////////////////////////////////////////////////////////////// . This is the primary source of the Exim Manual. It is an xfpt document that is -. converted into DocBook XML for subsequent conversion into printing and online +. converted into DocBook XML for subsequent conversion into printable and online . formats. The markup used herein is "standard" xfpt markup, with some extras. . The markup is summarized in a file called Markup.txt. . @@ -35,7 +35,7 @@ .literal off . ///////////////////////////////////////////////////////////////////////////// -. This generate the outermost element that wraps then entire document. +. This generates the outermost element that wraps the entire document. . ///////////////////////////////////////////////////////////////////////////// .book @@ -45,14 +45,14 @@ . Update the Copyright year (only) when changing content. . ///////////////////////////////////////////////////////////////////////////// -.set previousversion "4.91" +.set previousversion "4.92" .include ./local_params .set ACL "access control lists (ACLs)" .set I "    " .macro copyyear -2018 +2018, 2019 .endmacro . ///////////////////////////////////////////////////////////////////////////// @@ -60,12 +60,12 @@ . provided in the xfpt library. . ///////////////////////////////////////////////////////////////////////////// -. --- Override the &$ flag to automatically insert a $ with the variable name +. --- Override the &$ flag to automatically insert a $ with the variable name. .flag &$ $& "$" "" . --- Short flags for daggers in option headings. They will always be inside -. --- an italic string, but we want the daggers to be roman. +. --- an italic string, but we want the daggers to be in Roman. .flag &!! "†" .flag &!? "‡" @@ -89,7 +89,7 @@ . --- A macro for the common 2-column tables. The width of the first column . --- is suitable for the many tables at the start of the main options chapter; -. --- the small number of other 2-column tables override it. +. --- a small number of other 2-column tables override it. .macro table2 196pt 254pt .itable none 0 0 2 $1 left $2 left @@ -165,7 +165,7 @@ . //////////////////////////////////////////////////////////////////////////// -. The element is removed from the XML before processing for Ascii +. The element is removed from the XML before processing for ASCII . output formats. . //////////////////////////////////////////////////////////////////////////// @@ -337,7 +337,7 @@ Configuration files currently exist for the following operating systems: AIX, BSD/OS (aka BSDI), Darwin (Mac OS X), DGUX, Dragonfly, FreeBSD, GNU/Hurd, GNU/Linux, HI-OSF (Hitachi), HI-UX, HP-UX, IRIX, MIPS RISCOS, NetBSD, OpenBSD, OpenUNIX, QNX, SCO, SCO SVR4.2 (aka UNIX-SV), Solaris (aka SunOS5), SunOS4, -Tru64-Unix (formerly Digital UNIX, formerly DEC-OSF1), Ultrix, and Unixware. +Tru64-Unix (formerly Digital UNIX, formerly DEC-OSF1), Ultrix, and UnixWare. Some of these operating systems are no longer current and cannot easily be tested, so the configuration files may no longer work in practice. @@ -349,8 +349,8 @@ The terms and conditions for the use and distribution of Exim are contained in the file &_NOTICE_&. Exim is distributed under the terms of the GNU General Public Licence, a copy of which may be found in the 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, +The use, supply, or promotion of Exim for the purpose of sending bulk, +unsolicited electronic mail is incompatible with the basic aims of Exim, 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. @@ -371,20 +371,18 @@ contributors. .section "Exim documentation" "SECID1" . Keep this example change bar when updating the documentation! -.new .cindex "documentation" This edition of the Exim specification applies to version &version() of Exim. Substantive changes from the &previousversion; edition are marked in some -renditions of the document; this paragraph is so marked if the rendition is +renditions of this document; this paragraph is so marked if the rendition is capable of showing a change indicator. -.wen This document is very much a reference manual; it is not a tutorial. The reader is expected to have some familiarity with the SMTP mail transfer protocol and with general Unix system administration. 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 +Furthermore, this 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. @@ -394,7 +392,7 @@ introductory, and tutorial material can be found in a book entitled &'The Exim SMTP Mail Server'& (second edition, 2007), published by UIT Cambridge (&url(https://www.uit.co.uk/exim-book/)). -This book also contains a chapter that gives a general introduction to SMTP and +The 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 with the latest release of Exim. (Note that the earlier book about Exim, published by O'Reilly, covers Exim 3, and many things have changed in Exim 4.) @@ -409,7 +407,7 @@ information. .cindex "&_doc/NewStuff_&" .cindex "&_doc/ChangeLog_&" .cindex "change log" -As the program develops, there may be features in newer versions that have not +As Exim develops, there may be features in newer versions 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. Specifications of new features that are not yet in this manual are placed in the file @@ -420,7 +418,7 @@ incompatibly while they are developing, or even be withdrawn. For this reason, they are not documented in this manual. Information about experimental features can be found in the file &_doc/experimental.txt_&. -All changes to the program (whether new features, bug fixes, or other kinds of +All changes to Exim (whether new features, bug fixes, or other kinds of change) are noted briefly in the file called &_doc/ChangeLog_&. .cindex "&_doc/spec.txt_&" @@ -445,8 +443,8 @@ available in other formats (HTML, PostScript, PDF, and Texinfo). Section -.section "FTP and web sites" "SECID2" -.cindex "web site" +.section "FTP site and websites" "SECID2" +.cindex "website" .cindex "FTP site" 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%& @@ -454,7 +452,7 @@ 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 +As well as Exim distribution tar files, the Exim website contains a number of differently formatted versions of the documentation. A recent addition to the 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 @@ -489,7 +487,7 @@ via this web page: .display &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 +Please ask Debian-specific questions on that list and not on the general Exim lists. .section "Bug reports" "SECID5" @@ -505,7 +503,7 @@ 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" +.cindex "distribution" "FTP site" .cindex "distribution" "https site" The master distribution site for the Exim distribution is .display @@ -547,12 +545,12 @@ The distributions will be PGP signed by an individual key of the Release Coordinator. This key will have a uid containing an email address in the &'exim.org'& domain and will have signatures from other people, including other Exim maintainers. We expect that the key will be in the "strong set" of -PGP keys. There should be a trust path to that key from Nigel Metheringham's -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, +PGP keys. There should be a trust path to that key from the Exim Maintainer's +PGP keys, a version of which can be found in the release directory in the file +&_Exim-Maintainers-Keyring.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 Jeremy Harris and signed +At the time of the 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'&. @@ -563,7 +561,7 @@ The signatures for the tar bundles are in: &_exim-n.nn.tar.gz.asc_& &_exim-n.nn.tar.bz2.asc_& .endd -For each released version, the log of changes is made separately available in a +For each released version, the log of changes is made available in a separate file in the directory &_ChangeLogs_& so that it is possible to find out what has changed without having to download the entire distribution. @@ -621,8 +619,8 @@ a number of common scanners are provided. .endlist -.section "Run time configuration" "SECID7" -Exim's run time configuration is held in a single text file that is divided +.section "Runtime configuration" "SECID7" +Exim's runtime configuration is held in a single text file that 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 online installations is provided in the @@ -636,13 +634,13 @@ can be a straight replacement for &_/usr/lib/sendmail_& or &_/usr/sbin/sendmail_& when sending mail, but you do not need to know anything about Sendmail in order to run Exim. For actions other than sending messages, Sendmail-compatible options also exist, but those that produce output (for -example, &%-bp%&, which lists the messages on the queue) do so in Exim's own +example, &%-bp%&, which lists the messages in the queue) do so in Exim's own format. There are also some additional options that are compatible with Smail 3, and some further options that are new to Exim. Chapter &<>& documents all Exim's command line options. This information is automatically made into the man page that forms part of the Exim distribution. -Control of messages on the queue can be done via certain privileged command +Control of messages in the queue can be done via certain privileged command line options. There is also an optional monitor program called &'eximon'&, which displays current information in an X window, and which contains a menu interface to Exim's command line administration options. @@ -653,7 +651,7 @@ interface to Exim's command line administration options. .cindex "terminology definitions" .cindex "body of message" "definition of" The &'body'& of a message is the actual data that the sender wants to transmit. -It is the last part of a message, and is separated from the &'header'& (see +It is the last part of a message and is separated from the &'header'& (see below) by a blank line. .cindex "bounce message" "definition of" @@ -698,7 +696,7 @@ line. .cindex "local part" "definition of" .cindex "domain" "definition of" -The term &'local part'&, which is taken from RFC 2822, is used to refer to that +The term &'local part'&, which is taken from RFC 2822, is used to refer to the part of an email address that precedes the @ sign. The part that follows the @ sign is called the &'domain'& or &'mail domain'&. @@ -714,20 +712,20 @@ host it is running on are &'remote'&. message's envelope. .cindex "queue" "definition of" -The term &'queue'& is used to refer to the set of messages awaiting delivery, +The term &'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 +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" "definition of" The term &'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 &%runq%&, but in Exim +is used by other MTAs and also relates to the command &%runq%&, but in Exim the waiting messages are normally processed in an unpredictable order. .cindex "spool directory" "definition of" The term &'spool directory'& is used for a directory in which Exim keeps the -messages on its queue &-- that is, those that it is in the process of +messages in its queue &-- that is, those that it is in the process of delivering. This should not be confused with the directory in which local mailboxes are stored, which is called a &"spool directory"& by some people. In the Exim documentation, &"spool"& is always used in the first sense. @@ -879,7 +877,7 @@ source code. .next Many people have contributed code fragments, some large, some small, that were -not covered by any specific licence requirements. It is assumed that the +not covered by any specific license requirements. It is assumed that the contributors are happy to see their code incorporated into Exim under the GPL. .endlist @@ -907,9 +905,9 @@ has been down, and it also maintains per-host retry information. .section "Policy control" "SECID11" .cindex "policy control" "overview" Policy controls are now an important feature of MTAs that are connected to the -Internet. Perhaps their most important job is to stop MTAs being abused as +Internet. Perhaps their most important job is to stop MTAs from being abused as &"open relays"& by misguided individuals who send out vast amounts of -unsolicited junk, and want to disguise its source. Exim provides flexible +unsolicited junk and want to disguise its source. Exim provides flexible facilities for specifying policy controls on incoming mail: .ilist @@ -985,7 +983,7 @@ example &`16VDhn-0001bo-D3`&. Each part is a sequence of letters and digits, normally encoding numbers in base 62. However, in the Darwin operating system (Mac OS X) and when Exim is compiled to run under Cygwin, base 36 (avoiding the use of lower case letters) is used instead, because the message -id is used to construct file names, and the names of files in those systems are +id is used to construct filenames, and the names of files in those systems are not always case-sensitive. .cindex "pid (process id)" "re-use of" @@ -1042,7 +1040,7 @@ command line, or from the body of the message if &%-t%& is also used. If the process runs Exim with the &%-bS%& option, the message is also read non-interactively, but in this case the recipients are listed at the start of the message in a series of SMTP RCPT commands, terminated by a DATA -command. This is so-called &"batch SMTP"& format, +command. This is called &"batch SMTP"& format, but it isn't really SMTP. The SMTP commands are just another way of passing envelope addresses in a non-interactive submission. .next @@ -1066,7 +1064,7 @@ constructed from the login name of the user that called Exim and a default qualification domain (which can be set by the &%qualify_domain%& configuration option). For local or batch SMTP, a sender address that is passed using the SMTP MAIL command is ignored. However, the system administrator may allow -certain users (&"trusted users"&) to specify a different sender address +certain users (&"trusted users"&) to specify a different sender addresses unconditionally, or all users to specify certain forms of different sender address. The &%-f%& option or the SMTP MAIL command is used to specify these different addresses. See section &<>& for details of trusted @@ -1074,10 +1072,10 @@ users, and the &%untrusted_set_sender%& option for a way of allowing untrusted users to change sender addresses. Messages received by either of the non-interactive mechanisms are subject to -checking by the non-SMTP ACL, if one is defined. Messages received using SMTP -(either over TCP/IP, or interacting with a local process) can be checked by a +checking by the non-SMTP ACL if one is defined. Messages received using SMTP +(either over TCP/IP or interacting with a local process) can be checked by a number of ACLs that operate at different times during the SMTP session. Either -individual recipients, or the entire message, can be rejected if local policy +individual recipients or the entire message can be rejected if local policy requirements are not met. The &[local_scan()]& function (see chapter &<>&) is run for all incoming messages. @@ -1102,7 +1100,7 @@ the two spool files consist of the message id, followed by &`-H`& for the file containing the envelope and header, and &`-D`& for the data file. .cindex "spool directory" "&_input_& sub-directory" -By default all these message files are held in a single directory called +By default, all these message files are held in a single directory called &_input_& inside the general Exim spool directory. Some operating systems do not perform very well if the number of files in a directory gets large; to improve performance in such cases, the &%split_spool_directory%& option can be @@ -1139,7 +1137,7 @@ delivered (see chapters &<>& and 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 +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. @@ -1154,7 +1152,7 @@ to be sent. .oindex "&%ignore_bounce_errors_after%&" There are options called &%ignore_bounce_errors_after%& and &%timeout_frozen_after%&, which discard frozen messages after a certain time. -The first applies only to frozen bounces, the second to any frozen messages. +The first applies only to frozen bounces, the second to all frozen messages. .cindex "message" "log file for" .cindex "log" "file for each message" @@ -1162,7 +1160,7 @@ While Exim is working on a message, it writes information about each delivery attempt to its main log file. This includes successful, unsuccessful, and delayed deliveries for each recipient (see chapter &<>&). The log lines are also written to a separate &'message log'& file for each message. -These logs are solely for the benefit of the administrator, and are normally +These logs are solely for the benefit of the administrator and are normally deleted along with the spool files when processing of a message is complete. The use of individual message logs can be disabled by setting &%no_message_logs%&; this might give an improvement in performance on very busy @@ -1179,7 +1177,7 @@ 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 +Should the system or Exim 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 @@ -1194,11 +1192,11 @@ deliveries caused by crashes. The main delivery processing elements of Exim are called &'routers'& and &'transports'&, and collectively these are known as &'drivers'&. Code for a number of them is provided in the source distribution, and compile-time options -specify which ones are included in the binary. Run time options specify which +specify which ones are included in the binary. Runtime options specify which ones are actually used for delivering messages. .cindex "drivers" "instance definition" -Each driver that is specified in the run time configuration is an &'instance'& +Each driver that is specified in the runtime configuration is an &'instance'& of that particular driver type. Multiple instances are allowed; for example, you can set up several different &(smtp)& transports, each with different option values that might specify different ports or different timeouts. Each @@ -1233,8 +1231,8 @@ routers in many different ways, and there may be any number of routers in a configuration. The first router that is specified in a configuration is often one that handles -addresses in domains that are not recognized specially by the local host. These -are typically addresses for arbitrary domains on the Internet. A precondition +addresses in domains that are not recognized specifically by the local host. +Typically these are addresses for arbitrary domains on the Internet. A precondition is set up which looks for the special domains known to the host (for example, its own domain name), and the router is run for addresses that do &'not'& match. Typically, this is a router that looks up domains in the DNS in order to @@ -1271,7 +1269,7 @@ When an address is being verified, the routers are run in &"verify mode"&. This does not affect the way the routers work, but it is a state that can be detected. By this means, a router can be skipped or made to behave differently when verifying. A common example is a configuration in which the first router -sends all messages to a message-scanning program, unless they have been +sends all messages to a message-scanning program unless they have been previously scanned. Thus, the first router accepts all addresses without any checking, making it useless for verifying. Normally, the &%no_verify%& option would be set for such a router, causing it to be skipped in verify mode. @@ -1291,8 +1289,8 @@ the following: .ilist &'accept'&: The router accepts the address, and either assigns it to a -transport, or generates one or more &"child"& addresses. Processing the -original address ceases, +transport or generates one or more &"child"& addresses. Processing the +original address ceases .oindex "&%unseen%&" unless the &%unseen%& option is set on the router. This option can be used to set up multiple deliveries with different routing (for example, @@ -1307,7 +1305,7 @@ child addresses. Unlike &%pass_router%& (see below) the router specified by &%redirect_router%& may be anywhere in the router configuration. .next &'pass'&: The router recognizes the address, but cannot handle it itself. It -requests that the address be passed to another router. By default the address +requests that the address be passed to another router. By default, the address is passed to the next router, but this can be changed by setting the &%pass_router%& option. However, (unlike &%redirect_router%&) the named router must be below the current router (to avoid loops). @@ -1349,8 +1347,8 @@ facility for this purpose. .cindex "address duplicate, discarding" .cindex "duplicate addresses" Once routing is complete, Exim scans the addresses that are assigned to local -and remote transports, and discards any duplicates that it finds. During this -check, local parts are treated as case-sensitive. This happens only when +and remote transports and discards any duplicates that it finds. During this +check, local parts are treated case-sensitively. This happens only when actually delivering a message; when testing routers with &%-bt%&, all the routed addresses are shown. @@ -1470,7 +1468,7 @@ be immediately delivered, the system filter is run each time. The filter condition &%first_delivery%& can be used to detect the first run of the system filter. .next -Each recipient address is offered to each configured router in turn, subject to +Each recipient address is offered to each configured router, in turn, subject to its preconditions, until one is able to handle it. If no router can handle the address, that is, if they all decline, the address is failed. Because routers can be targeted at particular domains, several locally handled domains can be @@ -1547,9 +1545,9 @@ deleted, though the message log can optionally be preserved if required. Exim's mechanism for retrying messages that fail to get delivered at the first attempt is the queue runner process. You must either run an Exim daemon that uses the &%-q%& option with a time interval to start queue runners at regular -intervals, or use some other means (such as &'cron'&) to start them. If you do +intervals or use some other means (such as &'cron'&) to start them. If you do not arrange for queue runners to be run, messages that fail temporarily at the -first attempt will remain on your queue for ever. A queue runner process works +first attempt will remain in your queue forever. A queue runner process works its way through the queue, one message at a time, trying each delivery that has passed its retry time. You can run several queue runners at once. @@ -1618,7 +1616,7 @@ of the list. .section "Failures to deliver bounce messages" "SECID22" .cindex "bounce message" "failure to deliver" If a bounce message (either locally generated or received from a remote host) -itself suffers a permanent delivery failure, the message is left on the queue, +itself suffers a permanent delivery failure, the message is left in the queue, but it is frozen, awaiting the attention of an administrator. There are options that can be used to make Exim discard such failed messages, or to keep them for only a short time (see &%timeout_frozen_after%& and @@ -1663,7 +1661,7 @@ following subdirectories are created: .irow &_util_& "independent utilities" .endtable -The main utility programs are contained in the &_src_& directory, and are built +The main utility programs are contained in the &_src_& directory and are built with the Exim binary. The &_util_& directory contains a few optional scripts that may be useful to some sites. @@ -1688,8 +1686,8 @@ A C99-capable compiler will be required for the build. .section "PCRE library" "SECTpcre" .cindex "PCRE library" Exim no longer has an embedded PCRE library as the vast majority of -modern systems include PCRE as a system library, although you may need -to install the PCRE or PCRE development package for your operating +modern systems include PCRE as a system library, although you may need to +install the PCRE package or the PCRE development package for your operating system. If your system has a normal PCRE installation the Exim build process will need no further configuration. If the library or the headers are in an unusual location you will need to either set the PCRE_LIBS @@ -1738,7 +1736,7 @@ Solaris, operates on two files called &_dbmfile.dir_& and &_dbmfile.pag_&. The GNU library, &'gdbm'&, operates on a single file. If used via its &'ndbm'& compatibility interface it makes two different hard links to it with names &_dbmfile.dir_& and &_dbmfile.pag_&, but if used via its native interface, the -file name is used unmodified. +filename is used unmodified. .next .cindex "Berkeley DB library" The Berkeley DB package, if called via its &'ndbm'& compatibility interface, @@ -1820,17 +1818,17 @@ building Exim for the first time, the simplest thing to do is to copy &_src/EDITME_& to &_Local/Makefile_&, then read it and edit it appropriately. There are three settings that you must supply, because Exim will not build -without them. They are the location of the run time configuration file +without them. They are the location of the runtime configuration file (CONFIGURE_FILE), the directory in which Exim binaries will be installed (BIN_DIRECTORY), and the identity of the Exim user (EXIM_USER and maybe EXIM_GROUP as well). The value of CONFIGURE_FILE can in fact be -a colon-separated list of file names; Exim uses the first of them that exists. +a colon-separated list of filenames; Exim uses the first of them that exists. There are a few other 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 +at runtime, 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 &_Local/Makefile_& instead of at run time, so that errors +you specify them in &_Local/Makefile_& instead of at runtime, so that errors detected early in Exim's execution (such as a malformed configuration file) can be logged. @@ -1856,7 +1854,7 @@ happy with the default settings described in &_exim_monitor/EDITME_&, 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 +configuration files, for example, to change the C compiler, which defaults to &%gcc%&. See section &<>& below for details of how to do this. @@ -1888,11 +1886,10 @@ to your &_Local/Makefile_& and rebuild Exim. .section "Including TLS/SSL encryption support" "SECTinctlsssl" .cindex "TLS" "including support for TLS" .cindex "encryption" "including support for" -.cindex "SUPPORT_TLS" .cindex "OpenSSL" "building Exim with" .cindex "GnuTLS" "building Exim with" -Exim can be built to support encrypted SMTP connections, using the STARTTLS -command as per RFC 2487. It can also support legacy clients that expect to +Exim is usually built to support encrypted SMTP connections, using the STARTTLS +command as per RFC 2487. It can also support clients that expect to start a TLS session immediately on connection to a non-standard port (see the &%tls_on_connect_ports%& runtime option and the &%-tls-on-connect%& command line option). @@ -1901,35 +1898,41 @@ If you want to build Exim with TLS support, you must first install either the OpenSSL or GnuTLS library. There is no cryptographic code in Exim itself for implementing SSL. +.new +If you do not want TLS support you should set +.code +DISABLE_TLS=yes +.endd +in &_Local/Makefile_&. +.wen + If OpenSSL is installed, you should set .code -SUPPORT_TLS=yes +USE_OPENSL=yes TLS_LIBS=-lssl -lcrypto .endd in &_Local/Makefile_&. You may also need to specify the locations of the OpenSSL library and include files. For example: .code -SUPPORT_TLS=yes +USE_OPENSL=yes TLS_LIBS=-L/usr/local/openssl/lib -lssl -lcrypto TLS_INCLUDE=-I/usr/local/openssl/include/ .endd .cindex "pkg-config" "OpenSSL" If you have &'pkg-config'& available, then instead you can just use: .code -SUPPORT_TLS=yes +USE_OPENSL=yes USE_OPENSSL_PC=openssl .endd .cindex "USE_GNUTLS" If GnuTLS is installed, you should set .code -SUPPORT_TLS=yes USE_GNUTLS=yes TLS_LIBS=-lgnutls -ltasn1 -lgcrypt .endd in &_Local/Makefile_&, and again you may need to specify the locations of the library and include files. For example: .code -SUPPORT_TLS=yes USE_GNUTLS=yes TLS_LIBS=-L/usr/gnu/lib -lgnutls -ltasn1 -lgcrypt TLS_INCLUDE=-I/usr/gnu/include @@ -1937,7 +1940,6 @@ TLS_INCLUDE=-I/usr/gnu/include .cindex "pkg-config" "GnuTLS" If you have &'pkg-config'& available, then instead you can just use: .code -SUPPORT_TLS=yes USE_GNUTLS=yes USE_GNUTLS_PC=gnutls .endd @@ -2163,7 +2165,7 @@ libraries need to be installed before compiling Exim. However, there are some optional lookup types (such as cdb) for which 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 run time configuration +binary, attempts to configure Exim to use it cause runtime configuration errors. .cindex "pkg-config" "lookups" @@ -2266,7 +2268,7 @@ As with Exim itself, the final three files need not exist, and in this case the &_OS/eximon.conf-Default_& can be overridden dynamically by setting environment variables of the same name, preceded by EXIMON_. For example, setting EXIMON_LOG_DEPTH in the environment overrides the value of -LOG_DEPTH at run time. +LOG_DEPTH at runtime. .ecindex IIDbuex @@ -2286,10 +2288,10 @@ it may be possible to run Exim without making the binary setuid root (see chapter &<>& for details). .cindex "CONFIGURE_FILE" -Exim's run time configuration file is named by the CONFIGURE_FILE setting +Exim's runtime configuration file is named by the CONFIGURE_FILE setting in &_Local/Makefile_&. If this names a single file, and the file does not exist, the default configuration file &_src/configure.default_& is copied there -by the installation script. If a run time configuration file already exists, it +by the installation script. If a runtime configuration file already exists, it is left alone. If CONFIGURE_FILE is a colon-separated list, naming several alternative files, no default is installed. @@ -2337,7 +2339,7 @@ INFO_DIRECTORY, as described in section &<>& below. For the utility programs, old versions are renamed by adding the suffix &_.O_& to their names. The Exim binary itself, however, is handled differently. It is installed under a name that includes the version number and the compile number, -for example &_exim-&version()-1_&. The script then arranges for a symbolic link +for example, &_exim-&version()-1_&. The script then arranges for a symbolic link called &_exim_& to point to the binary. If you are updating a previous version of Exim, the script takes care to ensure that the name &_exim_& is never absent from the directory (as seen by other processes). @@ -2385,7 +2387,7 @@ make INSTALL_ARG='-no_symlink exim' install .cindex "installing Exim" "&'info'& documentation" Not all systems use the GNU &'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 +distribution. Instead it is available separately from the FTP site (see section &<>&). If you have defined INFO_DIRECTORY in &_Local/Makefile_& and the Texinfo @@ -2406,7 +2408,7 @@ necessary. .section "Testing" "SECID34" .cindex "testing" "installation" -Having installed Exim, you can check that the run time configuration file is +Having installed Exim, you can check that the runtime configuration file is syntactically valid by running the following command, which assumes that the Exim binary directory is within your PATH environment variable: .code @@ -2480,7 +2482,7 @@ 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 CONFIGURE_FILE setting. From -within the run time configuration, all other file and directory names +within the runtime configuration, all other file and directory names that Exim uses can be altered, in order to keep it entirely clear of the production version. @@ -2530,6 +2532,8 @@ use of Exim's filtering capabilities, you should make the document entitled If you are already running Exim on your host, building and installing a new version automatically makes it available to MUAs, or any other programs that call the MTA directly. However, if you are running an Exim daemon, you do need +.cindex restart "on HUP signal" +.cindex signal "HUP, to restart" to send it a HUP signal, to make it re-execute itself, and thereby pick up the new binary. You do not need to stop processing mail in order to install a new version of Exim. The install script does not modify an existing runtime @@ -2628,6 +2632,7 @@ supplementary group is one of those listed in the &%trusted_groups%& configuration option. Note that the Exim group is not automatically trusted. .cindex '&"From"& line' +.cindex "envelope from" .cindex "envelope sender" Trusted users are always permitted to use the &%-f%& option or a leading &"From&~"& line to specify the envelope sender of a message that is passed to @@ -2767,7 +2772,12 @@ used to specify a path on the command line if a pid file is required. The SIGHUP signal .cindex "SIGHUP" +.cindex restart "on HUP signal" +.cindex signal "HUP, to restart" .cindex "daemon" "restarting" +.cindex signal "to reload configuration" +.cindex daemon "reload configuration" +.cindex reload configuration can be used to cause the daemon to re-execute itself. This should be done whenever Exim's configuration file, or any file that is incorporated into it by means of the &%.include%& facility, is changed, and also whenever a new version @@ -2796,7 +2806,7 @@ function, which provides extensive line-editing facilities, for reading the test data. A line history is supported. Long expansion expressions can be split over several lines by using backslash -continuations. As in Exim's run time configuration, white space at the start of +continuations. As in Exim's runtime configuration, white space at the start of continuation lines is ignored. 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, &$qualify_domain$&) are available, but no @@ -2877,6 +2887,7 @@ separate document entitled &'Exim's interfaces to mail filtering'&. When testing a filter file, .cindex "&""From""& line" +.cindex "envelope from" .cindex "envelope sender" .oindex "&%-f%&" "for filter testing" the envelope sender can be set by the &%-f%& option, @@ -3130,7 +3141,7 @@ mysql_servers = If &%config%& is given as an argument, the config is output, as it was parsed, any include file resolved, any comment removed. -If &%config_file%& is given as an argument, the name of the run time +If &%config_file%& is given as an argument, the name of the runtime configuration file is output. (&%configure_file%& works too, for backward compatibility.) If a list of configuration files was supplied, the value that is output here @@ -3186,15 +3197,15 @@ the exit status will be nonzero. .vitem &%-bp%& .oindex "&%-bp%&" -.cindex "queue" "listing messages on" -.cindex "listing" "messages on the queue" +.cindex "queue" "listing messages in" +.cindex "listing" "messages in the queue" This option requests a listing of the contents of the mail queue on the standard output. If the &%-bp%& option is followed by a list of message ids, just those messages are listed. By default, this option can be used only by an admin user. However, the &%queue_list_requires_admin%& option can be set false to allow any user to see the queue. -Each message on the queue is displayed as in the following example: +Each message in the queue is displayed as in the following example: .code 25m 2.9K 0t5C6f-0000c8-00 red.king@looking-glass.fict.example @@ -3202,7 +3213,7 @@ Each message on the queue is displayed as in the following example: .endd .cindex "message" "size in queue listing" .cindex "size" "of message" -The first line contains the length of time the message has been on the queue +The first line contains the length of time the message has been in 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. For bounce messages, the sender address is empty, and appears as @@ -3233,7 +3244,7 @@ of just &"D"&. .vitem &%-bpc%& .oindex "&%-bpc%&" .cindex "queue" "count of messages on" -This option counts the number of messages on the queue, and writes the total +This option counts the number of messages in the queue, and writes the total to the standard output. It is restricted to admin users, unless &%queue_list_requires_admin%& is set false. @@ -3242,7 +3253,7 @@ to the standard output. It is restricted to admin users, unless .oindex "&%-bpr%&" This option operates like &%-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 +lots of messages in the queue, and is particularly useful if the output is going to be post-processed in a way that doesn't need the sorting. .vitem &%-bpra%& @@ -3413,7 +3424,7 @@ This option causes Exim to write the current version number, compilation number, and compilation date of the &'exim'& binary to the standard output. It also lists the DBM library that is being used, the optional modules (such as specific lookup types), the drivers that are included in the binary, and the -name of the run time configuration file that is in use. +name of the runtime configuration file that is in use. As part of its operation, &%-bV%& causes Exim to read and syntax check its configuration file. However, this is a static check only. It cannot check @@ -3502,10 +3513,10 @@ which the daemon will exit, which should cause inetd to listen once more. .cindex "configuration file" "alternate" .cindex "CONFIGURE_FILE" .cindex "alternate configuration file" -This option causes Exim to find the run time configuration file from the given +This option causes Exim to find the runtime configuration file from the given list instead of from the list specified by the CONFIGURE_FILE -compile-time setting. Usually, the list will consist of just a single file -name, but it can be a colon-separated list of names. In this case, the first +compile-time setting. Usually, the list will consist of just a single filename, +but it can be a colon-separated list of names. In this case, the first file that exists is used. Failure to open an existing file stops Exim from proceeding any further along the list, and an error is generated. @@ -3525,15 +3536,15 @@ even if the caller is root. The reception works, but by that time, Exim is running as the Exim user, so when it re-executes to regain privilege for the delivery, the use of &%-C%& causes privilege to be lost. However, root can test reception and delivery using two separate commands (one to put a message -on the queue, using &%-odq%&, and another to do the delivery, using &%-M%&). +in the queue, using &%-odq%&, and another to do the delivery, using &%-M%&). If ALT_CONFIG_PREFIX is defined &_in Local/Makefile_&, it specifies a prefix string with which any file named in a &%-C%& command line option -must start. In addition, the file name must not contain the sequence &`/../`&. +must start. In addition, the filename must not contain the sequence &`/../`&. However, if the value of the &%-C%& option is identical to the value of CONFIGURE_FILE in &_Local/Makefile_&, Exim ignores &%-C%& and proceeds as usual. There is no default setting for ALT_CONFIG_PREFIX; when it is -unset, any file name can be used with &%-C%&. +unset, any filename can be used with &%-C%&. ALT_CONFIG_PREFIX can be used to confine alternative configuration files to a directory to which only root has access. This prevents someone who has @@ -3661,14 +3672,12 @@ 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 +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. @@ -3719,6 +3728,7 @@ between &%-F%& and the <&'string'&> is optional. .cindex "sender" "address" .cindex "address" "sender" .cindex "trusted users" +.cindex "envelope from" .cindex "envelope sender" .cindex "user" "trusted" This option sets the address of the envelope sender of a locally-generated @@ -3907,7 +3917,7 @@ The arguments give the local address and port being proxied, and the TLS cipher. .oindex "&%-Mc%&" .cindex "hints database" "not overridden by &%-Mc%&" .cindex "delivery" "manually started &-- not forced" -This option requests Exim to run a delivery attempt on each message in turn, +This option requests Exim to run a delivery attempt on each message, in turn, but unlike the &%-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 @@ -3953,6 +3963,20 @@ is sent to the sender, containing the text &"cancelled by administrator"&. Bounce messages are just discarded. This option can be used only by an admin user. +.new +.vitem &%-MG%&&~<&'queue&~name'&&~<&'message&~id'&>&~<&'message&~id'&>&~... +.oindex "&%-MG%&" +.cindex queue named +.cindex "named queues" +.cindex "queue" "moving messages" +This option requests that each listed message be moved from its current +queue to the given named queue. +The destination queue name argument is required, but can be an empty +string to define the default queue. +If the messages are not currently located in the default queue, +a &%-qG%& option will be required to define the source queue. +.wen + .vitem &%-Mmad%&&~<&'message&~id'&>&~<&'message&~id'&>&~... .oindex "&%-Mmad%&" .cindex "delivery" "cancelling all" @@ -3982,7 +4006,7 @@ This option requests Exim to remove the given messages from the queue. No bounce messages are sent; each message is simply 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. +placed in the queue. . .new . .vitem &%-MS%& @@ -4087,7 +4111,7 @@ Exim. .oindex "&%-oA%&" .cindex "Sendmail compatibility" "&%-oA%& option" This option is used by Sendmail in conjunction with &%-bi%& to specify an -alternative alias file name. Exim handles &%-bi%& differently; see the +alternative alias filename. Exim handles &%-bi%& differently; see the description above. .vitem &%-oB%&&~<&'n'&> @@ -4136,7 +4160,7 @@ However, like &%-odb%&, this option has no effect if &%queue_only_override%& is false and one of the queueing options in the configuration file is in effect. If there is a temporary delivery error during foreground delivery, the -message is left on the queue for later delivery, and the original reception +message is left in the queue for later delivery, and the original reception process exits. See chapter &<>& for a way of setting up a restricted configuration that never queues messages. @@ -4154,7 +4178,7 @@ Sendmail. 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 process for each message received. Messages -are placed on the queue, and remain there until a subsequent queue runner +are placed in the queue, and remain there until a subsequent queue runner process encounters them. There are several configuration options (such as &%queue_only%&) that can be used to queue incoming messages under certain conditions. This option overrides all of them and also &%-odqs%&. It always @@ -4172,7 +4196,7 @@ When &%-odqs%& does operate, a delivery process is started for each incoming message, in the background by default, but in the foreground if &%-odi%& is also present. The recipient addresses are routed, and local deliveries are done in the normal way. However, if any SMTP deliveries are required, they are not -done at this time, so the message remains on the queue until a subsequent queue +done at this time, so the message remains in the queue until a subsequent queue runner process encounters it. Because routing was done, Exim knows which messages are waiting for which hosts, and so a number of messages for the same host can be sent in a single SMTP connection. The &%queue_smtp_domains%& @@ -4391,7 +4415,7 @@ This option is relevant only when the &%-bd%& (start listening daemon) option is also given. It controls which ports and interfaces the daemon uses. Details of the syntax, and how it interacts with configuration file options, are given in chapter &<>&. When &%-oX%& is used to start a daemon, no pid -file is written unless &%-oP%& is also present to specify a pid file name. +file is written unless &%-oP%& is also present to specify a pid filename. .vitem &%-pd%& .oindex "&%-pd%&" @@ -4493,7 +4517,7 @@ intermittently. .cindex "queue" "initial delivery" If the &'i'& flag is present, the queue runner runs delivery processes only for those messages that haven't previously been tried. (&'i'& stands for &"initial -delivery"&.) This can be helpful if you are putting messages on the queue using +delivery"&.) This can be helpful if you are putting messages in the queue using &%-odq%& and want a queue runner just to process the new messages. .vitem &%-q[q][i]f...%& @@ -4514,7 +4538,7 @@ frozen or not. .oindex "&%-ql%&" .cindex "queue" "local deliveries only" 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 +be done. If a message requires any remote deliveries, it remains in the queue for later delivery. .vitem &%-q[q][i][f[f]][l][G[/