danvics/selfhostblocks
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1
selfhostblocks/modules/services/mailserver/docs/default.md
ibizaman fe5a577d93 mailserver: update to e33fbde and add test
2026-05-24 01:25:53 +02:00

11 KiB
Raw Blame History

Mailserver Service

Defined in /modules/services/mailserver.nix.

This NixOS module is a service that sets up the NixOS Simple Mailserver project. It integrates the upstream project with the SHB modules like the SSL module, the contract for secrets and the LLDAP module.

It also exposes an XML file which allows some email clients to auto configure themselves.

Setting up a self-hosted email server in this age can be quite time consuming because you need to maintain a good IP hygiene to avoid being marked as spam from the big players. To avoid needing to deal with this, this module provides the means to use an email provider (like Fastmail or ProtonMail) as a mere proxy. If you also setup the email provider using your own custom domain, this combination allows you to change email provider without needing to change your clients or notify your email correspondents and keep a backup of all your emails at the same time. The setup looks like so:

Domain --[ DNS records ]->  Email Provider  --[ mbsync  ]->  SHB Server

Internet <----------------  Email Provider  <-[ postfix ]--  SHB Server

Configuring your domain name to point to your email provider is out of scope here. See the documentation for "custom domain" for you email provider, like for Fastmail and ProtonMail

To use an email provider as a proxy, use the shb.mailserver.imapSync and shb.mailserver.smtpRelay, options.

Usage

The following snippet assumes a few blocks have been setup already:

let
  domain = "example.com";
  username = "me@example.com";
in
{
  imports = [
    selfhostblocks.nixosModules.mailserver
  ];

  shb.mailserver = {
    enable = true;
    inherit domain;
    subdomain = "imap";
    ssl = config.shb.certs.certs.letsencrypt."domain";

    imapSync = {
      syncTimer = "10s";
      accounts.fastmail = {
        host = "imap.fastmail.com";
        port = 993;
        inherit username;
        password.result = config.shb.sops.secret."mailserver/imap/fastmail/password".result;
        mapSpecialJunk = "Spam";
      };
    };

    smtpRelay = {
      host = "smtp.fastmail.com";
      port = 587;
        inherit username;
      password.result = config.shb.sops.secret."mailserver/smtp/fastmail/password".result;
    };

    ldap = {
      enable = true;
      host = "127.0.0.1";
      port = config.shb.lldap.ldapPort;
      dcdomain = config.shb.lldap.dcdomain;
      adminName = "admin";
      adminPassword.result = config.shb.sops.secret."mailserver/ldap_admin_password".result;
      account = "fastmail";
    };
  };

  # Optionally add some mailboxes
  mailserver.mailboxes = {
    Drafts = {
      auto = "subscribe";
      specialUse = "Drafts";
    };
    Junk = {
      auto = "subscribe";
      specialUse = "Junk";
    };
    Sent = {
      auto = "subscribe";
      specialUse = "Sent";
    };
    Trash = {
      auto = "subscribe";
      specialUse = "Trash";
    };
    Archive = {
      auto = "subscribe";
      specialUse = "Archive";
    };
  };

  shb.sops.secret."mailserver/smtp/fastmail/password".request =
    config.shb.mailserver.smtpRelay.password.request;

  shb.sops.secret."mailserver/imap/fastmail/password".request =
    config.shb.mailserver.imapSync.accounts.fastmail.password.request;

  shb.sops.secret."mailserver/ldap_admin_password" = {
    request = config.shb.mailserver.ldap.adminPassword.request;
    # This reuses the admin password set in the shb.lldap module.
    settings.key = "lldap/user_password";
  };
}

With the example above, the mails are stored under /var/vmail/fastmail/<email address>.

Secrets

Secrets can be randomly generated with nix run nixpkgs#openssl -- rand -hex 64.

LDAP

The user LDAP group is created automatically.

Disk Layout

The disk layout has been purposely set to use slashes / for subfolders. By experience, this works better with iOS mail.

Backup

Backing up your emails using the Restic block is done like so:

shb.restic.instances."mailserver" = {
  request = config.shb.mailserver.backup;
  settings = {
    enable = true;
  };
};

The name "mailserver" in the instances can be anything. The config.shb.mailserver.backup option provides what directories to backup. You can define any number of Restic instances to backup your emails multiple times.

You will then need to configure more options like the repository, as explained in the restic documentation.

Certificates

For Let's Encrypt certificates, add:

let
  domain = "example.com";
in
{
  shb.certs.certs.letsencrypt.${domain}.extraDomains = [
    "${config.shb.mailserver.subdomain}.${config.shb.mailserver.domain}"
  ];
}

Impermanence

To save the data folder in an impermanence setup, add:

{
  shb.zfs.datasets."safe/mailserver/index".path = config.shb.mailserver.impermanence.index;
  shb.zfs.datasets."safe/mailserver/mail".path = config.shb.mailserver.impermanence.mail;
  shb.zfs.datasets."safe/mailserver/sieve".path = config.shb.mailserver.impermanence.sieve;
  shb.zfs.datasets."safe/mailserver/dkim".path = config.shb.mailserver.impermanence.dkim;
}

Declarative LDAP

To add a user USERNAME to the user group, add:

shb.lldap.ensureUsers.USERNAME.groups = [
  config.shb.mailserver.ldap.userGroup
];

Application Dashboard

Integration with the dashboard contract is provided by the dashboard option.

For example using the Homepage service:

{
  shb.homepage.servicesGroups.Home.services.Mailserver = {
    sortOrder = 1;
    dashboard.request = config.shb.mailserver.dashboard.request;
  };
}

Debug

Debugging this will be certainly necessary. The first issue you will encounter will probably be with mbsync under the shb.mailserver.imapSync option with the folder name mapping.

Systemd Services

The 3 systemd services setup by this module are:

  • mbsync.service
  • dovecot.service
  • postfix.service

Folders

The 4 folders where state is stored are:

  • config.mailserver.indexDir = /var/lib/dovecot/indices
  • config.mailserver.mailDirectory = /var/vmail
  • config.mailserver.sieveDirectory = /var/sieve
  • config.mailserver.dkimKeyDirectory = /var/dkim

Open Ports

The ports opened by default in this module are:

  • Submissions: 465
  • Imap: 993

You will need to forward those ports on your router if you want to access to your emails from the internet.

The complete list can be found in the upstream repository.

List Email Provider Folder Mapping

Replace $USER and $PASSWORD by those used to connect to your email provider. Yes, you will need to enter verbatim a LOGIN ... and b LIST "" "*".

$ nix run nixpkgs#openssl -- s_client -connect imap.fastmail.com:993 -crlf -quiet
a LOGIN $USER $password
b LIST "" "*"

Example output will be:

* LIST (\HasNoChildren) "/" INBOX
* LIST (\HasNoChildren \Drafts) "/" Drafts
* LIST (\HasNoChildren \Sent) "/" Sent
* LIST (\Noinferiors \HasNoChildren \Junk) "/" Spam

...

Here you can see the special folder \Junk is actually named Spam. To handle this, set the .mapSpecial* options:

{
  shb.mailserver.imapSync.accounts.<account> = {
    mapSpecialJunk = "Spam";
  };
}

List Local Folders

Check the local folders to make sure the mapping is correct and all folders are correctly downloaded. For example, if the mapping above is wrong, you will see both a Junk and Spam folder while if it is correct, you will only see the Junk folder.

$ sudo doveadm mailbox list -u $USER
Junk
Trash
Drafts
Sent
INBOX
MyCustomFolder

The following command shows the number of messages in a folder:

$ sudo doveadm mailbox status -u $USER messages INBOX
INBOX messages=13591

If any folder is not appearing or has 0 message but should have some, it could mean dovecot is not setup correctly and assumes an incorrect folder layout. If that is the case, check the user config with:

$ sudo doveadm user $USER
field   value
uid     5000
gid     5000
home    /var/vmail/fastmail/$USER
mail    maildir:~/mail:LAYOUT=fs
virtualMail

Test Auth

To test authentication to your dovecot instance, run:

$ nix run nixpkgs#openssl -- s_client -connect $SUBDOMAIN.$DOMAIN:993 -crlf -quiet
. LOGIN $USER $PASSWORD

You must here also enter the second line verbatim, replacing your user and password with the real one.

On success, you will see:

. OK [CAPABILITY IMAP4rev1 ...] Logged in

Otherwise, either if the password is wrong or, when using LDAP if the user is not part of the LDAP group, you will see:

. NO [AUTHENTICATIONFAILED] Authentication failed.

To test the postfix instance, run:

$ swaks \
    --server $SUBDOMAIN.$DOMAIN \
    --port 465 \
    --tls-on-connect \
    --auth LOGIN \
    --auth-user $USER \
    --auth-password '$PASSWORD' \
    --from $USER \
    --to $USER

Try once with a wrong password and once with a correct one. The former should log:

<~* 535 5.7.8 Error: authentication failed: (reason unavailable)

Mobile Apps

This module was tested with:

  • the iOS mail mobile app,
  • Thunderbird on NixOS.

The iOS mail app is pretty finicky. If downloading emails does not work, make sure the certificate used includes the whole chain:

$ openssl s_client -connect $SUBDOMAIN.$DOMAIN:993 -showcerts

Normally, the other options are setup correctly but if it fails for you, feel free to open an issue.

Options Reference

id-prefix: services-mailserver-options-
list-id: selfhostblocks-service-mailserver-options
source: @OPTIONS_JSON@