Maddy: Difference between revisions

From NixOS Wiki
imported>Onny
Add note about DMARC dns record
Dave (talk | contribs)
m Add alternate way of generating TLSA
 
(67 intermediate revisions by 4 users not shown)
Line 3: Line 3:
== Installation ==
== Installation ==


{{Note|Following example describes the usage of an experimental module which is still being reviewed as an open PR and might not be ready for production.}}
The following example enables the Maddy mail server on localhost, listening on mail delivery SMTP/Submission ports (<code>25,  587</code>) and IMAP port (<code>143</code>) for mail clients to connect to. Mailboxes for the accounts <code>postmaster@example.org</code> and <code>user1@example.org</code> get created if they don't exist yet.


The following example enables the Maddy mail server listening on mail delivery SMTP/Submission ports (<code>25,  587</code>) and IMAP/IMAPS ports (<code>143/993</code>) for mail clients to connect to. The server is configured to send and receive mails for the primary domain <code>example.org</code>.
{{file|/etc/nixos/configuration.nix|nix|<nowiki>
services.maddy = {
  enable = true;
  primaryDomain = "localhost";
  ensureAccounts = [
    "user1@example.org"
    "postmaster@example.org"
  ];
  ensureCredentials = {
    # Do not use this in production. This will make passwords world-readable
    # in the Nix store
    "user1@example.org".passwordFile = "${pkgs.writeText "postmaster" "test"}";
    "postmaster@example.org".passwordFile = "${pkgs.writeText "postmaster" "test"}";
  };
};
</nowiki>}}
 
This local test setup doesn't provide secure TLS connections and should be used only for testing purpose.
 
== Configuration ==
 
=== TLS ===
 
The following example changes the hostname for the mail server to the public domain <code>example.org</code>. TLS certificates are obtained using using the ACME dns-01 challenge. This requires API access to your domain provider. See [https://maddy.email/reference/tls-acme/ upstream documentation] for a list on supported providers and how to configure them.
 
Further the TLS connection is enabled on IMAP port <code>993</code> and Submission port <code>465</code>.


{{file|/etc/nixos/configuration.nix|nix|<nowiki>
{{file|/etc/nixos/configuration.nix|nix|<nowiki>
Line 13: Line 38:
   primaryDomain = "example.org";
   primaryDomain = "example.org";
   tls = {
   tls = {
     certPath = /var/lib/acme/example.org/example.org.crt;
     loader = "acme";
     keyPath = /var/lib/acme/example.org/example.org.key;
     extraConfig = ''
  };
      email put-your-email-here@example.org
  imap = {
      agreed # indicate your agreement with Let's Encrypt ToS
    port = 143;
      host ${config.services.maddy.primaryDomain}
    tlsEnable = true;
      challenge dns-01
     tlsPort = 993;
      dns gandi {
        api_token "{env:GANDI_API_KEY}"
      }
     '';
   };
   };
  # Enable TLS listeners. Configuring this via the module is not yet
  # implemented, see https://github.com/NixOS/nixpkgs/pull/153372
  config = builtins.replaceStrings [
    "imap tcp://0.0.0.0:143"
    "submission tcp://0.0.0.0:587"
  ] [
    "imap tls://0.0.0.0:993 tcp://0.0.0.0:143"
    "submission tls://0.0.0.0:465 tcp://0.0.0.0:587"
  ] options.services.maddy.config.default;
  # Reading secrets from a file. Do not use this example in production
  # since it stores the keys world-readable in the Nix store.
  secrets = [ "${pkgs.writeText "secrets" ''
    GANDI_API_KEY=1234
  ''}" ];
};
};
# Opening ports for additional TLS listeners. This is not yet
# implemented in the module.
networking.firewall.allowedTCPPorts = [ 993 465 ];
</nowiki>}}
</nowiki>}}


TLS certificates can be obtained by using services like [[certbot]] or the [[acme]] service. Please reference their documentation on how to configure it to acquire the certificates.
Alternativley certificates can be manually loaded with setting <code>tls.loader = "file";</code> and manually specifiying key and certificates file paths using the <code>tls.certificates = [];</code> option. In this case, more ACME protocols and providers are available when using the native NixOS [[ACME]] module or manual client tools like [[Certbot]].
 
=== DNS records ===
 
It is possibly easier to configure our own authoritative-only DNS server, which provides important setup information to other mail servers and clients. For details about the meaning of the specific DNS records or manual setup instructions see the [https://maddy.email/tutorials/setting-up/ Maddy setup tutorial].
 
{{file|/etc/nixos/configuration.nix|nix|<nowiki>
services.nsd = {
  enable = true;
  interfaces = [
    "0.0.0.0"
    "::"
  ];
  zones."example.org.".data = let
    domainkey = ''
      v=DKIM1; k=rsa; p=${
        lib.fileContents( /var/lib/maddy/dkim_keys/example.org_default.dns )}'';
    segments = ((lib.stringLength domainkey) / 255);
    domainkeySplitted = map (x: lib.substring (x*255) 255 domainkey) (lib.range 0 segments);
  in ''
    @ SOA ns.example.org noc.example.org 666 7200 3600 1209600 3600
    @ A 1.2.3.4
    @ AAAA abcd::eeff
    @ MX 10 mx1
    mx1 A 1.2.3.4
    mx1 AAAA abcd::eeff
    @ TXT "v=spf1 mx ~all"
    mx1 TXT "v=spf1 mx ~all"
    _dmarc TXT "v=DMARC1; p=quarantine; ruf=mailto:postmaster@example.org
    _mta-sts TXT "v=STSv1; id=1"
    _smtp._tls TXT "v=TLSRPTv1;rua=mailto:postmaster@example.org"
    default._domainkey TXT "${lib.concatStringsSep "\" \"" domainkeySplitted}"
  '';
};
</nowiki>}}


== Configuration ==
Update the IPv4 and IPv6 addresses after <code>A</code> and <code>AAAA</code> to the one which points to the publc IP addresses of your mail server. The last entry is used by the <code>DKIM</code> authentication mechanism which enables recipients to verify the authenticity of mails send by your server. They key is read from the file generated by Maddy on the first startup at <code>/var/lib/maddy/dkim_keys/example.org_default.dns</code> and spitted in segments of 255 chars length to fulfill the DNS record requirements.


=== DNS records ===
Now that your server also runs a DNS daemon besides the mail server, you have to configure it as the external nameserver of your domain <code>example.org</code>. Please consult your domain provider on how to do that.


Ensure that the domain you're going to use has <code>MX</code> DNS records probably configured. They should point to the correct public IP addresses of your server running Maddy.
=== rDNS ===


It is important that the public facing IP of your mail server resolves to the MX domain name. This is something you would normally configure on your server provider site. You can check if it's resolving correctly by running this command
<syntaxhighlight lang="console">
<syntaxhighlight lang="console">
# dig MX example.org
# nix shell nixpkgs#bind --command dig -x 1.2.3.4
[...]
;; ANSWER SECTION:
;; ANSWER SECTION:
example.org. 3364 IN MX 0 mx1.example.org.
1.2.3.4.in-addr.arpa. 6244 IN PTR mx1.example.org.
# dig A mx1.example.org
</syntaxhighlight>
;; ANSWER SECTION:
 
mx1.example.org. 3392 IN A 8.8.8.8
Replace the IP <code>1.2.3.4</code> with the IP of your mail server.
# dig AAAA mx1.example.org
 
;; ANSWER SECTION:
=== MTA-STS ===
mx1.example.org. 3364 IN AAAA 2001:db8:85a3:8d3:1319:8a2e:370:7348
 
MTA-STS enforces secure TLS configuration for servers which support this standard. We already advertised this feature in the DNS records above, but we also have to serve a static configuration file using a web server. We use the web server [[Caddy]] to do this but of course you can other Web Servers too.
 
{{file|/etc/nixos/configuration.nix|nix|<nowiki>
caddy = {
  enable = true;
  virtualHosts."mta-sts.example.org".extraConfig = ''
    encode gzip
    file_server
    root * ${
      pkgs.runCommand "testdir" {} ''
        mkdir -p "$out/.well-known"
        echo "
          version: STSv1
          mode: enforce
          max_age: 604800
          mx: mx1.example.org
        " > "$out/.well-known/mta-sts.txt"
      ''
    }
  '';
}; 
</nowiki>}}
 
Replace the domain <code>mta-sts.example.org</code> and  the domain <code>mx1.example.org</code> with the ones you're using.
 
=== TLSA (DANE) ===
 
Using a TLSA (DANE) record is recommended to bind TLS-certificates to a server. Your nameserver needs DNSSEC support for it. You can generate the key using following command
 
<syntaxhighlight lang="console">
# nix shell nixpkgs#hash-slinger --command tlsa  --create --selector 1 --protocol tcp -p 25 --create mx1.example.org
</syntaxhighlight>
</syntaxhighlight>


Consult your domain provider on how to configure these records.
Or you can generate it directly from the TLS-certificate that you are using with maddy:<syntaxhighlight lang="console">
# openssl x509 -in cert.pem -pubkey -noout | openssl ec -pubin -outform der | sha256sum
</syntaxhighlight>Add the key to a new TLSA record in your nameserver
 
{{file|/etc/nixos/configuration.nix|nix|<nowiki>
services.nsd.zones."example.org.".data = ''
  [...]
  _25._tcp.mx1.example.org. TLSA 3 1 1 7f59d873a70e224b184c95a4eb54caa9621e47d48b4a25d312d83d96e3498238
'';
</nowiki>}}
 
To verify if the record is set correctly
 
<syntaxhighlight lang="console">
# nix shell nixpkgs#dnsutils --command dig _25._tcp.mx1.example.org TLSA +short
3 1 1 7f59d873a70e224b184c95a4eb54caa9621e47d48b4a25d312d83d96 e3498238
</syntaxhighlight>


An other record called <code>SPF</code> should also be present, telling that only servers in the <code>MX</code> are allowed to send mails for this domain
Check if DNSSEC is working correctly for your new TLSA record


<syntaxhighlight lang="console">
<syntaxhighlight lang="console">
# dig TXT example.org
# nix shell nixpkgs#dnsutils --command delv _25._tcp.mx1.example.org TLSA @1.1.1.1
;; ANSWER SECTION:
; fully validated
example.org. 3600 IN TXT "v=spf1 mx ~all"
_25._tcp.mx1.example.org. 10800 IN TLSA 3 1 1 7f59d873a70e224b184c95a4eb54caa9621e47d48b4a25d312d83d96 e3498238
# dig TXT mx1.example.org
_25._tcp.mx1.example.org. 10800 IN RRSIG TLSA 13 5 10800 20230601000000 20230511000000 39688 example.org. He9VYZ35xTC3fNo8GJa6swPrZodSnjjIWPG6Th2YbsOEKTV1E8eGtJ2A +eyBd9jgG+B3cA/jw8EJHmpvy/buCw==
;; ANSWER SECTION:
</syntaxhighlight>
mx1.example.org. 3600 IN TXT "v=spf1 mx ~all"
 
# dig TXT _dmarc.example.org
To verify that the TLSA record matches the TLS certificate of the mail server, issue following openssl command
;; ANSWER SECTION:
 
_dmarc.example.org. 3600 IN TXT "v=DMARC1; p=quarantine; ruf=mailto:postmaster@example.org"
<syntaxhighlight lang="console">
# openssl s_client -connect mx1.example.org:25 -starttls smtp -dane_tlsa_domain mx1.example.org -dane_tlsa_rrdata "3 1 1 7f59d873a70e224b184c95a4eb54caa9621e47d48b4a25d312d83d96"
[...]
Verify return code: 0 (ok)
[...]
</syntaxhighlight>
</syntaxhighlight>


Further, with the last entry, we opt-in into </code>DMARC</code> with permissive policy and request reports about broken messages.
Replace the hostnames and the TLSA hash according to your configuration.


=== Managing users and inboxes ===
=== Users and inboxes ===


Creating credentials and inboxes for a specific account. The first command creates the user <code>postmaster@example.org</code> and will prompt for a password.
Creating credentials and inboxes for a specific account. The first command creates the user <code>postmaster@example.org</code> and will prompt for a password.
Line 69: Line 202:
# maddyctl creds create postmaster@example.org
# maddyctl creds create postmaster@example.org
# maddyctl imap-acct create postmaster@example.org
# maddyctl imap-acct create postmaster@example.org
</syntaxhighlight>
Change password of an existing account
<syntaxhighlight lang="console">
# maddyctl creds password postmaster@example.org
</syntaxhighlight>
</syntaxhighlight>


=== Spam filtering ===
=== Spam filtering ===


You can enable and use [[rspamd]] spam filtering daemon
You can enable and use [[rspamd]] spam filtering daemon like this
 
{{file|/etc/nixos/configuration.nix|nix|<nowiki>
{ options, lib, ... }: {
 
services.maddy.config = builtins.replaceStrings ["msgpipeline local_routing {"] [''msgpipeline local_routing {
  check {
    rspamd {
      api_path http://localhost:11334
    }
  }''] options.services.maddy.config.default;
 
services.rspamd = {
  enable = true;
  locals."dkim_signing.conf".text = ''
    selector = "default";
    domain = "project-insanity.org";
    path = "/var/lib/maddy/dkim_keys/$domain_$selector.key";
  '';
};
 
systemd.services.rspamd.serviceConfig.SupplementaryGroups = [ "maddy" ];
 
[...]
</nowiki>}}
 
The second part in this example replaces a part in the default config of the Maddy module and inserts the rspamd check to the message pipeline as described in the [https://maddy.email/reference/checks/rspamd upstream documentation].
 
The [[rspamd]] article also has some notes on how to achieve training for spam/ham mails using an additional helper script.
 
=== Mail attachement size ===
 
The default max mail attachement size is set to 32MB, for a higher value (in this case 64MB) change the default configuration via this workaround
 
{{file|/etc/nixos/configuration.nix|nix|<nowiki>
{ options, lib, ... }: {
 
services.maddy.config = builtins.replaceStrings [
  "dmarc yes"
] [
  ''dmarc yes
  max_message_size 64M''] options.services.maddy.config.default;
 
[...]
</nowiki>}}
 
=== Alias addresses ===
 
The following example will add an alias <code>mailA@example.org</code> for the local mail address <code>mailB@example.org</code> meaning that every mail send to <code>mailA</code> will get delivered to <code>mailB</code>.


{{file|/etc/nixos/configuration.nix|nix|<nowiki>
{{file|/etc/nixos/configuration.nix|nix|<nowiki>
services.rspamd.enable = true;
{ options, lib, ... }: {
 
services.maddy.config = builtins.replaceStrings [
  "optional_step file /etc/maddy/aliases"
] [
  "optional_step static {
    entry mailA@example.org mailB@example.org
  }"] options.services.maddy.config.default;
 
[...]
</nowiki>}}
</nowiki>}}


Add following <code>check</code> part to your Maddy configuration at the beginning of the section <code>msgpipeline local_routing</code> as referenced by the default config.
== Tips & tricks ==


<syntaxhighlight lang="json">
=== Test mail server ===
msgpipeline local_routing {


  check {
You can use several online tools to test your mail server configuration:
    rspamd
  }


  [...]
* [https://en.internet.nl/test-mail en.internet.nl/test-mail]: Test your mail server configuration for validity and security.
</syntaxhighlight>
* [https://www.mail-tester.com mail-tester.com]: Send a mail to this service and get a rating about the "spaminess" of your mail server.
* Send a mail to the echo server <code>echo@univie.ac.at</code>. You should receive a response containing your message in several seconds.


=== Autoconfig ===
=== Autoconfig ===


You can run an additional web service which provides autoconfig files for various mail clients like Thunderbird, iOS Mail or Outlook, so you don't have to manually configure your server settings into these apps. In this example, we're going to tell the clients, that our mail server is running on the domain <code>example.org</code> and which IMAP/SMTP ports to use
Since Maddy [https://github.com/foxcpp/maddy/issues/67 does not support this feature yet], you can run an additional web service which provides autoconfig or autodiscover files for various mail clients like Thunderbird, iOS Mail or Outlook, so you don't have to manually configure your server settings into these apps. In this example, we're going to tell the clients, that our mail server is running on the domain <code>example.org</code> and which IMAP/SMTP ports to use


{{file|/etc/nixos/configuration.nix|nix|<nowiki>
{{file|/etc/nixos/configuration.nix|nix|<nowiki>
services.go-autoconfig = {
services.go-autoconfig = {
   enable = true;
   enable = true;
   domain = "autoconfig.example.org";
   settings = {
  imap = {
    service_addr = ":1323";
    server = "example.org";
    domain = "autoconfig.example.org";
    port = 993;
    imap = {
  };
      server = "example.org";
  smtp = {
      port = 993;
    server = "example.org";
    };
    port = 587;
    smtp = {
      server = "example.org";
      port = 587;
    };
   };
   };
};
};
Line 123: Line 320:
</nowiki>}}
</nowiki>}}


You need DNS SRV-record on <code>example.org</code> to get Outlook and Thunderbird working:
Further we need to add an additional DNS record to the <code>nsd</code> service to get Outlook and Thunderbird working:
 
{{file|/etc/nixos/configuration.nix|nix|<nowiki>
services.nsd.zones."example.org.".data = ''
  [...]
  _autodiscover._tcp SRV 0 0 443 autoconfig
'';
</nowiki>}}
 
Of course autoconfig.example.org domain should point to your server running the SSL enabled web service.
 
== Troubleshooting ==
 
=== TLS it not available or unauthenticated but required ===
 
This error occurs if the receiving mail server has a invalid or none TLS configuration. The default configuration of Maddy enforces a valid TLS connection to the remote server for delivery. If you want to disable this default policy, apply following configuration hack
 
{{file|/etc/nixos/configuration.nix|nix|<nowiki>
{ options, lib, ... }: {
 
services.maddy.config = builtins.replaceStrings [
  "min_tls_level encrypted"
] [
  "min_tls_level none"] options.services.maddy.config.default;


<code>
[...]
_autodiscover._tcp IN SRV 0 0 443 autoconfig.example.org.
</nowiki>}}
</code>


Of course autoconfig.example.org domain should point to your server running the service.
== See also ==
* [https://maddy.email Maddy homepage and documentation]
* [[Stalwart]], an open-source, all-in-one mail server solution that supports JMAP, IMAP4, and SMTP protocols
* [https://nixos-mailserver.readthedocs.io/en/latest Simple NixOS Mailserver]
* [[Imapsync]], useful tool to migrate mailboxes to a new server


[[Category:Mail Server]]
[[Category:Mail Server]]
[[Category:Server]]

Latest revision as of 00:19, 22 July 2024

Maddy is a composable, modern mail server written in Go. It includes everything required to manage users, inboxes, send and receive mails while supporting all important secure protocols and standards.

Installation

The following example enables the Maddy mail server on localhost, listening on mail delivery SMTP/Submission ports (25, 587) and IMAP port (143) for mail clients to connect to. Mailboxes for the accounts postmaster@example.org and user1@example.org get created if they don't exist yet.

/etc/nixos/configuration.nix
services.maddy = {
  enable = true;
  primaryDomain = "localhost";
  ensureAccounts = [
    "user1@example.org"
    "postmaster@example.org"
  ];
  ensureCredentials = {
    # Do not use this in production. This will make passwords world-readable
    # in the Nix store
    "user1@example.org".passwordFile = "${pkgs.writeText "postmaster" "test"}";
    "postmaster@example.org".passwordFile = "${pkgs.writeText "postmaster" "test"}";
  };
};

This local test setup doesn't provide secure TLS connections and should be used only for testing purpose.

Configuration

TLS

The following example changes the hostname for the mail server to the public domain example.org. TLS certificates are obtained using using the ACME dns-01 challenge. This requires API access to your domain provider. See upstream documentation for a list on supported providers and how to configure them.

Further the TLS connection is enabled on IMAP port 993 and Submission port 465.

/etc/nixos/configuration.nix
services.maddy = {
  enable = true;
  openFirewall = true;
  primaryDomain = "example.org";
  tls = {
    loader = "acme";
    extraConfig = ''
      email put-your-email-here@example.org
      agreed # indicate your agreement with Let's Encrypt ToS
      host ${config.services.maddy.primaryDomain}
      challenge dns-01
      dns gandi {
        api_token "{env:GANDI_API_KEY}"
      }
    '';
  };
  # Enable TLS listeners. Configuring this via the module is not yet
  # implemented, see https://github.com/NixOS/nixpkgs/pull/153372
  config = builtins.replaceStrings [
    "imap tcp://0.0.0.0:143"
    "submission tcp://0.0.0.0:587"
  ] [
    "imap tls://0.0.0.0:993 tcp://0.0.0.0:143"
    "submission tls://0.0.0.0:465 tcp://0.0.0.0:587"
  ] options.services.maddy.config.default;
  # Reading secrets from a file. Do not use this example in production
  # since it stores the keys world-readable in the Nix store.
  secrets = [ "${pkgs.writeText "secrets" ''
    GANDI_API_KEY=1234
  ''}" ];
};

# Opening ports for additional TLS listeners. This is not yet
# implemented in the module.
networking.firewall.allowedTCPPorts = [ 993 465 ];

Alternativley certificates can be manually loaded with setting tls.loader = "file"; and manually specifiying key and certificates file paths using the tls.certificates = []; option. In this case, more ACME protocols and providers are available when using the native NixOS ACME module or manual client tools like Certbot.

DNS records

It is possibly easier to configure our own authoritative-only DNS server, which provides important setup information to other mail servers and clients. For details about the meaning of the specific DNS records or manual setup instructions see the Maddy setup tutorial.

/etc/nixos/configuration.nix
services.nsd = {
  enable = true;
  interfaces = [
    "0.0.0.0"
    "::"
  ]; 
  zones."example.org.".data = let
    domainkey = ''
      v=DKIM1; k=rsa; p=${
        lib.fileContents( /var/lib/maddy/dkim_keys/example.org_default.dns )}'';
    segments = ((lib.stringLength domainkey) / 255);
    domainkeySplitted = map (x: lib.substring (x*255) 255 domainkey) (lib.range 0 segments);
  in ''
    @ SOA ns.example.org noc.example.org 666 7200 3600 1209600 3600
    @ A 1.2.3.4
    @ AAAA abcd::eeff
    @ MX 10 mx1
    mx1 A 1.2.3.4
    mx1 AAAA abcd::eeff
    @ TXT "v=spf1 mx ~all"
    mx1 TXT "v=spf1 mx ~all"
    _dmarc TXT "v=DMARC1; p=quarantine; ruf=mailto:postmaster@example.org
    _mta-sts TXT "v=STSv1; id=1"
    _smtp._tls TXT "v=TLSRPTv1;rua=mailto:postmaster@example.org"
    default._domainkey TXT "${lib.concatStringsSep "\" \"" domainkeySplitted}"
  '';
};

Update the IPv4 and IPv6 addresses after A and AAAA to the one which points to the publc IP addresses of your mail server. The last entry is used by the DKIM authentication mechanism which enables recipients to verify the authenticity of mails send by your server. They key is read from the file generated by Maddy on the first startup at /var/lib/maddy/dkim_keys/example.org_default.dns and spitted in segments of 255 chars length to fulfill the DNS record requirements.

Now that your server also runs a DNS daemon besides the mail server, you have to configure it as the external nameserver of your domain example.org. Please consult your domain provider on how to do that.

rDNS

It is important that the public facing IP of your mail server resolves to the MX domain name. This is something you would normally configure on your server provider site. You can check if it's resolving correctly by running this command

# nix shell nixpkgs#bind --command dig -x 1.2.3.4
[...]
;; ANSWER SECTION:
1.2.3.4.in-addr.arpa. 6244	IN	PTR	mx1.example.org.

Replace the IP 1.2.3.4 with the IP of your mail server.

MTA-STS

MTA-STS enforces secure TLS configuration for servers which support this standard. We already advertised this feature in the DNS records above, but we also have to serve a static configuration file using a web server. We use the web server Caddy to do this but of course you can other Web Servers too.

/etc/nixos/configuration.nix
caddy = {
  enable = true;
  virtualHosts."mta-sts.example.org".extraConfig = ''
    encode gzip
    file_server
    root * ${
      pkgs.runCommand "testdir" {} ''
        mkdir -p "$out/.well-known"
        echo "
          version: STSv1
          mode: enforce
          max_age: 604800
          mx: mx1.example.org
        " &gt; "$out/.well-known/mta-sts.txt"
      ''
    }
  '';
};

Replace the domain mta-sts.example.org and the domain mx1.example.org with the ones you're using.

TLSA (DANE)

Using a TLSA (DANE) record is recommended to bind TLS-certificates to a server. Your nameserver needs DNSSEC support for it. You can generate the key using following command

# nix shell nixpkgs#hash-slinger --command tlsa  --create --selector 1 --protocol tcp -p 25 --create mx1.example.org

Or you can generate it directly from the TLS-certificate that you are using with maddy:

# openssl x509 -in cert.pem -pubkey -noout | openssl ec -pubin -outform der | sha256sum

Add the key to a new TLSA record in your nameserver

/etc/nixos/configuration.nix
services.nsd.zones."example.org.".data = ''
  [...]
  _25._tcp.mx1.example.org. TLSA 3 1 1 7f59d873a70e224b184c95a4eb54caa9621e47d48b4a25d312d83d96e3498238
'';

To verify if the record is set correctly

# nix shell nixpkgs#dnsutils --command dig _25._tcp.mx1.example.org TLSA +short
3 1 1 7f59d873a70e224b184c95a4eb54caa9621e47d48b4a25d312d83d96 e3498238

Check if DNSSEC is working correctly for your new TLSA record

# nix shell nixpkgs#dnsutils --command delv _25._tcp.mx1.example.org TLSA @1.1.1.1
; fully validated
_25._tcp.mx1.example.org. 10800 IN TLSA 3 1 1 7f59d873a70e224b184c95a4eb54caa9621e47d48b4a25d312d83d96 e3498238
_25._tcp.mx1.example.org. 10800 IN RRSIG	TLSA 13 5 10800 20230601000000 20230511000000 39688 example.org. He9VYZ35xTC3fNo8GJa6swPrZodSnjjIWPG6Th2YbsOEKTV1E8eGtJ2A +eyBd9jgG+B3cA/jw8EJHmpvy/buCw==

To verify that the TLSA record matches the TLS certificate of the mail server, issue following openssl command

# openssl s_client -connect mx1.example.org:25 -starttls smtp -dane_tlsa_domain mx1.example.org -dane_tlsa_rrdata "3 1 1 7f59d873a70e224b184c95a4eb54caa9621e47d48b4a25d312d83d96"
[...]
Verify return code: 0 (ok)
[...]

Replace the hostnames and the TLSA hash according to your configuration.

Users and inboxes

Creating credentials and inboxes for a specific account. The first command creates the user postmaster@example.org and will prompt for a password.

# maddyctl creds create postmaster@example.org
# maddyctl imap-acct create postmaster@example.org

Change password of an existing account

# maddyctl creds password postmaster@example.org

Spam filtering

You can enable and use rspamd spam filtering daemon like this

/etc/nixos/configuration.nix
{ options, lib, ... }: {

services.maddy.config = builtins.replaceStrings ["msgpipeline local_routing {"] [''msgpipeline local_routing {
  check {
    rspamd {
      api_path http://localhost:11334
    }
  }''] options.services.maddy.config.default;

services.rspamd = {
  enable = true;
  locals."dkim_signing.conf".text = ''
    selector = "default";
    domain = "project-insanity.org";
    path = "/var/lib/maddy/dkim_keys/$domain_$selector.key";
  '';
};

systemd.services.rspamd.serviceConfig.SupplementaryGroups = [ "maddy" ];

[...]

The second part in this example replaces a part in the default config of the Maddy module and inserts the rspamd check to the message pipeline as described in the upstream documentation.

The rspamd article also has some notes on how to achieve training for spam/ham mails using an additional helper script.

Mail attachement size

The default max mail attachement size is set to 32MB, for a higher value (in this case 64MB) change the default configuration via this workaround

/etc/nixos/configuration.nix
{ options, lib, ... }: {

services.maddy.config = builtins.replaceStrings [
  "dmarc yes"
] [
  ''dmarc yes
   max_message_size 64M''] options.services.maddy.config.default;

[...]

Alias addresses

The following example will add an alias mailA@example.org for the local mail address mailB@example.org meaning that every mail send to mailA will get delivered to mailB.

/etc/nixos/configuration.nix
{ options, lib, ... }: {

services.maddy.config = builtins.replaceStrings [
  "optional_step file /etc/maddy/aliases"
] [
  "optional_step static {
     entry mailA@example.org mailB@example.org
   }"] options.services.maddy.config.default;

[...]

Tips & tricks

Test mail server

You can use several online tools to test your mail server configuration:

  • en.internet.nl/test-mail: Test your mail server configuration for validity and security.
  • mail-tester.com: Send a mail to this service and get a rating about the "spaminess" of your mail server.
  • Send a mail to the echo server echo@univie.ac.at. You should receive a response containing your message in several seconds.

Autoconfig

Since Maddy does not support this feature yet, you can run an additional web service which provides autoconfig or autodiscover files for various mail clients like Thunderbird, iOS Mail or Outlook, so you don't have to manually configure your server settings into these apps. In this example, we're going to tell the clients, that our mail server is running on the domain example.org and which IMAP/SMTP ports to use

/etc/nixos/configuration.nix
services.go-autoconfig = {
  enable = true;
  settings = {
    service_addr = ":1323";
    domain = "autoconfig.example.org";
    imap = {
      server = "example.org";
      port = 993;
    };
    smtp = {
      server = "example.org";
      port = 587;
    };
  };
};

After that the autoconfig service based on program go-autoconfig will listen on http://localhost:1323 , serving the configuration informations used by the clients.

You can use your preferred web server, for example Caddy to proxy this service to an outside facing domain like https://autoconfig.example.org

/etc/nixos/configuration.nix
caddy = {                                  
  enable = true;                                              
  virtualHosts."autoconfig.example.org".extraConfig = ''
    reverse_proxy http://localhost:1323              
  '';             
};

Further we need to add an additional DNS record to the nsd service to get Outlook and Thunderbird working:

/etc/nixos/configuration.nix
services.nsd.zones."example.org.".data = ''
  [...]
  _autodiscover._tcp SRV 0 0 443 autoconfig
'';

Of course autoconfig.example.org domain should point to your server running the SSL enabled web service.

Troubleshooting

TLS it not available or unauthenticated but required

This error occurs if the receiving mail server has a invalid or none TLS configuration. The default configuration of Maddy enforces a valid TLS connection to the remote server for delivery. If you want to disable this default policy, apply following configuration hack

/etc/nixos/configuration.nix
{ options, lib, ... }: {

services.maddy.config = builtins.replaceStrings [
  "min_tls_level encrypted"
] [
  "min_tls_level none"] options.services.maddy.config.default;

[...]

See also