Skip to content

kumo.on('smtp_server_get_dynamic_parameters', function(listener, conn_meta))

Since: Dev Builds Only

The functionality described in this section requires a dev build of KumoMTA. You can obtain a dev build by following the instructions in the Installation section.

Note

This option is primarily intended to be used together with a wildcard listen value of 0.0.0.0 for an IPv4 listener or :: for an IPv6 listener where you desire to dynamically configure IP based virtual MTA service.

Called by the ESMTP server when a new server session has accepted a connection from a client, and offers a chance to update the configuration for the listener dynamically. This event triggers before smtp_server_connection_accepted.

The parameters are:

  • listener - the stringified version of the listener address, such as 0.0.0.0:25
  • conn_meta - the Connection Metadata object

The return value must be a table holding ESMTP listener parameter overrides that you wish to apply to the existing listener parameters for this connection. The fields that you specify in the return value will override the fields that were already configured. Almost every field described under kumo.start_esmtp_listener can be used; those that cannot will indicate it in their individual documentation pages.

The following example is equivalent to the via example, except that rather than the via parameters being statically configured during the init event, they are computed for every new connection:

kumo.on('init', function()
  kumo.start_esmtp_listener {
    listen = '0.0.0.0:25',
  }
end)

kumo.on('smtp_server_get_dynamic_parameters', function(listener, conn_meta)
  return {
    via = {
      -- When clients connect to this server via its 10.0.0.1 IP
      -- address, we will use the hostname and TLS parameters
      -- defined in this block
      ['10.0.0.1'] = {
        hostname = 'mx.example-customer.com',
        tls_certificate = '/path/to/customer1.cert',
        tls_private_key = '/path/to/customer1.key',
      },
      -- When clients connect to this server via its 10.0.0.2 IP
      -- address, we will use the hostname and TLS parameters
      -- defined in this block
      ['10.0.0.2'] = {
        hostname = 'mx.other-customer.com',
        tls_certificate = '/path/to/customer2.cert',
        tls_private_key = '/path/to/customer2.key',
      },
    },
  }
end)

This late binding of the configuration can be used to aid in dynamically updating the set of listeners on a wildcard port.

For example, you could put the listener overrides into a TOML or JSON file that has the same shape as the listener parameters:

[via.'10.0.0.1']
hostname = 'mx.example-customer.com'
tls_certificate = '/path/to/customer1.cert'
tls_private_key = '/path/to/customer1.key'

[via.'10.0.0.2']
hostname = 'mx.other-customer.com'
tls_certificate = '/path/to/customer2.cert'
tls_private_key = '/path/to/customer2.key'

Then change the policy code to load it:

kumo.on('init', function()
  kumo.start_esmtp_listener {
    listen = '0.0.0.0:25',
  }
end)

kumo.on('smtp_server_get_dynamic_parameters', function(listener, conn_meta)
  return kumo.serde.toml_load '/opt/kumometa/etc/policy/listener_params.toml'
end)

Depending upon the size of the data you are loading, and especially if you choose to load data from an external service, you should consider using kumo.memoize to cache the data.