mirror/kumomta
1
0
Fork 0
mirror of https://github.com/mailscope/kumomta.git synced 2026-08-24 05:08:18 +00:00
Code Issues Packages Projects Releases Wiki Activity

refining tutorial flow

Browse Source
This commit is contained in:
Tom Mairs
2023-03-13 06:43:32 +00:00
parent e9c926fee5
commit 2a3df1f2ba
8 changed files with 78 additions and 188 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/generate-toc.py
+2 -2
View File
@@ -89,8 +89,8 @@ TOC = [
),
Page("System Preparation", "tutorial/system_preparation.md"),
Page(
"Installing for Production",
"tutorial/install_for_production_use.md",
"Installing with Docker Containers",
"tutorial/install_with_docker.md",
),
Page(
"Installing for Development",
docs/tutorial/environment_consideration.md
+5 -2
View File
@@ -2,16 +2,17 @@
## Selecting a server or Instance
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.
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. You can deploy in bare metal, public or private cloud, with or without Kubernetes.
## Operating Systems
So far this is tested on Rocky (8,9), Alma (8,9), OpenSuse Leap (15.4), Ubuntu (22), AL2, CentOS7, ...
It has been deployed in AWS, Azure, GCP, VMWare and bare metal.
## 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.
At an absolute minimum, you will need 4Gb RAM and 20Gb Storage. KumoMTA makes heavy use of both resources and response time is 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. 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.
## Network Interfaces
@@ -36,3 +37,5 @@ AWS: [https://aws.amazon.com/premiumsupport/knowledge-center/ec2-port-25-throttl
Azure: [https://learn.microsoft.com/en-us/azure/virtual-network/troubleshoot-outbound-smtp-connectivity](https://learn.microsoft.com/en-us/azure/virtual-network/troubleshoot-outbound-smtp-connectivity)
GCP: [https://cloud.google.com/compute/docs/tutorials/sending-mail](https://cloud.google.com/compute/docs/tutorials/sending-mail)
docs/tutorial/getting_started.md
+11 -5
View File
@@ -4,17 +4,23 @@
KumoMTA is an open source Message Transfer Agent (MTA) designed to provide high performance outbound email functionality.
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.
KumoMTA is deployable from RPM, or as a Docker container or you can build it with Rust crates. If you just want to use it to send mail, you can follow the easy path below. 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.
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 read on.
## How do I install it?
That depends.
Got CentOS7? Do this:
Got Rocky or Alma? Do this:
Got Ubuntu or Debian? Do this:
- If you just want to _use_ it to send email, follow the instructions to [**Install For Production Use**](./install_for_production_use.md).
- If you want to experiment, contrubute, or hack stuff up, follow the instructions to [**Install For Development**](./install_for_development.md).
If you want to explore KumoMTA in Docker containers, potenially orchestrated with Kubernetes, You shoudl follow the instructions [here](./install_with_docker.md).
If you want to experiment, contrubute, or hack stuff up, follow the instructions to [**Install For Development**](./install_for_development.md).
## What's 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.
Read through the environment considerations and system preparation sections to make sure you have a right-sized server, then 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.
docs/tutorial/install_for_development.md
+1 -51
View File
@@ -6,7 +6,7 @@ Read the [Environmental considerations](https://github.com/kumomta/kumomta/blob/
## Step by Step
The commands below will install as a local user.
The commands below assume you have already followed the steps in [System Preparation](./system_preparation.md) and 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.
@@ -22,18 +22,6 @@ sudo dnf install -y libxml2 libxml2-devel clang telnet git
```
### Special case for CentOS7
Note that Red Hat full support for RHEL 7 [ended in August 2019](https://access.redhat.com/support/policy/updates/errata#Retired_Life_Cycle_Dates) and CentOS 7 full support [ended in August 2020](https://wiki.centos.org/About/Product)
This is long and complicated and only relevent if you plan to use Cento7 AND need the full build for development.
If that describes you, then you can follow this to prepage your system, then come back to install Rust and the KumoMTA repo.
[Special Instructions for Centos7](https://github.com/kumomta/kumomta/blob/main/docs/tutorial/special_for_centos7)
If you just want to run it in CentOS7, we built and RPM for you [on this page](https://github.com/kumomta/kumomta/blob/main/docs/tutorial/install_for_production_use.md).
### In Ubuntu
```bash
@@ -77,47 +65,9 @@ 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.
## 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`
```bash
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](https://github.com/kumomta/kumomta/blob/main/sink.lua),
which will accept and discard all mail:
```bash
$ 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
docs/tutorial/install_for_production_use.md → docs/tutorial/install_with_docker.md
+6 -47
View File
@@ -1,10 +1,9 @@
# Installing KumoMTA for Production Use
# Installing KumoMTA in a Docker container
If you plan to use KumoMTA for production use without modification, you can install a docker image and "just run it".
To build a lightweight alpine-based docker image:
- Prepare your system with the needed essentials
- Prepare your system with the needed essentials (see[ System Preparation](./system_preparation.md))
- Ensure docker is actually installed in your server instance.
## APT based systems
@@ -30,50 +29,6 @@ In Rocky, Alma, and any other DNF package manager system
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`
## Special Case for CentOS7
First prepare your system by making sure it has the most current updates, includes wget, and any testing tools you need like telnet and curl.
To run KumoMTA in Centos7, download the prebuilt RPM and policy.
RPM: [https://github.com/kumomta/kumomta/suites/11445755838/artifacts/590348846](https://github.com/kumomta/kumomta/suites/11445755838/artifacts/590348846)
Simple policy: [https://github.com/kumomta/kumomta/blob/main/simple_policy.lua](https://github.com/kumomta/kumomta/blob/main/simple_policy.lua)
Sink policy: [https://github.com/kumomta/kumomta/blob/main/sink.lua](https://github.com/kumomta/kumomta/blob/main/sink.lua)
You should `unzip centos7.zip`
Then install with `rpm -ivh centos7/kumomta-2023.03.08_b3fa0dab-1.centos7.x86_64`
This will install a working copy of KumoMTA at `/usr/bin/kumod`
You can pull a copy of the simple_policy.lua or sink.lua and then run it like:
`/usr/bin/kumod --policy simple_policy.lua`
**OR**
Follow this to do it from the command line:
```bash
# Prepare the system first
sudo yum install -y dnf
sudo dnf clean all
sudo dnf update -y
sudo dnf install -y libxml2 libxml2-devel clang curl telnet git bzip2 wget openssl-devel
# Now install KumoMTA
cd
sudo wget https://github.com/kumomta/kumomta/suites/11445755838/artifacts/590348846
sudo wget https://github.com/kumomta/kumomta/blob/main/simple_policy.lua
sudo wget https://github.com/kumomta/kumomta/blob/main/sink.lua
sudo unzip centos7.zip
rpm -ivh centos7/kumomta-2023.03.08_b3fa0dab-1.centos7.x86_64.rpm
sudo /usr/bin/kumod --policy sink.lua --user $USER
```
CentOS7 users can disregard the rest of this page.
### Start Docker
@@ -128,3 +83,7 @@ $ sudo docker run --rm -p 2025:25 \
--env KUMO_POLICY="/config/sink.lua" \
kumomta/kumod
```
docs/tutorial/special_for_centos7.md
+36 -67
View File
@@ -1,80 +1,49 @@
# Installing KumoMTA in CentOS7
## Special case for development work in CentOS7
Note that Red Hat full support for RHEL 7 [ended in August 2019](https://access.redhat.com/support/policy/updates/errata#Retired_Life_Cycle_Dates) and CentOS 7 full support [ended in August 2020](https://wiki.centos.org/About/Product). While KumoMTA is available for CentOS7, it is also available for almost any other Linux distro and we recommend upgrading to a newer OS as soon as possible.
Note that Red Hat full support for RHEL 7 [ended in August 2019](https://access.redhat.com/support/policy/updates/errata#Retired_Life_Cycle_Dates) and CentOS 7 full support [ended in August 2020](https://wiki.centos.org/About/Product)
...
Also note that in testing, this process took several hours.
First prepare your system by making sure it has the most current updates, includes wget, and any testing tools you need like telnet and curl.
This first starts by adding dnf so all the rest of the install is consistent.
To run KumoMTA in Centos7, download the prebuilt RPM and policy.
Next, You will need to install a few things in order to get this current.
RPM: [https://github.com/kumomta/kumomta/suites/11445755838/artifacts/590348846](https://github.com/kumomta/kumomta/suites/11445755838/artifacts/590348846)
Simple policy: [https://github.com/kumomta/kumomta/blob/main/simple_policy.lua](https://github.com/kumomta/kumomta/blob/main/simple_policy.lua)
Sink policy: [https://github.com/kumomta/kumomta/blob/main/sink.lua](https://github.com/kumomta/kumomta/blob/main/sink.lua)
You should `unzip centos7.zip`
Then install with `rpm -ivh centos7/kumomta-2023.03.08_b3fa0dab-1.centos7.x86_64`
This will install a working copy of KumoMTA at `/usr/bin/kumod`
You can pull a copy of the simple_policy.lua or sink.lua and then run it like:
`/usr/bin/kumod --policy simple_policy.lua`
**OR**
Follow this to do it from the command line:
```bash
# Get dnf installed first
# Prepare the system first
sudo yum install -y dnf
# Now clean up, update and get the basics
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
sudo dnf install -y libxml2 libxml2-devel clang curl telnet git bzip2 wget openssl-devel
# Now for the extra lifting we need to get CentOS7 to a relatively current state
sudo dnf -y install bzip2 wget gcc gcc-c++ gmp-devel mpfr-devel libmpc-devel make openssl-devel
sudo dnf install -y centos-release-scl
sudo dnf install -y llvm-toolset-7 devtoolset-9 devtoolset-9-gcc-c++ python3
# And now we need to make the compiler "current"
# Set us up in the right directory first
sudo -s
export PREFIX="/usr/share"
cd $PREFIX
# Get a newer version of GCC-C++ from source
# This part will take a while so maybe go get lunch... (About 40 minutes)
cd $PREFIX
wget https://ftp.gnu.org/gnu/gcc/gcc-12.2.0/gcc-12.2.0.tar.xz
tar xf gcc-12.2.0.tar.xz
mkdir gcc-12.2.0-build
cd gcc-12.2.0-build
../gcc-12.2.0/configure --enable-languages=c,c++ --disable-multilib --prefix=$PREFIX/gcc/12.2.0
make -j$(nproc)
make install
cd ..
rm -rf gcc-12.2.0 gcc-12.2.0-build gcc-12.2.0.tar.xz
echo "export CC=$PREFIX/gcc/12.2.0/bin/gcc" >> ~/.bashrc
source ~/.bashrc
echo "export CXX=$PREFIX/gcc/12.2.0/bin/g++" >> ~/.bashrc
source ~/.bashrc
echo "export FC=$PREFIX/gcc/12.2.0/bin/gfortran" >> ~/.bashrc
source ~/.bashrc
echo "export PATH=$PREFIX/gcc/12.2.0/bin:$PATH" >> ~/.bashrc
source ~/.bashrc
echo "export LD_LIBRARY_PATH=$PREFIX/gcc/12.2.0/lib64:$LD_LIRBARY_PATH" >> ~/.bashrc
source ~/.bashrc
# Get the latest version of cmake from source (About 20 minutes)
wget https://github.com/Kitware/CMake/releases/download/v3.25.3/cmake-3.25.3.tar.gz
tar zxf cmake-3.25.3.tar.gz
mv cmake-3.25.3.tar.gz /tmp/
cd cmake-3.25.3
./bootstrap && make && sudo make install
ln $PREFIX/cmake-3.25.3/bin/cmake /bin/cmake
mv $PREFIX/cmake-3.25.3 $PREFIX/cmake-3.25
# Get the latest version of llvm (clang) from source
cd $PREFIX
git clone --depth=1 https://github.com/llvm/llvm-project.git
cd llvm-project
cmake -S llvm -B build -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release
# Now install KumoMTA
cd
sudo wget https://github.com/kumomta/kumomta/suites/11445755838/artifacts/590348846
sudo wget https://github.com/kumomta/kumomta/blob/main/simple_policy.lua
sudo wget https://github.com/kumomta/kumomta/blob/main/sink.lua
sudo unzip centos7.zip
rpm -ivh centos7/kumomta-2023.03.08_b3fa0dab-1.centos7.x86_64.rpm
sudo /usr/bin/kumod --policy sink.lua --user $USER
```
You should now be running KumoMTA in CentOS7
docs/tutorial/system_preparation.md
+12 -14
View File
@@ -1,10 +1,5 @@
# System Preparation
## Picking the right server size
Whether you install on bare metal or in a cloud, you will need a minimum of 4Gb RAM, 2 cores and 20Gb Storage. While it may be possible to use a smaller container for the binary only, you will run into issues with the spool after only a few messages. You can read more detail on this sizing in the page covering [KumoMTA Environmental Considerations](https://github.com/kumomta/kumomta/blob/main/docs/guide/subs/environment_consideration.md#kumomta-environmental-considerations)
A good sized instance for testing features would be 4 cores, 16Gb RAM, 100Gb Storage. This is the build used for most of the testing shown in this document outside of the performance chart. In AWS this is an m3.xlarge. In Azure, this is a B4ms. In GCP, this is an e2-standard-4.
## Doing the basics
Reguardless of what system you deploy, there are things you need to do to prepare the OS.
@@ -17,7 +12,7 @@ Reguardless of what system you deploy, there are things you need to do to prepar
### Rocky Linux Example
Rocky Linux is very similar to CentOS, as is Alma and RHEL The instructions below are shown for a Rocky 8 system but with slight modification, should work for any DNF package management system.
Rocky Linux is very similar to CentOS, as is Alma and RHEL The instructions below are shown for a Rocky 8 system but with slight modification, should work for any DNF package management system. For Amazon Linux (AL2) the instructions are identical, but replace "dnf" with "yum".
```bash
# Do basic updates
@@ -33,9 +28,13 @@ sudo systemctl enable chrony
sudo dnf install -y make gcc firewalld sysstat
```
**These next 2 require actually being root so you need to manually set sudo, then run the following commands**
!!! note
The following commands must be executed as the root user
```sudo -s```
```bash
# RUN AS ROOT
sudo -s
```
Then run these:
```
@@ -128,18 +127,14 @@ kernel.shmmni = 4096
## OS Hardening
Above the basics of any system deloyment, you may also want to do some "hardening". This is the process of minimizing exposure to threats. This is not a comprehensive list, but are some of the common things you should do to protect your system.
- Disabling unnecessary services
- postfix
- Disabling unnecessary services like postfix and qpidd
```
sudo systemctl stop postfix.service
sudo systemctl disable postfix.service
```
- qpidd
```
sudo systemctl stop qpidd.service
sudo systemctl disable qpidd.service
```
- Firewall
@@ -155,3 +150,6 @@ Beyond the basics of any system deloyment, you may also want to do some "hardeni
- Firewall
- SSH config
- Switch to keypair only
docs/tutorial/your_first_email.md
+5
View File
@@ -57,3 +57,8 @@ You can test a relay through KumoMTA with this (change user@example.com to your
```bash
swaks --to user@example.com --server 127.0.0.1 --port 2025
```
## Checking the logs
...