imip-agent

Annotated README.txt

666:b25b2b903d88
2015-08-21 Paul Boddie Added support for delivery to local recipients via SMTP (at least for Postfix). Made the recipients parameter type consistent for the different sendmail method invocation possibilities.
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@102 61
  exim          Exim 4 routing and transport configuration
paul@102 62
  postfix       Postfix routing and transport configuration
paul@102 63
paul@102 64
Either Exim or Postfix can be chosen as a mail system supporting the agent.
paul@143 65
paul@143 66
Configuring Mail Systems for the Agent
paul@143 67
--------------------------------------
paul@143 68
paul@143 69
The essential aspect of mail system configuration involves mail transports and
paul@143 70
the integration of agent programs into the mail processing pipeline. Thus, the
paul@143 71
following files are of particular interest:
paul@143 72
paul@175 73
For Exim (in conf/exim)...
paul@143 74
paul@175 75
  30_exim4-config_people                Integration of agent programs
paul@175 76
  30_exim4-config_people_outgoing       ...
paul@175 77
  30_exim4-config_resources             ...
paul@143 78
paul@175 79
For Postfix (in conf/postfix)...
paul@143 80
paul@175 81
  master.cf.items                       Integration of agent programs (for
paul@175 82
                                        inclusion in master.cf)
paul@175 83
  transport                             Configuration of agent transports
paul@175 84
  virtual                               Configuration of outgoing mail routing
paul@143 85
paul@143 86
Such files need adjusting for the deployment environment so that, for example,
paul@143 87
the example.com domain would be replaced with a suitable value.
paul@143 88
paul@143 89
Where $lmtp_socket is employed, a suitable filesystem path is required; see
paul@143 90
below for a discussion of LMTP and mail delivery.
paul@143 91
paul@143 92
Configuring Mail Systems for Mail Recipients
paul@143 93
--------------------------------------------
paul@143 94
paul@143 95
The software should operate independently of the way mail recipients are
paul@143 96
identified in any given mail system, and thus does not dictate things such as
paul@143 97
routing or account querying. However, example configuration files are provided
paul@143 98
that demonstrate the use of LDAP to identify mail recipients:
paul@143 99
paul@175 100
For Exim (in conf/exim)...
paul@143 101
paul@175 102
  010_exim4-config_people_outgoing          Defines recipients and outgoing
paul@175 103
                                            mail routing
paul@175 104
  890_exim4-config_ldap_people              ...
paul@175 105
  890_exim4-config_ldap_resources           ...
paul@143 106
paul@175 107
For Postfix with LDAP (in conf/postfix/ldap)...
paul@143 108
paul@175 109
  main.cf.example                           Defines recipients and outgoing
paul@175 110
                                            mail routing (for inclusion in
paul@175 111
                                            main.cf)
paul@175 112
paul@177 113
  virtual_alias_maps_people.cf              Defines recipients and outgoing
paul@177 114
  virtual_alias_maps_people_outgoing.cf     mail routing
paul@176 115
  virtual_alias_maps_resources.cf           ...
paul@143 116
paul@664 117
Since the use of LDAP can be somewhat challenging and also excessive in some
paul@664 118
situations, examples of maintaining recipient information using a simpler
paul@664 119
approach are provided:
paul@664 120
paul@177 121
For Postfix without LDAP (in conf/postfix/simple)...
paul@177 122
paul@177 123
  main.cf.example                           Defines recipients and outgoing
paul@177 124
                                            mail routing (for inclusion in
paul@177 125
                                            main.cf)
paul@177 126
paul@664 127
  virtual_alias_maps                        Defines recipients and outgoing
paul@177 128
  virtual_alias_maps_people_outgoing        mail routing
paul@177 129
paul@664 130
In this simpler environment, recipient details must be manually edited in the
paul@664 131
virtual alias map files, but this permits a very transparent way of
paul@666 132
administering the system. To add support for delivery to local mailboxes, the
paul@666 133
following alternative to virtual_alias_maps is provided as an example:
paul@666 134
paul@666 135
  virtual_alias_maps_local                  Defines recipients and local users
paul@664 136
paul@664 137
Naturally, the above recipient identification configuration examples can be
paul@664 138
disregarded in favour of other ways of defining mail recipients, subject to
paul@664 139
the needs of any given environment.
paul@143 140
paul@144 141
LDAP Representations for Mail Recipients
paul@144 142
----------------------------------------
paul@144 143
paul@144 144
Relevant LDAP resources for structuring recipient information include the
paul@144 145
following:
paul@144 146
paul@175 147
  RFC 4524                                  Defines the mail attribute
paul@175 148
  http://tools.ietf.org/html/rfc4524
paul@175 149
paul@175 150
  RFC 2798                                  Defines the inetOrgPerson object
paul@175 151
  http://tools.ietf.org/html/rfc2798        class
paul@175 152
paul@175 153
  RFC 2739                                  Defines the calEntry object class
paul@175 154
  https://tools.ietf.org/html/rfc2739       supporting calFBURL
paul@144 155
paul@144 156
An additional draft RFC describes the mailRecipient object class:
paul@144 157
paul@144 158
  https://tools.ietf.org/html/draft-lachman-ldap-mail-routing-03
paul@144 159
paul@144 160
Resource schemas for LDAP are not effectively standardised for the purposes of
paul@145 161
this software. A useful object class, inetResource, was defined for the
paul@145 162
iPlanet Calendar Server:
paul@145 163
paul@145 164
  http://docs.oracle.com/cd/E19566-01/819-4437/6n6jckqrf/index.html#anocg
paul@145 165
  http://docs.oracle.com/cd/E19566-01/819-4437/6n6jckqr8/index.html
paul@145 166
paul@145 167
Although Kolab maintains notions of resources, they are tied up with the
paul@145 168
notion of a shared folder and the kolabSharedFolder object class, although the
paul@145 169
mailRecipient object class is employed by resources in Kolab.
paul@144 170
paul@143 171
Configuring Mail Systems for Mail Delivery
paul@143 172
------------------------------------------
paul@143 173
paul@143 174
The agent software assumes that delivery of mail to recipients may be
paul@143 175
performed using LMTP to a suitable mailbox provider. This is largely beyond
paul@143 176
the scope of this document, but systems such as Cyrus and Dovecot can be
paul@143 177
configured to provide a Unix domain socket offering support for LMTP
paul@143 178
connections.
paul@133 179
paul@209 180
For Cyrus, the following bug report is pertinent:
paul@209 181
paul@209 182
https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=494746
paul@209 183
paul@209 184
A permanent change in permissions on the Cyrus LMTP socket is therefore
paul@209 185
required to make delivery available to the lmtp group:
paul@209 186
paul@209 187
  dpkg-statoverride --force --update --add \
paul@209 188
    cyrus lmtp 750 /var/run/cyrus/socket
paul@209 189
paul@133 190
Prerequisites
paul@133 191
-------------
paul@133 192
paul@133 193
Depending on the mail transport agent (MTA) chosen, the following packages are
paul@133 194
required for this software to work on Debian systems:
paul@133 195
paul@133 196
  Exim:    exim4-daemon-heavy
paul@133 197
  Postfix: postfix postfix-ldap
paul@149 198
paul@175 199
The software itself requires the following packages:
paul@175 200
paul@175 201
  pytz:    python-tz
paul@175 202
paul@149 203
The management Web interface requires the following packages:
paul@149 204
paul@149 205
  Babel:   python-babel