# HG changeset patch
# User Paul Boddie <paul@boddie.org.uk>
# Date 1446419186 -3600
# Node ID d1375269e287a0de3675503100a6983c3c502bc5
# Parent  471f15d906d4a1c6661a0bf93e52237980b4eda5
Added filesystem usage documentation plus some general usage information.
Expanded the Web integration documentation.
Added some more MTA-related notes.
Split the outgoing message diagram into two to treat each different sending
scenario separately.

diff -r 471f15d906d4 -r d1375269e287 docs/wiki/CalendarManager
--- a/docs/wiki/CalendarManager	Mon Nov 02 00:03:42 2015 +0100
+++ b/docs/wiki/CalendarManager	Mon Nov 02 00:06:26 2015 +0100
@@ -5,3 +5,15 @@
 that allows such users to inspect incoming calendar data, consult a schedule
 that has been prepared through the work of the [[../AgentPrograms|agent programs]],
 and to create events to be shared with others.
+
+The management interface is deployed according to the
+[[../WebServerIntegration|Web server integration guide]], and if enabled will be
+advertised in messages sent by imip-agent to users receiving calendar-related
+messages, with links being provided like this (subject to the configuration):
+
+{{{
+https://webserver.example.com/imip-manager/eventid
+}}}
+
+Upon following such a link, users should be asked to log in. They should then be
+presented with the details of an event received via e-mail.
diff -r 471f15d906d4 -r d1375269e287 docs/wiki/FilesystemUsage
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/wiki/FilesystemUsage	Mon Nov 02 00:06:26 2015 +0100
@@ -0,0 +1,96 @@
+= Filesystem Usage =
+
+The behaviour and operation of imip-agent is controlled by resources stored
+in the filesystem on the host on which the software is running. These resources
+are organised as follows:
+
+{{{#!table
+'''Resource''' || '''Default Location''' || '''Purpose'''
+==
+Store || `/var/lib/imip-agent/store`
+|| Per-user directories containing calendar objects and scheduling information
+==
+Preferences || `/var/lib/imip-agent/preferences`
+|| Per-user directories containing [[../Preferences|preferences]] controlling
+.. each user's experience of the software
+==
+Free/busy || `/var/www/imip-agent/static`
+|| Per-user directories containing [[../FreeBusyPublishing|free/busy resources]]
+.. for publication over the Web
+}}}
+
+Note that the free/busy resources are located in `/var/www` as opposed to
+`/var/lib`.
+
+== Store Structure ==
+
+The store directory for each user is considered in isolation from all other
+users' directories: imip-agent does not go looking for information belonging to
+other users when processing information on behalf of a particular user.
+
+The following subdirectories are defined within a user's store directory:
+
+{{{{#!table
+'''Directory''' || '''Purpose'''
+==
+`cancellations`
+|| Retains cancelled event details in `objects` and `recurrences` structures
+.. corresponding to those at the top level of the store from which the
+.. cancelled events originate:
+{{{
+cancellations/objects/UID
+cancellations/recurrences/UID/RECURRENCE-ID
+}}}
+==
+`counters`
+|| Retains counter-proposals for events in `objects` and `recurrences`
+.. structures corresponding to those at the top level of the store for which
+.. the counter-proposals are received, with a counter-proposal for each
+.. respondent being held for each object or recurrence involved:
+{{{
+counters/objects/UID/ATTENDEE
+counters/recurrences/UID/RECURRENCE-ID/ATTENDEE
+}}}
+==
+`freebusy`
+|| A file containing period descriptions in chronological order, one per line,
+.. indicating start and end datetimes (in UTC), unique identifier (`UID`),
+.. transparency, summary and organiser
+==
+`freebusy-offers`
+|| A file containing period descriptions in chronological order for
+.. scheduling offers made by counter-proposals sent by the user
+==
+`freebusy-other`
+|| A collection of files, one per user, each containing period descriptions
+.. received or deduced for that user in chronological order, structured similarly
+.. to the store user's own `freebusy` file
+==
+`freebusy-providers`
+|| A file containing details of [[../EventRecurrences|recurring events]] for which
+.. new free/busy records must be [[../CronIntegration|periodically generated]]
+.. because these events recur indefinitely
+==
+`objects`
+|| A collection of files, one per event, each bearing as its name the unique
+.. identifier (`UID`) of the event, with each file containing the event data:
+{{{
+objects/UID
+}}}
+==
+`recurrences`
+|| A collection of directories, one per "parent" event, each bearing as its name
+.. the unique identifier (`UID`) of the event, with each directory containing a
+.. collection of files, one per event recurrence, each bearing as its name the
+.. normalised recurrence identifier (`RECURRENCE-ID`) of the recurrence, with each
+.. file containing the data of the event recurrence:
+{{{
+recurrences/UID/RECURRENCE-ID
+}}}
+==
+`requests`
+|| A list of records, one per line, each consisting of a unique identifier (`UID`),
+.. normalised recurrence identifier (`RECURRENCE-ID`) if appropriate, and
+.. (optionally) a scheduling method, indicating the availability of an incoming
+.. scheduling request for handling by a user
+}}}}
diff -r 471f15d906d4 -r d1375269e287 docs/wiki/FrontPage
--- a/docs/wiki/FrontPage	Mon Nov 02 00:03:42 2015 +0100
+++ b/docs/wiki/FrontPage	Mon Nov 02 00:06:26 2015 +0100
@@ -129,6 +129,7 @@
  * [[/Configuration|Configuration]] and [[/Preferences|Preferences]]
  * [[/CalendarManager|Calendar Management Interface]]
  * [[/FreeBusyPublishing|Free/Busy Publishing]]
+ * [[/Usage|Usage]]
 
 == Design and Implementation Notes ==
 
@@ -138,6 +139,7 @@
  * [[/CounterProposals|Counter-Proposals and Offers]]
  * [[/CronIntegration|Cron Task Scheduler Integration]]
  * [[/EventRecurrences|Event Recurrences]]
+ * [[/FilesystemUsage|Filesystem Usage]]
  * [[/IncomingMessages|Incoming Messages]]
  * [[/OutgoingMessages|Outgoing Messages]]
  * [[/MailIntegration|Mail Integration]]
diff -r 471f15d906d4 -r d1375269e287 docs/wiki/GettingStarted
--- a/docs/wiki/GettingStarted	Mon Nov 02 00:03:42 2015 +0100
+++ b/docs/wiki/GettingStarted	Mon Nov 02 00:06:26 2015 +0100
@@ -76,7 +76,8 @@
 ==
 `exim`
 || Exim 4 routing and transport configuration
-|| [[../MailIntegration|E-Mail Integration]]
+|| [[../MailIntegration|E-Mail Integration]] and
+.. [[../MailboxIntegration|Mailbox Integration]]
 ==
 `ldap`
 || Some LDAP-related resources
@@ -84,10 +85,16 @@
 ==
 `postfix`
 || Postfix routing and transport configuration
-|| [[../MailIntegration|E-Mail Integration]]
+|| [[../MailIntegration|E-Mail Integration]] and
+.. [[../MailboxIntegration|Mailbox Integration]]
 }}}
 
 == Configuring the Software ==
 
 The behaviour of the imip-agent software itself can be configured using
 mechanisms described in the [[../Configuration|configuration guide]].
+
+== Using the Software ==
+
+With everything configured, it should be possible to get started using
+the software. See the [[../Usage|usage guide]] for details.
diff -r 471f15d906d4 -r d1375269e287 docs/wiki/MailIntegration--MTA
--- a/docs/wiki/MailIntegration--MTA	Mon Nov 02 00:03:42 2015 +0100
+++ b/docs/wiki/MailIntegration--MTA	Mon Nov 02 00:06:26 2015 +0100
@@ -4,16 +4,12 @@
 mail transfer agent (MTA) software, some hints and tips are offered to help
 avoid frustration.
 
+<<TableOfContents(2,3)>>
+
 == General ==
 
 Some general measures are presented below.
 
-=== Mailname ===
-
-The contents of `/etc/mailname` should probably be the fully-qualified hostname,
-at least for Exim and Postfix. See
-[[https://wiki.debian.org/EtcMailName|the Debian Wiki page]] for more details.
-
 === Hostname ===
 
 The `hostname` command should provide a suitable hostname on the system, or MTAs
@@ -25,11 +21,30 @@
 
 It should report a fully-qualified hostname.
 
+=== Mailname ===
+
+The contents of `/etc/mailname` should probably be the fully-qualified hostname,
+at least for Exim and Postfix. See
+[[https://wiki.debian.org/EtcMailName|the Debian Wiki page]] for more details.
+
 === Interfaces ===
 
-Some software attempts to listen on interfaces that may not be supported. For example,
-Exim may be configured to listen on both IPv4 and IPv6 interfaces, even in environments
-(such as User Mode Linux) where IPv6 interfaces may not be available.
+Some software attempts to listen on interfaces that may not be supported. For
+example, Exim may be configured to listen on both IPv4 and IPv6 interfaces, even
+in environments (such as User Mode Linux) where IPv6 interfaces may not be
+available.
+
+=== Authentication ===
+
+It is highly undesirable to allow anyone to connect to a mail server to send
+mail. However, it is highly convenient to allow imip-agent to connect to the
+mail server on the same host without having to provide credentials. Consequently,
+the configuration of an MTA must permit the latter without allowing the former.
+
+Fortunately, many MTAs are configured to allow local connections because programs
+typically rely on such traditional behaviour, but this may be worth checking if
+mail server logs indicate authentication failures when imip-agent is attempting
+to send mail.
 
 == Exim ==
 
diff -r 471f15d906d4 -r d1375269e287 docs/wiki/OutgoingMessages
--- a/docs/wiki/OutgoingMessages	Mon Nov 02 00:03:42 2015 +0100
+++ b/docs/wiki/OutgoingMessages	Mon Nov 02 00:06:26 2015 +0100
@@ -4,14 +4,6 @@
 message rule in the MTA to provide a handler to inspect any calendar-related
 content and to update its records.
 
-The management interface does not use this outgoing message rule because it
-sends messages from the general calendar address (for example,
-`calendar@example.com`), and there is no trivial way of deducing the identity
-of the real sender. Instead, the manager explicitly sends suitably-modified
-messages to the address of the user operating the interface to achieve the
-same effect as the outgoing message rule, as well as to notify any mail
-clients that would normally be managing calendar events on behalf of the user.
-
 {{{#!graphviz
 //format=svg
 //transform=notugly
@@ -25,12 +17,48 @@
   subgraph {
     rank=same;
     outgoingrouter [label="Outgoing router"];
+  }
+
+  subgraph {
+    rank=same;
+    outgoinghandler [label="Outgoing handler",style=filled,fillcolor=gold];
+    scheduling [label="Scheduling",shape=ellipse,style=filled,fillcolor=gold];
+    freebusy [label="Free/busy",shape=folder,style=filled,fillcolor=gold];
+    manager [label="imip-manager",style=filled,fillcolor=gold];
+  }
+
+  client [label="Mail clients"];
+
+  client -> mail;
+  mail -> outgoingrouter -> outgoinghandler -> scheduling -> freebusy -> manager;
+}
+}}}
+
+The management interface does not use this outgoing message rule because it
+sends messages from the general calendar address (for example,
+`calendar@example.com`), and there is no trivial way of deducing the identity
+of the real sender. Instead, the manager explicitly sends suitably-modified
+messages to the address of the user operating the interface to achieve the
+same effect as the outgoing message rule, as well as to notify any mail
+clients that would normally be managing calendar events on behalf of the user.
+
+{{{#!graphviz
+//format=svg
+//transform=notugly
+digraph manager_outgoing {
+  node [shape=box,fontsize="16.0",fontname="sans-serif",tooltip="Outgoing messages from the manager"];
+  edge [tooltip="Outgoing messages from the manager"];
+  rankdir=LR;
+
+  mail [label="Outgoing mail",shape=folder,style=filled,fillcolor=cyan];
+
+  subgraph {
+    rank=same;
     personrouter [label="Person router"];
   }
 
   subgraph {
     rank=same;
-    outgoinghandler [label="Outgoing handler",style=filled,fillcolor=gold];
     personhandler [label="Person handler",style=filled,fillcolor=gold];
     scheduling [label="Scheduling",shape=ellipse,style=filled,fillcolor=gold];
     freebusy [label="Free/busy",shape=folder,style=filled,fillcolor=gold];
@@ -39,25 +67,10 @@
 
   webserver [label="Web server\n(Apache, ...)",tooltip="Web server"];
 
-  subgraph {
-    rank=same;
-    client [label="Mail clients"];
-    browser [label="Web browsers"];
-  }
-
-  client -> mail;
-  mail -> outgoingrouter -> outgoinghandler;
+  browser [label="Web browsers"];
 
-  browser -> webserver [penwidth="3.0"];
-  webserver -> manager [penwidth="3.0"];
-  manager -> mail [penwidth="3.0"];
-  mail -> personrouter [penwidth="3.0"];
-  personrouter -> personhandler [penwidth="3.0"];
-
-  outgoinghandler -> scheduling;
-  personhandler -> scheduling [penwidth="3.0"];
-  scheduling -> freebusy;
-  freebusy -> manager;
+  browser -> webserver -> manager -> mail -> personrouter ->
+  personhandler -> scheduling -> freebusy -> manager;
 }
 }}}
 
diff -r 471f15d906d4 -r d1375269e287 docs/wiki/Preferences
--- a/docs/wiki/Preferences	Mon Nov 02 00:03:42 2015 +0100
+++ b/docs/wiki/Preferences	Mon Nov 02 00:06:26 2015 +0100
@@ -26,7 +26,8 @@
 
 Each of the user preferences or settings are stored in a separate file within
 a dedicated preferences directory for each user, with the filename bearing the
-name of the setting concerned.
+name of the setting concerned. See the [[../FilesystemUsage|filesystem guide]]
+for more information.
 
 === CN ===
 
diff -r 471f15d906d4 -r d1375269e287 docs/wiki/Usage
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/wiki/Usage	Mon Nov 02 00:06:26 2015 +0100
@@ -0,0 +1,17 @@
+= Using imip-agent =
+
+With imip-agent deployed, usage of the software should occur automatically.
+However, evidence of its operation will only emerge when calendar-related
+messages are exchanged between e-mail users. This will cause a few different
+things to happen:
+
+ * Summary messages may be sent by the calendar system to mail recipients
+
+ * Replies to calendar-related messages may be received by the senders of
+ those messages
+
+ * Free/busy information will become available, either in responses to
+ requests sent over e-mail, or [[../FreeBusyPublishing|over the Web]]
+
+In the background, imip-agent uses and updates information as described in the
+[[../FilesystemUsage|filesystem usage guide]].
diff -r 471f15d906d4 -r d1375269e287 docs/wiki/WebServerIntegration
--- a/docs/wiki/WebServerIntegration	Mon Nov 02 00:03:42 2015 +0100
+++ b/docs/wiki/WebServerIntegration	Mon Nov 02 00:06:26 2015 +0100
@@ -48,6 +48,54 @@
 `conf/apache/imip-manager.conf` file provides a configuration file for
 deployment with the Apache Web server software that enables this interface.
 
+=== Configuring the Management Interface ===
+
+The `config.py` file described in the [[../Configuration|configuration guide]]
+provides some settings that can be adjusted to configure the management
+interface.
+
+{{{{#!table
+'''Setting''' || '''Result'''
+==
+`MANAGER_INTERFACE`
+|| If set to `True`, causes links to the interface to be included in
+.. notification messages sent by imip-agent. If set to `False`, such links
+.. will be omitted.
+==
+`MANAGER_URL`
+|| The deployment URL of the management interface. Together with the
+.. `MANAGER_PATH` described below, this forms the basis of the links
+.. described above. Some examples:
+{{{
+http://webserver.example.com/
+http://webserver.example.com/webapps/
+}}}
+It can be left as `None` and a default URL will be built using the
+hostname of the system running the software.
+==
+`MANAGER_URL_SCHEME`
+|| The URL scheme or protocol employed if a default URL is being constructed
+.. instead of `MANAGER_URL` providing a value. Some examples:
+{{{
+http://
+https://
+}}}
+Since the manager is only likely to be available via common Web protocols,
+other values may not make much sense.
+==
+`MANAGER_PATH`
+|| The "path info" added to the `MANAGER_URL` that locates the management
+.. interface in its deployment location. Some examples:
+{{{
+/
+/imip-agent
+}}}
+This setting affects the `imip-manager.conf` file, whose `Alias`, `ScriptAlias`
+and `Location` directives should be changed if this setting is changed.
+}}}}
+
+=== Deploying the Configuration ===
+
 On Debian, to enable the management interface, copy the configuration file to
 the Apache configuration and enable it as follows:
 
@@ -73,3 +121,31 @@
 {{{
 a2enmod authnz_ldap
 }}}
+
+=== Authenticating Users ===
+
+The `imip-manager.conf` file contains example directives for accessing
+authentication services or data.
+
+Where LDAP authentication is to be used, the appropriate LDAP URL needs to be
+specified using a directive. For example:
+
+{{{
+AuthLDAPUrl "ldap://localhost/ou=People,dc=example,dc=com?mail?sub"
+}}}
+
+Here, the `mail` attribute is used to match the username provided in the
+authentication dialogue. Configuration changes may be required within the LDAP
+infrastructure to allow this mechanism to function, but this is not described
+here.
+
+Meanwhile, particularly where [[../MailIntegration/Simple|simple integration]]
+strategies have been chosen, a plain text user file can be employed to
+authenticate users. For example:
+
+{{{
+AuthUserFile /var/www/imip-agent/users
+}}}
+
+Such a file should be created using the usual tools provided by the Apache Web
+server distribution.