imip-agent

Annotated README.txt

731:8c43fba1f9b1
2015-09-13 Paul Boddie Updated the documentation and scripts with information on local SMTP mode, parameterising the scripts and adding help texts.
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@102 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@731 77
published data. For example:
paul@731 78
paul@731 79
  tools/init.sh imip-agent www-data
paul@731 80
paul@102 81
Installing the Software
paul@102 82
-----------------------
paul@102 83
paul@102 84
The tools/install.sh script should install the software in appropriate
paul@175 85
locations. See the prerequisites below for other software that will be
paul@175 86
required.
paul@102 87
paul@102 88
Configuring Other Software
paul@102 89
--------------------------
paul@102 90
paul@102 91
The conf directory contains subdirectories for different systems:
paul@102 92
paul@102 93
  apache        Apache 2 site configuration for publishing resources
paul@670 94
  cron          Cron command scheduling for free/busy updates
paul@102 95
  exim          Exim 4 routing and transport configuration
paul@102 96
  postfix       Postfix routing and transport configuration
paul@102 97
paul@102 98
Either Exim or Postfix can be chosen as a mail system supporting the agent.
paul@143 99
paul@143 100
Configuring Mail Systems for the Agent
paul@143 101
--------------------------------------
paul@143 102
paul@143 103
The essential aspect of mail system configuration involves mail transports and
paul@143 104
the integration of agent programs into the mail processing pipeline. Thus, the
paul@143 105
following files are of particular interest:
paul@143 106
paul@175 107
For Exim (in conf/exim)...
paul@143 108
paul@175 109
  30_exim4-config_people                Integration of agent programs
paul@175 110
  30_exim4-config_people_outgoing       ...
paul@175 111
  30_exim4-config_resources             ...
paul@143 112
paul@175 113
For Postfix (in conf/postfix)...
paul@143 114
paul@175 115
  master.cf.items                       Integration of agent programs (for
paul@175 116
                                        inclusion in master.cf)
paul@175 117
  transport                             Configuration of agent transports
paul@175 118
  virtual                               Configuration of outgoing mail routing
paul@143 119
paul@143 120
Such files need adjusting for the deployment environment so that, for example,
paul@143 121
the example.com domain would be replaced with a suitable value.
paul@143 122
paul@143 123
Where $lmtp_socket is employed, a suitable filesystem path is required; see
paul@143 124
below for a discussion of LMTP and mail delivery.
paul@143 125
paul@143 126
Configuring Mail Systems for Mail Recipients
paul@143 127
--------------------------------------------
paul@143 128
paul@143 129
The software should operate independently of the way mail recipients are
paul@143 130
identified in any given mail system, and thus does not dictate things such as
paul@143 131
routing or account querying. However, example configuration files are provided
paul@143 132
that demonstrate the use of LDAP to identify mail recipients:
paul@143 133
paul@175 134
For Exim (in conf/exim)...
paul@143 135
paul@175 136
  010_exim4-config_people_outgoing          Defines recipients and outgoing
paul@175 137
                                            mail routing
paul@175 138
  890_exim4-config_ldap_people              ...
paul@175 139
  890_exim4-config_ldap_resources           ...
paul@143 140
paul@175 141
For Postfix with LDAP (in conf/postfix/ldap)...
paul@143 142
paul@175 143
  main.cf.example                           Defines recipients and outgoing
paul@175 144
                                            mail routing (for inclusion in
paul@175 145
                                            main.cf)
paul@175 146
paul@177 147
  virtual_alias_maps_people.cf              Defines recipients and outgoing
paul@177 148
  virtual_alias_maps_people_outgoing.cf     mail routing
paul@176 149
  virtual_alias_maps_resources.cf           ...
paul@143 150
paul@664 151
Since the use of LDAP can be somewhat challenging and also excessive in some
paul@664 152
situations, examples of maintaining recipient information using a simpler
paul@664 153
approach are provided:
paul@664 154
paul@177 155
For Postfix without LDAP (in conf/postfix/simple)...
paul@177 156
paul@177 157
  main.cf.example                           Defines recipients and outgoing
paul@177 158
                                            mail routing (for inclusion in
paul@177 159
                                            main.cf)
paul@177 160
paul@664 161
  virtual_alias_maps                        Defines recipients and outgoing
paul@177 162
  virtual_alias_maps_people_outgoing        mail routing
paul@177 163
paul@664 164
In this simpler environment, recipient details must be manually edited in the
paul@664 165
virtual alias map files, but this permits a very transparent way of
paul@666 166
administering the system. To add support for delivery to local mailboxes, the
paul@666 167
following alternative to virtual_alias_maps is provided as an example:
paul@666 168
paul@666 169
  virtual_alias_maps_local                  Defines recipients and local users
paul@664 170
paul@664 171
Naturally, the above recipient identification configuration examples can be
paul@664 172
disregarded in favour of other ways of defining mail recipients, subject to
paul@664 173
the needs of any given environment.
paul@143 174
paul@144 175
LDAP Representations for Mail Recipients
paul@144 176
----------------------------------------
paul@144 177
paul@144 178
Relevant LDAP resources for structuring recipient information include the
paul@144 179
following:
paul@144 180
paul@175 181
  RFC 4524                                  Defines the mail attribute
paul@175 182
  http://tools.ietf.org/html/rfc4524
paul@175 183
paul@175 184
  RFC 2798                                  Defines the inetOrgPerson object
paul@175 185
  http://tools.ietf.org/html/rfc2798        class
paul@175 186
paul@175 187
  RFC 2739                                  Defines the calEntry object class
paul@175 188
  https://tools.ietf.org/html/rfc2739       supporting calFBURL
paul@144 189
paul@144 190
An additional draft RFC describes the mailRecipient object class:
paul@144 191
paul@144 192
  https://tools.ietf.org/html/draft-lachman-ldap-mail-routing-03
paul@144 193
paul@144 194
Resource schemas for LDAP are not effectively standardised for the purposes of
paul@145 195
this software. A useful object class, inetResource, was defined for the
paul@145 196
iPlanet Calendar Server:
paul@145 197
paul@145 198
  http://docs.oracle.com/cd/E19566-01/819-4437/6n6jckqrf/index.html#anocg
paul@145 199
  http://docs.oracle.com/cd/E19566-01/819-4437/6n6jckqr8/index.html
paul@145 200
paul@145 201
Although Kolab maintains notions of resources, they are tied up with the
paul@145 202
notion of a shared folder and the kolabSharedFolder object class, although the
paul@145 203
mailRecipient object class is employed by resources in Kolab.
paul@144 204
paul@143 205
Configuring Mail Systems for Mail Delivery
paul@143 206
------------------------------------------
paul@143 207
paul@143 208
The agent software assumes that delivery of mail to recipients may be
paul@143 209
performed using LMTP to a suitable mailbox provider. This is largely beyond
paul@143 210
the scope of this document, but systems such as Cyrus and Dovecot can be
paul@143 211
configured to provide a Unix domain socket offering support for LMTP
paul@143 212
connections.
paul@133 213
paul@209 214
For Cyrus, the following bug report is pertinent:
paul@209 215
paul@209 216
https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=494746
paul@209 217
paul@209 218
A permanent change in permissions on the Cyrus LMTP socket is therefore
paul@209 219
required to make delivery available to the lmtp group:
paul@209 220
paul@209 221
  dpkg-statoverride --force --update --add \
paul@209 222
    cyrus lmtp 750 /var/run/cyrus/socket
paul@209 223
paul@670 224
Configuring Cron for Free/Busy Updates
paul@670 225
--------------------------------------
paul@670 226
paul@670 227
The periods occupied by recurring events are not expanded beyond a certain
paul@670 228
window of time by imip-agent. As a consequence, free/busy collections need to
paul@670 229
be progressively expanded over time to include periods occupied by such events
paul@670 230
that were not previously recorded in those collections.
paul@670 231
paul@670 232
The conf/cron/cron.daily/imip-agent file contains commands that update
paul@670 233
free/busy collections for all known users, and this should be copied to the
paul@670 234
appropriate destination. For example:
paul@670 235
paul@670 236
cp conf/cron/cron.daily/imip-agent /etc/cron.daily/
paul@670 237
paul@670 238
Where frequency-specific directories are not supported by cron on a system, a
paul@670 239
crontab entry of the appropriate format is required instead.
paul@670 240
paul@133 241
Prerequisites
paul@133 242
-------------
paul@133 243
paul@133 244
Depending on the mail transport agent (MTA) chosen, the following packages are
paul@133 245
required for this software to work on Debian systems:
paul@133 246
paul@133 247
  Exim:    exim4-daemon-heavy
paul@133 248
  Postfix: postfix postfix-ldap
paul@149 249
paul@175 250
The software itself requires the following packages:
paul@175 251
paul@175 252
  pytz:    python-tz
paul@175 253
paul@149 254
The management Web interface requires the following packages:
paul@149 255
paul@149 256
  Babel:   python-babel