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.
59
60 Configuring Other Software
61 --------------------------
62
63 The conf directory contains subdirectories for different systems:
64
65 apache Apache 2 site configuration for publishing resources
66 exim Exim 4 routing and transport configuration
67 postfix Postfix routing and transport configuration
68
69 Either Exim or Postfix can be chosen as a mail system supporting the agent.
70
71 Configuring Mail Systems for the Agent
72 --------------------------------------
73
74 The essential aspect of mail system configuration involves mail transports and
75 the integration of agent programs into the mail processing pipeline. Thus, the
76 following files are of particular interest:
77
78 For Exim...
79
80 conf/exim/30_exim4-config_people Integration of agent programs
81 conf/exim/30_exim4-config_people_outgoing ...
82 conf/exim/30_exim4-config_resources ...
83
84 For Postfix...
85
86 conf/postfix/master.cf.items Integration of agent programs (for
87 inclusion in master.cf)
88 conf/postfix/transport Configuration of agent transports
89 conf/postfix/virtual Configuration of outgoing mail routing
90
91 Such files need adjusting for the deployment environment so that, for example,
92 the example.com domain would be replaced with a suitable value.
93
94 Where $lmtp_socket is employed, a suitable filesystem path is required; see
95 below for a discussion of LMTP and mail delivery.
96
97 Configuring Mail Systems for Mail Recipients
98 --------------------------------------------
99
100 The software should operate independently of the way mail recipients are
101 identified in any given mail system, and thus does not dictate things such as
102 routing or account querying. However, example configuration files are provided
103 that demonstrate the use of LDAP to identify mail recipients:
104
105 For Exim...
106
107 conf/exim/010_exim4-config_people_outgoing Defines recipients and
108 outgoing mail routing
109 conf/exim/890_exim4-config_ldap_people ...
110 conf/exim/890_exim4-config_ldap_resources ...
111
112 For Postfix...
113
114 conf/postfix/local_recipient_maps.cf Defines local virtual
115 recipients
116 conf/postfix/main.cf.example Defines recipients and outgoing
117 mail routing (for inclusion in
118 main.cf)
119 conf/postfix/virtual_alias_maps_people.cf
120 conf/postfix/virtual_alias_maps_people_outgoing.cf
121 conf/postfix/virtual_alias_maps_resources.cf
122
123 With the exception of the sender_bcc_maps setting in Postfix's main.cf, the
124 above recipient identification configuration examples can be disregarded in
125 favour of other ways of defining mail recipients, subject to the needs of any
126 given environment.
127
128 LDAP Representations for Mail Recipients
129 ----------------------------------------
130
131 Relevant LDAP resources for structuring recipient information include the
132 following:
133
134 RFC 4524 http://tools.ietf.org/html/rfc4524 Defines the mail attribute
135 RFC 2798 http://tools.ietf.org/html/rfc2798 Defines the inetOrgPerson
136 object class
137 RFC 2739 https://tools.ietf.org/html/rfc2739 Defines the calEntry object
138 class supporting calFBURL
139
140 An additional draft RFC describes the mailRecipient object class:
141
142 https://tools.ietf.org/html/draft-lachman-ldap-mail-routing-03
143
144 Resource schemas for LDAP are not effectively standardised for the purposes of
145 this software. A useful object class, inetResource, was defined for the
146 iPlanet Calendar Server:
147
148 http://docs.oracle.com/cd/E19566-01/819-4437/6n6jckqrf/index.html#anocg
149 http://docs.oracle.com/cd/E19566-01/819-4437/6n6jckqr8/index.html
150
151 Although Kolab maintains notions of resources, they are tied up with the
152 notion of a shared folder and the kolabSharedFolder object class, although the
153 mailRecipient object class is employed by resources in Kolab.
154
155 Configuring Mail Systems for Mail Delivery
156 ------------------------------------------
157
158 The agent software assumes that delivery of mail to recipients may be
159 performed using LMTP to a suitable mailbox provider. This is largely beyond
160 the scope of this document, but systems such as Cyrus and Dovecot can be
161 configured to provide a Unix domain socket offering support for LMTP
162 connections.
163
164 Prerequisites
165 -------------
166
167 Depending on the mail transport agent (MTA) chosen, the following packages are
168 required for this software to work on Debian systems:
169
170 Exim: exim4-daemon-heavy
171 Postfix: postfix postfix-ldap