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