X-Git-Url: https://git.exim.org/exim.git/blobdiff_plain/f3766eb5a200d0deb99dc3f096ced249727940cd..07af267efb085ad25e9ec81eb4c6b11364acdcd1:/doc/doc-docbook/spec.xfpt diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt index 201aefc5d..62a07ad75 100644 --- a/doc/doc-docbook/spec.xfpt +++ b/doc/doc-docbook/spec.xfpt @@ -1,4 +1,4 @@ -. $Cambridge: exim/doc/doc-docbook/spec.xfpt,v 1.55 2009/10/14 14:48:40 nm4 Exp $ +. $Cambridge: exim/doc/doc-docbook/spec.xfpt,v 1.63 2009/10/26 13:14:23 nm4 Exp $ . . ///////////////////////////////////////////////////////////////////////////// . This is the primary source of the Exim Manual. It is an xfpt document that is @@ -2975,6 +2975,7 @@ local part) and outputs what it finds. .cindex "options" "router &-- extracting" .cindex "options" "transport &-- extracting" +.cindex "options" "authenticator &-- extracting" If one of the words &%router%&, &%transport%&, or &%authenticator%& is given, followed by the name of an appropriate driver instance, the option settings for that driver are output. For example: @@ -2988,6 +2989,11 @@ using one of the words &%router_list%&, &%transport_list%&, or settings can be obtained by using &%routers%&, &%transports%&, or &%authenticators%&. +.cindex "options" "macro &-- extracting" +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. .vitem &%-bp%& .oindex "&%-bp%&" @@ -5885,6 +5891,10 @@ password are correct. In the examples it just produces an error message. To make the authenticators work, you can use a string expansion expression like one of the examples in &<>&. +Beware that the sequence of the parameters to PLAIN and LOGIN differ; the +usercode and password are in different positions. &<>& +covers both. + .ecindex IIDconfiwal @@ -6128,7 +6138,7 @@ IPv6 addresses must be enclosed in quotes to prevent the first internal colon being interpreted as a key terminator. For example: .code 1.2.3.4: data for 1.2.3.4 -192.168.0.0/16 data for 192.168.0.0/16 +192.168.0.0/16: data for 192.168.0.0/16 "abcd::cdab": data for abcd::cdab "abcd:abcd::/32" data for abcd:abcd::/32 .endd @@ -10199,6 +10209,10 @@ configuration, you might have this: .code server_condition = ${if pwcheck{$auth1:$auth2}} .endd +Again, for a PLAIN authenticator configuration, this would be: +.code +server_condition = ${if pwcheck{$auth2:$auth3}} +.endd .vitem &*queue_running*& .cindex "queue runner" "detecting when delivering from" .cindex "expansion" "queue runner test" @@ -10986,7 +11000,7 @@ precise size of the file that has been written. See also &$message_body_size$&, &$body_linecount$&, and &$body_zerocount$&. .cindex "RCPT" "value of &$message_size$&" -While running an ACL at the time of an SMTP RCPT command, &$message_size$& +While running a per message ACL (mail/rcpt/predata), &$message_size$& contains the size supplied on the MAIL command, or -1 if no size was given. The value may not, of course, be truthful. @@ -12354,6 +12368,7 @@ listed in more than one group. .row &%gnutls_require_kx%& "control GnuTLS key exchanges" .row &%gnutls_require_mac%& "control GnuTLS MAC algorithms" .row &%gnutls_require_protocols%& "control GnuTLS protocols" +.row &%gnutls_compat_mode%& "use GnuTLS compatibility mode" .row &%tls_advertise_hosts%& "advertise TLS to these hosts" .row &%tls_certificate%& "location of server certificate" .row &%tls_crl%& "certificate revocation list" @@ -13353,6 +13368,11 @@ server. For details, see section &<>&. This option controls the protocols when GnuTLS is used in an Exim server. For details, see section &<>&. +.option gnutls_compat_mode main boolean unset +This option controls whether GnuTLS is used in compatibility mode in an Exim +server. This reduces security slightly, but improves interworking with older +implementations of TLS. + .option headers_charset main string "see below" This option sets a default character set for translating from encoded MIME @@ -13424,7 +13444,7 @@ do. By default, Exim just checks the syntax of HELO and EHLO commands (see &%helo_accept_junk_hosts%& and &%helo_allow_chars%&). However, some sites like to do more extensive checking of the data supplied by these commands. The ACL -condition &`verify`& &`=`& &`helo`& is provided to make this possible. +condition &`verify = helo`& is provided to make this possible. Formerly, it was necessary also to set this option (&%helo_try_verify_hosts%&) to force the check to occur. From release 4.53 onwards, this is no longer necessary. If the check has not been done before &`verify`& &`=`& &`helo`& is @@ -17826,10 +17846,10 @@ redirection items of the form :defer: :fail: .endd -respectively. When a redirection list contains such an item, it applies to the -entire redirection; any other items in the list are ignored (&':blackhole:'& is -different). Any text following &':fail:'& or &':defer:'& is placed in the error -text associated with the failure. For example, an alias file might contain: +respectively. When a redirection list contains such an item, it applies +to the entire redirection; any other items in the list are ignored. Any +text following &':fail:'& or &':defer:'& is placed in the error text +associated with the failure. For example, an alias file might contain: .code X.Employee: :fail: Gone away, no forwarding address .endd @@ -21453,6 +21473,11 @@ client. For details, see section &<>&. This option controls the protocols when GnuTLS is used in an Exim client. For details, see section &<>&. +.option gnutls_compat_mode main boolean unset +This option controls whether GnuTLS is used in compatibility mode in an Exim +server. This reduces security slightly, but improves interworking with older +implementations of TLS. + .option helo_data smtp string&!! "see below" .cindex "HELO" "argument, setting" .cindex "EHLO" "argument, setting" @@ -23813,7 +23838,7 @@ sasl_cram_md5: sasl_plain: driver = cyrus_sasl public_name = PLAIN - server_set_id = $auth1 + server_set_id = $auth2 .endd Cyrus SASL does implement the LOGIN authentication method, even though it is not a standard method. It is disabled by default in the source distribution, @@ -23846,7 +23871,7 @@ dovecot_plain: driver = dovecot public_name = PLAIN server_socket = /var/run/dovecot/auth-client - server_set_id = $auth1 + server_set_id = $auth2 dovecot_ntlm: driver = dovecot @@ -24429,13 +24454,10 @@ unencrypted. The &%tls_certificate%& and &%tls_privatekey%& options of the &(smtp)& transport provide the client with a certificate, which is passed to the server if it requests it. If the server is Exim, it will request a certificate only if -&%tls_verify_hosts%& or &%tls_try_verify_hosts%& matches the client. &*Note*&: -These options must be set in the &(smtp)& transport for Exim to use TLS when it -is operating as a client. Exim does not assume that a server certificate (set -by the global options of the same name) should also be used when operating as a -client. +&%tls_verify_hosts%& or &%tls_try_verify_hosts%& matches the client. -If &%tls_verify_certificates%& is set, it must name a file or, +If the &%tls_verify_certificates%& option is set on the &(smtp)& transport, it +must name a file or, for OpenSSL only (not GnuTLS), a directory, that contains a collection of expected server certificates. The client verifies the server's certificate against this collection, taking into account any revoked certificates that are @@ -24447,6 +24469,12 @@ list of permitted cipher suites. If either of these checks fails, delivery to the current host is abandoned, and the &(smtp)& transport tries to deliver to alternative hosts, if any. + &*Note*&: +These options must be set in the &(smtp)& transport for Exim to use TLS when it +is operating as a client. Exim does not assume that a server certificate (set +by the global options of the same name) should also be used when operating as a +client. + .vindex "&$host$&" .vindex "&$host_address$&" All the TLS options in the &(smtp)& transport are expanded before use, with @@ -26975,7 +27003,7 @@ entry must set the rate for the same key (otherwise it will always be zero). For example: .code acl_check_connect: - deny ratelimit = 100 / 5m / strict / noupdate + deny ratelimit = 100 / 5m / strict / per_cmd / noupdate log_message = RATE: $sender_rate/$sender_rate_period \ (max $sender_rate_limit) .endd @@ -34392,39 +34420,48 @@ runtime of the ACL. Calling the ACL only for existing signatures is not sufficient to build more advanced policies. For that reason, the global option &%dkim_verify_signers%&, and a global expansion variable -&%$dkim_signing_domains%& exist. +&%$dkim_signers%& exist. The global option &%dkim_verify_signers%& can be set to a colon-separated list of DKIM domains or identities for which the ACL &%acl_smtp_dkim%& is called. It is expanded when the message has been received. At this point, -the expansion variable &%$dkim_signing_domains%& already contains a colon- -separated list of signer domains for the message. When &%dkim_verify_signers%& -is not specified in the main configuration, it defaults as: +the expansion variable &%$dkim_signers%& already contains a colon- +separated list of signer domains and identities for the message. When +&%dkim_verify_signers%& is not specified in the main configuration, +it defaults as: .code -dkim_verify_signers = $dkim_signing_domains +dkim_verify_signers = $dkim_signers .endd This leads to the default behaviour of calling &%acl_smtp_dkim%& for each DKIM signature in the message. Current DKIM verifiers may want to explicitly call the ACL for known domains or identities. This would be achieved as follows: .code -dkim_verify_signers = paypal.com:ebay.com:$dkim_signing_domains +dkim_verify_signers = paypal.com:ebay.com:$dkim_signers .endd This would result in &%acl_smtp_dkim%& always being called for "paypal.com" -and "ebay.com", plus all domains that have signatures in the message. You can -also be more creative in constructing your policy. Example: +and "ebay.com", plus all domains and identities that have signatures in the message. +You can also be more creative in constructing your policy. Example: .code -dkim_verify_signers = $sender_address_domain:$dkim_signing_domains +dkim_verify_signers = $sender_address_domain:$dkim_signers .endd +If a domain or identity is listed several times in the (expanded) value of +&%dkim_verify_signers%&, the ACL is only called once for that domain or identity. + + Inside the &%acl_smtp_dkim%&, the following expansion variables are available (from most to least important): .vlist +.vitem &%$dkim_cur_signer%& +The signer that is being evaluated in this ACL run. This can be domain or +an identity. This is one of the list items from the expanded main option +&%dkim_verify_signers%& (see above). .vitem &%$dkim_verify_status%& A string describing the general status of the signature. One of .ilist &%none%&: There is no signature in the message for the current domain or -identity. +identity (as reflected by &%$dkim_cur_signer%&). .next &%invalid%&: The signature could not be verified due to a processing error. More detail is available in &%$dkim_verify_reason%&. @@ -34455,14 +34492,12 @@ DKIM verification. It may of course also mean that the signature is forged. .endlist .vitem &%$dkim_domain%& The signing domain. IMPORTANT: This variable is only populated if there is -ab actual signature in the message. It does NOT neccessarily carry the -domain that is currently being evaluated. Please use the &%dkim_signers%& ACL -condition for that. +an actual signature in the message for the current domain or identity (as +reflected by &%$dkim_cur_signer%&). .vitem &%$dkim_identity%& -The signing identity. IMPORTANT: This variable is only populated if there is -ab actual signature in the message. It does NOT neccessarily carry the -identity that is currently being evaluated. Please use the &%dkim_signers%& ACL -condition for that. +The signing identity, if present. IMPORTANT: This variable is only populated +if there is an actual signature in the message for the current domain or +identity (as reflected by &%$dkim_cur_signer%&). .vitem &%$dkim_selector%& The key record selector string .vitem &%$dkim_algo%& @@ -34507,8 +34542,9 @@ In addition, two ACL conditions are provided: .vlist .vitem &%dkim_signers%& ACL condition that checks a colon-separated list of domains or identities -for a match against the domain or identity that the ACL is currently verifying. -This is typically used to restrict an ACL verb to a group of domains or identities, like: +for a match against the domain or identity that the ACL is currently verifying +(reflected by &%$dkim_cur_signer%&). This is typically used to restrict an ACL +verb to a group of domains or identities, like: .code # Warn when message apparently from GMail has no signature at all