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