KumoMTA

https://docs.kumomta.com
Admin
KumoMTA is a modern, high-performance Message Transfer Agent (MTA) for reliable email delivery with...
Tokens:3,629,745
Snippets:26,236
Trust Score:6.9
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install and start bind9

Source: https://docs.kumomta.com/userguide/installation/system_prep?q=

Installs and starts the bind9 caching name server, which is critical for high-performance mail engines. Test it after installation.

```bash
sudo apt install bind9 -y
sudo systemctl start named

```

--------------------------------

### Install example configuration files

Source: https://docs.kumomta.com/userguide/installation/source

Installs the example/starter configuration files init.lua and tsa_init.lua into /opt/kumomta/etc/policy. You may skip this step and deploy your own configuration instead.

```bash
$ sudo install -Dm644 assets/init.lua -T /opt/kumomta/etc/policy/init.lua
$ sudo install -Dm644 assets/tsa_init.lua -T /opt/kumomta/etc/policy/tsa_init.lua

```

--------------------------------

### Start and enable kumomta service

Source: https://docs.kumomta.com/tutorial/quickstart

Starts and enables the KumoMTA service if it did not start after installation.

```bash
sudo systemctl start kumomta
sudo systemctl enable kumomta

```

--------------------------------

### Basic SOCKS5 proxy listener setup

Source: https://docs.kumomta.com/reference/proxy/start_proxy_listener

Starts a SOCKS5 proxy listener on 0.0.0.0:1080. This should be called from the proxy_init event handler.

```lua
kumo.on('proxy_init', function()
  proxy.start_proxy_listener {
    listen = '0.0.0.0:1080',
  }
end)

```

--------------------------------

### Install Prometheus

Source: https://docs.kumomta.com/userguide/integrations/prometheus

Downloads and extracts Prometheus v2.47.2. The example installs on localhost, but Prometheus can run on a remote server to collect metrics from a cluster.

```bash
$ cd
$ wget https://github.com/prometheus/prometheus/releases/download/v2.47.2/prometheus-2.47.2.linux-amd64.tar.gz
$ tar xvf prometheus-*.*-amd64.tar.gz cd prometheus-2.47.2.linux-amd64/

```

--------------------------------

### Example: set_signing_threads in pre_init

Source: https://docs.kumomta.com/reference/kumo.dkim/set_signing_threads

Starts the signing thread pool with half the system's cores. Use this when workloads mix IO and compute, allowing better sizing of smtpsrv or readyq pools. Adds context-switching overhead.

```lua
kumo.on('pre_init', function()
  -- Use half the cores on the system for DKIM signing
  kumo.dkim.set_signing_threads(math.ceil(kumo.available_parallelism() / 2))
end)

```

--------------------------------

### Start HTTP listener for metrics in proxy_init

Source: https://docs.kumomta.com/reference/proxy/start_http_listener?q=

Example of starting both the SOCKS5 proxy and the HTTP listener for metrics inside the proxy_init event handler. The HTTP listener is configured with listen address 0.0.0.0:8080 and trusted_hosts restricted to localhost addresses.

```lua
local kumo = require 'kumo'
local proxy = require 'proxy'

kumo.on('proxy_init', function()
  -- Start the SOCKS5 proxy
  proxy.start_proxy_listener {
    listen = '0.0.0.0:1080',
  }

  -- Start the HTTP listener for metrics
  proxy.start_http_listener {
    listen = '0.0.0.0:8080',
    trusted_hosts = { '127.0.0.1', '::1' },
  }
end)

```

--------------------------------

### Complete Example Server Policy (init.lua)

Source: https://docs.kumomta.com/userguide/configuration/example

A full example policy file for KumoMTA, intended to be written to /opt/kumomta/etc/policy/init.lua. It requires external TOML files (sources.toml, dkim_data.toml, shaping.toml, queues.toml) and sets up event handlers for init, spool, logging, and bounce classification.

```lua
-- NOTE: This example policy is not meant to be used as-is, and will require some editing.
-- We strongly recommend reading the User Guide chapter on configuration before working with
-- this example policy. See https://docs.kumomta.com/userguide/configuration

-- This file must be written to /opt/kumomta/etc/policy/init.lua for use.

-- This require statement is needed in any script passed to KumoMTA.
-- Includes from this policy script will not need this declared again.
local kumo = require 'kumo'
local utils = require 'policy-extras.policy_utils'

-- Load the policy helpers to simplify common configuration use cases
local shaping = require 'policy-extras.shaping'
local queue_module = require 'policy-extras.queue'
local listener_domains = require 'policy-extras.listener_domains'
local sources = require 'policy-extras.sources'
local dkim_sign = require 'policy-extras.dkim_sign'
local log_hooks = require 'policy-extras.log_hooks'

-- START SETUP

-- Configure the sending IP addresses that will be used by KumoMTA to
-- connect to remote systems using the sources.lua policy helper.
-- Note that defining sources and pools does nothing without some form of
-- policy in effect to assign messages to the source pools you have defined.
-- WARNING: THIS WILL NOT LOAD WITHOUT THE source.toml FILE IN PLACE
-- SEE https://docs.kumomta.com/userguide/configuration/sendingips/
sources:setup { '/opt/kumomta/etc/policy/sources.toml' }

-- Configure DKIM signing. In this case we use the dkim_sign.lua policy helper.
-- WARNING: THIS WILL NOT LOAD WITHOUT the dkim_data.toml FILE IN PLACE
-- See https://docs.kumomta.com/userguide/configuration/dkim/
local dkim_signer =
  dkim_sign:setup { '/opt/kumomta/etc/policy/dkim_data.toml' }

-- Load Traffic Shaping Automation Helper
local shaper = shaping:setup_with_automation {
  publish = { 'http://127.0.0.1:8008' },
  subscribe = { 'http://127.0.0.1:8008' },
  extra_files = { '/opt/kumomta/etc/policy/shaping.toml' },
}

-- Send a JSON webhook to a local network host.
-- See https://docs.kumomta.com/userguide/operation/webhooks/
log_hooks:new_json {
  name = 'webhook',
  url = 'http://10.0.0.1:4242/log',
  log_parameters = {
    headers = { 'Subject', 'X-Customer-ID' },
  },
}

-- Configure queue management settings. These are not throttles, but instead
-- control how messages flow through the queues.
-- WARNING: ENSURE THAT WEBHOOKS AND SHAPING ARE SET UP BEFORE THE QUEUE HELPER FOR PROPER OPERATION
-- WARNING: THIS WILL NOT LOAD WITHOUT the queues.toml FILE IN PLACE
-- See https://docs.kumomta.com/userguide/configuration/queuemanagement/
local queue_helper =
  queue_module:setup { '/opt/kumomta/etc/policy/queues.toml' }

-- END SETUP

--START EVENT HANDLERS

-- Called On Startup, handles initial configuration
kumo.on('init', function()
  -- Define the default "data" spool location; this is where
  -- message bodies will be stored.
  -- See https://docs.kumomta.com/userguide/configuration/spool/

  kumo.define_spool {
    name = 'data',
    path = '/var/spool/kumomta/data',
    kind = 'RocksDB',
  }

  -- Define the default "meta" spool location; this is where
  -- message envelope and metadata will be stored.
  kumo.define_spool {
    name = 'meta',
    path = '/var/spool/kumomta/meta',
    kind = 'RocksDB',
  }

  -- Configure publishing of TSA logs to automation daemon
  shaper.setup_publish()

  -- Configure logging to local disk. Separating spool and logs to separate
  -- disks helps reduce IO load and can help performance.
  -- See https://docs.kumomta.com/userguide/configuration/logging/
  kumo.configure_local_logs {
    log_dir = '/var/log/kumomta',
    max_segment_duration = '1 minute',
    -- headers = { 'Subject', 'X-Customer-ID' },
  }

  -- Configure bounce classification.
  -- See https://docs.kumomta.com/userguide/configuration/bounce/
  kumo.configure_bounce_classifier {
    files = {
      '/opt/kumomta/share/bounce_classifier/iana.toml',
    },
  }

```

--------------------------------

### Initialize system with listeners and spools

Source: https://docs.kumomta.com/reference/events/init

Example init handler that defines an ESMTP listener, local logs, an HTTP listener, and two spools. Can be used multiple times to define multiple listeners.

```lua
-- Called on startup to initialize the system
kumo.on('init', function()
  -- Define a listener.
  -- Can be used multiple times with different parameters to
  -- define multiple listeners!
  kumo.start_esmtp_listener {
    listen = '0.0.0.0:2025',
  }

  kumo.configure_local_logs {
    log_dir = '/var/tmp/kumo-logs',
  }

  kumo.start_http_listener {
    listen = '0.0.0.0:8000',
    -- allowed to access any http endpoint without additional auth
    trusted_hosts = { '127.0.0.1', '::1' },
  }

  kumo.define_spool {
    name = 'data',
    path = '/var/tmp/kumo-spool/data',
  }

  kumo.define_spool {
    name = 'meta',
    path = '/var/tmp/kumo-spool/meta',
  }
end)

```

--------------------------------

### Setup for subslice_range example

Source: https://docs.kumomta.com/rustapi/mailparsing/rfc5322_parser/struct.AddressList.html

Incomplete example for `subslice_range`; only the initial setup is shown. The method returns the range of indices that a subslice points to, or `None` if not aligned. Requires the nightly-only `substr_range` feature.

```rust
#![feature(substr_range)]

let nums = &[0, 5, 10, 0, 0, 5];
```

--------------------------------

### captures_from_pos example

Source: https://docs.kumomta.com/rustapi/kumo_api_types/shaping/struct.Regex.html

Example for the captures_from_pos method. It finds capture groups starting from a specified byte position.

```rust
let re = Regex::new(r"(?m:^)(\d+)").unwrap();
let text = "1 test 123\n2 foo";
let captures = re.captures_from_pos(text, 7).unwrap().unwrap();

let group = captures.get(1).unwrap();
assert_eq!(group.as_str(), "2");
assert_eq!(group.start(), 11);
assert_eq!(group.end(), 12);
```

--------------------------------

### find_from_pos example

Source: https://docs.kumomta.com/rustapi/kumo_api_types/shaping/struct.Regex.html

Example for the find_from_pos method. It finds the first match starting from a specified byte position.

```rust
let re = Regex::new(r"(?m:^)(\d+)").unwrap();
let text = "1 test 123\n2 foo";
let mat = re.find_from_pos(text, 7).unwrap().unwrap();

assert_eq!(mat.start(), 11);
assert_eq!(mat.end(), 12);
```

--------------------------------

### Launch HAProxy with configuration

Source: https://docs.kumomta.com/userguide/operation/proxy

Command to launch the HAProxy instance with the example configuration file. The -V flag enables verbose output.

```bash
$ sudo haproxy -f haproxy.conf -V

```

--------------------------------

### Example: list directory entries with kumo.read_dir

Source: https://docs.kumomta.com/reference/kumo/read_dir?q=

Example usage that logs the names of all entries under /etc using kumo.read_dir and kumo.json_encode_pretty. Requires the kumo module.

```lua
local kumo = require 'kumo'

-- logs the names of all of the entries under `/etc`
print(kumo.json_encode_pretty(kumo.read_dir '/etc'))

```

--------------------------------

### GET /api/admin/resolve-egress-path/v1

Source: https://docs.kumomta.com/reference/http/kumod/api_admin_resolve_egress_path_v1_get?q=

Documentation for the GET /api/admin/resolve-egress-path/v1 endpoint, including query parameters, response schema, and an example response.

```APIDOC
## GET /api/admin/resolve-egress-path/v1

### Description
Resolve the effective egress path configuration and throughput ceilings for a destination domain and egress source. This endpoint is used by the `kcli resolve-egress-path` command and mirrors the diagnostic that `kcli inspect-ready-q` provides for live ready queues, but operates from the configuration side.

### Method
GET

### Endpoint
/api/admin/resolve-egress-path/v1

### Parameters
#### Query Parameters
- **domain** (string) - Required - Destination domain. Drives the MX lookup and is passed through to the `get_egress_path_config` event callback.
- **source** (string, nullable) - Optional - Egress source name. Defaults to "unspecified" if omitted.

### Response
#### Success Response (200)
- **constraints** (EffectiveConstraints) - Required - Steady-state ceilings implied by an `EgressPathConfig`. Each ceiling carries a tag for which configuration term produced it. These are per-queue ceilings; shared limits in `additional_*` maps are reported at their full value and may be tighter in practice when the bucket is contended.
- **domain** (string) - Required - Destination domain.
- **mx** (MxResolution, nullable) - Optional - MX resolution result.
- **path_config** (object) - Required - Egress path configuration.
- **queue_config** (object) - Required - Snapshot of the resolved scheduled-queue configuration for this domain. Carried as an untyped JSON object because `QueueConfig` contains protocol variants that don't all round-trip cleanly through the OpenAPI schema.
- **queue_name** (string) - Required - The ready-queue name that this domain/source pair would resolve to. Lets the caller pivot to inspect-ready-q for live runtime detail when the queue exists.
- **source** (string) - Required - Egress source name.

#### Response Example
```json
{
  "constraints": {
    "max_concurrent_dispatchers": {
      "display": "string",
      "source": {
        "kind": "primary"
      },
      "value": 4.2
    },
    "max_connection_rate": {
      "display": "string",
      "source": {
        "kind": "primary"
      },
      "value": 4.2
    },
    "max_message_rate": {
      "display": "string",
      "source": {
        "kind": "primary"
      },
      "value": 4.2
    },
    "max_message_rate_declared": "string",
    "max_source_selection_rate": {
      "display": "string",
      "source": {
        "kind": "primary"
      },
      "value": 4.2
    }
  },
  "domain": "string",
  "mx": {
    "by_preference": {},
    "is_domain_literal": false,
    "is_mx": false,
    "is_secure": false,
    "site_name": "string"
  },
  "path_config": {},
  "queue_config": {},
  "queue_name": "string",
  "source": "string"
}
```
```

--------------------------------

### StartConfig::run method implementation

Source: https://docs.kumomta.com/rustapi/src/kumo_server_common/start.rs.html

Defines the run method of StartConfig, which initializes the server, sets up metrics, and manages the lifecycle. It forces the ONLINE_SINCE static, initializes logging, starts CPU monitoring, installs the default crypto provider, sets up memory limits, registers a runtime collector, registers Lua functions, sets the policy path, spawns a task to query machine info, and waits for shutdown. Errors during initialization are logged and trigger shutdown.

```rust
use crate::diagnostic_logging::LoggingConfig;
use crate::nodeid::NodeId;
use anyhow::Context;
use chrono::{DateTime, Utc};
use config::RegisterFunc;
use kumo_machine_info::MachineInfo;
use kumo_prometheus::declare_metric;
use kumo_server_lifecycle::LifeCycle;
use kumo_server_runtime::rt_spawn;
use parking_lot::Mutex;
use std::future::Future;
use std::path::Path;
use std::sync::LazyLock;

pub static ONLINE_SINCE: LazyLock<DateTime<Utc>> = LazyLock::new(Utc::now);
pub static MACHINE_INFO: LazyLock<Mutex<Option<MachineInfo>>> = LazyLock::new(|| Mutex::new(None));

pub struct StartConfig<'a> {
    pub logging: LoggingConfig<'a>,
    pub lua_funcs: &'a [RegisterFunc],
    pub policy: &'a Path,
}

impl StartConfig<'_> {
    pub async fn run<INIT, FINI>(
        self,
        init_future: INIT,
        shutdown_future: FINI,
    ) -> anyhow::Result<()>
    where
        INIT: Future<Output = anyhow::Result<()>> + Send + 'static,
        FINI: Future<Output = ()> + Send + 'static,
    {
        LazyLock::force(&ONLINE_SINCE);
        self.logging.init()?;

        start_cpu_usage_monitor();

        rustls::crypto::aws_lc_rs::default_provider()
            .install_default()
            .map_err(|_| anyhow::anyhow!("failed to install default crypto provider"))?;

        kumo_server_memory::setup_memory_limit().context("setup_memory_limit")?;

        prometheus::register(Box::new(
            tokio_metrics_collector::default_runtime_collector(),
        ))
        .context("failed to configure tokio-metrics-collector")?;

        for &func in self.lua_funcs {
            config::register(func);
        }

        config::set_policy_path(self.policy.to_path_buf())
            .await
            .with_context(|| format!("Error evaluating policy file {:?}", self.policy))?;

        tokio::spawn(async move {
            let mut info = MachineInfo::new();
            info.node_id.replace(NodeId::get().uuid.to_string());
            info.query_cloud_provider().await;
            *MACHINE_INFO.lock() = Some(info);
        });

        let mut life_cycle = LifeCycle::new();

        let init_handle = rt_spawn("initialize", async move {
            let mut error = None;
            if let Err(err) = init_future.await {
                let err = format!("{err:#}");
                tracing::error!("problem initializing: {err}");
                LifeCycle::request_shutdown(Ok(())).await;
                error.replace(err);
            }
            // This log line is depended upon by the integration
            // test harness. Do not change or remove it without
            // making appropriate adjustments over there!
            tracing::info!("initialization complete");
            error
        })?;

        let final_result = life_cycle.wait_for_shutdown().await;

        // after waiting for those to idle out, shut down logging
        shutdown_future.await;

        tracing::info!("Shutdown completed OK!");

        if let Some(error) = init_handle.await? {
            anyhow::bail!("Initialization raised an error: {error}");
        }
        if let Some(Err(error)) = final_result {
            anyhow::bail!("Shutdown due to error: {error}");
        }
        Ok(())
    }
}
```

--------------------------------

### get example

Source: https://docs.kumomta.com/rustapi/mailparsing/rfc5322_parser/struct.AddressList.html

Shows get with both index and range arguments, returning Option. Returns None for out-of-bounds positions or ranges.

```rust
let v = [10, 40, 30];
assert_eq!(Some(&40), v.get(1));
assert_eq!(Some(&[10, 40][..]), v.get(0..2));
assert_eq!(None, v.get(3));
assert_eq!(None, v.get(0..4));
```

--------------------------------

### Example: writing JSONL records with kumo.jsonl.new_writer

Source: https://docs.kumomta.com/reference/kumo.jsonl/new_writer

Complete example showing how to create a writer, write two records, and close it. The writer is configured with a log directory, max file size, max segment duration, compression level, and suffix.

```lua
local kumo = require 'kumo'

local writer = kumo.jsonl.new_writer {
  log_dir = '/var/log/kumomta/json',
  max_file_size = 268435456, -- 256 MiB
  max_segment_duration = '1h',
  compression_level = 3,
  suffix = '.zst',
}

writer:write_record { event = 'Delivery', id = 'abc123' }
writer:write_record { event = 'Bounce', id = 'def456' }
writer:close()

```

--------------------------------

### kumo.string.starts_with example

Source: https://docs.kumomta.com/reference/string/starts_with

Example call to kumo.string.starts_with with the string 'hello world' and prefix 'hello'. Returns true because the string starts with the prefix.

```lua
kumo.string.starts_with('hello world', 'hello')

```

--------------------------------

### Example output of kumo.format_egress_path_config_constraints

Source: https://docs.kumomta.com/reference/kumo/format_egress_path_config_constraints?q=

Example output showing the formatted ceilings block, identical to the 'ceilings:' block of kcli inspect-ready-q. It lists concurrent dispatchers, message rate, and connection rate with their sources and any declared limits.

```text
ceilings:
  concurrent dispatchers: 32
    source: connection_limit
  message rate:           10 × 10/s = 100/s
    source: max_deliveries_per_connection × max_connection_rate
    declared: max_message_rate = 1000/s ← effectively unreachable
  connection rate:        10/s
    source: max_connection_rate

```

--------------------------------

### Get URL path

Source: https://docs.kumomta.com/rustapi/kumo_api_client/struct.Url.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Shows how to get the percent-encoded path of a URL. The path starts with '/' for hierarchical URLs and is percent-encoded for non-ASCII characters.

```rust
use url::{Url, ParseError};

let url = Url::parse("https://example.com/api/versions?page=2")?;
assert_eq!(url.path(), "/api/versions");

let url = Url::parse("https://example.com")?;
assert_eq!(url.path(), "/");

let url = Url::parse("https://example.com/countries/việt nam")?;
assert_eq!(url.path(), "/countries/vi%E1%BB%87t%20nam");
```

--------------------------------

### str::get subslice example

Source: https://docs.kumomta.com/rustapi/kumo_prometheus/parser/struct.InternString.html

Use this example to safely get a subslice of a string. Returns `None` if the indices are not on UTF-8 boundaries or are out of bounds.

```rust
let v = String::from("🗻∈🌏");

assert_eq!(Some("🗻"), v.get(0..4));

// indices not on UTF-8 sequence boundaries
assert!(v.get(1..).is_none());
assert!(v.get(..8).is_none());

// out of bounds
assert!(v.get(..42).is_none());
```

--------------------------------

### Show proxy-server help

Source: https://docs.kumomta.com/userguide/operation/command-line-index

Displays usage instructions for the KumoProxy SOCKS5 proxy server.

```bash
/opt/kumomta/sbin/proxy-server --help
```

--------------------------------

### Start KumoMTA with systemd

Source: https://docs.kumomta.com/userguide/installation/linux?q=

Start the KumoMTA service using systemd.

```bash
$ sudo systemctl start kumomta

```

--------------------------------

### Usage example

Source: https://docs.kumomta.com/reference/kumo.http/build_url?q=

Example of calling kumo.http.build_url with a base URL and a table of parameters, and asserting the resulting URL.

```lua
local url = kumo.http.build_url('https://example.com/?existing=value', {
  a = 1,
  b = 2,
})
assert(url == 'https://example.com/?existing=value&a=1&b=2')
```

--------------------------------

### kumo.string.starts_with signature and example

Source: https://docs.kumomta.com/reference/string/starts_with?q=

The first block shows the function signature. The second block is a usage example that returns true because 'hello world' starts with 'hello'.

```lua
kumo.string.starts_with(STRING, PREFIX)

```

```lua
kumo.string.starts_with('hello world', 'hello')

```

--------------------------------

### proxy.start_http_listener syntax

Source: https://docs.kumomta.com/reference/proxy/start_http_listener?q=

Shows the required syntax for the proxy.start_http_listener function, which configures and starts an HTTP service for the proxy server. This function is only available to the proxy-server executable and should be called only from inside the proxy_init event handler.

```lua
proxy.start_http_listener { PARAMS }

```

--------------------------------

### str::get_unchecked example

Source: https://docs.kumomta.com/rustapi/kumo_prometheus/parser/struct.InternString.html

Use this example to get an unchecked subslice of a string. It is unsafe and requires indices within bounds and on UTF-8 boundaries to avoid invalid memory.

```rust
let v = "🗻∈🌏";
unsafe {
    assert_eq!("🗻", v.get_unchecked(0..4));
    assert_eq!("∈", v.get_unchecked(4..7));
    assert_eq!("🌏", v.get_unchecked(7..11));
}
```

--------------------------------

### Example: Name::prepend_label()

Source: https://docs.kumomta.com/rustapi/dns_resolver/struct.Name.html?search=std%3A%3Avec

Prepends a label to the beginning of a name. The example prepends "www" to "example.com" to get "www.example.com".

```rust
use std::str::FromStr;
use hickory_proto::rr::domain::Name;

let name = Name::from_str("example.com").unwrap();
let name = name.prepend_label("www").unwrap();
assert_eq!(name, Name::from_str("www.example.com").unwrap());
```

--------------------------------

### kumo.jsonl.new_multi_tailer usage example

Source: https://docs.kumomta.com/rustapi/src/kumo_jsonl/lua.rs.html?search=

Shows how to create a multi-consumer tailer that filters records by type and processes batches. The example demonstrates configuring consumers with filters and checkpoints, then iterating over batches and committing them.

```lua
local tailer <close> = kumo.jsonl.new_multi_tailer {
  directory = '/var/log/kumomta',
  consumers = {
    { name = 'deliveries', checkpoint_name = 'cp-del',
      filter = function(record) return record.type == 'Delivery' end },
    { name = 'bounces', checkpoint_name = 'cp-bounce',
      filter = function(record) return record.type == 'Bounce' end },
  },
}

for batches in tailer:batches() do
  for _, batch in ipairs(batches) do
    print(batch:consumer_name())
    for record in batch:iter_records() do ... end
    batch:commit()
  end
end
```

--------------------------------

### Example: creating and invoking a script

Source: https://docs.kumomta.com/rustapi/mod_redis/struct.Script.html

Shows how to create a Script with a Lua expression, add arguments, and invoke it synchronously. The result is expected to be Ok(3).

```rust
let script = redis::Script::new(r"
    return tonumber(ARGV[1]) + tonumber(ARGV[2]);
");
let result = script.arg(1).arg(2).invoke(&mut con);
assert_eq!(result, Ok(3));
```

--------------------------------

### Example: Name::append_label()

Source: https://docs.kumomta.com/rustapi/dns_resolver/struct.Name.html?search=std%3A%3Avec

Appends a label to the end of a name. The example appends "com" to "www.example" to get "www.example.com".

```rust
use std::str::FromStr;
use hickory_proto::rr::domain::Name;

let name = Name::from_str("www.example").unwrap();
let name = name.append_label("com").unwrap();
assert_eq!(name, Name::from_str("www.example.com").unwrap());
```

--------------------------------

### Redis GET and SET example in mod_redis test

Source: https://docs.kumomta.com/rustapi/src/mod_redis/test.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

This snippet shows how to use the redis crate to set a key with a value and then retrieve it using the GET command. It uses the redis::cmd function and the query method on a connection. The example asserts that the retrieved value is a BulkString containing the bytes of the string '42'.

```rust
cmd.arg("my_key").arg(42);
connection.query(cmd).await?;

let mut cmd = redis::cmd("GET");
cmd.arg("my_key");
let value = connection.query(cmd).await?;

assert_eq!(value, redis::Value::BulkString(b"42".to_vec()));

Ok(())
}
```

--------------------------------

### Start KumoMTA with KUMOD_LOG for feedback

Source: https://docs.kumomta.com/tutorial/starting_kumomta

Start KumoMTA manually with immediate feedback by setting KUMOD_LOG=kumod=info (or debug for more detail). If all goes well, it returns a PID and drops you back to a Linux prompt.

```bash
sudo KUMOD_LOG=kumod=info /opt/kumomta/sbin/kumod --policy /opt/kumomta/etc/policy/init.lua --user kumod&

```

--------------------------------

### split_off_mut from third element

Source: https://docs.kumomta.com/rustapi/mailparsing/rfc5322_parser/struct.AddressList.html

Example for split_off_mut removing a slice starting with the third element.

```rust
let mut slice: &mut [_] = &mut ['a', 'b', 'c', 'd'];
let mut tail = slice.split_off_mut(2..).unwrap();

assert_eq!(slice, &mut ['a', 'b']);
assert_eq!(tail, &mut ['c', 'd']);
```

--------------------------------

### split_off from third element

Source: https://docs.kumomta.com/rustapi/mailparsing/rfc5322_parser/struct.AddressList.html

Example for split_off removing a slice starting with the third element.

```rust
let mut slice: &[_] = &['a', 'b', 'c', 'd'];
let mut tail = slice.split_off(2..).unwrap();

assert_eq!(slice, &['a', 'b']);
assert_eq!(tail, &['c', 'd']);
```

--------------------------------

### Configure source_selection_rate with shaping.toml and queue.toml

Source: https://docs.kumomta.com/reference/kumo/make_egress_path/source_selection_rate?q=

These two configuration files work together to apply a selection rate limit to the 'new' source in the 'mypool' pool for messages destined to example.com. The shaping.toml sets source_selection_rate to 100/day with max_burst=1, and the queue.toml assigns the egress pool 'mypool' to the example.com queue.

```toml
["example.com".sources."new"]
# You will probably want to set max_burst for this sort of throttle,
# to avoid clumping all the sends together at the start of the day
source_selection_rate = "100/day,max_burst=1"
```

```toml
[queue.'example.com']
egress_pool = 'mypool'
```

--------------------------------

### Example: equivalent to batch_handling=BatchByDomain

Source: https://docs.kumomta.com/reference/events/smtp_server_split_transaction

Example handler that groups recipients with exactly the same domain portion, equivalent to batch_handling=BatchByDomain.

```lua
kumo.on('smtp_server_split_transaction', function(message, conn_meta)
  local by_domain = {}
  for _, recip in ipairs(message:recipient_list()) do
    local domain = recip.domain:lower()
    if not by_domain[domain] then
      by_domain[domain] = {}
    end
    table.insert(by_domain[domain], recip)
  end
  return by_domain
end)

```

--------------------------------

### len() example

Source: https://docs.kumomta.com/rustapi/mailparsing/rfc5322_parser/struct.AddressList.html

Shows how to use the `len` method on a slice to get the number of elements.

```rust
let a = [1, 2, 3];
assert_eq!(a.len(), 3);
```

--------------------------------

### Update packages and install tools

Source: https://docs.kumomta.com/tutorial/system_preparation

Update the system and install basic tools (wget, bind, bind-utils, telnet, firewalld) on Rocky 9. Also starts and enables the named service.

```bash
# Do basic updates
sudo dnf clean all
sudo dnf update -y

# Grab some handy tools
sudo dnf install -y wget bind bind-utils telnet firewalld

sudo systemctl start named
sudo systemctl enable named

```

--------------------------------

### pub fn start_monitor()

Source: https://docs.kumomta.com/rustapi/config/epoch/fn.start_monitor.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

The start_monitor function is a public function that takes no parameters and returns nothing. It is part of the config::epoch module.

```APIDOC
## Function start_monitor

### Description
The `start_monitor` function is a public function that takes no parameters and returns nothing. It is part of the `config::epoch` module.

### Signature
```rust
pub fn start_monitor()
```

### Parameters
None

### Return Value
None

```

--------------------------------

### as_rchunks_mut example

Source: https://docs.kumomta.com/rustapi/mailparsing/rfc5322_parser/struct.AddressList.html

Splits a mutable slice into N-element chunks starting from the end, with a remainder slice of length less than N. The example modifies the remainder and each chunk, showing the resulting slice.

```rust
let v = &mut [0, 0, 0, 0, 0];
let mut count = 1;

let (remainder, chunks) = v.as_rchunks_mut();
remainder[0] = 9;
for chunk in chunks {
    *chunk = [count; 2];
    count += 1;
}
assert_eq!(v, &[9, 1, 1, 2, 2]);
```

--------------------------------

### listener_domains.toml configuration example

Source: https://docs.kumomta.com/userguide/configuration/domains?q=

Example TOML configuration file for the listener_domains.lua helper. It shows default settings, per-domain overrides, wildcard matching, and per-listener configuration. Note that 'example.com' won't match '*.example.com'.

```toml
["*"]
# You can specify * as a default, overridden by any more explicitly defined domains.
# Since all options are false by default, this would only be needed to default
# An option to true for all domains.
relay_to = false
log_oob = true
log_arf = true

["example.com"]
# allow relaying mail from anyone, so long as it is
# addressed to example.com
relay_to = true

["bounce.example.com"]
# accept and log OOB bounce reports sent to bounce.example.com
log_oob = true

["fbl.example.com"]
# accept and log ARF feedback reports sent to fbl.example.com
log_arf = true

["send.example.com"]
# relay to anywhere, so long as the sender domain is send.example.com
# and the connected peer matches one of the listed CIDR blocks
relay_from = [ '10.0.0.0/24' ]

["auth-send.example.com"]
# relay to anywhere, so long as the sender domain is auth-send.example.com
# and the connected peer has authenticated as any of the authorization identities
# listed below using SMTP AUTH
relay_from_authz = [ 'username1', 'username2' ]

# wildcards are permitted. This will match
# <anything>.example.com that doesn't have
# another non-wildcard entry explicitly
# listed in this set of domains.
# Note that "example.com" won't match
# "*.example.com".
["*.example.com"]
# You can specify multiple options if you wish
log_oob = true
log_arf = true
relay_to = true

# and you can explicitly set options to false to
# essentially exclude an entry from a wildcard
["www.example.com"]
relay_to = false
log_arf = false
log_oob = false

# Define a per-listener configuration
[listener."127.0.0.1:25"."*.example.com"]
log_oob = false

```

--------------------------------

### Configure KumoProxy as a systemd service

Source: https://docs.kumomta.com/userguide/operation/kumo-proxy

Configure KumoProxy as a systemd service. Create the service file at /etc/systemd/system/kumoproxy.service, then create the environment file at /opt/kumomta/etc/kumoproxy.env with your IP and port. After creating both files, run daemon-reload and then start, check status, and enable the service manually once; it will restart automatically on reboot.

```ini
[Unit]
Description=KumoMTA SOCKS5 Proxy service
After=syslog.target network.target

[Service]
Type=simple
Restart=always
EnvironmentFile=-/opt/kumomta/etc/kumoproxy.env
ExecStart=/opt/kumomta/sbin/proxy-server --listen ${PROXY_IP}:${PROXY_PORT}
TimeoutStopSec=10

[Install]
WantedBy=multi-user.target

```

```ini
PROXY_IP="172.31.37.164"
PROXY_PORT="5000"

```

```bash
sudo systemctl start kumoproxy
sudo systemctl status kumoproxy
sudo systemctl enable kumoproxy

```

--------------------------------

### as_chunks_mut example

Source: https://docs.kumomta.com/rustapi/mailparsing/rfc5322_parser/struct.AddressList.html

Splits a mutable slice into N-element chunks starting from the beginning, with a remainder slice of length less than N. The example modifies the remainder and each chunk, showing the resulting slice.

```rust
let v = &mut [0, 0, 0, 0, 0];
let mut count = 1;

let (chunks, remainder) = v.as_chunks_mut();
remainder[0] = 9;
for chunk in chunks {
    *chunk = [count; 2];
    count += 1;
}
assert_eq!(v, &[1, 1, 2, 2, 9]);
```

--------------------------------

### kumo.http.build_url usage example

Source: https://docs.kumomta.com/reference/kumo.http/build_url

Example usage of kumo.http.build_url. It appends the given parameters as GET parameters to the base URL, preserving existing query parameters. The assert verifies the resulting URL.

```lua
local url = kumo.http.build_url('https://example.com/?existing=value', {
  a = 1,
  b = 2,
})
assert(url == 'https://example.com/?existing=value&a=1&b=2')

```

--------------------------------

### start_monitor

Source: https://docs.kumomta.com/rustapi/config/epoch/fn.start_monitor.html?search=

Starts the monitor for the epoch configuration. This function takes no parameters and returns nothing.

```APIDOC
## Function start_monitor

### Description
Starts the monitor for the epoch configuration.

### Signature
```rust
pub fn start_monitor()
```

### Parameters
None

### Returns
None
```

--------------------------------

### Configure listener_domains.toml with TOML and JSON formats

Source: https://docs.kumomta.com/userguide/configuration/domains

Create this file at /opt/kumomta/etc/policy/listener_domains.toml. The TOML and JSON versions are equivalent; the JSON version is shown for reference. Options include relay_to, log_oob, log_arf, relay_from, and relay_from_authz. Wildcards are permitted, but "example.com" won't match "*.example.com".

```toml
["*"]
# You can specify * as a default, overridden by any more explicitly defined domains.
# Since all options are false by default, this would only be needed to default
# An option to true for all domains.
relay_to = false
log_oob = true
log_arf = true

["example.com"]
# allow relaying mail from anyone, so long as it is
# addressed to example.com
relay_to = true

["bounce.example.com"]
# accept and log OOB bounce reports sent to bounce.example.com
log_oob = true

["fbl.example.com"]
# accept and log ARF feedback reports sent to fbl.example.com
log_arf = true

["send.example.com"]
# relay to anywhere, so long as the sender domain is send.example.com
# and the connected peer matches one of the listed CIDR blocks
relay_from = [ '10.0.0.0/24' ]

["auth-send.example.com"]
# relay to anywhere, so long as the sender domain is auth-send.example.com
# and the connected peer has authenticated as any of the authorization identities
# listed below using SMTP AUTH
relay_from_authz = [ 'username1', 'username2' ]

# wildcards are permitted. This will match
# <anything>.example.com that doesn't have
# another non-wildcard entry explicitly
# listed in this set of domains.
# Note that "example.com" won't match
# "*.example.com".
["*.example.com"]
# You can specify multiple options if you wish
log_oob = true
log_arf = true
relay_to = true

# and you can explicitly set options to false to
# essentially exclude an entry from a wildcard
["www.example.com"]
relay_to = false
log_arf = false
log_oob = false

# Define a per-listener configuration
[listener."127.0.0.1:25"."*.example.com"]
log_oob = false

```

```json
{
  "*": {
    // You can specify * as a default, overridden by any more explicitly defined domains.
    // Since all options are false by default, this would only be needed to default
    // An option to true for all domains.
    "relay_to": false,
    "log_oob": true,
    "log_arf": true
  },
  "example.com": {
    // allow relaying mail from anyone, so long as it is
    // addressed to example.com
    "relay_to": true
  },
  "bounce.example.com": {
    // accept and log OOB bounce reports sent to bounce.example.com
    "log_oob": true
  },
  "fbl.example.com": {
    // accept and log ARF feedback reports sent to fbl.example.com
    "log_arf": true
  },
  "send.example.com": {
    // relay to anywhere, so long as the sender domain is send.example.com
    // and the connected peer matches one of the listed CIDR blocks
    "relay_from": [
      "10.0.0.0/24"
    ]
  },
  "auth-send.example.com": {
    // relay to anywhere, so long as the sender domain is auth-send.example.com
    // and the connected peer has authenticated as any of the authorization identities
    // listed below using SMTP AUTH
    "relay_from_authz": [
      "username1",
      "username2"
    ]
  },
  // wildcards are permitted. This will match
  // <anything>.example.com that doesn't have
  // another non-wildcard entry explicitly
  // listed in this set of domains.
  // Note that "example.com" won't match
  // "*.example.com".
  "*.example.com": {
    // You can specify multiple options if you wish
    "log_oob": true,
    "log_arf": true,
    "relay_to": true
  },
  // and you can explicitly set options to false to
  // essentially exclude an entry from a wildcard
  "www.example.com": {
    "relay_to": false,
    "log_arf": false,
    "log_oob": false
  },
  "listener": {
    "127.0.0.1:25": {
      // Define a per-listener configuration
      "*.example.com": {
        "log_oob": false
      }
    }
  }
}

```

--------------------------------

### kumo.fs.open usage example

Source: https://docs.kumomta.com/reference/kumo.fs/open

Example usage of kumo.fs.open. Opens a file for writing, writes a string, seeks to the start, and reads back the content. Requires KumoMTA version 2025.10.06-5ec871ab or newer.

```lua
local kumo = require 'kumo'

local file = kumo.fs.open('/tmp/somefile.txt', 'w')
file:write 'hello there'
file:seek 'set'
assert(file:read() == 'hello there')

```

--------------------------------

### str::trim_start directionality example

Source: https://docs.kumomta.com/rustapi/kumo_prometheus/parser/struct.InternString.html

Directionality example for the `trim_start` method on `str`, showing that it removes leading whitespace from the start of the byte string, which is the left side for left-to-right languages like English.

```rust
let s = "  English  ";
assert!(Some('E') == s.trim_start().chars().next());
```

--------------------------------

### proxy.start_proxy_listener

Source: https://docs.kumomta.com/reference/proxy/start_proxy_listener

Starts a SOCKS5 proxy server with the given parameters. It is only available to the proxy-server executable and should be called from the proxy_init event handler.

```APIDOC
## proxy.start_proxy_listener

### Description
Configure and start a SOCKS5 proxy server. This function is only available to the `proxy-server` executable and should be called only from inside your `proxy_init` event handler.

### Method
Function call

### Endpoint
`proxy.start_proxy_listener { PARAMS }`

### Parameters
#### PARAMS (table)
- **hostname** (string) - Optional - The hostname to bind to.
- **listen** (string) - Required - The address and port to listen on, e.g., `'0.0.0.0:1080'`.
- **require_auth** (boolean) - Optional - If true, require authentication using RFC1929.
- **tcp_keepalive** (boolean) - Optional - Enable TCP keepalive.
- **timeout** (number) - Optional - Timeout in seconds.
- **tls_certificate** (string) - Optional - Path to TLS certificate file.
- **tls_private_key** (string) - Optional - Path to TLS private key file.
- **use_splice** (boolean) - Optional - Enable splice optimization.
- **use_tls** (boolean) - Optional - Enable TLS for the proxy connection.

### Request Example
```lua
kumo.on('proxy_init', function()
  proxy.start_proxy_listener {
    listen = '0.0.0.0:1080',
  }
end)
```

### Response
No return value.

### Notes
- This function is only available to the `proxy-server` executable.
- Should be called only from inside the `proxy_init` event handler.
- The proxy server implements the SOCKS5 protocol and can be used by KumoMTA's egress sources to route outbound connections through the proxy.

```

--------------------------------

### str::match_indices example

Source: https://docs.kumomta.com/rustapi/kumo_prometheus/parser/struct.InternString.html

Example for the `match_indices` method on `str`, which returns an iterator over disjoint matches of a pattern along with the starting index. For overlapping matches, only the first match's index is returned.

```rust
let v: Vec<_> = "abcXXXabcYYYabc".match_indices("abc").collect();
assert_eq!(v, [(0, "abc"), (6, "abc"), (12, "abc")]);

let v: Vec<_> = "1abcabc2".match_indices("abc").collect();
assert_eq!(v, [(1, "abc"), (4, "abc")]);

let v: Vec<_> = "ababa".match_indices("aba").collect();
assert_eq!(v, [(0, "aba")]); // only the first `aba`
```

--------------------------------

### Basic HTTP GET request with kumo.http.build_client

Source: https://docs.kumomta.com/reference/kumo.http/build_client

Creates an HTTP client with default parameters, sends a GET request to https://example.com/, and prints the status code, status reason, headers, and response body. The client maintains a connection pool that can be reused across multiple requests.

```lua
local response = kumo.http.build_client({}):get('https://example.com/'):send()
print(response:status_code(), response:status_reason())
for k, v in pairs(response:headers()) do
  print('Header', k, v)
end
print(response:text())
```

--------------------------------

### Setup listener_domains.lua policy helper

Source: https://docs.kumomta.com/userguide/configuration/domains?q=

Add this to the top level of your server policy script to use the listener_domains.lua policy helper. It registers a get_listener_domain event handler that loads configuration from the specified TOML file.

```lua
local listener_domains = require 'policy-extras.listener_domains'

kumo.on(
  'get_listener_domain',
  listener_domains:setup { '/opt/kumomta/etc/policy/listener_domains.toml' }
)

```
Tokens:
Raw