diff --git a/docs/tutorial/checking_logs.md b/docs/tutorial/checking_logs.md index 96b4a42e..566d74ea 100644 --- a/docs/tutorial/checking_logs.md +++ b/docs/tutorial/checking_logs.md @@ -1,3 +1,7 @@ +--- +description: Check the KumoMTA logs to confirm your test messages succeeded, using the built-in tailer utility to monitor reception and delivery events in real time. +--- + # Check for success in the logs When diagnosing the failure (or monitoring the success) of your test messages, diff --git a/docs/tutorial/installing_kumomta.md b/docs/tutorial/installing_kumomta.md index 4b66f2c5..b6dcf289 100644 --- a/docs/tutorial/installing_kumomta.md +++ b/docs/tutorial/installing_kumomta.md @@ -1,3 +1,7 @@ +--- +description: Install KumoMTA from prebuilt repositories, with a Rocky Linux example using dnf to set up the openrepo repo and install the kumod daemon in minutes. +--- + # Installing KumoMTA Pre-built repos are available for supported Operating Systems, making installation straightforward. diff --git a/docs/tutorial/next_steps.md b/docs/tutorial/next_steps.md index c479afec..0f37f0d5 100644 --- a/docs/tutorial/next_steps.md +++ b/docs/tutorial/next_steps.md @@ -1,3 +1,7 @@ +--- +description: You have finished the KumoMTA tutorial. See where to go next in the User Guide to learn more about installation, configuration, operation, and advanced policy. +--- + # Next Steps With KumoMTA installed, configured, and tested, the tutorial is complete. diff --git a/docs/tutorial/quickstart.md b/docs/tutorial/quickstart.md index e82cdd8b..b638a83a 100644 --- a/docs/tutorial/quickstart.md +++ b/docs/tutorial/quickstart.md @@ -1,3 +1,7 @@ +--- +description: A quickstart tutorial for experienced MailOps admins to install and configure KumoMTA on Rocky Linux 9, covering prerequisites and a fast non-production setup. +--- + # Quickstart Tutorial !!!warning diff --git a/docs/tutorial/server_environment.md b/docs/tutorial/server_environment.md index b8245c9a..8bbb7059 100644 --- a/docs/tutorial/server_environment.md +++ b/docs/tutorial/server_environment.md @@ -1,3 +1,7 @@ +--- +description: Size your KumoMTA server environment, calculating network, storage, CPU, and RAM needs from your message volume, size, and spool and log capacity requirements. +--- + # Environmental Considerations When deciding on server hardware, senders must balance vertical and horizontal scaling based on their preferences. KumoMTA is built to support both vertical and horizontal scaling, with both single-node performance of several million messages per hour, as well as support for clustered installations. diff --git a/docs/tutorial/starting_kumomta.md b/docs/tutorial/starting_kumomta.md index 13b52dc6..b8ea2310 100644 --- a/docs/tutorial/starting_kumomta.md +++ b/docs/tutorial/starting_kumomta.md @@ -1,3 +1,7 @@ +--- +description: Start KumoMTA with systemctl, restart it to apply config changes, enable it to launch at boot, or run the kumod daemon manually from the command line. +--- + # Starting KumoMTA If you followed all the instructions above without errors, you should now have a working MTA on a properly sized server. diff --git a/docs/tutorial/system_preparation.md b/docs/tutorial/system_preparation.md index bbf917a6..aed467cc 100644 --- a/docs/tutorial/system_preparation.md +++ b/docs/tutorial/system_preparation.md @@ -1,3 +1,7 @@ +--- +description: Prepare your server for KumoMTA, covering OS installation on AWS, package updates, firewall setup, and generating a self-signed TLS certificate. +--- + # System Preparation Now that we know **_what_** to build, lets go ahead and build it. diff --git a/docs/tutorial/testing_kumomta.md b/docs/tutorial/testing_kumomta.md index 2707cc98..bacf3655 100644 --- a/docs/tutorial/testing_kumomta.md +++ b/docs/tutorial/testing_kumomta.md @@ -1,3 +1,7 @@ +--- +description: Test your KumoMTA installation by sending mail from the host with telnet on port 25, the curl HTTP injection API, or Swaks to confirm end-to-end delivery. +--- + # Testing KumoMTA Now that you have KumoMTA installed, you should test it from the command line of the installed host. This is easy if you installed the basic tools as described earlier. diff --git a/docs/userguide/clustering/deployment.md b/docs/userguide/clustering/deployment.md index 56a1da79..3384cc9d 100644 --- a/docs/userguide/clustering/deployment.md +++ b/docs/userguide/clustering/deployment.md @@ -1,3 +1,7 @@ +--- +description: Explore KumoMTA deployment architectures for single-node, multi-node, and many-node clusters, including egress proxies for sharing IPs when sending at scale. +--- + # Deployment Architecture ## Single Node diff --git a/docs/userguide/clustering/eventdata.md b/docs/userguide/clustering/eventdata.md index acb32bc3..3120da7f 100644 --- a/docs/userguide/clustering/eventdata.md +++ b/docs/userguide/clustering/eventdata.md @@ -1,3 +1,7 @@ +--- +description: Aggregate event data across a KumoMTA cluster using webhooks, AMQP, and Kafka instead of collecting and parsing local log files on every node. +--- + # Aggregating Event Data Clustered environments typically don't aggregate log files in order to collect event data, instead either processing the log files locally and then pushing the event data out, or using webhooks. diff --git a/docs/userguide/clustering/index.md b/docs/userguide/clustering/index.md index 1488cd1d..6682c24d 100644 --- a/docs/userguide/clustering/index.md +++ b/docs/userguide/clustering/index.md @@ -1,3 +1,7 @@ +--- +description: Cluster KumoMTA for high-volume sending, comparing vertical and horizontal scaling, shared configuration, egress proxies, and managing shared secrets. +--- + # Clustering KumoMTA is designed to be used in high-volume sending environments where cluster capabilities are essential to effective and manageable scaling. diff --git a/docs/userguide/clustering/kubernetes.md b/docs/userguide/clustering/kubernetes.md index f5d9c9ac..ef3015ef 100644 --- a/docs/userguide/clustering/kubernetes.md +++ b/docs/userguide/clustering/kubernetes.md @@ -1,3 +1,7 @@ +--- +description: Deploy KumoMTA on Kubernetes with a community example, running horizontally scaled MTA clusters in orchestrated container environments. +--- + # Deploying KumoMTA on Kubernetes diff --git a/docs/userguide/clustering/nodeid.md b/docs/userguide/clustering/nodeid.md index 1585e3d3..6fd3ab37 100644 --- a/docs/userguide/clustering/nodeid.md +++ b/docs/userguide/clustering/nodeid.md @@ -1,3 +1,7 @@ +--- +description: Configure the KumoMTA NodeId, a per-instance UUID that identifies nodes in a cluster, aids reporting, and persists or falls back to a generated ID. +--- + # Node ID Each KumoMTA (`kumod`) instance can have its own `NodeId`, which is a UUID diff --git a/docs/userguide/clustering/scaling.md b/docs/userguide/clustering/scaling.md index 367dcd99..f086bac8 100644 --- a/docs/userguide/clustering/scaling.md +++ b/docs/userguide/clustering/scaling.md @@ -1,3 +1,7 @@ +--- +description: Scale KumoMTA clusters up and down in response to sending patterns, monitoring node liveness and draining the spool safely before taking a node offline. +--- + # Scaling Up and Down One advantage of horizontal scaling in virtualized environments is that resources can be conserved by scaling the KumoMTA cluster up and down in response to sending patterns. diff --git a/docs/userguide/clustering/throttles.md b/docs/userguide/clustering/throttles.md index 8a66ba43..7ea81042 100644 --- a/docs/userguide/clustering/throttles.md +++ b/docs/userguide/clustering/throttles.md @@ -1,3 +1,7 @@ +--- +description: Implement shared throttles across a KumoMTA cluster with Redis so nodes sending from shared IPs enforce common traffic shaping counters and rate limits. +--- + # Implementing Shared Throttles When KumoMTA is deployed in a clustered environment using shared IPs the nodes will need to be able to use shared counters in order to adhere to traffic shaping rules. diff --git a/docs/userguide/clustering/trafficshapingautomation.md b/docs/userguide/clustering/trafficshapingautomation.md index af1542f1..244de7c2 100644 --- a/docs/userguide/clustering/trafficshapingautomation.md +++ b/docs/userguide/clustering/trafficshapingautomation.md @@ -1,3 +1,7 @@ +--- +description: Deploy KumoMTA Traffic Shaping Automation in a cluster, configuring the tsa-daemon and trusted hosts so every node processes tempfail and permfail events. +--- + # Deploying Traffic Shaping Automation The `tsa-daemon` process communicates with KumoMTA nodes to process tempfail and permfail events and issue commands to the KumoMTA nodes based on those events. diff --git a/docs/userguide/configuration/bounce.md b/docs/userguide/configuration/bounce.md index a3ead48d..55fdd55c 100644 --- a/docs/userguide/configuration/bounce.md +++ b/docs/userguide/configuration/bounce.md @@ -1,3 +1,7 @@ +--- +description: Configure bounce classification and out-of-band (OOB) bounce processing in KumoMTA, capturing SMTP response and enhanced status codes in your logs. +--- + # Configuring Bounce Classification By default, the logs will contain extensive information on the responses diff --git a/docs/userguide/configuration/concepts.md b/docs/userguide/configuration/concepts.md index 249e6bf0..098828c5 100644 --- a/docs/userguide/configuration/concepts.md +++ b/docs/userguide/configuration/concepts.md @@ -1,3 +1,7 @@ +--- +description: Understand KumoMTA configuration concepts, using Lua as config-as-code to define scopes, events, and message flow from injection through scheduled queues. +--- + # Configuration Concepts diff --git a/docs/userguide/configuration/dkim.md b/docs/userguide/configuration/dkim.md index bfedb1dc..7a62942c 100644 --- a/docs/userguide/configuration/dkim.md +++ b/docs/userguide/configuration/dkim.md @@ -1,3 +1,7 @@ +--- +description: Configure DKIM signing in KumoMTA to authenticate outbound email, generating keys and signing messages with the dkim_sign.lua helper or custom Lua policy. +--- + # Configuring DKIM Signing ## What it is diff --git a/docs/userguide/configuration/domains.md b/docs/userguide/configuration/domains.md index f14d3dd4..22703b22 100644 --- a/docs/userguide/configuration/domains.md +++ b/docs/userguide/configuration/domains.md @@ -1,3 +1,7 @@ +--- +description: Configure inbound and relay domains in KumoMTA with the listener_domains.lua helper to control relaying, bounce processing, and feedback loop reception. +--- + # Configuring Inbound and Relay Domains When listening via SMTP, it is common to simply define a list of `relay_hosts` diff --git a/docs/userguide/configuration/example.md b/docs/userguide/configuration/example.md index 2ea1dcac..142464de 100644 --- a/docs/userguide/configuration/example.md +++ b/docs/userguide/configuration/example.md @@ -1,3 +1,7 @@ +--- +description: Review a complete example KumoMTA init.lua policy covering common use cases, a reference for building your own functional server configuration. +--- + # An Example Configuration KumoMTA ships with only a [minimal `init.lua` diff --git a/docs/userguide/configuration/fbl.md b/docs/userguide/configuration/fbl.md index 40ba9576..c5d22886 100644 --- a/docs/userguide/configuration/fbl.md +++ b/docs/userguide/configuration/fbl.md @@ -1,3 +1,7 @@ +--- +description: Configure feedback loop (FBL) processing in KumoMTA to receive and log ARF complaint reports, inject tracking headers, and suppress recipients who report spam. +--- + # Configuring Feedback Loop Processing Feedback Loops are provided by several mailbox providers, including AOL, diff --git a/docs/userguide/configuration/httplisteners.md b/docs/userguide/configuration/httplisteners.md index d0a173dd..4680e2a3 100644 --- a/docs/userguide/configuration/httplisteners.md +++ b/docs/userguide/configuration/httplisteners.md @@ -1,3 +1,7 @@ +--- +description: Configure HTTP listeners in KumoMTA with kumo.start_http_listener, setting IP, port, trusted hosts, and TLS to expose the injection and management HTTP API. +--- + # Configuring HTTP Listeners An HTTP listener can be defined with a `kumo.start_http_listener` function. In diff --git a/docs/userguide/configuration/logging.md b/docs/userguide/configuration/logging.md index d4bdf4ae..fbd3a662 100644 --- a/docs/userguide/configuration/logging.md +++ b/docs/userguide/configuration/logging.md @@ -1,3 +1,7 @@ +--- +description: Configure logging in KumoMTA, including compressed JSON logs, segment rotation, custom log formats, and per-record-type settings for message event data. +--- + # Configuring Logging By default, KumoMTA writes to a ([zstd](https://en.wikipedia.org/wiki/Zstd) diff --git a/docs/userguide/configuration/policy_helpers.md b/docs/userguide/configuration/policy_helpers.md index 2642d056..5509bbf0 100644 --- a/docs/userguide/configuration/policy_helpers.md +++ b/docs/userguide/configuration/policy_helpers.md @@ -1,3 +1,7 @@ +--- +description: Use KumoMTA Lua policy helpers to configure common use cases from TOML and JSON files, simplifying config-as-code for DKIM, queues, domains, and sources. +--- + # Lua Policy Helpers KumoMTA is designed around the concept of configuration as code, where all configuration of KumoMTA is implemented through Lua policy rather than static text files. diff --git a/docs/userguide/configuration/queuemanagement.md b/docs/userguide/configuration/queuemanagement.md index 4be61171..cf6fbaed 100644 --- a/docs/userguide/configuration/queuemanagement.md +++ b/docs/userguide/configuration/queuemanagement.md @@ -1,3 +1,7 @@ +--- +description: Configure queue management in KumoMTA with the queue.lua helper, assigning tenant and campaign, setting message age and retry timing, and egress pools. +--- + # Configuring Queue Management After a message is injected, it is placed into a Scheduled Queue based on the diff --git a/docs/userguide/configuration/rollup.md b/docs/userguide/configuration/rollup.md index 831a84dd..026277b3 100644 --- a/docs/userguide/configuration/rollup.md +++ b/docs/userguide/configuration/rollup.md @@ -1,3 +1,7 @@ +--- +description: Configure queue rollup in KumoMTA to group Ready Queues by MX site name, with alternative suffix- and IP-based schemes for domains like Outlook and Hotmail. +--- + # Configuring Queue Rollup By default, KumoMTA will perform automatic "rollup" of the Ready Queue based on diff --git a/docs/userguide/configuration/sendingips.md b/docs/userguide/configuration/sendingips.md index 26ac5dc8..0f7271c2 100644 --- a/docs/userguide/configuration/sendingips.md +++ b/docs/userguide/configuration/sendingips.md @@ -1,3 +1,7 @@ +--- +description: Configure sending IPs in KumoMTA using egress source and pool definitions, distributing sends with weighted round robin to isolate reputation and warm IPs. +--- + # Configuring Sending IPs By default, all traffic injected to the KumoMTA server will be delivered using diff --git a/docs/userguide/configuration/smtplisteners.md b/docs/userguide/configuration/smtplisteners.md index 70305d96..fd1bc70f 100644 --- a/docs/userguide/configuration/smtplisteners.md +++ b/docs/userguide/configuration/smtplisteners.md @@ -1,3 +1,7 @@ +--- +description: Configure SMTP listeners in KumoMTA with kumo.start_esmtp_listener, defining IP, port, banner, relay hosts, and SMTP AUTH to secure inbound injection. +--- + # Configuring SMTP Listeners An SMTP listener can be defined using the `kumo.start_esmtp_listener` function. diff --git a/docs/userguide/configuration/spool.md b/docs/userguide/configuration/spool.md index d569bed6..c7843e9d 100644 --- a/docs/userguide/configuration/spool.md +++ b/docs/userguide/configuration/spool.md @@ -1,3 +1,7 @@ +--- +description: Configure message spooling in KumoMTA, choosing between LocalDisk and the recommended RocksDB spool store for separate message data and metadata storage. +--- + # Configuring Spooling KumoMTA uses separate storage areas for metadata and message contents, named diff --git a/docs/userguide/configuration/trafficshaping.md b/docs/userguide/configuration/trafficshaping.md index 64796dc1..b0a282a1 100644 --- a/docs/userguide/configuration/trafficshaping.md +++ b/docs/userguide/configuration/trafficshaping.md @@ -1,3 +1,7 @@ +--- +description: Traffic shaping is now its own chapter in the KumoMTA User Guide, with links to scoping, shaping files, rollups, resolution order, and automation. +--- + # Configuring Traffic Shaping !!! note diff --git a/docs/userguide/general/about.md b/docs/userguide/general/about.md index 7c1f1b71..9cc863fe 100644 --- a/docs/userguide/general/about.md +++ b/docs/userguide/general/about.md @@ -1,3 +1,7 @@ +--- +description: About the KumoMTA User Guide, who it is for, the assumed SMTP and email infrastructure knowledge, and the typographical conventions used throughout. +--- + # About This Manual This is the User Guide for the KumoMTA SMTP server. For license information, see the Legal Notices. diff --git a/docs/userguide/general/architecture.md b/docs/userguide/general/architecture.md index 5ed35c22..7cb3d2c5 100644 --- a/docs/userguide/general/architecture.md +++ b/docs/userguide/general/architecture.md @@ -1,3 +1,7 @@ +--- +description: Explore the KumoMTA architecture, built in Rust on Tokio for modern multi-core systems, with a high-performance RocksDB spool and advanced message queueing. +--- + # KumoMTA Architecture KumoMTA was built with large-scale sending in mind. Here are a few key ideas diff --git a/docs/userguide/general/credits.md b/docs/userguide/general/credits.md index 466cf832..9fd335a9 100644 --- a/docs/userguide/general/credits.md +++ b/docs/userguide/general/credits.md @@ -1,3 +1,7 @@ +--- +description: Credits for KumoMTA, recognizing the developers, documenters, community contributors, supporters, and open source tools behind the MTA and its manual. +--- + # Credits While Kumo Corp owns all copyrights in the KumoMTA software and the KumoMTA manual, we wish to thank the following developers, contributors, and supporters who have helped make KumoMTA what it is today. diff --git a/docs/userguide/general/get_help.md b/docs/userguide/general/get_help.md index 783e65d0..3a8d37cc 100644 --- a/docs/userguide/general/get_help.md +++ b/docs/userguide/general/get_help.md @@ -1,3 +1,7 @@ +--- +description: Get help with KumoMTA through the community forum, Discord, and paid support, including the details to provide for the fastest issue resolution. +--- + # How to Get Help With KumoMTA Community support for KumoMTA is available both in the forum and in the diff --git a/docs/userguide/general/history.md b/docs/userguide/general/history.md index 32fa5480..bf53a47f 100644 --- a/docs/userguide/general/history.md +++ b/docs/userguide/general/history.md @@ -1,3 +1,7 @@ +--- +description: The history of KumoMTA, an open source high-performance MTA written in Rust by email industry veterans, and the story behind its name and open source model. +--- + # The History of KumoMTA KumoMTA is an open source Message Transfer Agent (MTA) designed to provide high performance outbound email functionality. diff --git a/docs/userguide/general/lua.md b/docs/userguide/general/lua.md index 2ae960ea..fbcba656 100644 --- a/docs/userguide/general/lua.md +++ b/docs/userguide/general/lua.md @@ -1,3 +1,7 @@ +--- +description: Learn Lua fundamentals for KumoMTA configuration, a quick primer on syntax, comments, and variables to help you read and write KumoMTA policy scripts. +--- + # Lua Fundamentals Lua is Portuguese for moon. It is also the name of the scripting language we use in KumoMTA. Because it is a name, Lua is always capitalized. diff --git a/docs/userguide/general/preface.md b/docs/userguide/general/preface.md index f6d2c405..3e1cba26 100644 --- a/docs/userguide/general/preface.md +++ b/docs/userguide/general/preface.md @@ -1,3 +1,7 @@ +--- +description: Preface and legal notices for the KumoMTA documentation, including Apache License 2.0 terms and copyright for the KumoMTA Message Transfer Agent. +--- + # Preface and Legal Notices This is the Documentation for the KumoMTA Message Transfer Agent. diff --git a/docs/userguide/general/report.md b/docs/userguide/general/report.md index 52dcb804..5174a068 100644 --- a/docs/userguide/general/report.md +++ b/docs/userguide/general/report.md @@ -1,3 +1,7 @@ +--- +description: Report bugs in KumoMTA by verifying the issue against the manual and changelog, searching existing GitHub issues, and submitting an effective bug report. +--- + # How to Report Bugs diff --git a/docs/userguide/index.md b/docs/userguide/index.md index a2fe91e4..fc6ddb70 100644 --- a/docs/userguide/index.md +++ b/docs/userguide/index.md @@ -1,3 +1,7 @@ +--- +description: The KumoMTA User Guide covers installing, configuring, and administering the KumoMTA MTA, from core concepts through deployment for high-volume email sending. +--- + # User Guide This is the KumoMTA User Guide. diff --git a/docs/userguide/installation/docker.md b/docs/userguide/installation/docker.md index 12ed2d62..c24b5306 100644 --- a/docs/userguide/installation/docker.md +++ b/docs/userguide/installation/docker.md @@ -1,3 +1,7 @@ +--- +description: Install KumoMTA in a Docker container using the official ghcr.io images, creating an init.lua policy script to start the MTA in stable or dev releases. +--- + # Installing KumoMTA in a Docker container Our CI builds the latest version of our image and publishes it diff --git a/docs/userguide/installation/environment.md b/docs/userguide/installation/environment.md index 2419169b..20fb0405 100644 --- a/docs/userguide/installation/environment.md +++ b/docs/userguide/installation/environment.md @@ -1,3 +1,7 @@ +--- +description: Choose a server environment for KumoMTA across AWS, Azure, GCP, VMware, bare metal, and other tested platforms, noting outbound port 25 restrictions in the cloud. +--- + # Server Environment KumoMTA can be installed in a physical server, public cloud, or private cloud. The following environments have all been tested. diff --git a/docs/userguide/installation/hardware.md b/docs/userguide/installation/hardware.md index 7fc72553..f212b694 100644 --- a/docs/userguide/installation/hardware.md +++ b/docs/userguide/installation/hardware.md @@ -1,3 +1,7 @@ +--- +description: Plan KumoMTA hardware, sizing CPU, RAM, fast local storage, and network interfaces to support high-volume sending of millions of messages per hour. +--- + # Hardware Considerations ## Selecting a server or Instance diff --git a/docs/userguide/installation/linux.md b/docs/userguide/installation/linux.md index 6c6ebda3..3ca47187 100644 --- a/docs/userguide/installation/linux.md +++ b/docs/userguide/installation/linux.md @@ -1,3 +1,7 @@ +--- +description: Install KumoMTA on Linux from prebuilt repositories for Rocky, Ubuntu, and Amazon Linux, with steps for the initial config file and starting the server. +--- + # Installing on Linux Pre-built releases are available for Rocky Linux 8/9, Ubuntu 20.04/22.04, and Amazon Linux 2/2023. diff --git a/docs/userguide/installation/operatingsystem.md b/docs/userguide/installation/operatingsystem.md index 9545a8c0..6a92b875 100644 --- a/docs/userguide/installation/operatingsystem.md +++ b/docs/userguide/installation/operatingsystem.md @@ -1,3 +1,7 @@ +--- +description: Select an operating system for KumoMTA, covering officially supported platforms and additional community-tested Linux distributions for building from source. +--- + # Operating System Selection and Configuration Pre-built packages are provided for the officially supported platforms listed on the [Installing on Linux](linux.md) page. If you build from source, a wide variety of operating systems are possible. diff --git a/docs/userguide/installation/overview.md b/docs/userguide/installation/overview.md index 2b4f0da6..89d8ba54 100644 --- a/docs/userguide/installation/overview.md +++ b/docs/userguide/installation/overview.md @@ -1,3 +1,7 @@ +--- +description: An overview of installing KumoMTA from a repository, as a Docker container, or from source, plus guidance on architecture, environment, and hardware. +--- + # Installation Overview This chapter starts with information regarding how to architect your deployment, what environment and hardware to select, as well as descriptions of supported operating systems. We recommend reading this chapter in order before jumping to the chapter for your install environment of choice. diff --git a/docs/userguide/installation/security.md b/docs/userguide/installation/security.md index 7e0a064e..2dbef4ca 100644 --- a/docs/userguide/installation/security.md +++ b/docs/userguide/installation/security.md @@ -1,3 +1,7 @@ +--- +description: Secure your KumoMTA installation with guidance on service accounts, privilege dropping, directory permissions, SMTP relaying, authentication, and TLS. +--- + # Security Considerations This page summarizes the key considerations for deploying a secure installation of KumoMTA. diff --git a/docs/userguide/installation/source.md b/docs/userguide/installation/source.md index 8662b67d..a255e78b 100644 --- a/docs/userguide/installation/source.md +++ b/docs/userguide/installation/source.md @@ -1,3 +1,7 @@ +--- +description: Build KumoMTA from source when prebuilt packages are unavailable, covering prerequisites, Rust setup, compiling, packaging, and creating the initial config. +--- + # Building From Source If pre-built binaries are not provided for your system of choice, or if you'd diff --git a/docs/userguide/installation/system_prep.md b/docs/userguide/installation/system_prep.md index 5889913f..0fbd0504 100644 --- a/docs/userguide/installation/system_prep.md +++ b/docs/userguide/installation/system_prep.md @@ -1,3 +1,7 @@ +--- +description: Prepare your system before installing KumoMTA, configuring firewall security groups, the required SMTP and HTTP ports, and applying the latest OS patches. +--- + # System Preparation Regardless of what OS and hardware you select, there are some basic things you should do to prepare your system before installing KumoMTA. While veteran system admins will probably have done much of this already as a standard course of building a server, it is worth noting these to save you some stress later. diff --git a/docs/userguide/installation/upgrading.md b/docs/userguide/installation/upgrading.md index 576ceda3..400d92d5 100644 --- a/docs/userguide/installation/upgrading.md +++ b/docs/userguide/installation/upgrading.md @@ -1,3 +1,7 @@ +--- +description: Upgrade KumoMTA installed from a repository using standard dnf or apt package upgrade commands on RPM- and Debian-based Linux systems. +--- + # Upgrading KumoMTA If you have installed from a repository, you can upgrade with the same process used for any package upgrade. diff --git a/docs/userguide/integrations/emailelement.md b/docs/userguide/integrations/emailelement.md index 300b4429..c6bf81e3 100644 --- a/docs/userguide/integrations/emailelement.md +++ b/docs/userguide/integrations/emailelement.md @@ -1,3 +1,7 @@ +--- +description: Integrate EmailElement with KumoMTA to power multi-brand email marketing campaigns, configuring KumoMTA as an SMTP send integration for the platform. +--- + # EmailElement KumoMTA Integration ## Introduction diff --git a/docs/userguide/integrations/grafana.md b/docs/userguide/integrations/grafana.md index b0b5f2e5..72786c9c 100644 --- a/docs/userguide/integrations/grafana.md +++ b/docs/userguide/integrations/grafana.md @@ -1,3 +1,7 @@ +--- +description: Integrate Grafana with KumoMTA to visualize metrics and generate alerts, consuming the KumoMTA data feed exposed through Prometheus for dashboards. +--- + # Grafana integration ## Introduction diff --git a/docs/userguide/integrations/hornetsecurity.md b/docs/userguide/integrations/hornetsecurity.md index d42cae94..004cdba5 100644 --- a/docs/userguide/integrations/hornetsecurity.md +++ b/docs/userguide/integrations/hornetsecurity.md @@ -1,3 +1,7 @@ +--- +description: Integrate Hornetsecurity Email Protection with KumoMTA to scan messages for spam and malware in real time using the Hornetsecurity Filter Engine. +--- + # Hornetsecurity Spam and Malware Protection integration ## Introduction diff --git a/docs/userguide/integrations/index.md b/docs/userguide/integrations/index.md index 6f2f0bfa..59179487 100644 --- a/docs/userguide/integrations/index.md +++ b/docs/userguide/integrations/index.md @@ -1,3 +1,7 @@ +--- +description: Explore KumoMTA integrations with partner and adjacent systems, from open source tools to paid services, for marketing, monitoring, and deliverability. +--- + # Integrations This chapter is focused on partner and adjacent systems integrations. diff --git a/docs/userguide/integrations/mautic.md b/docs/userguide/integrations/mautic.md index 4c0fc754..ee59e621 100644 --- a/docs/userguide/integrations/mautic.md +++ b/docs/userguide/integrations/mautic.md @@ -1,3 +1,7 @@ +--- +description: Integrate the open source marketing automation platform Mautic with KumoMTA, using SMTP AUTH to inject and deliver email campaigns through KumoMTA. +--- + # Mautic integration ## Introduction diff --git a/docs/userguide/integrations/ongage.md b/docs/userguide/integrations/ongage.md index 8a6937c5..0004d006 100644 --- a/docs/userguide/integrations/ongage.md +++ b/docs/userguide/integrations/ongage.md @@ -1,3 +1,7 @@ +--- +description: Integrate the Ongage email marketing platform with KumoMTA as your delivery engine, configuring SMTP AUTH with TLS and the required sending DNS records. +--- + # Ongage SMTP integration ## Introduction diff --git a/docs/userguide/integrations/postmastery.md b/docs/userguide/integrations/postmastery.md index baf327b6..4a8337c6 100644 --- a/docs/userguide/integrations/postmastery.md +++ b/docs/userguide/integrations/postmastery.md @@ -1,3 +1,7 @@ +--- +description: Monitor deliverability with Postmastery Console using KumoMTA data, integrating via webhooks to track blocklisting, DMARC reports, and best practices. +--- + # Deliverability Reporting with Postmastery Console Postmastery Console is a third-party cloud-hosted tool for monitoring deliverability and the factors that affect deliverability such as blocklisting, DMARC reports, and messaging best practices. Postmastery Console is able to incorporate data provided by KumoMTA to give a full picture of an organization's deliverability. More information on Postmastery Console can be found at [https://www.postmastery.com/postmastery-email-analytics-console/](https://www.postmastery.com/postmastery-email-analytics-console/). diff --git a/docs/userguide/integrations/prometheus.md b/docs/userguide/integrations/prometheus.md index ef4f56ce..91367e1c 100644 --- a/docs/userguide/integrations/prometheus.md +++ b/docs/userguide/integrations/prometheus.md @@ -1,3 +1,7 @@ +--- +description: Add observability to KumoMTA with Prometheus, collecting and storing time-series metrics and labels for monitoring and alerting on your email infrastructure. +--- + # Observability with Prometheus ## Introduction diff --git a/docs/userguide/integrations/rspamd.md b/docs/userguide/integrations/rspamd.md index 50166dd1..4358ff28 100644 --- a/docs/userguide/integrations/rspamd.md +++ b/docs/userguide/integrations/rspamd.md @@ -1,3 +1,7 @@ +--- +description: Integrate the open source Rspamd spam filter with KumoMTA, adding message scanning to your init.lua policy to filter outbound or relayed email. +--- + # Rspamd Spam filter ## Introduction diff --git a/docs/userguide/integrations/tatamimonitor.md b/docs/userguide/integrations/tatamimonitor.md index e749a3ce..3ddd0a11 100644 --- a/docs/userguide/integrations/tatamimonitor.md +++ b/docs/userguide/integrations/tatamimonitor.md @@ -1,3 +1,7 @@ +--- +description: Integrate Tatami Monitor with KumoMTA for real-time email infrastructure monitoring and alerting, using a webhook log hook to stream event data. +--- + # Tatami Monitor integration ## Introduction diff --git a/docs/userguide/operation/cancel.md b/docs/userguide/operation/cancel.md index 1a9f64ce..0f4ce6b3 100644 --- a/docs/userguide/operation/cancel.md +++ b/docs/userguide/operation/cancel.md @@ -1,3 +1,7 @@ +--- +description: Cancel queued messages in KumoMTA with the Admin Bounce API or kcli, targeting a specific campaign, queue, or tenant to stop a bad send with precision. +--- + # Canceling Queued Messages Occasionally, you will have a bad send or for some reason need to cancel a send diff --git a/docs/userguide/operation/command-line-index.md b/docs/userguide/operation/command-line-index.md index a394f6b2..af8c9c14 100644 --- a/docs/userguide/operation/command-line-index.md +++ b/docs/userguide/operation/command-line-index.md @@ -1,3 +1,7 @@ +--- +description: Reference the KumoMTA command-line utilities in /opt/kumomta/sbin, including validate-shaping, resolve-shaping-domain, traffic-gen, tailer, and more. +--- + # Supporting utilities KumoMTA comes with several utilities that are useful for debugging or supporting KumoMTA. These are located in `/opt/kumomta/sbin/`. diff --git a/docs/userguide/operation/httpinjection.md b/docs/userguide/operation/httpinjection.md index c1658ece..4abe858e 100644 --- a/docs/userguide/operation/httpinjection.md +++ b/docs/userguide/operation/httpinjection.md @@ -1,3 +1,7 @@ +--- +description: Inject messages into KumoMTA over HTTP using a configured HTTP listener, controlling the IPs and ports available for message submission via the API. +--- + # Injecting Using HTTP KumoMTA will listen for message injection in any diff --git a/docs/userguide/operation/kcli.md b/docs/userguide/operation/kcli.md index 013930c6..b09adf30 100644 --- a/docs/userguide/operation/kcli.md +++ b/docs/userguide/operation/kcli.md @@ -1,3 +1,7 @@ +--- +description: Use the kcli command-line client to administer KumoMTA over its HTTP API, monitoring queues, managing bounces, and tracing inbound and outbound SMTP. +--- + # Using the kcli Command-Line Client KumoMTA comes with several API endpoints to make administration of the server diff --git a/docs/userguide/operation/kumo-proxy.md b/docs/userguide/operation/kumo-proxy.md index dd46637a..4d0c297b 100644 --- a/docs/userguide/operation/kumo-proxy.md +++ b/docs/userguide/operation/kumo-proxy.md @@ -1,3 +1,7 @@ +--- +description: Run the KumoProxy SOCKS5 proxy server to share sending IPs across a KumoMTA cluster, including installing it as a systemd service to survive restarts. +--- + # Using the KumoProxy SOCKS5 proxy utility KumoMTA comes with its own SOCKS5 proxy server to assist with deployment of cluster environments. diff --git a/docs/userguide/operation/logs.md b/docs/userguide/operation/logs.md index 1d1132a5..cb8f427c 100644 --- a/docs/userguide/operation/logs.md +++ b/docs/userguide/operation/logs.md @@ -1,3 +1,7 @@ +--- +description: View KumoMTA logs stored as compressed, date-stamped segments in /var/log/kumomta, reading them with the tailer utility or by decompressing files manually. +--- + # Viewing Logs An important part of routine operations is checking logs. KumoMTA compressed diff --git a/docs/userguide/operation/outbound_auth.md b/docs/userguide/operation/outbound_auth.md index db0de86f..f9f8ea52 100644 --- a/docs/userguide/operation/outbound_auth.md +++ b/docs/userguide/operation/outbound_auth.md @@ -1,3 +1,7 @@ +--- +description: Deliver messages from KumoMTA using SMTP AUTH, configuring an egress path with credentials or a keysource to authenticate when relaying through upstream hosts. +--- + # Delivering Messages Using SMTP AUTH While not used when delivering messages to remote hosts under normal circumstances, there are scenarios where the KumoMTA server must authenticate when relaying mail. Some examples include: diff --git a/docs/userguide/operation/performance.md b/docs/userguide/operation/performance.md index 36aba941..e4a1d1ad 100644 --- a/docs/userguide/operation/performance.md +++ b/docs/userguide/operation/performance.md @@ -1 +1,5 @@ +--- +description: This page has moved to the KumoMTA Performance chapter, covering architecture, Linux tuning, DNS, testing, message flows, and log hooks for high-volume sending. +--- + This page has moved, see the [Performance](../performance/index.md) chapter. \ No newline at end of file diff --git a/docs/userguide/operation/proxy.md b/docs/userguide/operation/proxy.md index 3d5ba986..414d1486 100644 --- a/docs/userguide/operation/proxy.md +++ b/docs/userguide/operation/proxy.md @@ -1,3 +1,7 @@ +--- +description: Route KumoMTA message delivery through SOCKS5 or HAProxy forward proxies to share IP addresses across instances and send from remote environments. +--- + # Routing Messages Via Proxy Servers KumoMTA supports SOCKS5 and HAProxy for use as forward proxies as part of message delivery. diff --git a/docs/userguide/operation/smtpinjection.md b/docs/userguide/operation/smtpinjection.md index da78aa29..05fcc345 100644 --- a/docs/userguide/operation/smtpinjection.md +++ b/docs/userguide/operation/smtpinjection.md @@ -1,3 +1,7 @@ +--- +description: Inject messages into KumoMTA over SMTP using a configured ESMTP listener, controlling the IP addresses and ports available for message submission. +--- + # Injecting Using SMTP KumoMTA will listen for message injection in any diff --git a/docs/userguide/operation/starting.md b/docs/userguide/operation/starting.md index 4c98844a..705f9798 100644 --- a/docs/userguide/operation/starting.md +++ b/docs/userguide/operation/starting.md @@ -1,3 +1,7 @@ +--- +description: Start KumoMTA as a systemd service or manually with kumod, enabling it to run at boot and pointing it at your init.lua policy script. +--- + # Starting KumoMTA Once KumoMTA has been installed and an initial policy script is in place, the diff --git a/docs/userguide/operation/status.md b/docs/userguide/operation/status.md index c11928e1..225a4189 100644 --- a/docs/userguide/operation/status.md +++ b/docs/userguide/operation/status.md @@ -1,3 +1,7 @@ +--- +description: Check KumoMTA server status with systemctl and kcli, monitor the running service, and set up a Grafana dashboard to track health and activity. +--- + # Getting Server Status Once KumoMTA is installed, you can check on the server status with systemctl. diff --git a/docs/userguide/operation/troubleshooting.md b/docs/userguide/operation/troubleshooting.md index 0dd67a1b..57e7903f 100644 --- a/docs/userguide/operation/troubleshooting.md +++ b/docs/userguide/operation/troubleshooting.md @@ -1,3 +1,7 @@ +--- +description: Troubleshoot common KumoMTA issues by validating your configuration, testing injection with Swaks, tracing SMTP conversations, and reviewing logs. +--- + # Troubleshooting KumoMTA There are several things that can go wrong, especially when first installing KumoMTA. This page is intended to help with troubleshooting common issues. diff --git a/docs/userguide/operation/webhooks.md b/docs/userguide/operation/webhooks.md index 46fae3c5..0b63635d 100644 --- a/docs/userguide/operation/webhooks.md +++ b/docs/userguide/operation/webhooks.md @@ -1,3 +1,7 @@ +--- +description: Publish KumoMTA log events via webhooks for near real-time integration, using the log_hooks.lua helper and durable queuing to deliver events to HTTP endpoints. +--- + # Publishing Log Events Via Webhooks While logs are an invaluable resource for monitoring and troubleshooting mail diff --git a/docs/userguide/performance/architecture.md b/docs/userguide/performance/architecture.md index 24043736..caee5ca6 100644 --- a/docs/userguide/performance/architecture.md +++ b/docs/userguide/performance/architecture.md @@ -1,3 +1,7 @@ +--- +description: Architect KumoMTA for performance and scalability, weighing CPU choice, horizontal scaling, dynamic cluster sizing, disk, network, and role separation. +--- + # Architecting for Performance and Scalability For lower volume environments it may be practical to run your email infrastructure on a single KumoMTA instance, especially in a virtualized environment where single-node fault tolerance is relatively high. diff --git a/docs/userguide/performance/dns.md b/docs/userguide/performance/dns.md index 0da19ccf..ead6a36c 100644 --- a/docs/userguide/performance/dns.md +++ b/docs/userguide/performance/dns.md @@ -1,3 +1,7 @@ +--- +description: Optimize DNS performance for KumoMTA with a local caching resolver, since DNS lookups are central to validating, queueing, and routing every message. +--- + # DNS Performance DNS is at the core of KumoMTA's processing pathway, it's used to validate incoming messages and their destination and to define queueing, and it's needed to successfully route messages to their MXes. diff --git a/docs/userguide/performance/index.md b/docs/userguide/performance/index.md index 2b28c6b3..bc77d9c3 100644 --- a/docs/userguide/performance/index.md +++ b/docs/userguide/performance/index.md @@ -1,3 +1,7 @@ +--- +description: Optimize KumoMTA for high-performance sending with this chapter on architecture, Linux tuning, DNS, performance testing, message flows, and log hooks. +--- + # KumoMTA Performance Optimization KumoMTA is designed for high-performance sending environments and is architected to allow for significant performance tuning. diff --git a/docs/userguide/performance/linuxtuning.md b/docs/userguide/performance/linuxtuning.md index 638a8e27..1cc52889 100644 --- a/docs/userguide/performance/linuxtuning.md +++ b/docs/userguide/performance/linuxtuning.md @@ -1,3 +1,7 @@ +--- +description: Tune Linux for KumoMTA performance by adjusting sysctl.conf parameters for file handles, memory buffers, and networking to maximize resource utilization. +--- + # Linux Tuning for Performance KumoMTA performance can be optimized by fine tuning system parameters. The parameters listed below are a starting point: research each one and tune it as needed for your own system. diff --git a/docs/userguide/performance/loghooks.md b/docs/userguide/performance/loghooks.md index 6ef57f1e..77da886f 100644 --- a/docs/userguide/performance/loghooks.md +++ b/docs/userguide/performance/loghooks.md @@ -1,3 +1,7 @@ +--- +description: Understand the performance implications of KumoMTA log hooks, tuning traffic shaping and batching for webhook, AMQP, and Kafka log event delivery. +--- + # The Performance Implications of Log Hooks KumoMTA supports the use of [webhooks](../operation/webhooks.md) for the delivery of log events, as well as routing events via [AMQP](../policy/amqp.md) and [Kafka](../policy/kafka.md). diff --git a/docs/userguide/performance/messageflow.md b/docs/userguide/performance/messageflow.md index 06fa874a..558b21aa 100644 --- a/docs/userguide/performance/messageflow.md +++ b/docs/userguide/performance/messageflow.md @@ -1,3 +1,7 @@ +--- +description: Understand how messages flow through KumoMTA queues and processing stages, the key to tuning throughput and resource usage in high-volume deployments. +--- + # Understanding Message Flows Most KumoMTA performance tuning is going to involve tuning the flow of messages through KumoMTA and how each stage of the flow can affect performance. This involves understanding both how the queues work as well as the various processing that occurs. diff --git a/docs/userguide/performance/testing.md b/docs/userguide/performance/testing.md index 932e6de0..3edfaf15 100644 --- a/docs/userguide/performance/testing.md +++ b/docs/userguide/performance/testing.md @@ -1,3 +1,7 @@ +--- +description: Performance test KumoMTA safely against a smart sink instead of the public internet, generating realistic traffic with traffic-gen to tune throughput. +--- + # Performance Testing Performance testing **must not** be performed against the public internet, as large volumes of test messages can be catastrophic for sending reputation. This isn't to say that one-off test messages will be a problem, but that sending in bulk can cause serious issues. diff --git a/docs/userguide/policy/amqp.md b/docs/userguide/policy/amqp.md index b6b01684..42de8100 100644 --- a/docs/userguide/policy/amqp.md +++ b/docs/userguide/policy/amqp.md @@ -1,3 +1,7 @@ +--- +description: Route KumoMTA log events and queued messages via AMQP, configuring a custom_lua queue handler to publish records to an AMQP broker. +--- + # Routing Messages via AMQP In addition to local logging and Webhooks, KumoMTA can relay log events (or other queued messages) via AMQP. diff --git a/docs/userguide/policy/hashicorp_vault.md b/docs/userguide/policy/hashicorp_vault.md index 0e5cb477..4f4525bc 100644 --- a/docs/userguide/policy/hashicorp_vault.md +++ b/docs/userguide/policy/hashicorp_vault.md @@ -1,3 +1,7 @@ +--- +description: Use HashiCorp Vault with KumoMTA to securely store DKIM signing keys and secrets outside your policy code, loading them dynamically at runtime. +--- + # Using HashiCorp Vault ## Introduction diff --git a/docs/userguide/policy/http.md b/docs/userguide/policy/http.md index d083e717..e1ae8ac3 100644 --- a/docs/userguide/policy/http.md +++ b/docs/userguide/policy/http.md @@ -1,3 +1,7 @@ +--- +description: Route KumoMTA messages via HTTP requests with custom Lua, assembling API calls to relay mail through third-party HTTP email APIs such as Mailgun. +--- + # Routing Messages via HTTP Request Some sending environments use a mixture of different services to send messages, and while it's possible to relay messages through many services using SMTP, some services are only/better served via an HTTP API. diff --git a/docs/userguide/policy/inbound_auth.md b/docs/userguide/policy/inbound_auth.md index 267ddb6a..219e3eb7 100644 --- a/docs/userguide/policy/inbound_auth.md +++ b/docs/userguide/policy/inbound_auth.md @@ -1,3 +1,7 @@ +--- +description: Check inbound SMTP authentication in KumoMTA over TLS, validating relay users against a static table, a datasource, or a keystore to protect your infrastructure. +--- + # Checking Inbound SMTP Authentication When hosting relay users it is important to protect your infrastructure from malicious senders, often without the ability to allowlist the IP addresses of legitimate users. In such environments, it is critical to set up SMTP Authentication to validate injecting hosts before relaying their mail. diff --git a/docs/userguide/policy/index.md b/docs/userguide/policy/index.md index 89331dd8..cec299c4 100644 --- a/docs/userguide/policy/index.md +++ b/docs/userguide/policy/index.md @@ -1,3 +1,7 @@ +--- +description: The KumoMTA Policy chapter covers advanced Lua policy scripting use cases for experienced users configuring routing, authentication, and message handling. +--- + # Policy While the entirety of configuring a KumoMTA instance is done with policy, this diff --git a/docs/userguide/policy/kafka.md b/docs/userguide/policy/kafka.md index de5c8018..59033729 100644 --- a/docs/userguide/policy/kafka.md +++ b/docs/userguide/policy/kafka.md @@ -1,3 +1,7 @@ +--- +description: Route KumoMTA log events and queued messages via Apache Kafka, configuring a custom_lua queue handler to publish records to Kafka topics. +--- + # Routing Messages via Kafka {{since('2023.12.28-63cde9c7')}} diff --git a/docs/userguide/policy/nats.md b/docs/userguide/policy/nats.md index 656ee477..f37b98f9 100644 --- a/docs/userguide/policy/nats.md +++ b/docs/userguide/policy/nats.md @@ -1,3 +1,7 @@ +--- +description: Route KumoMTA log events and queued messages via NATS JetStream, configuring a custom_lua queue handler to publish records to NATS. +--- + # Routing Messages via NATS {{since('2026.03.04-bb93ecb1')}} diff --git a/docs/userguide/policy/rewrite.md b/docs/userguide/policy/rewrite.md index 57110dcf..4b336546 100644 --- a/docs/userguide/policy/rewrite.md +++ b/docs/userguide/policy/rewrite.md @@ -1,3 +1,7 @@ +--- +description: Rewrite remote server responses in KumoMTA with the smtp_client_rewrite_delivery_status event, transposing temporary failures to permanent bounces and back. +--- + # Rewriting Remote Server Responses {{since('2023.11.28-b5252a41')}} diff --git a/docs/userguide/policy/routing.md b/docs/userguide/policy/routing.md index 2e52bdb4..26761e86 100644 --- a/docs/userguide/policy/routing.md +++ b/docs/userguide/policy/routing.md @@ -1,3 +1,7 @@ +--- +description: Configure message routing in KumoMTA to smarthost or relay mail, overriding routing domains per message or per queue and handling IPv4 and IPv6 literals. +--- + # Configuring Message Routing If you need to "smarthost" or route messages through another server, you have diff --git a/docs/userguide/trafficshaping/automation.md b/docs/userguide/trafficshaping/automation.md index 74f71e4b..7724c139 100644 --- a/docs/userguide/trafficshaping/automation.md +++ b/docs/userguide/trafficshaping/automation.md @@ -1,3 +1,7 @@ +--- +description: Automate KumoMTA traffic shaping with the tsa-daemon, monitoring mailbox provider responses to adjust connection, rate, and volume rules in real time. +--- + # Traffic Shaping Automation Many of the largest MailBox Providers (MBPs) operate platforms that provide feedback to senders through their response codes during the SMTP conversation. This feedback will include information related to the traffic shaping patterns in use by the sender, including bounces for too many connections, too many messages per connection, sending rate, and sender reputation. diff --git a/docs/userguide/trafficshaping/customshaping.md b/docs/userguide/trafficshaping/customshaping.md index b48801e2..7cd35584 100644 --- a/docs/userguide/trafficshaping/customshaping.md +++ b/docs/userguide/trafficshaping/customshaping.md @@ -1,3 +1,7 @@ +--- +description: Write custom KumoMTA traffic shaping files in TOML or JSON to add your own domain rules alongside the team- and community-maintained shaping.toml files. +--- + # Writing Custom Shaping Files ## Writing Your Own Traffic Shaping Rules diff --git a/docs/userguide/trafficshaping/index.md b/docs/userguide/trafficshaping/index.md index 0200dc1e..4604ac9a 100644 --- a/docs/userguide/trafficshaping/index.md +++ b/docs/userguide/trafficshaping/index.md @@ -1,3 +1,7 @@ +--- +description: Shape KumoMTA outbound traffic to match mailbox provider limits, configuring egress paths with connection, message rate, and concurrency controls. +--- + # Traffic Shaping diff --git a/docs/userguide/trafficshaping/resolution.md b/docs/userguide/trafficshaping/resolution.md index cea52eff..84883fa6 100644 --- a/docs/userguide/trafficshaping/resolution.md +++ b/docs/userguide/trafficshaping/resolution.md @@ -1,3 +1,7 @@ +--- +description: Understand the order and precedence KumoMTA uses to resolve traffic shaping options, merging default, provider, site name, domain, and source blocks. +--- + # Shaping Option Resolution Order and Precedence When resolving the configuration for a site, the options are resolved in the diff --git a/docs/userguide/trafficshaping/rollups.md b/docs/userguide/trafficshaping/rollups.md index 8d2b76a4..061e9229 100644 --- a/docs/userguide/trafficshaping/rollups.md +++ b/docs/userguide/trafficshaping/rollups.md @@ -1,3 +1,7 @@ +--- +description: Configure MX rollups and provider blocks in KumoMTA shaping, controlling option inheritance by site name and pattern-matching domains with mx_rollup settings. +--- + # MX Rollups and Provider Blocks ## MX Rollups and Option Inheritance diff --git a/docs/userguide/trafficshaping/scoping.md b/docs/userguide/trafficshaping/scoping.md index 96c7a8c5..0b41425b 100644 --- a/docs/userguide/trafficshaping/scoping.md +++ b/docs/userguide/trafficshaping/scoping.md @@ -1,3 +1,7 @@ +--- +description: Scope KumoMTA traffic shaping rules using the get_egress_path_config event, keying configuration on routing domain, egress source, and site name. +--- + # Scoping Traffic Shaping Rules When KumoMTA needs to connect to a remote host to deliver messages, the [get_egress_path_config](../../reference/events/get_egress_path_config.md) event is fired in order to determine what configuration to use for that specific pathway. diff --git a/docs/userguide/trafficshaping/shapingfiles.md b/docs/userguide/trafficshaping/shapingfiles.md index 62851419..3911e135 100644 --- a/docs/userguide/trafficshaping/shapingfiles.md +++ b/docs/userguide/trafficshaping/shapingfiles.md @@ -1,3 +1,7 @@ +--- +description: Configure KumoMTA traffic shaping with TOML or JSON files, covering the default and community shaping.toml, custom files, and configuration precedence. +--- + # Traffic Shaping Configuration Files The `shaping.lua` policy reads one or more configuration files in either TOML or JSON formats. diff --git a/docs/userguide/trafficshaping/testing.md b/docs/userguide/trafficshaping/testing.md index 1f38e1fc..5a0de0ab 100644 --- a/docs/userguide/trafficshaping/testing.md +++ b/docs/userguide/trafficshaping/testing.md @@ -1,3 +1,7 @@ +--- +description: Test your KumoMTA traffic shaping files with the validate-shaping utility, checking custom shaping.toml override syntax before deploying to production. +--- + # Testing Your Shaping Files Included in the standard deployment is a validation tool for testing the syntax of your shaping.toml override file. The file located at `/opt/kumomta/sbin/validate-shaping` can be used to validate the syntax of your shaping file. If there are no errors, it will return an "OK".