imip-agent

Annotated README.txt

670:93ad1f9ce395
2015-08-31 Paul Boddie Added support/guidance for daily free/busy updates for all users using cron.
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@209 20
A system group needs to be created for LMTP delivery and for certain users to
paul@209 21
share resources:
paul@209 22
paul@209 23
  addgroup lmtp
paul@209 24
paul@209 25
This group should be employed for LMTP delivery by systems like Cyrus and
paul@209 26
Dovecot. See the section on configuring mail systems for delivery for more
paul@209 27
information.
paul@209 28
paul@102 29
A system user needs to be created and to belong to certain groups in order to
paul@102 30
deliver messages to mail stores and to publish resources on the Web:
paul@102 31
paul@102 32
  useradd -d /var/lib/imip-agent -m -U -G lmtp,www-data -r imip-agent
paul@102 33
paul@209 34
Store details and published resources need to be accessible by the imip-agent
paul@209 35
and www-data users. Thus, www-data also needs to belong to the lmtp group:
paul@102 36
paul@209 37
  adduser www-data lmtp
paul@209 38
paul@634 39
Stored and published data is then initialised using the tools/init.sh script.
paul@634 40
The script employs the setgid flag on the directories initialised for stored
paul@634 41
and published data so that new files and directories have the appropriate
paul@634 42
group associated with them.
paul@102 43
paul@634 44
Fixing ownership can be done using the tools/fix.sh script, in case some form
paul@634 45
of modification has altered the ownership or membership of the created files
paul@634 46
and directories.
paul@102 47
paul@102 48
Installing the Software
paul@102 49
-----------------------
paul@102 50
paul@102 51
The tools/install.sh script should install the software in appropriate
paul@175 52
locations. See the prerequisites below for other software that will be
paul@175 53
required.
paul@102 54
paul@102 55
Configuring Other Software
paul@102 56
--------------------------
paul@102 57
paul@102 58
The conf directory contains subdirectories for different systems:
paul@102 59
paul@102 60
  apache        Apache 2 site configuration for publishing resources
paul@670 61
  cron          Cron command scheduling for free/busy updates
paul@102 62
  exim          Exim 4 routing and transport configuration
paul@102 63
  postfix       Postfix routing and transport configuration
paul@102 64
paul@102 65
Either Exim or Postfix can be chosen as a mail system supporting the agent.
paul@143 66
paul@143 67
Configuring Mail Systems for the Agent
paul@143 68
--------------------------------------
paul@143 69
paul@143 70
The essential aspect of mail system configuration involves mail transports and
paul@143 71
the integration of agent programs into the mail processing pipeline. Thus, the
paul@143 72
following files are of particular interest:
paul@143 73
paul@175 74
For Exim (in conf/exim)...
paul@143 75
paul@175 76
  30_exim4-config_people                Integration of agent programs
paul@175 77
  30_exim4-config_people_outgoing       ...
paul@175 78
  30_exim4-config_resources             ...
paul@143 79
paul@175 80
For Postfix (in conf/postfix)...
paul@143 81
paul@175 82
  master.cf.items                       Integration of agent programs (for
paul@175 83
                                        inclusion in master.cf)
paul@175 84
  transport                             Configuration of agent transports
paul@175 85
  virtual                               Configuration of outgoing mail routing
paul@143 86
paul@143 87
Such files need adjusting for the deployment environment so that, for example,
paul@143 88
the example.com domain would be replaced with a suitable value.
paul@143 89
paul@143 90
Where $lmtp_socket is employed, a suitable filesystem path is required; see
paul@143 91
below for a discussion of LMTP and mail delivery.
paul@143 92
paul@143 93
Configuring Mail Systems for Mail Recipients
paul@143 94
--------------------------------------------
paul@143 95
paul@143 96
The software should operate independently of the way mail recipients are
paul@143 97
identified in any given mail system, and thus does not dictate things such as
paul@143 98
routing or account querying. However, example configuration files are provided
paul@143 99
that demonstrate the use of LDAP to identify mail recipients:
paul@143 100
paul@175 101
For Exim (in conf/exim)...
paul@143 102
paul@175 103
  010_exim4-config_people_outgoing          Defines recipients and outgoing
paul@175 104
                                            mail routing
paul@175 105
  890_exim4-config_ldap_people              ...
paul@175 106
  890_exim4-config_ldap_resources           ...
paul@143 107
paul@175 108
For Postfix with LDAP (in conf/postfix/ldap)...
paul@143 109
paul@175 110
  main.cf.example                           Defines recipients and outgoing
paul@175 111
                                            mail routing (for inclusion in
paul@175 112
                                            main.cf)
paul@175 113
paul@177 114
  virtual_alias_maps_people.cf              Defines recipients and outgoing
paul@177 115
  virtual_alias_maps_people_outgoing.cf     mail routing
paul@176 116
  virtual_alias_maps_resources.cf           ...
paul@143 117
paul@664 118
Since the use of LDAP can be somewhat challenging and also excessive in some
paul@664 119
situations, examples of maintaining recipient information using a simpler
paul@664 120
approach are provided:
paul@664 121
paul@177 122
For Postfix without LDAP (in conf/postfix/simple)...
paul@177 123
paul@177 124
  main.cf.example                           Defines recipients and outgoing
paul@177 125
                                            mail routing (for inclusion in
paul@177 126
                                            main.cf)
paul@177 127
paul@664 128
  virtual_alias_maps                        Defines recipients and outgoing
paul@177 129
  virtual_alias_maps_people_outgoing        mail routing
paul@177 130
paul@664 131
In this simpler environment, recipient details must be manually edited in the
paul@664 132
virtual alias map files, but this permits a very transparent way of
paul@666 133
administering the system. To add support for delivery to local mailboxes, the
paul@666 134
following alternative to virtual_alias_maps is provided as an example:
paul@666 135
paul@666 136
  virtual_alias_maps_local                  Defines recipients and local users
paul@664 137
paul@664 138
Naturally, the above recipient identification configuration examples can be
paul@664 139
disregarded in favour of other ways of defining mail recipients, subject to
paul@664 140
the needs of any given environment.
paul@143 141
paul@144 142
LDAP Representations for Mail Recipients
paul@144 143
----------------------------------------
paul@144 144
paul@144 145
Relevant LDAP resources for structuring recipient information include the
paul@144 146
following:
paul@144 147
paul@175 148
  RFC 4524                                  Defines the mail attribute
paul@175 149
  http://tools.ietf.org/html/rfc4524
paul@175 150
paul@175 151
  RFC 2798                                  Defines the inetOrgPerson object
paul@175 152
  http://tools.ietf.org/html/rfc2798        class
paul@175 153
paul@175 154
  RFC 2739                                  Defines the calEntry object class
paul@175 155
  https://tools.ietf.org/html/rfc2739       supporting calFBURL
paul@144 156
paul@144 157
An additional draft RFC describes the mailRecipient object class:
paul@144 158
paul@144 159
  https://tools.ietf.org/html/draft-lachman-ldap-mail-routing-03
paul@144 160
paul@144 161
Resource schemas for LDAP are not effectively standardised for the purposes of
paul@145 162
this software. A useful object class, inetResource, was defined for the
paul@145 163
iPlanet Calendar Server:
paul@145 164
paul@145 165
  http://docs.oracle.com/cd/E19566-01/819-4437/6n6jckqrf/index.html#anocg
paul@145 166
  http://docs.oracle.com/cd/E19566-01/819-4437/6n6jckqr8/index.html
paul@145 167
paul@145 168
Although Kolab maintains notions of resources, they are tied up with the
paul@145 169
notion of a shared folder and the kolabSharedFolder object class, although the
paul@145 170
mailRecipient object class is employed by resources in Kolab.
paul@144 171
paul@143 172
Configuring Mail Systems for Mail Delivery
paul@143 173
------------------------------------------
paul@143 174
paul@143 175
The agent software assumes that delivery of mail to recipients may be
paul@143 176
performed using LMTP to a suitable mailbox provider. This is largely beyond
paul@143 177
the scope of this document, but systems such as Cyrus and Dovecot can be
paul@143 178
configured to provide a Unix domain socket offering support for LMTP
paul@143 179
connections.
paul@133 180
paul@209 181
For Cyrus, the following bug report is pertinent:
paul@209 182
paul@209 183
https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=494746
paul@209 184
paul@209 185
A permanent change in permissions on the Cyrus LMTP socket is therefore
paul@209 186
required to make delivery available to the lmtp group:
paul@209 187
paul@209 188
  dpkg-statoverride --force --update --add \
paul@209 189
    cyrus lmtp 750 /var/run/cyrus/socket
paul@209 190
paul@670 191
Configuring Cron for Free/Busy Updates
paul@670 192
--------------------------------------
paul@670 193
paul@670 194
The periods occupied by recurring events are not expanded beyond a certain
paul@670 195
window of time by imip-agent. As a consequence, free/busy collections need to
paul@670 196
be progressively expanded over time to include periods occupied by such events
paul@670 197
that were not previously recorded in those collections.
paul@670 198
paul@670 199
The conf/cron/cron.daily/imip-agent file contains commands that update
paul@670 200
free/busy collections for all known users, and this should be copied to the
paul@670 201
appropriate destination. For example:
paul@670 202
paul@670 203
cp conf/cron/cron.daily/imip-agent /etc/cron.daily/
paul@670 204
paul@670 205
Where frequency-specific directories are not supported by cron on a system, a
paul@670 206
crontab entry of the appropriate format is required instead.
paul@670 207
paul@133 208
Prerequisites
paul@133 209
-------------
paul@133 210
paul@133 211
Depending on the mail transport agent (MTA) chosen, the following packages are
paul@133 212
required for this software to work on Debian systems:
paul@133 213
paul@133 214
  Exim:    exim4-daemon-heavy
paul@133 215
  Postfix: postfix postfix-ldap
paul@149 216
paul@175 217
The software itself requires the following packages:
paul@175 218
paul@175 219
  pytz:    python-tz
paul@175 220
paul@149 221
The management Web interface requires the following packages:
paul@149 222
paul@149 223
  Babel:   python-babel