1# Remote MX delivery23Module that implements message delivery to remote MTAs discovered via DNS MX4records. You probably want to use it with queue module for reliability.56If a message check marks a message as 'quarantined', remote module7will refuse to deliver it.89## Configuration directives1011```12target.remote {13 hostname mx.example.org14 debug no15}16```1718### hostname _domain_19Default: global directive value2021Hostname to use client greeting (EHLO/HELO command). Some servers require it to22be FQDN, SPF-capable servers check whether it corresponds to the server IP23address, so it is better to set it to a domain that resolves to the server IP.2425---2627### limits { ... }28Default: no limits2930See ['limits' directive for SMTP endpoint](/reference/endpoints/smtp/#rate-concurrency-limiting).31It works the same except for address domains used for32per-source/per-destination are as observed when message exits the server.3334---3536### local_ip _ip-address_37Default: empty3839Choose the local IP to bind for outbound SMTP connections.4041---4243### force_ipv4 _boolean_44Default: `false`4546Force resolving outbound SMTP domains to IPv4 addresses. Some server providers47do not offer a way to properly set reverse PTR domains for IPv6 addresses; this48option makes maddy only connect to IPv4 addresses so that its public IPv4 address49is used to connect to that server, and thus reverse PTR checks are made against50its IPv4 address.5152Warning: this may break sending outgoing mail to IPv6-only SMTP servers.5354---5556### connect_timeout _duration_57Default: `5m`5859Timeout for TCP connection establishment.6061RFC 5321 recommends 5 minutes for "initial greeting" that includes TCP62handshake. maddy uses two separate timers - one for "dialing" (DNS A/AAAA63lookup + TCP handshake) and another for "initial greeting". This directive64configures the former. The latter is not configurable and is hardcoded to be655 minutes.6667---6869### command_timeout _duration_70Default: `5m`7172Timeout for any SMTP command (EHLO, MAIL, RCPT, DATA, etc).7374If STARTTLS is used this timeout also applies to TLS handshake.7576RFC 5321 recommends 5 minutes for MAIL/RCPT and 3 minutes for77DATA.7879---8081### submission_timeout _duration_82Default: `12m`8384Time to wait after the entire message is sent (after "final dot").8586RFC 5321 recommends 10 minutes.8788---8990### debug _boolean_91Default: global directive value9293Enable verbose logging.9495---9697### requiretls_override _boolean_98Default: `true`99100Allow local security policy to be disabled using 'TLS-Required' header field in101sent messages. Note that the field has no effect if transparent forwarding is102used, message body should be processed before outbound delivery starts for it103to take effect (e.g. message should be queued using 'queue' module).104105---106107### relaxed_requiretls _boolean_108Default: `true`109110This option disables strict conformance with REQUIRETLS specification and111allows forwarding of messages 'tagged' with REQUIRETLS to MXes that are not112advertising REQUIRETLS support. It is meant to allow REQUIRETLS use without the113need to have support from all servers. It is based on the assumption that114server referenced by MX record is likely the final destination and therefore115there is only need to secure communication towards it and not beyond.116117---118119### conn_reuse_limit _integer_120Default: `10`121122Amount of times the same SMTP connection can be used.123Connections are never reused if the previous DATA command failed.124125---126127### conn_max_idle_count _integer_128Default: `10`129130Max. amount of idle connections per recipient domains to keep in cache.131132---133134### conn_max_idle_time _integer_135Default: `150` (2.5 min)136137Amount of time the idle connection is still considered potentially usable.138139---140141## Security policies142143### mx_auth { ... }144Default: no policies145146'remote' module implements a number of of schemes and protocols necessary to147ensure security of message delivery. Most of these schemes are concerned with148authentication of recipient server and TLS enforcement.149150To enable mechanism, specify its name in the `mx_auth` directive block:151152```153mx_auth {154 dane155 mtasts156}157```158159Additional configuration is possible if supported by the mechanism by160specifying additional options as a block for the corresponding mechanism.161E.g.162163```164mtasts {165 cache ram166}167```168169If the `mx_auth` directive is not specified, no mechanisms are enabled. Note170that, however, this makes outbound SMTP vulnerable to a numerous downgrade171attacks and hence not recommended.172173It is possible to share the same set of policies for multiple 'remote' module174instances by defining it at the top-level using `mx_auth` module and then175referencing it using standard & syntax:176177```178mx_auth outbound_policy {179 dane180 mtasts {181 cache ram182 }183}184185# ... somewhere else ...186187deliver_to remote {188 mx_auth &outbound_policy189}190191# ... somewhere else ...192193deliver_to remote {194 mx_auth &outbound_policy195 tls_client { ... }196}197```198199---200201### MTA-STS202203Checks MTA-STS policy of the recipient domain. Provides proper authentication204and TLS enforcement for delivery, but partially vulnerable to persistent active205attacks.206207Sets MX level to "mtasts" if the used MX matches MTA-STS policy even if it is208not set to "enforce" mode.209210```211mtasts {212 cache fs213 fs_dir StateDirectory/mtasts_cache214}215```216217### cache `fs` | `ram`218Default: `fs`219220Storage to use for MTA-STS cache. 'fs' is to use a filesystem directory, 'ram'221to store the cache in memory.222223It is recommended to use 'fs' since that will not discard the cache (and thus224cause MTA-STS security to disappear) on server restart. However, using the RAM225cache can make sense for high-load configurations with good uptime.226227### fs_dir _directory_228Default: `StateDirectory/mtasts_cache`229230Filesystem directory to use for policies caching if 'cache' is set to 'fs'.231232---233234### DNSSEC235236Checks whether MX records are signed. Sets MX level to "dnssec" is they are.237238maddy does not validate DNSSEC signatures on its own. Instead it relies on239the upstream resolver to do so by causing lookup to fail when verification240fails and setting the AD flag for signed and verified zones. As a safety241measure, if the resolver is not 127.0.0.1 or ::1, the AD flag is ignored.242243DNSSEC is currently not supported on Windows and other platforms that do not244have the /etc/resolv.conf file in the standard format.245246```247dnssec { }248```249250---251252### DANE253254Checks TLSA records for the recipient MX. Provides downgrade-resistant TLS255enforcement.256257Sets TLS level to "authenticated" if a valid and matching TLSA record uses258DANE-EE or DANE-TA usage type.259260See above for notes on DNSSEC. DNSSEC support is required for DANE to work.261262```263dane { }264```265266---267268### Local policy269270Checks effective TLS and MX levels (as set by other policies) against local271configuration.272273```274local_policy {275 min_tls_level none276 min_mx_level none277}278```279280Using `local_policy off` is equivalent to setting both directives to `none`.281282### min_tls_level `none` | `encrypted` | `authenticated`283Default: `encrypted`284285Set the minimal TLS security level required for all outbound messages.286287See [Security levels](/seclevels) page for details.288289### min_mx_level `none` | `mtasts` | `dnssec`290Default: `none`291292Set the minimal MX security level required for all outbound messages.293294See [Security levels](/seclevels) page for details.295