Skip to end of metadata
Go to start of metadata

Introduction

This document will cover using exim to handle incoming and outgoing mail for a Sakai installation.

Basic Configuration

First, you need to add the service name of your sakai installation to the list of domains the server accepts mail for:

domainlist local_domains = @:[your.sakai.domain]

If you wish to test mail delivery at this point, send a message to somename@your.sakai.domain, you should receive an error like "no such user". You should also see a record in the main exim log file (usually /var/log/exim/main.log).

Configuring Incoming Mail

The first thing that needs to be done is to set up a router that defines what mail gets sent to Sakai. The following code needs to be in the router section of your configuration file. As the routers are processed in order and the first one that matches is used, this code should be added near the top of the configuration.

# Router (in routers section)
sakai_local:
  driver = manualroute
  domains = [your.sakai.domain]
  transport = sakai_smtp
  route_list = "* localhost"
  local_parts = !webmaster:!feedback:!help:!bounces:!homepage:!postmaster:!bugs:!alerts
  self = send

Here's a line-by-line breakdown of the above configuration settings:

Setting

Description

domains = [your.sakai.domain]

The domain(s) for which the router will be used, in this case your Sakai domain name.

transport = sakai_smtp

The name of the transport that will handle the delivery (see bellow)

local_parts = !webmaster:!feedback:!help:!bounces:!homepage:!postmaster:!bugs:!alerts

A list of local parts (everything before the @) for which the router will or won't be used. In this case by prefixing the addresses with ! we are indicating these are addresses that we won't send to Sakai but will handle in some other way - for instance forwarding using system aliases.

Next in the Transport section of exim.conf:

# Transport (in transport section)
sakai_smtp:
  driver = smtp
  allow_localhost = true
  port = 8025

Quite simply, this is just a driver to forward mail via SMTP to port 8025 on the local machine.

Configuring a Fallback Host

If you are running Sakai in a cluster you may want to cater for the case that the machine receives the mail may have exim running but Sakai wont accept email - for instance because the application is not running on that node. Fortunately exim handles this quite easily using the fallback host.

First, make sure that exim is configured to accept mail for the machine's hostname as well as the Sakai mail domain:

domainlist local_domains = @:[your.sakai.domain]:[thisserver.host.name]

Now, all we need to do is add this to our router:

fallback_hosts = [another.node.address]

If exim receives an email for Sakai and Sakai is not running it will, on the next queue run, forward the mail to the server with the hostname defined in fallback_hosts. If there is more than one fallback host, they will be tried in the order listed.

Configuring exim for Outgoing Mail

You may wish to use exim to handle outgoing mail delivery. Having a local SMTP server gives you the ability to easily handle your mail in intelligent ways and control the way in which outgoing messages are spooled.

The first step in configuring outgoing Sakai mail to go through exim is to update your sakai.properties file:

# smtp server for outgoing emails
smtp@org.sakaiproject.email.api.EmailService=localhost

After clearing our your James install and restarting Sakai, you should be able to to send an email from your Sakai installation and see exim deliver it. If you get a "Relay not permitted error" check that your exim is configured to relay mail from the localhost.

Using A SmartHost

There are several reasons you may wish to use an upstream SMTP server to handle delivery of external emails including:

  • Institutional IT policy on outgoing emails
  • The desire to avoid build up of queues of mail for external addresses, which in turn delay delivery of mail for local users

In this example we will look at configuring a router that will forward all external email to a SMTP smarthost but will leave exim to handle mail for your institution. This router needs to go in your router section after the router settings mentioned above.

smarthost:
  driver = manualroute
  transport = remote_smtp
  domains = ! +local_domains : !*.[institution.domain] : ![institution.domain]
  route_list = "* [smtp.server.name]"

Here's a line-by-line breakdown of the above configuration settings:

Setting

Description

transport = remote_smtp

The pre-defined exim transport to use.

domains = ! +local_domains : !*.[institution.domain] : ![institution.domain]

Domains to exclude from routing. In this case, this list includes anything on the local domain list as well as anything that matches your local institution domain.

route_list = "* [smtp.server.name]"

Simply the host name of your institutional SMTP server that will continue the process of delivering outgoing messages after they leave exim.

  • No labels