+.vitem &%$dkim_selector%&
+The key record selector string.
+
+.vitem &%$dkim_algo%&
+The algorithm used. One of 'rsa-sha1' or 'rsa-sha256'.
+
+.vitem &%$dkim_canon_body%&
+The body canonicalization method. One of 'relaxed' or 'simple'.
+
+.vitem &%dkim_canon_headers%&
+The header canonicalization method. One of 'relaxed' or 'simple'.
+
+.vitem &%$dkim_copiedheaders%&
+A transcript of headers and their values which are included in the signature
+(copied from the 'z=' tag of the signature).
+Note that RFC6376 requires that verification fail if the From: header is
+not included in the signature. Exim does not enforce this; sites wishing
+strict enforcement should code the check explicitly.
+
+.vitem &%$dkim_bodylength%&
+The number of signed body bytes. If zero ("0"), the body is unsigned. If no
+limit was set by the signer, "9999999999999" is returned. This makes sure
+that this variable always expands to an integer value.
+
+.vitem &%$dkim_created%&
+UNIX timestamp reflecting the date and time when the signature was created.
+When this was not specified by the signer, "0" is returned.
+
+.vitem &%$dkim_expires%&
+UNIX timestamp reflecting the date and time when the signer wants the
+signature to be treated as "expired". When this was not specified by the
+signer, "9999999999999" is returned. This makes it possible to do useful
+integer size comparisons against this value.
+
+.vitem &%$dkim_headernames%&
+A colon-separated list of names of headers included in the signature.
+
+.vitem &%$dkim_key_testing%&
+"1" if the key record has the "testing" flag set, "0" if not.
+
+.vitem &%$dkim_key_nosubdomains%&
+"1" if the key record forbids subdomaining, "0" otherwise.
+
+.vitem &%$dkim_key_srvtype%&
+Service type (tag s=) from the key record. Defaults to "*" if not specified
+in the key record.
+
+.vitem &%$dkim_key_granularity%&
+Key granularity (tag g=) from the key record. Defaults to "*" if not specified
+in the key record.
+
+.vitem &%$dkim_key_notes%&
+Notes from the key record (tag n=).
+
+.vitem &%$dkim_key_length%&
+Number of bits in the key.
+.endlist
+
+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
+(reflected by &%$dkim_cur_signer%&). This is typically used to restrict an ACL
+verb to a group of domains or identities. For example:
+
+.code
+# Warn when Mail purportedly from GMail has no gmail signature
+warn log_message = GMail sender without gmail.com DKIM signature
+ sender_domains = gmail.com
+ dkim_signers = gmail.com
+ dkim_status = none
+.endd
+
+Note that the above does not check for a total lack of DKIM signing;
+for that check for empty &$h_DKIM-Signature:$& in the data ACL.
+
+.vitem &%dkim_status%&
+ACL condition that checks a colon-separated list of possible DKIM verification
+results against the actual result of verification. This is typically used
+to restrict an ACL verb to a list of verification outcomes, for example:
+
+.code
+deny message = Mail from Paypal with invalid/missing signature
+ sender_domains = paypal.com:paypal.de
+ dkim_signers = paypal.com:paypal.de
+ dkim_status = none:invalid:fail
+.endd
+
+The possible status keywords are: 'none','invalid','fail' and 'pass'. Please
+see the documentation of the &%$dkim_verify_status%& expansion variable above
+for more information of what they mean.
+.endlist
+
+. ////////////////////////////////////////////////////////////////////////////
+. ////////////////////////////////////////////////////////////////////////////
+
+.chapter "Proxies" "CHAPproxies" &&&
+ "Proxy support"
+.cindex "proxy support"
+.cindex "proxy" "access via"
+
+A proxy is an intermediate system through which communication is passed.
+Proxies may provide a security, availability or load-distribution function.
+
+
+.section "Inbound proxies" SECTproxyInbound
+.cindex proxy inbound
+.cindex proxy "server side"
+.cindex proxy "Proxy protocol"
+.cindex "Proxy protocol" proxy
+
+Exim has support for receiving inbound SMTP connections via a proxy
+that uses &"Proxy Protocol"& to speak to it.
+To include this support, include &"SUPPORT_PROXY=yes"&
+in Local/Makefile.
+
+It was built on specifications from:
+(&url(http://haproxy.1wt.eu/download/1.5/doc/proxy-protocol.txt)).
+That URL was revised in May 2014 to version 2 spec:
+(&url(http://git.1wt.eu/web?p=haproxy.git;a=commitdiff;h=afb768340c9d7e50d8e)).
+
+The purpose of this facility is so that an application load balancer,
+such as HAProxy, can sit in front of several Exim servers
+to distribute load.
+Exim uses the local protocol communication with the proxy to obtain
+the remote SMTP system IP address and port information.
+There is no logging if a host passes or
+fails Proxy Protocol negotiation, but it can easily be determined and
+recorded in an ACL (example is below).
+
+Use of a proxy is enabled by setting the &%hosts_proxy%&
+main configuration option to a hostlist; connections from these
+hosts will use Proxy Protocol.
+
+The following expansion variables are usable
+(&"internal"& and &"external"& here refer to the interfaces
+of the proxy):
+.display
+&'proxy_external_address '& IP of host being proxied or IP of remote interface of proxy
+&'proxy_external_port '& Port of host being proxied or Port on remote interface of proxy
+&'proxy_local_address '& IP of proxy server inbound or IP of local interface of proxy
+&'proxy_local_port '& Port of proxy server inbound or Port on local interface of proxy
+&'proxy_session '& boolean: SMTP connection via proxy
+.endd
+If &$proxy_session$& is set but &$proxy_external_address$& is empty
+there was a protocol error.
+
+Since the real connections are all coming from the proxy, and the
+per host connection tracking is done before Proxy Protocol is
+evaluated, &%smtp_accept_max_per_host%& must be set high enough to
+handle all of the parallel volume you expect per inbound proxy.
+With the option set so high, you lose the ability
+to protect your server from many connections from one IP.
+In order to prevent your server from overload, you
+need to add a per connection ratelimit to your connect ACL.
+A possible solution is:
+.display
+ # Set max number of connections per host
+ LIMIT = 5
+ # Or do some kind of IP lookup in a flat file or database
+ # LIMIT = ${lookup{$sender_host_address}iplsearch{/etc/exim/proxy_limits}}
+
+ defer message = Too many connections from this IP right now
+ ratelimit = LIMIT / 5s / per_conn / strict
+.endd
+
+
+
+.section "Outbound proxies" SECTproxySOCKS
+.cindex proxy outbound
+.cindex proxy "client side"
+.cindex proxy SOCKS
+.cindex SOCKS proxy
+Exim has support for sending outbound SMTP via a proxy
+using a protocol called SOCKS5 (defined by RFC1928).
+The support can be optionally included by defining SUPPORT_SOCKS=yes in
+Local/Makefile.
+
+Use of a proxy is enabled by setting the &%socks_proxy%& option
+on an smtp transport.
+The option value is expanded and should then be a list
+(colon-separated by default) of proxy specifiers.
+Each proxy specifier is a list
+(space-separated by default) where the initial element
+is an IP address and any subsequent elements are options.
+
+Options are a string <name>=<value>.
+The list of options is in the following table:
+.display
+&'auth '& authentication method
+&'name '& authentication username
+&'pass '& authentication password
+&'port '& tcp port
+&'tmo '& connection timeout
+&'pri '& priority
+&'weight '& selection bias
+.endd
+
+More details on each of these options follows:
+
+.ilist
+.cindex authentication "to proxy"
+.cindex proxy authentication
+&%auth%&: Either &"none"& (default) or &"name"&.
+Using &"name"& selects username/password authentication per RFC 1929
+for access to the proxy.
+Default is &"none"&.
+.next
+&%name%&: sets the username for the &"name"& authentication method.
+Default is empty.
+.next
+&%pass%&: sets the password for the &"name"& authentication method.
+Default is empty.
+.next
+&%port%&: the TCP port number to use for the connection to the proxy.
+Default is 1080.
+.next
+&%tmo%&: sets a connection timeout in seconds for this proxy.
+Default is 5.
+.next
+&%pri%&: specifies a priority for the proxy within the list,
+higher values being tried first.
+The default priority is 1.
+.next
+&%weight%&: specifies a selection bias.
+Within a priority set servers are queried in a random fashion,
+weighted by this value.
+The default value for selection bias is 1.
+.endlist
+
+Proxies from the list are tried according to their priority
+and weight settings until one responds. The timeout for the
+overall connection applies to the set of proxied attempts.
+
+.section Logging SECTproxyLog
+To log the (local) IP of a proxy in the incoming or delivery logline,
+add &"+proxy"& to the &%log_selector%& option.
+This will add a component tagged with &"PRX="& to the line.
+
+. ////////////////////////////////////////////////////////////////////////////
+. ////////////////////////////////////////////////////////////////////////////
+
+.chapter "Internationalisation" "CHAPi18n" &&&
+ "Internationalisation""
+.cindex internationalisation "email address"
+.cindex EAI
+.cindex i18n
+.cindex UTF-8 "mail name handling"
+
+Exim has support for Internationalised mail names.
+To include this it must be built with SUPPORT_I18N and the libidn library.
+Standards supported are RFCs 2060, 5890, 6530 and 6533.
+
+.section "MTA operations" SECTi18nMTA
+.cindex SMTPUTF8 "ESMTP option"
+The main configuration option &%smtputf8_advertise_hosts%& specifies
+a host list. If this matches the sending host and
+accept_8bitmime is true (the default) then the ESMTP option
+SMTPUTF8 will be advertised.
+
+If the sender specifies the SMTPUTF8 option on a MAIL command
+international handling for the message is enabled and
+the expansion variable &$message_smtputf8$& will have value TRUE.
+
+The option &%allow_utf8_domains%& is set to true for this
+message. All DNS lookups are converted to a-label form
+whatever the setting of &%allow_utf8_domains%&
+when Exim is built with SUPPORT_I18N.
+
+Both localparts and domain are maintained as the original
+UTF-8 form internally; any comparison or regular-expression use will
+require appropriate care. Filenames created, eg. by
+the appendfile transport, will have UTF-8 names.
+
+HELO names sent by the smtp transport will have any UTF-8
+components expanded to a-label form,
+and any certificate name checks will be done using the a-label
+form of the name.
+
+.cindex log protocol
+.cindex SMTPUTF8 logging
+Log lines and Received-by: header lines will acquire a "utf8"
+prefix on the protocol element, eg. utf8esmtp.
+
+The following expansion operators can be used:
+.code
+${utf8_domain_to_alabel:str}
+${utf8_domain_from_alabel:str}
+${utf8_localpart_to_alabel:str}
+${utf8_localpart_from_alabel:str}
+.endd
+
+ACLs may use the following modifier:
+.display
+control = utf8_downconvert
+control = utf8_downconvert/<value>
+.endd
+This sets a flag requiring that addresses are converted to
+a-label form before smtp delivery, for use in a
+Message Submission Agent context.
+If a value is appended it may be:
+.display
+&`1 `& (default) mandatory downconversion
+&`0 `& no downconversion
+&`-1 `& if SMTPUTF8 not supported by destination host
+.endd
+
+If mua_wrapper is set, the utf8_downconvert control
+is initially set to -1.
+
+
+There is no explicit support for VRFY and EXPN.
+Configurations supporting these should inspect
+&$smtp_command_argument$& for an SMTPUTF8 argument.
+
+There is no support for LMTP on Unix sockets.
+Using the "lmtp" protocol option on an smtp transport,
+for LMTP over TCP, should work as expected.
+
+There is no support for DSN unitext handling,
+and no provision for converting logging from or to UTF-8.
+
+
+
+.section "MDA operations" SECTi18nMDA
+To aid in constructing names suitable for IMAP folders
+the following expansion operator can be used:
+.code
+${imapfolder {<string>} {<sep>} {<specials>}}
+.endd
+
+The string is converted from the charset specified by
+the "headers charset" command (in a filter file)
+or &%headers_charset%& main configuration option (otherwise),
+to the
+modified UTF-7 encoding specified by RFC 2060,
+with the following exception: All occurences of <sep>
+(which has to be a single character)
+are replaced with periods ("."), and all periods and slashes that are not
+<sep> and are not in the <specials> string are BASE64 encoded.
+
+The third argument can be omitted, defaulting to an empty string.
+The second argument can be omitted, defaulting to "/".
+
+This is the encoding used by Courier for Maildir names on disk, and followed
+by many other IMAP servers.
+
+Examples:
+.display
+&`${imapfolder {Foo/Bar}} `& yields &`Foo.Bar`&
+&`${imapfolder {Foo/Bar}{.}{/}} `& yields &`Foo&&AC8-Bar`&
+&`${imapfolder {Räksmörgås}} `& yields &`R&&AOQ-ksm&&APY-rg&&AOU-s`&
+.endd
+
+Note that the source charset setting is vital, and also that characters
+must be representable in UTF-16.
git://git.exim.org / exim.git / blobdiff