imip-agent

Annotated README.txt

147:ee2bd0ee8f55
145:35850f0a96e0
144:4d19192e3cf1
2014-12-20 Paul Boddie file changeset files shortlog Removed Kolab schema references from resource searches.
paul@102 1 
imip-agent
paul@102 2 
==========
paul@102 3 
 
 paul@102      4 
This software implements an agent that can interpret e-mail messages

 
 paul@102      5 
containing calendar information, maintain availability records for scheduling

 
 paul@102      6 
participants, act on behalf of resources and other entities that need to

 
 paul@102      7 
participate in scheduling, and support user interfaces for end-users whose

 
 paul@102      8 
e-mail programs do not understand calendar data.

 
 paul@102      9 
 
 paul@102     10 
Getting Started

 
 paul@102     11 
===============

 
 paul@102     12 
 
 paul@102     13 
Eventually, this information should be incorporated into packages for various

 
 paul@102     14 
operating system distributions, and these instructions should be largely

 
 paul@102     15 
superfluous for most users.

 
 paul@102     16 
 
 paul@102     17 
System User and Filesystem Access

 
 paul@102     18 
---------------------------------

 
 paul@102     19 
 
 paul@102     20 
A system user needs to be created and to belong to certain groups in order to

 
 paul@102     21 
deliver messages to mail stores and to publish resources on the Web:

 
 paul@102     22 
 
 paul@102     23 
  useradd -d /var/lib/imip-agent -m -U -G lmtp,www-data -r imip-agent

 
 paul@102     24 
 
 paul@102     25 
If the lmtp group does not exist, it should be created and be employed for

 
 paul@102     26 
LMTP delivery to systems like Cyrus and Dovecot.

 
 paul@102     27 
 
 paul@102     28 
Store details and published resources need to be accessible by the imip-agent

 
 paul@102     29 
and www-data users:

 
 paul@102     30 
 
 paul@102     31 
  mkdir /var/lib/imip-agent/store /var/www/imip-agent/static

 
 paul@102     32 
  chown imip-agent /var/lib/imip-agent/store /var/www/imip-agent/static

 
 paul@102     33 
  chgrp www-data /var/lib/imip-agent/store /var/www/imip-agent/static

 
 paul@102     34 
  chmod g+s /var/lib/imip-agent/store /var/www/imip-agent/static

 
 paul@102     35 
 
 paul@102     36 
Here, the setgid flag should ensure that new files and directories have the

 
 paul@102     37 
appropriate group associated with them.

 
 paul@102     38 
 
 paul@102     39 
Fixing ownership can be done as follows:

 
 paul@102     40 
 
 paul@102     41 
  chown -R imip-agent /var/lib/imip-agent

 
 paul@102     42 
  chgrp -R imip-agent /var/lib/imip-agent

 
 paul@102     43 
  chown -R imip-agent /var/lib/imip-agent/store /var/www/imip-agent/static

 
 paul@102     44 
  chgrp -R www-data /var/lib/imip-agent/store /var/www/imip-agent/static

 
 paul@102     45 
  chmod -R g+w /var/lib/imip-agent/store /var/www/imip-agent/static

 
 paul@102     46 
 
 paul@102     47 
Installing the Software

 
 paul@102     48 
-----------------------

 
 paul@102     49 
 
 paul@102     50 
The tools/install.sh script should install the software in appropriate

 
 paul@102     51 
locations.

 
 paul@102     52 
 
 paul@102     53 
Configuring Other Software

 
 paul@102     54 
--------------------------

 
 paul@102     55 
 
 paul@102     56 
The conf directory contains subdirectories for different systems:

 
 paul@102     57 
 
 paul@102     58 
  apache        Apache 2 site configuration for publishing resources

 
 paul@102     59 
  exim          Exim 4 routing and transport configuration

 
 paul@102     60 
  postfix       Postfix routing and transport configuration

 
 paul@102     61 
 
 paul@102     62 
Either Exim or Postfix can be chosen as a mail system supporting the agent.

 
 paul@143     63 
 
 paul@143     64 
Configuring Mail Systems for the Agent

 
 paul@143     65 
--------------------------------------

 
 paul@143     66 
 
 paul@143     67 
The essential aspect of mail system configuration involves mail transports and

 
 paul@143     68 
the integration of agent programs into the mail processing pipeline. Thus, the

 
 paul@143     69 
following files are of particular interest:

 
 paul@143     70 
 
 paul@143     71 
For Exim...

 
 paul@143     72 
 
 paul@143     73 
  conf/exim/30_exim4-config_people              Integration of agent programs

 
 paul@143     74 
  conf/exim/30_exim4-config_people_outgoing     ...

 
 paul@143     75 
  conf/exim/30_exim4-config_resources           ...

 
 paul@143     76 
 
 paul@143     77 
For Postfix...

 
 paul@143     78 
 
 paul@143     79 
  conf/postfix/master.cf.items      Integration of agent programs (for

 
 paul@143     80 
                                    inclusion in master.cf)

 
 paul@143     81 
  conf/postfix/transport            Configuration of agent transports

 
 paul@143     82 
  conf/postfix/virtual              Configuration of outgoing mail routing

 
 paul@143     83 
 
 paul@143     84 
Such files need adjusting for the deployment environment so that, for example,

 
 paul@143     85 
the example.com domain would be replaced with a suitable value.

 
 paul@143     86 
 
 paul@143     87 
Where $lmtp_socket is employed, a suitable filesystem path is required; see

 
 paul@143     88 
below for a discussion of LMTP and mail delivery.

 
 paul@143     89 
 
 paul@143     90 
Configuring Mail Systems for Mail Recipients

 
 paul@143     91 
--------------------------------------------

 
 paul@143     92 
 
 paul@143     93 
The software should operate independently of the way mail recipients are

 
 paul@143     94 
identified in any given mail system, and thus does not dictate things such as

 
 paul@143     95 
routing or account querying. However, example configuration files are provided

 
 paul@143     96 
that demonstrate the use of LDAP to identify mail recipients:

 
 paul@143     97 
 
 paul@143     98 
For Exim...

 
 paul@143     99 
 
 paul@143    100 
  conf/exim/010_exim4-config_people_outgoing    Defines recipients and

 
 paul@143    101 
                                                outgoing mail routing

 
 paul@143    102 
  conf/exim/890_exim4-config_ldap_people        ...

 
 paul@143    103 
  conf/exim/890_exim4-config_ldap_resources     ...

 
 paul@143    104 
 
 paul@143    105 
For Postfix...

 
 paul@143    106 
 
 paul@143    107 
  conf/postfix/local_recipient_maps.cf          Defines local virtual

 
 paul@143    108 
                                                recipients

 
 paul@143    109 
  conf/postfix/main.cf.example                  Defines recipients and outgoing

 
 paul@143    110 
                                                mail routing (for inclusion in

 
 paul@143    111 
                                                main.cf)

 
 paul@143    112 
  conf/postfix/virtual_alias_maps_people.cf

 
 paul@143    113 
  conf/postfix/virtual_alias_maps_people_outgoing.cf

 
 paul@143    114 
  conf/postfix/virtual_alias_maps_resources.cf

 
 paul@143    115 
 
 paul@143    116 
With the exception of the sender_bcc_maps setting in Postfix's main.cf, the

 
 paul@143    117 
above recipient identification configuration examples can be disregarded in

 
 paul@143    118 
favour of other ways of defining mail recipients, subject to the needs of any

 
 paul@143    119 
given environment.

 
 paul@143    120 
 
 paul@144    121 
LDAP Representations for Mail Recipients

 
 paul@144    122 
----------------------------------------

 
 paul@144    123 
 
 paul@144    124 
Relevant LDAP resources for structuring recipient information include the

 
 paul@144    125 
following:

 
 paul@144    126 
 
 paul@144    127 
  RFC 4524  http://tools.ietf.org/html/rfc4524  Defines the mail attribute

 
 paul@144    128 
  RFC 2798  http://tools.ietf.org/html/rfc2798  Defines the inetOrgPerson

 
 paul@144    129 
                                                object class

 
 paul@144    130 
  RFC 2739  https://tools.ietf.org/html/rfc2739 Defines the calEntry object

 
 paul@144    131 
                                                class supporting calFBURL

 
 paul@144    132 
 
 paul@144    133 
An additional draft RFC describes the mailRecipient object class:

 
 paul@144    134 
 
 paul@144    135 
  https://tools.ietf.org/html/draft-lachman-ldap-mail-routing-03

 
 paul@144    136 
 
 paul@144    137 
Resource schemas for LDAP are not effectively standardised for the purposes of

 
 paul@145    138 
this software. A useful object class, inetResource, was defined for the

 
 paul@145    139 
iPlanet Calendar Server:

 
 paul@145    140 
 
 paul@145    141 
  http://docs.oracle.com/cd/E19566-01/819-4437/6n6jckqrf/index.html#anocg

 
 paul@145    142 
  http://docs.oracle.com/cd/E19566-01/819-4437/6n6jckqr8/index.html

 
 paul@145    143 
 
 paul@145    144 
Although Kolab maintains notions of resources, they are tied up with the

 
 paul@145    145 
notion of a shared folder and the kolabSharedFolder object class, although the

 
 paul@145    146 
mailRecipient object class is employed by resources in Kolab.

 
 paul@144    147 
 
 paul@143    148 
Configuring Mail Systems for Mail Delivery

 
 paul@143    149 
------------------------------------------

 
 paul@143    150 
 
 paul@143    151 
The agent software assumes that delivery of mail to recipients may be

 
 paul@143    152 
performed using LMTP to a suitable mailbox provider. This is largely beyond

 
 paul@143    153 
the scope of this document, but systems such as Cyrus and Dovecot can be

 
 paul@143    154 
configured to provide a Unix domain socket offering support for LMTP

 
 paul@143    155 
connections.

 
 paul@133    156 
 
 paul@133    157 
Prerequisites

 
 paul@133    158 
-------------

 
 paul@133    159 
 
 paul@133    160 
Depending on the mail transport agent (MTA) chosen, the following packages are

 
 paul@133    161 
required for this software to work on Debian systems:

 
 paul@133    162 
 
 paul@133    163 
  Exim:    exim4-daemon-heavy

 
 paul@133    164 
  Postfix: postfix postfix-ldap