mirror/kumomta
1
0
Fork 0
mirror of https://github.com/mailscope/kumomta.git synced 2026-09-11 13:02:14 +00:00
Code Issues Packages Projects Releases Wiki Activity

bulk updated to user guide

Browse Source
This commit is contained in:
Tom Mairs
2023-03-07 00:11:12 +00:00
parent 30e64c577f
commit 295a33dce3
10 changed files with 241 additions and 86 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/generate-toc.py
+3
View File
@@ -79,6 +79,7 @@ TOC = [
]
),
Page(
"User Guide",
"guide/index.md",
children=[
@@ -89,6 +90,7 @@ TOC = [
),
Page("Installing for Development","guide/subs/install_for_development.md"),
Page("Installing for Production","guide/subs/install_for_production_use.md"),
Page("Your First Email","guide/subs/your_first_email.md"),
Page("Beyond Basics","guide/beyond_basics.md"),
Page("Securing It","guide/securing_it.md",
children=[
@@ -96,6 +98,7 @@ TOC = [
Page("Configuring TLS","guide/subs/tls.md"),
]
),
Page("Advanced Configurations","guide/advanced_config.md",
children=[
Page("Lua Resources","guide/subs/lua_resources.md"),
docs/guide/beyond_basics.md
+14 -3
View File
@@ -1,13 +1,24 @@
# Chapter 2 - Beyond The Basics
Now that you have Kumo MTA installed and sending email, it is time to look at refining teh configuration. Just being able to send a single test email is nice, but if you plan to send any volume of mail, you need ot consider many factors like resillinecy, reporting, and security.
Now that you have Kumo MTA installed and sending email, it is time to look at refining the configuration. Just being able to send a single test email is nice, but if you plan to send any volume of mail, you need to consider many factors like resilliency, reporting, and security.
The samples below are present in the _*simple_policy.lua*_ file included with the default build. You can add to or replace this entirely with your own config. The config is entirely written in Lua which reads like english, but has the power of C.
## Control Access
FIrst lets make sure only authorized people can access your MTA. This is done in the configuration like this:
First let's make sure only authorized systems can access your MTA. For SMTP, this is done in the configuration with relay_hosts:
``` -- override the default set of relay hosts
relay_hosts = { '127.0.0.1', '192.168.1.0/24' },
```
By default only localhost and private networks are able to relay (send) mail. Add the IP address or CIDR block of your injectors here to allow them to relay mail.
For HTTP, this is done with the _*trusted_hosts*_ setting in a litener stanza.
```
sample
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' },
}
```
docs/guide/contributing_to_docs.md
-15
View File
@@ -1,15 +0,0 @@
# Contributing to KumoMTA Documentation
## Preparing your system
We use mdbook for documentation, so contributing edits requires installing mdbook.
Original documentation for mdbook can be found [here](https://rust-lang.github.io/mdBook/index.html)
First follow the instructions under "Installing for Development"
Install mdbook with ```cargo install mdbook```
cd to the book source. IE: ```cd ~/kumomta/docs/kumomta_user_guide/src/```
Create your edits, test and then file a PR with the team.
docs/guide/getting_started.md
+16 -30
View File
@@ -1,42 +1,28 @@
# Getting Started with KumoMTA
## Installing for active development
Deploy a suitable server (instance).
So far this is tested on Rocky 8, ...
## What is this?
Note that in order for KumoMTA to bind to port 25 for outbound mail, it must be run as a privileged user.
The commands below will install as a local user.
KumoMTA is an open source Message Transfer Agent (MTA) designed to provide high performance outbound email functionality. The project was founded by people with decades of experience building and managing extremely high power On-Prem MTAs and is supported by a community of some of the largest senders in the world. While paying attention to the lessons of history, KumoMTA was designed from the ground up with new tech as opposed to modifying something that already existed. We specifically avoided making a modification of Postfix or Exim or some other existing MTA and instead wrote entirely new code in [Rust](https://www.rust-lang.org/).
Install Rust
If you have no idea what an MTA is then [this may be a good primer](https://en.wikipedia.org/wiki/Message_transfer_agent) before you get too deep into the documentation here. If you DO know what an MTA is and you are looking for an open source option to support, then you have found your people.
```curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh```
KumoMTA is deployable as a Docker container if you just want to use it to send mail. Alternately, you can install as a developer/contributor and have full access to the source code of the core MTA. Contributions from the community are welcome.
Install git
### What is a "Kumo"?
So how did we come up with the name **KumoMTA**? We set out to build a cloud deployable on-premises MTA that was flexible enough to install on bare metal and in public cloud. Kumo means cloud in Japanese and we are fans of Japanese culture, so "**KumoMTA**" just kinda made sense at the time :)
```sudo dnf install -y git```
### Why Open Source?
High volume commercial MTAs tend to have closed source code and steep license fees. Neither of these are particularly bad as long as the software is maintained and is flexible enough to modify. However, the kind of people who typically install very complex high volume MTAs, also usually want to modify it or embed it into other systems. Providing an open source option allows people to modify the code if needed, and contribute modifications easily to the community. The email community is full of very smart, creative people who now have an avenue to contribute to a wider community project.
Get the repo
The other reason for open source is accessibility. A user can literally just clone the repo, modify the basic config and be sending email without ever talking to a salesperson or requesting a license. All you need is a little technical skill and a server to deploy on. Usage is governed by an Apache 2.0 license.
```git clone https://github.com/wez/kumomta.git```
Build it
```
cd kumomta
cargo run --release -p kumod -- --policy simple_policy.lua
```
In the above you are telling Cargo to run the Rust compiler to build an optimized release version and package it as kumod, then execute kumod using the policy file called simple_policy.lua.
If you are planning to just "use" KumoMTA and not develop against it, then you are better off using a Docker Image. See above section for more on that.
You can add debugging output by adding KUMOD_LOG=kumod=trace in the environment when you start kumod.
## Run as root after the build
Once you have built the package you can run as root separately like this:
sudo ~/kumomta/target/release/kumod --policy simple_policy.lua
## How do I install it?
That depends.
- If you just want to _use_ it to send email, follow the instructions to [**Install For Production Use**](./subs/install_for_production_use.md).
- If you want to experiment, contrubute, or hack stuff up, follow the instructions to [**Install For Development**](./subs/install_for_development.md).
## What next?
Install the version you need based on your reading above. Modify your config to make it uniquely yours, then test with a small sample of receivers.
Provide feedback to the project as appropriate and let us know if you want to take the next step to active support and advanced features.
docs/guide/subs/_can_delete_installation.md
-1
View File
@@ -1 +0,0 @@
# Installtion
docs/guide/subs/dkim.md
+1 -1
View File
@@ -99,7 +99,7 @@ Configure KumoMTA to sign emails passing through the MTA with DKIM signatures.
domain = msg:sender().domain,
selector = 'default',
headers = { 'From', 'To', 'Subject' },
key = 'example-private-dkim-key.pem',
file_name = 'example-private-dkim-key.pem',
}
Where you want to enable dkim signing, simple call that signer in policy.
docs/guide/subs/environment_consideration.md
+10 -1
View File
@@ -4,13 +4,22 @@
KumoMTA is a performance MTA that will leverage every bit of power you provide. It may be kind of obvious, but 'more is better' so if you plan to send many millions of messages per hour, deploy the largest server you can. If you are installing for development, you will need a minimum of 4Gb RAM, 2 cores and 20Gb Storage. In AWS, a t2.medium is adequate for a minimal install. If you are installing a Docker Image, the same guide applies. See the chart below for sample performance reports.
## Operating Systems
So far this is tested on Rocky 8, ...
So far this is tested on Rocky (8), Alma (8), OpenSuse Leap (15.4), Ubuntu (22), ...
## RAM and Storage
At an absolute minimum, you will need 4Gb RAM and 20Gb Storage. KumoMTA makes heavy use of both resources so more is better, but response time is also going to be a factor. For high performance systems you will want to select storage with the fastest IOPS and lowest latency, so local disk is going to be much better than NAS or SAN. Likewise, you can benefit from faster RAM if it is available.
## Network Interfaces
KumoMTA is capable of processing many millions of message per hour, or more relevant to this conversation, many thousands of bytes per second. Your network interface could be your biggest bottleneck. Below is a quick calculation:
Assuming the average message is 50kB and you plan to send 1 Million of those per hour, your bandwidth requirement will be:
50 * 8000 * 1,000,000 / 3600s =~ 111Mbps
You can see that a 10Mbps Network interface would fail you quickly. Any performance system should use at least a 10Gb NIC.
## Ports and Security
Note that in order for KumoMTA to bind to port 25 for outbound mail, it must be run as a privileged user.
docs/guide/subs/install_for_development.md
+66 -28
View File
@@ -1,19 +1,7 @@
# Installing KumoMTA for Development
## Prepare your environment
Deploy a suitable server (instance). This should have at least 4Gb RAM and 2 cores and 20Gb Storage. In AWS, a t2.medium is adequate for a minimal install.
For performance install, more is better.
So far this is tested on Rocky 8, ...
Note that in order for KumoMTA to bind to port 25 for outbound mail, it must be run as a privileged user.
Note also that if you are deploying to any public cloud, outbound port 25 is probably blocked by default. If this node specificially needs to send mail directly on port 25 to the public internet, you should request access to the port from the cloud provider. Some hints are below.
AWS: https://aws.amazon.com/premiumsupport/knowledge-center/ec2-port-25-throttle/
Azure: https://learn.microsoft.com/en-us/azure/virtual-network/troubleshoot-outbound-smtp-connectivity
GCP: https://cloud.google.com/compute/docs/tutorials/sending-mail
Read the [Environmental considerations](./docs/guide/subs/environment_consideration.md) before proceeding. You will need a suitably sized server with all of the prerequisites in order to be successful.
## Step by Step
@@ -21,21 +9,31 @@ GCP: https://cloud.google.com/compute/docs/tutorials/sending-mail
The commands below will install as a local user.
You can either just execute the installer script (kumoinstall.sh), or follow the steps below manually (same thing).
At a minimum, you will need to install some dev tools and other glue before starting.
```
sudo dnf group install -y "Development Tools"
sudo dnf install -y libxml2 libxml2-devel clang telnet
```
At a minimum, you will need to install some dev tools and other glue before starting.
And you should make sure you have all the latest patches first too.
### In Rocky, CentOS, Alma, and (likely) any other dnf supporting OS
```
sudo dnf clean all
sudo dnf update -y
sudo dnf group install -y "Development Tools"
sudo dnf install -y libxml2 libxml2-devel clang telnet git
```
### In Ubuntu
```
sudo apt-get -y update
sudo apt-get -y upgrade
sudo apt-get install -y build-essential
sudo apt-get install -y cmake make gcc clang llvm telnet git apt-utils
```
### In OpenSuse (Note that SLES does not appear to have an available clang package)
```
sudo zypper refresh
sudo zypper update -y
sudo zypper install -y cmake make gcc clang llvm telnet git gcc-c++
```
Install Rust
## Install Rust
```
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
@@ -44,31 +42,71 @@ source ~/.cargo/env
rustc -V
```
Install git
```sudo dnf install -y git```
Get the repo
## Get the repo and build it
```git clone https://github.com/kumomta/kumomta.git```
Build it
Enter your credentials and wait...
```
cd kumomta
KUMOD_LOG=kumod=trace cargo run -p kumod -- --policy simple_policy.lua
```
In the above you are telling Cargo to run the Rust compiler to build an optimized release version and package it as kumod, then execute kumod using the policy file called simple_policy.lua.
If you are planning to just "use" KumoMTA and not develop against it, then you are better off using a Docker Image. See the next section for more on that.
## Using KumoMTA in a Docker container
To build a lightweight alpine-based docker image:
First ensure docker is actually installed in your server instance.
- In Ubuntu, Debian, and other Debian APT package management systems:
- ```sudo apt install -y docker.io apt-utils```
- In Rocky, Alma, and any other DNF package manager system
- - ``` sudo dnf install -y ```
Then build the docker image from the repo root (~/kumomta)
```sudo ./docker/kumod/build-docker-image.sh```
```
docker image ls kumomta/kumod
REPOSITORY TAG IMAGE ID CREATED SIZE
kumomta/kumod latest bbced15ff4d1 3 minutes ago 116MB
```
You can then run that image; this invocation mounts the kumo
src dir at `/config` and then the `KUMO_POLICY` environment
variable is used to override the default `/config/policy.lua`
path to use the SMTP sink policy script [sink.lua](sink.lua),
which will accept and discard all mail:
```
$ sudo docker run --rm -p 2025:25 \
-v .:/config \
--name kumo-sink \
--env KUMO_POLICY="/config/sink.lua" \
kumomta/kumod
```
If you are planning to just "use" KumoMTA and not develop against it, then you are better off using a prebuilt Docker Image. See the next section for more on that.
You can add debugging output by adding KUMOD_LOG=kumod=trace in the environment when you start kumod.
Then follow the rest above...
## Run as root after the build
Once you have built the package you can run as root separately like this:
sudo ~/kumomta/target/release/kumod --policy simple_policy.lua
## Getting the latest
If you want to always be runniung the latest version, start in the instal directory ( IE: ~/kumomta/ ) then pull and build the latest.
```git pull```
Then ```KUMOD_LOG=kumod=trace cargo run -p kumod -- --policy simple_policy.lua```
docs/guide/subs/install_for_production_use.md
+76 -7
View File
@@ -1,15 +1,84 @@
# Installing KumoMTA for Production Use
FIXME
If you plan to use KumoMTA for production use without modification, you can install a docker image and "just run it".
## Using a Docker container for commercial mailing
Download a Docker container as described in the docs.
Deploy as a standalone or in K8
To build a lightweight alpine-based docker image:
- Prepare your system with the needed essentials
- Ensure docker is actually installed in your server instance.
## Run as root after the build
- In Ubuntu, Debian, and other Debial APT package management systems:
```
sudo apt update
sudo apt install -y apt-utils docker.io
sudo snap install docker
```
Once you have built the package you can run as root separately like this:
sudo ~/kumomta/target/release/kumod --policy simple_policy.lua
- In Rocky, Alma, and any other DNF package manager system
```
sudo dnf config-manager --add-repo=https://download.docker.com/linux/centos/docker-ce.repo
sudo dnf update -y
sudo dnf install -y docker-ce docker-ce-cli containerd.io
sudo systemctl enable docker
```
If you get an error that "/etc/rc.d/rc.local is not marked executable" then make it executable with ```sudo chmod +x /etc/rc.d/rc.local```
### Start Docker with the command below.
```sudo systemctl start docker```
### Check if Docker is running by typing:
```systemctl status docker```
### Enable Non-Root User Access
After completing Step 3, you can use Docker by prepending each command with sudo. To eliminate the need for administrative access authorization, set up a non-root user access by following the steps below.
1. Use the usermod command to add the user to the docker system group.
```sudo usermod -aG docker $USER```
2. Confirm the user is a member of the docker group by typing:
```id $USER```
It is a good idea to restart to make sure it is all set correctly (init 6)
### Then build the docker image
At the time of this writing, the Docker image needs to be built from the project repo. You will need to clone the repo and then build the image from ./docker.
```
sudo dnf install -y git
git clone https://github.com/kumomta/kumomta.git
```
Then
```
cd kumomta
sudo ./docker/kumod/build-docker-image.sh
```
This should result in something roughly like this:
```
docker image ls kumomta/kumod
REPOSITORY TAG IMAGE ID CREATED SIZE
kumomta/kumod latest bbced15ff4d1 3 minutes ago 116MB
```
You can then run that image; this invocation mounts the kumo
src dir at `/config` and then the `KUMO_POLICY` environment
variable is used to override the default `/config/policy.lua`
path to use the SMTP sink policy script [sink.lua](sink.lua),
which will accept and discard all mail:
```
$ sudo docker run --rm -p 2025:25 \
-v .:/config \
--name kumo-sink \
--env KUMO_POLICY="/config/sink.lua" \
kumomta/kumod
```
docs/guide/subs/your_first_email.md
+55
View File
@@ -0,0 +1,55 @@
# Your First Email
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 in the System Preparation section.
Note that the default SMTP listener is on port 2025, so we have use that in these examples.
## Telnet method for SMTP
Start a telnet session with ```telnet localhost 2025```
Then replace youremail@address.com with your actual email address.
Copy the entire thing and paste it into the telnet session in your console.
```
ehlo moto
mail from:youremail@address.com
rcpt to:youremail@address.com
DATA
from:youremail@address.com
to:youremail@address.com
subject: My First Email
Hey, this is my first email!
.
```
## Curl method for HTTP API
curl 'http://127.0.0.1:8000/api/inject/v1'
{
"envelope_sender": "noreply@example.com",
"content": "Subject: hello\n\nHello there",
"recipients": [
{
"email": "recipient@example.com",
}
]
}
## Using SwAKS for testing
SwAKS, the [Swiss Army Knife for SMTP](http://www.jetmore.org/john/code/swaks/) by John Jetmore is a fantastic tool for testing.
- Click the link above for more detail on how to use SwAKS
- As of this writing, you can pull and install the package with
```
curl -O https://jetmore.org/john/code/swaks/files/swaks-20201014.0.tar.gz
tar -xvzf swaks-20201014.0.tar.gz
chmod 755 ./swaks-20201014.0/swaks
```
You can test a relay through KumoMTA with this (change user@example.com to your own email address first)
```
swaks --to user@example.com --server 127.0.0.1 --port 2025
```