imip-agent

Annotated README.txt

144:4d19192e3cf1
2014-12-20 Paul Boddie Added LDAP references; removed Kolab-specific schema class usage for people.
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@102 20
A system user needs to be created and to belong to certain groups in order to
paul@102 21
deliver messages to mail stores and to publish resources on the Web:
paul@102 22
paul@102 23
  useradd -d /var/lib/imip-agent -m -U -G lmtp,www-data -r imip-agent
paul@102 24
paul@102 25
If the lmtp group does not exist, it should be created and be employed for
paul@102 26
LMTP delivery to systems like Cyrus and Dovecot.
paul@102 27
paul@102 28
Store details and published resources need to be accessible by the imip-agent
paul@102 29
and www-data users:
paul@102 30
paul@102 31
  mkdir /var/lib/imip-agent/store /var/www/imip-agent/static
paul@102 32
  chown imip-agent /var/lib/imip-agent/store /var/www/imip-agent/static
paul@102 33
  chgrp www-data /var/lib/imip-agent/store /var/www/imip-agent/static
paul@102 34
  chmod g+s /var/lib/imip-agent/store /var/www/imip-agent/static
paul@102 35
paul@102 36
Here, the setgid flag should ensure that new files and directories have the
paul@102 37
appropriate group associated with them.
paul@102 38
paul@102 39
Fixing ownership can be done as follows:
paul@102 40
paul@102 41
  chown -R imip-agent /var/lib/imip-agent
paul@102 42
  chgrp -R imip-agent /var/lib/imip-agent
paul@102 43
  chown -R imip-agent /var/lib/imip-agent/store /var/www/imip-agent/static
paul@102 44
  chgrp -R www-data /var/lib/imip-agent/store /var/www/imip-agent/static
paul@102 45
  chmod -R g+w /var/lib/imip-agent/store /var/www/imip-agent/static
paul@102 46
paul@102 47
Installing the Software
paul@102 48
-----------------------
paul@102 49
paul@102 50
The tools/install.sh script should install the software in appropriate
paul@102 51
locations.
paul@102 52
paul@102 53
Configuring Other Software
paul@102 54
--------------------------
paul@102 55
paul@102 56
The conf directory contains subdirectories for different systems:
paul@102 57
paul@102 58
  apache        Apache 2 site configuration for publishing resources
paul@102 59
  exim          Exim 4 routing and transport configuration
paul@102 60
  postfix       Postfix routing and transport configuration
paul@102 61
paul@102 62
Either Exim or Postfix can be chosen as a mail system supporting the agent.
paul@143 63
paul@143 64
Configuring Mail Systems for the Agent
paul@143 65
--------------------------------------
paul@143 66
paul@143 67
The essential aspect of mail system configuration involves mail transports and
paul@143 68
the integration of agent programs into the mail processing pipeline. Thus, the
paul@143 69
following files are of particular interest:
paul@143 70
paul@143 71
For Exim...
paul@143 72
paul@143 73
  conf/exim/30_exim4-config_people              Integration of agent programs
paul@143 74
  conf/exim/30_exim4-config_people_outgoing     ...
paul@143 75
  conf/exim/30_exim4-config_resources           ...
paul@143 76
paul@143 77
For Postfix...
paul@143 78
paul@143 79
  conf/postfix/master.cf.items      Integration of agent programs (for
paul@143 80
                                    inclusion in master.cf)
paul@143 81
  conf/postfix/transport            Configuration of agent transports
paul@143 82
  conf/postfix/virtual              Configuration of outgoing mail routing
paul@143 83
paul@143 84
Such files need adjusting for the deployment environment so that, for example,
paul@143 85
the example.com domain would be replaced with a suitable value.
paul@143 86
paul@143 87
Where $lmtp_socket is employed, a suitable filesystem path is required; see
paul@143 88
below for a discussion of LMTP and mail delivery.
paul@143 89
paul@143 90
Configuring Mail Systems for Mail Recipients
paul@143 91
--------------------------------------------
paul@143 92
paul@143 93
The software should operate independently of the way mail recipients are
paul@143 94
identified in any given mail system, and thus does not dictate things such as
paul@143 95
routing or account querying. However, example configuration files are provided
paul@143 96
that demonstrate the use of LDAP to identify mail recipients:
paul@143 97
paul@143 98
For Exim...
paul@143 99
paul@143 100
  conf/exim/010_exim4-config_people_outgoing    Defines recipients and
paul@143 101
                                                outgoing mail routing
paul@143 102
  conf/exim/890_exim4-config_ldap_people        ...
paul@143 103
  conf/exim/890_exim4-config_ldap_resources     ...
paul@143 104
paul@143 105
For Postfix...
paul@143 106
paul@143 107
  conf/postfix/local_recipient_maps.cf          Defines local virtual
paul@143 108
                                                recipients
paul@143 109
  conf/postfix/main.cf.example                  Defines recipients and outgoing
paul@143 110
                                                mail routing (for inclusion in
paul@143 111
                                                main.cf)
paul@143 112
  conf/postfix/virtual_alias_maps_people.cf
paul@143 113
  conf/postfix/virtual_alias_maps_people_outgoing.cf
paul@143 114
  conf/postfix/virtual_alias_maps_resources.cf
paul@143 115
paul@143 116
With the exception of the sender_bcc_maps setting in Postfix's main.cf, the
paul@143 117
above recipient identification configuration examples can be disregarded in
paul@143 118
favour of other ways of defining mail recipients, subject to the needs of any
paul@143 119
given environment.
paul@143 120
paul@144 121
LDAP Representations for Mail Recipients
paul@144 122
----------------------------------------
paul@144 123
paul@144 124
Relevant LDAP resources for structuring recipient information include the
paul@144 125
following:
paul@144 126
paul@144 127
  RFC 4524  http://tools.ietf.org/html/rfc4524  Defines the mail attribute
paul@144 128
  RFC 2798  http://tools.ietf.org/html/rfc2798  Defines the inetOrgPerson
paul@144 129
                                                object class
paul@144 130
  RFC 2739  https://tools.ietf.org/html/rfc2739 Defines the calEntry object
paul@144 131
                                                class supporting calFBURL
paul@144 132
paul@144 133
An additional draft RFC describes the mailRecipient object class:
paul@144 134
paul@144 135
  https://tools.ietf.org/html/draft-lachman-ldap-mail-routing-03
paul@144 136
paul@144 137
Resource schemas for LDAP are not effectively standardised for the purposes of
paul@144 138
this software.
paul@144 139
paul@143 140
Configuring Mail Systems for Mail Delivery
paul@143 141
------------------------------------------
paul@143 142
paul@143 143
The agent software assumes that delivery of mail to recipients may be
paul@143 144
performed using LMTP to a suitable mailbox provider. This is largely beyond
paul@143 145
the scope of this document, but systems such as Cyrus and Dovecot can be
paul@143 146
configured to provide a Unix domain socket offering support for LMTP
paul@143 147
connections.
paul@133 148
paul@133 149
Prerequisites
paul@133 150
-------------
paul@133 151
paul@133 152
Depending on the mail transport agent (MTA) chosen, the following packages are
paul@133 153
required for this software to work on Debian systems:
paul@133 154
paul@133 155
  Exim:    exim4-daemon-heavy
paul@133 156
  Postfix: postfix postfix-ldap