From 7d6c8e24ce1c270b249b0fcd6d2dfeddd10750cd Mon Sep 17 00:00:00 2001
From: Martin Weinelt <hexa@darmstadt.ccc.de>
Date: Sun, 15 Jun 2025 03:06:43 +0200
Subject: [PATCH] nixos/postfix: improve option documentation for service
 toggles

In particular we now explain what port the service listens on and what
protocol to expect. Update the RFC8341 recommendation to discourage
submission and recommend submissions.
---
 nixos/modules/services/mail/postfix.nix | 34 +++++++++++++++++++++----
 1 file changed, 29 insertions(+), 5 deletions(-)

diff --git a/nixos/modules/services/mail/postfix.nix b/nixos/modules/services/mail/postfix.nix
index dcb61e337a0e..a135665412e2 100644
--- a/nixos/modules/services/mail/postfix.nix
+++ b/nixos/modules/services/mail/postfix.nix
@@ -356,23 +356,47 @@ in
       enableSmtp = lib.mkOption {
         type = lib.types.bool;
         default = true;
-        description = "Whether to enable smtp in master.cf.";
+        description = ''
+          Whether to enable the `smtp` service configured in the master.cf.
+
+          This service listens for plain text SMTP connections on port 25
+          and supports explicit TLS via StartTLS.
+
+          It is the primary port used by SMTP servers to exchange mail.
+        '';
       };
 
       enableSubmission = lib.mkOption {
         type = lib.types.bool;
         default = false;
-        description = "Whether to enable smtp submission.";
+        description = "
+          Whether to enable the `submission` service configured in master.cf.
+
+          This service listens for plain text SMTP connections on port 587
+          and supports explicit TLS via StartTLS.
+
+          It is a way for clients to login and submit mails after an inband
+          connection upgrade using StartTLS.
+
+          ::: {.warning}
+          [RFC 8314](https://www.rfc-editor.org/rfc/rfc8314) discourages the use
+          of explicit TLS for mail submissionn.
+          :::
+        ";
       };
 
       enableSubmissions = lib.mkOption {
         type = lib.types.bool;
         default = false;
         description = ''
-          Whether to enable smtp submission via smtps.
+          Whether to enable the `submissions` service configured in master.cf.
 
-          According to RFC 8314 this should be preferred
-          over STARTTLS for submission of messages by end user clients.
+          This service listen for implicit TLS connections on port 465.
+
+          ::: {.info}
+          Per [RFC 8314](https://www.rfc-editor.org/rfc/rfc8314) implicit TLS
+          is recommended for mail submission.
+          :::
         '';
       };