Maddy: Difference between revisions

Line 1:

[https://maddy.email 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.

{{Warning|Following example describes the usage of an experimental module which is still being reviewed as an [https://github.com/NixOS/nixpkgs/pull/153372 open PR] and might not be ready for production.}}

== Installation ==

{{Warning|Following example describes the usage of an experimental module which is still being reviewed as an [https://github.com/NixOS/nixpkgs/pull/153372 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 TLS-encrypted mails for the primary domain <code>example.org</code>.~~

Mailboxes for the accounts <code>postmaster@example.org</code> and <code>user1@example.org</code> get created if they don't exist yet.

{{file|/etc/nixos/configuration.nix|nix|<nowiki>

services.maddy = {

enable = true;

~~openFirewall = true;~~

primaryDomain = "localhost";

primaryDomain = "~~example.org";~~

~~tls = {~~

~~loader = "file";~~

~~certificates = [{~~

~~certPath = "/var/lib/acme/example.org/example.org.crt";~~

~~keyPath = "/var/lib/acme/example.org/example.org.key~~";

~~}];~~

};

~~imap = {~~

~~port = 143;~~

~~tlsEnable = true;~~

~~tlsPort = 993;~~

};

ensureAccounts = [

"user1@example.org"

Line 38:

Line 24:

</nowiki>}}

TLS ~~certificates can~~ be ~~obtained by using services like [[certbot]] or the [[ACME]] service. Please reference their documentation on how to configure them to acquire the certificates~~.

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

== Configuration ==

~~In case of using the ''acme'' service, grant~~ the ~~''maddy'' service read permissions~~ for the ~~certificates by adding it~~ to the ~~corresponding group~~

=== TLS ===

~~{{file|/etc/nixos/configuration~~.~~nix|nix|~~<~~nowiki~~>

~~systemd~~.~~services~~.~~maddy~~.~~serviceConfig.SupplementaryGroups =~~

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.

[ ~~config.security~~.acme.~~certs."example.org".group ];~~

</~~nowiki~~>}}

Further the TLS connection is enabled on IMAP port <code>993</code> and Submission port <code>465</code>.

~~For other clients such as ''certbot'', add it to the <code>acme</code> group~~

{{file|/etc/nixos/configuration.nix|nix|<nowiki>

~~systemd.~~services.maddy.~~serviceConfig~~.~~SupplementaryGroups~~ = [ "~~acme~~" ];

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

challenge dns-01

dns gandi {

api_token "{env:GANDI_API_KEY}"

}

'';

};

# Enable TLS listeners. Configuring this via the module is not yet

# implemented.

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

''}";

};

</nowiki>}}

== ~~Configuration ==~~

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.

=== DNS records ===

@@ Line 1: / Line 1: @@
 [https://maddy.email 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.
+{{Warning|Following example describes the usage of an experimental module which is still being reviewed as an [https://github.com/NixOS/nixpkgs/pull/153372 open PR] and might not be ready for production.}}
 == Installation ==
-{{Warning|Following example describes the usage of an experimental module which is still being reviewed as an [https://github.com/NixOS/nixpkgs/pull/153372 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 TLS-encrypted mails for the primary domain <code>example.org</code>.
-Mailboxes for the accounts <code>postmaster@example.org</code> and <code>user1@example.org</code> get created if they don't exist yet.
 {{file|/etc/nixos/configuration.nix|nix|<nowiki>
 services.maddy = {
    enable = true;
-  openFirewall = true;
+   primaryDomain = "localhost";
-   primaryDomain = "example.org";
-  tls = {
-    loader = "file";
-    certificates = [{
-      certPath = "/var/lib/acme/example.org/example.org.crt";
-      keyPath = "/var/lib/acme/example.org/example.org.key";
-    }];
-  };
-  imap = {
-    port = 143;
-    tlsEnable = true;
-    tlsPort = 993;
-  };
    ensureAccounts = [
      "user1@example.org"
@@ Line 38: / Line 24: @@
 </nowiki>}}
-TLS certificates can be obtained by using services like [[certbot]] or the [[ACME]] service. Please reference their documentation on how to configure them to acquire the certificates.
+This local test setup doesn't provide secure TLS connections and should be used only for testing purpose.
+== Configuration ==
-In case of using the ''acme'' service, grant the ''maddy''  service read permissions for the certificates by adding it to the corresponding group
+=== TLS ===
-{{file|/etc/nixos/configuration.nix|nix|<nowiki>
-systemd.services.maddy.serviceConfig.SupplementaryGroups =
+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.
-  [ config.security.acme.certs."example.org".group ];
-</nowiki>}}
+Further the TLS connection is enabled on IMAP port <code>993</code> and Submission port <code>465</code>.
-For other clients such as ''certbot'', add it to the <code>acme</code> group
 {{file|/etc/nixos/configuration.nix|nix|<nowiki>
-systemd.services.maddy.serviceConfig.SupplementaryGroups = [ "acme" ];
+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
+      challenge dns-01
+      dns gandi {
+        api_token "{env:GANDI_API_KEY}"
+      }
+    '';
+  };
+  # Enable TLS listeners. Configuring this via the module is not yet
+  # implemented.
+  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
+  ''}";
+};
 </nowiki>}}
-== Configuration ==
+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.
 === DNS records ===