kumomta/docs/userguide/configuration/domains.md

Configuring Inbound and Relay Domains

When configuring an SMTP listener, 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 rejected immediately.

While a simple list of relay_hosts is appropriate for outbound relay, even organizations focused on email sending will also need to receive inbound messages in the form of out-of-bound bounce messages, AKA Message Disposition Notification (MDN) messages, as well as Feedback Loop (FBL) abuse reports in Abuse Reporting Format (ARF).

Additionally, some mixed-sending environments may need to add additional security by limiting which domains a given injecting host is permitted to send from. This helps prevent a malicious system from impersonating a peer by injecting messages with the peer's domain, something possible when only relay_hosts are configured.

To address these use cases, listeners can be configured with domain-level configuration:

!!!note It is a best practice to use separate listeners for hosts inside and outside of your network. Typically the relay_to, log_oop, and log_arf options would be configured for listeners on the external network, where the relay_from option could appear on both internal and external listeners.

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' },

  -- Configure the domains that are allowed for outbound & inbound relay,
  -- Out-Of-Band bounces, and Feedback Loop Reports.
  -- See https://docs.kumomta.com/userguide/configuration/domains/
  domains = {
    ['examplecorp.com'] = {
      -- allow relaying mail from any source, so long as it is
      -- addressed to examplecorp.com, for inbound mail.
      relay_to = true,
    },
    ['send.examplecorp.com'] = {
      -- relay to anywhere, so long as the sender domain is
      -- send.examplecorp.com and the connected peer matches one of the
      -- listed CIDR blocks, helps prevent abuse by less trusted peers.
      relay_from = { '10.0.0.0/24' },
    },
    ['bounce.examplecorp.com'] = {
      -- accept and log OOB bounce reports sent to bounce.examplecorp.com
      log_oob = true,
    },
    ['fbl.examplecorp.com'] = {
      -- accept and log ARF feedback reports sent to fbl.examplecorp.com
      log_arf = true,
    },
  },
}

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.

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)
  if domain == 'example.com' then
    return kumo.make_listener_domain {
      relay_to = true,
    }
  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.

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

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:

["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' }

# wildcards are permitted. This will match
# <anything>.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