1# Installation & initial configuration23This is the practical guide on how to set up a mail server using maddy for4personal use. It omits most of the technical details for brevity and just gives5you the minimal list of things you need to be aware of and what to do to make6stuff work.78For purposes of clarity, these values are used in this tutorial as examples,9wherever you see them, you need to replace them with your actual values:1011- Domain: example.org12- MX domain (hostname): mx1.example.org13- IPv4 address: 10.2.3.414- IPv6 address: 2001:beef::11516## Getting a server1718Where to get a server to run maddy on is out of the scope of this article. Any19VPS (virtual private server) will work fine for small configurations. However,20there are a few things to keep in mind:2122- Make sure your provider does not block SMTP traffic (25 TCP port). Most VPS23 providers don't do it, but some "cloud" providers (such as Google Cloud) do24 it, so you can't host your mail there.2526- It is recommended to run your own DNS resolver with DNSSEC verification27 enabled.2829## Installing maddy3031Your options are:3233* Pre-built tarball (Linux, amd64)3435 Available on [GitHub](https://github.com/foxcpp/maddy/releases) or36 [maddy.email/builds](https://maddy.email/builds/).3738 The tarball includes maddy executable you can39 copy into /usr/local/bin as well as systemd unit file you can40 use on systemd-based distributions for automatic startup and service41 supervision. You should also create "maddy" user and group.42 See below for more detailed instructions.4344* Docker image (Linux, amd64)4546 ```47 docker pull foxcpp/maddy:0.648 ```4950 See [here](../../docker) for Docker-specific instructions.5152* Building from source5354 See [here](../building-from-source) for instructions.5556* Arch Linux packages5758 For Arch Linux users, `maddy` and `maddy-git` PKGBUILDs are available59 in AUR. Additionally, binary packages are available in 3rd-party60 repository at [https://maddy.email/archlinux/](https://maddy.email/archlinux/)6162## System configuration (systemd-based distribution)6364If you built maddy from source and used `./build.sh install` then65systemd unit files should be already installed. If you used66a pre-built tarball - copy `systemd/*.service` to `/etc/systemd/system`67manually.6869You need to reload service manager configuration to make service available:7071```72systemctl daemon-reload73```7475Additionally, you should create maddy user and group. Unlike most other76Linux mail servers, maddy never runs as root.7778```79useradd -mrU -s /sbin/nologin -d /var/lib/maddy -c "maddy mail server" maddy80```8182## Host name + domain8384Open /etc/maddy/maddy.conf with vim^W your favorite editor and change85the following lines to match your server name and domain you want to handle86mail for.87If you setup a very small mail server you can use example.org in both fields.88However, to easier a future migration of service, it's recommended to use a89separate DNS entry for that purpose. It's usually mx1.example.org, mx2, etc.90You can of course use another subdomain, for instance: smtp1.example.org.91An email failover server will become possible if you forward mx2.example.org92to another server (as long as you configure it to handle your domain).9394```95$(hostname) = mx1.example.org96$(primary_domain) = example.org97```9899If you want to handle multiple domains, you still need to designate100one as "primary". Add all other domains to the `local_domains` line:101102```103$(local_domains) = $(primary_domain) example.com other.example.com104```105106## TLS certificates107108One thing that can't be automagically configured is TLS certs. If you already109have them somewhere - use them, open /etc/maddy/maddy.conf and put the right110paths in. You need to make sure maddy can read them while running as111unprivileged user (maddy never runs as root, even during start-up), one way to112do so is to use ACLs (replace with your actual paths):113```114$ sudo setfacl -R -m u:maddy:rX /etc/ssl/mx1.example.org.crt /etc/ssl/mx1.example.org.key115```116117maddy reloads TLS certificates from disk once in a minute so it will notice118renewal. It is possible to force reload via `systemctl reload maddy` (or just119`killall -USR2 maddy`).120121### Let's Encrypt and certbot122123If you use certbot to manage your certificates, you can simply symlink124/etc/maddy/certs into /etc/letsencrypt/live. maddy will pick the right125certificate depending on the domain you specified during installation.126127You still need to make keys readable for maddy, though:128```129$ sudo setfacl -R -m u:maddy:rX /etc/letsencrypt/{live,archive}130```131132### ACME.sh133134If you use acme.sh to manage your certificates, you could simply run:135136```137mkdir -p /etc/maddy/certs/mx1.example.org138acme.sh --force --install-cert -d mx1.example.org \139 --key-file /etc/maddy/certs/mx1.example.org/privkey.pem \140 --fullchain-file /etc/maddy/certs/mx1.example.org/fullchain.pem141```142143## First run144145```146systemctl start maddy147```148149The daemon should be running now, except that it is useless because we haven't150configured DNS records.151152## DNS records153154How it is configured depends on your DNS provider (or server, if you run your155own). Here is how your DNS zone should look like:156```157; Basic domain->IP records, you probably already have them.158example.org. A 10.2.3.4159example.org. AAAA 2001:beef::1160161; It says that "server mx1.example.org is handling messages for example.org".162example.org. MX 10 mx1.example.org.163; Of course, mx1 should have A/AAAA entry as well:164mx1.example.org. A 10.2.3.4165mx1.example.org. AAAA 2001:beef::1166167; Use SPF to say that the servers in "MX" above are allowed to send email168; for this domain, and nobody else.169example.org. TXT "v=spf1 mx ~all"170; It is recommended to server SPF record for both domain and MX hostname171mx1.example.org. TXT "v=spf1 a ~all"172173; Opt-in into DMARC with permissive policy and request reports about broken174; messages.175_dmarc.example.org. TXT "v=DMARC1; p=quarantine; ruf=mailto:postmaster@example.org"176177; Mark domain as MTA-STS compatible (see the next section)178; and request reports about failures to be sent to postmaster@example.org179_mta-sts.example.org. TXT "v=STSv1; id=1"180_smtp._tls.example.org. TXT "v=TLSRPTv1;rua=mailto:postmaster@example.org"181```182183And the last one, DKIM key, is a bit tricky. maddy generated a key for you on184the first start-up. You can find it in185/var/lib/maddy/dkim_keys/example.org_default.dns. You need to put it in a TXT186record for `default._domainkey.example.org.` domain, like that:187```188default._domainkey.example.org. TXT "v=DKIM1; k=ed25519; p=nAcUUozPlhc4VPhp7hZl+owES7j7OlEv0laaDEDBAqg="189```190191## MTA-STS and DANE192193By default SMTP is not protected against active attacks. MTA-STS policy tells194compatible senders to always use properly authenticated TLS when talking to195your server, offering a simple-to-deploy way to protect your server against196MitM attacks on port 25.197198Basically, you to create a file with following contents and make it available199at https://mta-sts.example.org/.well-known/mta-sts.txt:200```201version: STSv1202mode: enforce203max_age: 604800204mx: mx1.example.org205```206207**Note**: mx1.example.org in the file is your MX hostname, In a simple configuration,208it will be the same as your hostname example.org.209In a more complex setups, you would have multiple MX servers - add them all once210per line, like that:211212```213mx: mx1.example.org214mx: mx2.example.org215```216217It is also recommended to set a TLSA (DANE) record.218Use https://www.huque.com/bin/gen_tlsa to generate one.219Set port to 25, Transport Protocol to "tcp" and Domain Name to **the MX hostname**.220Example of a valid record:221```222_25._tcp.mx1.example.org. TLSA 3 1 1 7f59d873a70e224b184c95a4eb54caa9621e47d48b4a25d312d83d96e3498238223```224225## User accounts and maddy command226227A mail server is useless without mailboxes, right? Unlike software like postfix228and dovecot, maddy uses "virtual users" by default, meaning it does not care or229know about system users.230231IMAP mailboxes ("accounts") and authentication credentials are kept separate.232233To register user credentials, use `maddy creds create` command.234Like that:235```236$ maddy creds create postmaster@example.org237```238239Note the username is a e-mail address. This is required as username is used to240authorize IMAP and SMTP access (unless you configure custom mappings, not241described here).242243After registering the user credentials, you also need to create a local244storage account:245```246$ maddy imap-acct create postmaster@example.org247```248249Note: to run `maddy` CLI commands, your user should be in the `maddy`250group. Alternatively, just use `sudo -u maddy`.251252That is it. Now you have your first e-mail address. when authenticating using253your e-mail client, do not forget the username is "postmaster@example.org", not254just "postmaster".255256You may find running `maddy creds --help` and `maddy imap-acct --help`257useful to learn about other commands. Note that IMAP accounts and credentials258are managed separately yet usernames should match by default for things to259work.