docs: create a readthedocs manual
The goal is to remove the WIKI since modifications can not be submitted via PRs.
This commit is contained in:
Antoine Eiche
lewo
parent
eb70dd1f55
commit
781073b64d
8 changed files with 471 additions and 6 deletions
20
docs/backup-guide.rst
Normal file
20
docs/backup-guide.rst
Normal file
|
|
@ -0,0 +1,20 @@
|
||||||
|
A Complete Backup Guide
|
||||||
|
=======================
|
||||||
|
|
||||||
|
This is really easy. First off you should have a backup of your
|
||||||
|
``configuration.nix`` file where you have the server config (but that is
|
||||||
|
already in a git repository right?)
|
||||||
|
|
||||||
|
Next you need to backup ``/var/vmail`` or whatever you have specified
|
||||||
|
for the option ``mailDirectory``. This is where all the mails reside.
|
||||||
|
Good options are a cron job with ``rsync`` or ``scp``. But really
|
||||||
|
anything works, as it is simply a folder with plenty of files in it. If
|
||||||
|
your backup solution does not preserve the owner of the files don’t
|
||||||
|
forget to ``chown`` them to ``virtualMail:virtualMail`` if you copy them
|
||||||
|
back (or whatever you specified as ``vmailUserName``, and
|
||||||
|
``vmailGoupName``).
|
||||||
|
|
||||||
|
Finally you can (optionally) make a backup of ``/var/dkim`` (or whatever
|
||||||
|
you specified as ``dkimKeyDirectory``). If you should lose those don’t
|
||||||
|
worry, new ones will be created on the fly. But you will need to repeat
|
||||||
|
step ``B)5`` and correct all the ``dkim`` keys.
|
||||||
53
docs/conf.py
Normal file
53
docs/conf.py
Normal file
|
|
@ -0,0 +1,53 @@
|
||||||
|
# Configuration file for the Sphinx documentation builder.
|
||||||
|
#
|
||||||
|
# This file only contains a selection of the most common options. For a full
|
||||||
|
# list see the documentation:
|
||||||
|
# https://www.sphinx-doc.org/en/master/usage/configuration.html
|
||||||
|
|
||||||
|
# -- Path setup --------------------------------------------------------------
|
||||||
|
|
||||||
|
# If extensions (or modules to document with autodoc) are in another directory,
|
||||||
|
# add these directories to sys.path here. If the directory is relative to the
|
||||||
|
# documentation root, use os.path.abspath to make it absolute, like shown here.
|
||||||
|
#
|
||||||
|
# import os
|
||||||
|
# import sys
|
||||||
|
# sys.path.insert(0, os.path.abspath('.'))
|
||||||
|
|
||||||
|
|
||||||
|
# -- Project information -----------------------------------------------------
|
||||||
|
|
||||||
|
project = 'NixOS Mailserver'
|
||||||
|
copyright = '2020, NixOS Mailserver Contributors'
|
||||||
|
author = 'NixOS Mailserver Contributors'
|
||||||
|
|
||||||
|
|
||||||
|
# -- General configuration ---------------------------------------------------
|
||||||
|
|
||||||
|
# Add any Sphinx extension module names here, as strings. They can be
|
||||||
|
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
|
||||||
|
# ones.
|
||||||
|
extensions = [
|
||||||
|
]
|
||||||
|
|
||||||
|
# Add any paths that contain templates here, relative to this directory.
|
||||||
|
templates_path = ['_templates']
|
||||||
|
|
||||||
|
# List of patterns, relative to source directory, that match files and
|
||||||
|
# directories to ignore when looking for source files.
|
||||||
|
# This pattern also affects html_static_path and html_extra_path.
|
||||||
|
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
|
||||||
|
|
||||||
|
master_doc = 'index'
|
||||||
|
|
||||||
|
# -- Options for HTML output -------------------------------------------------
|
||||||
|
|
||||||
|
# The theme to use for HTML and HTML Help pages. See the documentation for
|
||||||
|
# a list of builtin themes.
|
||||||
|
#
|
||||||
|
html_theme = 'sphinx_rtd_theme'
|
||||||
|
|
||||||
|
# Add any paths that contain custom static files (such as style sheets) here,
|
||||||
|
# relative to this directory. They are copied after the builtin static files,
|
||||||
|
# so a file named "default.css" will overwrite the builtin "default.css".
|
||||||
|
html_static_path = ['_static']
|
||||||
50
docs/howto-add-radicale.rst
Normal file
50
docs/howto-add-radicale.rst
Normal file
|
|
@ -0,0 +1,50 @@
|
||||||
|
How to Add Radicale to SNM
|
||||||
|
==========================
|
||||||
|
|
||||||
|
Configuration by @dotlambda
|
||||||
|
|
||||||
|
.. code:: nix
|
||||||
|
|
||||||
|
{ config, pkgs, lib, ... }:
|
||||||
|
|
||||||
|
with lib;
|
||||||
|
|
||||||
|
let
|
||||||
|
mailAccounts = config.mailserver.loginAccounts;
|
||||||
|
htpasswd = pkgs.writeText "radicale.users" (concatStrings
|
||||||
|
(flip mapAttrsToList mailAccounts (mail: user:
|
||||||
|
mail + ":" + user.hashedPassword + "\n"
|
||||||
|
))
|
||||||
|
);
|
||||||
|
|
||||||
|
in {
|
||||||
|
services.radicale = {
|
||||||
|
enable = true;
|
||||||
|
config = ''
|
||||||
|
[auth]
|
||||||
|
type = htpasswd
|
||||||
|
htpasswd_filename = ${htpasswd}
|
||||||
|
htpasswd_encryption = crypt
|
||||||
|
'';
|
||||||
|
};
|
||||||
|
|
||||||
|
services.nginx = {
|
||||||
|
enable = true;
|
||||||
|
virtualHosts = {
|
||||||
|
"cal.example.com" = {
|
||||||
|
forceSSL = true;
|
||||||
|
enableACME = true;
|
||||||
|
locations."/" = {
|
||||||
|
proxyPass = "http://localhost:5232/";
|
||||||
|
extraConfig = ''
|
||||||
|
proxy_set_header X-Script-Name /;
|
||||||
|
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||||
|
proxy_pass_header Authorization;
|
||||||
|
'';
|
||||||
|
};
|
||||||
|
};
|
||||||
|
};
|
||||||
|
};
|
||||||
|
|
||||||
|
networking.firewall.allowedTCPPorts = [ 80 443 ];
|
||||||
|
}
|
||||||
39
docs/howto-develop.rst
Normal file
39
docs/howto-develop.rst
Normal file
|
|
@ -0,0 +1,39 @@
|
||||||
|
How to Develop SNM
|
||||||
|
==================
|
||||||
|
|
||||||
|
Run tests
|
||||||
|
---------
|
||||||
|
|
||||||
|
You can run the testsuite via
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
nix-build tests -A extern.nixpkgs_20_03
|
||||||
|
nix-build tests -A intern.nixpkgs_unstable
|
||||||
|
...
|
||||||
|
|
||||||
|
Nixops
|
||||||
|
------
|
||||||
|
|
||||||
|
You can test the setup via ``nixops``. After installation, do
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
nixops create nixops/single-server.nix nixops/vbox.nix -d mail
|
||||||
|
nixops deploy -d mail
|
||||||
|
nixops info -d mail
|
||||||
|
|
||||||
|
You can then test the server via e.g. \ ``telnet``. To log into it, use
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
nixops ssh -d mail mailserver
|
||||||
|
|
||||||
|
Imap
|
||||||
|
----
|
||||||
|
|
||||||
|
To test imap manually use
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
openssl s_client -host mail.example.com -port 143 -starttls imap
|
||||||
27
docs/index.rst
Normal file
27
docs/index.rst
Normal file
|
|
@ -0,0 +1,27 @@
|
||||||
|
.. NixOS Mailserver documentation master file, created by
|
||||||
|
sphinx-quickstart on Thu Jul 2 20:50:36 2020.
|
||||||
|
You can adapt this file completely to your liking, but it should at least
|
||||||
|
contain the root `toctree` directive.
|
||||||
|
|
||||||
|
Welcome to NixOS Mailserver's documentation!
|
||||||
|
============================================
|
||||||
|
|
||||||
|
.. image:: ../logo/logo.png
|
||||||
|
:width: 400
|
||||||
|
:alt: SNM Logo
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:maxdepth: 2
|
||||||
|
|
||||||
|
quick-start
|
||||||
|
setup-guide
|
||||||
|
howto-develop
|
||||||
|
backup-guide
|
||||||
|
howto-add-radicale
|
||||||
|
|
||||||
|
Indices and tables
|
||||||
|
==================
|
||||||
|
|
||||||
|
* :ref:`genindex`
|
||||||
|
* :ref:`modindex`
|
||||||
|
* :ref:`search`
|
||||||
32
docs/quick-start.rst
Normal file
32
docs/quick-start.rst
Normal file
|
|
@ -0,0 +1,32 @@
|
||||||
|
Quick Start
|
||||||
|
===========
|
||||||
|
|
||||||
|
.. code:: nix
|
||||||
|
|
||||||
|
{ config, pkgs, ... }:
|
||||||
|
{
|
||||||
|
imports = [
|
||||||
|
(builtins.fetchTarball {
|
||||||
|
url = "https://gitlab.com/simple-nixos-mailserver/nixos-mailserver/-/archive/v2.2.1/nixos-mailserver-v2.2.1.tar.gz";
|
||||||
|
sha256 = "03d49v8qnid9g9rha0wg2z6vic06mhp0b049s3whccn1axvs2zzx";
|
||||||
|
})
|
||||||
|
];
|
||||||
|
|
||||||
|
|
||||||
|
mailserver = {
|
||||||
|
enable = true;
|
||||||
|
fqdn = "mail.example.com";
|
||||||
|
domains = [ "example.com" "example2.com" ];
|
||||||
|
loginAccounts = {
|
||||||
|
"user1@example.com" = {
|
||||||
|
hashedPassword = "$6$/z4n8AQl6K$kiOkBTWlZfBd7PvF5GsJ8PmPgdZsFGN1jPGZufxxr60PoR0oUsrvzm2oQiflyz5ir9fFJ.d/zKm/NgLXNUsNX/";
|
||||||
|
|
||||||
|
aliases = [
|
||||||
|
"info@example.com"
|
||||||
|
"postmaster@example.com"
|
||||||
|
"postmaster@example2.com"
|
||||||
|
];
|
||||||
|
};
|
||||||
|
};
|
||||||
|
};
|
||||||
|
}
|
||||||
242
docs/setup-guide.rst
Normal file
242
docs/setup-guide.rst
Normal file
|
|
@ -0,0 +1,242 @@
|
||||||
|
A Complete Setup Guide
|
||||||
|
======================
|
||||||
|
|
||||||
|
Mail servers can be a tricky thing to set up. This guide is supposed to
|
||||||
|
run you through the most important steps to achieve a 10/10 score on
|
||||||
|
``mail-tester.com``.
|
||||||
|
|
||||||
|
What you need:
|
||||||
|
|
||||||
|
- A server with a public IP (referred to as ``server-IP``)
|
||||||
|
- A Fully Qualified Domain Name (``FQDN``) where your server is
|
||||||
|
reachable, so that other servers can find yours. Common FQDN include
|
||||||
|
``mx.example.com`` (where ``example.com`` is a domain you own) or
|
||||||
|
``mail.example.com``. The domain is referred to as ``server-domain``
|
||||||
|
(``example.com`` in the above example) and the ``FQDN`` is referred
|
||||||
|
to by ``server-FQDN`` (``mx.example.com`` above).
|
||||||
|
- A list of domains you want to your email server to serve. (Note that
|
||||||
|
this does not have to include ``server-domain``, but may of course).
|
||||||
|
These will be referred to as ``domains``. As an example,
|
||||||
|
``domains = [ example1.com, example2.com ]``.
|
||||||
|
|
||||||
|
A) Setup server
|
||||||
|
~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
The following describes a server setup that is fairly complete. Even
|
||||||
|
though there are more possible options (see ``default.nix``), these
|
||||||
|
should be the most common ones.
|
||||||
|
|
||||||
|
.. code:: nix
|
||||||
|
|
||||||
|
{ config, pkgs, ... }:
|
||||||
|
{
|
||||||
|
imports = [
|
||||||
|
(builtins.fetchTarball {
|
||||||
|
# Pick a commit from the branch you are interested in
|
||||||
|
url = "https://gitlab.com/simple-nixos-mailserver/nixos-mailserver/-/archive/A-COMMIT-ID/nixos-mailserver-A-COMMIT-ID.tar.gz";
|
||||||
|
# And set its hash
|
||||||
|
sha256 = "0000000000000000000000000000000000000000000000000000";
|
||||||
|
})
|
||||||
|
];
|
||||||
|
|
||||||
|
|
||||||
|
mailserver = {
|
||||||
|
enable = true;
|
||||||
|
fqdn = <server-FQDN>;
|
||||||
|
domains = [ <domains> ];
|
||||||
|
|
||||||
|
# A list of all login accounts. To create the password hashes, use
|
||||||
|
# mkpasswd -m sha-512 "super secret password"
|
||||||
|
loginAccounts = {
|
||||||
|
"user1@example.com" = {
|
||||||
|
hashedPassword = "$6$/z4n8AQl6K$kiOkBTWlZfBd7PvF5GsJ8PmPgdZsFGN1jPGZufxxr60PoR0oUsrvzm2oQiflyz5ir9fFJ.d/zKm/NgLXNUsNX/";
|
||||||
|
|
||||||
|
aliases = [
|
||||||
|
"postmaster@example.com"
|
||||||
|
"postmaster@example2.com"
|
||||||
|
];
|
||||||
|
|
||||||
|
# Make this user the catchAll address for domains example.com and
|
||||||
|
# example2.com
|
||||||
|
catchAll = [
|
||||||
|
"example.com"
|
||||||
|
"example2.com"
|
||||||
|
];
|
||||||
|
};
|
||||||
|
|
||||||
|
"user2@example.com" = { ... };
|
||||||
|
};
|
||||||
|
|
||||||
|
# Extra virtual aliases. These are email addresses that are forwarded to
|
||||||
|
# loginAccounts addresses.
|
||||||
|
extraVirtualAliases = {
|
||||||
|
# address = forward address;
|
||||||
|
"abuse@example.com" = "user1@example.com";
|
||||||
|
};
|
||||||
|
|
||||||
|
# Use Let's Encrypt certificates. Note that this needs to set up a stripped
|
||||||
|
# down nginx and opens port 80.
|
||||||
|
certificateScheme = 3;
|
||||||
|
|
||||||
|
# Enable IMAP and POP3
|
||||||
|
enableImap = true;
|
||||||
|
enablePop3 = true;
|
||||||
|
enableImapSsl = true;
|
||||||
|
enablePop3Ssl = true;
|
||||||
|
|
||||||
|
# Enable the ManageSieve protocol
|
||||||
|
enableManageSieve = true;
|
||||||
|
|
||||||
|
# whether to scan inbound emails for viruses (note that this requires at least
|
||||||
|
# 1 Gb RAM for the server. Without virus scanning 256 MB RAM should be plenty)
|
||||||
|
virusScanning = false;
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
After a ``nixos-rebuild switch --upgrade`` your server should be good to
|
||||||
|
go. If you want to use ``nixops`` to deploy the server, look in the
|
||||||
|
subfolder ``nixops`` for some inspiration.
|
||||||
|
|
||||||
|
B) Setup everything else
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Step 1: Set DNS entry for server
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
Add a DNS record to the domain ``server-domain`` with the following
|
||||||
|
entries
|
||||||
|
|
||||||
|
================ ===== ==== ======== =============
|
||||||
|
Name (Subdomain) TTL Type Priority Value
|
||||||
|
================ ===== ==== ======== =============
|
||||||
|
``server-FQDN`` 10800 A ``server-IP``
|
||||||
|
================ ===== ==== ======== =============
|
||||||
|
|
||||||
|
This resolves DNS queries for ``server-FQDN`` to ``server-IP``. You can
|
||||||
|
test if your setting is correct by
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
ping <server-FQDN>
|
||||||
|
64 bytes from <server-FQDN> (<server-IP>): icmp_seq=1 ttl=46 time=21.3 ms
|
||||||
|
...
|
||||||
|
|
||||||
|
Note that it can take a while until a DNS entry is propagated.
|
||||||
|
|
||||||
|
Step 2: Set rDNS (reverse DNS) entry for server
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
Wherever you have rented your server, you should be able to set reverse
|
||||||
|
DNS entries for the IP’s you own. Add an entry resolving ``server-IP``
|
||||||
|
to ``server-FQDN``
|
||||||
|
|
||||||
|
You can test if your setting is correct by
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
host <server-IP>
|
||||||
|
<server-IP>.in-addr.arpa domain name pointer <server-FQDN>.
|
||||||
|
|
||||||
|
Note that it can take a while until a DNS entry is propagated.
|
||||||
|
|
||||||
|
Step 3: Set ``MX`` Records
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
For every ``domain`` in ``domains`` do: \* Add a ``MX`` record to the
|
||||||
|
domain ``domain``
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
| Name (Subdomain) | TTL | Type | Priority | Value |
|
||||||
|
| ---------------- | ----- | ---- | -------- | ----------------- |
|
||||||
|
| `domain` | | MX | 10 | `server-FQDN` |
|
||||||
|
|
||||||
|
You can test this via
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
dig -t MX <domain>
|
||||||
|
|
||||||
|
...
|
||||||
|
;; ANSWER SECTION:
|
||||||
|
<domain> 10800 IN MX 10 <server-FQDN>
|
||||||
|
...
|
||||||
|
|
||||||
|
Note that it can take a while until a DNS entry is propagated.
|
||||||
|
|
||||||
|
Step 4: Set ``SPF`` Records
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
For every ``domain`` in ``domains`` do: \* Add a ``SPF`` record to the
|
||||||
|
domain ``domain``
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
| Name (Subdomain) | TTL | Type | Priority | Value |
|
||||||
|
| ---------------- | ----- | ---- | -------- | ----------------- |
|
||||||
|
| `domain` | 10800 | TXT | | `v=spf1 ip4:<server-IP> -all` |
|
||||||
|
|
||||||
|
You can check this with ``dig -t TXT <domain>`` similar to the last
|
||||||
|
section. Note that ``SPF`` records are set as ``TXT`` records since
|
||||||
|
RFC1035.
|
||||||
|
|
||||||
|
Note that it can take a while until a DNS entry is propagated. If you
|
||||||
|
want to use multiple servers for your email handling, don’t forget to
|
||||||
|
add all server IP’s to this list.
|
||||||
|
|
||||||
|
Step 5: Set ``DKIM`` signature
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
In this section we assume that your ``dkimSelector`` is set to ``mail``.
|
||||||
|
If you have a different selector, replace all ``mail``\ ’s below
|
||||||
|
accordingly.
|
||||||
|
|
||||||
|
For every ``domain`` in ``domains`` do: \* Go to your server and
|
||||||
|
navigate to the dkim key directory (by default ``/var/dkim``). There you
|
||||||
|
will find a public key for any domain in the ``domain.txt`` file. It
|
||||||
|
will look like
|
||||||
|
``mail._domainkey IN TXT "v=DKIM1; r=postmaster; g=*; k=rsa; p=<really-long-key>" ; ----- DKIM mail for domain.tld``
|
||||||
|
\* Add a ``DKIM`` record to the domain ``domain``
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
| Name (Subdomain) | TTL | Type | Priority | Value |
|
||||||
|
| ---------------- | ----- | ---- | -------- | ----------------- |
|
||||||
|
| mail._domainkey.`domain` | 10800 | TXT | | `v=DKIM1; p=<really-long-key>` |
|
||||||
|
|
||||||
|
You can check this with ``dig -t TXT mail._domainkey.<domain>`` similar
|
||||||
|
to the last section.
|
||||||
|
|
||||||
|
Note that it can take a while until a DNS entry is propagated.
|
||||||
|
|
||||||
|
Step 6: Set ``DMARC`` record
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
For every ``domain`` in ``domains`` do:
|
||||||
|
|
||||||
|
- Add a ``DMARC`` record to the domain ``domain``
|
||||||
|
|
||||||
|
==================== ===== ==== ======== ====================
|
||||||
|
Name (Subdomain) TTL Type Priority Value
|
||||||
|
==================== ===== ==== ======== ====================
|
||||||
|
\_dmarc.\ ``domain`` 10800 TXT ``v=DMARC1; p=none``
|
||||||
|
==================== ===== ==== ======== ====================
|
||||||
|
|
||||||
|
You can check this with ``dig -t TXT _dmarc.<domain>`` similar to the
|
||||||
|
last section.
|
||||||
|
|
||||||
|
Note that it can take a while until a DNS entry is propagated.
|
||||||
|
|
||||||
|
C) Test your Setup
|
||||||
|
~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Write an email to your aunt (who has been waiting for your reply far too
|
||||||
|
long), and sign up for some of the finest newsletters the Internet has.
|
||||||
|
Maybe you want to sign up for the `SNM Announcement
|
||||||
|
List <https://www.freelists.org/list/snm>`__?
|
||||||
|
|
||||||
|
Besides that, you can send an email to
|
||||||
|
`mail-tester.com <https://www.mail-tester.com/>`__ and see how you
|
||||||
|
score, and let `mxtoolbox.com <http://mxtoolbox.com/>`__ take a look at
|
||||||
|
your setup, but if you followed the steps closely then everything should
|
||||||
|
be awesome!
|
||||||
14
shell.nix
14
shell.nix
|
|
@ -1,9 +1,11 @@
|
||||||
{ nixpkgs ? <nixpkgs>, system ? builtins.currentSystem }:
|
let
|
||||||
|
nixpkgs = (import ./nix/sources.nix).nixpkgs-unstable;
|
||||||
with (import nixpkgs { inherit system; }); stdenv.mkDerivation rec {
|
pkgs = import nixpkgs {};
|
||||||
name = "nixos-mailserver-env";
|
in
|
||||||
env = buildEnv { name = name; paths = buildInputs; };
|
pkgs.mkShell {
|
||||||
buildInputs = with pkgs; [
|
buildInputs = with pkgs; [
|
||||||
jq clamav
|
(python3.withPackages(p: [p.sphinx p.sphinx_rtd_theme]))
|
||||||
|
niv
|
||||||
|
jq clamav
|
||||||
];
|
];
|
||||||
}
|
}
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue