EOP-164: add support pages for MTA-STS in Momentum

content/momentum/4/4-console-commands.md

@@ -118,6 +118,9 @@ This table lists all console commands alphabetically giving a brief description.
 | [message retry](/momentum/4/console-commands/message-retry) – Perform an immediate delivery attempt on a message | 4.0 |   | message |
 | [module hooks](/momentum/4/console-commands/4-module) – Manage loaded module hooks | 4.0 |   | module |
 | [module list](/momentum/4/console-commands/4-module) – Show loaded modules | 4.0 |   | module |
+| [mta_sts list all](/momentum/4/console-commands/mta-sts) – list active domains which have MTA-STS policy | 4.8 |   | mta-sts |
+| [mta_sts show domain](/momentum/4/console-commands/mta-sts) – show MTA-STS policy details for a domain | 4.8 |   | mta-sts |
+| [mta_sts refresh policy](/momentum/4/console-commands/mta-sts) – refresh MTA-STS policy for a domain | 4.8 |   | mta-sts |
 | [outbound_audit:instance_name clear all](/momentum/4/modules/outbound-audit#modules.outbound_audit.console) – Zero-out all statistics | 4.0 | outbound_audit | module |
 | [outbound_audit:instance_name clear domain](/momentum/4/modules/outbound-audit#modules.outbound_audit.console) – Zero-out a domain's statistics | 4.0 | outbound_audit | module |
 | [outbound_audit:instance_name domain_list](/momentum/4/modules/outbound-audit#modules.outbound_audit.console) – Runtime addition/deletion of a domain in the monitoring list | 4.0 | outbound_audit | module |
@@ -160,4 +163,4 @@ This table lists all console commands alphabetically giving a brief description.
 | [trace smtp remove](/momentum/4/console-commands/trace-smtp) – Remove an SMTP trace | 4.0 |   | misc |
 | [unlink stats](/momentum/4/console-commands/unlink-stats) – Show statistics of removing messages from the disk | 4.0 |   | stats |
 | [version](/momentum/4/console-commands/version) – Show version information of Momentum | 4.0 |   | misc |
-| [write config](/momentum/4/console-commands/write-config) – Display current running configuration | 4.0 |   | config |
+| [write config](/momentum/4/console-commands/write-config) – Display current running configuration | 4.0 |   | config |

content/momentum/4/config-options-summary.md

@@ -149,6 +149,7 @@ The `Version` column indicated the version(s) of Momentum that support the optio
 | [enable_authorization](/momentum/4/control-authz) – Whether or not to enable authorization for console commands | receiving |   | 4.0 and later | control_listener, listen, peer |
 | [enable_duravip](/momentum/4/4-cluster-config-duravip) – Whether to enable Durable MultiVIP© bindings (cluster-specific) | both |   | 4.0 and later | binding, listen |
 | [enable_fbl_header_insertion](/momentum/4/config/ref-enable-fbl-header-insertion) – Enable or disable fbl header insertion | sending |   | 4.0 and later | binding, binding_group, domain, global |
+| [enable_mta_sts](/momentum/4/config/mta-sts/enable-mta-sts) – Enable or disable MTA-STS policy application | sending |   | 4.8 and later | binding, binding_group, domain, global |
 | **enabled** – Whether or not the module is enabled (cluster-specific) | na | true | 4.0 and later | cluster |
 | [error](/momentum/4/config/ref-debug-flags) – Set the debug level | na | ALL | 4.0 and later | debug_flags |
 | [esmtp_listener](/momentum/4/esmtp-listener) *(scope)* – Listener for incoming SMTP connections | receiving |   | 4.0 and later | global |
@@ -237,6 +238,8 @@ The `Version` column indicated the version(s) of Momentum that support the optio
 | [max_resident_active_queue](/momentum/4/config/ref-max-resident-active-queue) – Threshold above which messages are not held in memory | sending | 250 | 4.0 and later | binding, binding_group, domain, global |
 | [max_resident_messages](/momentum/4/config/ref-max-resident-messages) – Threshold above which messages are not held in memory | sending | 32768 | 4.0 and later | binding, binding_group, global |
 | [max_resident_transfails](/momentum/4/config/ref-max-resident-transfails) – If the transient failure queue grows beyond this size, messages are swapped out of memory | sending | 100 | 4.0 and later | global |
+| [mta_sts_dns_cname_max_depth](/momentum/4/config/mta-sts/mta-sts-dns-cname-max-depth) – Maximum number of continous CNAME lookups allowed while doing MTA-STS DNS lookup | sending | 5 | 4.8 and later | global |
+| [mta_sts_policy_store](/momentum/4/config/mta-sts/mta-sts-policy-store) – Directory to store MTA-STS policy files | sending | /var/spool/ecelerity/mtasts (*non-dynamic*) | 4.8 and later | global |
 | [swap_out_meta_after_each_tempfail](/momentum/4/config/ref-swap-out-meta-after-each-tempfail) – If this is set to false, Momentum will only update metadata on disk after each tempfail if the message context is dirty, and the num_retires, next_attempt and message context may not be accurate if Momentum crashes | sending | true | 4.3.1 and later | global |
 | [max_retries](/momentum/4/config/ref-max-retries) – Override the system configured max_retries | sending |   | 4.0 and later | binding, binding_group, domain, global |
 | [max_retry_interval](/momentum/4/config/ref-max-retry-interval) – Maximum retry interval | sending | 43200 | 4.0 and later | binding, binding_group, domain, global |
@@ -365,6 +368,7 @@ The `Version` column indicated the version(s) of Momentum that support the optio
 | [use_iflist_cache](/momentum/4/config/ref-use-iflist-cache) – Whether or not to cache the list of interfaces configured by the system | sending | 0 (*non-dynamic*) | 4.0 and later | global |
 | [use_ipv6](/momentum/4/config/ref-use-ipv-6) – Affects the selection of IPv6 hosts in the SMTP client | sending | false | 4.0 and later | global |
 | [use_mmap](/momentum/4/config/ref-use-mmap) – Use mmap when spooling messages from disk | na | false | 4.0 and later | global |
+| [use_mta_sts](/momentum/4/config/mta-sts/use-mta-sts) – Enable MTA-STS policy fetching on a domain | sending | false | 4.8 and later | global, domain |
 | [use_sendfile](/momentum/4/config/ref-use-sendfile) – Use sendfile() when sending mail | sending | false | 4.0 and later | global |
 | **use_ssl** – Whether or not to use SSL verification | receiving | false | 4.0 and later | ecstream_listener, esmtp_listener, http_listener, listen, pathway, pathway_group, peer |
 | [user](/momentum/4/config/ref-user) – User identity to assume after startup | na | ecuser (*non-dynamic*) | 4.0 and later | security |

content/momentum/4/config/index.md

@@ -76,6 +76,7 @@ description: "This chapter provides the definitions of the configuration options
 | [ehlo_hostname](/momentum/4/config/ref-ehlo-hostname) | set the hostname used for EHLO in outbound mail |
 | [ehlo_timeout](/momentum/4/config/ref-ehlo-timeout) | network timeout for EHLO |
 | [enable_fbl_header_insertion](/momentum/4/config/ref-enable-fbl-header-insertion) | enable or disable fbl header insertion |
+| [enable_mta_sts](/momentum/4/config/mta-sts/enable-mta-sts) | enable application of MTA-STS policy on email delivery to a remote domain |
 | [event_loop](/momentum/4/config/ref-event-loop) | associate a pool of event loops within a listener scope to use multiple threads |
 | [eventloop](/momentum/4/config/ref-eventloop) | define a pool of event loops to enable multiple event loop configuration |
 | [events_per_iter](/momentum/4/config/ref-events-per-iter) | employ when using a concurrency greater than 1. |
@@ -136,6 +137,8 @@ description: "This chapter provides the definitions of the configuration options
 | [migrate_connections_between_sibling_domains](/momentum/4/config/ref-migrate-connections-between-sibling-domains) | optimize connections for sibling domains |
 | [mime_parse_large_messages_during_reception](/momentum/4/config/ref-mime-parse-large-messages-during-reception) | configure whether large messages are parsed upon reception or just in time. |
 | [min_dns_ttl](/momentum/4/config/ref-min-dns-ttl) | override DNS TTLs smaller than this value |
+| [mta_sts_dns_cname_max_depth](/momentum/4/config/mta-sts/mta-sts-dns-cname-max-depth) | the maximum number of continuous CNAME lookups while doing MTA-STS DNS TXT lookup |
+| [mta_sts_policy_store](/momentum/4/config/mta-sts/mta-sts-policy-store) | the directory to store MTA-STS policy files |
 | [mx_failures_fallback_to_a](/momentum/4/config/ref-mx-failures-fallback-to-a) | configure the maximum number of times an MX lookup will be attempted |
 | [mx_failures_to_delay](/momentum/4/config/ref-mx-failures-to-delay) | number of consecutive failures before a domain is auto-delayed |
 | [never_attempt_expired_messages](/momentum/4/config/ref-never-attempt-expired-messages) | Never attempt delivery of expired messages |
@@ -227,6 +230,7 @@ description: "This chapter provides the definitions of the configuration options
 | [use_iflist_cache](/momentum/4/config/ref-use-iflist-cache) | Whether or not to cache the list of network interfaces configured by the system |
 | [use_ipv6](/momentum/4/config/ref-use-ipv-6) | Affects the selection of IPv6 hosts in the SMTP client |
 | [use_mmap](/momentum/4/config/ref-use-mmap) | use mmap when spooling messages from disk |
+| [use_mta_sts](/momentum/4/config/mta-sts/use-mta-sts) | fetch MTA-STS policy for a domain |
 | [use_sendfile](/momentum/4/config/ref-use-sendfile) | use sendfile() when sending mail |
 | [user](/momentum/4/config/ref-user) | security: user identity to assume after startup |
 | [xclient](/momentum/4/config/ref-xclient) | use the xclient extension to SMTP for outbound mail |

content/momentum/4/config/mta-sts/enable-mta-sts.md

@@ -0,0 +1,42 @@
+---
+lastUpdated: "06/01/2024"
+title: "enable_mta_sts"
+description: "config option to enable MTA-STS policy application for outbound mails"
+---
+
+<a name="config.enable-mta-sts"></a>
+## Name
+
+enable_mta_sts — specify whether Momentum should apply MTA-STS policies for outbound emails
+
+## Synopsis
+
+`enable_mta_sts = "true|false"`
+
+## Description
+
+This option is only effective when [use_mta_sts](/momentum/4/config/mta-sts/use-mta-sts) is `true`
+for a recipient domain.
+This option specifies whether Momentum should try to apply the retrieved MTA-STS policy when sending
+emails to a remote site. See [MTA-STS support in Momentum](/momentum/4/mta-sts) for more details.
+
+
+When this option is `true`, the MTA-STS policy mode will be considered along with the configuration
+ values for [TLS](/momentum/4/config/ref-tls) and [TLS_Verify](/momentum/4/config/tls-verify).
+ The more strict policy will apply. E.g. When the MTA-STS policy mode is `enforce`, regardless of the
+ values for `TLS` and `TLS_Verify`, Momentum will enforce TLS (equivalent to `TLS = required`) and
+ will fail the delivery upon a failed certificate validation (equivalent to `TLS_Verify = host`).
+
+When the MTA-STS policy mode is `testing`, Momentum will apply `TLS = ifavailable` (unless
+ `TLS = required` is specified) and `TLS_Verify = optional` (unless `TLS_Verify = host` is
+ specified).
+
+When the MTA-STS policy mode is `none`, the policy will be ignored and the configuration values for
+ `TLS` and `TLS_Verify` will be respected.
+
+The default value is `true` when `use_mta_sts` is `true` for a domain.
+
+
+## Scope
+
+`enable_mta_sts` is valid in the binding, binding_group, domain and global scopes.

content/momentum/4/config/mta-sts/index.md

@@ -0,0 +1,14 @@
+---
+lastUpdated: "06/01/2024"
+title: "Category File"
+type: "custom"
+name: "MTA-STS Configuration Options Reference"
+description: "MTA-STS configuration Options index"
+---
+
+- [use_mta_sts](/momentum/4/config/mta-sts/use-mta-sts)
+- [enable_mta_sts](/momentum/4/config/mta-sts/enable-mta-sts)
+- [mta_sts_dns_cname_max_depth](/momentum/4/config/mta-sts/mta-sts-dns-cname-max-depth)
+- [mta_sts_policy_store](/momentum/4/config/mta-sts/mta-sts-policy-store)
+
+

content/momentum/4/config/mta-sts/mta-sts-dns-cname-max-depth.md

@@ -0,0 +1,31 @@
+---
+lastUpdated: "06/01/2024"
+title: "mta_sts_dns_cname_max_depth"
+description: "config option on how many continous cname lookups are allowed when doing MTA-STS TXT
+record lookup for a domain"
+---
+
+<a name="config.mta-sts-dns-cname-max-depth"></a>
+## Name
+
+mta_sts_dns_cname_max_depth — specifies how many continous cname lookups are allowed when doing DNS
+ lookups for MTA-STS TXT record for a domain. Exceeding the configured value will be treated as a DNS
+ lookup failure, which will be further treated as no MTA-STS policy available.
+
+## Synopsis
+
+`mta_sts_dns_cname_max_depth = 5`
+
+## Description
+
+Momentum supports MTA-STS policy delegation, which points the `_mta-sts` TXT record for the policy
+ domain via `CNAME` (to the `_mta-sts` record maintained by the provider). Momentum's DNS lookup
+ will follow the `CNAME`s. To avoid a DNS lookup loop, Momentum uses this config option to limit how
+ many continuous `CNAME` lookups can happen before claiming a lookup failure.
+
+The default value is `5`.
+
+
+## Scope
+
+`mta_sts_dns_cname_max_depth` is valid in the domain and global scopes.

content/momentum/4/config/mta-sts/mta-sts-policy-store.md

@@ -0,0 +1,27 @@
+---
+lastUpdated: "06/01/2024"
+title: "mta_sts_policy_store"
+description: "the location to store the MTA-STS policy"
+---
+
+<a name="config.mta-sts-policy-store"></a>
+## Name
+
+mta_sts_policy_store — specifies the location to keep the MTA-STS policy details for the domains.
+
+## Synopsis
+
+`mta_sts_policy_store = "/var/spool/ecelerity/mtasts"`
+
+## Description
+
+Momentum stores MTA-STS policy for a domain in a file on disk, and accesses the HTTPS endpoint to refresh the
+ policy once every 24 hours. This config option specifies the directory where the policies are stored
+ on the disk.
+
+The default value is `/var/spool/ecelerity/mtasts`.
+
+
+## Scope
+
+`mta_sts_policy_store` is valid in the global scope.

content/momentum/4/config/mta-sts/use-mta-sts.md

@@ -0,0 +1,27 @@
+---
+lastUpdated: "06/01/2024"
+title: "use_mta_sts"
+description: "config option to enable MTA-STS policy fetching for a domain"
+---
+
+<a name="config.use-mta-sts"></a>
+## Name
+
+use_mta_sts — specify whether Momentum should do MTA-STS policy fetching for a domain
+
+## Synopsis
+
+`use_mta_sts = "true|false"`
+
+## Description
+
+This option specifies whether Momentum shall attempt to discover the recipient domain's MTA-STS
+ policy (via a DNS TXT lookup to retrieve the MTA-STS policy ID and a HTTPS lookup to retrieve the
+ MTA-STS policy)
+
+The default value is `false`.
+
+
+## Scope
+
+`use_mta_sts` is valid in the domain and global scopes.

content/momentum/4/config/ref-debug-flags.md

@@ -28,11 +28,21 @@ Debug_Flags {
         CRITICAL = (TIME FD SMTP LOG1 DNS DNSDS NET SIG MEM DB LIC SSL MOD START ALL)
 }
 ```
-
 ### Note
-
 Use ‘`ALL`’ instead of listing each service debug flag.
 
+
+The example below enables more (at `WARNING` level) MTA-STS and SSL related logging, along with default
+`ERROR` and `CRITICAL` loggings:
+```
+Debug_Flags {
+    WARNING = (MTA_STS SSL)
+    ERROR = (ALL)
+    CRITICAL = (ALL)
+}
+```
+
+
 <a name="conf.ref.debug.levels"></a> 
 
 
@@ -57,6 +67,7 @@ Use ‘`ALL`’ instead of listing each service debug flag.
 | LOG1 | LOG1 |
 | DNS | DNS |
 | DNS data structures | DNSDS |
+| MTA-STS | MTA_STS |
 | Network | NET |
 | Signals | SIG |
 | Memory Management | MEM |
@@ -69,4 +80,4 @@ Use ‘`ALL`’ instead of listing each service debug flag.
 <a name="idp24068272"></a> 
 ## Scope
 
-debug_flags is valid in the global scope.
+debug_flags is valid in the global scope.

content/momentum/4/console-commands/index.md

@@ -1,5 +1,5 @@
 ---
-lastUpdated: "02/09/2021"
+lastUpdated: "06/01/2024"
 title: "Category File"
 type: "custom"
 name: "Non-Module-Specific Console Commands"
@@ -44,6 +44,7 @@ description: "This section documents all the non module specific console command
 | [message fail quiet](/momentum/4/console-commands/message-fail-quiet)                       | fail a message and do not create a non-delivery receipt (NDR)                     |
 | [message retry](/momentum/4/console-commands/message-retry)                                 | perform an immediate delivery attempt on a message                                |
 | [module](/momentum/4/console-commands/4-module)                                               | manage loaded modules online                                                      |
+| [mta_sts](/momentum/4/console-commands/mta_sts)                                             | commands to display and manage MTA-STS policy for a domain                        |
 | [\pager](/momentum/4/console-commands/pager)                                                | Page output of long console commands in the console.                              |
 | [paniclog](/momentum/4/console-commands/paniclog)                                           | show last several entries written to paniclog                                     |
 | [pid](/momentum/4/console-commands/pid)                                                     | show process id of Momentum                                                       |

content/momentum/4/console-commands/mta-sts.md

@@ -0,0 +1,53 @@
+---
+lastUpdated: "06/01/2024"
+title: "mta_sts"
+description: "mta_sts ec_console commands" 
+---
+
+<a name="console_commands.mta-sts"></a>
+## Name
+
+mta_sts - commands for MTA-STS related data
+
+## Synopsis
+
+`mta_sts list all`
+
+`mta_sts show domain {domain name}`
+
+`mta_sts refresh policy {domain name}`
+
+## Description
+
+**mta_sts list all**     - lists all the active domains which have MTA-STS policies
+
+```
+15:42:38 /tmp/2025> mta_sts list all
+gmail.com
+Total domains: 1
+```
+
+**mta-sts show domain { domain name }**     - shows MTA-STS TXT record and policy details of a given domain.
+ The same content will be shown in [domain](/momentum/4/console-commands/domain) command output also if
+ available.
+
+
+```
+18:13:43 /tmp/2025> mta_sts show domain gmail.com
+Domain 'gmail.com' has MTA-STS TXT and a TTL of 185 seconds
+        id: 20190429T010101
+        max_age: 86400 seconds; refresh in 86375 seconds
+        mode: enforce
+        mxlist:
+               gmail-smtp-in.l.google.com
+               *.gmail-smtp-in.l.google.com
+```
+
+**mta-sts refresh policy {domain name}**     - forces MTA-STS policy refresh by fetching the policy
+ from the HTTPS endpoint for a given domain
+
+
+```
+18:14:41 /tmp/2025> mta_sts refresh policy gmail.com
+MTA-STS policy for gmail.com refreshed.
+```