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