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@902 | 17 | Installing the Software
|
paul@902 | 18 | =======================
|
paul@902 | 19 |
|
paul@902 | 20 | The tools/install.sh script should install the software in appropriate
|
paul@902 | 21 | locations. See the prerequisites below for other software that will be
|
paul@902 | 22 | required.
|
paul@902 | 23 |
|
paul@102 | 24 | System User and Filesystem Access
|
paul@732 | 25 | =================================
|
paul@102 | 26 |
|
paul@731 | 27 | The data handled by imip-agent needs to be accessible to other software,
|
paul@731 | 28 | notably mail handling software and Web server software. Two approaches are
|
paul@731 | 29 | described here: LMTP delivery and local SMTP delivery.
|
paul@731 | 30 |
|
paul@731 | 31 | LMTP Delivery
|
paul@731 | 32 | -------------
|
paul@731 | 33 |
|
paul@731 | 34 | Here, imip-agent's programs run in a way that permits LMTP delivery (requiring
|
paul@731 | 35 | suitable local privileges to communicate with the mail storage solution)
|
paul@731 | 36 | whilst allowing the Web server to read data written by those programs.
|
paul@731 | 37 |
|
paul@209 | 38 | A system group needs to be created for LMTP delivery and for certain users to
|
paul@209 | 39 | share resources:
|
paul@209 | 40 |
|
paul@209 | 41 | addgroup lmtp
|
paul@209 | 42 |
|
paul@209 | 43 | This group should be employed for LMTP delivery by systems like Cyrus and
|
paul@209 | 44 | Dovecot. See the section on configuring mail systems for delivery for more
|
paul@209 | 45 | information.
|
paul@209 | 46 |
|
paul@102 | 47 | A system user needs to be created and to belong to certain groups in order to
|
paul@102 | 48 | deliver messages to mail stores and to publish resources on the Web:
|
paul@102 | 49 |
|
paul@102 | 50 | useradd -d /var/lib/imip-agent -m -U -G lmtp,www-data -r imip-agent
|
paul@102 | 51 |
|
paul@209 | 52 | Store details and published resources need to be accessible by the imip-agent
|
paul@209 | 53 | and www-data users. Thus, www-data also needs to belong to the lmtp group:
|
paul@102 | 54 |
|
paul@209 | 55 | adduser www-data lmtp
|
paul@209 | 56 |
|
paul@731 | 57 | Local SMTP Delivery
|
paul@731 | 58 | -------------------
|
paul@731 | 59 |
|
paul@731 | 60 | Here, imip-agent's programs run in a way that permits local SMTP delivery
|
paul@731 | 61 | (which merely needs the ability to connect to a local network service) whilst
|
paul@731 | 62 | allowing the Web server to read data written by those programs.
|
paul@731 | 63 |
|
paul@731 | 64 | A system user needs to be created and to belong to certain groups in order to
|
paul@731 | 65 | deliver messages to mail stores and to publish resources on the Web:
|
paul@731 | 66 |
|
paul@731 | 67 | useradd -d /var/lib/imip-agent -m -U -G www-data -r imip-agent
|
paul@731 | 68 |
|
paul@731 | 69 | Again, the tools/init.sh script will initialise directories for stored and
|
paul@891 | 70 | published data. The tools/config.sh script should be edited and the group
|
paul@891 | 71 | redefined as follows:
|
paul@731 | 72 |
|
paul@891 | 73 | IMIP_AGENT_GROUP=www-data
|
paul@891 | 74 |
|
paul@891 | 75 | If already installed, the /etc/imip-agent/config.sh script should be edited
|
paul@891 | 76 | instead.
|
paul@731 | 77 |
|
paul@932 | 78 | With local SMTP delivery, the mail system will need to be configured to route
|
paul@932 | 79 | messages for local recipients. See the description of mail configuration for
|
paul@932 | 80 | more information.
|
paul@932 | 81 |
|
paul@946 | 82 | Initialising the Software
|
paul@946 | 83 | =========================
|
paul@946 | 84 |
|
paul@946 | 85 | Once a suitable system user has been chosen, stored and published data is then
|
paul@946 | 86 | initialised using the tools/init.sh script. The script employs the setgid flag
|
paul@946 | 87 | on the directories initialised for stored and published data so that new files
|
paul@946 | 88 | and directories have the appropriate group associated with them.
|
paul@946 | 89 |
|
paul@946 | 90 | It should be possible to omit all arguments to the init.sh script, but it is
|
paul@946 | 91 | also worth reading the help message:
|
paul@946 | 92 |
|
paul@946 | 93 | tools/init.sh --help
|
paul@946 | 94 |
|
paul@946 | 95 | Fixing ownership can be done using the tools/fix.sh script, in case some form
|
paul@946 | 96 | of modification has altered the ownership or membership of the created files
|
paul@946 | 97 | and directories.
|
paul@946 | 98 |
|
paul@102 | 99 | Configuring Other Software
|
paul@732 | 100 | ==========================
|
paul@102 | 101 |
|
paul@102 | 102 | The conf directory contains subdirectories for different systems:
|
paul@102 | 103 |
|
paul@102 | 104 | apache Apache 2 site configuration for publishing resources
|
paul@670 | 105 | cron Cron command scheduling for free/busy updates
|
paul@102 | 106 | exim Exim 4 routing and transport configuration
|
paul@902 | 107 | ldap Some LDAP-related resources
|
paul@102 | 108 | postfix Postfix routing and transport configuration
|
paul@102 | 109 |
|
paul@102 | 110 | Either Exim or Postfix can be chosen as a mail system supporting the agent.
|
paul@143 | 111 |
|
paul@143 | 112 | Configuring Mail Systems for the Agent
|
paul@932 | 113 | ======================================
|
paul@143 | 114 |
|
paul@143 | 115 | The essential aspect of mail system configuration involves mail transports and
|
paul@143 | 116 | the integration of agent programs into the mail processing pipeline. Thus, the
|
paul@143 | 117 | following files are of particular interest:
|
paul@143 | 118 |
|
paul@175 | 119 | For Exim (in conf/exim)...
|
paul@143 | 120 |
|
paul@175 | 121 | 30_exim4-config_people Integration of agent programs
|
paul@175 | 122 | 30_exim4-config_people_outgoing ...
|
paul@175 | 123 | 30_exim4-config_resources ...
|
paul@143 | 124 |
|
paul@175 | 125 | For Postfix (in conf/postfix)...
|
paul@143 | 126 |
|
paul@175 | 127 | master.cf.items Integration of agent programs (for
|
paul@175 | 128 | inclusion in master.cf)
|
paul@175 | 129 | transport Configuration of agent transports
|
paul@175 | 130 | virtual Configuration of outgoing mail routing
|
paul@143 | 131 |
|
paul@143 | 132 | Such files need adjusting for the deployment environment so that, for example,
|
paul@143 | 133 | the example.com domain would be replaced with a suitable value.
|
paul@143 | 134 |
|
paul@900 | 135 | If local SMTP delivery is being used, the 30_exim4-config_people file (in
|
paul@900 | 136 | conf/exim) or the master.cf.items file (in conf/postfix) will need adjusting.
|
paul@932 | 137 |
|
paul@932 | 138 | If LMTP is being used, instances of LMTP_SOCKET in the example configuration
|
paul@932 | 139 | files will need to be replaced with a suitable filesystem path. Where the lmtp
|
paul@932 | 140 | system group is employed, it may be replaced with a different group. See
|
paul@932 | 141 | below for a discussion of LMTP and mail delivery.
|
paul@891 | 142 |
|
paul@143 | 143 | Configuring Mail Systems for Mail Recipients
|
paul@932 | 144 | ============================================
|
paul@143 | 145 |
|
paul@143 | 146 | The software should operate independently of the way mail recipients are
|
paul@143 | 147 | identified in any given mail system, and thus does not dictate things such as
|
paul@143 | 148 | routing or account querying. However, example configuration files are provided
|
paul@932 | 149 | that demonstrate the use of various techniques to identify mail recipients.
|
paul@143 | 150 |
|
paul@932 | 151 | Naturally, these recipient identification configuration examples can be
|
paul@932 | 152 | disregarded in favour of other ways of defining mail recipients, subject to
|
paul@932 | 153 | the needs of any given environment.
|
paul@900 | 154 |
|
paul@932 | 155 | Using LDAP with Exim
|
paul@932 | 156 | --------------------
|
paul@932 | 157 |
|
paul@932 | 158 | For Exim (in conf/exim/ldap)...
|
paul@143 | 159 |
|
paul@899 | 160 | 010_exim4-config_ldap_people_outgoing Defines recipients and outgoing
|
paul@175 | 161 | mail routing
|
paul@899 | 162 | 020_exim4-config_ldap_people ...
|
paul@899 | 163 | 020_exim4-config_ldap_resources ...
|
paul@899 | 164 | 020_exim4-config_ldap_people_outgoing_recipients
|
paul@143 | 165 |
|
paul@932 | 166 | Using LDAP with Postfix
|
paul@932 | 167 | -----------------------
|
paul@900 | 168 |
|
paul@932 | 169 | For Postfix (in conf/postfix/ldap)...
|
paul@143 | 170 |
|
paul@175 | 171 | main.cf.example Defines recipients and outgoing
|
paul@175 | 172 | mail routing (for inclusion in
|
paul@175 | 173 | main.cf)
|
paul@175 | 174 |
|
paul@177 | 175 | virtual_alias_maps_people.cf Defines recipients and outgoing
|
paul@177 | 176 | virtual_alias_maps_people_outgoing.cf mail routing
|
paul@176 | 177 | virtual_alias_maps_resources.cf ...
|
paul@143 | 178 |
|
paul@932 | 179 | Using Lists of Identities
|
paul@932 | 180 | -------------------------
|
paul@900 | 181 |
|
paul@664 | 182 | Since the use of LDAP can be somewhat challenging and also excessive in some
|
paul@664 | 183 | situations, examples of maintaining recipient information using a simpler
|
paul@900 | 184 | approach are provided.
|
paul@900 | 185 |
|
paul@900 | 186 | In this simpler environment, recipient details must be manually edited in the
|
paul@900 | 187 | virtual identity files, but this permits a very transparent way of
|
paul@900 | 188 | administering the system.
|
paul@900 | 189 |
|
paul@932 | 190 | Using Lists with Exim
|
paul@932 | 191 | ---------------------
|
paul@664 | 192 |
|
paul@932 | 193 | For Exim (in conf/exim/simple)...
|
paul@890 | 194 |
|
paul@890 | 195 | 010_exim4-config_people_outgoing Defines recipients and outgoing
|
paul@890 | 196 | mail routing
|
paul@899 | 197 | 020_exim4-config_people ...
|
paul@899 | 198 | 020_exim4-config_resources ...
|
paul@899 | 199 | 020_exim4-config_people_outgoing_recipients
|
paul@890 | 200 |
|
paul@890 | 201 | virtual_people Defines recipient identities
|
paul@899 | 202 | virtual_people_outgoing_recipients belonging to known domains
|
paul@899 | 203 | virtual_resources ...
|
paul@890 | 204 |
|
paul@890 | 205 | virtual_domains Defines recipient domains
|
paul@899 | 206 |
|
paul@900 | 207 | To add support for delivery to local mailboxes, the following additional file
|
paul@900 | 208 | is provided as an example:
|
paul@899 | 209 |
|
paul@899 | 210 | virtual_people_local Defines recipients and local users
|
paul@890 | 211 |
|
paul@900 | 212 | And to route bounced messages back to the generic calendar address, an
|
paul@900 | 213 | addition to the /etc/aliases file is provided:
|
paul@900 | 214 |
|
paul@900 | 215 | aliases.example Routes calendar to root
|
paul@900 | 216 |
|
paul@932 | 217 | Using Lists with Postfix
|
paul@932 | 218 | ------------------------
|
paul@900 | 219 |
|
paul@932 | 220 | For Postfix (in conf/postfix/simple)...
|
paul@177 | 221 |
|
paul@177 | 222 | main.cf.example Defines recipients and outgoing
|
paul@177 | 223 | mail routing (for inclusion in
|
paul@177 | 224 | main.cf)
|
paul@177 | 225 |
|
paul@664 | 226 | virtual_alias_maps Defines recipients and outgoing
|
paul@177 | 227 | virtual_alias_maps_people_outgoing mail routing
|
paul@177 | 228 |
|
paul@900 | 229 | To add support for delivery to local mailboxes, the following alternative to
|
paul@900 | 230 | virtual_alias_maps is provided as an example:
|
paul@666 | 231 |
|
paul@666 | 232 | virtual_alias_maps_local Defines recipients and local users
|
paul@664 | 233 |
|
paul@144 | 234 | LDAP Representations for Mail Recipients
|
paul@144 | 235 | ----------------------------------------
|
paul@144 | 236 |
|
paul@144 | 237 | Relevant LDAP resources for structuring recipient information include the
|
paul@144 | 238 | following:
|
paul@144 | 239 |
|
paul@175 | 240 | RFC 4524 Defines the mail attribute
|
paul@175 | 241 | http://tools.ietf.org/html/rfc4524
|
paul@175 | 242 |
|
paul@175 | 243 | RFC 2798 Defines the inetOrgPerson object
|
paul@175 | 244 | http://tools.ietf.org/html/rfc2798 class
|
paul@175 | 245 |
|
paul@175 | 246 | RFC 2739 Defines the calEntry object class
|
paul@175 | 247 | https://tools.ietf.org/html/rfc2739 supporting calFBURL
|
paul@144 | 248 |
|
paul@144 | 249 | An additional draft RFC describes the mailRecipient object class:
|
paul@144 | 250 |
|
paul@144 | 251 | https://tools.ietf.org/html/draft-lachman-ldap-mail-routing-03
|
paul@144 | 252 |
|
paul@144 | 253 | Resource schemas for LDAP are not effectively standardised for the purposes of
|
paul@145 | 254 | this software. A useful object class, inetResource, was defined for the
|
paul@145 | 255 | iPlanet Calendar Server:
|
paul@145 | 256 |
|
paul@145 | 257 | http://docs.oracle.com/cd/E19566-01/819-4437/6n6jckqrf/index.html#anocg
|
paul@145 | 258 | http://docs.oracle.com/cd/E19566-01/819-4437/6n6jckqr8/index.html
|
paul@145 | 259 |
|
paul@145 | 260 | Although Kolab maintains notions of resources, they are tied up with the
|
paul@145 | 261 | notion of a shared folder and the kolabSharedFolder object class, although the
|
paul@145 | 262 | mailRecipient object class is employed by resources in Kolab.
|
paul@144 | 263 |
|
paul@143 | 264 | Configuring Mail Systems for Mail Delivery
|
paul@932 | 265 | ==========================================
|
paul@143 | 266 |
|
paul@143 | 267 | The agent software assumes that delivery of mail to recipients may be
|
paul@900 | 268 | performed either using local SMTP or by using LMTP to a suitable mailbox
|
paul@900 | 269 | provider.
|
paul@900 | 270 |
|
paul@900 | 271 | If employing local SMTP, the burden of routing messages to suitable storage
|
paul@900 | 272 | becomes a configuration problem within the mail system itself, but given that
|
paul@900 | 273 | routing to local system users is typically supported "out of the box", this
|
paul@900 | 274 | can provide a usable solution with minimal effort.
|
paul@900 | 275 |
|
paul@912 | 276 | Where the mail system must instead route messages to mailbox providers
|
paul@912 | 277 | employing LMTP, some more effort is required. For Exim, some sample
|
paul@912 | 278 | configuration files are provided in conf/exim/lmtp to route messages for local
|
paul@912 | 279 | users to LMTP endpoints.
|
paul@912 | 280 |
|
paul@900 | 281 | By using LMTP from the agent software, the issue of configuring the mail
|
paul@900 | 282 | system to integrate with storage solutions is avoided, but then those
|
paul@900 | 283 | solutions must expose their LMTP interface appropriately.
|
paul@900 | 284 |
|
paul@912 | 285 | Configuring Mail Storage Providers for LMTP
|
paul@912 | 286 | -------------------------------------------
|
paul@912 | 287 |
|
paul@900 | 288 | Although this topic is largely beyond the scope of this document, systems such
|
paul@900 | 289 | as Cyrus and Dovecot can be configured to provide a Unix domain socket
|
paul@900 | 290 | offering support for LMTP connections.
|
paul@133 | 291 |
|
paul@209 | 292 | For Cyrus, the following bug report is pertinent:
|
paul@209 | 293 |
|
paul@209 | 294 | https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=494746
|
paul@209 | 295 |
|
paul@209 | 296 | A permanent change in permissions on the Cyrus LMTP socket is therefore
|
paul@209 | 297 | required to make delivery available to the lmtp group:
|
paul@209 | 298 |
|
paul@209 | 299 | dpkg-statoverride --force --update --add \
|
paul@209 | 300 | cyrus lmtp 750 /var/run/cyrus/socket
|
paul@209 | 301 |
|
paul@670 | 302 | Configuring Cron for Free/Busy Updates
|
paul@932 | 303 | ======================================
|
paul@670 | 304 |
|
paul@670 | 305 | The periods occupied by recurring events are not expanded beyond a certain
|
paul@670 | 306 | window of time by imip-agent. As a consequence, free/busy collections need to
|
paul@670 | 307 | be progressively expanded over time to include periods occupied by such events
|
paul@670 | 308 | that were not previously recorded in those collections.
|
paul@670 | 309 |
|
paul@670 | 310 | The conf/cron/cron.daily/imip-agent file contains commands that update
|
paul@670 | 311 | free/busy collections for all known users, and this should be copied to the
|
paul@670 | 312 | appropriate destination. For example:
|
paul@670 | 313 |
|
paul@670 | 314 | cp conf/cron/cron.daily/imip-agent /etc/cron.daily/
|
paul@670 | 315 |
|
paul@670 | 316 | Where frequency-specific directories are not supported by cron on a system, a
|
paul@670 | 317 | crontab entry of the appropriate format is required instead.
|
paul@670 | 318 |
|
paul@748 | 319 | Configuring Web Servers for Free/Busy Publishing
|
paul@932 | 320 | ================================================
|
paul@748 | 321 |
|
paul@748 | 322 | Each user may request the publishing of their free/busy information by
|
paul@748 | 323 | configuring certain settings. The conf/apache/imip-agent.conf file provides a
|
paul@748 | 324 | configuration file for deployment with the Apache Web server software that
|
paul@748 | 325 | exposes a directory for Web publishing containing the published free/busy
|
paul@748 | 326 | information.
|
paul@748 | 327 |
|
paul@748 | 328 | Access to free/busy information may not be moderated, but Web server
|
paul@748 | 329 | directives can be introduced to impose access controls. Mail programs that
|
paul@748 | 330 | wish to consult the free/busy information may have problems in dealing with
|
paul@748 | 331 | authentication mechanisms, however, and it may be regarded as acceptable in
|
paul@748 | 332 | certain environments to expose such information publicly or with
|
paul@748 | 333 | network-specific access constraints.
|
paul@748 | 334 |
|
paul@748 | 335 | Configuring Web Servers for the Calendar Management Interface
|
paul@932 | 336 | =============================================================
|
paul@748 | 337 |
|
paul@748 | 338 | A calendar management interface is provided to allow users to view and
|
paul@748 | 339 | interact with their calendars through the Web. The
|
paul@748 | 340 | conf/apache/imip-manager.conf file provides a configuration file for
|
paul@748 | 341 | deployment with the Apache Web server software that enables this interface.
|
paul@748 | 342 |
|
paul@905 | 343 | The management interface is deployed as a CGI program, meaning that a suitable
|
paul@905 | 344 | module must be enabled in the Apache configuration. On Debian, this is done as
|
paul@905 | 345 | follows:
|
paul@905 | 346 |
|
paul@905 | 347 | a2enmod cgi
|
paul@905 | 348 |
|
paul@748 | 349 | Since such access to calendars should only be performed by identified
|
paul@905 | 350 | users, access controls are suggested in the configuration file. Modules
|
paul@905 | 351 | providing additional authentication support may need to be enabled. For
|
paul@905 | 352 | example, on Debian, the LDAP authentication/authorisation support is enabled
|
paul@905 | 353 | as follows:
|
paul@905 | 354 |
|
paul@905 | 355 | a2enmod authnz_ldap
|
paul@748 | 356 |
|
paul@133 | 357 | Prerequisites
|
paul@732 | 358 | =============
|
paul@133 | 359 |
|
paul@133 | 360 | Depending on the mail transport agent (MTA) chosen, the following packages are
|
paul@133 | 361 | required for this software to work on Debian systems:
|
paul@133 | 362 |
|
paul@133 | 363 | Exim: exim4-daemon-heavy
|
paul@133 | 364 | Postfix: postfix postfix-ldap
|
paul@149 | 365 |
|
paul@175 | 366 | The software itself requires the following packages:
|
paul@175 | 367 |
|
paul@890 | 368 | Python: python
|
paul@175 | 369 | pytz: python-tz
|
paul@175 | 370 |
|
paul@900 | 371 | To update free/busy details periodically, the following software is
|
paul@900 | 372 | recommended:
|
paul@900 | 373 |
|
paul@900 | 374 | Cron: cron
|
paul@900 | 375 |
|
paul@149 | 376 | The management Web interface requires the following packages:
|
paul@149 | 377 |
|
paul@890 | 378 | Apache: apache2
|
paul@149 | 379 | Babel: python-babel
|
paul@890 | 380 |
|
paul@890 | 381 | Although not necessarily within the scope of the deployment of this software,
|
paul@890 | 382 | the following mail storage solutions would be used to receive and hold
|
paul@890 | 383 | messages:
|
paul@890 | 384 |
|
paul@890 | 385 | Cyrus: cyrus-imapd
|
paul@890 | 386 | Dovecot: dovecot-imapd dovecot-ldap dovecot-lmtpd
|
paul@908 | 387 |
|
paul@908 | 388 | Some test programs need additional programs provided by other packages:
|
paul@908 | 389 |
|
paul@908 | 390 | envsubst: gettext-base
|