Merge branch 'gh-pages-external-smtp-check' into gh-pages

2 files changed, 89 insertions, 37 deletions

diff --git a/docs/installing/email.md b/docs/installing/email.md
index 5eaaa3786..44476cefa 100644
--- a/docs/installing/email.md
+++ b/docs/installing/email.md
@@ -323,7 +323,7 @@ is working (it doesn't actually send any mail). If it is working, you
 should receive a delivery report email, with text like:
 
     <foi+request-1234@example.com>: delivery via alaveteli:
-delivers to command: /var/www/alaveteli/script/mailin
+    delivers to command: /var/www/alaveteli/script/mailin
     <backupfoi@local.machine.name>: delivery via local: delivers to  mailbox
 
 You can also test the other aliases you have set up for your domain in
@@ -339,6 +339,10 @@ delivery report email using the `mail` command on a new server:
 
     apt-get install mailutils
 
+If emails are not being received by your Alaveteli install, we have some
+more troubleshooting tips for incoming mail in [general email troubleshooting]({{ site.baseurl }}docs/installing/email#general-email-troubleshooting).
+
+
 
 ## Example setup on exim4
 
@@ -541,6 +545,86 @@ message routing in the same way:
     user-support@example.com -> |/var/www/alaveteli/script/handle-mail-replies
       transport = alaveteli_mailin_transport
 
-There is a great
-[Exim Cheatsheet](http://bradthemad.org/tech/notes/exim_cheatsheet.php)
-online that you may find useful.
+If emails are not being received by your Alaveteli install, we have some
+more troubleshooting tips for incoming mail in the next section. There is also a
+great [Exim
+Cheatsheet](http://bradthemad.org/tech/notes/exim_cheatsheet.php) online
+that you may find useful.
+
+## General Email Troubleshooting
+
+First, you need to check that your MTA is delivering relevant
+incoming emails to the `script/mailin` command.  There are various
+ways of setting your MTA up to do this; we have documented
+one way of doing it
+[in Exim]({{ site.baseurl }}docs/installing/email/#example-setup-on-exim4), including [a command you can use]({{ site.baseurl }}docs/installing/email/#troubleshooting-exim) to check that the email
+routing is set up correctly. We've also documented one way of setting up [Postfix]({{ site.baseurl }}docs/installing/email/#example-setup-on-postfix), with a similar [debugging command]({{ site.baseurl }}docs/installing/email/#troubleshooting-postfix).
+
+Second, you need to test that the mailin script itself is working
+correctly, by running it from the command line, First, find a
+valid "To" address for a request in your system.  You can do this
+through your site's admin interface, or from the command line,
+like so:
+
+    $ ./script/console
+    Loading development environment (Rails 2.3.14)
+    >> InfoRequest.find_by_url_title("why_do_you_have_such_a_fancy_dog").incoming_email
+    => "request-101-50929748@localhost"
+
+Now take the source of a valid email (there are some sample emails in
+`spec/fixtures/files/`); edit the `To:` header to match this address;
+and then pipe it through the mailin script.  A non-zero exit code
+means there was a problem.  For example:
+
+    $ cp spec/fixtures/files/incoming-request-plain.email /tmp/
+    $ perl -pi -e 's/^To:.*/To: <request-101-50929748@localhost>/' /tmp/incoming-request-plain.email
+    $ ./script/mailin < /tmp/incoming-request-plain.email
+    $ echo $?
+    75
+
+The `mailin` script emails the details of any errors to
+`CONTACT_EMAIL` (from your `general.yml` file). A common problem is
+for the user that the MTA runs as not to have write access to
+`files/raw_emails/`.
+
+If everything seems fine locally, you should also check from another
+computer connected to the Internet that the DNS for your chosen
+domain indicates that your Alaveteli server is handling mail, and
+that your server is receiving mail on port 25. The following
+command is a query to ask which server is handling the mail for
+the domain `example.com`, which receives the answer `mail.example.com`.
+
+    $ host -t mx example.com
+    example.com mail is handled by 5 mail.example.com.
+
+This next command tries to connect to port 25, the standard SMTP
+port, on `mail.example.com`, and is refused.
+
+    $ telnet mail.example.com 25
+    Trying 10.10.10.30...
+    telnet: connect to address 10.10.10.30: Connection refused
+
+The transcript below shows a successful connection where the server
+accepts mail for delivery (the commands you would type are prefixed
+by a `$`):
+
+    $ telnet 10.10.10.30 25
+    Trying 10.10.10.30...
+    Connected to 10.10.10.30.
+    Escape character is '^]'.
+    220 mail.example.com ESMTP Exim 4.80 Tue, 12 Aug 2014 11:10:39 +0000
+    $ HELO X
+    250 mail.example.com Hello X [10.10.10.1]
+    $ MAIL FROM: <test@local.domain>
+    250 OK
+    $ RCPT TO:<foi+request-1234@example.com>
+    250 Accepted
+    $ DATA
+    354 Enter message, ending with "." on a line by itself
+    $ Subject: Test
+    $
+    $ This is a test mail.
+    $ .
+    250 OK id=1XHA03-0001Vx-Qn
+    QUIT
+
diff --git a/docs/installing/manual_install.md b/docs/installing/manual_install.md
index 9ab661f8f..8c9e2a8d6 100644
--- a/docs/installing/manual_install.md
+++ b/docs/installing/manual_install.md
@@ -845,39 +845,7 @@ You should then be able to run the tests. Don't forget to restore <code>config/r
 
 *   **Incoming emails aren't appearing in my Alaveteli install**
 
-    First, you need to check that your MTA is delivering relevant
-    incoming emails to the `script/mailin` command.  There are various
-    ways of setting your MTA up to do this; we have documented
-    one way of doing it
-    [in Exim]({{ site.baseurl }}docs/installing/email/#example-setup-on-exim4), including [a command you can use]({{ site.baseurl }}docs/installing/email/#troubleshooting-exim) to check that the email
-    routing is set up correctly. We've also documented one way of setting up [Postfix]({{ site.baseurl }}docs/installing/email/#example-setup-on-postfix), with a similar [debugging command]({{ site.baseurl }}docs/installing/email/#troubleshooting-postfix).
-
-    Second, you need to test that the mailin script itself is working
-    correctly, by running it from the command line, First, find a
-    valid "To" address for a request in your system.  You can do this
-    through your site's admin interface, or from the command line,
-    like so:
-
-        $ ./script/console
-        Loading development environment (Rails 2.3.14)
-        >> InfoRequest.find_by_url_title("why_do_you_have_such_a_fancy_dog").incoming_email
-        => "request-101-50929748@localhost"
-
-    Now take the source of a valid email (there are some sample emails in
-    `spec/fixtures/files/`); edit the `To:` header to match this address;
-    and then pipe it through the mailin script.  A non-zero exit code
-    means there was a problem.  For example:
-
-        $ cp spec/fixtures/files/incoming-request-plain.email /tmp/
-        $ perl -pi -e 's/^To:.*/To: <request-101-50929748@localhost>/' /tmp/incoming-request-plain.email
-        $ ./script/mailin < /tmp/incoming-request-plain.email
-        $ echo $?
-        75
-
-    The `mailin` script emails the details of any errors to
-    `CONTACT_EMAIL` (from your `general.yml` file).  A common problem is
-    for the user that the MTA runs as not to have write access to
-    `files/raw_emails/`.
+    See the [general email troubleshooting guide]({{ site.baseurl }}docs/installing/email#general-email-troubleshooting).
 
 *   **Various tests fail with "*Your PostgreSQL connection does not support
     unescape_bytea. Try upgrading to pg 0.9.0 or later.*"**