kumomta/docs/userguide/configuration/domains.md

Configuring Inbound and Relay Domains

When listening via SMTP, it is common to simply define a list of relay_hosts that are permitted to connect and relay messages through the server. Any host that connects and does not match the list of relay hosts will be allowed to connect to the server, but will not be permitted to relay mail through the server.

kumo.start_esmtp_listener {
  listen = '0.0.0.0:25',

  -- override the default set of relay hosts
  relay_hosts = { '127.0.0.1', '192.168.1.0/24' },
}

Using the listener_domains.lua Policy Helper

For most basic use cases, it will be simpler to use the listener_domains.lua policy helper script to manage the listener domain configuration in a simple TOML file.

To use the helper, add the following to the top level of your server policy script:

local listener_domains = require 'policy-extras.listener_domains'

kumo.on(
  'get_listener_domain',
  listener_domains:setup { '/opt/kumomta/etc/listener_domains.toml' }
)

Then create a text file at /opt/kumomta/etc/listener_domains.toml with the following format:

{% call toml_data() %} ["*"]

You can specify * as a default, overridden by any more explicitly defined domains.

Since all options are false by default, this would only be needed to default

An option to true for all domains.

relay_to = false log_oob = true log_arf = true

["example.com"]

allow relaying mail from anyone, so long as it is

addressed to example.com

relay_to = true

["bounce.example.com"]

accept and log OOB bounce reports sent to bounce.example.com

log_oob = true

["fbl.example.com"]

accept and log ARF feedback reports sent to fbl.example.com

log_arf = true

["send.example.com"]

relay to anywhere, so long as the sender domain is send.example.com

and the connected peer matches one of the listed CIDR blocks

relay_from = [ '10.0.0.0/24' ]

["auth-send.example.com"]

relay to anywhere, so long as the sender domain is auth-send.example.com

and the connected peer has authenticated as any of the authorization identities

listed below using SMTP AUTH

relay_from_authz = [ 'username1', 'username2' ]

wildcards are permitted. This will match

.example.com that doesn't have

another non-wildcard entry explicitly

listed in this set of domains.

Note that "example.com" won't match

"*.example.com".

["*.example.com"]

You can specify multiple options if you wish

log_oob = true log_arf = true relay_to = true

and you can explicitly set options to false to

essentially exclude an entry from a wildcard

["www.example.com"] relay_to = false log_arf = false log_oob = false

Define a per-listener configuration

[listener."127.0.0.1:25"."*.example.com"] log_oob = false {% endcall %}

!!! note If you configure a domain for relay_to = true you will need to configure a routing domain in the Queues Helper so that KumoMTA knows where to relay the messages to internally, since an MX lookup will return the IP for your KumoMTA instance:

{% call toml_data() %}
[queue.'my.own.hostname']
routing_domain = '[10.0.0.1]'
{% endcall %}

Configuring Domains for Relaying, Bounces, and Feedback Loops

By default, if a host connects to the listener and is not listed in the relay_hosts directive, that host will not be permitted to inject messages. While that is acceptable for most outbound relaying, it is necessary in most use cases to also configure certain exceptions on a destination-domain basis for things such as inbound mail relay, out-of-band bounce processing, and feedback loop processing.

When a host not on the relay_hosts list connects to a listener and issues a RCPT TO command, the get_listener_domain hook is fired, allowing for policy to be applied based on the destination domain of the message.

To apply policy based on the domain, the make_listener_domain function is used:

kumo.on('get_listener_domain', function(domain, listener, conn_meta)
  if domain == 'example.com' then
    return kumo.make_listener_domain {
      relay_to = true,
      log_oob = 'LogThenDrop',
      log_arf = 'LogThenDrop',
    }
  end
end)

In the preceding example, the domain example.com is permitted for inbound relay, resulting in messages destined for the domain being accepted and queued, while messages will also be checked for whether they are OOB or FBL messages, which are processed, logged, and discarded.

Additional information on the log_oob and log_arf options can be found in the Configuring Bounce Classification and the Configuring Feedback Loop Processing chapters respectively.

For more information, see the make_listener_domain page of the Reference manual.