imip-agent

Annotated docs/wiki/MailIntegration

1214:3bc482b5f33e
1024:48b37822d2a0
1006:ead8eeb668ff
2016-01-29 Paul Boddie file changeset files shortlog Moved common test initialisation into a separate script.
paul@984 1 
= Mail Integration =
paul@933 2 
 
 paul@934      3 
To act as a part of an e-mail system, imip-agent provides a number of programs
 
 paul@934      4 
that may be invoked by mail transfer agents (MTAs) upon sending or receiving
 
 paul@934      5 
messages. In order to uphold portability and to minimise configuration issues,
 
 paul@934      6 
these programs need only be registered as simple mail handlers or transports,
 
 paul@934      7 
thus potentially supporting a wide range of MTAs.
 
 paul@933      8 
 
 paul@934      9 
Once imip-agent has processed a message, it may then deliver it to its
 
 paul@934     10 
intended recipient. The mail storage systems that may receive messages from
 
 paul@934     11 
imip-agent need only support the delivery mechanisms used by imip-agent.
 
 paul@934     12 
Otherwise, few constraints should be imposed by each kind of system on the
 
 paul@934     13 
other.
 
 paul@933     14 
 
 paul@971     15 
{{{#!graphviz
 
 paul@971     16 
//format=svg
 
 paul@971     17 
//transform=notugly
 
 paul@971     18 
digraph mail_integration {
 
 paul@1006     19 
  node [shape=box,fontsize="13.0",fontname="Helvetica",tooltip="Mail integration"];
 
 paul@971     20 
  edge [tooltip="Mail integration"];
 
 paul@971     21 
  rankdir=LR;
 
 paul@971     22 
 
 paul@971     23 
  mail [label="Incoming mail",shape=folder,style=filled,fillcolor=cyan];
 
 paul@971     24 
 
 paul@971     25 
  subgraph {
 
 paul@971     26 
    rank=same;
 
 paul@971     27 
    personrouter [label="Person router"];
 
 paul@971     28 
    resourcerouter [label="Resource router"];
 
 paul@971     29 
    recipients [label="Recipient database",shape=folder];
 
 paul@971     30 
  }
 
 paul@971     31 
 
 paul@971     32 
  subgraph {
 
 paul@971     33 
    rank=same;
 
 paul@971     34 
    personhandler [label="Person handler",style=filled,fillcolor=gold];
 
 paul@971     35 
    resourcehandler [label="Resource handler",style=filled,fillcolor=gold];
 
 paul@971     36 
    scheduling [label="Scheduling",shape=ellipse,style=filled,fillcolor=gold];
 
 paul@971     37 
    freebusy [label="Free/busy",shape=folder,style=filled,fillcolor=gold];
 
 paul@971     38 
  }
 
 paul@971     39 
 
 paul@971     40 
  mailbox [label="Mailboxes\n(Cyrus, Dovecot, ...)",tooltip="Mailboxes"];
 
 paul@971     41 
 
 paul@971     42 
  mail -> personrouter -> personhandler -> mailbox;
 
 paul@971     43 
  mail -> resourcerouter -> resourcehandler
 
 paul@971     44 
 
 paul@971     45 
  recipients -> personrouter;
 
 paul@971     46 
  recipients -> resourcerouter;
 
 paul@971     47 
 
 paul@971     48 
  personhandler -> scheduling;
 
 paul@971     49 
  resourcehandler -> scheduling;
 
 paul@971     50 
  scheduling -> freebusy;
 
 paul@971     51 
}
 
 paul@971     52 
}}}
 
 paul@971     53 
 
 paul@933     54 
== MTAs ==
 
 paul@933     55 
 
 paul@934     56 
Currently, imip-agent supports [[http://exim.org/|Exim]] and
 
 paul@934     57 
[[http://www.postfix.org/|Postfix]], although this support should be readily
 
 paul@934     58 
broadened, and offers configuration resources for these supported systems so
 
 paul@934     59 
as to allow imip-agent to be deployed within existing mail-sending and
 
 paul@934     60 
delivery infrastructures.
 
 paul@933     61 
 
 paul@933     62 
{{{#!table
 
 paul@933     63 
|| '''Identifying Recipients''' || '''Integrating imip-agent''' || '''Notes'''
 
 paul@933     64 
==
 
 paul@933     65 
'''Exim'''
 
 paul@933     66 
|| Routers identify recipients of mail that shall be handled by imip-agent
 
 paul@933     67 
|| Transports invoke imip-agent programs
 
 paul@934     68 
|| Exim is widely deployed as the default MTA for Debian. Consequently, it is
 
 paul@949     69 
.. desirable to support this software in imip-agent.
 
 paul@933     70 
==
 
 paul@933     71 
'''Postfix'''
 
 paul@934     72 
|| Virtual aliases identify recipients of mail that shall be handled by
 
 paul@934     73 
.. imip-agent
 
 paul@933     74 
|| Transports invoke imip-agent programs
 
 paul@933     75 
|| Postfix is also widely deployed and is sometimes preferred by administrators.
 
 paul@933     76 
}}}
 
 paul@933     77 
 
 paul@984     78 
Some hints on mail system configuration can be found in the [[/MTA|MTA guide]].
 
 paul@984     79 
 
 paul@933     80 
== Identification of Recipients ==
 
 paul@933     81 
 
 paul@934     82 
In principle, any mechanism supported by the MTA can be used to identify
 
 paul@934     83 
recipients; imip-agent does not employ identification mechanisms of its own.
 
 paul@934     84 
Thus, the task of identifying recipients is one of MTA configuration, with the
 
 paul@934     85 
following mechanisms tested:
 
 paul@933     86 
 
 paul@933     87 
{{{#!table
 
 paul@933     88 
'''Identification Mechanisms''' || '''Tested with...'''
 
 paul@933     89 
==
 
 paul@951     90 
[[/LDAP|LDAP]] || Exim, Postfix
 
 paul@933     91 
==
 
 paul@951     92 
[[/Simple|Simple (list-based identification)]] || Exim, Postfix
 
 paul@933     93 
}}}
 
 paul@933     94 
 
 paul@989     95 
It is worth repeating that imip-agent does not try and validate users. Once
 
 paul@989     96 
the MTA has decided that a recipient can actually receive a message, and once
 
 paul@989     97 
that message is passed to one of the [[../AgentPrograms|agent programs]], the
 
 paul@989     98 
software will process that message and record information for the recipient in
 
 paul@989     99 
the [[../FilesystemUsage|filesystem structures]] for the user.
 
 paul@989    100 
 
 paul@989    101 
See the [[../Usage|usage guide]] for information on preparing data stores for
 
 paul@989    102 
users in advance of any mail being received for them.
 
 paul@989    103 
 
 paul@969    104 
=== The Calendar System Address ===
 
 paul@969    105 
 
 paul@969    106 
Since imip-agent may send messages on behalf of calendar users, the address
 
 paul@969    107 
it uses to do so must be recognised by the MTA. This may be done by adding
 
 paul@969    108 
an entry to the `/etc/aliases` file such as the one defined in the
 
 paul@969    109 
`conf/aliases.example` file:
 
 paul@969    110 
 
 paul@969    111 
{{{
 
 paul@969    112 
calendar: root
 
 paul@969    113 
}}}
 
 paul@969    114 
 
 paul@969    115 
More suitable routing can be defined as desired. See the `MESSAGE_SENDER`
 
 paul@969    116 
setting defined in the `config.py` file described in the
 
 paul@969    117 
[[../Configuration|configuration guide]].
 
 paul@969    118 
 
 paul@955    119 
== Invoking the Agent Programs ==
 
 paul@955    120 
 
 paul@955    121 
Regardless of identification or delivery mechanisms, the imip-agent software
 
 paul@955    122 
must be integrated into the mail processing pipeline so that messages can be
 
 paul@955    123 
interpreted and processed. This is done by configuring the MTA's
 
 paul@955    124 
[[/Transports|transport mechanisms]].
 
 paul@955    125 
 
 paul@933    126 
== Delivery ==
 
 paul@933    127 
 
 paul@934    128 
To deliver messages to their ultimate recipients after having processed them,
 
 paul@934    129 
imip-agent currently employs either local SMTP connections or
 
 paul@934    130 
[[https://tools.ietf.org/html/rfc2033|LMTP]]. There is nothing in principle
 
 paul@934    131 
preventing imip-agent from also supporting other common delivery mechanisms,
 
 paul@955    132 
however.
 
 paul@955    133 
 
 paul@955    134 
{{{#!table
 
 paul@955    135 
'''Delivery Mechanisms''' || '''Tested with...'''
 
 paul@955    136 
==
 
 paul@955    137 
[[/LocalSMTP|Local SMTP]] || Exim, Postfix
 
 paul@955    138 
==
 
 paul@955    139 
[[/LMTP|LMTP]]            || Exim, Postfix
 
 paul@955    140 
}}}
 
 paul@971    141 
 
 paul@971    142 
See the [[../MailboxIntegration|mailbox integration guide]] for a brief
 
 paul@971    143 
overview of configuring mail storage solutions.