imip-agent

Annotated README.txt

932:675d1e7f8510
2015-10-26 Paul Boddie Reformatted the documentation somewhat.
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@932 92
With local SMTP delivery, the mail system will need to be configured to route
paul@932 93
messages for local recipients. See the description of mail configuration for
paul@932 94
more information.
paul@932 95
paul@102 96
Configuring Other Software
paul@732 97
==========================
paul@102 98
paul@102 99
The conf directory contains subdirectories for different systems:
paul@102 100
paul@102 101
  apache        Apache 2 site configuration for publishing resources
paul@670 102
  cron          Cron command scheduling for free/busy updates
paul@102 103
  exim          Exim 4 routing and transport configuration
paul@902 104
  ldap          Some LDAP-related resources
paul@102 105
  postfix       Postfix routing and transport configuration
paul@102 106
paul@102 107
Either Exim or Postfix can be chosen as a mail system supporting the agent.
paul@143 108
paul@143 109
Configuring Mail Systems for the Agent
paul@932 110
======================================
paul@143 111
paul@143 112
The essential aspect of mail system configuration involves mail transports and
paul@143 113
the integration of agent programs into the mail processing pipeline. Thus, the
paul@143 114
following files are of particular interest:
paul@143 115
paul@175 116
For Exim (in conf/exim)...
paul@143 117
paul@175 118
  30_exim4-config_people                Integration of agent programs
paul@175 119
  30_exim4-config_people_outgoing       ...
paul@175 120
  30_exim4-config_resources             ...
paul@143 121
paul@175 122
For Postfix (in conf/postfix)...
paul@143 123
paul@175 124
  master.cf.items                       Integration of agent programs (for
paul@175 125
                                        inclusion in master.cf)
paul@175 126
  transport                             Configuration of agent transports
paul@175 127
  virtual                               Configuration of outgoing mail routing
paul@143 128
paul@143 129
Such files need adjusting for the deployment environment so that, for example,
paul@143 130
the example.com domain would be replaced with a suitable value.
paul@143 131
paul@900 132
If local SMTP delivery is being used, the 30_exim4-config_people file (in
paul@900 133
conf/exim) or the master.cf.items file (in conf/postfix) will need adjusting.
paul@932 134
paul@932 135
If LMTP is being used, instances of LMTP_SOCKET in the example configuration
paul@932 136
files will need to be replaced with a suitable filesystem path. Where the lmtp
paul@932 137
system group is employed, it may be replaced with a different group. See
paul@932 138
below for a discussion of LMTP and mail delivery.
paul@891 139
paul@143 140
Configuring Mail Systems for Mail Recipients
paul@932 141
============================================
paul@143 142
paul@143 143
The software should operate independently of the way mail recipients are
paul@143 144
identified in any given mail system, and thus does not dictate things such as
paul@143 145
routing or account querying. However, example configuration files are provided
paul@932 146
that demonstrate the use of various techniques to identify mail recipients.
paul@143 147
paul@932 148
Naturally, these recipient identification configuration examples can be
paul@932 149
disregarded in favour of other ways of defining mail recipients, subject to
paul@932 150
the needs of any given environment.
paul@900 151
paul@932 152
Using LDAP with Exim
paul@932 153
--------------------
paul@932 154
paul@932 155
For Exim (in conf/exim/ldap)...
paul@143 156
paul@899 157
  010_exim4-config_ldap_people_outgoing     Defines recipients and outgoing
paul@175 158
                                            mail routing
paul@899 159
  020_exim4-config_ldap_people              ...
paul@899 160
  020_exim4-config_ldap_resources           ...
paul@899 161
  020_exim4-config_ldap_people_outgoing_recipients
paul@143 162
paul@932 163
Using LDAP with Postfix
paul@932 164
-----------------------
paul@900 165
paul@932 166
For Postfix (in conf/postfix/ldap)...
paul@143 167
paul@175 168
  main.cf.example                           Defines recipients and outgoing
paul@175 169
                                            mail routing (for inclusion in
paul@175 170
                                            main.cf)
paul@175 171
paul@177 172
  virtual_alias_maps_people.cf              Defines recipients and outgoing
paul@177 173
  virtual_alias_maps_people_outgoing.cf     mail routing
paul@176 174
  virtual_alias_maps_resources.cf           ...
paul@143 175
paul@932 176
Using Lists of Identities
paul@932 177
-------------------------
paul@900 178
paul@664 179
Since the use of LDAP can be somewhat challenging and also excessive in some
paul@664 180
situations, examples of maintaining recipient information using a simpler
paul@900 181
approach are provided.
paul@900 182
paul@900 183
In this simpler environment, recipient details must be manually edited in the
paul@900 184
virtual identity files, but this permits a very transparent way of
paul@900 185
administering the system.
paul@900 186
paul@932 187
Using Lists with Exim
paul@932 188
---------------------
paul@664 189
paul@932 190
For Exim (in conf/exim/simple)...
paul@890 191
paul@890 192
  010_exim4-config_people_outgoing          Defines recipients and outgoing
paul@890 193
                                            mail routing
paul@899 194
  020_exim4-config_people                   ...
paul@899 195
  020_exim4-config_resources                ...
paul@899 196
  020_exim4-config_people_outgoing_recipients
paul@890 197
paul@890 198
  virtual_people                            Defines recipient identities
paul@899 199
  virtual_people_outgoing_recipients        belonging to known domains
paul@899 200
  virtual_resources                         ...
paul@890 201
paul@890 202
  virtual_domains                           Defines recipient domains
paul@899 203
paul@900 204
To add support for delivery to local mailboxes, the following additional file
paul@900 205
is provided as an example:
paul@899 206
paul@899 207
  virtual_people_local                      Defines recipients and local users
paul@890 208
paul@900 209
And to route bounced messages back to the generic calendar address, an
paul@900 210
addition to the /etc/aliases file is provided:
paul@900 211
paul@900 212
  aliases.example                           Routes calendar to root
paul@900 213
paul@932 214
Using Lists with Postfix
paul@932 215
------------------------
paul@900 216
paul@932 217
For Postfix (in conf/postfix/simple)...
paul@177 218
paul@177 219
  main.cf.example                           Defines recipients and outgoing
paul@177 220
                                            mail routing (for inclusion in
paul@177 221
                                            main.cf)
paul@177 222
paul@664 223
  virtual_alias_maps                        Defines recipients and outgoing
paul@177 224
  virtual_alias_maps_people_outgoing        mail routing
paul@177 225
paul@900 226
To add support for delivery to local mailboxes, the following alternative to
paul@900 227
virtual_alias_maps is provided as an example:
paul@666 228
paul@666 229
  virtual_alias_maps_local                  Defines recipients and local users
paul@664 230
paul@144 231
LDAP Representations for Mail Recipients
paul@144 232
----------------------------------------
paul@144 233
paul@144 234
Relevant LDAP resources for structuring recipient information include the
paul@144 235
following:
paul@144 236
paul@175 237
  RFC 4524                                  Defines the mail attribute
paul@175 238
  http://tools.ietf.org/html/rfc4524
paul@175 239
paul@175 240
  RFC 2798                                  Defines the inetOrgPerson object
paul@175 241
  http://tools.ietf.org/html/rfc2798        class
paul@175 242
paul@175 243
  RFC 2739                                  Defines the calEntry object class
paul@175 244
  https://tools.ietf.org/html/rfc2739       supporting calFBURL
paul@144 245
paul@144 246
An additional draft RFC describes the mailRecipient object class:
paul@144 247
paul@144 248
  https://tools.ietf.org/html/draft-lachman-ldap-mail-routing-03
paul@144 249
paul@144 250
Resource schemas for LDAP are not effectively standardised for the purposes of
paul@145 251
this software. A useful object class, inetResource, was defined for the
paul@145 252
iPlanet Calendar Server:
paul@145 253
paul@145 254
  http://docs.oracle.com/cd/E19566-01/819-4437/6n6jckqrf/index.html#anocg
paul@145 255
  http://docs.oracle.com/cd/E19566-01/819-4437/6n6jckqr8/index.html
paul@145 256
paul@145 257
Although Kolab maintains notions of resources, they are tied up with the
paul@145 258
notion of a shared folder and the kolabSharedFolder object class, although the
paul@145 259
mailRecipient object class is employed by resources in Kolab.
paul@144 260
paul@143 261
Configuring Mail Systems for Mail Delivery
paul@932 262
==========================================
paul@143 263
paul@143 264
The agent software assumes that delivery of mail to recipients may be
paul@900 265
performed either using local SMTP or by using LMTP to a suitable mailbox
paul@900 266
provider.
paul@900 267
paul@900 268
If employing local SMTP, the burden of routing messages to suitable storage
paul@900 269
becomes a configuration problem within the mail system itself, but given that
paul@900 270
routing to local system users is typically supported "out of the box", this
paul@900 271
can provide a usable solution with minimal effort.
paul@900 272
paul@912 273
Where the mail system must instead route messages to mailbox providers
paul@912 274
employing LMTP, some more effort is required. For Exim, some sample
paul@912 275
configuration files are provided in conf/exim/lmtp to route messages for local
paul@912 276
users to LMTP endpoints.
paul@912 277
paul@900 278
By using LMTP from the agent software, the issue of configuring the mail
paul@900 279
system to integrate with storage solutions is avoided, but then those
paul@900 280
solutions must expose their LMTP interface appropriately.
paul@900 281
paul@912 282
Configuring Mail Storage Providers for LMTP
paul@912 283
-------------------------------------------
paul@912 284
paul@900 285
Although this topic is largely beyond the scope of this document, systems such
paul@900 286
as Cyrus and Dovecot can be configured to provide a Unix domain socket
paul@900 287
offering support for LMTP connections.
paul@133 288
paul@209 289
For Cyrus, the following bug report is pertinent:
paul@209 290
paul@209 291
https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=494746
paul@209 292
paul@209 293
A permanent change in permissions on the Cyrus LMTP socket is therefore
paul@209 294
required to make delivery available to the lmtp group:
paul@209 295
paul@209 296
  dpkg-statoverride --force --update --add \
paul@209 297
    cyrus lmtp 750 /var/run/cyrus/socket
paul@209 298
paul@670 299
Configuring Cron for Free/Busy Updates
paul@932 300
======================================
paul@670 301
paul@670 302
The periods occupied by recurring events are not expanded beyond a certain
paul@670 303
window of time by imip-agent. As a consequence, free/busy collections need to
paul@670 304
be progressively expanded over time to include periods occupied by such events
paul@670 305
that were not previously recorded in those collections.
paul@670 306
paul@670 307
The conf/cron/cron.daily/imip-agent file contains commands that update
paul@670 308
free/busy collections for all known users, and this should be copied to the
paul@670 309
appropriate destination. For example:
paul@670 310
paul@670 311
cp conf/cron/cron.daily/imip-agent /etc/cron.daily/
paul@670 312
paul@670 313
Where frequency-specific directories are not supported by cron on a system, a
paul@670 314
crontab entry of the appropriate format is required instead.
paul@670 315
paul@748 316
Configuring Web Servers for Free/Busy Publishing
paul@932 317
================================================
paul@748 318
paul@748 319
Each user may request the publishing of their free/busy information by
paul@748 320
configuring certain settings. The conf/apache/imip-agent.conf file provides a
paul@748 321
configuration file for deployment with the Apache Web server software that
paul@748 322
exposes a directory for Web publishing containing the published free/busy
paul@748 323
information.
paul@748 324
paul@748 325
Access to free/busy information may not be moderated, but Web server
paul@748 326
directives can be introduced to impose access controls. Mail programs that
paul@748 327
wish to consult the free/busy information may have problems in dealing with
paul@748 328
authentication mechanisms, however, and it may be regarded as acceptable in
paul@748 329
certain environments to expose such information publicly or with
paul@748 330
network-specific access constraints.
paul@748 331
paul@748 332
Configuring Web Servers for the Calendar Management Interface
paul@932 333
=============================================================
paul@748 334
paul@748 335
A calendar management interface is provided to allow users to view and
paul@748 336
interact with their calendars through the Web. The
paul@748 337
conf/apache/imip-manager.conf file provides a configuration file for
paul@748 338
deployment with the Apache Web server software that enables this interface.
paul@748 339
paul@905 340
The management interface is deployed as a CGI program, meaning that a suitable
paul@905 341
module must be enabled in the Apache configuration. On Debian, this is done as
paul@905 342
follows:
paul@905 343
paul@905 344
a2enmod cgi
paul@905 345
paul@748 346
Since such access to calendars should only be performed by identified
paul@905 347
users, access controls are suggested in the configuration file. Modules
paul@905 348
providing additional authentication support may need to be enabled. For
paul@905 349
example, on Debian, the LDAP authentication/authorisation support is enabled
paul@905 350
as follows:
paul@905 351
paul@905 352
a2enmod authnz_ldap
paul@748 353
paul@133 354
Prerequisites
paul@732 355
=============
paul@133 356
paul@133 357
Depending on the mail transport agent (MTA) chosen, the following packages are
paul@133 358
required for this software to work on Debian systems:
paul@133 359
paul@133 360
  Exim:    exim4-daemon-heavy
paul@133 361
  Postfix: postfix postfix-ldap
paul@149 362
paul@175 363
The software itself requires the following packages:
paul@175 364
paul@890 365
  Python:  python
paul@175 366
  pytz:    python-tz
paul@175 367
paul@900 368
To update free/busy details periodically, the following software is
paul@900 369
recommended:
paul@900 370
paul@900 371
  Cron:    cron
paul@900 372
paul@149 373
The management Web interface requires the following packages:
paul@149 374
paul@890 375
  Apache:  apache2
paul@149 376
  Babel:   python-babel
paul@890 377
paul@890 378
Although not necessarily within the scope of the deployment of this software,
paul@890 379
the following mail storage solutions would be used to receive and hold
paul@890 380
messages:
paul@890 381
paul@890 382
  Cyrus:   cyrus-imapd
paul@890 383
  Dovecot: dovecot-imapd dovecot-ldap dovecot-lmtpd
paul@908 384
paul@908 385
Some test programs need additional programs provided by other packages:
paul@908 386
paul@908 387
  envsubst: gettext-base