X-Git-Url: https://git.exim.org/exim.git/blobdiff_plain/4bc16ab818795e5d4eccc52d65bd7613376ffbe3..0d1ec695d8cc045581878d3a9e519dca649e3ef1:/doc/doc-docbook/spec.xfpt?ds=sidebyside diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt index aaa4a270f..d7c2da911 100644 --- a/doc/doc-docbook/spec.xfpt +++ b/doc/doc-docbook/spec.xfpt @@ -446,7 +446,7 @@ website, are hosted at the University of Cambridge. .cindex "FAQ" 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)), +online information is &url(https://wiki.exim.org,the Exim wiki), 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 @@ -487,7 +487,7 @@ lists. .cindex "bug reports" .cindex "reporting bugs" Reports of obvious bugs can be emailed to &'bugs@exim.org'& or reported -via the Bugzilla (&url(https://bugs.exim.org)). However, if you are unsure +via &url(https://bugs.exim.org,the Bugzilla). 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. @@ -1811,7 +1811,7 @@ Yet another DBM library, called &'tdb'&, is available from &url(https://sourceforge.net/projects/tdb/files/). It has its own interface, and also operates on a single file. .next -It is possible to use sqlite3 (&url(https://www.sqlite.org/index.html)) +It is possible to use &url(https://www.sqlite.org/index.html,sqlite3) for the DBM library. .endlist @@ -2069,19 +2069,29 @@ withdrawn. -.section "Dynamically loaded lookup module support" "SECTdynamicmodules" +.section "Dynamically loaded module support" "SECTdynamicmodules" .cindex "lookup modules" +.cindex "router modules" +.cindex "transport modules" +.cindex "authenticator modules" .cindex "dynamic modules" .cindex ".so building" On some platforms, Exim supports not compiling all lookup types directly into the main binary, instead putting some into external modules which can be loaded on demand. This permits packagers to build Exim with support for lookups with extensive -library dependencies without requiring all users to install all of those +library dependencies without requiring all systems to install all of those dependencies. -Most, but not all, lookup types can be built this way. +.new +Any combination of lookup types can be built this way. +Lookup types that provide several variants will be loaded as +Exim starts. +Types that provide only one method are not loaded until used by +the runtime configuration. +.wen -Set &`LOOKUP_MODULE_DIR`& to the directory into which the modules will be +For building +set &`LOOKUP_MODULE_DIR`& to the directory into which the modules will be installed; Exim will only load modules from that directory, as a security measure. You will need to set &`CFLAGS_DYNAMIC`& if not already defined for your OS; see &_OS/Makefile-Linux_& for an example. @@ -2091,12 +2101,25 @@ see &_src/EDITME_& for details. Then, for each module to be loaded dynamically, define the relevant &`LOOKUP_`&<&'lookup_type'&> flags to have the value "2" instead of "yes". For example, this will build in lsearch but load sqlite and mysql support -on demand: +only if each is installed: .code LOOKUP_LSEARCH=yes LOOKUP_SQLITE=2 LOOKUP_MYSQL=2 .endd +Set also &`LOOKUP_`&<&'lookup_type'&>&` INCLUDE`& and +&`LOOKUP_`&<&'lookup_type'&>`_LIBS if needed for each lookup type, +ensuring that duplicates are not present in more global values. + +.new +Similarly, authenticator, router and transport drivers can be built +as external modules. +Modules will be searched for as demanded by the runtime configuration, +permitting a smaller Exim binary. + +For building, as above but using +&`AUTH_*`&, &`ROUTER_*`& and &`TRANSPORT_*`& instead of &`LOOKUP_*`&, +.wen .section "The building process" "SECID29" @@ -3057,7 +3080,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(https://www.jetmore.org/john/code/swaks/,swaks). +&url(https://www.jetmore.org/john/code/swaks/,swaks,swaks). .cmdopt -bhc <&'IP&~address'&> This option operates in the same way as &%-bh%&, except that address @@ -5452,7 +5475,7 @@ list items, it is not ignored when parsing the list. The spaces around the first colon in the example above are necessary. If they were not there, the list would be interpreted as the two items 127.0.0.1:: and 1. -.section "Changing list separators" "SECTlistsepchange" +.subsection "Changing list separators" "SECTlistsepchange" .cindex "list separator" "changing" .cindex "IPv6" "addresses in lists" Doubling colons in IPv6 addresses is an unwelcome chore, so a mechanism was @@ -5493,7 +5516,7 @@ enclosing an empty list item. -.section "Empty items in lists" "SECTempitelis" +.subsection "Empty items in lists" "SECTempitelis" .cindex "list" "empty item in" An empty item at the end of a list is always ignored. In other words, trailing separator characters are ignored. Thus, the list in @@ -6967,7 +6990,7 @@ For elements of type string, the returned value is de-quoted. The given file is an LMDB database. LMDB is a memory-mapped key-value store, with API modeled loosely on that of BerkeleyDB. -See &url(https://symas.com/products/lightning-memory-mapped-database/) +See &url(https://symas.com/products/lightning-memory-mapped-database/,LMDB) for the feature set and operation modes. Exim provides read-only access via the LMDB C library. @@ -8198,7 +8221,7 @@ ${lookup mysql{servers=master; UPDATE ...} } The new version avoids issues with tainted arguments explicitly expanded as part of the query. The entire string within the braces becomes tainted, -including the server sepcification - which is not permissible. +including the server specification - which is not permissible. If the older sytax is used, a warning message will be logged. This syntax will be removed in a future release. @@ -10810,7 +10833,7 @@ will sort an MX lookup into priority order. .vitem &*${srs_encode&~{*&<&'secret'&>&*}{*&<&'return&~path'&>&*}{*&<&'original&~domain'&>&*}}*& -SRS encoding. See SECT &<>& for details. +SRS encoding. See section &<>& for details. @@ -16258,7 +16281,7 @@ set. .cindex "underscore in EHLO/HELO" This option can be set to a string of rogue characters that are permitted in non-ip-literal EHLO and HELO names in addition to the standard letters, digits, -hyphens, and dots. For examplem if you really must allow underscores, +hyphens, and dots. For example if you really must allow underscores, you can set .code helo_allow_chars = _ @@ -16632,7 +16655,7 @@ has been built with LDAP support. .cindex "ESMTP extensions" LIMITS This option can be used to suppress the advertisement of the SMTP LIMITS extension (RFC 9422) to specific hosts. -If permitted, Exim as a servier will advertise in the EHLO response +If permitted, Exim as a server will advertise in the EHLO response the limit for RCPT commands set by the &%recipients_max%& option (if it is set) and the limit for MAIL commands set by the &%smtp_accept_max_per_connection%& option. @@ -17196,7 +17219,7 @@ See also the &%hosts_pipe_connect%& smtp transport option. The SMTP service extension keyword advertised is &"PIPECONNECT"&; it permits the client to pipeline -TCP connection and hello command (inclear phase), +TCP connection and hello command (cleatext phase), or TLS-establishment and hello command (encrypted phase), on later connections to the same host. @@ -28910,7 +28933,7 @@ The &(spa)& authenticator provides client support for Microsoft's &'Secure Password Authentication'& mechanism, which is also sometimes known as NTLM (NT LanMan). The code for client side of this authenticator was contributed by Marc Prud'hommeaux, and much of it is -taken from the Samba project (&url(https://www.samba.org/)). The code for the +taken from the &url(https://www.samba.org/,Samba project). The code for the server side was subsequently contributed by Tom Kistner. The mechanism works as follows: @@ -28998,8 +29021,8 @@ msn: .cindex "Certificate-based authentication" The &(external)& authenticator provides support for authentication based on non-SMTP information. -The specification is in RFC 4422 Appendix A -(&url(https://tools.ietf.org/html/rfc4422)). +The specification is in +&url(https://tools.ietf.org/html/rfc4422,PFC 4422) Appendix A. It is only a transport and negotiation mechanism; the process of authentication is entirely controlled by the server configuration. @@ -29010,7 +29033,7 @@ and for clients to only attempt, this authentication method on a secure (eg. under TLS) connection. One possible use, compatible with the -K-9 Mail Android client (&url(https://k9mail.github.io/)), +&url(https://k9mail.github.io/,K-9 Mail Android client) is for using X509 client certificates. It thus overlaps in function with the TLS authenticator @@ -32032,12 +32055,17 @@ This control turns off DKIM verification processing entirely. For details on the operation and configuration of DKIM, see section &<>&. -.vitem &*control&~=&~dmarc_disable_verify*& +.vitem &*control&~=&~dmarc_disable_verify*& &&& + &*control&~=&~dmarc_enable_forensic*& .cindex "disable DMARC verify" -.cindex "DMARC" "disable verify" -This control turns off DMARC verification processing entirely. For details on +.cindex DMARC "disable verify" +.cindex DMARC controls +.cindex DMARC "forensic mails" +These control affect DMARC processing. For details on the operation and configuration of DMARC, see section &<>&. +The &"disable"& turns off DMARC verification processing entirely. + .vitem &*control&~=&~dscp/*&<&'value'&> .cindex "&ACL;" "setting DSCP value" @@ -35954,7 +35982,7 @@ The third argument may be NULL, in which case the &%-oMas%& option is omitted. .vitem &*void&~debug_printf(char&~*,&~...)*& -This is Exim's debugging function, with arguments as for &'(printf()'&. The +This is Exim's debugging function, with arguments as for &'printf()'&. The output is written to the standard error stream. If no debugging is selected, calls to &'debug_printf()'& have no effect. Normally, you should make calls conditional on the &`local_scan`& debug selector by coding like this: @@ -41039,20 +41067,31 @@ will be used during message reception. .next A queue runner process retains root privilege throughout its execution. Its job is to fork a controlled sequence of delivery processes. + .next -A delivery process retains root privilege throughout most of its execution, -but any actual deliveries (that is, the transports themselves) are run in -subprocesses which always change to a non-root uid and gid. For local -deliveries this is typically the uid and gid of the owner of the mailbox; for -remote deliveries, the Exim uid and gid are used. Once all the delivery +A delivery process retains root privilege throughout most of its execution., +including while the recipient addresses in a message are being routed. + +.ilist +However, if a user's filter file has to be processed, +this is done in a subprocess that runs under the individual user's uid and +gid. A system filter is run as root unless &%system_filter_user%& is set. +.endlist + +Any actual deliveries (that is, the transports themselves) are run in +subprocesses which always change to a non-root uid and gid. +.ilist +For local +deliveries this is typically the uid and gid of the owner of the mailbox. +.next +For remote deliveries, the Exim uid and gid are used. +.endlist + +Once all the delivery subprocesses have been run, a delivery process changes to the Exim uid and gid while doing post-delivery tidying up such as updating the retry database and generating bounce and warning messages. -While the recipient addresses in a message are being routed, the delivery -process runs as root. However, if a user's filter file has to be processed, -this is done in a subprocess that runs under the individual user's uid and -gid. A system filter is run as root unless &%system_filter_user%& is set. .next A process that is testing addresses (the &%-bt%& option) runs as root so that the routing is done in the same environment as a message delivery. @@ -41865,8 +41904,9 @@ To generate keys under OpenSSL: openssl genrsa -out dkim_rsa.private 2048 openssl rsa -in dkim_rsa.private -out /dev/stdout -pubout -outform PEM .endd -The result file from the first command should be retained, and -this option set to use it. +The result file from the first command should be retained, +permissions set so that Exim can read it, +and this option set to use it. Take the base-64 lines from the output of the second command, concatenated, for the DNS TXT record. See section 3.6 of RFC6376 for the record specification. @@ -42291,6 +42331,12 @@ This includes retransmissions done by traditional forwarders. SPF verification support is built into Exim if SUPPORT_SPF=yes is set in &_Local/Makefile_&. The support uses the &_libspf2_& library &url(https://www.libspf2.org/). +.new +.cindex "dynamic modules" +The support can be built as a dynamic-load module if desired; +see the comments in that Makefile. +.wen + There is no Exim involvement in the transmission of messages; publishing certain DNS records is all that is required. @@ -42587,14 +42633,14 @@ Example usage: DMARC combines feedback from SPF, DKIM, and header From: in order to attempt to provide better indicators of the authenticity of an email. This document does not explain the fundamentals; you -should read and understand how it works by visiting the website at -&url(http://www.dmarc.org/). +should read and understand how it works by visiting the +&url(http://www.dmarc.org/,DMARC website). If Exim is built with DMARC support, the libopendmarc library is used. For building Exim yourself, obtain the library from -&url(http://sourceforge.net/projects/opendmarc/) +&url(http://sourceforge.net/projects/opendmarc/,sourceforge) to obtain a copy, or find it in your favorite package repository. You will need to attend to the local/Makefile feature SUPPORT_DMARC and the associated LDFLAGS addition. @@ -43150,6 +43196,7 @@ Events have names which correspond to the point in process at which they fire. The name is placed in the variable &$event_name$& and the event action expansion must check this, as it will be called for every possible event type. +.new The current list of events is: .itable all 0 0 4 25* left 10* center 15* center 50* left .row auth:fail after both "per driver per authentication attempt" @@ -43169,7 +43216,10 @@ The current list of events is: .row tls:fail:connect after main "per connection" .row smtp:connect after transport "per connection" .row smtp:ehlo after transport "per connection" +.row smtp:fail:protocol after main "per connection" +.row smtp:fail:syntax after main "per connection" .endtable +.wen New event types may be added in future. The event name is a colon-separated list, defining the type of @@ -43185,6 +43235,7 @@ should define the event action. An additional variable, &$event_data$&, is filled with information varying with the event type: +.new .itable all 0 0 2 20* left 80* left .row auth:fail "smtp response" .row dane:fail "failure reason" @@ -43200,7 +43251,10 @@ with the event type: .row tls:fail:connect "error string" .row smtp:connect "smtp banner" .row smtp:ehlo "smtp ehlo response" +.row smtp:fail:protocol "error string" +.row smtp:fail:syntax "error string" .endtable +.wen The :defer events populate one extra variable: &$event_defer_errno$&.