queue.scm: Add documentation to all postfix variables

And move it to the "finished services" section.

1 files changed, 52 insertions, 57 deletions

diff --git a/src/org/euandre/queue.scm b/src/org/euandre/queue.scm
index 01b5645..25fb6e5 100644
--- a/src/org/euandre/queue.scm
+++ b/src/org/euandre/queue.scm
@@ -706,7 +706,7 @@ By default, the daemon runs in a container.")))
   (match-record config <dkimproxyout-configuration>
       (config-extra listen relay domains selector data-directory)
     (format #f
-"listen ~a
+     "listen ~a
 relay ~a
 
 domain ~a
@@ -863,13 +863,6 @@ entry.
 By default, the daemon runs in a container.")))
 
 
-
-;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
-;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; WIP services ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
-;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
-
-
-
 (define-record-type* <postfix-configuration>
   postfix-configuration
   make-postfix-configuration
@@ -942,7 +935,7 @@ dksign      unix       -        -       n       -        -        smtp
   (match-record config <postfix-configuration>
       (enable-submission? master.cf-extra dkim-filter-listen dkim-filter-relay)
     (format #f
-      "# ============================================================================================================
+     "# ============================================================================================================
 # service   type       private  unpriv  chroot  wakeup   maxproc  command + args
 #                      (yes)    (yes)   (no)    (never)  (100)
 # =============================================================================================================
@@ -990,7 +983,7 @@ postlog     unix-dgram n        -       n       -        1        postlogd
 
 (define (main.cf-internet-extra hostname cert key sasl-dirname)
   (format #f
-  "
+   "
 myhostname = ~a
 
 smtpd_use_tls = yes
@@ -1215,7 +1208,8 @@ incurs in no interruption of the running service.")
                (list "alias "
                      (plain-file
                       "mta-sts.txt"
-                      (format #f "version: STSv1
+                      (format #f
+                       "version: STSv1
 mode: enforce
 mx: ~a
 max_age: 604800
@@ -1256,30 +1250,33 @@ max_age: 604800
     (extensions local-postfix-service-extensions)
     (default-value (postfix-configuration))
     (description
-       "
-        Run the Postfix MTA.
-
-        This is the top-level system service for Postfix.
-
-        It includes:
-        - populating /etc/postfix/ with read-only configuration files;
-        - the user and groups used by Postfix when handling email delivery;
-        - the special setgid binaries for daily usage, such as \"sendmail\";
-        - the Shepherd service for starting, stopping and *reloading* the
-          service without restarting it;
-        - the activation script for creating the required directories and
-          configuring them with the correct permissions;
-        - the binaries in the system profile so that one doesn't need to explicilty
-          include the package when the service is already enabled.
-
-        An extension to the log-rotation service isn't included: the default
-        rottlog configuration already includes /var/log/maillog in its routine,
-        so it is kept out.
-
-        The defaults of <postfix-configuration> provide sane default values for
-        most things, such as group names, data and queue directories, etc.  When
-        used as-is, it creates a Postfix server that sends email from local users
-        of the domain provided by \"/etc/hostname\".")))
+      "Run the Postfix MTA.
+
+This is the top-level system service for Postfix, targeted at \"local\"
+installations, that is, not internet-facing, usually for delivery of cronjob
+emails, or for offline email sending in a laptop via a relay.
+
+It includes:
+@itemize
+@item populating @file{/etc/postfix/} with read-only configuration files;
+@item the user and groups used by Postfix when handling email delivery;
+@item the special setgid binaries for daily usage, such as \"sendmail\";
+@item the Shepherd service for starting, stopping and @emph{reloading} the
+      service without restarting it;
+@item the activation script for creating the required directories and
+      configuring them with the correct permissions;
+@item the binaries in the system profile so that one doesn't need to explicilty
+      include the package when the service is already enabled.
+@end itemize
+
+An extension to the log-rotation service isn't included: the default rottlog
+configuration already includes @file{/var/log/maillog} in its routine, so it is
+kept out.
+
+The defaults of @code{<postfix-configuration>} provide sane default values for
+most things, such as group names, data and queue directories, etc.  When used
+as-is, it creates a Postfix server that sends email locally-only, and one can
+add relaying configuration via the @code{main.cf-extra} parameter.")))
 
 (define internet-postfix-service-type
   (service-type
@@ -1299,35 +1296,33 @@ max_age: 604800
     (default-value (postfix-configuration
                      (enable-submission? #t)))
     (description
-       "
-        Run the Postfix MTA.
+      "Run the Postfix MTA.
 
-        This is the top-level system service for Postfix.
+This is the top-level system service for Postfix, targeted at \"internet\"
+installations, that is, internet-facing SMTP servers, for sending and receiving
+emails to other servers, as well as local delivery of emails between users or by
+system users such as cronjobs.
 
-        It includes:
-        - populating /etc/postfix/ with read-only configuration files;
-        - the user and groups used by Postfix when handling email delivery;
-        - the special setgid binaries for daily usage, such as \"sendmail\";
-        - the Shepherd service for starting, stopping and *reloading* the
-          service without restarting it;
-        - the activation script for creating the required directories and
-          configuring them with the correct permissions;
-        - the binaries in the system profile so that one doesn't need to explicilty
-          include the package when the service is already enabled.
-
-        An extension to the log-rotation service isn't included: the default
-        rottlog configuration already includes /var/log/maillog in its routine,
-        so it is kept out.
+It includes everything from @code{local-postfix-service-type}, plus:
+@itemize
+@item nginx configuration for answering the @code{mta-sts.$domain} HTTP
+      subdomain, specifically the @code{.well-known/mta-sts.txt} URL;
+@item certbot extension for acquiring the certificate for @code{mta-sts.$domain}
+      so that the item above happens via HTTPS;
+@item best-practices email aliases for administering a SMTP server;
+@item cyrus-sasl extension for authenticating SMTP users via the Cyrus SASL
+      @code{saslauthd} daemon.
+@end itemize
 
-        The defaults of <postfix-configuration> provide sane default values for
-        most things, such as group names, data and queue directories, etc.  When
-        used as-is, it creates a Postfix server that sends email from local users
-        of the domain provided by \"/etc/hostname\".")))
+The defaults of @code{<postfix-configuration>} provide sane default values for
+most things, hostname, certificates, permissions, etc.  When used as-is, it
+creates a Postfix server that can send and receive emails from the internet
+correctly.")))
 
 
 
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
-;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; Dovecot ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; WIP services ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;