# HG changeset patch # User Paul Boddie # Date 1445989125 -3600 # Node ID 18aa266fe15d30ae540d7949b48d073046573117 # Parent 06e9eb58ca55720f56fe642e80530cce9de5a175 Moved documentation to the wiki page representations, tidying along the way. diff -r 06e9eb58ca55 -r 18aa266fe15d README.txt --- a/README.txt Wed Oct 28 00:37:57 2015 +0100 +++ b/README.txt Wed Oct 28 00:38:45 2015 +0100 @@ -11,134 +11,10 @@ =============== Eventually, this information should be incorporated into packages for various -operating system distributions, and these instructions should be largely -superfluous for most users. - -Installing the Software -======================= - -The tools/install.sh script should install the software in appropriate -locations. See the prerequisites below for other software that will be -required. - -System User and Filesystem Access -================================= - -The data handled by imip-agent needs to be accessible to other software, -notably mail handling software and Web server software. Two approaches are -described here: LMTP delivery and local SMTP delivery. - -LMTP Delivery -------------- - -Here, imip-agent's programs run in a way that permits LMTP delivery (requiring -suitable local privileges to communicate with the mail storage solution) -whilst allowing the Web server to read data written by those programs. - -A system group needs to be created for LMTP delivery and for certain users to -share resources: - - addgroup lmtp - -This group should be employed for LMTP delivery by systems like Cyrus and -Dovecot. See the section on configuring mail systems for delivery for more -information. - -A system user needs to be created and to belong to certain groups in order to -deliver messages to mail stores and to publish resources on the Web: - - useradd -d /var/lib/imip-agent -m -U -G lmtp,www-data -r imip-agent - -Store details and published resources need to be accessible by the imip-agent -and www-data users. Thus, www-data also needs to belong to the lmtp group: - - adduser www-data lmtp - -Local SMTP Delivery -------------------- - -Here, imip-agent's programs run in a way that permits local SMTP delivery -(which merely needs the ability to connect to a local network service) whilst -allowing the Web server to read data written by those programs. - -A system user needs to be created and to belong to certain groups in order to -deliver messages to mail stores and to publish resources on the Web: - - useradd -d /var/lib/imip-agent -m -U -G www-data -r imip-agent - -Again, the tools/init.sh script will initialise directories for stored and -published data. The tools/config.sh script should be edited and the group -redefined as follows: - - IMIP_AGENT_GROUP=www-data - -If already installed, the /etc/imip-agent/config.sh script should be edited -instead. +operating system distributions, and the accompanying instructions should be +largely superfluous for most users. -With local SMTP delivery, the mail system will need to be configured to route -messages for local recipients. See the description of mail configuration for -more information. - -Initialising the Software -========================= - -Once a suitable system user has been chosen, stored and published data is then -initialised using the tools/init.sh script. The script employs the setgid flag -on the directories initialised for stored and published data so that new files -and directories have the appropriate group associated with them. - -It should be possible to omit all arguments to the init.sh script, but it is -also worth reading the help message: - - tools/init.sh --help - -Fixing ownership can be done using the tools/fix.sh script, in case some form -of modification has altered the ownership or membership of the created files -and directories. - -Configuring Other Software -========================== - -The conf directory contains subdirectories for different systems: - - apache Apache 2 site configuration for publishing resources - cron Cron command scheduling for free/busy updates - exim Exim 4 routing and transport configuration - ldap Some LDAP-related resources - postfix Postfix routing and transport configuration - -Either Exim or Postfix can be chosen as a mail system supporting the agent. - -Configuring Mail Systems for the Agent -====================================== - -The essential aspect of mail system configuration involves mail transports and -the integration of agent programs into the mail processing pipeline. Thus, the -following files are of particular interest: - -For Exim (in conf/exim)... - - 30_exim4-config_people Integration of agent programs - 30_exim4-config_people_outgoing ... - 30_exim4-config_resources ... - -For Postfix (in conf/postfix)... - - master.cf.items Integration of agent programs (for - inclusion in master.cf) - transport Configuration of agent transports - virtual Configuration of outgoing mail routing - -Such files need adjusting for the deployment environment so that, for example, -the example.com domain would be replaced with a suitable value. - -If local SMTP delivery is being used, the 30_exim4-config_people file (in -conf/exim) or the master.cf.items file (in conf/postfix) will need adjusting. - -If LMTP is being used, instances of LMTP_SOCKET in the example configuration -files will need to be replaced with a suitable filesystem path. Where the lmtp -system group is employed, it may be replaced with a different group. See -below for a discussion of LMTP and mail delivery. +See: docs/wiki/GettingStarted Configuring Mail Systems for Mail Recipients ============================================ @@ -152,114 +28,9 @@ disregarded in favour of other ways of defining mail recipients, subject to the needs of any given environment. -Using LDAP with Exim --------------------- - -For Exim (in conf/exim/ldap)... - - 010_exim4-config_ldap_people_outgoing Defines recipients and outgoing - mail routing - 020_exim4-config_ldap_people ... - 020_exim4-config_ldap_resources ... - 020_exim4-config_ldap_people_outgoing_recipients - -Using LDAP with Postfix ------------------------ - -For Postfix (in conf/postfix/ldap)... - - main.cf.example Defines recipients and outgoing - mail routing (for inclusion in - main.cf) - - virtual_alias_maps_people.cf Defines recipients and outgoing - virtual_alias_maps_people_outgoing.cf mail routing - virtual_alias_maps_resources.cf ... - -Using Lists of Identities -------------------------- - -Since the use of LDAP can be somewhat challenging and also excessive in some -situations, examples of maintaining recipient information using a simpler -approach are provided. - -In this simpler environment, recipient details must be manually edited in the -virtual identity files, but this permits a very transparent way of -administering the system. - -Using Lists with Exim ---------------------- - -For Exim (in conf/exim/simple)... - - 010_exim4-config_people_outgoing Defines recipients and outgoing - mail routing - 020_exim4-config_people ... - 020_exim4-config_resources ... - 020_exim4-config_people_outgoing_recipients - - virtual_people Defines recipient identities - virtual_people_outgoing_recipients belonging to known domains - virtual_resources ... - - virtual_domains Defines recipient domains - -To add support for delivery to local mailboxes, the following additional file -is provided as an example: - - virtual_people_local Defines recipients and local users - -And to route bounced messages back to the generic calendar address, an -addition to the /etc/aliases file is provided: - - aliases.example Routes calendar to root - -Using Lists with Postfix ------------------------- - -For Postfix (in conf/postfix/simple)... - - main.cf.example Defines recipients and outgoing - mail routing (for inclusion in - main.cf) - - virtual_alias_maps Defines recipients and outgoing - virtual_alias_maps_people_outgoing mail routing - -To add support for delivery to local mailboxes, the following alternative to -virtual_alias_maps is provided as an example: - - virtual_alias_maps_local Defines recipients and local users - -LDAP Representations for Mail Recipients ----------------------------------------- - -Relevant LDAP resources for structuring recipient information include the -following: - - RFC 4524 Defines the mail attribute - http://tools.ietf.org/html/rfc4524 - - RFC 2798 Defines the inetOrgPerson object - http://tools.ietf.org/html/rfc2798 class - - RFC 2739 Defines the calEntry object class - https://tools.ietf.org/html/rfc2739 supporting calFBURL - -An additional draft RFC describes the mailRecipient object class: - - https://tools.ietf.org/html/draft-lachman-ldap-mail-routing-03 - -Resource schemas for LDAP are not effectively standardised for the purposes of -this software. A useful object class, inetResource, was defined for the -iPlanet Calendar Server: - - http://docs.oracle.com/cd/E19566-01/819-4437/6n6jckqrf/index.html#anocg - http://docs.oracle.com/cd/E19566-01/819-4437/6n6jckqr8/index.html - -Although Kolab maintains notions of resources, they are tied up with the -notion of a shared folder and the kolabSharedFolder object class, although the -mailRecipient object class is employed by resources in Kolab. +See: docs/wiki/MailIntegration +See: docs/wiki/MailIntegration--LDAP +See: docs/wiki/MailIntegration--Simple Configuring Mail Systems for Mail Delivery ========================================== @@ -268,53 +39,9 @@ performed either using local SMTP or by using LMTP to a suitable mailbox provider. -If employing local SMTP, the burden of routing messages to suitable storage -becomes a configuration problem within the mail system itself, but given that -routing to local system users is typically supported "out of the box", this -can provide a usable solution with minimal effort. - -Where the mail system must instead route messages to mailbox providers -employing LMTP, some more effort is required. For Exim, some sample -configuration files are provided in conf/exim/lmtp to route messages for local -users to LMTP endpoints. - -By using LMTP from the agent software, the issue of configuring the mail -system to integrate with storage solutions is avoided, but then those -solutions must expose their LMTP interface appropriately. - -Configuring Mail Storage Providers for LMTP -------------------------------------------- - -Although this topic is largely beyond the scope of this document, systems such -as Cyrus and Dovecot can be configured to provide a Unix domain socket -offering support for LMTP connections. - -For Cyrus, the following bug report is pertinent: - -https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=494746 - -A permanent change in permissions on the Cyrus LMTP socket is therefore -required to make delivery available to the lmtp group: - - dpkg-statoverride --force --update --add \ - cyrus lmtp 750 /var/run/cyrus/socket - -Configuring Cron for Free/Busy Updates -====================================== - -The periods occupied by recurring events are not expanded beyond a certain -window of time by imip-agent. As a consequence, free/busy collections need to -be progressively expanded over time to include periods occupied by such events -that were not previously recorded in those collections. - -The conf/cron/cron.daily/imip-agent file contains commands that update -free/busy collections for all known users, and this should be copied to the -appropriate destination. For example: - -cp conf/cron/cron.daily/imip-agent /etc/cron.daily/ - -Where frequency-specific directories are not supported by cron on a system, a -crontab entry of the appropriate format is required instead. +See: docs/wiki/MailIntegration +See: docs/wiki/MailIntegration--LMTP +See: docs/wiki/MailIntegration--LocalSMTP Configuring Web Servers for Free/Busy Publishing ================================================ @@ -353,38 +80,3 @@ as follows: a2enmod authnz_ldap - -Prerequisites -============= - -Depending on the mail transport agent (MTA) chosen, the following packages are -required for this software to work on Debian systems: - - Exim: exim4-daemon-heavy - Postfix: postfix postfix-ldap - -The software itself requires the following packages: - - Python: python - pytz: python-tz - -To update free/busy details periodically, the following software is -recommended: - - Cron: cron - -The management Web interface requires the following packages: - - Apache: apache2 - Babel: python-babel - -Although not necessarily within the scope of the deployment of this software, -the following mail storage solutions would be used to receive and hold -messages: - - Cyrus: cyrus-imapd - Dovecot: dovecot-imapd dovecot-ldap dovecot-lmtpd - -Some test programs need additional programs provided by other packages: - - envsubst: gettext-base diff -r 06e9eb58ca55 -r 18aa266fe15d docs/wiki/Configuration --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/wiki/Configuration Wed Oct 28 00:38:45 2015 +0100 @@ -0,0 +1,30 @@ += Configuration = + +There are two principal configuration files in imip-agent: + + * `config.py` provides the configuration to the software itself + * `config.sh` provides system-level and tool configuration + +These files are by default installed into the `/etc/imip-agent` directory +and they can be changed in that location once the system is installed. + +== System User and Filesystem Configuration == + +Given a choice of [[../SystemUsers|system users and groups]], the +resulting configuration must be indicated in the `config.sh` file. Since +the `tools/install.sh` script depends on this configuration, changes must +be made to the file in the `tools/config.sh` location before installation +can occur. + +== Agent System Configuration == + +Any changes to filesystem locations may need to be incorporated into the +`config.py` file, which is found in the `imiptools/config.py` location of +the distribution. There is, however, no urgency in changing this file +before installation, and it can be edited in its installed location to +achieve the same effects. + +The agent system configuration dictates how the software behaves, and the +`config.py` file provides system-level settings (filesystem locations +and file permissions), service-level settings (e-mail address and Web site +choices), and default policies for users of the software. diff -r 06e9eb58ca55 -r 18aa266fe15d docs/wiki/CronIntegration --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/wiki/CronIntegration Wed Oct 28 00:38:45 2015 +0100 @@ -0,0 +1,20 @@ += Cron Task Scheduler Integration = + +The periods occupied by recurring events are not expanded beyond a certain +window of time by imip-agent. As a consequence, free/busy collections need to +be progressively expanded over time to include periods occupied by such events +that were not previously recorded in those collections. + +The `conf/cron/cron.daily/imip-agent` file contains commands that update +free/busy collections for all known users, and this should be copied to the +appropriate destination. For example: + +{{{ +cp conf/cron/cron.daily/imip-agent /etc/cron.daily/ +}}} + +Where frequency-specific directories are not supported by cron on a system, a +`crontab` entry of the appropriate format is required instead. + +See the [[../EventRecurrences|guide to event recurrences]] for more information +on how recurring events are supported. diff -r 06e9eb58ca55 -r 18aa266fe15d docs/wiki/EventRecurrences --- a/docs/wiki/EventRecurrences Wed Oct 28 00:37:57 2015 +0100 +++ b/docs/wiki/EventRecurrences Wed Oct 28 00:38:45 2015 +0100 @@ -94,6 +94,7 @@ regularly scheduled task be used to consult the events known (or thought) to provide additional free/busy periods and to record such additional periods for each user. This can be done using a system's `cron` daemon and a suitable -script in `/etc/cron.daily` or equivalent. Such a script is provided in the -imip-agent distribution along with a program that can expand availability -information for all known recipients of calendar information. +script in `/etc/cron.daily` or equivalent. Such a script is +[[../CronIntegration|provided]] in the imip-agent distribution along with a +program that can expand availability information for all known recipients of +calendar information. diff -r 06e9eb58ca55 -r 18aa266fe15d docs/wiki/FrontPage --- a/docs/wiki/FrontPage Wed Oct 28 00:37:57 2015 +0100 +++ b/docs/wiki/FrontPage Wed Oct 28 00:38:45 2015 +0100 @@ -87,15 +87,21 @@ According to your requirements, any or all of the above solutions can be implemented, providing as much of a groupware solution as you need. +== Deployment Notes == + + * [[/GettingStarted|Getting Started]] + == Design and Implementation Notes == Details of the mechanisms employed by imip-agent are described in the following documents: * [[/CounterProposals|Counter-Proposals and Offers]] + * [[/CronIntegration|Cron Task Scheduler Integration]] * [[/MailIntegration|E-Mail Integration]] * [[/EventRecurrences|Event Recurrences]] * [[/IncomingMessages|Incoming Messages]] * [[/OutgoingMessages|Outgoing Messages]] + * [[/Testing|Testing]] * [[/UseCases|Use Cases]] * [[/WebServerIntegration|Web Server Integration]] diff -r 06e9eb58ca55 -r 18aa266fe15d docs/wiki/GettingStarted --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/wiki/GettingStarted Wed Oct 28 00:38:45 2015 +0100 @@ -0,0 +1,74 @@ += Getting Started = + +To get imip-agent running on your own system you will need the following: + + * The ability to install software and to configure the system + * A working mail configuration + +It is possible to [[../Testing|test the agent programs]] without these +abilities, but any difficulties in getting the software to work will be +compounded by any problem or deficiency in either of these areas. + +== Configuring System Users == + +The [[../SystemUsers|system users guide]] indicates the requirements for +system user and group configuration. + +If you are comfortable configuring your mail system, you may decide to +choose the [[../MailIntegration/LocalSMTP|local SMTP delivery]] approach. + +If you already use mail storage solutions that employ LMTP, you may decide +to choose the [[../MailIntegration/LMTP|LMTP delivery]] approach. + +== Installing the Software == + +Ideally, an operating system distribution package should be used to +install the software. As a result, the software should already be suitably +integrated and configured and guidance will be available to get everything +working. + + 1. In the absence of a suitable system package, the installation locations + and system user details must first be configured, as described above. + + 1. Then, the `tools/install.sh` script should install the software in + appropriate locations. You may need to be `root` or use `sudo` to + successfully use this script. + +See the [[../Prerequisites|prerequisites]] for other software that will be +required for the software to function. + +== Initialising the Software == + +Once a suitable system user has been chosen, stored and published data is then +initialised using the `tools/init.sh` script. The script employs the setgid +flag on the directories initialised for stored and published data so that new +files and directories have the appropriate group associated with them. + +It should be possible to omit all arguments to the `init.sh` script, but it is +also worth reading the help message: + +{{{ +tools/init.sh --help +}}} + +Fixing ownership can be done using the `tools/fix.sh` script, in case some form +of modification has altered the ownership or membership of the created files +and directories. + +== Configuring Other Software == + +The `conf` directory contains subdirectories for different systems: + +|| '''Directory''' || '''Description''' || +|| `apache` || Apache 2 site configuration for publishing resources || +|| `cron` || Cron command scheduling for free/busy updates || +|| `exim` || Exim 4 routing and transport configuration || +|| `ldap` || Some LDAP-related resources || +|| `postfix` || Postfix routing and transport configuration || + +The configuration activities associated with these directories are covered in +the following documents: + + * [[../CronIntegration|Cron Task Scheduler Integration]] + * [[../MailIntegration|E-Mail Integration]] + * [[../WebServerIntegration|Web Server Integration]] diff -r 06e9eb58ca55 -r 18aa266fe15d docs/wiki/MailIntegration --- a/docs/wiki/MailIntegration Wed Oct 28 00:37:57 2015 +0100 +++ b/docs/wiki/MailIntegration Wed Oct 28 00:38:45 2015 +0100 @@ -51,11 +51,25 @@ [[/Simple|Simple (list-based identification)]] || Exim, Postfix }}} +== Invoking the Agent Programs == + +Regardless of identification or delivery mechanisms, the imip-agent software +must be integrated into the mail processing pipeline so that messages can be +interpreted and processed. This is done by configuring the MTA's +[[/Transports|transport mechanisms]]. + == Delivery == To deliver messages to their ultimate recipients after having processed them, imip-agent currently employs either local SMTP connections or [[https://tools.ietf.org/html/rfc2033|LMTP]]. There is nothing in principle preventing imip-agent from also supporting other common delivery mechanisms, -however. Currently, Cyrus-IMAP and Dovecot have both been tested with -imip-agent, along with delivery to local system users. +however. + +{{{#!table +'''Delivery Mechanisms''' || '''Tested with...''' +== +[[/LocalSMTP|Local SMTP]] || Exim, Postfix +== +[[/LMTP|LMTP]] || Exim, Postfix +}}} diff -r 06e9eb58ca55 -r 18aa266fe15d docs/wiki/MailIntegration--LMTP --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/wiki/MailIntegration--LMTP Wed Oct 28 00:38:45 2015 +0100 @@ -0,0 +1,24 @@ += LMTP Delivery = + +When imip-agent is configured to use LMTP, it connects directly to mail +storage solutions. By using LMTP from the agent software, the issue of +configuring the mail system to integrate with such solutions is avoided, but +then those solutions must expose their LMTP interface appropriately. + +Although this topic is largely beyond the scope of this document, systems such +as Cyrus and Dovecot can be configured to provide a Unix domain socket +offering support for LMTP connections. + +For Cyrus, the following bug report is pertinent: + + * https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=494746 + +A permanent change in permissions on the Cyrus LMTP socket is therefore +required to make delivery available to the `lmtp` group: + +{{{ +dpkg-statoverride --force --update --add cyrus lmtp 750 /var/run/cyrus/socket +}}} + +See the [[../../SystemUsers|system users]] documentation for a discussion of +users and groups. diff -r 06e9eb58ca55 -r 18aa266fe15d docs/wiki/MailIntegration--LocalSMTP --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/wiki/MailIntegration--LocalSMTP Wed Oct 28 00:38:45 2015 +0100 @@ -0,0 +1,24 @@ += Local SMTP Delivery = + +By employing local SMTP, the burden of routing messages to suitable storage +becomes a configuration problem within the mail system itself. Here, imip-agent +connects to the mail transport agent (MTA) and sends a message to an +explicitly-indicated local user such as, for example: + +{{{ +local+vincent.vole@example.com +}}} + +The message is then routed to a mail delivery mechanism, perhaps by converting +the local address to a local user identity: + +{{{ +vole +}}} + +The local delivery mechanism would then deposit the message in the user's mailbox. + +Where the mail system must instead route messages to mailbox providers +employing LMTP, some more effort is required. For Exim, some sample +configuration files are provided in `conf/exim/lmtp` to route messages for local +users to LMTP endpoints. diff -r 06e9eb58ca55 -r 18aa266fe15d docs/wiki/MailIntegration--Simple --- a/docs/wiki/MailIntegration--Simple Wed Oct 28 00:37:57 2015 +0100 +++ b/docs/wiki/MailIntegration--Simple Wed Oct 28 00:38:45 2015 +0100 @@ -38,6 +38,10 @@ || Defines recipients and local users for delivery to local mailboxes }}} +These files can be incorporated into the Exim configuration. On Debian +systems, the numbered files can be copied into `/etc/exim4/conf.d/router`, +whereas the virtual files can be copied into `/etc/exim4`. + == Using Lists with Postfix == Example configuration file for Postfix are distributed in `conf/postfix/simple`: @@ -56,3 +60,7 @@ `virtual_alias_maps_local` || Defines recipients and local users for delivery to local mailboxes }}} + +These files can be incorporated into the Postfix configuration. On Debian +systems, `main.cf.example` can be merged into `/etc/postfix/main.cf`, +whereas the remaining files would be installed into `/etc/postfix`. diff -r 06e9eb58ca55 -r 18aa266fe15d docs/wiki/MailIntegration--Transports --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/wiki/MailIntegration--Transports Wed Oct 28 00:38:45 2015 +0100 @@ -0,0 +1,58 @@ += Mail Transports and Invoking Agent Programs = + +The essential aspect of mail system configuration involves mail transports and +the integration of agent programs into the mail processing pipeline. A number of +example files are provided here. + +Such files need adjusting for the deployment environment so that, for example, +the `example.com` domain would be replaced with a suitable value. + +If LMTP is being used, instances of `LMTP_SOCKET` in the example configuration +files will need to be replaced with a suitable filesystem path. Where the `lmtp` +system group is employed, it may be replaced with a different group. See the +[[../LMTP|LMTP guide]] for a discussion of LMTP and mail delivery. + +== Transports in Exim == + +Example configuration files for Exim are distributed in `conf/exim`: + +{{{#!table +'''File''' || '''Purpose''' +== +`30_exim4-config_people` +|| Integration of agent programs +== +`30_exim4-config_people_outgoing` +== +`30_exim4-config_resources` +}}} + +These files can be incorporated into the Exim configuration. On Debian +systems, they can be copied into `/etc/exim4/conf.d/transport`. + +If local SMTP delivery is being used, the `30_exim4-config_people` file (in +`conf/exim`) will need adjusting. + +== Transports in Postfix == + +Example configuration files for Postfix are distributed in `conf/postfix`: + +{{{#!table +'''File''' || '''Purpose''' +== +`master.cf.items` +|| Integration of agent programs (for inclusion in `master.cf`) +== +`transport` +|| Configuration of agent transports +== +`virtual` +|| Configuration of outgoing mail routing +}}} + +These files can be incorporated into the Postfix configuration. On Debian +systems, `master.cf.items` can be merged into `/etc/postfix/master.cf`, +whereas the remaining files would be installed into `/etc/postfix`. + +If local SMTP delivery is being used, the `master.cf.items` file (in +`conf/postfix`) will need adjusting. diff -r 06e9eb58ca55 -r 18aa266fe15d docs/wiki/Prerequisites --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/wiki/Prerequisites Wed Oct 28 00:38:45 2015 +0100 @@ -0,0 +1,33 @@ += Prerequisites = + +Depending on the mail transport agent (MTA) chosen, the following packages are +required for this software to work on Debian systems: + + Exim:: exim4-daemon-heavy + Postfix:: postfix postfix-ldap + +The software itself requires the following packages: + + Python:: python + pytz:: python-tz + +To update free/busy details periodically, the following software is +recommended: + + Cron:: cron + +The management Web interface requires the following packages: + + Apache:: apache2 + Babel:: python-babel + +Although not necessarily within the scope of the deployment of this software, +the following mail storage solutions would be used to receive and hold +messages: + + Cyrus:: cyrus-imapd + Dovecot:: dovecot-imapd dovecot-ldap dovecot-lmtpd + +Some test programs need additional programs provided by other packages: + + envsubst:: gettext-base diff -r 06e9eb58ca55 -r 18aa266fe15d docs/wiki/SystemUsers --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/wiki/SystemUsers Wed Oct 28 00:38:45 2015 +0100 @@ -0,0 +1,84 @@ += System Users and Filesystem Access = + +The data handled by imip-agent needs to be accessible to other software, +notably mail handling software and Web server software. Two approaches to +[[../MailIntegration|e-mail integration]] affect the choice of system users +and groups: + +{{{#!table +'''Integration Method''' || '''System Users and Groups''' +== +[[../MailIntegration/LMTP|LMTP delivery]] +|| `imip-agent` belongs to `lmtp` and `www-data` groups<
> +.. `www-data` also belongs to the `lmtp` group +== +[[../MailIntegration/LocalSMTP|Local SMTP delivery]] +|| `imip-agent` belongs to the `www-data` group +}}} + +The corresponding strategies are described in more detail below. + +== LMTP Delivery == + +Here, imip-agent's programs run in a way that permits LMTP delivery (requiring +suitable local privileges to communicate with the mail storage solution) +whilst allowing the Web server to read data written by those programs. + +A system group needs to be created for LMTP delivery and for certain users to +share resources: + +{{{ +addgroup lmtp +}}} + +This group should be employed for LMTP delivery by systems like Cyrus and +Dovecot. See the section on configuring mail systems for delivery for more +information. + +A system user needs to be created and to belong to certain groups in order to +deliver messages to mail stores and to publish resources on the Web: + +{{{ +useradd -d /var/lib/imip-agent -m -U -G lmtp,www-data -r imip-agent +}}} + +Store details and published resources need to be accessible by the `imip-agent` +and `www-data` users. Thus, `www-data` also needs to belong to the `lmtp` group: + +{{{ +adduser www-data lmtp +}}} + +== Local SMTP Delivery == + +Here, imip-agent's programs run in a way that permits local SMTP delivery +(which merely needs the ability to connect to a local network service) whilst +allowing the Web server to read data written by those programs. + +A system user needs to be created and to belong to certain groups in order to +deliver messages to mail stores and to publish resources on the Web: + +{{{ +useradd -d /var/lib/imip-agent -m -U -G www-data -r imip-agent +}}} + +Again, the `tools/init.sh` script will initialise directories for stored and +published data. The `tools/config.sh` script should be edited and the group +redefined as follows: + +{{{ +IMIP_AGENT_GROUP=www-data +}}} + +If already installed, the `/etc/imip-agent/config.sh` script should be edited +instead. See the [[../Configuration|configuration guide]] for more information. + +With local SMTP delivery, the mail system will need to be configured to route +messages for local recipients. See the [[../MailIntegration/LocalSMTP|local SMTP]] +description of mail configuration for more information. + +== Updating the Configuration == + +Once the necessary decisions have been taken here, the system's +[[../Configuration|configuration]] will need updating so that the software and +tools will work correctly. diff -r 06e9eb58ca55 -r 18aa266fe15d docs/wiki/Testing --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/wiki/Testing Wed Oct 28 00:38:45 2015 +0100 @@ -0,0 +1,72 @@ += Testing = + +To see how the software operates, you can run one of the agent programs +provided in the distribution. For example: + +{{{ +./imip_resource.py -S xxx/store -P xxx/static -p xxx/prefs -d \ + < tests/templates/event-request.txt +}}} + +This uses one of the test files, sending it to the agent program for +resource entities, producing output resembling the following: + +{{{ +Outgoing parts for paul.boddie@example.com... +From nobody Wed Oct 28 00:24:41 2015 +MIME-Version: 1.0 +Content-Transfer-Encoding: base64 +Content-Type: text/calendar; charset="utf-8"; method="REPLY" +From: calendar@example.com +To: paul.boddie@example.com +Subject: Calendar system message + +QkVHSU46VkNBTEVOREFSDQpNRVRIT0Q6UkVQTFkNClZFUlNJT046Mi4wDQpCRUdJTjpWRlJFRUJV +U1kNCk9SR0FOSVpFUjptYWlsdG86cGF1bC5ib2RkaWVAZXhhbXBsZS5jb20NCkFUVEVOREVFO1NF +TlQtQlk9Im1haWx0bzpjYWxlbmRhckBleGFtcGxlLmNvbSI6bWFpbHRvOnJlc291cmNlLXJvb20t +Y29uZnJvb20NCiBAZXhhbXBsZS5jb20NClVJRDpmYjFAZXhhbXBsZS5jb20NCkVORDpWRlJFRUJV +U1kNCkVORDpWQ0FMRU5EQVINCg== +}}} + +The rather opaque encoding can be inspected using the `tools/showmail.py` +program, and thus the result of the script can be seen by piping the output +through that program as follows: + +{{{ +./imip_resource.py -S xxx/store/ -P xxx/static/ -p xxx/prefs/ -d \ + < tests/templates/event-request.txt \ + | tools/showmail.py +}}} + +The result should resemble the following: + +{{{ +Outgoing parts for paul.boddie@example.com... +MIME-Version: 1.0 +Content-Type: text/calendar; charset="utf-8"; method="REPLY" +From: calendar@example.com +To: paul.boddie@example.com +Subject: Calendar system message + +BEGIN:VCALENDAR +METHOD:REPLY +VERSION:2.0 +BEGIN:VEVENT +DTSTAMP:20151027T232738Z +UID:event1@example.com +ATTENDEE;PARTSTAT=ACCEPTED;SENT-BY="mailto:calendar@example.com":mailto:reso + urce-room-confroom@example.com +SUMMARY:Meeting at 4pm +ORGANIZER:mailto:paul.boddie@example.com +DTSTART;TZID=Europe/Oslo:20141126T160000 +DTEND;TZID=Europe/Oslo:20141126T170000 +END:VEVENT +END:VCALENDAR +}}} + +What has happened here is the presentation of a request to the resource +program in the form of an e-mail message containing an iCalendar event +employing a scheduling method. The program interprets the request, +consults its own records, makes a decision about scheduling the event, +and indicates the kind of response it would like to send back to the +requester.