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. For example:
78
79 tools/init.sh imip-agent www-data
80
81 Installing the Software
82 =======================
83
84 The tools/install.sh script should install the software in appropriate
85 locations. See the prerequisites below for other software that will be
86 required.
87
88 Configuring Other Software
89 ==========================
90
91 The conf directory contains subdirectories for different systems:
92
93 apache Apache 2 site configuration for publishing resources
94 cron Cron command scheduling for free/busy updates
95 exim Exim 4 routing and transport configuration
96 postfix Postfix routing and transport configuration
97
98 Either Exim or Postfix can be chosen as a mail system supporting the agent.
99
100 Configuring Mail Systems for the Agent
101 --------------------------------------
102
103 The essential aspect of mail system configuration involves mail transports and
104 the integration of agent programs into the mail processing pipeline. Thus, the
105 following files are of particular interest:
106
107 For Exim (in conf/exim)...
108
109 30_exim4-config_people Integration of agent programs
110 30_exim4-config_people_outgoing ...
111 30_exim4-config_resources ...
112
113 For Postfix (in conf/postfix)...
114
115 master.cf.items Integration of agent programs (for
116 inclusion in master.cf)
117 transport Configuration of agent transports
118 virtual Configuration of outgoing mail routing
119
120 Such files need adjusting for the deployment environment so that, for example,
121 the example.com domain would be replaced with a suitable value.
122
123 Where $lmtp_socket is employed, a suitable filesystem path is required; see
124 below for a discussion of LMTP and mail delivery.
125
126 Configuring Mail Systems for Mail Recipients
127 --------------------------------------------
128
129 The software should operate independently of the way mail recipients are
130 identified in any given mail system, and thus does not dictate things such as
131 routing or account querying. However, example configuration files are provided
132 that demonstrate the use of LDAP to identify mail recipients:
133
134 For Exim (in conf/exim)...
135
136 010_exim4-config_people_outgoing Defines recipients and outgoing
137 mail routing
138 890_exim4-config_ldap_people ...
139 890_exim4-config_ldap_resources ...
140
141 For Postfix with LDAP (in conf/postfix/ldap)...
142
143 main.cf.example Defines recipients and outgoing
144 mail routing (for inclusion in
145 main.cf)
146
147 virtual_alias_maps_people.cf Defines recipients and outgoing
148 virtual_alias_maps_people_outgoing.cf mail routing
149 virtual_alias_maps_resources.cf ...
150
151 Since the use of LDAP can be somewhat challenging and also excessive in some
152 situations, examples of maintaining recipient information using a simpler
153 approach are provided:
154
155 For Postfix without LDAP (in conf/postfix/simple)...
156
157 main.cf.example Defines recipients and outgoing
158 mail routing (for inclusion in
159 main.cf)
160
161 virtual_alias_maps Defines recipients and outgoing
162 virtual_alias_maps_people_outgoing mail routing
163
164 In this simpler environment, recipient details must be manually edited in the
165 virtual alias map files, but this permits a very transparent way of
166 administering the system. To add support for delivery to local mailboxes, the
167 following alternative to virtual_alias_maps is provided as an example:
168
169 virtual_alias_maps_local Defines recipients and local users
170
171 Naturally, the above recipient identification configuration examples can be
172 disregarded in favour of other ways of defining mail recipients, subject to
173 the needs of any given environment.
174
175 LDAP Representations for Mail Recipients
176 ----------------------------------------
177
178 Relevant LDAP resources for structuring recipient information include the
179 following:
180
181 RFC 4524 Defines the mail attribute
182 http://tools.ietf.org/html/rfc4524
183
184 RFC 2798 Defines the inetOrgPerson object
185 http://tools.ietf.org/html/rfc2798 class
186
187 RFC 2739 Defines the calEntry object class
188 https://tools.ietf.org/html/rfc2739 supporting calFBURL
189
190 An additional draft RFC describes the mailRecipient object class:
191
192 https://tools.ietf.org/html/draft-lachman-ldap-mail-routing-03
193
194 Resource schemas for LDAP are not effectively standardised for the purposes of
195 this software. A useful object class, inetResource, was defined for the
196 iPlanet Calendar Server:
197
198 http://docs.oracle.com/cd/E19566-01/819-4437/6n6jckqrf/index.html#anocg
199 http://docs.oracle.com/cd/E19566-01/819-4437/6n6jckqr8/index.html
200
201 Although Kolab maintains notions of resources, they are tied up with the
202 notion of a shared folder and the kolabSharedFolder object class, although the
203 mailRecipient object class is employed by resources in Kolab.
204
205 Configuring Mail Systems for Mail Delivery
206 ------------------------------------------
207
208 The agent software assumes that delivery of mail to recipients may be
209 performed using LMTP to a suitable mailbox provider. This is largely beyond
210 the scope of this document, but systems such as Cyrus and Dovecot can be
211 configured to provide a Unix domain socket offering support for LMTP
212 connections.
213
214 For Cyrus, the following bug report is pertinent:
215
216 https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=494746
217
218 A permanent change in permissions on the Cyrus LMTP socket is therefore
219 required to make delivery available to the lmtp group:
220
221 dpkg-statoverride --force --update --add \
222 cyrus lmtp 750 /var/run/cyrus/socket
223
224 Configuring Cron for Free/Busy Updates
225 --------------------------------------
226
227 The periods occupied by recurring events are not expanded beyond a certain
228 window of time by imip-agent. As a consequence, free/busy collections need to
229 be progressively expanded over time to include periods occupied by such events
230 that were not previously recorded in those collections.
231
232 The conf/cron/cron.daily/imip-agent file contains commands that update
233 free/busy collections for all known users, and this should be copied to the
234 appropriate destination. For example:
235
236 cp conf/cron/cron.daily/imip-agent /etc/cron.daily/
237
238 Where frequency-specific directories are not supported by cron on a system, a
239 crontab entry of the appropriate format is required instead.
240
241 Configuring Web Servers for Free/Busy Publishing
242 ------------------------------------------------
243
244 Each user may request the publishing of their free/busy information by
245 configuring certain settings. The conf/apache/imip-agent.conf file provides a
246 configuration file for deployment with the Apache Web server software that
247 exposes a directory for Web publishing containing the published free/busy
248 information.
249
250 Access to free/busy information may not be moderated, but Web server
251 directives can be introduced to impose access controls. Mail programs that
252 wish to consult the free/busy information may have problems in dealing with
253 authentication mechanisms, however, and it may be regarded as acceptable in
254 certain environments to expose such information publicly or with
255 network-specific access constraints.
256
257 Configuring Web Servers for the Calendar Management Interface
258 -------------------------------------------------------------
259
260 A calendar management interface is provided to allow users to view and
261 interact with their calendars through the Web. The
262 conf/apache/imip-manager.conf file provides a configuration file for
263 deployment with the Apache Web server software that enables this interface.
264
265 Since such access to calendars should only be performed by identified
266 users, access controls are suggested in the configuration file.
267
268 Prerequisites
269 =============
270
271 Depending on the mail transport agent (MTA) chosen, the following packages are
272 required for this software to work on Debian systems:
273
274 Exim: exim4-daemon-heavy
275 Postfix: postfix postfix-ldap
276
277 The software itself requires the following packages:
278
279 pytz: python-tz
280
281 The management Web interface requires the following packages:
282
283 Babel: python-babel
