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