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 as follows:
40
41 mkdir /var/lib/imip-agent/store /var/lib/imip-agent/preferences
42 mkdir /var/www/imip-agent/static
43 chown imip-agent /var/lib/imip-agent/store /var/lib/imip-agent/preferences
44 chown imip-agent /var/www/imip-agent/static
45 chgrp lmtp /var/lib/imip-agent/store /var/lib/imip-agent/preferences
46 chgrp lmtp /var/www/imip-agent/static
47 chmod g+ws /var/lib/imip-agent/store /var/lib/imip-agent/preferences
48 chmod g+ws /var/www/imip-agent/static
49
50 Here, the setgid flag should ensure that new files and directories have the
51 appropriate group associated with them.
52
53 Fixing ownership can be done as follows:
54
55 chown -R imip-agent /var/lib/imip-agent
56 chgrp -R imip-agent /var/lib/imip-agent
57 chown -R imip-agent /var/lib/imip-agent/store /var/lib/imip-agent/preferences
58 chown -R imip-agent /var/www/imip-agent/static
59 chgrp -R lmtp /var/lib/imip-agent/store /var/lib/imip-agent/preferences
60 chgrp -R lmtp /var/www/imip-agent/static
61 chmod -R g+w /var/lib/imip-agent/store /var/lib/imip-agent/preferences
62 chmod -R g+w /var/www/imip-agent/static
63
64 Installing the Software
65 -----------------------
66
67 The tools/install.sh script should install the software in appropriate
68 locations. See the prerequisites below for other software that will be
69 required.
70
71 Configuring Other Software
72 --------------------------
73
74 The conf directory contains subdirectories for different systems:
75
76 apache Apache 2 site configuration for publishing resources
77 exim Exim 4 routing and transport configuration
78 postfix Postfix routing and transport configuration
79
80 Either Exim or Postfix can be chosen as a mail system supporting the agent.
81
82 Configuring Mail Systems for the Agent
83 --------------------------------------
84
85 The essential aspect of mail system configuration involves mail transports and
86 the integration of agent programs into the mail processing pipeline. Thus, the
87 following files are of particular interest:
88
89 For Exim (in conf/exim)...
90
91 30_exim4-config_people Integration of agent programs
92 30_exim4-config_people_outgoing ...
93 30_exim4-config_resources ...
94
95 For Postfix (in conf/postfix)...
96
97 master.cf.items Integration of agent programs (for
98 inclusion in master.cf)
99 transport Configuration of agent transports
100 virtual Configuration of outgoing mail routing
101
102 Such files need adjusting for the deployment environment so that, for example,
103 the example.com domain would be replaced with a suitable value.
104
105 Where $lmtp_socket is employed, a suitable filesystem path is required; see
106 below for a discussion of LMTP and mail delivery.
107
108 Configuring Mail Systems for Mail Recipients
109 --------------------------------------------
110
111 The software should operate independently of the way mail recipients are
112 identified in any given mail system, and thus does not dictate things such as
113 routing or account querying. However, example configuration files are provided
114 that demonstrate the use of LDAP to identify mail recipients:
115
116 For Exim (in conf/exim)...
117
118 010_exim4-config_people_outgoing Defines recipients and outgoing
119 mail routing
120 890_exim4-config_ldap_people ...
121 890_exim4-config_ldap_resources ...
122
123 For Postfix with LDAP (in conf/postfix/ldap)...
124
125 main.cf.example Defines recipients and outgoing
126 mail routing (for inclusion in
127 main.cf)
128
129 virtual_alias_maps_people.cf Defines recipients and outgoing
130 virtual_alias_maps_people_outgoing.cf mail routing
131 virtual_alias_maps_resources.cf ...
132
133 For Postfix without LDAP (in conf/postfix/simple)...
134
135 main.cf.example Defines recipients and outgoing
136 mail routing (for inclusion in
137 main.cf)
138
139 virtual_alias_maps_people Defines recipients and outgoing
140 virtual_alias_maps_people_outgoing mail routing
141 virtual_alias_maps_resources ...
142
143 The above recipient identification configuration examples can be disregarded
144 in favour of other ways of defining mail recipients, subject to the needs of
145 any given environment.
146
147 LDAP Representations for Mail Recipients
148 ----------------------------------------
149
150 Relevant LDAP resources for structuring recipient information include the
151 following:
152
153 RFC 4524 Defines the mail attribute
154 http://tools.ietf.org/html/rfc4524
155
156 RFC 2798 Defines the inetOrgPerson object
157 http://tools.ietf.org/html/rfc2798 class
158
159 RFC 2739 Defines the calEntry object class
160 https://tools.ietf.org/html/rfc2739 supporting calFBURL
161
162 An additional draft RFC describes the mailRecipient object class:
163
164 https://tools.ietf.org/html/draft-lachman-ldap-mail-routing-03
165
166 Resource schemas for LDAP are not effectively standardised for the purposes of
167 this software. A useful object class, inetResource, was defined for the
168 iPlanet Calendar Server:
169
170 http://docs.oracle.com/cd/E19566-01/819-4437/6n6jckqrf/index.html#anocg
171 http://docs.oracle.com/cd/E19566-01/819-4437/6n6jckqr8/index.html
172
173 Although Kolab maintains notions of resources, they are tied up with the
174 notion of a shared folder and the kolabSharedFolder object class, although the
175 mailRecipient object class is employed by resources in Kolab.
176
177 Configuring Mail Systems for Mail Delivery
178 ------------------------------------------
179
180 The agent software assumes that delivery of mail to recipients may be
181 performed using LMTP to a suitable mailbox provider. This is largely beyond
182 the scope of this document, but systems such as Cyrus and Dovecot can be
183 configured to provide a Unix domain socket offering support for LMTP
184 connections.
185
186 For Cyrus, the following bug report is pertinent:
187
188 https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=494746
189
190 A permanent change in permissions on the Cyrus LMTP socket is therefore
191 required to make delivery available to the lmtp group:
192
193 dpkg-statoverride --force --update --add \
194 cyrus lmtp 750 /var/run/cyrus/socket
195
196 Prerequisites
197 -------------
198
199 Depending on the mail transport agent (MTA) chosen, the following packages are
200 required for this software to work on Debian systems:
201
202 Exim: exim4-daemon-heavy
203 Postfix: postfix postfix-ldap
204
205 The software itself requires the following packages:
206
207 pytz: python-tz
208
209 The management Web interface requires the following packages:
210
211 Babel: python-babel
