route-map

smtpf sits in front of one or more mail transfer agents (MTA) on SMTP port 25. It acts as a proxy, filtering and forwarding mail to one or more MTAs, which can be on the same machine or different machines. To that end the file referenced by the route-map option tells smtpf what domains, hosts, or mail addresses you accept mail for, where to route them, where to optionally verify users, and/or if to allow relaying.

The file referenced by the route-map option can be a simple text file, SQLite3 database, or socket-map server. The recommended configuration uses an SQLite3 database generated from a route.cf text file. This can be done in one of two ways:

# kvmap -l \
  "route!sql!/etc/smtpf/route.sq3" \
  < /etc/smtpf/route.cf

or simply by using the supplied Makefile

# cd /etc/smtpf
# make route.sq3

If you do not specify the route.sq3 explicitly, then the make command will build all the configuration files if necessary.

The route.cf text file consists of lines of key-value pairs. Each line consists of a key field separated by white space from the value field, which is the remainder of the line. Comments start with a hash (#) on a line by themselves. The key lookups are case insensitive, while the values are case sensitive. The order in which keys are looked up is outlined by the access-map option.

The key can be the connecting SMTP client IPv4 or IPv6 address or part thereof, the client host name found from a DNS PTR lookup or part thereof, or a recipient's domain name or part thereof for which we accept mail. The key is prefixed with a route: tag. Other tags may be added in future releases.

The value is a semi-colon (;) separated list of one or more parameters. Currently supported parameters are FORWARD:, RCPT:, and RELAY (case sensitive). The FORWARD: and RCPT: parameters each specify a comma (,) separated list of one or more hosts by IP address or name.

Local MTA

When a local MTA operates on the same machine as smtpf, it will have to be configured to accept connections on a port other than SMTP port 25, which smtpf will be listening on. In our examples, we use local host port 26 for the local MTA. When specifying IPv6 addresses with a port number, the address must appear within square brackets ([, ]), for example "[2001:0DB8::1234]:26".

This example shows all the possible variants for the local route using a local MTA on the same machine, though the preferred form is route:local. The other variants are still supported for backwards compatibility with previous releases.

route:local	FORWARD: localhost:26
route:127.0.0.1	FORWARD: 127.0.0.1:26
route:::1	FORWARD: [::1]:26

Local Route

The local route is very important in smtpf. It is used for queuing outbound messages from a RELAY, queuing messages for SMTP authenticated senders, and for processing messages for unqualified recipients, ie. those that have no domain name part in the address. The local route can be a list of other hosts machines as shown below. Note that the hosts specified in the local route must not use the smtpf server as a smart-host, otherwise you can end up with a mail loop.

This example shows all the possible variants for the local route, though the preferred form is route:local. The other variants are still supported for backwards compatibility with previous releases.

route:local	FORWARD: [2001:db8::1]:26, other.host
route:127.0.0.1	FORWARD: 192.0.2.1
route:::1	FORWARD: 2001:db8::1

FORWARD & RELAY

After the local route, the next most important records that must be added to the route-map are the recipient domains we will accept mail for. For example:

route:example.com	FORWARD: 127.0.0.1:26, 192.168.0.9
route:snertsoft.com	FORWARD: 192.0.2.1
route:info@snertsoft.com	FORWARD: 192.0.2.2

The FORWARD: parameter tells smtpf where to send a message for a recipient of that domain. When you specify more than one FORWARD: host, as was done for route:example.com above, then they are tried in left to right order until one of them answers (see also route-forward-selection). If no host answers, then that recipient will be temporarily rejected.

Note that it is also possible to route individual mail addresses as shown by route:info@snertsoft.com to a different host, instead of the default for the domain, route:snertsoft.com.

When creating a route-map, it is usually a good idea to specify which hosts or subnets from your LAN are allowed to relay. For example:

route:10.0.0.1	RELAY
route:192.168.0	RELAY
route:FE80:0000	RELAY
route:example.com	FORWARD: 192.168.1.2; RELAY

The RELAY tag should be used sparingly, typically only for your LAN and trusted hosts. Any client connection that is marked as a RELAY, will have their mail sent to the local route for queuing and white listed through many, but not all, of the tests (anti-virus scanning will always be done when enabled and if required, EMEW transformation of the Message-Id header).

When a RELAY connects, all mail is sent to the local route for queuing. It is imperative that the SMTP servers handling the local route know how to relay their domains correctly, otherwise mail may fail to be delivered.

The route:example.com shows an instance where inbound mail destined for example.com is forwarded to a specific host on the LAN and outbound mail from any host within the example.com domain is relayed. The point to note here is that inbound mail route selection is taken based on the domain name of the recipient address, while relay selection is based on the DNS PTR record found based on the connected SMTP client's IP address. If you do not have reverse DNS entries for your internal hosts, then you must specify RELAY entries by IP address or family as shown above.

Call-Ahead

The RCPT: parameter tells smtpf to perform a call-ahead to another set of hosts in order to verify if the recipient is valid. This parameter is optional and is only recommended when the FORWARD: host is some intermediate MTA, such as an anti-virus appliance or gateway machine that has no knowledge of recipients for that domain. RCPT: allows you to jump over one or more intermediate servers to talk directly with the final mail store. Accept and reject results from a call-ahead are cached for future use, while temporary failure results are not cached at all. Only the expire time of an accept result will be touched (see cache-accept-ttl).

route:example.net	FORWARD: scan.our.domain; RCPT: 192.168.1.2
route:example.org	FORWARD: scan.our.domain; RCPT: exchange.our.domain

Note that some MTA by default use an accept-then-bounce model and so do not work with call-ahead very well, such as default configurations for Microsoft Exchange and Domino servers. An accept-then-bounce server will always accept any SMTP RCPT TO: command whether it be valid or not. Typically such servers can be configured to verify the RCPT TO: argument the moment the command is received (instead of delaying until after the message body) so as to provide a more useful and immediate response to the call-ahead.

The call-ahead test will perform a false-RCPT test to detect accept-then-bounce servers and cache the result. If the server does accept-then-bounce, then future call-ahead attempts will be skipped. Alternatively, if an accept-then-bounce server cannot be configured otherwise, then do not use the RCPT: parameter.

AUTH Support

smtpf has support for SMTP AUTH PLAIN and AUTH LOGIN methods. If you need SMTP AUTH support, then be sure to enable both smtp-enable-esmtp, auth-delay-checks, which will postpone some connection and HELO/EHLO tests until a MAIL FROM: is received.

If the authentication-Id given to the AUTH command is fully qualified, ie. it has the form userid@sender.domain, then AUTH command is first proxied to the RCPT: or FORWARD: host of the route:sender.domain; if that fails, then the unqualified version of the authentication-Id is tried. If the authentication-Id is not qualified, ie. is just a simple userid, then the AUTH command is proxied to the RCPT: or FORWARD: host of the local route.

All mail sent over an authenticated session is forwarded (queued) to the SMTP host that authenticated the credentials. SMTP AUTH support in smtpf is limited and it is recommended that a proper MSA be employed.

ETRN Support

smtpf has support for SMTP ETRN, where ETRN commands are simply relayed to the local route, which is responsible for queuing. If the local route refers to more than one forward host, then those hosts must all share the same mail queue, otherwise the behaviour is undefined.

- TOP -

Copyright 2006, 2016 by SnertSoft. All rights reserved.
BarricadeMX trademark & patents pending.