1.1 --- a/docs/wiki/CalendarManager Mon Nov 02 00:03:42 2015 +0100
1.2 +++ b/docs/wiki/CalendarManager Mon Nov 02 00:06:26 2015 +0100
1.3 @@ -5,3 +5,15 @@
1.4 that allows such users to inspect incoming calendar data, consult a schedule
1.5 that has been prepared through the work of the [[../AgentPrograms|agent programs]],
1.6 and to create events to be shared with others.
1.7 +
1.8 +The management interface is deployed according to the
1.9 +[[../WebServerIntegration|Web server integration guide]], and if enabled will be
1.10 +advertised in messages sent by imip-agent to users receiving calendar-related
1.11 +messages, with links being provided like this (subject to the configuration):
1.12 +
1.13 +{{{
1.14 +https://webserver.example.com/imip-manager/eventid
1.15 +}}}
1.16 +
1.17 +Upon following such a link, users should be asked to log in. They should then be
1.18 +presented with the details of an event received via e-mail.
2.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
2.2 +++ b/docs/wiki/FilesystemUsage Mon Nov 02 00:06:26 2015 +0100
2.3 @@ -0,0 +1,96 @@
2.4 += Filesystem Usage =
2.5 +
2.6 +The behaviour and operation of imip-agent is controlled by resources stored
2.7 +in the filesystem on the host on which the software is running. These resources
2.8 +are organised as follows:
2.9 +
2.10 +{{{#!table
2.11 +'''Resource''' || '''Default Location''' || '''Purpose'''
2.12 +==
2.13 +Store || `/var/lib/imip-agent/store`
2.14 +|| Per-user directories containing calendar objects and scheduling information
2.15 +==
2.16 +Preferences || `/var/lib/imip-agent/preferences`
2.17 +|| Per-user directories containing [[../Preferences|preferences]] controlling
2.18 +.. each user's experience of the software
2.19 +==
2.20 +Free/busy || `/var/www/imip-agent/static`
2.21 +|| Per-user directories containing [[../FreeBusyPublishing|free/busy resources]]
2.22 +.. for publication over the Web
2.23 +}}}
2.24 +
2.25 +Note that the free/busy resources are located in `/var/www` as opposed to
2.26 +`/var/lib`.
2.27 +
2.28 +== Store Structure ==
2.29 +
2.30 +The store directory for each user is considered in isolation from all other
2.31 +users' directories: imip-agent does not go looking for information belonging to
2.32 +other users when processing information on behalf of a particular user.
2.33 +
2.34 +The following subdirectories are defined within a user's store directory:
2.35 +
2.36 +{{{{#!table
2.37 +'''Directory''' || '''Purpose'''
2.38 +==
2.39 +`cancellations`
2.40 +|| Retains cancelled event details in `objects` and `recurrences` structures
2.41 +.. corresponding to those at the top level of the store from which the
2.42 +.. cancelled events originate:
2.43 +{{{
2.44 +cancellations/objects/UID
2.45 +cancellations/recurrences/UID/RECURRENCE-ID
2.46 +}}}
2.47 +==
2.48 +`counters`
2.49 +|| Retains counter-proposals for events in `objects` and `recurrences`
2.50 +.. structures corresponding to those at the top level of the store for which
2.51 +.. the counter-proposals are received, with a counter-proposal for each
2.52 +.. respondent being held for each object or recurrence involved:
2.53 +{{{
2.54 +counters/objects/UID/ATTENDEE
2.55 +counters/recurrences/UID/RECURRENCE-ID/ATTENDEE
2.56 +}}}
2.57 +==
2.58 +`freebusy`
2.59 +|| A file containing period descriptions in chronological order, one per line,
2.60 +.. indicating start and end datetimes (in UTC), unique identifier (`UID`),
2.61 +.. transparency, summary and organiser
2.62 +==
2.63 +`freebusy-offers`
2.64 +|| A file containing period descriptions in chronological order for
2.65 +.. scheduling offers made by counter-proposals sent by the user
2.66 +==
2.67 +`freebusy-other`
2.68 +|| A collection of files, one per user, each containing period descriptions
2.69 +.. received or deduced for that user in chronological order, structured similarly
2.70 +.. to the store user's own `freebusy` file
2.71 +==
2.72 +`freebusy-providers`
2.73 +|| A file containing details of [[../EventRecurrences|recurring events]] for which
2.74 +.. new free/busy records must be [[../CronIntegration|periodically generated]]
2.75 +.. because these events recur indefinitely
2.76 +==
2.77 +`objects`
2.78 +|| A collection of files, one per event, each bearing as its name the unique
2.79 +.. identifier (`UID`) of the event, with each file containing the event data:
2.80 +{{{
2.81 +objects/UID
2.82 +}}}
2.83 +==
2.84 +`recurrences`
2.85 +|| A collection of directories, one per "parent" event, each bearing as its name
2.86 +.. the unique identifier (`UID`) of the event, with each directory containing a
2.87 +.. collection of files, one per event recurrence, each bearing as its name the
2.88 +.. normalised recurrence identifier (`RECURRENCE-ID`) of the recurrence, with each
2.89 +.. file containing the data of the event recurrence:
2.90 +{{{
2.91 +recurrences/UID/RECURRENCE-ID
2.92 +}}}
2.93 +==
2.94 +`requests`
2.95 +|| A list of records, one per line, each consisting of a unique identifier (`UID`),
2.96 +.. normalised recurrence identifier (`RECURRENCE-ID`) if appropriate, and
2.97 +.. (optionally) a scheduling method, indicating the availability of an incoming
2.98 +.. scheduling request for handling by a user
2.99 +}}}}
3.1 --- a/docs/wiki/FrontPage Mon Nov 02 00:03:42 2015 +0100
3.2 +++ b/docs/wiki/FrontPage Mon Nov 02 00:06:26 2015 +0100
3.3 @@ -129,6 +129,7 @@
3.4 * [[/Configuration|Configuration]] and [[/Preferences|Preferences]]
3.5 * [[/CalendarManager|Calendar Management Interface]]
3.6 * [[/FreeBusyPublishing|Free/Busy Publishing]]
3.7 + * [[/Usage|Usage]]
3.8
3.9 == Design and Implementation Notes ==
3.10
3.11 @@ -138,6 +139,7 @@
3.12 * [[/CounterProposals|Counter-Proposals and Offers]]
3.13 * [[/CronIntegration|Cron Task Scheduler Integration]]
3.14 * [[/EventRecurrences|Event Recurrences]]
3.15 + * [[/FilesystemUsage|Filesystem Usage]]
3.16 * [[/IncomingMessages|Incoming Messages]]
3.17 * [[/OutgoingMessages|Outgoing Messages]]
3.18 * [[/MailIntegration|Mail Integration]]
4.1 --- a/docs/wiki/GettingStarted Mon Nov 02 00:03:42 2015 +0100
4.2 +++ b/docs/wiki/GettingStarted Mon Nov 02 00:06:26 2015 +0100
4.3 @@ -76,7 +76,8 @@
4.4 ==
4.5 `exim`
4.6 || Exim 4 routing and transport configuration
4.7 -|| [[../MailIntegration|E-Mail Integration]]
4.8 +|| [[../MailIntegration|E-Mail Integration]] and
4.9 +.. [[../MailboxIntegration|Mailbox Integration]]
4.10 ==
4.11 `ldap`
4.12 || Some LDAP-related resources
4.13 @@ -84,10 +85,16 @@
4.14 ==
4.15 `postfix`
4.16 || Postfix routing and transport configuration
4.17 -|| [[../MailIntegration|E-Mail Integration]]
4.18 +|| [[../MailIntegration|E-Mail Integration]] and
4.19 +.. [[../MailboxIntegration|Mailbox Integration]]
4.20 }}}
4.21
4.22 == Configuring the Software ==
4.23
4.24 The behaviour of the imip-agent software itself can be configured using
4.25 mechanisms described in the [[../Configuration|configuration guide]].
4.26 +
4.27 +== Using the Software ==
4.28 +
4.29 +With everything configured, it should be possible to get started using
4.30 +the software. See the [[../Usage|usage guide]] for details.
5.1 --- a/docs/wiki/MailIntegration--MTA Mon Nov 02 00:03:42 2015 +0100
5.2 +++ b/docs/wiki/MailIntegration--MTA Mon Nov 02 00:06:26 2015 +0100
5.3 @@ -4,16 +4,12 @@
5.4 mail transfer agent (MTA) software, some hints and tips are offered to help
5.5 avoid frustration.
5.6
5.7 +<<TableOfContents(2,3)>>
5.8 +
5.9 == General ==
5.10
5.11 Some general measures are presented below.
5.12
5.13 -=== Mailname ===
5.14 -
5.15 -The contents of `/etc/mailname` should probably be the fully-qualified hostname,
5.16 -at least for Exim and Postfix. See
5.17 -[[https://wiki.debian.org/EtcMailName|the Debian Wiki page]] for more details.
5.18 -
5.19 === Hostname ===
5.20
5.21 The `hostname` command should provide a suitable hostname on the system, or MTAs
5.22 @@ -25,11 +21,30 @@
5.23
5.24 It should report a fully-qualified hostname.
5.25
5.26 +=== Mailname ===
5.27 +
5.28 +The contents of `/etc/mailname` should probably be the fully-qualified hostname,
5.29 +at least for Exim and Postfix. See
5.30 +[[https://wiki.debian.org/EtcMailName|the Debian Wiki page]] for more details.
5.31 +
5.32 === Interfaces ===
5.33
5.34 -Some software attempts to listen on interfaces that may not be supported. For example,
5.35 -Exim may be configured to listen on both IPv4 and IPv6 interfaces, even in environments
5.36 -(such as User Mode Linux) where IPv6 interfaces may not be available.
5.37 +Some software attempts to listen on interfaces that may not be supported. For
5.38 +example, Exim may be configured to listen on both IPv4 and IPv6 interfaces, even
5.39 +in environments (such as User Mode Linux) where IPv6 interfaces may not be
5.40 +available.
5.41 +
5.42 +=== Authentication ===
5.43 +
5.44 +It is highly undesirable to allow anyone to connect to a mail server to send
5.45 +mail. However, it is highly convenient to allow imip-agent to connect to the
5.46 +mail server on the same host without having to provide credentials. Consequently,
5.47 +the configuration of an MTA must permit the latter without allowing the former.
5.48 +
5.49 +Fortunately, many MTAs are configured to allow local connections because programs
5.50 +typically rely on such traditional behaviour, but this may be worth checking if
5.51 +mail server logs indicate authentication failures when imip-agent is attempting
5.52 +to send mail.
5.53
5.54 == Exim ==
5.55
6.1 --- a/docs/wiki/OutgoingMessages Mon Nov 02 00:03:42 2015 +0100
6.2 +++ b/docs/wiki/OutgoingMessages Mon Nov 02 00:06:26 2015 +0100
6.3 @@ -4,14 +4,6 @@
6.4 message rule in the MTA to provide a handler to inspect any calendar-related
6.5 content and to update its records.
6.6
6.7 -The management interface does not use this outgoing message rule because it
6.8 -sends messages from the general calendar address (for example,
6.9 -`calendar@example.com`), and there is no trivial way of deducing the identity
6.10 -of the real sender. Instead, the manager explicitly sends suitably-modified
6.11 -messages to the address of the user operating the interface to achieve the
6.12 -same effect as the outgoing message rule, as well as to notify any mail
6.13 -clients that would normally be managing calendar events on behalf of the user.
6.14 -
6.15 {{{#!graphviz
6.16 //format=svg
6.17 //transform=notugly
6.18 @@ -25,12 +17,48 @@
6.19 subgraph {
6.20 rank=same;
6.21 outgoingrouter [label="Outgoing router"];
6.22 + }
6.23 +
6.24 + subgraph {
6.25 + rank=same;
6.26 + outgoinghandler [label="Outgoing handler",style=filled,fillcolor=gold];
6.27 + scheduling [label="Scheduling",shape=ellipse,style=filled,fillcolor=gold];
6.28 + freebusy [label="Free/busy",shape=folder,style=filled,fillcolor=gold];
6.29 + manager [label="imip-manager",style=filled,fillcolor=gold];
6.30 + }
6.31 +
6.32 + client [label="Mail clients"];
6.33 +
6.34 + client -> mail;
6.35 + mail -> outgoingrouter -> outgoinghandler -> scheduling -> freebusy -> manager;
6.36 +}
6.37 +}}}
6.38 +
6.39 +The management interface does not use this outgoing message rule because it
6.40 +sends messages from the general calendar address (for example,
6.41 +`calendar@example.com`), and there is no trivial way of deducing the identity
6.42 +of the real sender. Instead, the manager explicitly sends suitably-modified
6.43 +messages to the address of the user operating the interface to achieve the
6.44 +same effect as the outgoing message rule, as well as to notify any mail
6.45 +clients that would normally be managing calendar events on behalf of the user.
6.46 +
6.47 +{{{#!graphviz
6.48 +//format=svg
6.49 +//transform=notugly
6.50 +digraph manager_outgoing {
6.51 + node [shape=box,fontsize="16.0",fontname="sans-serif",tooltip="Outgoing messages from the manager"];
6.52 + edge [tooltip="Outgoing messages from the manager"];
6.53 + rankdir=LR;
6.54 +
6.55 + mail [label="Outgoing mail",shape=folder,style=filled,fillcolor=cyan];
6.56 +
6.57 + subgraph {
6.58 + rank=same;
6.59 personrouter [label="Person router"];
6.60 }
6.61
6.62 subgraph {
6.63 rank=same;
6.64 - outgoinghandler [label="Outgoing handler",style=filled,fillcolor=gold];
6.65 personhandler [label="Person handler",style=filled,fillcolor=gold];
6.66 scheduling [label="Scheduling",shape=ellipse,style=filled,fillcolor=gold];
6.67 freebusy [label="Free/busy",shape=folder,style=filled,fillcolor=gold];
6.68 @@ -39,25 +67,10 @@
6.69
6.70 webserver [label="Web server\n(Apache, ...)",tooltip="Web server"];
6.71
6.72 - subgraph {
6.73 - rank=same;
6.74 - client [label="Mail clients"];
6.75 - browser [label="Web browsers"];
6.76 - }
6.77 -
6.78 - client -> mail;
6.79 - mail -> outgoingrouter -> outgoinghandler;
6.80 + browser [label="Web browsers"];
6.81
6.82 - browser -> webserver [penwidth="3.0"];
6.83 - webserver -> manager [penwidth="3.0"];
6.84 - manager -> mail [penwidth="3.0"];
6.85 - mail -> personrouter [penwidth="3.0"];
6.86 - personrouter -> personhandler [penwidth="3.0"];
6.87 -
6.88 - outgoinghandler -> scheduling;
6.89 - personhandler -> scheduling [penwidth="3.0"];
6.90 - scheduling -> freebusy;
6.91 - freebusy -> manager;
6.92 + browser -> webserver -> manager -> mail -> personrouter ->
6.93 + personhandler -> scheduling -> freebusy -> manager;
6.94 }
6.95 }}}
6.96
7.1 --- a/docs/wiki/Preferences Mon Nov 02 00:03:42 2015 +0100
7.2 +++ b/docs/wiki/Preferences Mon Nov 02 00:06:26 2015 +0100
7.3 @@ -26,7 +26,8 @@
7.4
7.5 Each of the user preferences or settings are stored in a separate file within
7.6 a dedicated preferences directory for each user, with the filename bearing the
7.7 -name of the setting concerned.
7.8 +name of the setting concerned. See the [[../FilesystemUsage|filesystem guide]]
7.9 +for more information.
7.10
7.11 === CN ===
7.12
8.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
8.2 +++ b/docs/wiki/Usage Mon Nov 02 00:06:26 2015 +0100
8.3 @@ -0,0 +1,17 @@
8.4 += Using imip-agent =
8.5 +
8.6 +With imip-agent deployed, usage of the software should occur automatically.
8.7 +However, evidence of its operation will only emerge when calendar-related
8.8 +messages are exchanged between e-mail users. This will cause a few different
8.9 +things to happen:
8.10 +
8.11 + * Summary messages may be sent by the calendar system to mail recipients
8.12 +
8.13 + * Replies to calendar-related messages may be received by the senders of
8.14 + those messages
8.15 +
8.16 + * Free/busy information will become available, either in responses to
8.17 + requests sent over e-mail, or [[../FreeBusyPublishing|over the Web]]
8.18 +
8.19 +In the background, imip-agent uses and updates information as described in the
8.20 +[[../FilesystemUsage|filesystem usage guide]].
9.1 --- a/docs/wiki/WebServerIntegration Mon Nov 02 00:03:42 2015 +0100
9.2 +++ b/docs/wiki/WebServerIntegration Mon Nov 02 00:06:26 2015 +0100
9.3 @@ -48,6 +48,54 @@
9.4 `conf/apache/imip-manager.conf` file provides a configuration file for
9.5 deployment with the Apache Web server software that enables this interface.
9.6
9.7 +=== Configuring the Management Interface ===
9.8 +
9.9 +The `config.py` file described in the [[../Configuration|configuration guide]]
9.10 +provides some settings that can be adjusted to configure the management
9.11 +interface.
9.12 +
9.13 +{{{{#!table
9.14 +'''Setting''' || '''Result'''
9.15 +==
9.16 +`MANAGER_INTERFACE`
9.17 +|| If set to `True`, causes links to the interface to be included in
9.18 +.. notification messages sent by imip-agent. If set to `False`, such links
9.19 +.. will be omitted.
9.20 +==
9.21 +`MANAGER_URL`
9.22 +|| The deployment URL of the management interface. Together with the
9.23 +.. `MANAGER_PATH` described below, this forms the basis of the links
9.24 +.. described above. Some examples:
9.25 +{{{
9.26 +http://webserver.example.com/
9.27 +http://webserver.example.com/webapps/
9.28 +}}}
9.29 +It can be left as `None` and a default URL will be built using the
9.30 +hostname of the system running the software.
9.31 +==
9.32 +`MANAGER_URL_SCHEME`
9.33 +|| The URL scheme or protocol employed if a default URL is being constructed
9.34 +.. instead of `MANAGER_URL` providing a value. Some examples:
9.35 +{{{
9.36 +http://
9.37 +https://
9.38 +}}}
9.39 +Since the manager is only likely to be available via common Web protocols,
9.40 +other values may not make much sense.
9.41 +==
9.42 +`MANAGER_PATH`
9.43 +|| The "path info" added to the `MANAGER_URL` that locates the management
9.44 +.. interface in its deployment location. Some examples:
9.45 +{{{
9.46 +/
9.47 +/imip-agent
9.48 +}}}
9.49 +This setting affects the `imip-manager.conf` file, whose `Alias`, `ScriptAlias`
9.50 +and `Location` directives should be changed if this setting is changed.
9.51 +}}}}
9.52 +
9.53 +=== Deploying the Configuration ===
9.54 +
9.55 On Debian, to enable the management interface, copy the configuration file to
9.56 the Apache configuration and enable it as follows:
9.57
9.58 @@ -73,3 +121,31 @@
9.59 {{{
9.60 a2enmod authnz_ldap
9.61 }}}
9.62 +
9.63 +=== Authenticating Users ===
9.64 +
9.65 +The `imip-manager.conf` file contains example directives for accessing
9.66 +authentication services or data.
9.67 +
9.68 +Where LDAP authentication is to be used, the appropriate LDAP URL needs to be
9.69 +specified using a directive. For example:
9.70 +
9.71 +{{{
9.72 +AuthLDAPUrl "ldap://localhost/ou=People,dc=example,dc=com?mail?sub"
9.73 +}}}
9.74 +
9.75 +Here, the `mail` attribute is used to match the username provided in the
9.76 +authentication dialogue. Configuration changes may be required within the LDAP
9.77 +infrastructure to allow this mechanism to function, but this is not described
9.78 +here.
9.79 +
9.80 +Meanwhile, particularly where [[../MailIntegration/Simple|simple integration]]
9.81 +strategies have been chosen, a plain text user file can be employed to
9.82 +authenticate users. For example:
9.83 +
9.84 +{{{
9.85 +AuthUserFile /var/www/imip-agent/users
9.86 +}}}
9.87 +
9.88 +Such a file should be created using the usual tools provided by the Apache Web
9.89 +server distribution.