Package README (CVS ver. 1.2)

Plone Mail Transport Agent
===========================

WARNING: THIS TOOL IS A POTENTIAL SECURITY HAZARD. READ TROUGH THIS DOCUMENT
FOR MORE INFO.

This is a product that attempts to tackle once and for all the task of getting
mail into a Plone site. It's inspired by ZWiki, CMFBoard, CMFMailIn,
PloneMailBoxer, and others.

This is not about accessing mail that's outside Zope (stored in a local
mailbox, IMAP, or POP). The intent here is to receive email in Zope, and either
store it in the ZODB, or use it to execute some actions (like subscribing to a
list, or getting help).

The tool is very agnostic with regard to what will be done with mail. Its only
purpose is to get the message in, and then route it to a method that will do
whatever should be done. In this aspect, its architecture is similar to the
Mail Transport Agents that run on most GNU-like or Unix-like stations -
software like sendmail, exim, courier, postfix. So this is the name that was
chosen for the tool: Mail Transport Agent, or MTA.

The primary character in the MTA tool is the "rules" script. It's a python
script, hardwired into the tool, which you can edit via ZMI. You should be very
careful about who has permission to edit those rules! They may implement their
own authentication, and therefore execute code as pretty much anyone.

POTENTIAL SECURITY RISK: allowing a Plone admin to create a MTA tool inside a
Plone instance is more or less as risky as allowing {Extensible|Simple} User
Folder. It could easily be used to execute code as an user defined outside
Plone, and do bad things like shutting down Zope or peeking at other people's
passwords. In principle, on a shared Zope server running multiple Plone
instances for different people, this tool shouldn't be allowed. In the future,
we'll look into ways of removing this risk.

That said, back to our regularly scheduled documentation. The primary character
is the rules script. Its task is to examine an incoming message and decide what
script should be used to deliver it, and under what user identity this script
should run. These scripts are referred to as "handlers". There are only two
possibilities for a handler: it may be an object that exists inside the MTA
tool (acquisition is disallowed due to security concerns), or it may be a
built-in method.

The current version ships with built-in methods to:

 - silently discard the message

 - log the message to a tool-wide box; this method could be used for example to
 receive mail sent to the portal's address and store it in a place where any
 managers can read it

 - deliver to CMFBoard (www.cmfboard.org)

 - (TODO) deliver to PloneMail, a companion product that implements a webmail
 system in a portal

 - (TODO) perform a search and return a list of URLs with titles and
 descriptions

 - return the title + description + body of a document or news item (a.k.a.
 sendback)

Neither CMFBoard, PloneMail or Archetypes are required to run the MTA tool, but
they're used if found.

The handler sandbox
--------------------

By default, handlers run in a special security sandbox. If you want to use this
feature, you'll have to do some setup by yourself.

The handler will be run authenticated with the username returned by the rules
script; however, there will be an additional security restriction. For each
action that's attempted, besides the user having permission to perform it, the
tool also checks if the role "Mail Access" has permission. Since this role
doesn't exist by default, this means the handler will run authenticated, for
the purposes of ownership and 'creator' tracking, but with the permissions of
anonymous.

So if you want some action to be doable by mail, you have to choices. Either
create the "Mail Access" role on your Plone instance (preferably on its root),
and give permissions to this role only on the places you need it, **or** tweak
the rules script to return "authoritative" authentication. The first option is
by far preferred; "authoritative" authentication should only be allowed in very
special cases (for example, if the message is gpg-signed and after checking the
signature), because it's just too easy to spoof email.

How to get mail into the MTA tool
----------------------------------

To actually get mail into the tool, you need to program your os-level MTA to
forward some mail to it. The easiest way to do it is by using a "pipe
transport" and curl (http://curl.haxx.se).

Here is how I do it on my personal test instance, using exim 4.24: in the
routers section, I have an entry that look like

    # Zope PloneMTA router
    zope_lists:
      driver = accept
      domains = lists.laranja.org portal.laranja.org
      transport = zopepipe

And then in transports:

    # PloneMTA transport
    zopepipe:
      driver = pipe
      return_fail_output
      # 7 is connection failed; 28 is timeout; 52 is server closed before
      replying.
      # temp_errors instructs exim that these errors are not permanent;
      # it should queue the messages and attempt again later
      temp_errors = 7:28:52
      command = curl -s --connect-timeout 10 \
            http://localhost:9080/mepaba/portal_mailtransport/deliver \
            -F sender=${sender_address} -F rcpt_list=${local_part}@${domain} -F
            data=<-

This transport is still not ideal; I could use the ${pipe_addresses} to handle
all 'rcpt's of a given message in a single http request. However, curl doesn't
allow me to do that, because it would want each rcpt to be preceded by "-F
rcpt_list=". Writing a specialized python script would probably be a better
solution, or even writing a custom exim transport driver in C (using the neon
library).

I hope these instructions are clear enough to be adapted to other MTAs. If
someone wants to provide detailed instructions for specific MTAs, by all means
please send it to me and I'll include them in a 'doc' subdirectory in the
package.

Who
----

The MTA tool was written by Lalo Martins <lalo@laranja.org>, with some code
copied over from CMFBoard by Nik Kim <fafhrd@legco.kz>.

PloneMTA is copyright © 2003 Lalo Martins and Nik Kim.