imip-agent

Annotated README.txt

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