README: More or less complete.
authorMark Wooding <mdw@distorted.org.uk>
Tue, 28 Jan 2014 02:00:41 +0000 (02:00 +0000)
committerMark Wooding <mdw@distorted.org.uk>
Tue, 28 Jan 2014 02:15:01 +0000 (02:15 +0000)
README

diff --git a/README b/README
index 25149fd..3940b91 100644 (file)
--- 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
 
 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
 
 
 ** 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.
 
 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
 
 
 * 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
 
 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
 
 
 ** 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
 
 
 ** 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
 
 
 * 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.
 
 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
 
 
 * Mail hosting and custom domains
@@ -176,13 +258,10 @@ 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.
 
 such domains and deliver them locally or to other hosts.  Pester me if
 this sounds useful to you.
 
-
-* Quick reference
-
-
-
 * COMMENT Emacs cruft
 
 * COMMENT Emacs cruft
 
+#+LaTeX_CLASS: strayman
+
 ### Local variables:
 ### mode: org
 ### End:
 ### Local variables:
 ### mode: org
 ### End: