This commit refactors the dovecot serialization process to express the values
to be serialized as G-Exps instead. String values are now properly serialized
according to dovecot.conf syntax rules. [1]
The documentation was also revised and regenerated.
* gnu/services/mail.scm: Reorganize dovecot related procedures.
(uglify-field-name): Simplify.
(escape-string, make-serialize-list-with-delimiter, serialize-list-of-strings)
(serialize-alist, make-serialize-section, make-serialize-list-of-sections)
(serialize-section-name, serialize-list-of-passdb-configurations)
(serialize-list-of-userdb-configurations)
(serialize-list-of-listener-configurations)
(serialize-list-of-service-configurations)
(serialize-list-of-protocol-configurations)
(serialize-list-of-mailbox-configurations)
(serialize-list-of-namespace-configurations)
(dovecot-configuration->file): New procedure.
(serialize-field, serialize-string, serialize-non-negative-integer)
(serialize-boolean, free-form-fields?, serialize-free-form-fields)
(serialize-dict-configuration, listener-configuration?)
(serialize-listener-configuration, serialize-protocol-configuration)
(serialize-plugin-configuration, serialize-mailbox-configuration): Refactor.
(list-of-passdb-configurations?, list-of-userdb-configurations?)
(list-of-listener-configurations?, list-of-service-configurations?)
(list-of-protocol-configurations?, list-of-mailbox-configurations?)
(list-of-namespace-configurations?): New predicate.
(space-separated-string-list?, comma-separated-string-list?, file-name?)
(colon-separated-file-name-list?, free-form-args?)
(passdb-configuration-list?, userdb-configuration-list?)
(listener-configuration-list?, service-configuration-list?)
(protocol-configuration-list?, mailbox-configuration-list?)
(list-of-namespace-configuration?): Remove predicate.
(serialize-space-separated-string-list, serialize-comma-separated-string-list)
(serialize-colon-separated-file-name-list, serialize-free-form-args)
(serialize-passdb-configuration, serialize-passdb-configuration-list)
(serialize-userdb-configuration, serialize-userdb-configuration-list)
(serialize-unix-listener-configuration, serialize-fifo-listener-configuration)
(serialize-inet-listener-configuration, serialize-listener-configuration-list)
(serialize-service-configuration, serialize-service-configuration-list)
(serialize-protocol-configuration-list, serialize-mailbox-configuration-list)
(serialize-namespace-configuration)
(serialize-list-of-namespace-configuration): Remove procedure.
(hours?): Remove unused predicate, leftovers from
28c03b4555e99da9524c697f5eba3783916050c7.
(serialize-hours): Likewise.
(unix-listener-configuration, fifo-listener-configuration): Deduplicate
definition with a let-syntax macro.
(passdb-configuration)[args]: Set value type to maybe-list-of-strings.
(userdb-configuration)[args]: Likewise.
[override-fields]: Set value type to alist.
(unix-listener-configuration, fifo-listener-configuration)[path]: Remove
redundant error guard.
(inet-listener-configuration)[protocol, port]: Likewise.
(service-configuration)[kind]: Likewise. Set serializing procedure to
serialize-section-name.
[listeners]: Set value type to list-of-listener-configurations.
(protocol-configuration)[name]: Remove redundant error guard.
[mail-plugins]: Set value type to list-of-strings.
[managesieve-notify-capability, managesieve-sieve-capability]: Set value type
to maybe-list-of-strings.
(mailbox-configuration)[name]: Remove redundant error guard.
[special-use]: : Set value type to maybe-list-of-strings.
(namespace-configuration)[name]: Remove redundant error guard.
[location, hidden?, subscriptions?]: Fix documentation.
[mailboxes]: Set value type to list-of-mailbox-configurations.
(dovecot-configuration)[listen]: Set value type to list-of-strings. Serialize
this using comma as the delimiter.
[passdbs, userdbs]: Simplify default value.
[namespaces]: Set value type to list-of-namespace-configurations.
[base-dir, auth-winbind-helper-path, mail-temp-dir, auth-socket-path]
[mail-plugin-dir, sendmail-path]: Set value type to string.
[login-trusted-networks, director-servers, director-mail-servers]
[imap-client-workarounds]: Set value type to maybe-list-of-strings.
[doveadm-socket-path, auth-cache-size, auth-cache-ttl]
[auth-cache-negative-ttl, auth-realms, auth-master-user-separator]
[auth-anonymous-username, director-servers, director-mail-servers]
[info-log-path, debug-log-path, syslog-facility, auth-verbose-passwords]
[auth-debug-passwords?, login-log-format, mail-location]
[mail-privileged-group, mail-access-groups, mail-full-filesystem-access?]
[mmap-disable?, dotlock-use-excl?, mail-fsync, lock-method, first-valid-uid]
[mail-chroot, mail-plugins, mail-save-crlf?, maildir-stat-dirs?]
[mbox-read-locks, mbox-very-dirty-syncs?, mail-attachment-dir]
[ssl-crypto-device, lda-mailbox-autocreate?]
[lda-mailbox-autosubscribe?]: Fix documentation.
[import-environment, auth-mechanisms, login-log-format-elements]
[mail-plugins, mbox-read-locks, mbox-write-locks]: Set value type to
list-of-strings.
[log-timestamp, mail-log-prefix]: Reflect changes from escape-string, remove
extraneous quotes.
[valid-chroot-dirs]: Refactor documentation. Serialize this using colon as the
delimiter.
[protocols]: Set value type to list-of-protocol-configurations.
[services]: Set value type to list-of-service-configurations. Re-style.
(opaque-dovecot-configuration)[string]: Remove redundant error guard.
(%dovecot-activation): Refactor to use 'dovecot-configuration->file' for
serializing dovecot.conf.
(dovecot-service-type): Re-style.
* doc/guix.texi: Regenerate it. Remove example using deprecated
'dovecot-service' procedure.
Change-Id: I8d18c504c5cd80497a069f28c1c6975538510e7e
---
doc/guix.texi | 1613 ++++++++++++++++-------------------------
gnu/services/mail.scm | 870 +++++++++++-----------
2 files changed, 1083 insertions(+), 1400 deletions(-)
Toggle diff (370 lines)
diff --git a/doc/guix.texi b/doc/guix.texi
index b90078be06..5242e89104 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -25658,9 +25658,11 @@ Mail Services
@cindex mail
@cindex email
The @code{(gnu services mail)} module provides Guix service definitions
-for email services: IMAP, POP3, and LMTP servers, as well as mail
-transport agents (MTAs). Lots of acronyms! These services are detailed
-in the subsections below.
+for email services: @acronym{IMAP, Internet Message Access Protocol},
+@acronym{POP3, Post Office Protocol version 3}, and @acronym{LMTP,
+Local Mail Transfer Protocol} servers, as well as @acronym{MTA,
+transport agent}s. Lots of acronyms! These services are detailed in
+the subsections below.
@subsubheading Dovecot Service
@@ -25678,8 +25680,11 @@ Mail Services
and as is the case with other services, Guix allows the system
administrator to specify these parameters via a uniform Scheme interface.
-For example, to specify that mail is located at @code{maildir~/.mail},
-one would instantiate the Dovecot service like this:
+For example, to specify that the mail location is a
+maildir@footnote{A mailbox format, see
+@url{https://manpages.debian.org/stretch/qmail/maildir.5.en.html}.}
+located at @file{~/.mail}, one would instantiate the Dovecot service
+like this:
@lisp
(service dovecot-service-type
@@ -25687,10 +25692,8 @@ Mail Services
(mail-location "maildir:~/.mail")))
@end lisp
-The available configuration parameters follow. Each parameter
-definition is preceded by its type; for example, @samp{string-list foo}
-indicates that the @code{foo} parameter should be specified as a list of
-strings. There is also a way to specify the configuration as a string,
+The available configuration parameters follow.
+There is also a way to specify the configuration as a string,
if you have an old @code{dovecot.conf} file that you want to port over
from some other system; see the end for more details.
@@ -25702,688 +25705,378 @@ Mail Services
@c (generate-documentation) than to make it below and have to deal with
@c the churn as dovecot updates.
+@c %start of fragment
+@deftp {Data Type} dovecot-configuration
Available @code{dovecot-configuration} fields are:
-@deftypevr {@code{dovecot-configuration} parameter} package dovecot
+@table @asis
+@item @code{dovecot} (default: @code{dovecot}) (type: file-like)
The dovecot package.
-@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} comma-separated-string-list listen
-A list of IPs or hosts where to listen for connections. @samp{*}
-listens on all IPv4 interfaces, @samp{::} listens on all IPv6
+@item @code{listen} (default: @code{("*" "::")}) (type: list-of-strings)
+A list of IPs or hosts where to listen in for connections. @samp{*}
+listens in all IPv4 interfaces, @samp{::} listens in all IPv6
interfaces. If you want to specify non-default ports or anything more
complex, customize the address and port fields of the
-@samp{inet-listener} of the specific services you are interested in.
-@end deftypevr
-
-@deftypevr {@code{dovecot-configuration} parameter} protocol-configuration-list protocols
-List of protocols we want to serve. Available protocols include
-@samp{imap}, @samp{pop3}, and @samp{lmtp}.
-
-Available @code{protocol-configuration} fields are:
-
-@deftypevr {@code{protocol-configuration} parameter} string name
-The name of the protocol.
-@end deftypevr
-
-@deftypevr {@code{protocol-configuration} parameter} string auth-socket-path
-UNIX socket path to the master authentication server to find users.
-This is used by imap (for shared users) and lda.
-It defaults to @samp{"/var/run/dovecot/auth-userdb"}.
-@end deftypevr
-
-@deftypevr {@code{protocol-configuration} parameter} boolean imap-metadata?
-Whether to enable the @code{IMAP METADATA} extension as defined in
-@uref{https://tools.ietf.org/html/rfc5464,RFC@tie{}5464}, which provides
-a means for clients to set and retrieve per-mailbox, per-user metadata
-and annotations over IMAP.
-
-If this is @samp{#t}, you must also specify a dictionary @i{via} the
-@code{mail-attribute-dict} setting.
-
-Defaults to @samp{#f}.
-
-@end deftypevr
-
-@deftypevr {@code{protocol-configuration} parameter} space-separated-string-list managesieve-notify-capabilities
-Which NOTIFY capabilities to report to clients that first connect to
-the ManageSieve service, before authentication. These may differ from the
-capabilities offered to authenticated users. If this field is left empty,
-report what the Sieve interpreter supports by default.
-
-Defaults to @samp{'()}.
-@end deftypevr
-
-@deftypevr {@code{protocol-configuration} parameter} space-separated-string-list managesieve-sieve-capability
-Which SIEVE capabilities to report to clients that first connect to
-the ManageSieve service, before authentication. These may differ from the
-capabilities offered to authenticated users. If this field is left empty,
-report what the Sieve interpreter supports by default.
-
-Defaults to @samp{'()}.
-
-@end deftypevr
-
-@deftypevr {@code{protocol-configuration} parameter} space-separated-string-list mail-plugins
-Space separated list of plugins to load.
-@end deftypevr
-
-@deftypevr {@code{protocol-configuration} parameter} non-negative-integer mail-max-userip-connections
-Maximum number of IMAP connections allowed for a user from each IP
-address. NOTE: The username is compared case-sensitively.
-Defaults to @samp{10}.
-@end deftypevr
-
-@end deftypevr
-
-@deftypevr {@code{dovecot-configuration} parameter} service-configuration-list services
-List of services to enable. Available services include @samp{imap},
-@samp{imap-login}, @samp{pop3}, @samp{pop3-login}, @samp{auth}, and
-@samp{lmtp}.
-
-Available @code{service-configuration} fields are:
-
-@deftypevr {@code{service-configuration} parameter} string kind
-The service kind. Valid values include @code{director},
-@code{imap-login}, @code{pop3-login}, @code{lmtp}, @code{imap},
-@code{pop3}, @code{auth}, @code{auth-worker}, @code{dict},
-@code{tcpwrap}, @code{quota-warning}, or anything else.
-@end deftypevr
-
-@deftypevr {@code{service-configuration} parameter} listener-configuration-list listeners
-Listeners for the service. A listener is either a
-@code{unix-listener-configuration}, a @code{fifo-listener-configuration}, or
-an @code{inet-listener-configuration}.
-Defaults to @samp{'()}.
-
-Available @code{unix-listener-configuration} fields are:
-
-@deftypevr {@code{unix-listener-configuration} parameter} string path
-Path to the file, relative to @code{base-dir} field. This is also used as
-the section name.
-@end deftypevr
-
-@deftypevr {@code{unix-listener-configuration} parameter} string mode
-The access mode for the socket.
-Defaults to @samp{"0600"}.
-@end deftypevr
-
-@deftypevr {@code{unix-listener-configuration} parameter} string user
-The user to own the socket.
-Defaults to @samp{""}.
-@end deftypevr
-
-@deftypevr {@code{unix-listener-configuration} parameter} string group
-The group to own the socket.
-Defaults to @samp{""}.
-@end deftypevr
-
-
-Available @code{fifo-listener-configuration} fields are:
-
-@deftypevr {@code{fifo-listener-configuration} parameter} string path
-Path to the file, relative to @code{base-dir} field. This is also used as
-the section name.
-@end deftypevr
-
-@deftypevr {@code{fifo-listener-configuration} parameter} string mode
-The access mode for the socket.
-Defaults to @samp{"0600"}.
-@end deftypevr
-
-@deftypevr {@code{fifo-listener-configuration} parameter} string user
-The user to own the socket.
-Defaults to @samp{""}.
-@end deftypevr
-
-@deftypevr {@code{fifo-listener-configuration} parameter} string group
-The group to own the socket.
-Defaults to @samp{""}.
-@end deftypevr
-
-
-Available @code{inet-listener-configuration} fields are:
-
-@deftypevr {@code{inet-listener-configuration} parameter} string protocol
-The protocol to listen for.
-@end deftypevr
-
-@deftypevr {@code{inet-listener-configuration} parameter} string address
-The address on which to listen, or empty for all addresses.
-Defaults to @samp{""}.
-@end deftypevr
-
-@deftypevr {@code{inet-listener-configuration} parameter} non-negative-integer port
-The port on which to listen.
-@end deftypevr
-
-@deftypevr {@code{inet-listener-configuration} parameter} boolean ssl?
-Whether to use SSL for this service; @samp{yes}, @samp{no}, or
-@samp{required}.
-Defaults to @samp{#t}.
-@end deftypevr
-
-@end deftypevr
-
-@deftypevr {@code{service-configuration} parameter} non-negative-integer client-limit
-Maximum number of simultaneous client connections per process. Once
-this number of connections is received, the next incoming connection
-will prompt Dovecot to spawn another process. If set to 0,
-@code{default-client-limit} is used instead.
-
-Defaults to @samp{0}.
-
-@end deftypevr
-
-@deftypevr {@code{service-configuration} parameter} non-negative-integer service-count
-Number of connections to handle before starting a new process.
-Typically the only useful values are 0 (unlimited) or 1. 1 is more
-secure, but 0 is faster. <doc/wiki/LoginProcess.txt>.
-Defaults to @samp{1}.
-
-@end deftypevr
-
-@deftypevr {@code{service-configuration} parameter} non-negative-integer process-limit
-Maximum number of processes that can exist for this service. If set to
-0, @code{default-process-limit} is used instead.
-
-Defaults to @samp{0}.
-
-@end deftypevr
-
-@deftypevr {@code{service-configuration} parameter} non-negative-integer process-min-avail
-Number of processes to always keep waiting for more connections.
-Defaults to @samp{0}.
-@end deftypevr
-
-@deftypevr {@code{service-configuration} parameter} non-negative-integer vsz-limit
-If you set @samp{service-count 0}, you probably need to grow
-this.
-Defaults to @samp{256000000}.
-@end deftypevr
+@code{inet-listener} of the specific services you are interested in.
-@end deftypevr
-
-@deftypevr {@code{dovecot-configuration} parameter} dict-configuration dict
+@item @code{dict} (type: dict-configuration)
Dict configuration, as created by the @code{dict-configuration}
constructor.
+@deftp {Data Type} dict-configuration
Available @code{dict-configuration} fields are:
-@deftypevr {@code{dict-configuration} parameter} free-form-fields entries
+@table @asis
+@item @code{entries} (default: @code{'()}) (type: free-form-fields)
A list of key-value pairs that this dict should hold.
-Defaults to @samp{'()}.
-@end deftypevr
-
-@end deftypevr
+@end table
+@end deftp
-@deftypevr {@code{dovecot-configuration} parameter} passdb-configuration-list passdbs
-A list of passdb configurations, each one created by the
+@item @code{passdbs} (type: list-of-passdb-configurations)
+List of passdb configurations, each one created by the
@code{passdb-configuration} constructor.
+@deftp {Data Type} passdb-configuration
Available @code{passdb-configuration} fields are:
-@deftypevr {@code{passdb-configuration} parameter} string driver
-The driver that the passdb should use. Valid values include
-@samp{pam}, @samp{passwd}, @samp{shadow}, @samp{bsdauth}, and
-@samp{static}.
-Defaults to @samp{"pam"}.
-@end deftypevr
+@table @asis
+@item @code{driver} (default: @code{"pam"}) (type: string)
+The driver that the passdb should use. Valid values include @samp{pam},
+@samp{passwd}, @samp{shadow}, @samp{bsdauth}, and @samp{static}.
-@deftypevr {@code{passdb-configuration} parameter} space-separated-string-list args
+@item @code{args} (type: maybe-list-of-strings)
Space separated list of arguments to the passdb driver.
-Defaults to @samp{""}.
-@end deftypevr
-
-@end deftypevr
+@end table
+@end deftp
-@deftypevr {@code{dovecot-configuration} parameter} userdb-configuration-list userdbs
+@item @code{userdbs} (type: list-of-userdb-configurations)
List of userdb configurations, each one created by the
@code{userdb-configuration} constructor.
+@deftp {Data Type} userdb-configuration
Available @code{userdb-configuration} fields are:
-@deftypevr {@code{userdb-configuration} parameter} string driver
+@table @asis
+@item @code{driver} (default: @code{"passwd"}) (type: string)
The driver that the userdb should use. Valid values include
@samp{passwd} and @samp{static}.
-Defaults to @samp{"passwd"}.
-@end deftypevr
-@deftypevr {@code{userdb-configuration} parameter} space-separated-string-list args
+@item @code{args} (type: maybe-list-of-strings)
Space separated list of arguments to the userdb driver.
-Defaults to @samp{""}.
-@end deftypevr
-@deftypevr {@code{userdb-configuration} parameter} free-form-args override-fields
+@item @code{override-fields} (default: @code{'()}) (type: alist)
Override fields from passwd.
-Defaults to @samp{'()}.
-@end deftypevr
-
-@end deftypevr
+@end table
+@end deftp
-@deftypevr {@code{dovecot-configuration} parameter} plugin-configuration plugin-configuration
+@item @code{plugin-configuration} (type: plugin-configuration)
Plug-in configuration, created by the @code{plugin-configuration}
constructor.
-@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} list-of-namespace-configuration namespaces
+@item @code{namespaces} (type: list-of-namespace-configurations)
List of namespaces. Each item in the list is created by the
@code{namespace-configuration} constructor.
+@deftp {Data Type} namespace-configuration
Available @code{namespace-configuration} fields are:
-@deftypevr {@code{namespace-configuration} parameter} string name
+@table @asis
+@item @code{name} (type: string)
Name for this namespace.
-@end deftypevr
-@deftypevr {@code{namespace-configuration} parameter} string type
+@item @code{type} (default: @code{"private"}) (type: string)
Namespace type: @samp{private}, @samp{shared} or @samp{public}.
-Defaults to @samp{"private"}.
-@end deftypevr
-@deftypevr {@code{namespace-configuration} parameter} string separator
-Hierarchy separator to use. You should use the same separator for
-all namespaces or some clients get confused. @samp{/} is u
