Unreleased Changes in The Mainline
Breaking Changes
-
The
LocalDiskspool kind is deprecated and slated for removal in a future release. It has not yet been removed, but defining a spool with it now logs an error to advise you of the future removal. Use theRocksDBkind instead; it is faster, more durable, uses less space (and thus IOPS), and is the recommended production configuration. In addition, we've made the kind field of kumo.define_spool a required field so that new users don't accidentally deploy withLocalDiskbetween now and the removal of theLocalDisksupport. -
kumo.dns.configure_unbound_resolver is deprecated and slated for removal in a future release. It is not yet removed, but calling it now logs an error to advise you of the future removal. Use kumo.dns.configure_resolver instead. The only reason to consider using the
configure_unbound_resolverwas if you required DANE support, but the hickory resolver has been able to satisfy that requirement since version2026.09.22-a276d4a8and works more reliably in KumoMTA. -
Site-name generation now preserves complete hostname branches instead of combining labels independently. Distinct MX sets that previously collided now have separate site names and ready queues. For example, two real-world Zoho MX sets:
Set A: mx.zoho.com, mx2.zoho.com, mx3.zoho.eu
Set B: mx.zoho.com, mx2.zoho.eu, mx3.zoho.com
Before (both): (mx|mx2|mx3).zoho.(com|eu)
After A: ((mx|mx2).zoho.com|mx3.zoho.eu)
After B: ((mx|mx3).zoho.com|mx2.zoho.eu)
This affects the site names that you may observe in metrics and kcli command output. It is recommended that you review whether you have hardcoded any assumptions about the site name in your monitoring/orchestration integration prior to upgrading. We do not anticipate this affecting anyone in practice. See Site Names for details.
-
The HTTP injection API now bounds the number of concurrently processed requests (default
32768), configurable via kumo.set_httpinject_concurrency_limit. Requests above the limit are rejected with a503response rather than queued. The new httpinject_requests_in_flight gauge and httpinject_requests_rejected_total counter expose the current load and rejections. #631 -
If you deliver with DANE, you MUST also enable the new global kumo.dns.set_dane_enabled option (default off) during
init. Without it, a domain whose MX selection is not DNSSEC-secure, but has the same site_name as another DNSSEC-secure domain introduces the possibility of a DANE downgrade. Enabling the option separates these queues and makes this safe. If you have enable_dane set but have not set the global option, we will generate TransientFailure records instead of delivering mail on that egress path to protect you from this misconfiguration.
Other Changes and Enhancements
-
kumo.make_egress_pool accepts a new selection_strategy parameter. Setting it to
StickyWeightedRoundRobinrecords the source chosen for a message's first attempt and reuses that source for later attempts, as long as the source remains part of the pool. #670 -
Implicit TLS (SMTPS) is now supported on both the inbound and outbound SMTP paths. kumo.start_esmtp_listener accepts a tls_mode parameter, and kumo.make_egress_path accepts a tls_mode parameter, each selecting
StartTls(the default) orImplicitTls. #199 #200 -
New kumo.string.psl_suffix_is_known and kumo.string.psl_domain_is_known report whether the resolved public suffix is explicitly listed in the Public Suffix List. Thanks to @umutondersu! #592
-
The SOCKS5 proxy listener now accepts a max_connections parameter (default
32768) that bounds the number of concurrent client connections. Connections above the limit are closed immediately and counted by the new proxy_connections_denied_total metric. -
You may now monitor the status of your log consumers via kumod metrics. For configure_local_logs and kumo.jsonl.new_writer, the status of jsonl log segments is reported based on the checkpoint files maintained in the corresponding log directories. The new log_consumer_segments_behind, log_consumer_bytes_behind, and log_consumer_lag_seconds metrics expose this information.
-
The systemd unit now launches kumod directly as the
kumoduser, withCAP_NET_BIND_SERVICEgranted ambiently, matching the configuration that kumod would establish for itself when spawned as root, but doing so without ever having full root privilege. If you deploy your own unit file, addUser=kumod,Group=kumod,AmbientCapabilities=CAP_NET_BIND_SERVICEandCapabilityBoundingSet=CAP_NET_BIND_SERVICEto adopt the same model. -
The
log_hookshelper new_disposition_hook now accepts alog_parameterstable and forwards it to kumo.configure_log_disposition_hook, letting you set options such asper_recordthrough the helper. #499 #500 #519 #520 -
kumo.memoize caches now run the population function that fills a cache miss on a separate task by default, rather than on the calling task. A caller that is cancelled (an HTTP request handler whose client disconnected) no longer cancels the cache population function. The new
detachedmemoize option can be used to override this if needed. #602 -
New kumo.serde.load_files efficiently reads and parses a list of JSON and TOML files in a single call. The
policy-extras.policy_utilshelper gained a matchingload_json_or_toml_files. -
The
sources.luahelper now loads its source and pool definition files with one call tokumo.serde.load_filesinstead of one call per file. -
The
sources.luahelper'ssetupnow accepts an optional second table of options that tune its data cache:cache_ttl,sources_data_populate_timeout,allow_stale_sources_dataandretry_sources_data_fetch_on_populate_timeout, mirroring the options theshaping.luahelper already exposes. -
New metrics: thread_pool_global_queue_depth, thread_pool_alive_tasks, thread_pool_busy_seconds, thread_pool_blocking_threads, thread_pool_idle_blocking_threads, thread_pool_blocking_queue_depth report the state of each thread pool, and lruttl_populate_duration reports how long each cache population takes.
-
Improved HTTP injection API performance for
contentfields and headers that are effectively static. Previously these would round-trip through the template engine, but now we recognize that we can precompile them once for the whole request and skip the engine overhead. In a microbenchmark of expanding a marker-free value, this is 50-100x faster than routing it through the engine, depending on the template dialect. The benefit scales with the number of static fields and recipients in a batch injection. Thanks to @shivamgoel1009! #620 -
Further improved HTTP injection API performance for the
contentfields and headers that do vary per recipient. Previously the substitution context was re-serialized into the template engine's native form for every field expanded, but now we convert it once per recipient and render every field against that prepared context. In a microbenchmark this expands fields roughly 2-3x faster with the Jinja dialect and 3-5x faster with Handlebars. -
Handlebars templates no longer copy the substitution context a second time when converting it into the engine's native form. This benefits the HTTP injection API with
"template_dialect": "Handlebars", as well as any other Handlebars template expansion. In a microbenchmark this expands Handlebars templates roughly 1.3-1.7x faster with a handful of substitution values, and roughly 2x faster with a large, nested substitution context. Thanks to @akshitsethi0023! #637 -
The HTTP injection API now caches compiled templates across requests. A
contentfield or header whose text was seen in an earlier request is reused from the cache instead of being compiled again. The win is largest for theHandlebarsdialect, whose compiler is far slower than its renderer. Jinja compiles quickly enough that the gain there is modest. The cache is namedcompiled_templatesand its capacity can be tuned with kumo.set_lruttl_cache_capacity. A capacity of zero turns the cache off. Thanks to @akshitsethi0023! #638 -
Traffic shaping automation rules in a
providerblock can now set a configuration override scoped to the whole provider, the triggeringsite_name, or just the triggering domain:SetProviderConfig(new) scopes the override to the whole provider, covering everysite_namematched by the provider.SetConfignow applies the override to the triggering domain'ssite_name(mx_rollup=true). It previously behaved likeSetDomainConfig.SetDomainConfigapplies the override only to the triggering domain (mx_rollup=false).
-
The
queue.luahelper loads a largequeues.tomlmuch faster. With 2000 domain entries the load went from roughly 300ms to under 50ms, and resolving the configuration for a new scheduled queue from roughly 240us to roughly 10us.
Fixes
-
The AAA accounting log didn't finalize its active segment on shutdown, resulting in incomplete writes unless you had set
max_segment_durationto a relatively short value. -
The
max_file_sizeoption of kumo.aaa.configure_acct_log had no effect. It now rotates the accounting log as documented. -
A graceful shutdown could hang indefinitely, logging
Still waiting for 1 pending activities... Queue Manager Meta Maintaineruntil the process was killed. This was most likely to occur when stopping while messages were being sent to a rate-limited destination. #654 -
With DNSSEC validation enabled, the hickory resolver backend could misclassify unsigned zones as DNSSEC-bogus and prevent delivery to the affected domains, due to an upstream hickory bug https://github.com/hickory-dns/hickory-dns/issues/3974. We now build against a pre-release hickory, from its
release/0.26branch, until it is published as0.26.4. If you are a user of KumoMTA release2026.09.22-a276d4a8or2026.09.29-b90d8bc1you can switch to kumo.dns.configure_unbound_resolver in the meantime. You only need to consider this if you require DNSSEC validation to be enabled (such as for DANE support). Most users are unaffected. -
A destination's published MTA-STS or DANE policy can no longer lower the enable_tls configured for an egress path. Previously an MTA-STS
testingpolicy replaced the configured value withOpportunisticInsecure, and DANETLSArecords that were present but unusable replaced it withRequiredInsecure. Both dropped certificate verification that the configured value required. Thetestingcase also made STARTTLS optional. A published policy now only raises the effective posture, and atestingpolicy has no effect on it. Thanks to @terrorobe! #616 -
MTA-STS: When several domains share a ready queue (they resolve to the same MX hosts), a message is no longer delivered over a cleartext connection that another of those domains established, if the domain that message is addressed to publishes an MTA-STS enforce policy. Such a message is now deferred and logs a TransientFailure record with additional information, rather than being sent without TLS.
-
DANE: new kumo.dns.set_dane_enabled (default off). When enabled, a domain that is not DNSSEC-secure but shares mail exchangers that publish DANE
TLSArecords with a DNSSEC-secure domain gets a[dane-insecure]-prefixed site_name, keeping it in a separate ready queue from that domain. -
AUTH PLAINcredentials are now redacted from both inbound rejection logs and outbound delivery failure records, replaced with[REDACTED]in all log and diagnostic output. Thanks to @terrorobe! #636 -
DKIM relaxed body canonicalization now reduces an empty body, or a body consisting only of empty or whitespace-only lines, to zero octets as required by RFC 6376 section 3.4.4. Previously it retained a CRLF, producing a body hash that disagreed with verifiers such as Gmail and causing otherwise-valid signatures to fail. Thanks to @bjarn! #575
-
SMTP and SOCKS5 proxy listeners no longer stop serving when
acceptreturns an error. Previously a transient error such as file-descriptor exhaustion (EMFILE/ENFILE) propagated out of the accept loop and permanently halted the listener while the process kept running. Because the process itself stayed up, a supervisor such as systemd'sRestart=alwayssaw a healthy process and would not restart it, leaving only a manual service restart to recover the listener. The listeners now log and continue, pausing briefly on resource-exhaustion errors to avoid spinning. -
When started as root with
--user, kumod now sets the real, effective and saved user and group ids to the target user, rather than lowering only the effective user id. Previously the real and saved ids remained0, which could potentially allow code running inside kumod to callsetresuid(0,0,0)and regain full root privilege. No such code exists in kumod itself, but it presented a potential avenue for an attacker, if they could contrive for kumod to execute arbitrary code through some other vulerability. No remote code execution vulnerabilities are known to exist. kumod now retains onlyCAP_NET_BIND_SERVICE, which it needs to bind privileged ports. -
kumo.generate_rfc3464_message no longer fails to produce a bounce when the original message has 8-bit headers or body. The returned copy of the original is encoded to keep the report 7-bit clean, and downgrades to just the headers, or is omitted, when its content cannot be represented that way.
-
The mail_auth iprev check now follows at most 10 of the connecting IP's PTR names with forward A/AAAA lookups, as required by RFC 8601 section 3. Previously it followed every name, letting the owner of the reverse zone drive an unbounded number of DNS lookups per connection. #623
-
The SMTP connection plan built for a delivery attempt is now bounded by two new make_egress_path options, max_mx_addresses_per_host (default
10) and max_mx_plan_size (default50). Previously MX resolution retained every address of every MX host with no cap, which meant that the connection plan could be arbitrarily large. #622 -
Fixed a DANE downgrade that could occur when an A or AAAA lookup returned a bogus (DNSSEC validation failure) result. Such a result now defers delivery rather than being treated as ordinary unsigned addresses. #612
-
Fixed the handling of a failed MX lookup on the deprecated unbound resolver backend. A DNS failure response (SERVFAIL, REFUSED, or any other non-NXDOMAIN failure RCODE) is now classified as a temporary error instead, and it no longer qualifies for the implicit
MX->Afallback and is treated as an ordinary failed lookup, as RFC 5321 section 5.1 requires. The default hickory backend already reports these failures as errors and its behavior is unchanged. #629 -
A DNSSEC-bogus MX answer (one that failed DNSSEC validation) is no longer used to route mail. The MX lookup now treats a bogus result as a temporary error and defers, rather than using forged or tampered MX hosts as an ordinary unsigned MX set, as RFC 7672 section 2.1.1 requires. This is the MX counterpart of the A/AAAA bogus fix above (#612). It applies both to the deprecated unbound backend and to a hickory backend that has been explicitly configured to perform DNSSEC validation (
validate = true) against an upstream that does not validate (a validating upstream returns a SERVFAIL for bogus data, which hickory handles as an error). #629 -
A dual-stack address lookup where one family (A or AAAA) failed while the other succeeded no longer holds the partial result for the surviving family's full TTL, which could be up to a day. We now use the negative-cache TTL (60 seconds) to ensure that we will re-attempt the failed address family in a more reasonable time frame. NXDOMAIN and NODATA answers are not failures and keep their normal TTL. #630
-
An explicit mx_list with multiple entries would error out of the SMTP dispatcher setup if one of the entries failed to resolve, instead of continuing with a partial list of hosts. This could prevent delivery to that destination for as long as the entry failed to resolve, without a clear log of the reason. We now continue with whatever resolved in the partial success case, and include the failed DNS lookup results in the TransientFailure log record that we produce if they all fail. #628
-
Reduced lua context creation overhead in scheduled queue config refreshes, egress source and pool loading and
kumo.secretsloading by reusing the cached context. Thanks to @edgarsendernet! #632 -
Improved performance of Lua context destruction by processing on a dedicated thread. This reduces contention especially when a config epoch is bumped.
-
The message_data_resident_count metric could drift away from the true number of messages holding their body in memory: constructing a message with an empty body leaked the count upward, while messages received via node-to-node transfer were never counted and drove it downward (potentially negative). The count is now bound to the lifetime of the resident body, which keeps it accurate in both directions. Thanks to @kayozaki! #588
-
KumoMTA no longer continues in cleartext after a failed STARTTLS handshake, on either the outbound or the inbound SMTP path. Thanks to @terrorobe for reporting and analyzing this in #615!
On the outbound path, a failed handshake with
enable_tls set to
Opportunistic or OpportunisticInsecure now fails the connection attempt
rather than continuing the session in cleartext. Delivery behavior is
unchanged; only the logged text for such a failure changes, from:
mx.example.com/192.0.2.1:25: EHLO after OpportunisticInsecure STARTTLS handshake status: failed: <tls error>
to:
TLS handshake with ResolvedAddress { name: "mx.example.com", addr: 192.0.2.1, is_secure: false }:25 failed: <tls error>
On the inbound SMTP listener, a failed STARTTLS handshake now drops the connection instead of continuing to read commands in cleartext.
-
RFC3464 parsing now correctly recognizes the RFC822 address type case insensitively and handles extraneous spaces in the
Original-RecipientandFinal-Recipientportions of the DSN. Thanks to @Harshjha3006! #640 -
smtp_dispatcher: now correctly clears the reported
tls_infowhen establishing a fallback connection. -
xfer: a message moved into an xfer queue could be expired, retried in a tight loop, or panic the process, depending on how many delivery attempts it had already made. Thanks to @edgarsendernet! #644
-
A per-message expiration set via msg:set_scheduling, or set on a message before it was transferred to another node, was not always honored, so a message could be delivered after its expiration. This is now fixed. #671
-
queue.lua: a known queue option with an invalid value, such asmax_age = 'bogus'in a[queue.'domain']block, was silently treated as a tenant namedmax_ageand the setting was discarded. It is now reported as a configuration error when the file is loaded. -
Reading a kumo.domain_map, kumo.cidr.make_map or kumo.regex_set_map value back out of a kumo.memoize cache copied the whole map on every access, an O(N) cost in the number of entries. It is now an O(1) reference count increment. The
queue.luahelper reads its compiledqueues.tomldomain map from such a cache for every received message. In practical terms, that meant that the maximum ingress rate possible would fall as the size ofqueues.tomlincreased.