X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/exim-config/blobdiff_plain/185b5456076ca86959643ce2f19c98c0f82f281e..1e5ccd7c52be79d1de45691a0bb46cbb1a686bf0:/README diff --git a/README b/README index 25149fd..045e99b 100644 --- a/README +++ b/README @@ -25,7 +25,7 @@ about these files. 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 @@ -40,6 +40,15 @@ If this file exists, it should be world-readable, because it will be 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 @@ -47,14 +56,134 @@ particular =SUFFIX= string is valid. 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 @@ -119,53 +248,6 @@ for popular mailing lists, for example. 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 @@ -177,12 +259,144 @@ such domains and deliver them locally or to other hosts. Pester me if 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: