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.
133
134 Naturally, the above recipient identification configuration examples can be
135 disregarded in favour of other ways of defining mail recipients, subject to
136 the needs of any given environment.
137
138 LDAP Representations for Mail Recipients
139 ----------------------------------------
140
141 Relevant LDAP resources for structuring recipient information include the
142 following:
143
144 RFC 4524 Defines the mail attribute
145 http://tools.ietf.org/html/rfc4524
146
147 RFC 2798 Defines the inetOrgPerson object
148 http://tools.ietf.org/html/rfc2798 class
149
150 RFC 2739 Defines the calEntry object class
151 https://tools.ietf.org/html/rfc2739 supporting calFBURL
152
153 An additional draft RFC describes the mailRecipient object class:
154
155 https://tools.ietf.org/html/draft-lachman-ldap-mail-routing-03
156
157 Resource schemas for LDAP are not effectively standardised for the purposes of
158 this software. A useful object class, inetResource, was defined for the
159 iPlanet Calendar Server:
160
161 http://docs.oracle.com/cd/E19566-01/819-4437/6n6jckqrf/index.html#anocg
162 http://docs.oracle.com/cd/E19566-01/819-4437/6n6jckqr8/index.html
163
164 Although Kolab maintains notions of resources, they are tied up with the
165 notion of a shared folder and the kolabSharedFolder object class, although the
166 mailRecipient object class is employed by resources in Kolab.
167
168 Configuring Mail Systems for Mail Delivery
169 ------------------------------------------
170
171 The agent software assumes that delivery of mail to recipients may be
172 performed using LMTP to a suitable mailbox provider. This is largely beyond
173 the scope of this document, but systems such as Cyrus and Dovecot can be
174 configured to provide a Unix domain socket offering support for LMTP
175 connections.
176
177 For Cyrus, the following bug report is pertinent:
178
179 https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=494746
180
181 A permanent change in permissions on the Cyrus LMTP socket is therefore
182 required to make delivery available to the lmtp group:
183
184 dpkg-statoverride --force --update --add \
185 cyrus lmtp 750 /var/run/cyrus/socket
186
187 Prerequisites
188 -------------
189
190 Depending on the mail transport agent (MTA) chosen, the following packages are
191 required for this software to work on Debian systems:
192
193 Exim: exim4-daemon-heavy
194 Postfix: postfix postfix-ldap
195
196 The software itself requires the following packages:
197
198 pytz: python-tz
199
200 The management Web interface requires the following packages:
201
202 Babel: python-babel