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 A system group needs to be created for LMTP delivery and for certain users to
21 share resources:
22
23 addgroup lmtp
24
25 This group should be employed for LMTP delivery by systems like Cyrus and
26 Dovecot. See the section on configuring mail systems for delivery for more
27 information.
28
29 A system user needs to be created and to belong to certain groups in order to
30 deliver messages to mail stores and to publish resources on the Web:
31
32 useradd -d /var/lib/imip-agent -m -U -G lmtp,www-data -r imip-agent
33
34 Store details and published resources need to be accessible by the imip-agent
35 and www-data users. Thus, www-data also needs to belong to the lmtp group:
36
37 adduser www-data lmtp
38
39 Stored and published data is then initialised using the tools/init.sh script.
40 The script employs the setgid flag on the directories initialised for stored
41 and published data so that new files and directories have the appropriate
42 group associated with them.
43
44 Fixing ownership can be done using the tools/fix.sh script, in case some form
45 of modification has altered the ownership or membership of the created files
46 and directories.
47
48 Installing the Software
49 -----------------------
50
51 The tools/install.sh script should install the software in appropriate
52 locations. See the prerequisites below for other software that will be
53 required.
54
55 Configuring Other Software
56 --------------------------
57
58 The conf directory contains subdirectories for different systems:
59
60 apache Apache 2 site configuration for publishing resources
61 cron Cron command scheduling for free/busy updates
62 exim Exim 4 routing and transport configuration
63 postfix Postfix routing and transport configuration
64
65 Either Exim or Postfix can be chosen as a mail system supporting the agent.
66
67 Configuring Mail Systems for the Agent
68 --------------------------------------
69
70 The essential aspect of mail system configuration involves mail transports and
71 the integration of agent programs into the mail processing pipeline. Thus, the
72 following files are of particular interest:
73
74 For Exim (in conf/exim)...
75
76 30_exim4-config_people Integration of agent programs
77 30_exim4-config_people_outgoing ...
78 30_exim4-config_resources ...
79
80 For Postfix (in conf/postfix)...
81
82 master.cf.items Integration of agent programs (for
83 inclusion in master.cf)
84 transport Configuration of agent transports
85 virtual Configuration of outgoing mail routing
86
87 Such files need adjusting for the deployment environment so that, for example,
88 the example.com domain would be replaced with a suitable value.
89
90 Where $lmtp_socket is employed, a suitable filesystem path is required; see
91 below for a discussion of LMTP and mail delivery.
92
93 Configuring Mail Systems for Mail Recipients
94 --------------------------------------------
95
96 The software should operate independently of the way mail recipients are
97 identified in any given mail system, and thus does not dictate things such as
98 routing or account querying. However, example configuration files are provided
99 that demonstrate the use of LDAP to identify mail recipients:
100
101 For Exim (in conf/exim)...
102
103 010_exim4-config_people_outgoing Defines recipients and outgoing
104 mail routing
105 890_exim4-config_ldap_people ...
106 890_exim4-config_ldap_resources ...
107
108 For Postfix with LDAP (in conf/postfix/ldap)...
109
110 main.cf.example Defines recipients and outgoing
111 mail routing (for inclusion in
112 main.cf)
113
114 virtual_alias_maps_people.cf Defines recipients and outgoing
115 virtual_alias_maps_people_outgoing.cf mail routing
116 virtual_alias_maps_resources.cf ...
117
118 Since the use of LDAP can be somewhat challenging and also excessive in some
119 situations, examples of maintaining recipient information using a simpler
120 approach are provided:
121
122 For Postfix without LDAP (in conf/postfix/simple)...
123
124 main.cf.example Defines recipients and outgoing
125 mail routing (for inclusion in
126 main.cf)
127
128 virtual_alias_maps Defines recipients and outgoing
129 virtual_alias_maps_people_outgoing mail routing
130
131 In this simpler environment, recipient details must be manually edited in the
132 virtual alias map files, but this permits a very transparent way of
133 administering the system. To add support for delivery to local mailboxes, the
134 following alternative to virtual_alias_maps is provided as an example:
135
136 virtual_alias_maps_local Defines recipients and local users
137
138 Naturally, the above recipient identification configuration examples can be
139 disregarded in favour of other ways of defining mail recipients, subject to
140 the needs of any given environment.
141
142 LDAP Representations for Mail Recipients
143 ----------------------------------------
144
145 Relevant LDAP resources for structuring recipient information include the
146 following:
147
148 RFC 4524 Defines the mail attribute
149 http://tools.ietf.org/html/rfc4524
150
151 RFC 2798 Defines the inetOrgPerson object
152 http://tools.ietf.org/html/rfc2798 class
153
154 RFC 2739 Defines the calEntry object class
155 https://tools.ietf.org/html/rfc2739 supporting calFBURL
156
157 An additional draft RFC describes the mailRecipient object class:
158
159 https://tools.ietf.org/html/draft-lachman-ldap-mail-routing-03
160
161 Resource schemas for LDAP are not effectively standardised for the purposes of
162 this software. A useful object class, inetResource, was defined for the
163 iPlanet Calendar Server:
164
165 http://docs.oracle.com/cd/E19566-01/819-4437/6n6jckqrf/index.html#anocg
166 http://docs.oracle.com/cd/E19566-01/819-4437/6n6jckqr8/index.html
167
168 Although Kolab maintains notions of resources, they are tied up with the
169 notion of a shared folder and the kolabSharedFolder object class, although the
170 mailRecipient object class is employed by resources in Kolab.
171
172 Configuring Mail Systems for Mail Delivery
173 ------------------------------------------
174
175 The agent software assumes that delivery of mail to recipients may be
176 performed using LMTP to a suitable mailbox provider. This is largely beyond
177 the scope of this document, but systems such as Cyrus and Dovecot can be
178 configured to provide a Unix domain socket offering support for LMTP
179 connections.
180
181 For Cyrus, the following bug report is pertinent:
182
183 https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=494746
184
185 A permanent change in permissions on the Cyrus LMTP socket is therefore
186 required to make delivery available to the lmtp group:
187
188 dpkg-statoverride --force --update --add \
189 cyrus lmtp 750 /var/run/cyrus/socket
190
191 Configuring Cron for Free/Busy Updates
192 --------------------------------------
193
194 The periods occupied by recurring events are not expanded beyond a certain
195 window of time by imip-agent. As a consequence, free/busy collections need to
196 be progressively expanded over time to include periods occupied by such events
197 that were not previously recorded in those collections.
198
199 The conf/cron/cron.daily/imip-agent file contains commands that update
200 free/busy collections for all known users, and this should be copied to the
201 appropriate destination. For example:
202
203 cp conf/cron/cron.daily/imip-agent /etc/cron.daily/
204
205 Where frequency-specific directories are not supported by cron on a system, a
206 crontab entry of the appropriate format is required instead.
207
208 Prerequisites
209 -------------
210
211 Depending on the mail transport agent (MTA) chosen, the following packages are
212 required for this software to work on Debian systems:
213
214 Exim: exim4-daemon-heavy
215 Postfix: postfix postfix-ldap
216
217 The software itself requires the following packages:
218
219 pytz: python-tz
220
221 The management Web interface requires the following packages:
222
223 Babel: python-babel
