1.1 --- a/README.txt Wed Oct 28 00:37:57 2015 +0100
1.2 +++ b/README.txt Wed Oct 28 00:38:45 2015 +0100
1.3 @@ -11,134 +11,10 @@
1.4 ===============
1.5
1.6 Eventually, this information should be incorporated into packages for various
1.7 -operating system distributions, and these instructions should be largely
1.8 -superfluous for most users.
1.9 -
1.10 -Installing the Software
1.11 -=======================
1.12 -
1.13 -The tools/install.sh script should install the software in appropriate
1.14 -locations. See the prerequisites below for other software that will be
1.15 -required.
1.16 -
1.17 -System User and Filesystem Access
1.18 -=================================
1.19 -
1.20 -The data handled by imip-agent needs to be accessible to other software,
1.21 -notably mail handling software and Web server software. Two approaches are
1.22 -described here: LMTP delivery and local SMTP delivery.
1.23 -
1.24 -LMTP Delivery
1.25 --------------
1.26 -
1.27 -Here, imip-agent's programs run in a way that permits LMTP delivery (requiring
1.28 -suitable local privileges to communicate with the mail storage solution)
1.29 -whilst allowing the Web server to read data written by those programs.
1.30 -
1.31 -A system group needs to be created for LMTP delivery and for certain users to
1.32 -share resources:
1.33 -
1.34 - addgroup lmtp
1.35 -
1.36 -This group should be employed for LMTP delivery by systems like Cyrus and
1.37 -Dovecot. See the section on configuring mail systems for delivery for more
1.38 -information.
1.39 -
1.40 -A system user needs to be created and to belong to certain groups in order to
1.41 -deliver messages to mail stores and to publish resources on the Web:
1.42 -
1.43 - useradd -d /var/lib/imip-agent -m -U -G lmtp,www-data -r imip-agent
1.44 -
1.45 -Store details and published resources need to be accessible by the imip-agent
1.46 -and www-data users. Thus, www-data also needs to belong to the lmtp group:
1.47 -
1.48 - adduser www-data lmtp
1.49 -
1.50 -Local SMTP Delivery
1.51 --------------------
1.52 -
1.53 -Here, imip-agent's programs run in a way that permits local SMTP delivery
1.54 -(which merely needs the ability to connect to a local network service) whilst
1.55 -allowing the Web server to read data written by those programs.
1.56 -
1.57 -A system user needs to be created and to belong to certain groups in order to
1.58 -deliver messages to mail stores and to publish resources on the Web:
1.59 -
1.60 - useradd -d /var/lib/imip-agent -m -U -G www-data -r imip-agent
1.61 -
1.62 -Again, the tools/init.sh script will initialise directories for stored and
1.63 -published data. The tools/config.sh script should be edited and the group
1.64 -redefined as follows:
1.65 -
1.66 - IMIP_AGENT_GROUP=www-data
1.67 -
1.68 -If already installed, the /etc/imip-agent/config.sh script should be edited
1.69 -instead.
1.70 +operating system distributions, and the accompanying instructions should be
1.71 +largely superfluous for most users.
1.72
1.73 -With local SMTP delivery, the mail system will need to be configured to route
1.74 -messages for local recipients. See the description of mail configuration for
1.75 -more information.
1.76 -
1.77 -Initialising the Software
1.78 -=========================
1.79 -
1.80 -Once a suitable system user has been chosen, stored and published data is then
1.81 -initialised using the tools/init.sh script. The script employs the setgid flag
1.82 -on the directories initialised for stored and published data so that new files
1.83 -and directories have the appropriate group associated with them.
1.84 -
1.85 -It should be possible to omit all arguments to the init.sh script, but it is
1.86 -also worth reading the help message:
1.87 -
1.88 - tools/init.sh --help
1.89 -
1.90 -Fixing ownership can be done using the tools/fix.sh script, in case some form
1.91 -of modification has altered the ownership or membership of the created files
1.92 -and directories.
1.93 -
1.94 -Configuring Other Software
1.95 -==========================
1.96 -
1.97 -The conf directory contains subdirectories for different systems:
1.98 -
1.99 - apache Apache 2 site configuration for publishing resources
1.100 - cron Cron command scheduling for free/busy updates
1.101 - exim Exim 4 routing and transport configuration
1.102 - ldap Some LDAP-related resources
1.103 - postfix Postfix routing and transport configuration
1.104 -
1.105 -Either Exim or Postfix can be chosen as a mail system supporting the agent.
1.106 -
1.107 -Configuring Mail Systems for the Agent
1.108 -======================================
1.109 -
1.110 -The essential aspect of mail system configuration involves mail transports and
1.111 -the integration of agent programs into the mail processing pipeline. Thus, the
1.112 -following files are of particular interest:
1.113 -
1.114 -For Exim (in conf/exim)...
1.115 -
1.116 - 30_exim4-config_people Integration of agent programs
1.117 - 30_exim4-config_people_outgoing ...
1.118 - 30_exim4-config_resources ...
1.119 -
1.120 -For Postfix (in conf/postfix)...
1.121 -
1.122 - master.cf.items Integration of agent programs (for
1.123 - inclusion in master.cf)
1.124 - transport Configuration of agent transports
1.125 - virtual Configuration of outgoing mail routing
1.126 -
1.127 -Such files need adjusting for the deployment environment so that, for example,
1.128 -the example.com domain would be replaced with a suitable value.
1.129 -
1.130 -If local SMTP delivery is being used, the 30_exim4-config_people file (in
1.131 -conf/exim) or the master.cf.items file (in conf/postfix) will need adjusting.
1.132 -
1.133 -If LMTP is being used, instances of LMTP_SOCKET in the example configuration
1.134 -files will need to be replaced with a suitable filesystem path. Where the lmtp
1.135 -system group is employed, it may be replaced with a different group. See
1.136 -below for a discussion of LMTP and mail delivery.
1.137 +See: docs/wiki/GettingStarted
1.138
1.139 Configuring Mail Systems for Mail Recipients
1.140 ============================================
1.141 @@ -152,114 +28,9 @@
1.142 disregarded in favour of other ways of defining mail recipients, subject to
1.143 the needs of any given environment.
1.144
1.145 -Using LDAP with Exim
1.146 ---------------------
1.147 -
1.148 -For Exim (in conf/exim/ldap)...
1.149 -
1.150 - 010_exim4-config_ldap_people_outgoing Defines recipients and outgoing
1.151 - mail routing
1.152 - 020_exim4-config_ldap_people ...
1.153 - 020_exim4-config_ldap_resources ...
1.154 - 020_exim4-config_ldap_people_outgoing_recipients
1.155 -
1.156 -Using LDAP with Postfix
1.157 ------------------------
1.158 -
1.159 -For Postfix (in conf/postfix/ldap)...
1.160 -
1.161 - main.cf.example Defines recipients and outgoing
1.162 - mail routing (for inclusion in
1.163 - main.cf)
1.164 -
1.165 - virtual_alias_maps_people.cf Defines recipients and outgoing
1.166 - virtual_alias_maps_people_outgoing.cf mail routing
1.167 - virtual_alias_maps_resources.cf ...
1.168 -
1.169 -Using Lists of Identities
1.170 --------------------------
1.171 -
1.172 -Since the use of LDAP can be somewhat challenging and also excessive in some
1.173 -situations, examples of maintaining recipient information using a simpler
1.174 -approach are provided.
1.175 -
1.176 -In this simpler environment, recipient details must be manually edited in the
1.177 -virtual identity files, but this permits a very transparent way of
1.178 -administering the system.
1.179 -
1.180 -Using Lists with Exim
1.181 ----------------------
1.182 -
1.183 -For Exim (in conf/exim/simple)...
1.184 -
1.185 - 010_exim4-config_people_outgoing Defines recipients and outgoing
1.186 - mail routing
1.187 - 020_exim4-config_people ...
1.188 - 020_exim4-config_resources ...
1.189 - 020_exim4-config_people_outgoing_recipients
1.190 -
1.191 - virtual_people Defines recipient identities
1.192 - virtual_people_outgoing_recipients belonging to known domains
1.193 - virtual_resources ...
1.194 -
1.195 - virtual_domains Defines recipient domains
1.196 -
1.197 -To add support for delivery to local mailboxes, the following additional file
1.198 -is provided as an example:
1.199 -
1.200 - virtual_people_local Defines recipients and local users
1.201 -
1.202 -And to route bounced messages back to the generic calendar address, an
1.203 -addition to the /etc/aliases file is provided:
1.204 -
1.205 - aliases.example Routes calendar to root
1.206 -
1.207 -Using Lists with Postfix
1.208 -------------------------
1.209 -
1.210 -For Postfix (in conf/postfix/simple)...
1.211 -
1.212 - main.cf.example Defines recipients and outgoing
1.213 - mail routing (for inclusion in
1.214 - main.cf)
1.215 -
1.216 - virtual_alias_maps Defines recipients and outgoing
1.217 - virtual_alias_maps_people_outgoing mail routing
1.218 -
1.219 -To add support for delivery to local mailboxes, the following alternative to
1.220 -virtual_alias_maps is provided as an example:
1.221 -
1.222 - virtual_alias_maps_local Defines recipients and local users
1.223 -
1.224 -LDAP Representations for Mail Recipients
1.225 -----------------------------------------
1.226 -
1.227 -Relevant LDAP resources for structuring recipient information include the
1.228 -following:
1.229 -
1.230 - RFC 4524 Defines the mail attribute
1.231 - http://tools.ietf.org/html/rfc4524
1.232 -
1.233 - RFC 2798 Defines the inetOrgPerson object
1.234 - http://tools.ietf.org/html/rfc2798 class
1.235 -
1.236 - RFC 2739 Defines the calEntry object class
1.237 - https://tools.ietf.org/html/rfc2739 supporting calFBURL
1.238 -
1.239 -An additional draft RFC describes the mailRecipient object class:
1.240 -
1.241 - https://tools.ietf.org/html/draft-lachman-ldap-mail-routing-03
1.242 -
1.243 -Resource schemas for LDAP are not effectively standardised for the purposes of
1.244 -this software. A useful object class, inetResource, was defined for the
1.245 -iPlanet Calendar Server:
1.246 -
1.247 - http://docs.oracle.com/cd/E19566-01/819-4437/6n6jckqrf/index.html#anocg
1.248 - http://docs.oracle.com/cd/E19566-01/819-4437/6n6jckqr8/index.html
1.249 -
1.250 -Although Kolab maintains notions of resources, they are tied up with the
1.251 -notion of a shared folder and the kolabSharedFolder object class, although the
1.252 -mailRecipient object class is employed by resources in Kolab.
1.253 +See: docs/wiki/MailIntegration
1.254 +See: docs/wiki/MailIntegration--LDAP
1.255 +See: docs/wiki/MailIntegration--Simple
1.256
1.257 Configuring Mail Systems for Mail Delivery
1.258 ==========================================
1.259 @@ -268,53 +39,9 @@
1.260 performed either using local SMTP or by using LMTP to a suitable mailbox
1.261 provider.
1.262
1.263 -If employing local SMTP, the burden of routing messages to suitable storage
1.264 -becomes a configuration problem within the mail system itself, but given that
1.265 -routing to local system users is typically supported "out of the box", this
1.266 -can provide a usable solution with minimal effort.
1.267 -
1.268 -Where the mail system must instead route messages to mailbox providers
1.269 -employing LMTP, some more effort is required. For Exim, some sample
1.270 -configuration files are provided in conf/exim/lmtp to route messages for local
1.271 -users to LMTP endpoints.
1.272 -
1.273 -By using LMTP from the agent software, the issue of configuring the mail
1.274 -system to integrate with storage solutions is avoided, but then those
1.275 -solutions must expose their LMTP interface appropriately.
1.276 -
1.277 -Configuring Mail Storage Providers for LMTP
1.278 --------------------------------------------
1.279 -
1.280 -Although this topic is largely beyond the scope of this document, systems such
1.281 -as Cyrus and Dovecot can be configured to provide a Unix domain socket
1.282 -offering support for LMTP connections.
1.283 -
1.284 -For Cyrus, the following bug report is pertinent:
1.285 -
1.286 -https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=494746
1.287 -
1.288 -A permanent change in permissions on the Cyrus LMTP socket is therefore
1.289 -required to make delivery available to the lmtp group:
1.290 -
1.291 - dpkg-statoverride --force --update --add \
1.292 - cyrus lmtp 750 /var/run/cyrus/socket
1.293 -
1.294 -Configuring Cron for Free/Busy Updates
1.295 -======================================
1.296 -
1.297 -The periods occupied by recurring events are not expanded beyond a certain
1.298 -window of time by imip-agent. As a consequence, free/busy collections need to
1.299 -be progressively expanded over time to include periods occupied by such events
1.300 -that were not previously recorded in those collections.
1.301 -
1.302 -The conf/cron/cron.daily/imip-agent file contains commands that update
1.303 -free/busy collections for all known users, and this should be copied to the
1.304 -appropriate destination. For example:
1.305 -
1.306 -cp conf/cron/cron.daily/imip-agent /etc/cron.daily/
1.307 -
1.308 -Where frequency-specific directories are not supported by cron on a system, a
1.309 -crontab entry of the appropriate format is required instead.
1.310 +See: docs/wiki/MailIntegration
1.311 +See: docs/wiki/MailIntegration--LMTP
1.312 +See: docs/wiki/MailIntegration--LocalSMTP
1.313
1.314 Configuring Web Servers for Free/Busy Publishing
1.315 ================================================
1.316 @@ -353,38 +80,3 @@
1.317 as follows:
1.318
1.319 a2enmod authnz_ldap
1.320 -
1.321 -Prerequisites
1.322 -=============
1.323 -
1.324 -Depending on the mail transport agent (MTA) chosen, the following packages are
1.325 -required for this software to work on Debian systems:
1.326 -
1.327 - Exim: exim4-daemon-heavy
1.328 - Postfix: postfix postfix-ldap
1.329 -
1.330 -The software itself requires the following packages:
1.331 -
1.332 - Python: python
1.333 - pytz: python-tz
1.334 -
1.335 -To update free/busy details periodically, the following software is
1.336 -recommended:
1.337 -
1.338 - Cron: cron
1.339 -
1.340 -The management Web interface requires the following packages:
1.341 -
1.342 - Apache: apache2
1.343 - Babel: python-babel
1.344 -
1.345 -Although not necessarily within the scope of the deployment of this software,
1.346 -the following mail storage solutions would be used to receive and hold
1.347 -messages:
1.348 -
1.349 - Cyrus: cyrus-imapd
1.350 - Dovecot: dovecot-imapd dovecot-ldap dovecot-lmtpd
1.351 -
1.352 -Some test programs need additional programs provided by other packages:
1.353 -
1.354 - envsubst: gettext-base
2.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
2.2 +++ b/docs/wiki/Configuration Wed Oct 28 00:38:45 2015 +0100
2.3 @@ -0,0 +1,30 @@
2.4 += Configuration =
2.5 +
2.6 +There are two principal configuration files in imip-agent:
2.7 +
2.8 + * `config.py` provides the configuration to the software itself
2.9 + * `config.sh` provides system-level and tool configuration
2.10 +
2.11 +These files are by default installed into the `/etc/imip-agent` directory
2.12 +and they can be changed in that location once the system is installed.
2.13 +
2.14 +== System User and Filesystem Configuration ==
2.15 +
2.16 +Given a choice of [[../SystemUsers|system users and groups]], the
2.17 +resulting configuration must be indicated in the `config.sh` file. Since
2.18 +the `tools/install.sh` script depends on this configuration, changes must
2.19 +be made to the file in the `tools/config.sh` location before installation
2.20 +can occur.
2.21 +
2.22 +== Agent System Configuration ==
2.23 +
2.24 +Any changes to filesystem locations may need to be incorporated into the
2.25 +`config.py` file, which is found in the `imiptools/config.py` location of
2.26 +the distribution. There is, however, no urgency in changing this file
2.27 +before installation, and it can be edited in its installed location to
2.28 +achieve the same effects.
2.29 +
2.30 +The agent system configuration dictates how the software behaves, and the
2.31 +`config.py` file provides system-level settings (filesystem locations
2.32 +and file permissions), service-level settings (e-mail address and Web site
2.33 +choices), and default policies for users of the software.
3.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
3.2 +++ b/docs/wiki/CronIntegration Wed Oct 28 00:38:45 2015 +0100
3.3 @@ -0,0 +1,20 @@
3.4 += Cron Task Scheduler Integration =
3.5 +
3.6 +The periods occupied by recurring events are not expanded beyond a certain
3.7 +window of time by imip-agent. As a consequence, free/busy collections need to
3.8 +be progressively expanded over time to include periods occupied by such events
3.9 +that were not previously recorded in those collections.
3.10 +
3.11 +The `conf/cron/cron.daily/imip-agent` file contains commands that update
3.12 +free/busy collections for all known users, and this should be copied to the
3.13 +appropriate destination. For example:
3.14 +
3.15 +{{{
3.16 +cp conf/cron/cron.daily/imip-agent /etc/cron.daily/
3.17 +}}}
3.18 +
3.19 +Where frequency-specific directories are not supported by cron on a system, a
3.20 +`crontab` entry of the appropriate format is required instead.
3.21 +
3.22 +See the [[../EventRecurrences|guide to event recurrences]] for more information
3.23 +on how recurring events are supported.
4.1 --- a/docs/wiki/EventRecurrences Wed Oct 28 00:37:57 2015 +0100
4.2 +++ b/docs/wiki/EventRecurrences Wed Oct 28 00:38:45 2015 +0100
4.3 @@ -94,6 +94,7 @@
4.4 regularly scheduled task be used to consult the events known (or thought) to
4.5 provide additional free/busy periods and to record such additional periods for
4.6 each user. This can be done using a system's `cron` daemon and a suitable
4.7 -script in `/etc/cron.daily` or equivalent. Such a script is provided in the
4.8 -imip-agent distribution along with a program that can expand availability
4.9 -information for all known recipients of calendar information.
4.10 +script in `/etc/cron.daily` or equivalent. Such a script is
4.11 +[[../CronIntegration|provided]] in the imip-agent distribution along with a
4.12 +program that can expand availability information for all known recipients of
4.13 +calendar information.
5.1 --- a/docs/wiki/FrontPage Wed Oct 28 00:37:57 2015 +0100
5.2 +++ b/docs/wiki/FrontPage Wed Oct 28 00:38:45 2015 +0100
5.3 @@ -87,15 +87,21 @@
5.4 According to your requirements, any or all of the above solutions can be
5.5 implemented, providing as much of a groupware solution as you need.
5.6
5.7 +== Deployment Notes ==
5.8 +
5.9 + * [[/GettingStarted|Getting Started]]
5.10 +
5.11 == Design and Implementation Notes ==
5.12
5.13 Details of the mechanisms employed by imip-agent are described in the
5.14 following documents:
5.15
5.16 * [[/CounterProposals|Counter-Proposals and Offers]]
5.17 + * [[/CronIntegration|Cron Task Scheduler Integration]]
5.18 * [[/MailIntegration|E-Mail Integration]]
5.19 * [[/EventRecurrences|Event Recurrences]]
5.20 * [[/IncomingMessages|Incoming Messages]]
5.21 * [[/OutgoingMessages|Outgoing Messages]]
5.22 + * [[/Testing|Testing]]
5.23 * [[/UseCases|Use Cases]]
5.24 * [[/WebServerIntegration|Web Server Integration]]
6.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
6.2 +++ b/docs/wiki/GettingStarted Wed Oct 28 00:38:45 2015 +0100
6.3 @@ -0,0 +1,74 @@
6.4 += Getting Started =
6.5 +
6.6 +To get imip-agent running on your own system you will need the following:
6.7 +
6.8 + * The ability to install software and to configure the system
6.9 + * A working mail configuration
6.10 +
6.11 +It is possible to [[../Testing|test the agent programs]] without these
6.12 +abilities, but any difficulties in getting the software to work will be
6.13 +compounded by any problem or deficiency in either of these areas.
6.14 +
6.15 +== Configuring System Users ==
6.16 +
6.17 +The [[../SystemUsers|system users guide]] indicates the requirements for
6.18 +system user and group configuration.
6.19 +
6.20 +If you are comfortable configuring your mail system, you may decide to
6.21 +choose the [[../MailIntegration/LocalSMTP|local SMTP delivery]] approach.
6.22 +
6.23 +If you already use mail storage solutions that employ LMTP, you may decide
6.24 +to choose the [[../MailIntegration/LMTP|LMTP delivery]] approach.
6.25 +
6.26 +== Installing the Software ==
6.27 +
6.28 +Ideally, an operating system distribution package should be used to
6.29 +install the software. As a result, the software should already be suitably
6.30 +integrated and configured and guidance will be available to get everything
6.31 +working.
6.32 +
6.33 + 1. In the absence of a suitable system package, the installation locations
6.34 + and system user details must first be configured, as described above.
6.35 +
6.36 + 1. Then, the `tools/install.sh` script should install the software in
6.37 + appropriate locations. You may need to be `root` or use `sudo` to
6.38 + successfully use this script.
6.39 +
6.40 +See the [[../Prerequisites|prerequisites]] for other software that will be
6.41 +required for the software to function.
6.42 +
6.43 +== Initialising the Software ==
6.44 +
6.45 +Once a suitable system user has been chosen, stored and published data is then
6.46 +initialised using the `tools/init.sh` script. The script employs the setgid
6.47 +flag on the directories initialised for stored and published data so that new
6.48 +files and directories have the appropriate group associated with them.
6.49 +
6.50 +It should be possible to omit all arguments to the `init.sh` script, but it is
6.51 +also worth reading the help message:
6.52 +
6.53 +{{{
6.54 +tools/init.sh --help
6.55 +}}}
6.56 +
6.57 +Fixing ownership can be done using the `tools/fix.sh` script, in case some form
6.58 +of modification has altered the ownership or membership of the created files
6.59 +and directories.
6.60 +
6.61 +== Configuring Other Software ==
6.62 +
6.63 +The `conf` directory contains subdirectories for different systems:
6.64 +
6.65 +|| '''Directory''' || '''Description''' ||
6.66 +|| `apache` || Apache 2 site configuration for publishing resources ||
6.67 +|| `cron` || Cron command scheduling for free/busy updates ||
6.68 +|| `exim` || Exim 4 routing and transport configuration ||
6.69 +|| `ldap` || Some LDAP-related resources ||
6.70 +|| `postfix` || Postfix routing and transport configuration ||
6.71 +
6.72 +The configuration activities associated with these directories are covered in
6.73 +the following documents:
6.74 +
6.75 + * [[../CronIntegration|Cron Task Scheduler Integration]]
6.76 + * [[../MailIntegration|E-Mail Integration]]
6.77 + * [[../WebServerIntegration|Web Server Integration]]
7.1 --- a/docs/wiki/MailIntegration Wed Oct 28 00:37:57 2015 +0100
7.2 +++ b/docs/wiki/MailIntegration Wed Oct 28 00:38:45 2015 +0100
7.3 @@ -51,11 +51,25 @@
7.4 [[/Simple|Simple (list-based identification)]] || Exim, Postfix
7.5 }}}
7.6
7.7 +== Invoking the Agent Programs ==
7.8 +
7.9 +Regardless of identification or delivery mechanisms, the imip-agent software
7.10 +must be integrated into the mail processing pipeline so that messages can be
7.11 +interpreted and processed. This is done by configuring the MTA's
7.12 +[[/Transports|transport mechanisms]].
7.13 +
7.14 == Delivery ==
7.15
7.16 To deliver messages to their ultimate recipients after having processed them,
7.17 imip-agent currently employs either local SMTP connections or
7.18 [[https://tools.ietf.org/html/rfc2033|LMTP]]. There is nothing in principle
7.19 preventing imip-agent from also supporting other common delivery mechanisms,
7.20 -however. Currently, Cyrus-IMAP and Dovecot have both been tested with
7.21 -imip-agent, along with delivery to local system users.
7.22 +however.
7.23 +
7.24 +{{{#!table
7.25 +'''Delivery Mechanisms''' || '''Tested with...'''
7.26 +==
7.27 +[[/LocalSMTP|Local SMTP]] || Exim, Postfix
7.28 +==
7.29 +[[/LMTP|LMTP]] || Exim, Postfix
7.30 +}}}
8.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
8.2 +++ b/docs/wiki/MailIntegration--LMTP Wed Oct 28 00:38:45 2015 +0100
8.3 @@ -0,0 +1,24 @@
8.4 += LMTP Delivery =
8.5 +
8.6 +When imip-agent is configured to use LMTP, it connects directly to mail
8.7 +storage solutions. By using LMTP from the agent software, the issue of
8.8 +configuring the mail system to integrate with such solutions is avoided, but
8.9 +then those solutions must expose their LMTP interface appropriately.
8.10 +
8.11 +Although this topic is largely beyond the scope of this document, systems such
8.12 +as Cyrus and Dovecot can be configured to provide a Unix domain socket
8.13 +offering support for LMTP connections.
8.14 +
8.15 +For Cyrus, the following bug report is pertinent:
8.16 +
8.17 + * https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=494746
8.18 +
8.19 +A permanent change in permissions on the Cyrus LMTP socket is therefore
8.20 +required to make delivery available to the `lmtp` group:
8.21 +
8.22 +{{{
8.23 +dpkg-statoverride --force --update --add cyrus lmtp 750 /var/run/cyrus/socket
8.24 +}}}
8.25 +
8.26 +See the [[../../SystemUsers|system users]] documentation for a discussion of
8.27 +users and groups.
9.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
9.2 +++ b/docs/wiki/MailIntegration--LocalSMTP Wed Oct 28 00:38:45 2015 +0100
9.3 @@ -0,0 +1,24 @@
9.4 += Local SMTP Delivery =
9.5 +
9.6 +By employing local SMTP, the burden of routing messages to suitable storage
9.7 +becomes a configuration problem within the mail system itself. Here, imip-agent
9.8 +connects to the mail transport agent (MTA) and sends a message to an
9.9 +explicitly-indicated local user such as, for example:
9.10 +
9.11 +{{{
9.12 +local+vincent.vole@example.com
9.13 +}}}
9.14 +
9.15 +The message is then routed to a mail delivery mechanism, perhaps by converting
9.16 +the local address to a local user identity:
9.17 +
9.18 +{{{
9.19 +vole
9.20 +}}}
9.21 +
9.22 +The local delivery mechanism would then deposit the message in the user's mailbox.
9.23 +
9.24 +Where the mail system must instead route messages to mailbox providers
9.25 +employing LMTP, some more effort is required. For Exim, some sample
9.26 +configuration files are provided in `conf/exim/lmtp` to route messages for local
9.27 +users to LMTP endpoints.
10.1 --- a/docs/wiki/MailIntegration--Simple Wed Oct 28 00:37:57 2015 +0100
10.2 +++ b/docs/wiki/MailIntegration--Simple Wed Oct 28 00:38:45 2015 +0100
10.3 @@ -38,6 +38,10 @@
10.4 || Defines recipients and local users for delivery to local mailboxes
10.5 }}}
10.6
10.7 +These files can be incorporated into the Exim configuration. On Debian
10.8 +systems, the numbered files can be copied into `/etc/exim4/conf.d/router`,
10.9 +whereas the virtual files can be copied into `/etc/exim4`.
10.10 +
10.11 == Using Lists with Postfix ==
10.12
10.13 Example configuration file for Postfix are distributed in `conf/postfix/simple`:
10.14 @@ -56,3 +60,7 @@
10.15 `virtual_alias_maps_local`
10.16 || Defines recipients and local users for delivery to local mailboxes
10.17 }}}
10.18 +
10.19 +These files can be incorporated into the Postfix configuration. On Debian
10.20 +systems, `main.cf.example` can be merged into `/etc/postfix/main.cf`,
10.21 +whereas the remaining files would be installed into `/etc/postfix`.
11.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
11.2 +++ b/docs/wiki/MailIntegration--Transports Wed Oct 28 00:38:45 2015 +0100
11.3 @@ -0,0 +1,58 @@
11.4 += Mail Transports and Invoking Agent Programs =
11.5 +
11.6 +The essential aspect of mail system configuration involves mail transports and
11.7 +the integration of agent programs into the mail processing pipeline. A number of
11.8 +example files are provided here.
11.9 +
11.10 +Such files need adjusting for the deployment environment so that, for example,
11.11 +the `example.com` domain would be replaced with a suitable value.
11.12 +
11.13 +If LMTP is being used, instances of `LMTP_SOCKET` in the example configuration
11.14 +files will need to be replaced with a suitable filesystem path. Where the `lmtp`
11.15 +system group is employed, it may be replaced with a different group. See the
11.16 +[[../LMTP|LMTP guide]] for a discussion of LMTP and mail delivery.
11.17 +
11.18 +== Transports in Exim ==
11.19 +
11.20 +Example configuration files for Exim are distributed in `conf/exim`:
11.21 +
11.22 +{{{#!table
11.23 +'''File''' || '''Purpose'''
11.24 +==
11.25 +`30_exim4-config_people`
11.26 +||<rowspan="3"> Integration of agent programs
11.27 +==
11.28 +`30_exim4-config_people_outgoing`
11.29 +==
11.30 +`30_exim4-config_resources`
11.31 +}}}
11.32 +
11.33 +These files can be incorporated into the Exim configuration. On Debian
11.34 +systems, they can be copied into `/etc/exim4/conf.d/transport`.
11.35 +
11.36 +If local SMTP delivery is being used, the `30_exim4-config_people` file (in
11.37 +`conf/exim`) will need adjusting.
11.38 +
11.39 +== Transports in Postfix ==
11.40 +
11.41 +Example configuration files for Postfix are distributed in `conf/postfix`:
11.42 +
11.43 +{{{#!table
11.44 +'''File''' || '''Purpose'''
11.45 +==
11.46 +`master.cf.items`
11.47 +|| Integration of agent programs (for inclusion in `master.cf`)
11.48 +==
11.49 +`transport`
11.50 +|| Configuration of agent transports
11.51 +==
11.52 +`virtual`
11.53 +|| Configuration of outgoing mail routing
11.54 +}}}
11.55 +
11.56 +These files can be incorporated into the Postfix configuration. On Debian
11.57 +systems, `master.cf.items` can be merged into `/etc/postfix/master.cf`,
11.58 +whereas the remaining files would be installed into `/etc/postfix`.
11.59 +
11.60 +If local SMTP delivery is being used, the `master.cf.items` file (in
11.61 +`conf/postfix`) will need adjusting.
12.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
12.2 +++ b/docs/wiki/Prerequisites Wed Oct 28 00:38:45 2015 +0100
12.3 @@ -0,0 +1,33 @@
12.4 += Prerequisites =
12.5 +
12.6 +Depending on the mail transport agent (MTA) chosen, the following packages are
12.7 +required for this software to work on Debian systems:
12.8 +
12.9 + Exim:: exim4-daemon-heavy
12.10 + Postfix:: postfix postfix-ldap
12.11 +
12.12 +The software itself requires the following packages:
12.13 +
12.14 + Python:: python
12.15 + pytz:: python-tz
12.16 +
12.17 +To update free/busy details periodically, the following software is
12.18 +recommended:
12.19 +
12.20 + Cron:: cron
12.21 +
12.22 +The management Web interface requires the following packages:
12.23 +
12.24 + Apache:: apache2
12.25 + Babel:: python-babel
12.26 +
12.27 +Although not necessarily within the scope of the deployment of this software,
12.28 +the following mail storage solutions would be used to receive and hold
12.29 +messages:
12.30 +
12.31 + Cyrus:: cyrus-imapd
12.32 + Dovecot:: dovecot-imapd dovecot-ldap dovecot-lmtpd
12.33 +
12.34 +Some test programs need additional programs provided by other packages:
12.35 +
12.36 + envsubst:: gettext-base
13.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
13.2 +++ b/docs/wiki/SystemUsers Wed Oct 28 00:38:45 2015 +0100
13.3 @@ -0,0 +1,84 @@
13.4 += System Users and Filesystem Access =
13.5 +
13.6 +The data handled by imip-agent needs to be accessible to other software,
13.7 +notably mail handling software and Web server software. Two approaches to
13.8 +[[../MailIntegration|e-mail integration]] affect the choice of system users
13.9 +and groups:
13.10 +
13.11 +{{{#!table
13.12 +'''Integration Method''' || '''System Users and Groups'''
13.13 +==
13.14 +[[../MailIntegration/LMTP|LMTP delivery]]
13.15 +|| `imip-agent` belongs to `lmtp` and `www-data` groups<<BR>>
13.16 +.. `www-data` also belongs to the `lmtp` group
13.17 +==
13.18 +[[../MailIntegration/LocalSMTP|Local SMTP delivery]]
13.19 +|| `imip-agent` belongs to the `www-data` group
13.20 +}}}
13.21 +
13.22 +The corresponding strategies are described in more detail below.
13.23 +
13.24 +== LMTP Delivery ==
13.25 +
13.26 +Here, imip-agent's programs run in a way that permits LMTP delivery (requiring
13.27 +suitable local privileges to communicate with the mail storage solution)
13.28 +whilst allowing the Web server to read data written by those programs.
13.29 +
13.30 +A system group needs to be created for LMTP delivery and for certain users to
13.31 +share resources:
13.32 +
13.33 +{{{
13.34 +addgroup lmtp
13.35 +}}}
13.36 +
13.37 +This group should be employed for LMTP delivery by systems like Cyrus and
13.38 +Dovecot. See the section on configuring mail systems for delivery for more
13.39 +information.
13.40 +
13.41 +A system user needs to be created and to belong to certain groups in order to
13.42 +deliver messages to mail stores and to publish resources on the Web:
13.43 +
13.44 +{{{
13.45 +useradd -d /var/lib/imip-agent -m -U -G lmtp,www-data -r imip-agent
13.46 +}}}
13.47 +
13.48 +Store details and published resources need to be accessible by the `imip-agent`
13.49 +and `www-data` users. Thus, `www-data` also needs to belong to the `lmtp` group:
13.50 +
13.51 +{{{
13.52 +adduser www-data lmtp
13.53 +}}}
13.54 +
13.55 +== Local SMTP Delivery ==
13.56 +
13.57 +Here, imip-agent's programs run in a way that permits local SMTP delivery
13.58 +(which merely needs the ability to connect to a local network service) whilst
13.59 +allowing the Web server to read data written by those programs.
13.60 +
13.61 +A system user needs to be created and to belong to certain groups in order to
13.62 +deliver messages to mail stores and to publish resources on the Web:
13.63 +
13.64 +{{{
13.65 +useradd -d /var/lib/imip-agent -m -U -G www-data -r imip-agent
13.66 +}}}
13.67 +
13.68 +Again, the `tools/init.sh` script will initialise directories for stored and
13.69 +published data. The `tools/config.sh` script should be edited and the group
13.70 +redefined as follows:
13.71 +
13.72 +{{{
13.73 +IMIP_AGENT_GROUP=www-data
13.74 +}}}
13.75 +
13.76 +If already installed, the `/etc/imip-agent/config.sh` script should be edited
13.77 +instead. See the [[../Configuration|configuration guide]] for more information.
13.78 +
13.79 +With local SMTP delivery, the mail system will need to be configured to route
13.80 +messages for local recipients. See the [[../MailIntegration/LocalSMTP|local SMTP]]
13.81 +description of mail configuration for more information.
13.82 +
13.83 +== Updating the Configuration ==
13.84 +
13.85 +Once the necessary decisions have been taken here, the system's
13.86 +[[../Configuration|configuration]] will need updating so that the software and
13.87 +tools will work correctly.
14.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
14.2 +++ b/docs/wiki/Testing Wed Oct 28 00:38:45 2015 +0100
14.3 @@ -0,0 +1,72 @@
14.4 += Testing =
14.5 +
14.6 +To see how the software operates, you can run one of the agent programs
14.7 +provided in the distribution. For example:
14.8 +
14.9 +{{{
14.10 +./imip_resource.py -S xxx/store -P xxx/static -p xxx/prefs -d \
14.11 + < tests/templates/event-request.txt
14.12 +}}}
14.13 +
14.14 +This uses one of the test files, sending it to the agent program for
14.15 +resource entities, producing output resembling the following:
14.16 +
14.17 +{{{
14.18 +Outgoing parts for paul.boddie@example.com...
14.19 +From nobody Wed Oct 28 00:24:41 2015
14.20 +MIME-Version: 1.0
14.21 +Content-Transfer-Encoding: base64
14.22 +Content-Type: text/calendar; charset="utf-8"; method="REPLY"
14.23 +From: calendar@example.com
14.24 +To: paul.boddie@example.com
14.25 +Subject: Calendar system message
14.26 +
14.27 +QkVHSU46VkNBTEVOREFSDQpNRVRIT0Q6UkVQTFkNClZFUlNJT046Mi4wDQpCRUdJTjpWRlJFRUJV
14.28 +U1kNCk9SR0FOSVpFUjptYWlsdG86cGF1bC5ib2RkaWVAZXhhbXBsZS5jb20NCkFUVEVOREVFO1NF
14.29 +TlQtQlk9Im1haWx0bzpjYWxlbmRhckBleGFtcGxlLmNvbSI6bWFpbHRvOnJlc291cmNlLXJvb20t
14.30 +Y29uZnJvb20NCiBAZXhhbXBsZS5jb20NClVJRDpmYjFAZXhhbXBsZS5jb20NCkVORDpWRlJFRUJV
14.31 +U1kNCkVORDpWQ0FMRU5EQVINCg==
14.32 +}}}
14.33 +
14.34 +The rather opaque encoding can be inspected using the `tools/showmail.py`
14.35 +program, and thus the result of the script can be seen by piping the output
14.36 +through that program as follows:
14.37 +
14.38 +{{{
14.39 +./imip_resource.py -S xxx/store/ -P xxx/static/ -p xxx/prefs/ -d \
14.40 + < tests/templates/event-request.txt \
14.41 + | tools/showmail.py
14.42 +}}}
14.43 +
14.44 +The result should resemble the following:
14.45 +
14.46 +{{{
14.47 +Outgoing parts for paul.boddie@example.com...
14.48 +MIME-Version: 1.0
14.49 +Content-Type: text/calendar; charset="utf-8"; method="REPLY"
14.50 +From: calendar@example.com
14.51 +To: paul.boddie@example.com
14.52 +Subject: Calendar system message
14.53 +
14.54 +BEGIN:VCALENDAR
14.55 +METHOD:REPLY
14.56 +VERSION:2.0
14.57 +BEGIN:VEVENT
14.58 +DTSTAMP:20151027T232738Z
14.59 +UID:event1@example.com
14.60 +ATTENDEE;PARTSTAT=ACCEPTED;SENT-BY="mailto:calendar@example.com":mailto:reso
14.61 + urce-room-confroom@example.com
14.62 +SUMMARY:Meeting at 4pm
14.63 +ORGANIZER:mailto:paul.boddie@example.com
14.64 +DTSTART;TZID=Europe/Oslo:20141126T160000
14.65 +DTEND;TZID=Europe/Oslo:20141126T170000
14.66 +END:VEVENT
14.67 +END:VCALENDAR
14.68 +}}}
14.69 +
14.70 +What has happened here is the presentation of a request to the resource
14.71 +program in the form of an e-mail message containing an iCalendar event
14.72 +employing a scheduling method. The program interprets the request,
14.73 +consults its own records, makes a decision about scheduling the event,
14.74 +and indicates the kind of response it would like to send back to the
14.75 +requester.