mirror/kumomta
1
0
Fork 0
mirror of https://github.com/mailscope/kumomta.git synced 2026-09-06 18:48:57 +00:00
Code Issues Packages Projects Releases Wiki Activity

sendingips.md: fix incorrect pool lua example

Browse Source 
I've seen this trip up at least two people so far.

While we're in there, update the example to show how to memoize and make
it both easier to write and more efficient at runtime.
This commit is contained in:
Wez Furlong
2023-08-11 09:30:31 -07:00
parent d0add809ae
commit a8ea458ced
1 changed files with 68 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/userguide/configuration/sendingips.md
+68 -20
View File
@@ -1,12 +1,20 @@
# Configuring Sending IPs
By default, all traffic injected to the KumoMTA server will be delivered using the default interface configured on the host server. For smaller installations this is acceptable, but best practices recommend separating mail streams into their own IPs addresses in order to isolate reputation and enable larger sending volumes than would be possible on a single IP address.
By default, all traffic injected to the KumoMTA server will be delivered using
the default interface configured on the host server. For smaller installations
this is acceptable, but best practices recommend separating mail streams into
their own IPs addresses in order to isolate reputation and enable larger
sending volumes than would be possible on a single IP address.
## Using the sources.lua Policy Helper
While the process for creating Egress Sources and Pools are defined below, most users will want to take advantage of the `sources.lua` policy helper. This is a supplemental script that takes care of the creation logic by leveraging a TOML configuration file you define.
While the process for creating Egress Sources and Pools are defined below, most
users will want to take advantage of the `sources.lua` policy helper. This is a
supplemental script that takes care of the creation logic by leveraging a TOML
configuration file you define.
To use the `sources.lua` policy helper, add the following to your server policy script:
To use the `sources.lua` policy helper, add the following to your server policy
script:
```lua
-- Configure source IPs.
@@ -14,7 +22,8 @@ local sources = require 'policy-extras.sources'
sources:setup { '/opt/kumomta/etc/sources.toml' }
```
In addition, create a file at `/opt/kumomta/etc/sources.toml` and populate it as follows:
In addition, create a file at `/opt/kumomta/etc/sources.toml` and populate it
as follows:
```toml
[source."ip-1"]
@@ -48,11 +57,20 @@ The sources you define can include any options listed for the [make_egress_sourc
## Making an Egress Source
In KumoMTA, source IPs are described in an *Egress Source.* And Egress Source represents an object that can be used to send messages and is not attached to a particular protocol. While the most common use case is an IP address used for SMTP, it could also define a specific outbound port for sending through port-based NAT, or a specific configuration for sending over HTTP.
In KumoMTA, source IPs are described in an *Egress Source.* And Egress Source
represents an object that can be used to send messages and is not attached to a
particular protocol. While the most common use case is an IP address used for
SMTP, it could also define a specific outbound port for sending through
port-based NAT, or a specific configuration for sending over HTTP.
An Egress Source is defined using the **`kumo.make_egress_source`** function, called during the init event. For more information, see the [make_egress_source](../../reference/kumo/make_egress_source.md) chapter of the Reference Manual.
An Egress Source is defined using the **`kumo.make_egress_source`** function,
called during the init event. For more information, see the
[make_egress_source](../../reference/kumo/make_egress_source.md) chapter of the
Reference Manual.
By default, the only option required for defining an Egress Source is a name, creating a logical grouping for messages used for queueing but still using the default server IP address:
By default, the only option required for defining an Egress Source is a name,
creating a logical grouping for messages used for queueing but still using the
default server IP address:
```lua
kumo.on('get_egress_source', function(source_name)
@@ -65,7 +83,13 @@ kumo.on('get_egress_source', function(source_name)
end)
```
Typically an Egress source is used to assign messages to a specific IP address for sending. It is a best practice for each source IP to have a unique hostname used during the EHLO command, that matches a PTR record that points to the external IP associated with the Egress Source. The IP address is set with the *source* address option and the hostname is set using the *ehlo_domain* option. The IP address used is not required to be unique to a given Egress Source:
Typically an Egress source is used to assign messages to a specific IP address
for sending. It is a best practice for each source IP to have a unique hostname
used during the EHLO command, that matches a PTR record that points to the
external IP associated with the Egress Source. The IP address is set with
the *source* address option and the hostname is set using the *ehlo_domain*
option. The IP address used is not required to be unique to a given Egress
Source:
```lua
kumo.on('get_egress_source', function(source_name)
@@ -81,7 +105,8 @@ kumo.on('get_egress_source', function(source_name)
end)
```
KumoMTA supports both IPv4 and IPv6 for sending, based on the source address assigned to the Egress Source:
KumoMTA supports both IPv4 and IPv6 for sending, based on the source address
assigned to the Egress Source:
```lua
kumo.on('get_egress_source', function(source_name)
@@ -99,29 +124,35 @@ end)
## Making an Egress Pool
Messages cannot be assigned directly to an Egress Source, but are instead assigned to an Egress Pool. An Egress Pool contains one or more Egress Sources, and messages assigned to the pool are assigned in a round-robin fashion by default, with weighted round-robin available as an option.
Messages cannot be assigned directly to an Egress Source, but are instead
assigned to an Egress Pool. An Egress Pool contains one or more Egress Sources,
and messages assigned to the pool are assigned in a round-robin fashion by
default, with weighted round-robin available as an option.
A given Egress Source can be added to multiple Egress Pools.
Egress Pools are defined using the **`kumo.make_egress_pool`** function, called during the `get_egress_pool` event:
Egress Pools are defined using the **`kumo.make_egress_pool`** function, called
during the `get_egress_pool` event:
```lua
-- Maps a source name to the corresponding IP address
local SOURCE_TO_IP = {
['ip-1'] = '10.0.0.1',
['ip-2'] = '10.0.0.2',
['ip-3'] = '10.0.0.3',
}
-- This makes it convenient to author the pools, but is not as efficient
-- as it could be. That is balanced out by using memoize below.
function setup_pools()
return {
kumo.make_egress_pool {
local pools = {
{
name = 'BestReputation',
entries = {
{ name = 'ip-1' },
},
},
kumo.make_egress_pool {
{
name = 'MediumReputation',
entries = {
{ name = 'ip-2', weight = 2 },
@@ -130,9 +161,19 @@ function setup_pools()
},
},
}
local result = {}
for _, pool in ipairs(pools) do
result[pool.name] = kumo.make_egress_pool(pool)
end
return result
end
local POOLS = setup_pools()
-- Wrap setup_pools as a caching version called get_pool_config
local get_pool_config = kumo.memoize(setup_pools, {
name = 'setup-my-pools',
ttl = '5 minutes',
capacity = 10,
})
kumo.on('get_egress_source', function(source_name)
return kumo.make_egress_source {
@@ -142,14 +183,21 @@ kumo.on('get_egress_source', function(source_name)
end)
kumo.on('get_egress_pool', function(pool_name)
return POOLS[pool_name]
local pools = get_pool_config()
return pools[pool_name]
end)
```
For more information, see the [make_egress_pool](../../reference/kumo/make_egress_pool.md) chapter of the Reference Manual.
For more information, see the
[make_egress_pool](../../reference/kumo/make_egress_pool.md) chapter of the
Reference Manual.
## Assigning Messages to Pools
It's not enough to simply create an Egress Source and assign it to an Egress Pool, the server requires explicit logic to know which message is assigned to which Egress Pool.
It's not enough to simply create an Egress Source and assign it to an Egress
Pool, the server requires explicit logic to know which message is assigned to
which Egress Pool.
This logic occurs in the events related to queue management, see the [Queue Management](./queuemanagement.md#configuring-egress-pool-assignment) chapter for more information.
This logic occurs in the events related to queue management, see the [Queue
Management](./queuemanagement.md#configuring-egress-pool-assignment) chapter
for more information.