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