From cf699684ac7a068d06bc5782eacea64dd45ac723 Mon Sep 17 00:00:00 2001 From: Mark Wooding Date: Sat, 20 Dec 2014 19:33:59 +0000 Subject: [PATCH] README: Add a bunch of technical documentation. --- README | 135 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 135 insertions(+) diff --git a/README b/README index 3940b91..045e99b 100644 --- a/README +++ b/README @@ -258,6 +258,141 @@ other than =distorted.org.uk=. I can easily arrange to accept mail for such domains and deliver them locally or to other hosts. Pester me if this sounds useful to you. + +* Technical documentation + +** =auth-sender.conf= + +This file is an =lsearch=-format map from user names to address lists +that the users are allowed to claim as envelope senders. (For domains +hosted locally, the *users* and *locals* options of =domains.conf= works +better: this mechanism is intended to allow users to send mail +apparently from their Gmail addresses, for example.) + +** =domains.conf= + +Most of the special knowledge for the mail configuration is in +=/etc/mail/domains.conf=. This contains a number of stanzas, each +headed by a domain pattern, and containing a sequence of /key/ = /value/ +pairs. If a /value/ contains whitespace then it must be quoted. In +terms of Exim syntax, this is a `partial0-wildlsearch' file where the +values are =${extract ...}= strings. + +The following keys are recognized. Nothing will save you if you spell +the name of a key wrongly. + + + errors_to :: Sets =errors_to= for deliveries to a virtual domain -- + see [[info:spec:Generic%20options%20for%20routers][Generic options for routers]]. The default is to send errors to + the sender, as usual. + + + filter :: Specifies the name (subject to expansion) of a filter file + to use for routing mail to a virtual domain. The filter file may + use full the Exim filtering language, and may cause deferrals, + failures, or blackholing. This is one of a number of mutually + exclusive router options: see also *redirect* and *route*. + + + final :: If true (the default, if there is an entry for the + receiving domain), then recipients not routed through the + =domains.conf= file are assumed not to exist. (As a last ditch + measure, mail to the special local-parts =postmaster= and =abuse= is + redirected to the global administrator.) If false, local parts not + routed using the =domains.conf= machinery are handled as for the + main system domain. + + + home :: The home directory for the virtual domain administrator. + This is available to other expansions as =$home=. + + + hosts :: A list of host names and/or addresses which are permitted + to send mail from this domain. If this key is omitted, but there is + a matching =domains.conf= entry for the domain, then the default is + the list of known networks =+allnets=; otherwise the default is all + external networks. + + + locals :: A list (expanded) of those local-parts which the + authenticated user (named by =$acl_c_user=) is permitted to use as + the sender on outgoing messages. + + + owner :: The name of the user who should perform local deliveries to + this virtual domain. + + + redirect :: Redirection data (expanded) for deliveries to this + virtual domain. This is one of a number of mutually exclusive + router options: see also *filter* and *route*. + + + require-auth :: If true, then the recipient domain requires us to + perform SMTP authentication to it. The necessary credentials are in + =/etc/mail/client-secrets=, which is in =partial0-lsearch= format, + keyed by either the recipient domain or host, and the values are + =${extract ...}=-format key/value pairs which depend on the + authenticator to use. For PLAIN authentication, set *plain* to the + string to send (using =^= to stand for NUL bytes, e.g., + =^user^passwd=). For LOGIN, set *login-name* and *login-passwd*. + For CRAM-MD5, set *cram-md5-name* and *cram-md5-secret*. + + + route :: Routing data (=route_data= for Exim's =manualroute= + transport) for sending mail to the domain. This is one of a number + of mutually exclusive router options: see also *filter* and + *redirect*. + + + senders :: A list of sender addresses (not local-parts) which are + known to be valid from the sending domain: the usual sender + verification is skipped for such addresses. This is a hack for + sending domains which have misconfigured MX records. + + + service :: If true (the default if an entry is found) , then we + provide main mail service for this domain. + + + spam-check :: If true, then check incoming mail to this domain for + spam. Only overridden for special effects. + + + spam-limit-file :: The name of a file in =nwildlsearch= format in + which to look up RECIPIENT/SENDER to find a spam-score limit for a + message sent to the virtual domain. + + + spam-limit-userv :: The name of a user whose =exim-spam-limit= Userv + service should be invoked to find the spam-score limit for a message + sent to the virtual domain. + + + tls-certificate :: The name (subject to expansion) of a file + containing the TLS client certificate list to present when sending + mail to this domain. Requires a *route* entry for the target + domain. + + + tls-ciphers :: A list (subject to expansion) of permitted + ciphersuite names when delivering mail to this domain. + Alternatively, this can be one of the special keywords *good* or + *any*, for the preconfigured known-strong and any-acceptable lists. + Requires a *route* entry for the target domain. + + + tls-min-dh-bits :: When routing to this domain, ensure that the + order of the Diffie--Hellman group used for forward-secure key + exchange has at least this many bits. Because the Exim + =tls_dh_min_bits= option doesn't actually allow expansion, only + *1024* and *2048* are valid values for this option. Requires a + *route* entry for the target domain. + + + tls-peer-ca :: The name (subject to expansion) of a file containing + acceptable trust anchors for verifying the server's certificate when + delivering to this domain (and to require TLS for the + communication). The default is to not worry about TLS. Requires a + *route* entry for the target domain. + + + tls-private-key :: The name (subject to expansion) of a file + containing the private key to use to authenticate to a server when + delivering to this domain. Requires a *route* entry for the domain. + + + users :: A list (subject to expansion) of user names (matched as + local parts) of users who are permitted to send mail from this + domain. + + +** =helo.conf= + +This file is a =partial0-lsearch=-format map from HELO names to +=match_ip= lists of IP addresses which are permitted to claim that name. +This is intended to deal with hosts whose DNS configuration doesn't +match their HELO announcement. + * COMMENT Emacs cruft #+LaTeX_CLASS: strayman -- 2.11.0