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 Installing the Software
18 =======================
19
20 The tools/install.sh script should install the software in appropriate
21 locations. See the prerequisites below for other software that will be
22 required.
23
24 System User and Filesystem Access
25 =================================
26
27 The data handled by imip-agent needs to be accessible to other software,
28 notably mail handling software and Web server software. Two approaches are
29 described here: LMTP delivery and local SMTP delivery.
30
31 LMTP Delivery
32 -------------
33
34 Here, imip-agent's programs run in a way that permits LMTP delivery (requiring
35 suitable local privileges to communicate with the mail storage solution)
36 whilst allowing the Web server to read data written by those programs.
37
38 A system group needs to be created for LMTP delivery and for certain users to
39 share resources:
40
41 addgroup lmtp
42
43 This group should be employed for LMTP delivery by systems like Cyrus and
44 Dovecot. See the section on configuring mail systems for delivery for more
45 information.
46
47 A system user needs to be created and to belong to certain groups in order to
48 deliver messages to mail stores and to publish resources on the Web:
49
50 useradd -d /var/lib/imip-agent -m -U -G lmtp,www-data -r imip-agent
51
52 Store details and published resources need to be accessible by the imip-agent
53 and www-data users. Thus, www-data also needs to belong to the lmtp group:
54
55 adduser www-data lmtp
56
57 Stored and published data is then initialised using the tools/init.sh script.
58 The script employs the setgid flag on the directories initialised for stored
59 and published data so that new files and directories have the appropriate
60 group associated with them.
61
62 It should be possible to omit all arguments to the init.sh script, but it is
63 also worth reading the help message:
64
65 tools/init.sh --help
66
67 Fixing ownership can be done using the tools/fix.sh script, in case some form
68 of modification has altered the ownership or membership of the created files
69 and directories.
70
71 Local SMTP Delivery
72 -------------------
73
74 Here, imip-agent's programs run in a way that permits local SMTP delivery
75 (which merely needs the ability to connect to a local network service) whilst
76 allowing the Web server to read data written by those programs.
77
78 A system user needs to be created and to belong to certain groups in order to
79 deliver messages to mail stores and to publish resources on the Web:
80
81 useradd -d /var/lib/imip-agent -m -U -G www-data -r imip-agent
82
83 Again, the tools/init.sh script will initialise directories for stored and
84 published data. The tools/config.sh script should be edited and the group
85 redefined as follows:
86
87 IMIP_AGENT_GROUP=www-data
88
89 If already installed, the /etc/imip-agent/config.sh script should be edited
90 instead.
91
92 Configuring Other Software
93 ==========================
94
95 The conf directory contains subdirectories for different systems:
96
97 apache Apache 2 site configuration for publishing resources
98 cron Cron command scheduling for free/busy updates
99 exim Exim 4 routing and transport configuration
100 ldap Some LDAP-related resources
101 postfix Postfix routing and transport configuration
102
103 Either Exim or Postfix can be chosen as a mail system supporting the agent.
104
105 Configuring Mail Systems for the Agent
106 --------------------------------------
107
108 The essential aspect of mail system configuration involves mail transports and
109 the integration of agent programs into the mail processing pipeline. Thus, the
110 following files are of particular interest:
111
112 For Exim (in conf/exim)...
113
114 30_exim4-config_people Integration of agent programs
115 30_exim4-config_people_outgoing ...
116 30_exim4-config_resources ...
117
118 For Postfix (in conf/postfix)...
119
120 master.cf.items Integration of agent programs (for
121 inclusion in master.cf)
122 transport Configuration of agent transports
123 virtual Configuration of outgoing mail routing
124
125 Such files need adjusting for the deployment environment so that, for example,
126 the example.com domain would be replaced with a suitable value.
127
128 If local SMTP delivery is being used, the 30_exim4-config_people file (in
129 conf/exim) or the master.cf.items file (in conf/postfix) will need adjusting.
130 Where LMTP_SOCKET is employed, a suitable filesystem path is required; where
131 the lmtp system group is employed, it may be replaced with a different group.
132 See below for a discussion of LMTP and mail delivery.
133
134 Configuring Mail Systems for Mail Recipients
135 --------------------------------------------
136
137 The software should operate independently of the way mail recipients are
138 identified in any given mail system, and thus does not dictate things such as
139 routing or account querying. However, example configuration files are provided
140 that demonstrate the use of LDAP to identify mail recipients:
141
142
143 For Exim with LDAP (in conf/exim/ldap)...
144
145 010_exim4-config_ldap_people_outgoing Defines recipients and outgoing
146 mail routing
147 020_exim4-config_ldap_people ...
148 020_exim4-config_ldap_resources ...
149 020_exim4-config_ldap_people_outgoing_recipients
150
151
152 For Postfix with LDAP (in conf/postfix/ldap)...
153
154 main.cf.example Defines recipients and outgoing
155 mail routing (for inclusion in
156 main.cf)
157
158 virtual_alias_maps_people.cf Defines recipients and outgoing
159 virtual_alias_maps_people_outgoing.cf mail routing
160 virtual_alias_maps_resources.cf ...
161
162
163 Since the use of LDAP can be somewhat challenging and also excessive in some
164 situations, examples of maintaining recipient information using a simpler
165 approach are provided.
166
167 In this simpler environment, recipient details must be manually edited in the
168 virtual identity files, but this permits a very transparent way of
169 administering the system.
170
171
172 For Exim without LDAP (in conf/exim/simple)...
173
174 010_exim4-config_people_outgoing Defines recipients and outgoing
175 mail routing
176 020_exim4-config_people ...
177 020_exim4-config_resources ...
178 020_exim4-config_people_outgoing_recipients
179
180 virtual_people Defines recipient identities
181 virtual_people_outgoing_recipients belonging to known domains
182 virtual_resources ...
183
184 virtual_domains Defines recipient domains
185
186 To add support for delivery to local mailboxes, the following additional file
187 is provided as an example:
188
189 virtual_people_local Defines recipients and local users
190
191 And to route bounced messages back to the generic calendar address, an
192 addition to the /etc/aliases file is provided:
193
194 aliases.example Routes calendar to root
195
196
197 For Postfix without LDAP (in conf/postfix/simple)...
198
199 main.cf.example Defines recipients and outgoing
200 mail routing (for inclusion in
201 main.cf)
202
203 virtual_alias_maps Defines recipients and outgoing
204 virtual_alias_maps_people_outgoing mail routing
205
206 To add support for delivery to local mailboxes, the following alternative to
207 virtual_alias_maps is provided as an example:
208
209 virtual_alias_maps_local Defines recipients and local users
210
211
212 Naturally, the above recipient identification configuration examples can be
213 disregarded in favour of other ways of defining mail recipients, subject to
214 the needs of any given environment.
215
216 LDAP Representations for Mail Recipients
217 ----------------------------------------
218
219 Relevant LDAP resources for structuring recipient information include the
220 following:
221
222 RFC 4524 Defines the mail attribute
223 http://tools.ietf.org/html/rfc4524
224
225 RFC 2798 Defines the inetOrgPerson object
226 http://tools.ietf.org/html/rfc2798 class
227
228 RFC 2739 Defines the calEntry object class
229 https://tools.ietf.org/html/rfc2739 supporting calFBURL
230
231 An additional draft RFC describes the mailRecipient object class:
232
233 https://tools.ietf.org/html/draft-lachman-ldap-mail-routing-03
234
235 Resource schemas for LDAP are not effectively standardised for the purposes of
236 this software. A useful object class, inetResource, was defined for the
237 iPlanet Calendar Server:
238
239 http://docs.oracle.com/cd/E19566-01/819-4437/6n6jckqrf/index.html#anocg
240 http://docs.oracle.com/cd/E19566-01/819-4437/6n6jckqr8/index.html
241
242 Although Kolab maintains notions of resources, they are tied up with the
243 notion of a shared folder and the kolabSharedFolder object class, although the
244 mailRecipient object class is employed by resources in Kolab.
245
246 Configuring Mail Systems for Mail Delivery
247 ------------------------------------------
248
249 The agent software assumes that delivery of mail to recipients may be
250 performed either using local SMTP or by using LMTP to a suitable mailbox
251 provider.
252
253 If employing local SMTP, the burden of routing messages to suitable storage
254 becomes a configuration problem within the mail system itself, but given that
255 routing to local system users is typically supported "out of the box", this
256 can provide a usable solution with minimal effort.
257
258 Where the mail system must instead route messages to mailbox providers
259 employing LMTP, some more effort is required. For Exim, some sample
260 configuration files are provided in conf/exim/lmtp to route messages for local
261 users to LMTP endpoints.
262
263 By using LMTP from the agent software, the issue of configuring the mail
264 system to integrate with storage solutions is avoided, but then those
265 solutions must expose their LMTP interface appropriately.
266
267 Configuring Mail Storage Providers for LMTP
268 -------------------------------------------
269
270 Although this topic is largely beyond the scope of this document, systems such
271 as Cyrus and Dovecot can be configured to provide a Unix domain socket
272 offering support for LMTP connections.
273
274 For Cyrus, the following bug report is pertinent:
275
276 https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=494746
277
278 A permanent change in permissions on the Cyrus LMTP socket is therefore
279 required to make delivery available to the lmtp group:
280
281 dpkg-statoverride --force --update --add \
282 cyrus lmtp 750 /var/run/cyrus/socket
283
284 Configuring Cron for Free/Busy Updates
285 --------------------------------------
286
287 The periods occupied by recurring events are not expanded beyond a certain
288 window of time by imip-agent. As a consequence, free/busy collections need to
289 be progressively expanded over time to include periods occupied by such events
290 that were not previously recorded in those collections.
291
292 The conf/cron/cron.daily/imip-agent file contains commands that update
293 free/busy collections for all known users, and this should be copied to the
294 appropriate destination. For example:
295
296 cp conf/cron/cron.daily/imip-agent /etc/cron.daily/
297
298 Where frequency-specific directories are not supported by cron on a system, a
299 crontab entry of the appropriate format is required instead.
300
301 Configuring Web Servers for Free/Busy Publishing
302 ------------------------------------------------
303
304 Each user may request the publishing of their free/busy information by
305 configuring certain settings. The conf/apache/imip-agent.conf file provides a
306 configuration file for deployment with the Apache Web server software that
307 exposes a directory for Web publishing containing the published free/busy
308 information.
309
310 Access to free/busy information may not be moderated, but Web server
311 directives can be introduced to impose access controls. Mail programs that
312 wish to consult the free/busy information may have problems in dealing with
313 authentication mechanisms, however, and it may be regarded as acceptable in
314 certain environments to expose such information publicly or with
315 network-specific access constraints.
316
317 Configuring Web Servers for the Calendar Management Interface
318 -------------------------------------------------------------
319
320 A calendar management interface is provided to allow users to view and
321 interact with their calendars through the Web. The
322 conf/apache/imip-manager.conf file provides a configuration file for
323 deployment with the Apache Web server software that enables this interface.
324
325 The management interface is deployed as a CGI program, meaning that a suitable
326 module must be enabled in the Apache configuration. On Debian, this is done as
327 follows:
328
329 a2enmod cgi
330
331 Since such access to calendars should only be performed by identified
332 users, access controls are suggested in the configuration file. Modules
333 providing additional authentication support may need to be enabled. For
334 example, on Debian, the LDAP authentication/authorisation support is enabled
335 as follows:
336
337 a2enmod authnz_ldap
338
339 Prerequisites
340 =============
341
342 Depending on the mail transport agent (MTA) chosen, the following packages are
343 required for this software to work on Debian systems:
344
345 Exim: exim4-daemon-heavy
346 Postfix: postfix postfix-ldap
347
348 The software itself requires the following packages:
349
350 Python: python
351 pytz: python-tz
352
353 To update free/busy details periodically, the following software is
354 recommended:
355
356 Cron: cron
357
358 The management Web interface requires the following packages:
359
360 Apache: apache2
361 Babel: python-babel
362
363 Although not necessarily within the scope of the deployment of this software,
364 the following mail storage solutions would be used to receive and hold
365 messages:
366
367 Cyrus: cyrus-imapd
368 Dovecot: dovecot-imapd dovecot-ldap dovecot-lmtpd
369
370 Some test programs need additional programs provided by other packages:
371
372 envsubst: gettext-base