mirror of
https://github.com/mailscope/kumomta.git
synced 2026-09-10 20:42:14 +00:00
Wez Furlong
b7c557c31a
Switch the configuration plumbing for pools and sources to be pull-based rather than push based. In other words, rather than defining them in the `init` event, you now need to supply them to the new `get_egress_pool` and `get_egress_source` events. Data is cached by default for 1 minute. This allows for new sources to come into being on-demand, and for data to age out and change over time, without requiring that the server be restarted. This commit updates the reference section, but there is some content in the user guide that refers to the old style of configuration that will need to be updated. refs: https://github.com/KumoCorp/kumomta/issues/13
141 lines
4.0 KiB
Markdown
141 lines
4.0 KiB
Markdown
# `kumo.make_egress_source {PARAMS}`
|
|
|
|
Defines an *egress source*, which is an entity associated with the source of
|
|
outbound traffic from the MTA. A source must be referenced by a
|
|
[pool](make_egress_pool.md) to be useful.
|
|
|
|
This function is intended to be used inside your
|
|
[get_egress_source](../events/get_egress_source.md) event handler.
|
|
|
|
A source must have at a minimum a *name*, which will be used in logging/reporting.
|
|
|
|
`PARAMS` is a lua table which may have the following keys:
|
|
|
|
## name
|
|
|
|
Required string.
|
|
|
|
The name of the source. If you call `kumo.define_egress_source` multiple
|
|
times with the same name, the most recently defined version of that name will replace
|
|
any previously defined source with that name.
|
|
|
|
```lua
|
|
kumo.on('get_egress_source', function(source_name)
|
|
-- Make a source that just has the requested name, but otherwise doesn't
|
|
-- specify any particular source configuration
|
|
return kumo.make_egress_source {
|
|
name = source_name,
|
|
}
|
|
end)
|
|
```
|
|
|
|
## source_address
|
|
|
|
Optional string.
|
|
|
|
If set, specifies the local IP address that should be used as the source of any
|
|
connection that will be made from this source.
|
|
|
|
If not specified, the kernel will select the IP address automatically.
|
|
|
|
|
|
```lua
|
|
kumo.on('get_egress_source', function(source_name)
|
|
if source_name == 'ip-1' then
|
|
-- Make a source that will emit from 10.0.0.1
|
|
return kumo.make_egress_source {
|
|
name = 'ip-1',
|
|
source_address = '10.0.0.1',
|
|
}
|
|
end
|
|
error 'you need to do something for other source names'
|
|
end)
|
|
```
|
|
|
|
!!! note
|
|
When using HA Proxy, the `source_address` will be used when connecting to the proxy.
|
|
You should use `ha_proxy_source_address` to specify the actual address to use
|
|
from the HA Proxy instance to the destination.
|
|
|
|
## ehlo_domain
|
|
|
|
Optional string.
|
|
|
|
If set, specifies the hostname to be passed with the EHLO command when the server connects to a remote host.
|
|
|
|
If not specified, the kernel will use the server's hostname.
|
|
|
|
```lua
|
|
kumo.on('get_egress_source', function(source_name)
|
|
if source_name == 'ip-1' then
|
|
-- Make a source that will emit from 10.0.0.1
|
|
kumo.make_egress_source {
|
|
name = 'ip-1',
|
|
source_address = '10.0.0.1',
|
|
ehlo_domain = 'mta1.examplecorp.com',
|
|
}
|
|
end
|
|
error 'you need to do something for other source names'
|
|
end)
|
|
```
|
|
|
|
## remote_port
|
|
|
|
Optional integer.
|
|
|
|
If set, will override the remote SMTP port number. This is useful in scenarios
|
|
where your network is set to manage the egress address based on port mapping.
|
|
|
|
This option takes precedence over
|
|
[kumo.make_egress_path().smtp_port](make_egress_path.md#smtp_port).
|
|
|
|
## ha_proxy_server
|
|
|
|
Optional string.
|
|
|
|
If both `ha_proxy_server` and `ha_proxy_source_address` are specified, then
|
|
SMTP connections will be made via an HA Proxy server.
|
|
|
|
`ha_proxy_server` specifies the address and port of the proxy server.
|
|
|
|
```lua
|
|
kumo.on('get_egress_source', function(source_name)
|
|
if source_name == 'ip-1' then
|
|
-- Make a source that will emit from 10.0.0.1, via a proxy server
|
|
kumo.make_egress_source {
|
|
name = 'ip-1',
|
|
ha_proxy_source_address = '10.0.0.1',
|
|
ha_proxy_server = '10.0.0.1:5000',
|
|
ehlo_domain = 'mta1.examplecorp.com',
|
|
}
|
|
end
|
|
error 'you need to do something for other source names'
|
|
end)
|
|
```
|
|
|
|
## ha_proxy_source_address
|
|
|
|
Optional string.
|
|
|
|
Specifies the source address that the HA Proxy server should use when
|
|
initiating a connection.
|
|
|
|
!!! note
|
|
The HA Proxy protocol doesn't provide a mechanism for reporting
|
|
whether binding to this address was successful. From the perspective
|
|
of KumoMTA, invalid proxy configuration will appear as a timeout
|
|
with no additional context.
|
|
|
|
## ttl
|
|
|
|
Optional *time-to-live* specifying how long the source definition should be
|
|
cached. The cache has two purposes:
|
|
|
|
* To limit the number of configurations kept in memory at any one time
|
|
* To enable data to be refreshed from external storage, such as a json data
|
|
file, or a database
|
|
|
|
The default TTL is 60 seconds, but you can specify any duration using a string
|
|
like `"5 mins"` to specify 5 minutes.
|
|
|