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
|