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 user needs to be created and to belong to certain groups in order to
21 deliver messages to mail stores and to publish resources on the Web:
22
23 useradd -d /var/lib/imip-agent -m -U -G lmtp,www-data -r imip-agent
24
25 If the lmtp group does not exist, it should be created and be employed for
26 LMTP delivery to systems like Cyrus and Dovecot.
27
28 Store details and published resources need to be accessible by the imip-agent
29 and www-data users:
30
31 mkdir /var/lib/imip-agent/store /var/lib/imip-agent/preferences
32 mkdir /var/www/imip-agent/static
33 chown imip-agent /var/lib/imip-agent/store /var/lib/imip-agent/preferences
34 chown imip-agent /var/www/imip-agent/static
35 chgrp www-data /var/lib/imip-agent/store /var/lib/imip-agent/preferences
36 chgrp www-data /var/www/imip-agent/static
37 chmod g+ws /var/lib/imip-agent/store /var/lib/imip-agent/preferences
38 chmod g+ws /var/www/imip-agent/static
39
40 Here, the setgid flag should ensure that new files and directories have the
41 appropriate group associated with them.
42
43 Fixing ownership can be done as follows:
44
45 chown -R imip-agent /var/lib/imip-agent
46 chgrp -R imip-agent /var/lib/imip-agent
47 chown -R imip-agent /var/lib/imip-agent/store /var/lib/imip-agent/preferences
48 chown -R imip-agent /var/www/imip-agent/static
49 chgrp -R www-data /var/lib/imip-agent/store /var/lib/imip-agent/preferences
50 chgrp -R www-data /var/www/imip-agent/static
51 chmod -R g+w /var/lib/imip-agent/store /var/lib/imip-agent/preferences
52 chmod -R g+w /var/www/imip-agent/static
53
54 Installing the Software
55 -----------------------
56
57 The tools/install.sh script should install the software in appropriate
58 locations. See the prerequisites below for other software that will be
59 required.
60
61 Configuring Other Software
62 --------------------------
63
64 The conf directory contains subdirectories for different systems:
65
66 apache Apache 2 site configuration for publishing resources
67 exim Exim 4 routing and transport configuration
68 postfix Postfix routing and transport configuration
69
70 Either Exim or Postfix can be chosen as a mail system supporting the agent.
71
72 Configuring Mail Systems for the Agent
73 --------------------------------------
74
75 The essential aspect of mail system configuration involves mail transports and
76 the integration of agent programs into the mail processing pipeline. Thus, the
77 following files are of particular interest:
78
79 For Exim (in conf/exim)...
80
81 30_exim4-config_people Integration of agent programs
82 30_exim4-config_people_outgoing ...
83 30_exim4-config_resources ...
84
85 For Postfix (in conf/postfix)...
86
87 master.cf.items Integration of agent programs (for
88 inclusion in master.cf)
89 transport Configuration of agent transports
90 virtual Configuration of outgoing mail routing
91
92 Such files need adjusting for the deployment environment so that, for example,
93 the example.com domain would be replaced with a suitable value.
94
95 Where $lmtp_socket is employed, a suitable filesystem path is required; see
96 below for a discussion of LMTP and mail delivery.
97
98 Configuring Mail Systems for Mail Recipients
99 --------------------------------------------
100
101 The software should operate independently of the way mail recipients are
102 identified in any given mail system, and thus does not dictate things such as
103 routing or account querying. However, example configuration files are provided
104 that demonstrate the use of LDAP to identify mail recipients:
105
106 For Exim (in conf/exim)...
107
108 010_exim4-config_people_outgoing Defines recipients and outgoing
109 mail routing
110 890_exim4-config_ldap_people ...
111 890_exim4-config_ldap_resources ...
112
113 For Postfix with LDAP (in conf/postfix/ldap)...
114
115 main.cf.example Defines recipients and outgoing
116 mail routing (for inclusion in
117 main.cf)
118
119 local_recipient_maps.cf Defines local virtual recipients
120 virtual_alias_maps_people.cf
121 virtual_alias_maps_people_outgoing.cf
122 virtual_alias_maps_resources.cf
123
124 With the exception of the sender_bcc_maps setting in Postfix's main.cf, the
125 above recipient identification configuration examples can be disregarded in
126 favour of other ways of defining mail recipients, subject to the needs of any
127 given environment.
128
129 LDAP Representations for Mail Recipients
130 ----------------------------------------
131
132 Relevant LDAP resources for structuring recipient information include the
133 following:
134
135 RFC 4524 Defines the mail attribute
136 http://tools.ietf.org/html/rfc4524
137
138 RFC 2798 Defines the inetOrgPerson object
139 http://tools.ietf.org/html/rfc2798 class
140
141 RFC 2739 Defines the calEntry object class
142 https://tools.ietf.org/html/rfc2739 supporting calFBURL
143
144 An additional draft RFC describes the mailRecipient object class:
145
146 https://tools.ietf.org/html/draft-lachman-ldap-mail-routing-03
147
148 Resource schemas for LDAP are not effectively standardised for the purposes of
149 this software. A useful object class, inetResource, was defined for the
150 iPlanet Calendar Server:
151
152 http://docs.oracle.com/cd/E19566-01/819-4437/6n6jckqrf/index.html#anocg
153 http://docs.oracle.com/cd/E19566-01/819-4437/6n6jckqr8/index.html
154
155 Although Kolab maintains notions of resources, they are tied up with the
156 notion of a shared folder and the kolabSharedFolder object class, although the
157 mailRecipient object class is employed by resources in Kolab.
158
159 Configuring Mail Systems for Mail Delivery
160 ------------------------------------------
161
162 The agent software assumes that delivery of mail to recipients may be
163 performed using LMTP to a suitable mailbox provider. This is largely beyond
164 the scope of this document, but systems such as Cyrus and Dovecot can be
165 configured to provide a Unix domain socket offering support for LMTP
166 connections.
167
168 Prerequisites
169 -------------
170
171 Depending on the mail transport agent (MTA) chosen, the following packages are
172 required for this software to work on Debian systems:
173
174 Exim: exim4-daemon-heavy
175 Postfix: postfix postfix-ldap
176
177 The software itself requires the following packages:
178
179 pytz: python-tz
180
181 The management Web interface requires the following packages:
182
183 Babel: python-babel