imip-agent

Annotated README.txt

897:6cc2fe1118b4
2015-10-21 Paul Boddie Changed the priority of configuration files. Made the local people router use a redirect driver.
paul@102 1
imip-agent
paul@102 2
==========
paul@102 3
paul@102 4
This software implements an agent that can interpret e-mail messages
paul@102 5
containing calendar information, maintain availability records for scheduling
paul@102 6
participants, act on behalf of resources and other entities that need to
paul@102 7
participate in scheduling, and support user interfaces for end-users whose
paul@102 8
e-mail programs do not understand calendar data.
paul@102 9
paul@102 10
Getting Started
paul@102 11
===============
paul@102 12
paul@102 13
Eventually, this information should be incorporated into packages for various
paul@102 14
operating system distributions, and these instructions should be largely
paul@102 15
superfluous for most users.
paul@102 16
paul@102 17
System User and Filesystem Access
paul@732 18
=================================
paul@102 19
paul@731 20
The data handled by imip-agent needs to be accessible to other software,
paul@731 21
notably mail handling software and Web server software. Two approaches are
paul@731 22
described here: LMTP delivery and local SMTP delivery.
paul@731 23
paul@731 24
LMTP Delivery
paul@731 25
-------------
paul@731 26
paul@731 27
Here, imip-agent's programs run in a way that permits LMTP delivery (requiring
paul@731 28
suitable local privileges to communicate with the mail storage solution)
paul@731 29
whilst allowing the Web server to read data written by those programs.
paul@731 30
paul@209 31
A system group needs to be created for LMTP delivery and for certain users to
paul@209 32
share resources:
paul@209 33
paul@209 34
  addgroup lmtp
paul@209 35
paul@209 36
This group should be employed for LMTP delivery by systems like Cyrus and
paul@209 37
Dovecot. See the section on configuring mail systems for delivery for more
paul@209 38
information.
paul@209 39
paul@102 40
A system user needs to be created and to belong to certain groups in order to
paul@102 41
deliver messages to mail stores and to publish resources on the Web:
paul@102 42
paul@102 43
  useradd -d /var/lib/imip-agent -m -U -G lmtp,www-data -r imip-agent
paul@102 44
paul@209 45
Store details and published resources need to be accessible by the imip-agent
paul@209 46
and www-data users. Thus, www-data also needs to belong to the lmtp group:
paul@102 47
paul@209 48
  adduser www-data lmtp
paul@209 49
paul@634 50
Stored and published data is then initialised using the tools/init.sh script.
paul@634 51
The script employs the setgid flag on the directories initialised for stored
paul@634 52
and published data so that new files and directories have the appropriate
paul@634 53
group associated with them.
paul@102 54
paul@731 55
It should be possible to omit all arguments to the init.sh script, but it is
paul@731 56
also worth reading the help message:
paul@731 57
paul@731 58
  tools/init.sh --help
paul@731 59
paul@634 60
Fixing ownership can be done using the tools/fix.sh script, in case some form
paul@634 61
of modification has altered the ownership or membership of the created files
paul@634 62
and directories.
paul@102 63
paul@731 64
Local SMTP Delivery
paul@731 65
-------------------
paul@731 66
paul@731 67
Here, imip-agent's programs run in a way that permits local SMTP delivery
paul@731 68
(which merely needs the ability to connect to a local network service) whilst
paul@731 69
allowing the Web server to read data written by those programs.
paul@731 70
paul@731 71
A system user needs to be created and to belong to certain groups in order to
paul@731 72
deliver messages to mail stores and to publish resources on the Web:
paul@731 73
paul@731 74
  useradd -d /var/lib/imip-agent -m -U -G www-data -r imip-agent
paul@731 75
paul@731 76
Again, the tools/init.sh script will initialise directories for stored and
paul@891 77
published data. The tools/config.sh script should be edited and the group
paul@891 78
redefined as follows:
paul@731 79
paul@891 80
  IMIP_AGENT_GROUP=www-data
paul@891 81
paul@891 82
If already installed, the /etc/imip-agent/config.sh script should be edited
paul@891 83
instead.
paul@731 84
paul@102 85
Installing the Software
paul@732 86
=======================
paul@102 87
paul@102 88
The tools/install.sh script should install the software in appropriate
paul@175 89
locations. See the prerequisites below for other software that will be
paul@175 90
required.
paul@102 91
paul@102 92
Configuring Other Software
paul@732 93
==========================
paul@102 94
paul@102 95
The conf directory contains subdirectories for different systems:
paul@102 96
paul@102 97
  apache        Apache 2 site configuration for publishing resources
paul@670 98
  cron          Cron command scheduling for free/busy updates
paul@102 99
  exim          Exim 4 routing and transport configuration
paul@102 100
  postfix       Postfix routing and transport configuration
paul@102 101
paul@102 102
Either Exim or Postfix can be chosen as a mail system supporting the agent.
paul@143 103
paul@143 104
Configuring Mail Systems for the Agent
paul@143 105
--------------------------------------
paul@143 106
paul@143 107
The essential aspect of mail system configuration involves mail transports and
paul@143 108
the integration of agent programs into the mail processing pipeline. Thus, the
paul@143 109
following files are of particular interest:
paul@143 110
paul@175 111
For Exim (in conf/exim)...
paul@143 112
paul@175 113
  30_exim4-config_people                Integration of agent programs
paul@175 114
  30_exim4-config_people_outgoing       ...
paul@175 115
  30_exim4-config_resources             ...
paul@143 116
paul@175 117
For Postfix (in conf/postfix)...
paul@143 118
paul@175 119
  master.cf.items                       Integration of agent programs (for
paul@175 120
                                        inclusion in master.cf)
paul@175 121
  transport                             Configuration of agent transports
paul@175 122
  virtual                               Configuration of outgoing mail routing
paul@143 123
paul@143 124
Such files need adjusting for the deployment environment so that, for example,
paul@143 125
the example.com domain would be replaced with a suitable value.
paul@143 126
paul@891 127
Where LMTP_SOCKET is employed, a suitable filesystem path is required; see
paul@143 128
below for a discussion of LMTP and mail delivery.
paul@143 129
paul@891 130
If local SMTP delivery is being used, the conf/postfix/master.cf.items file
paul@891 131
will need adjusting to use the appropriate system group.
paul@891 132
paul@143 133
Configuring Mail Systems for Mail Recipients
paul@143 134
--------------------------------------------
paul@143 135
paul@143 136
The software should operate independently of the way mail recipients are
paul@143 137
identified in any given mail system, and thus does not dictate things such as
paul@143 138
routing or account querying. However, example configuration files are provided
paul@143 139
that demonstrate the use of LDAP to identify mail recipients:
paul@143 140
paul@890 141
For Exim with LDAP (in conf/exim/ldap)...
paul@143 142
paul@175 143
  010_exim4-config_people_outgoing          Defines recipients and outgoing
paul@175 144
                                            mail routing
paul@897 145
  010_exim4-config_ldap_people              ...
paul@897 146
  010_exim4-config_ldap_resources           ...
paul@143 147
paul@175 148
For Postfix with LDAP (in conf/postfix/ldap)...
paul@143 149
paul@175 150
  main.cf.example                           Defines recipients and outgoing
paul@175 151
                                            mail routing (for inclusion in
paul@175 152
                                            main.cf)
paul@175 153
paul@177 154
  virtual_alias_maps_people.cf              Defines recipients and outgoing
paul@177 155
  virtual_alias_maps_people_outgoing.cf     mail routing
paul@176 156
  virtual_alias_maps_resources.cf           ...
paul@143 157
paul@664 158
Since the use of LDAP can be somewhat challenging and also excessive in some
paul@664 159
situations, examples of maintaining recipient information using a simpler
paul@664 160
approach are provided:
paul@664 161
paul@890 162
For Exim without LDAP (in conf/exim/simple)...
paul@890 163
paul@890 164
  010_exim4-config_people_outgoing          Defines recipients and outgoing
paul@890 165
                                            mail routing
paul@897 166
  010_exim4-config_ldap_people              ...
paul@897 167
  010_exim4-config_ldap_resources           ...
paul@890 168
paul@890 169
  virtual_people                            Defines recipient identities
paul@890 170
  virtual_resources                         belonging to known domains
paul@890 171
paul@890 172
  virtual_domains                           Defines recipient domains
paul@890 173
  virtual_people_outgoing                   Defines sender addresses
paul@890 174
paul@177 175
For Postfix without LDAP (in conf/postfix/simple)...
paul@177 176
paul@177 177
  main.cf.example                           Defines recipients and outgoing
paul@177 178
                                            mail routing (for inclusion in
paul@177 179
                                            main.cf)
paul@177 180
paul@664 181
  virtual_alias_maps                        Defines recipients and outgoing
paul@177 182
  virtual_alias_maps_people_outgoing        mail routing
paul@177 183
paul@664 184
In this simpler environment, recipient details must be manually edited in the
paul@664 185
virtual alias map files, but this permits a very transparent way of
paul@666 186
administering the system. To add support for delivery to local mailboxes, the
paul@666 187
following alternative to virtual_alias_maps is provided as an example:
paul@666 188
paul@666 189
  virtual_alias_maps_local                  Defines recipients and local users
paul@664 190
paul@664 191
Naturally, the above recipient identification configuration examples can be
paul@664 192
disregarded in favour of other ways of defining mail recipients, subject to
paul@664 193
the needs of any given environment.
paul@143 194
paul@144 195
LDAP Representations for Mail Recipients
paul@144 196
----------------------------------------
paul@144 197
paul@144 198
Relevant LDAP resources for structuring recipient information include the
paul@144 199
following:
paul@144 200
paul@175 201
  RFC 4524                                  Defines the mail attribute
paul@175 202
  http://tools.ietf.org/html/rfc4524
paul@175 203
paul@175 204
  RFC 2798                                  Defines the inetOrgPerson object
paul@175 205
  http://tools.ietf.org/html/rfc2798        class
paul@175 206
paul@175 207
  RFC 2739                                  Defines the calEntry object class
paul@175 208
  https://tools.ietf.org/html/rfc2739       supporting calFBURL
paul@144 209
paul@144 210
An additional draft RFC describes the mailRecipient object class:
paul@144 211
paul@144 212
  https://tools.ietf.org/html/draft-lachman-ldap-mail-routing-03
paul@144 213
paul@144 214
Resource schemas for LDAP are not effectively standardised for the purposes of
paul@145 215
this software. A useful object class, inetResource, was defined for the
paul@145 216
iPlanet Calendar Server:
paul@145 217
paul@145 218
  http://docs.oracle.com/cd/E19566-01/819-4437/6n6jckqrf/index.html#anocg
paul@145 219
  http://docs.oracle.com/cd/E19566-01/819-4437/6n6jckqr8/index.html
paul@145 220
paul@145 221
Although Kolab maintains notions of resources, they are tied up with the
paul@145 222
notion of a shared folder and the kolabSharedFolder object class, although the
paul@145 223
mailRecipient object class is employed by resources in Kolab.
paul@144 224
paul@143 225
Configuring Mail Systems for Mail Delivery
paul@143 226
------------------------------------------
paul@143 227
paul@143 228
The agent software assumes that delivery of mail to recipients may be
paul@143 229
performed using LMTP to a suitable mailbox provider. This is largely beyond
paul@143 230
the scope of this document, but systems such as Cyrus and Dovecot can be
paul@143 231
configured to provide a Unix domain socket offering support for LMTP
paul@143 232
connections.
paul@133 233
paul@209 234
For Cyrus, the following bug report is pertinent:
paul@209 235
paul@209 236
https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=494746
paul@209 237
paul@209 238
A permanent change in permissions on the Cyrus LMTP socket is therefore
paul@209 239
required to make delivery available to the lmtp group:
paul@209 240
paul@209 241
  dpkg-statoverride --force --update --add \
paul@209 242
    cyrus lmtp 750 /var/run/cyrus/socket
paul@209 243
paul@670 244
Configuring Cron for Free/Busy Updates
paul@670 245
--------------------------------------
paul@670 246
paul@670 247
The periods occupied by recurring events are not expanded beyond a certain
paul@670 248
window of time by imip-agent. As a consequence, free/busy collections need to
paul@670 249
be progressively expanded over time to include periods occupied by such events
paul@670 250
that were not previously recorded in those collections.
paul@670 251
paul@670 252
The conf/cron/cron.daily/imip-agent file contains commands that update
paul@670 253
free/busy collections for all known users, and this should be copied to the
paul@670 254
appropriate destination. For example:
paul@670 255
paul@670 256
cp conf/cron/cron.daily/imip-agent /etc/cron.daily/
paul@670 257
paul@670 258
Where frequency-specific directories are not supported by cron on a system, a
paul@670 259
crontab entry of the appropriate format is required instead.
paul@670 260
paul@748 261
Configuring Web Servers for Free/Busy Publishing
paul@748 262
------------------------------------------------
paul@748 263
paul@748 264
Each user may request the publishing of their free/busy information by
paul@748 265
configuring certain settings. The conf/apache/imip-agent.conf file provides a
paul@748 266
configuration file for deployment with the Apache Web server software that
paul@748 267
exposes a directory for Web publishing containing the published free/busy
paul@748 268
information.
paul@748 269
paul@748 270
Access to free/busy information may not be moderated, but Web server
paul@748 271
directives can be introduced to impose access controls. Mail programs that
paul@748 272
wish to consult the free/busy information may have problems in dealing with
paul@748 273
authentication mechanisms, however, and it may be regarded as acceptable in
paul@748 274
certain environments to expose such information publicly or with
paul@748 275
network-specific access constraints.
paul@748 276
paul@748 277
Configuring Web Servers for the Calendar Management Interface
paul@748 278
-------------------------------------------------------------
paul@748 279
paul@748 280
A calendar management interface is provided to allow users to view and
paul@748 281
interact with their calendars through the Web. The
paul@748 282
conf/apache/imip-manager.conf file provides a configuration file for
paul@748 283
deployment with the Apache Web server software that enables this interface.
paul@748 284
paul@748 285
Since such access to calendars should only be performed by identified
paul@748 286
users, access controls are suggested in the configuration file.
paul@748 287
paul@133 288
Prerequisites
paul@732 289
=============
paul@133 290
paul@133 291
Depending on the mail transport agent (MTA) chosen, the following packages are
paul@133 292
required for this software to work on Debian systems:
paul@133 293
paul@133 294
  Exim:    exim4-daemon-heavy
paul@133 295
  Postfix: postfix postfix-ldap
paul@149 296
paul@175 297
The software itself requires the following packages:
paul@175 298
paul@890 299
  Python:  python
paul@175 300
  pytz:    python-tz
paul@175 301
paul@149 302
The management Web interface requires the following packages:
paul@149 303
paul@890 304
  Apache:  apache2
paul@149 305
  Babel:   python-babel
paul@890 306
paul@890 307
Although not necessarily within the scope of the deployment of this software,
paul@890 308
the following mail storage solutions would be used to receive and hold
paul@890 309
messages:
paul@890 310
paul@890 311
  Cyrus:   cyrus-imapd
paul@890 312
  Dovecot: dovecot-imapd dovecot-ldap dovecot-lmtpd