If you prefer, you can write delivery instructions to =~/.mail/forward=
instead. If you have lots of mail configuration files, you may find it
-tidier to keep them all together in =~/.mail=.
+tidier to keep them all together in =~/.mail/=.
** The =~/.mail/forward.suffix= file
used by the mail server at SMTP time in order to decide whether a
particular =SUFFIX= string is valid.
+** Permissions for filter files
+
+Your various filter files are used by Exim's SMTP server, which runs as
+an unprivileged user =Debian-exim= for security reasons. Therefore your
+filter files must be readable by this user. Currently, the only way to
+do this is to make the filter files world-readable. If this is
+unsatisfactory for some reason I'll try to come up with a way to arrange
+privacy for your filters.
+
* Reading mail
The servers =stratocaster= and =jem= have a few mail user agents
installed, most notably trad BSD =mail=, =mutt=, and Emacs's various
-mail-reading interfaces; more can be added.
+mail-reading interfaces; more can be added. Your mail is delivered to
+=/var/mail/USER=; any further arrangements, e.g., multiple folders, are
+left to you.
** Fetching mail through IMAP
-There's an IMAP server running on =mail.distorted.org.uk=. ...
+There's an IMAP server running on =mail.distorted.org.uk=. It expects
+your main inbox to be in =/var/mail/USER=, and further folders are put
+in =~/mail/=, in mbox format.
+
+The IMAP server listens on ports 143 (plain IMAP) and 993 (IMAP over
+TLS). In the former case, you'll have to configure your client to send
+=STARTTLS=, because the server simply won't allow non-encrypted
+communication.
+
+The server's certificate is signed by my certificate authority, whose
+own certificate can be fetched from
+https://www.distorted.org.uk/ca/ca.cert. (The web server's certificate
+is signed by the StartCom Class 1 CA, which should be in most browser's
+certificate stores.) I issue new short-term certificates daily, so
+telling your mail client to pin the certificate won't help. (The public
+key doesn't change, though, so if you can do public-key pinning you'll
+be OK.)
** Forwarding mail off-site
+You can redirect all of your mail to some other site if you prefer to
+consolidate it: just write the destination mailbox to =~/.forward=.
+Everything else is left to you.
+
+
+* Sending mail
+
+** The =sendmail= program
+
+Exim provides a =/usr/sbin/sendmail= program with a plausible interface,
+and most traditional Unix programs will use this by default to send
+mail.
+
+** SMTP to =localhost=
+
+Another traditional way of submitting mail is by connecting to port 25
+on the loopback address 127.0.0.1 and speaking SMTP. This will work on
+most servers, and you will be authenticated automatically using the
+system's =identd=. NB: servers other than stratocaster won't
+understand unusual domains.
+
+** The Submission protocol
+
+The `modern' way to submit mail involves connecting to port 587 on the
+=mail.distorted.org.uk= (the `submission' service) and speaking SMTP.
+If you use this service, then (a) you must tell your client to send
+=STARTTLS=, and (b) you will have to provide a user name and password.
+
+As with IMAP, the SMTP server's certificate is signed by the
+=distorted.org.uk= CA; see above.
+
+** Sender authenticity
+
+It is my intention that it be very hard for one =distorted.org.uk= user
+to impersonate another to a third. To this end, the mail server is
+rather picky about envelope sender addresses.
+
+ + It won't accept an apparently local sender address from an external
+ mail server at all.
+
+ + It will check locally submitted mail against the submitter's user
+ name. The precise details vary according to the submission
+ mechanism: mail submitted through =sendmail= will have additional
+ headers added; mail submitted through SMTP will be rejected unless
+ the envelope sender is acceptable.
+
+If I see something like DKIM catching on then this will also provide
+external users with some kind of (probably fairly weak) sender
+authenticity.
+
+On the other hand, the mail server is aware of vanity domains, extension
+addresses, and so on, and should let you send mail apparently from an
+such an address that you control. If you think the mail server is being
+unnecessarily strict about something then I'm willing to discuss your
+requirements.
+
+If I'm hosting your mail domain for you then you get to decide the
+appropriate policy.
+
+
+* Chopwood, and passwords
+
+Users don't have login passwords on =distorted.org.uk= machines; but the
+SMTP and IMAP services require user names and passwords, which are
+managed using the `Chopwood' service (whose name is `chpwd' -- short for
+`change password' -- with some additional vowels).
+
+You can communicate with Chopwood in three different ways.
+
+ 1. Using Userv. On stratocaster, run =userv chpwd help= for a list
+ of commands.
+
+ 2. Using SSH. You will need to send me an SSH public key (or
+ several), which I'll install for you. Then you'll be able to run
+ =ssh chpwd@stratocaster.distorted.org.uk help= for a list of
+ commands, as for Userv. (This is mainly intended for people who
+ don't have login accounts.)
+
+ 3. Using the web interface. Point your browser at
+ =https://www.distorted.org.uk/chpwd/=. For this, you'll need a
+ user name and password for Chopwood itself: if you have a local
+ login, you can set this up yourself using Userv (say); otherwise
+ I'll generate a password for you and send it to you.
+
+If you're using Userv or SSH, you can list which password-using services
+you have accounts with the =list= command, and request new passwords
+with =reset=, which prints the new password to stdout; the =clear=
+command will disable a service's password, preventing you from logging
+in at all. There is a command =set= for setting a password that you
+choose, but that's disabled as a matter of local policy: it's possible
+that I can be persuaded to enable it, but not very likely. Note that
+you can reset several services' passwords with the same command, and
+this will use the same (freshly generated) password for all of them.
+For example,
+
+: userv chpwd reset smtp imap
+
+will generate a new password which will work both with the SMTP
+submission service and the IMAP server.
+
+Similar functionality is available through the web interface.
+
* Spam filtering
I'm not currently running SAUCE, but I'm giving it some consideration.
If you have comments on the matter, either way, I'm interested.
-
-
-* Sending mail
-
-** Submission mechanisms
-
-Mail can be sent in a number of ways.
-
- + The =sendmail= program. This is really Exim in disguise.
-
- + SMTP to =localhost= port 25. This doesn't require explicit
- authentication, since it relies on an identd, which is running on
- all =distorted.org.uk= hosts.
-
- + SMTP to =mail.distorted.org.uk= port 587. You must establish TLS,
- and authenticate using a username and password; the server uses a
- short-lived certificate signed by the =distorted.org.uk= certificate
- authority, whose root certificate is at =/etc/ca/ca.cert= on all
- servers. Use [[https://www.distorted.org.uk/chpwd/][Chopwood]] to set or change this password.
-
-** Sender authenticity
-
-It is my intention that it be very hard for one =distorted.org.uk= user
-to impersonate another to a third. To this end, the mail server is
-rather picky about envelope sender addresses.
-
- + It won't accept an apparently local sender address from an external
- mail server at all.
-
- + It will check locally submitted mail against the submitter's user
- name. The precise details vary according to the submission
- mechanism: mail submitted through =sendmail= will have additional
- headers added; mail submitted through SMTP will be rejected unless
- the envelope sender is acceptable.
-
-If I see something like DKIM catching on then this will also provide
-external users with some kind of (probably fairly weak) sender
-authenticity.
-
-On the other hand, the mail server is aware of vanity domains, extension
-addresses, and so on, and should let you send mail apparently from an
-such an address that you control. If you think the mail server is being
-unnecessarily strict about something then I'm willing to discuss your
-requirements.
-
-If I'm hosting your mail domain for you then you get to decide the
-appropriate policy.
* Mail hosting and custom domains
this sounds useful to you.
-* Quick reference
-
-
+* 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
+
### Local variables:
### mode: org
### End:
~mdw / exim-config / blobdiff