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