mirror of
https://github.com/mailscope/kumomta.git
synced 2026-08-19 02:48:18 +00:00
Tom Mairs
268 lines
8.5 KiB
Markdown
268 lines
8.5 KiB
Markdown
# Building From Source
|
|
|
|
If pre-built binaries are not provided for your system of choice, of if you'd
|
|
like try your hand at extending KumoMTA, you'll need to build it from source.
|
|
|
|
If you are on Ubuntu or Rocky Linux and just want to try KumoMTA, rather than
|
|
build from source we recommend that you follow the instructions in the [Installing on Linux](linux.md) section.
|
|
|
|
## Prepare your environment
|
|
|
|
Read the [Environmental considerations](environment.md) before proceeding. You
|
|
will need a suitably sized server with all of the prerequisites in order to be
|
|
successful.
|
|
|
|
In addition, you will need to install some development packages.
|
|
|
|
## Obtain The Code
|
|
|
|
You will need `git`:
|
|
|
|
=== "RPM based systems"
|
|
```console
|
|
$ sudo dnf install -y git
|
|
```
|
|
|
|
=== "APT based systems"
|
|
```console
|
|
$ sudo apt install -y git curl
|
|
```
|
|
|
|
Then clone the repo:
|
|
|
|
```console
|
|
$ git clone https://github.com/KumoCorp/kumomta.git
|
|
$ cd kumomta
|
|
```
|
|
|
|
## Install Dependencies
|
|
|
|
The `get-deps.sh` script in the repo knows how to install dependencies for
|
|
various systems; you should run it the first time you clone the repo,
|
|
and may need to run it after running a pull to update the repo in the future:
|
|
|
|
```console
|
|
$ ./get-deps.sh
|
|
```
|
|
|
|
!!! note
|
|
`get-deps.sh` will install the various deps, but will complain
|
|
that rust is not installed the first time that you run it.
|
|
You can ignore that error as the very next step is to install
|
|
rust.
|
|
|
|
## Install Rust
|
|
|
|
You will need the Rust compiler to build KumoMTA.
|
|
|
|
We strongly recommend using [rustup](https://rustup.rs/) to install and manage
|
|
your Rust compiler. While some distributions offer a version of the Rust compiler,
|
|
it is often outdated.
|
|
|
|
If you are using a priviledged user, drop back to your non-priviledged user first:
|
|
|
|
```console
|
|
$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
|
|
$ source ~/.cargo/env
|
|
```
|
|
|
|
## Building KumoMTA
|
|
|
|
With all the dependencies available, the actual build process is very simple:
|
|
|
|
```console
|
|
$ cargo build --release
|
|
```
|
|
|
|
This will build everything, leaving the binaries in the `target/release`
|
|
directory in the repo.
|
|
|
|
## Building your own package
|
|
|
|
There are scripts to build out packages in either RPM or DEB format.
|
|
If you're running on such a system, we recommend building and installing from
|
|
a package built by our scripts, as those packages will best encapsulate how
|
|
we intend for KumoMTA to be installed and operated.
|
|
|
|
These scripts will produce a package file that you are then free to install
|
|
either locally or on a target system elsewhere.
|
|
|
|
=== "RPM based systems"
|
|
|
|
```console
|
|
$ assets/build-rpm.sh
|
|
```
|
|
|
|
You can find the generated rpm in a directory maintained by rpmbuild; that is
|
|
usually `~/rpmbuild/RPMS/x86_64`, but some environments use a different
|
|
location, so the example below uses `rpm --eval` to obtain the correct location:
|
|
|
|
```console
|
|
$ rpm --eval '%{_rpmdir}/%{_arch}'
|
|
/home/USER/rpmbuild/RPMS/x86_64
|
|
$ ls $(rpm --eval '%{_rpmdir}/%{_arch}')/kumo*.rpm
|
|
/home/USER/rpmbuild/RPMS/x86_64/kumomta-dev-2023.10.24.112314_f8aaa6f1-1.fedora38.x86_64.rpm
|
|
```
|
|
|
|
You can install it directly if you wish:
|
|
|
|
```console
|
|
$ sudo rpm -Uvh $(ls $(rpm --eval '%{_rpmdir}/%{_arch}')/kumo*.rpm | tail -1)
|
|
```
|
|
|
|
=== "APT based systems"
|
|
|
|
```console
|
|
$ assets/build-deb.sh
|
|
$ ls *.deb
|
|
kumomta-dev.2023.10.24.112314.f8aaa6f1.Ubuntu22.04.deb
|
|
```
|
|
|
|
You can install it directly if you wish:
|
|
|
|
```console
|
|
$ sudo apt-get install -y ./kumomta*.deb
|
|
```
|
|
|
|
## Installing from source
|
|
|
|
If RPM or DEB is not suitable for your environment for some reason, you can install
|
|
the various components "by hand". We recommend installing to `/opt/kumomta` so that
|
|
various product defaults continue to operate as intended.
|
|
|
|
### Pre-req: service account
|
|
|
|
The default service account assumed by the `kumod` process is the `kumod` user.
|
|
|
|
You can create the account manually like this:
|
|
|
|
```console
|
|
$ sudo useradd --system -g kumod -d /var/spool/kumod -s /sbin/nologin \
|
|
-c "Service account for kumomta" kumod
|
|
```
|
|
|
|
### Directory Structure
|
|
|
|
Take care with the ownership and permissions on the various directories,
|
|
in order to avoid deploying with an insecure configuration:
|
|
|
|
```console
|
|
$ sudo install -d --mode 755 --owner kumod --group kumod /opt/kumomta/sbin
|
|
$ sudo install -d --mode 755 --owner kumod --group kumod /opt/kumomta/etc
|
|
$ sudo install -d --mode 755 --owner kumod --group kumod /opt/kumomta/etc/policy
|
|
$ sudo install -d --mode 2770 --owner kumod --group kumod /opt/kumomta/etc/dkim
|
|
$ sudo install -d --mode 2770 --owner kumod --group kumod /var/spool/kumomta
|
|
$ sudo install -d --mode 2770 --owner kumod --group kumod /var/log/kumomta
|
|
```
|
|
|
|
The executables:
|
|
|
|
```console
|
|
$ for bin in validate-shaping tsa-daemon \
|
|
proxy-server kumod kcli traffic-gen tailer ; do
|
|
install -Dsm755 target/release/$bin -t /opt/kumomta/sbin
|
|
done
|
|
```
|
|
|
|
The helpers and other assets:
|
|
|
|
```console
|
|
$ sudo mkdir -p /opt/kumomta/share/bounce_classifier /opt/kumomta/share/policy-extras
|
|
$ sudo install -Dm644 assets/bounce_classifier/* -t /opt/kumomta/share/bounce_classifier
|
|
$ sudo install -Dm644 assets/policy-extras/*.lua -t /opt/kumomta/share/policy-extras
|
|
$ sudo install -Dm644 assets/policy-extras/*.toml -t /opt/kumomta/share/policy-extras
|
|
```
|
|
|
|
The example/starter configuration files can be installed like this; you may wish
|
|
to skip this set and just deploy your own configuration, as discussed in the
|
|
section below:
|
|
|
|
```console
|
|
$ 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
|
|
```
|
|
|
|
### Systemd Service
|
|
|
|
If you wish to use systemd to manage `kumod` and/or `tsa-daemon`, you can find
|
|
the `.service` files in the `assets` directory. Precisely where these files
|
|
are deployed varies a little depending on your distribution, so copyable
|
|
instructions for that are not currently provided here.
|
|
|
|
## Creating the initial config
|
|
|
|
KumoMTA is now installed, but it requires a policy configuration script so it
|
|
knows how to behave. The policy config is written in Lua and should live in
|
|
`/opt/kumomta/etc/policy/init.lua` in order to work with the systemd service
|
|
definition.
|
|
|
|
Both the from-package and from-source instructions above will pre-populate
|
|
that file with the basic configuration that is reproduced below.
|
|
Alternately, there is a more substantial config sample
|
|
[HERE](https://docs.kumomta.com/userguide/configuration/example/), but you must
|
|
save it as `/opt/kumomta/etc/policy/init.lua`.
|
|
|
|
```lua title="/opt/kumomta/etc/policy/init.lua"
|
|
--8<-- "init.lua"
|
|
```
|
|
|
|
## Running kumod
|
|
|
|
If you are not using systemd to manage the service, then you will need to
|
|
use some other way to launch kumod. This section shows how you might launch
|
|
it manually, so that you understand how to automatate/manage this for yourself
|
|
in your chosen environment:
|
|
|
|
```console
|
|
$ sudo /opt/kumomta/sbin/kumod \
|
|
--policy /opt/kumomta/etc/policy/init.lua \
|
|
--user kumod
|
|
```
|
|
|
|
Using `sudo` (or otherwise spawning as root) to launch the process allows
|
|
binding to privileged ports, such as port 25, so that you can accept incoming
|
|
mail on the standard port.
|
|
|
|
When launched with root privileges, `kumod` requires a service account to
|
|
switch to after it has bound privileged ports, in order to avoid running in a
|
|
dangerously insecure mode: you do not want public internet traffic
|
|
connecting directly to a privileged process!
|
|
|
|
The `--policy` argument specifies the path to your `init.lua` configuration.
|
|
|
|
The `--user` argument specifies the name of the service account to use
|
|
instead of running as root.
|
|
|
|
## Running from your source directory
|
|
|
|
!!! note
|
|
This section is intended for people that are developing kumomta
|
|
itself, rather than people that just want to install and use kumomta
|
|
|
|
This command will bring `kumod` up to date (in case you made changes), and then try to launch it:
|
|
|
|
```console
|
|
$ cargo run --release -p kumod -- --policy /opt/kumomta/etc/policy/init.lua
|
|
```
|
|
|
|
You can run as root using port 25, in the foreground, with this:
|
|
|
|
```console
|
|
$ cargo build --release -p kumod && \
|
|
sudo target/release/kumod \
|
|
--policy /opt/kumomta/etc/policy/init.lua \
|
|
--user kumod
|
|
```
|
|
|
|
## Keeping the source up to date
|
|
|
|
To synchronize your repo with the latest changes in the `main` branch:
|
|
|
|
```console
|
|
$ cd kumomta
|
|
$ git pull --rebase
|
|
$ ./get-deps.sh
|
|
$ cargo build --release
|
|
```
|
|
Note that this builds the new files in `target/release/`. If you installed binaries to /opt/kumomta/sbin then you will want to follow the instructions above to [build your own package](source.md/#building-your-own-package) and update the files in `/opt/kumomta/`.
|