# HG changeset patch # User Paul Boddie # Date 1446491300 -3600 # Node ID c573fc2035e74ce32f38be0644d5fd6ba463e7be # Parent d1375269e287a0de3675503100a6983c3c502bc5 Added new content on calendaring support, downloads and obtaining the code, the identification of mail recipients and participants in the calendar system, the test suite, and the initialisation and configuration of calendar user structures and preferences. diff -r d1375269e287 -r c573fc2035e7 docs/wiki/CalendaringSupport --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/wiki/CalendaringSupport Mon Nov 02 20:08:20 2015 +0100 @@ -0,0 +1,64 @@ += Calendaring Support = + +imip-agent aims to provide broad support for the following standards: + + * [[https://tools.ietf.org/html/rfc5545|iCalendar]] + * [[https://tools.ietf.org/html/rfc5546|iTIP]] + * [[https://tools.ietf.org/html/rfc6047|iMIP]] + +The following sections indicate notable deviations or deficiencies in the support +for these standards. + +== iCalendar == + +The general iCalendar format should be mostly supported, but the interpretation +of calendar objects in imip-agent is currently limited to events and free/busy +data, and the software does not seek to understand the other object types +described in the specification. + +The `VTIMEZONE` component is not interpreted. Instead, `TZID` properties are +expected to provide [[https://en.wikipedia.org/wiki/Tz_database|tz database]] +(tzinfo, zoneinfo, Olson database) identifiers that indicate the time zone or +"regime" applying to the indicated datetimes. + +The `VALARM` component is not interpreted since imip-agent does not seek to +implement reminders or notifications, although it is conceivable that a mechanism +could be implemented to achieve this over e-mail. + +Week numbers (`BYWEEKNO`) are not yet supported in recurring datetimes. + +Only the essential scheduling properties are interpreted by imip-agent. Thus, +support for attachments, categories, and so on is not provided in the +[[../CalendarManager|management interface]]. Such support may eventually be +added, and existing calendar clients may, of course, use such features without +any restrictions imposed by imip-agent. + +== iTIP == + +Only event and free/busy object types are supported in scheduling. + +`VTIMEZONE` and `VALARM` are not interpreted. + +Delegation +([[http://tools.ietf.org/html/rfc5546#section-2.1.2|RFC 5546 section 2.1.2]]) +is not yet supported. + +Multiple recurrence updates using the `THISANDFUTURE` attribute on the +`RECURRENCE-ID` property +([[http://tools.ietf.org/html/rfc5546#section-4.4.5|RFC 5546 section 4.4.5]]) +is not yet supported. + +The `REQUEST-STATUS` property is not yet supported. (See +[[http://tools.ietf.org/html/rfc5546#section-7.3|RFC 5546 section 7.3]].) + +Support is provided in the [[../Configuration|configuration]] of imip-agent +for interpreting `REQUEST` messages that should really be `COUNTER` messages, +generated by some mail programs. See the `IMIP_COUNTER_AS_REQUEST` setting in +`config.py`. + +== iMIP == + +Since attachments are not supported by the +[[../CalendarManager|management interface]], imip-agent does not generate or +interpret the various methods of referencing attachments in exchanged objects. +(See [[https://tools.ietf.org/html/rfc6047#section-4.3|RFC 6047 section 4.3]].) diff -r d1375269e287 -r c573fc2035e7 docs/wiki/Downloads --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/wiki/Downloads Mon Nov 02 20:08:20 2015 +0100 @@ -0,0 +1,40 @@ += Downloads = + +Ultimately, the aim is to be able to integrate imip-agent into Free Software +operating system distributions such as Debian, providing packages that are +trivially installed and that work with the rest of the system straight away. +Until this is realised, the software will need to be downloaded manually. + +== Repository == + +The source code repository is located at the following location: + +http://hgweb.boddie.org.uk/imip-agent + +The repository can be cloned using [[http://mercurial.selenic.com/|Mercurial]] +as follows: + +{{{ +hg clone http://hgweb.boddie.org.uk/imip-agent +}}} + +If you are familiar with version control systems and Mercurial in particular, +it can be convenient to use this approach to obtain and update the software, +although you should be aware that updates to the repository may cause the +software to not function correctly on occasion, even if attempts are made to +avoid such situations. Therefore, you should choose to update with care and +be prepared to switch to a "known working" revision if necessary. + +== Releases == + +Releases are tagged in the repository. The currently-supported releases are +listed here for convenience: + +{{{#!table +'''Release''' || '''Archives''' +== +0.1 +|| [[http://hgweb.boddie.org.uk/imip-agent/archive/rel-0-1.tar.bz2|tar.bz2]] +.. [[http://hgweb.boddie.org.uk/imip-agent/archive/rel-0-1.tar.gz|tar.gz]] +.. [[http://hgweb.boddie.org.uk/imip-agent/archive/rel-0-1.zip|zip]] +}}} diff -r d1375269e287 -r c573fc2035e7 docs/wiki/FrontPage --- a/docs/wiki/FrontPage Mon Nov 02 00:06:26 2015 +0100 +++ b/docs/wiki/FrontPage Mon Nov 02 20:08:20 2015 +0100 @@ -1,5 +1,10 @@ = imip-agent = +{{{#!table +[[/Downloads|Downloads]] || [[/GettingStarted|Getting started]] || +[[#Deployment|Deployment]] || [[#Notes|Design/Implementation Notes]] +}}} + imip-agent is an extension for existing mail systems (such as [[http://exim.org/|Exim]] and [[http://www.postfix.org/|Postfix]]) providing extra support for calendaring and scheduling. @@ -123,19 +128,23 @@ 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 == +<> +== Deploying the Software == + * [[/Downloads|Downloads]] * [[/GettingStarted|Getting Started]] * [[/Configuration|Configuration]] and [[/Preferences|Preferences]] * [[/CalendarManager|Calendar Management Interface]] * [[/FreeBusyPublishing|Free/Busy Publishing]] * [[/Usage|Usage]] +<> == Design and Implementation Notes == Details of the mechanisms employed by imip-agent are described in the following documents: + * [[/CalendaringSupport|Calendaring Support]] * [[/CounterProposals|Counter-Proposals and Offers]] * [[/CronIntegration|Cron Task Scheduler Integration]] * [[/EventRecurrences|Event Recurrences]] diff -r d1375269e287 -r c573fc2035e7 docs/wiki/MailIntegration --- a/docs/wiki/MailIntegration Mon Nov 02 00:06:26 2015 +0100 +++ b/docs/wiki/MailIntegration Mon Nov 02 20:08:20 2015 +0100 @@ -92,6 +92,15 @@ [[/Simple|Simple (list-based identification)]] || Exim, Postfix }}} +It is worth repeating that imip-agent does not try and validate users. Once +the MTA has decided that a recipient can actually receive a message, and once +that message is passed to one of the [[../AgentPrograms|agent programs]], the +software will process that message and record information for the recipient in +the [[../FilesystemUsage|filesystem structures]] for the user. + +See the [[../Usage|usage guide]] for information on preparing data stores for +users in advance of any mail being received for them. + === The Calendar System Address === Since imip-agent may send messages on behalf of calendar users, the address diff -r d1375269e287 -r c573fc2035e7 docs/wiki/Testing --- a/docs/wiki/Testing Mon Nov 02 00:06:26 2015 +0100 +++ b/docs/wiki/Testing Mon Nov 02 20:08:20 2015 +0100 @@ -1,5 +1,16 @@ = Testing = +Before attempting to integrate imip-agent with other system components, +it can be useful to check whether the different programs function as +expected by themselves. Should errors or faults occur, these would need +to be remedied first before attempting to get the software working with +the [[../MailIntegration|mail]] and [[../WebIntegration|Web]] system +components. + +<> + +== How the Software Works == + To see how the software operates, you can run one of the agent programs provided in the distribution. For example: @@ -70,3 +81,26 @@ 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. + +== The Test Suite == + +A script called `test_all.sh` is provided that runs a test suite (found +in the `tests` directory within the source code distribution), initialising +new and separate data store instances for each test, running programs that +are presented with message content, and testing for the desired effects of +running those programs with such content. + +Individual tests may also be run directly from the topmost level of the +source code distribution. For example: + +{{{ +tests/test_resource_invitation.sh +}}} + +Should everything be functioning correctly, `Success` should be reported +repeatedly as opposed to `Failed`. If the latter occurs, the output of the +tests should be inspected: a number of files whose names end with `.tmp` +will have been saved in the current directory, and these will contain the +output from various commands from the last test script invocation; the +`err.tmp` will contain tracebacks indicating serious error conditions, +should any have occurred. diff -r d1375269e287 -r c573fc2035e7 docs/wiki/Usage --- a/docs/wiki/Usage Mon Nov 02 00:06:26 2015 +0100 +++ b/docs/wiki/Usage Mon Nov 02 20:08:20 2015 +0100 @@ -15,3 +15,64 @@ In the background, imip-agent uses and updates information as described in the [[../FilesystemUsage|filesystem usage guide]]. + +== Creating User Data Stores == + +The [[../MailIntegration|mail system]] mechanisms are responsible for +determining whether a valid recipient has been specified in any given message, +and imip-agent does not attempt to validate such information again. Therefore, +when a message is received for a calendar user for whom no data store has been +initialised in the [[../FilesystemUsage|filesystem]], the software will +automatically create one. + +Consequently, users for whom such data stores have been created will experience +the software using the default configuration, described in the +[[../Preferences|preferences guide]]. It is for this reason that the default +values in the [[../Configuration|configuration]] should be adjusted according +to the policies decided for the deployment of this software. + +However, it is possible to create data stores for users in advance using the +`tools/init_user.sh` script as in the following example: + +{{{ +tools/init_user.sh mailto:vincent.vole@example.com +}}} + +Here, the user identity is given as a URI since this is how iCalendar references +participants in scheduling operations. The result of the above command should be +some new directories in the [[../FilesystemUsage|filesystem area]] dedicated to +calendar information storage. + +=== Adjusting Preferences === + +Once initialised, the user preferences can be adjusted by adding files to the +`preferences` directory created by the above command. For example, if a user has +elected to not participate in the calendar system, a file called `participating` +can be added as follows: + +{{{ +echo 'no' > '/var/lib/imip-agent/preferences/mailto:vincent.vole@example.com/participating' +}}} + +Here, the default storage location has been given in the filename. + +Normally, users should visit the [[../CalendarManager|management interface]] to +change their preferences, but modifications done by administrators are more +efficiently performed by directly interacting with the filesystem. For example, +an administrator might initialise the common names of users by scripting changes +to the `CN` file for each user, obtaining such names from some kind of database. + +== Excluding Users Entirely == + +Since the [[../AgentPrograms|agent programs]] are installed as part of the mail +handling workflow, even the configuration of non-participation in the calendar +system for users will still result in those users' messages being passed along +the workflow by imip-agent, which may result in a decrease in general mail +delivery performance. + +To exclude users entirely, the routing configuration of the +[[../MailIntegration|MTA]] needs to be changed so that such users identities are +not recognised as calendar system participants, thus preventing their messages +from being routed via imip-agent. This is as simple as either not listing the +identity in [[../MailIntegration/Simple|lists of addresses]] or by adjusting +[[../MailIntegration/LDAP|queries yielding calendar users]].