Skip to content

Quickstart Tutorial

This adbridged set of instructions assumes you are an experienced MailOps administrator looking for the basic commands needed for an install. More detailed instructions are in the next section of the tutorial. This tutorial is not intended to be a replacement for reading the full documentation, but rather will show how to install and configure KumoMTA for a specific environment and serve as a basis to your own unique deployment.

This tutorial assumes the reader has a basic understanding of Linux administration, experience installing and managing an MTA, a provisioned physical or virtual machine, and a minimal installer for Rocky Linux 9.

  1. Provision an AWS t2.xlarge (or larger) instance (or any physical or virtual server with at least 4 CPUs, 16Gb RAM, 300Gb Hard Drive).


    The hardware here is for a high-throughput sending environment, but KumoMTA can run on a smaller footprint for low-volume environments. if your sending needs are smaller, you can deploy to a server with 1 CPU, 2GB RAM, and 10Gb of storage.

  2. Install Rocky Linux 9. A minimal install is sufficient.

  3. Update the OS and disable Postfix if needed

    sudo dnf clean all
    sudo dnf update -y
    sudo systemctl stop postfix.service
    sudo systemctl disable postfix.service
  4. Add the KumoMTA repo to your config manager and yum install it like this:

    sudo dnf -y install dnf-plugins-core
    sudo dnf config-manager \
        --add-repo \
    sudo yum install kumomta


    Alternatively you can install the kumomta-dev package in order to take advantage of the latest pre-release features. This is only recommended for testing environments.

  5. The instructions above will place a default configuration file at /opt/kumomta/etc/policy/init.lua and start the KumoMTA service, if the service does not start by default it can be started and enabled with the following commands:

    sudo systemctl start kumomta
    sudo systemctl enable kumomta

    Alternately you can run it manually with :

    sudo /opt/kumomta/sbin/kumod --policy \
      /opt/kumomta/etc/policy/init.lua --user kumod&

    KumoMTA will now be installed and running the init.lua configuration from /opt/kumomta/sbin/kumod. If you started it manually, the & pushes the running process to the background, type 'fg' to bring it forward again.

  6. Test your KumoMTA configuration using telnet or the tool of your choice:

    telnet localhost 25
    Trying ::1...
    telnet: connect to address ::1: Connection refused
    Connected to localhost.
    Escape character is '^]'.
    220 localhost.localdomain KumoMTA
    ehlo moto
    250-localhost.localdomain Aloha moto
    250 STARTTLS
    250 OK EnvelopeAddress("")
    250 OK EnvelopeAddress("")
    354 Send body; end with CRLF.CRLF
    Subject: Test Message Using KumoMTA
    This is a test.
    250 OK ids=d7ef132b5d7711eea8c8000c29c33806
    221 So long, and thanks for all the fish!
  7. View the log entries related to your test message:

    $ sudo /opt/kumomta/sbin/tailer --tail /var/log/kumomta
      "type": "Reception",
      "id": "d7ef132b5d7711eea8c8000c29c33806",
      "sender": "",
      "recipient": "",
      "queue": "",
      "site": "",
      "size": 320,
      "response": {
        "code": 250,
        "enhanced_code": null,
        "content": "",
        "command": null
      "peer_address": {
        "name": "moto",
        "addr": ""
      "timestamp": 1695847980,
      "created": 1695847980,
      "num_attempts": 0,
      "bounce_classification": "Uncategorized",
      "egress_pool": null,
      "egress_source": null,
      "feedback_report": null,
      "meta": {},
      "headers": {},
      "delivery_protocol": null,
      "reception_protocol": "ESMTP",
      "nodeid": "d8e014c7-eaeb-4683-a56e-61324e91b1fc"


    In the default configuration, it will take about 10 seconds for the log files to flush and show the log entries in the tailer output. You can speed that up by changing the max_segment_duration in the init.lua file, or just by restarting the server via sudo systemctl restart kumomta.

    These example log entries have been formatted for ease of reading in the documentation.

Next Steps

This page described a situation where you already have a fully prepared server/instance and just needed basic install instructions. Read on to look at server selection and sizing, OS preparation, installation, and testing in more detail.