diff --git a/content/momentum/4/config-options-summary.md b/content/momentum/4/config-options-summary.md index 7a784f35..d77f1983 100644 --- a/content/momentum/4/config-options-summary.md +++ b/content/momentum/4/config-options-summary.md @@ -274,8 +274,8 @@ The `Version` column indicated the version(s) of Momentum that support the optio | [open_tracking_scheme](/momentum/4/config/open-tracking-scheme) – Set the hyperlink scheme to use for open tracking links in SMTP injections | string | http | 4.1-HF4 (beta) | esmtp_listener, listen, pathway, pathway_group, peer | | [open_relay](/momentum/4/config/ref-open-relay) – Whether the MTA is an open relay or not | receiving | false | 4.0 and later | esmtp_listener, listen, pathway, pathway_group, peer | | [opendkim_sign](/momentum/4/config/ref-opendkim-sign) – Whether or not to enable OpenDKIM signing | sending | true (*non-dynamic*) | 4.0 and later | binding, binding_group, domain, global | -| [outbound_throttle_connections](/momentum/4/config/ref-outbound-throttle-connections) – Limit the rate at which connections are established | sending |   | 4.0 and later | binding, binding_group, domain, global | -| [outbound_throttle_messages](/momentum/4/config/ref-outbound-throttle-messages) – Limit the rate at which messages are delivered | sending |   | 4.0 and later | binding, binding_group, domain, global | +| [outbound_throttle_connections](/momentum/4/config/ref-outbound-throttle-connections) – Limit the rate at which connections are established | sending |   | 4.0 and later | binding, binding_group, domain, global, host | +| [outbound_throttle_messages](/momentum/4/config/ref-outbound-throttle-messages) – Limit the rate at which messages are delivered | sending |   | 4.0 and later | binding, binding_group, domain, global, host | | [pathway](/momentum/4/config/ref-pathway) *(scope)* – Grouping of inbound configuration options | receiving |   | 4.0 and later | global, pathway_group | | [pathway](/momentum/4/config/ref-pathway) – Means for associating a Listener with a pathway scope | receiving |   | 4.0 and later | ecstream_listener, esmtp_listener, listen, peer | | [pathway_group](/momentum/4/config/ref-pathway-group) *(scope)* – Container for pathway scopes | receiving |   | 4.0 and later | global | diff --git a/content/momentum/4/config/ref-host.md b/content/momentum/4/config/ref-host.md index a961efb0..03ea5873 100644 --- a/content/momentum/4/config/ref-host.md +++ b/content/momentum/4/config/ref-host.md @@ -33,6 +33,10 @@ The following options can be specified in a `host` stanza: * [max_outbound_connections](/momentum/4/config/ref-max-outbound-connections) +* [outbound_throttle_connections](/momentum/4/config/ref-outbound-throttle-connections) + +* [outbound_throttle_messages](/momentum/4/config/ref-outbound-throttle-messages) + **Configuration Change. ** As of version 4.2, Regex is supported in the `Host` stanza. In addition to specifying a host by host name, you may use Perl-compatible regular expression (PCRE) syntax to define a "Regex Host". Using regex hosts you can define common rules for hosts that have similar configurations, without needing to specify the rules for every possible matching host. @@ -101,4 +105,4 @@ To be effective, you would do this for each of the MX hosts that service Google ## See Also -[binding](/momentum/4/config/ref-binding), [domain](/momentum/4/config/ref-domain) \ No newline at end of file +[binding](/momentum/4/config/ref-binding), [domain](/momentum/4/config/ref-domain) diff --git a/content/momentum/4/config/ref-outbound-throttle-connections.md b/content/momentum/4/config/ref-outbound-throttle-connections.md index 569178db..3a2ae7c7 100644 --- a/content/momentum/4/config/ref-outbound-throttle-connections.md +++ b/content/momentum/4/config/ref-outbound-throttle-connections.md @@ -28,7 +28,55 @@ Where throttles are concerned, Momentum's fallback behavior differs. For more in This option can also be used to throttle *ecstream* connections. + +### `Outbound_Throttle_Connections` in the `host` Scope + +`Outbound_Throttle_Connections` may also be declared inside a `host` stanza to limit the rate at which connections are initiated to a particular MX host — a dimension that the binding/binding_group/domain/global form cannot express on its own, since multiple domains can share a single MX host and a single domain can be served by several MX hosts. The throttle is consulted at connection-establishment time, once the MX host has been selected, and is enforced alongside any binding/binding_group/domain/global throttle already in effect (see [Layering on top of the binding/domain/global throttle](#conf.ref.outbound_throttle_connections.host_scope) below). + +#### Layering on top of the binding/domain/global throttle + +The host-scoped throttle is **additive**: it is consulted **in addition to** any `Outbound_Throttle_Connections` value already in effect for the binding/binding_group/domain/global fallback chain. A new outbound TCP connection to a host proceeds only when none of the applicable throttles is saturated. + +#### `host` scope fallback chain + +The `host`-scoped throttle walks its own dedicated fallback chain — separate from the binding/binding_group/domain/global chain — when looking up the most specific value for a given `(binding_group, binding, host)` triple: + +``` +binding_group::binding::host > binding_group::host > binding::host > host +``` + +The most specific declaration wins. If no `host` stanza along the chain sets `Outbound_Throttle_Connections`, the host-scoped throttle is not enforced; only the binding/domain/global throttle applies. Note that, as with [max_outbound_connections](/momentum/4/config/ref-max-outbound-connections) in the `host` scope, there is no fallback from a `host`-scope lookup to the binding/domain/global value of `Outbound_Throttle_Connections` — the two chains are independent. + +#### Usage Example + +``` +host "smtp.example.com" { + Outbound_Throttle_Connections = "5/10" +} + +Binding "vip" { + host "smtp.example.com" { + Outbound_Throttle_Connections = "30" + } +} +``` + +In the example above, connections opened to the resolved MX host `smtp.example.com` are limited to 5 every 10 seconds by default, but the `vip` binding may open up to 30 new connections per second to the same host. + +#### Throttles-by-reference semantics still apply + +As with the binding/domain/global form (see [the section called “Throttles and Fallback”](/momentum/4/config/ref-outbound-throttle-messages#conf.ref.outbound_throttle_messages.fallback)), the host-scoped throttle object is shared by reference across more specific scopes that fall back to it. Two bindings whose `binding::host` lookup falls back to the same plain `host "smtp.example.com"` declaration share the **same** token bucket and are rate-limited cumulatively. Declare an explicit `Outbound_Throttle_Connections` inside each binding's `host` stanza if you want each binding to have its own independent connection rate to the host. + +#### Note on cluster enforcement + +The `host`-scoped form of `Outbound_Throttle_Connections` is enforced **locally** on each Momentum node. The cluster module does **not** replicate this throttle across nodes; for cluster-wide rate limiting, use [cluster_outbound_throttle_connections](/momentum/4/config/ref-cluster-outbound-throttle-connections), which operates in the binding_group, domain, and global scopes. + ## Scope -outbound_throttle_connections is valid in the binding, binding_group, domain, and global scopes. \ No newline at end of file +outbound_throttle_connections is valid in the binding, binding_group, domain, global, and host scopes. In the `host` scope it walks a dedicated fallback chain (binding_group::binding::host, binding_group::host, binding::host, host). + + +## See Also + +[outbound_throttle_messages](/momentum/4/config/ref-outbound-throttle-messages), [host](/momentum/4/config/ref-host), [max_outbound_connections](/momentum/4/config/ref-max-outbound-connections), [cluster_outbound_throttle_connections](/momentum/4/config/ref-cluster-outbound-throttle-connections) diff --git a/content/momentum/4/config/ref-outbound-throttle-messages.md b/content/momentum/4/config/ref-outbound-throttle-messages.md index 1619c2f4..f92737d1 100644 --- a/content/momentum/4/config/ref-outbound-throttle-messages.md +++ b/content/momentum/4/config/ref-outbound-throttle-messages.md @@ -106,12 +106,55 @@ Domain "/(?:^|[.])example[.](/momentum/4/com-co-uk)$/" { outbound_throttle_messages set in the regex domain shown in the preceding example will impact all domains together, in the same way that a throttle set in a binding_group impacts all bindings. + +### `Outbound_Throttle_Messages` in the `host` Scope + +`Outbound_Throttle_Messages` may also be declared inside a `host` stanza to limit the message-delivery rate to a particular MX host — a dimension that the binding/binding_group/domain/global form cannot express on its own, since multiple domains can share a single MX host and a single domain can be served by several MX hosts. The `host` scope identifies the resolved MX hostname for a delivery, so the throttle is consulted once the connection has been bound to a specific MX host, and is enforced alongside any binding/binding_group/domain/global throttle already in effect (see [Layering on top of the binding/domain/global throttle](#conf.ref.outbound_throttle_messages.host_scope) below). + +#### Layering on top of the binding/domain/global throttle + +The host-scoped throttle is **additive**: it is consulted **in addition to** any `Outbound_Throttle_Messages` value already in effect for the binding/binding_group/domain/global fallback chain. A delivery proceeds only when none of the applicable throttles is saturated; if either the per-binding/domain throttle **or** the per-host throttle is exceeded, the delivery is deferred. + +#### `host` scope fallback chain + +The `host`-scoped throttle walks its own dedicated fallback chain — separate from the binding/binding_group/domain/global chain — when looking up the most specific value for a given `(binding_group, binding, host)` triple: + +``` +binding_group::binding::host > binding_group::host > binding::host > host +``` + +The most specific declaration wins. If no `host` stanza along the chain sets `Outbound_Throttle_Messages`, the host-scoped throttle is not enforced; only the binding/domain/global throttle applies. Note that, as with [max_outbound_connections](/momentum/4/config/ref-max-outbound-connections) in the `host` scope, there is no fallback from a `host`-scope lookup to the binding/domain/global value of `Outbound_Throttle_Messages` — the two chains are independent. + +#### Usage Example + +``` +host "smtp.example.com" { + Outbound_Throttle_Messages = "10/5" +} + +Binding "vip" { + host "smtp.example.com" { + Outbound_Throttle_Messages = "100" + } +} +``` + +With the configuration above, deliveries to the resolved MX host `smtp.example.com` are capped at 10 messages per 5 seconds by default, but messages going out from the `vip` binding to the same host may run at 100 per second. + +#### Throttles-by-reference semantics still apply + +As with the binding/domain/global form (see [the section called “Throttles and Fallback”](#conf.ref.outbound_throttle_messages.fallback)), the host-scoped throttle object is shared by reference across more specific scopes that fall back to it. For example, deliveries from `binding_a::host smtp.example.com` and `binding_b::host smtp.example.com` that both fall back to the plain `host "smtp.example.com"` declaration share the **same** token bucket and are rate-limited cumulatively. Declare an explicit `Outbound_Throttle_Messages` inside each binding's `host` stanza if you want each binding to have its own independent rate to the host. + +#### Note on cluster enforcement + +The `host`-scoped form of `Outbound_Throttle_Messages` is enforced **locally** on each Momentum node. The cluster module does **not** replicate this throttle across nodes; for cluster-wide rate limiting, use [cluster_outbound_throttle_messages](/momentum/4/config/ref-cluster-outbound-throttle-messages), which operates in the binding_group, domain, and global scopes. + ## Scope -outbound_throttle_messages is valid in the binding, binding_group, domain, and global scopes. +outbound_throttle_messages is valid in the binding, binding_group, domain, global, and host scopes. In the `host` scope it walks a dedicated fallback chain (binding_group::binding::host, binding_group::host, binding::host, host). ## See Also -[“Configuration Scopes and Fallback”](/momentum/4/4-ecelerity-conf-fallback) \ No newline at end of file +[“Configuration Scopes and Fallback”](/momentum/4/4-ecelerity-conf-fallback), [outbound_throttle_connections](/momentum/4/config/ref-outbound-throttle-connections), [host](/momentum/4/config/ref-host), [max_outbound_connections](/momentum/4/config/ref-max-outbound-connections), [cluster_outbound_throttle_messages](/momentum/4/config/ref-cluster-outbound-throttle-messages) diff --git a/content/momentum/changelog/5/5-3-0.md b/content/momentum/changelog/5/5-3-0.md index d39afc7a..4a2ad340 100644 --- a/content/momentum/changelog/5/5-3-0.md +++ b/content/momentum/changelog/5/5-3-0.md @@ -20,4 +20,5 @@ This section will list all of the major changes that happened with the release o | Feature | I-1225 | Added optional `--meta` / `--header` filtering to the [`reroute queue`](/momentum/4/console-commands/reroute-queue#reroute_queue_selective) console command, to selectively move queued messages by metadata or RFC822 header match. | | Feature | TASK-144964 | The [tls_ec_curve_names](/momentum/4/config/tls-ec-curve-names) option now accepts a colon-separated list of curve or TLS group short names in preference order, instead of a single curve. | | Feature | TASK-198522 | New DNS configuration options to [rate-limit MX lookups](/momentum/4/config/ref-dns-rate-limit), preventing query bursts from overwhelming the DNS infrastructure. | +| Feature | TASK-258127 | [`outbound_throttle_messages`](/momentum/4/config/ref-outbound-throttle-messages#conf.ref.outbound_throttle_messages.host_scope) and [`outbound_throttle_connections`](/momentum/4/config/ref-outbound-throttle-connections#conf.ref.outbound_throttle_connections.host_scope) may now be declared in a `host` stanza for per-MX-host rate-limiting of outbound message deliveries and connection establishment. | | Fix | TASK-227757 | [`ha_proxy_client`](/momentum/4/modules/ha-proxy-client) now re-resolves a hostname-based `ha_proxy_server` during each health check, so backend IP changes are picked up automatically without restart. |