Merge branch 'gh-pages-exim' into gh-pages

1 files changed, 155 insertions, 56 deletions

diff --git a/docs/installing/email.md b/docs/installing/email.md
index e1806d66f..5eaaa3786 100644
--- a/docs/installing/email.md
+++ b/docs/installing/email.md
@@ -75,6 +75,13 @@ _Note:_ Bounce handling is not applied to [request emails]({{ site.baseurl }}doc
 
 ---
 
+<div class="attention-box">
+ <ul>
+ <li>Commands in this guide will require root privileges</li>
+ <li>Commands are intended to be run via the terminal or over ssh</li>
+ </ul>
+</div>
+
 Make sure you follow the correct instructions for the specific MTA you're using:
 
 * [postfix](#example-setup-on-postfix)
@@ -207,7 +214,7 @@ If you have set [`BLACKHOLE_PREFIX`]({{ site.baseurl }}docs/customising/config/#
 #### Filter incoming messages to site admin addresses
 
 You can make use of Alaveteli's [automatic bounce handling]({{site.baseurl}}docs/installing/email/#automatic-bounce-handling-optional) to filter bounces sent to [`TRACK_SENDER_EMAIL`]({{site.baseurl}}docs/customising/config/#track_sender_email)
-and [`CONTACT_EMAIL`]({{site.baseurl}}docs/customising/config/#contact_email). 
+and [`CONTACT_EMAIL`]({{site.baseurl}}docs/customising/config/#contact_email).
 
 
 <div class="attention-box">
@@ -340,40 +347,82 @@ This section shows an example of how to set up your MTA if you're using
 [postfix](#example-setup-on-postfix) if you're using that instead of exim4.
 
 
-### Instructions
+### Install exim4
+
+Install exim4:
+
+     apt-get install exim4
+
+
+### Configure exim4
+
+#### Set up exim to receive mail from other servers
+
+Edit `/etc/exim4/update-exim4.conf.conf`. Set the following settings (use your hostname, not `example.com`):
 
-We suggest you add the following to your exim configuration.
+    dc_eximconfig_configtype='internet'
+    dc_other_hostnames='example.com'
+    dc_local_interfaces='0.0.0.0 ; ::1'
+    dc_use_split_config='true'
 
-In `/etc/exim4/conf.d/main/04_alaveteli_options`, set:
+This final line tells exim to use the files in `/etc/exim4/conf.d` to configure itself.
 
-    ALAVETELI_HOME=/path/to/alaveteli/software
-    ALAVETELI_USER=www-data
+#### Define general variables and logging settings
+
+Create `/etc/exim4/conf.d/main/04_alaveteli_options` with the command:
+
+    cat > /etc/exim4/conf.d/main/04_alaveteli_options <<'EOF'
+    ALAVETELI_HOME=/var/www/alaveteli
+    ALAVETELI_USER=alaveteli
     log_file_path=/var/log/exim4/exim-%slog-%D
     MAIN_LOG_SELECTOR==+all -retry_defer
     extract_addresses_remove_arguments=false
+    EOF
+
+This sets up `ALAVETELI_HOME` and `ALAVETELI_USER` for use in other config files, and sets up logging.
+
+- **`ALAVETELI_HOME`:** set to the directory where Alaveteli is installed.
+- **`ALAVETELI_USER`:** should be the Unix user that is going to run your site. They should have write permissions on `ALAVETELI_HOME`.
+- **`log_file_path`:** The name and location of the log files created by Exim must match what the `load-mail-server-logs` script expects
+- **`MAIN_LOG_SELECTOR`:** The `check-recent-requests-sent` scripts expects the logs to contain the `from=<...>` envelope information, so we make the logs more verbose
+- **`extract_addresses_remove_arguments`:** setting to `false` gets exim to treat the `-t` command line option that the `mail` gem uses when specifying delivery addresses on the command line as specifying that the addresses should be added, not removed. See [this `mail` issue](https://github.com/mikel/mail/issues/70) for more details.
+
+<div class="attention-box">
+Note: If you are editing an existing exim config rather than creating a new one, check the <code>untrusted_set_sender</code> option in  <code>/etc/exim4/conf.d/main/02_exim4-config_options</code>. By default, untrusted users in exim are only allowed to set an empty envelope sender address, to declare that a message should never generate any bounces. <code>untrusted_set_sender</code> can be set to a list of address patterns, meaning that  untrusted users are allowed to set envelope sender addresses that match any of the patterns in the list. If a pattern list is specified,  you will need also to add <code>ALAVETELI_USER</code> to the <code>MAIN_TRUSTED_USERS</code> list in order to allow them to set the return path on outgoing mail. This option is also in <code>/etc/exim4/conf.d/main/02_exim4-config_options</code> in a split config. Look for the line that begins with <code>MAIN_TRUSTED_USERS</code> - something like:
+
+    <pre><code>MAIN_TRUSTED_USERS = uucp</code></pre>
 
-The user ALAVETELI_USER should have write permissions on ALAVETELI_HOME.
+and add the alaveteli user:
 
-The name and location of the log files created by Exim must match what the
-`load-mail-server-logs` script expects, which is why you must provide the
-`log_file_path` setting.
+    <pre><code>MAIN_TRUSTED_USERS = uucp : alaveteli</code></pre>
 
-The `check-recent-requests-sent` scripts expects the logs to contain the
-`from=<...>` envelope information, so we make the logs more verbose with
-`log_selector`. The ALAVETELI_USER may need to also need to be added to the
-`trusted_users` list in your Exim config in order to set the return path on
-outgoing mail, depending on your setup.
+ If <code>untrusted_set_sender</code> is set to <code>*</code>, that means that untrusted users can set envelope sender addresses without restriction, so there's no need to add <code>ALAVETELI_USER</code> to the <code>MAIN_TRUSTED_USERS</code> list.
+</div>
+
+#### Pipe incoming mail for requests from Exim to Alaveteli
+
+In this section, we'll add config to pipe incoming mail for special
+Alaveteli addresses into Alaveteli, and also send them to a local backup
+mailbox.
 
-In `/etc/exim4/conf.d/router/04_alaveteli`:
+Create the `backupfoi` UNIX user
 
+    adduser --quiet --disabled-password \
+      --gecos "Alaveteli Mail Backup" backupfoi
+
+Specify an exim `router` for special Alaveteli addresses, which will route messages into Alaveteli using a local pipe transport:
+
+    cat > /etc/exim4/conf.d/router/04_alaveteli <<'EOF'
     alaveteli_request:
        debug_print = "R: alaveteli for $local_part@$domain"
        driver = redirect
        data = ${lookup{$local_part}wildlsearch{ALAVETELI_HOME/config/aliases}}
        pipe_transport = alaveteli_mailin_transport
+    EOF
 
-In `/etc/exim4/conf.d/transport/04_alaveteli`:
+Create `/etc/exim4/conf.d/transport/04_alaveteli`, which sets the properties of the pipe `transport` that will deliver mail to Alaveteli:
 
+    cat > /etc/exim4/conf.d/transport/04_alaveteli <<'EOF'
     alaveteli_mailin_transport:
        driver = pipe
        command = $address_pipe ${lc:$local_part}
@@ -381,66 +430,116 @@ In `/etc/exim4/conf.d/transport/04_alaveteli`:
        home_directory = ALAVETELI_HOME
        user = ALAVETELI_USER
        group = ALAVETELI_USER
+    EOF
+
+
+<div class="attention-box">
+  This guide assumes you have set <a href="/docs/customising/config/#incoming_email_prefix"><code>INCOMING_EMAIL_PREFIX</code></a> to <code>foi+</code> in <code>config/general.yml</code>
+</div>
+
+Create the `config/aliases` file that the `alaveteli_request` exim `router` sources. This pipes mail from the special address to `script/mailin` and the `backupfoi` user.
+
+    cat > /var/www/alaveteli/config/aliases <<'EOF'
+    ^foi\\+.*: "|/var/www/alaveteli/script/mailin", backupfoi
+    EOF
+
+_Note:_ Replace `/var/www/alaveteli` with the correct path to alaveteli if required.
 
-And, assuming you set
-[`INCOMING_EMAIL_PREFIX`]({{ site.baseurl }}docs/customising/config/#incoming_email_prefix)
-in your config at `config/general.yml` to "foi+", create `config/aliases` with the following
-content:
+#### Set up your contact email recipient groups
 
-    ^foi\\+.*: |/path/to/alaveteli/software/script/mailin
+To set up recipient groups for the `team@` and `user-support@` email addresses at your domain, add alias records for them in `/var/www/alaveteli/config/aliases`
 
-You should also configure exim to discard any messages sent to the
-[`BLACKHOLE_PREFIX`]({{ site.baseurl }}docs/customising/config/#blackhole_prefix)
-address, whose default value is
-`do-not-reply-to-this-address`. For example, add the following to
-`config/aliases`:
+    cat >> /var/www/alaveteli/config/aliases <<EOF
+    team: user@example.com, otheruser@example.com
+    user-support: team
+    EOF
 
-    # We use this for envelope from for some messages where we don't care about delivery
+#### Discard unwanted incoming email
+
+Configure exim to discard any messages sent to the [`BLACKHOLE_PREFIX`]({{ site.baseurl }}docs/customising/config/#blackhole_prefix) address, whose default value is `do-not-reply-to-this-address`
+
+    cat >> /var/www/alaveteli/config/aliases <<EOF
+    # We use this for envelope from for some messages where
+    # we don't care about delivery
     do-not-reply-to-this-address:        :blackhole:
+    EOF
+
+_Note:_ Replace `/var/www/alaveteli` with the correct path to alaveteli if required.
+
+#### Filter incoming messages to admin addresses
+
+You can make use of Alaveteli's [automatic bounce handling]({{site.baseurl}}docs/installing/email/#automatic-bounce-handling-optional) to filter bounces sent to [`TRACK_SENDER_EMAIL`]({{site.baseurl}}docs/customising/config/#track_sender_email)
+and [`CONTACT_EMAIL`]({{site.baseurl}}docs/customising/config/#contact_email).
+
+<div class="attention-box">
+This guide assumes you have set the following in <code>config/general.yml</code>:
 
-If you want to make use of the automatic bounce-message handling, then set the
-[`TRACK_SENDER_EMAIL`]({{ site.baseurl }}docs/customising/config/#track_sender_email)
-address to be filtered through
-`script/handle-mail-replies`. Messages that are not bounces or
-out-of-office autoreplies will be forwarded to
-[`FORWARD_NONBOUNCE_RESPONSES_TO`]({{ site.baseurl }}docs/customising/config/#forward_nonbounce_responses_to).
-For example, in WhatDoTheyKnow the
-configuration looks like this:
+  <ul>
+    <li><a href="{{site.baseurl}}docs/customising/config/#contact_email">CONTACT_EMAIL</a>: <code>user-support@example.com</code></li>
+    <li><a href="{{site.baseurl}}docs/customising/config/#track_sender_email">TRACK_SENDER_EMAIL</a>: <code>user-support@example.com</code></li>
+    <li><a href="{{site.baseurl}}docs/customising/config/#forward_nonbounce_responses_to">FORWARD_NONBOUNCE_RESPONSES_TO</a>: <code>team@example.com</code></li>
+  </ul>
 
-    raw_team: [a list of people on the team]
-    team:     |/path/to/alaveteli/software/script/handle-mail-replies
+Change the examples below to the addresses you have configured.
+</div>
 
-with `FORWARD_NONBOUNCE_RESPONSES_TO`: 'raw_team@whatdotheyknow.com'`
+Change the `user-support` line in `/var/www/alaveteli/config/aliases`:
 
-Finally, make sure you have `dc_use_split_config='true'` in
-`/etc/exim4/update-exim4.conf.conf`, and execute the command
-`update-exim4.conf`.
+    user-support:     |/var/www/alaveteli/script/handle-mail-replies
+
+#### Logging
+
+You’ll need to tell Alaveteli where the log files are stored and that they’re in exim format. Update [`MTA_LOG_PATH`]({{ site.baseurl }}docs/customising/config/#mta_log_path) and [`MTA_LOG_TYPE`]({{ site.baseurl }}docs/customising/config/#mta_log_type) in `config/general.yml`:
+
+    MTA_LOG_PATH: '/var/log/exim4/exim-mainlog-*'
+    MTA_LOG_TYPE: 'exim'
+
+
+#### Making the changes live in exim
+
+Finally, execute the commands:
+
+    update-exim4.conf
+    service exim4 restart
 
 Note that if the file `/etc/exim4/exim4.conf` exists then `update-exim4.conf`
 will silently do nothing. Some distributions include this file. If
-yours does, you will need to rename it before running `update-exim4.conf`.
+yours does, you will need to remove or rename it before running `update-exim4.conf`.
 
-(You may also want to set `dc_eximconfig_configtype='internet'`,
-`dc_local_interfaces='0.0.0.0 ; ::1'`, and
-`dc_other_hostnames='<your-host-name>'`).
 
-### Troubleshooting (exim)
+#### Troubleshooting (exim)
 
-To test mail delivery, run:
+To test mail delivery, as a privileged user run:
 
-    exim -bt foi+request-1234@localhost
+    exim4 -bt foi+request-1234@example.com
 
-This should tell you which routers are being processed.  You should
+replacing `example.com` with your domain name. This should tell you which routers are being processed.  You should
 see something like:
 
-    $ exim -bt foi+request-1234@localhost
-    R: alaveteli pipe for snafflerequest-234@localhost
-    snafflerequest-234@localhost -> |/home/alaveteli/alaveteli/script/mailin
-    transport = alaveteli_mailin_transport
+    $ exim4 -bt foi+request-1234@example.com
+    R: alaveteli for foi+request-1234@example.com
+    foi+request-1234@example.com -> |/var/www/alaveteli/script/mailin
+      transport = alaveteli_mailin_transport
+    R: alaveteli for backupfoi@your.machine.name
+    R: system_aliases for backupfoi@your.machine.name
+    R: userforward for backupfoi@your.machine.name
+    R: procmail for backupfoi@your.machine.name
+    R: maildrop for backupfoi@your.machine.name
+    R: lowuid_aliases for backupfoi@your.machine.name (UID 1001)
+    R: local_user for backupfoi@your.machine.name
+    backupfoi@your.machine.name
+        <-- foi+request-1234@example.com
+      router = local_user, transport = mail_spool
 
 This tells you that the routing part (making emails to
-`foi\+.*@localhost` be forwarded to Alaveteli's `mailin` script) is
-working.
+`foi\+.*@example.com` be forwarded to Alaveteli's `mailin` script, and
+also sent to the local backup account) is working. You can test bounce
+message routing in the same way:
+
+    exim4 -bt user-support@example.com
+    R: alaveteli for user-support@example.com
+    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)