imip-agent

README.txt

334:d44eb4aa42ac
2015-02-12 Paul Boddie Added initial support for receiving and accessing recurring event instances. recurring-events
     1 imip-agent
     2 ==========
     3 
     4 This software implements an agent that can interpret e-mail messages
     5 containing calendar information, maintain availability records for scheduling
     6 participants, act on behalf of resources and other entities that need to
     7 participate in scheduling, and support user interfaces for end-users whose
     8 e-mail programs do not understand calendar data.
     9 
    10 Getting Started
    11 ===============
    12 
    13 Eventually, this information should be incorporated into packages for various
    14 operating system distributions, and these instructions should be largely
    15 superfluous for most users.
    16 
    17 System User and Filesystem Access
    18 ---------------------------------
    19 
    20 A system group needs to be created for LMTP delivery and for certain users to
    21 share resources:
    22 
    23   addgroup lmtp
    24 
    25 This group should be employed for LMTP delivery by systems like Cyrus and
    26 Dovecot. See the section on configuring mail systems for delivery for more
    27 information.
    28 
    29 A system user needs to be created and to belong to certain groups in order to
    30 deliver messages to mail stores and to publish resources on the Web:
    31 
    32   useradd -d /var/lib/imip-agent -m -U -G lmtp,www-data -r imip-agent
    33 
    34 Store details and published resources need to be accessible by the imip-agent
    35 and www-data users. Thus, www-data also needs to belong to the lmtp group:
    36 
    37   adduser www-data lmtp
    38 
    39 Stored and published data is then initialised as follows:
    40 
    41   mkdir /var/lib/imip-agent/store /var/lib/imip-agent/preferences
    42   mkdir /var/www/imip-agent/static
    43   chown imip-agent /var/lib/imip-agent/store /var/lib/imip-agent/preferences
    44   chown imip-agent /var/www/imip-agent/static
    45   chgrp lmtp /var/lib/imip-agent/store /var/lib/imip-agent/preferences
    46   chgrp lmtp /var/www/imip-agent/static
    47   chmod g+ws /var/lib/imip-agent/store /var/lib/imip-agent/preferences
    48   chmod g+ws /var/www/imip-agent/static
    49 
    50 Here, the setgid flag should ensure that new files and directories have the
    51 appropriate group associated with them.
    52 
    53 Fixing ownership can be done as follows:
    54 
    55   chown -R imip-agent /var/lib/imip-agent
    56   chgrp -R imip-agent /var/lib/imip-agent
    57   chown -R imip-agent /var/lib/imip-agent/store /var/lib/imip-agent/preferences
    58   chown -R imip-agent /var/www/imip-agent/static
    59   chgrp -R lmtp /var/lib/imip-agent/store /var/lib/imip-agent/preferences
    60   chgrp -R lmtp /var/www/imip-agent/static
    61   chmod -R g+w /var/lib/imip-agent/store /var/lib/imip-agent/preferences
    62   chmod -R g+w /var/www/imip-agent/static
    63 
    64 Installing the Software
    65 -----------------------
    66 
    67 The tools/install.sh script should install the software in appropriate
    68 locations. See the prerequisites below for other software that will be
    69 required.
    70 
    71 Configuring Other Software
    72 --------------------------
    73 
    74 The conf directory contains subdirectories for different systems:
    75 
    76   apache        Apache 2 site configuration for publishing resources
    77   exim          Exim 4 routing and transport configuration
    78   postfix       Postfix routing and transport configuration
    79 
    80 Either Exim or Postfix can be chosen as a mail system supporting the agent.
    81 
    82 Configuring Mail Systems for the Agent
    83 --------------------------------------
    84 
    85 The essential aspect of mail system configuration involves mail transports and
    86 the integration of agent programs into the mail processing pipeline. Thus, the
    87 following files are of particular interest:
    88 
    89 For Exim (in conf/exim)...
    90 
    91   30_exim4-config_people                Integration of agent programs
    92   30_exim4-config_people_outgoing       ...
    93   30_exim4-config_resources             ...
    94 
    95 For Postfix (in conf/postfix)...
    96 
    97   master.cf.items                       Integration of agent programs (for
    98                                         inclusion in master.cf)
    99   transport                             Configuration of agent transports
   100   virtual                               Configuration of outgoing mail routing
   101 
   102 Such files need adjusting for the deployment environment so that, for example,
   103 the example.com domain would be replaced with a suitable value.
   104 
   105 Where $lmtp_socket is employed, a suitable filesystem path is required; see
   106 below for a discussion of LMTP and mail delivery.
   107 
   108 Configuring Mail Systems for Mail Recipients
   109 --------------------------------------------
   110 
   111 The software should operate independently of the way mail recipients are
   112 identified in any given mail system, and thus does not dictate things such as
   113 routing or account querying. However, example configuration files are provided
   114 that demonstrate the use of LDAP to identify mail recipients:
   115 
   116 For Exim (in conf/exim)...
   117 
   118   010_exim4-config_people_outgoing          Defines recipients and outgoing
   119                                             mail routing
   120   890_exim4-config_ldap_people              ...
   121   890_exim4-config_ldap_resources           ...
   122 
   123 For Postfix with LDAP (in conf/postfix/ldap)...
   124 
   125   main.cf.example                           Defines recipients and outgoing
   126                                             mail routing (for inclusion in
   127                                             main.cf)
   128 
   129   virtual_alias_maps_people.cf              Defines recipients and outgoing
   130   virtual_alias_maps_people_outgoing.cf     mail routing
   131   virtual_alias_maps_resources.cf           ...
   132 
   133 For Postfix without LDAP (in conf/postfix/simple)...
   134 
   135   main.cf.example                           Defines recipients and outgoing
   136                                             mail routing (for inclusion in
   137                                             main.cf)
   138 
   139   virtual_alias_maps_people                 Defines recipients and outgoing
   140   virtual_alias_maps_people_outgoing        mail routing
   141   virtual_alias_maps_resources              ...
   142 
   143 The above recipient identification configuration examples can be disregarded
   144 in favour of other ways of defining mail recipients, subject to the needs of
   145 any given environment.
   146 
   147 LDAP Representations for Mail Recipients
   148 ----------------------------------------
   149 
   150 Relevant LDAP resources for structuring recipient information include the
   151 following:
   152 
   153   RFC 4524                                  Defines the mail attribute
   154   http://tools.ietf.org/html/rfc4524
   155 
   156   RFC 2798                                  Defines the inetOrgPerson object
   157   http://tools.ietf.org/html/rfc2798        class
   158 
   159   RFC 2739                                  Defines the calEntry object class
   160   https://tools.ietf.org/html/rfc2739       supporting calFBURL
   161 
   162 An additional draft RFC describes the mailRecipient object class:
   163 
   164   https://tools.ietf.org/html/draft-lachman-ldap-mail-routing-03
   165 
   166 Resource schemas for LDAP are not effectively standardised for the purposes of
   167 this software. A useful object class, inetResource, was defined for the
   168 iPlanet Calendar Server:
   169 
   170   http://docs.oracle.com/cd/E19566-01/819-4437/6n6jckqrf/index.html#anocg
   171   http://docs.oracle.com/cd/E19566-01/819-4437/6n6jckqr8/index.html
   172 
   173 Although Kolab maintains notions of resources, they are tied up with the
   174 notion of a shared folder and the kolabSharedFolder object class, although the
   175 mailRecipient object class is employed by resources in Kolab.
   176 
   177 Configuring Mail Systems for Mail Delivery
   178 ------------------------------------------
   179 
   180 The agent software assumes that delivery of mail to recipients may be
   181 performed using LMTP to a suitable mailbox provider. This is largely beyond
   182 the scope of this document, but systems such as Cyrus and Dovecot can be
   183 configured to provide a Unix domain socket offering support for LMTP
   184 connections.
   185 
   186 For Cyrus, the following bug report is pertinent:
   187 
   188 https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=494746
   189 
   190 A permanent change in permissions on the Cyrus LMTP socket is therefore
   191 required to make delivery available to the lmtp group:
   192 
   193   dpkg-statoverride --force --update --add \
   194     cyrus lmtp 750 /var/run/cyrus/socket
   195 
   196 Prerequisites
   197 -------------
   198 
   199 Depending on the mail transport agent (MTA) chosen, the following packages are
   200 required for this software to work on Debian systems:
   201 
   202   Exim:    exim4-daemon-heavy
   203   Postfix: postfix postfix-ldap
   204 
   205 The software itself requires the following packages:
   206 
   207   pytz:    python-tz
   208 
   209 The management Web interface requires the following packages:
   210 
   211   Babel:   python-babel