1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/docs/wiki/CalendaringSupport Mon Nov 02 20:08:20 2015 +0100
1.3 @@ -0,0 +1,64 @@
1.4 += Calendaring Support =
1.5 +
1.6 +imip-agent aims to provide broad support for the following standards:
1.7 +
1.8 + * [[https://tools.ietf.org/html/rfc5545|iCalendar]]
1.9 + * [[https://tools.ietf.org/html/rfc5546|iTIP]]
1.10 + * [[https://tools.ietf.org/html/rfc6047|iMIP]]
1.11 +
1.12 +The following sections indicate notable deviations or deficiencies in the support
1.13 +for these standards.
1.14 +
1.15 +== iCalendar ==
1.16 +
1.17 +The general iCalendar format should be mostly supported, but the interpretation
1.18 +of calendar objects in imip-agent is currently limited to events and free/busy
1.19 +data, and the software does not seek to understand the other object types
1.20 +described in the specification.
1.21 +
1.22 +The `VTIMEZONE` component is not interpreted. Instead, `TZID` properties are
1.23 +expected to provide [[https://en.wikipedia.org/wiki/Tz_database|tz database]]
1.24 +(tzinfo, zoneinfo, Olson database) identifiers that indicate the time zone or
1.25 +"regime" applying to the indicated datetimes.
1.26 +
1.27 +The `VALARM` component is not interpreted since imip-agent does not seek to
1.28 +implement reminders or notifications, although it is conceivable that a mechanism
1.29 +could be implemented to achieve this over e-mail.
1.30 +
1.31 +Week numbers (`BYWEEKNO`) are not yet supported in recurring datetimes.
1.32 +
1.33 +Only the essential scheduling properties are interpreted by imip-agent. Thus,
1.34 +support for attachments, categories, and so on is not provided in the
1.35 +[[../CalendarManager|management interface]]. Such support may eventually be
1.36 +added, and existing calendar clients may, of course, use such features without
1.37 +any restrictions imposed by imip-agent.
1.38 +
1.39 +== iTIP ==
1.40 +
1.41 +Only event and free/busy object types are supported in scheduling.
1.42 +
1.43 +`VTIMEZONE` and `VALARM` are not interpreted.
1.44 +
1.45 +Delegation
1.46 +([[http://tools.ietf.org/html/rfc5546#section-2.1.2|RFC 5546 section 2.1.2]])
1.47 +is not yet supported.
1.48 +
1.49 +Multiple recurrence updates using the `THISANDFUTURE` attribute on the
1.50 +`RECURRENCE-ID` property
1.51 +([[http://tools.ietf.org/html/rfc5546#section-4.4.5|RFC 5546 section 4.4.5]])
1.52 +is not yet supported.
1.53 +
1.54 +The `REQUEST-STATUS` property is not yet supported. (See
1.55 +[[http://tools.ietf.org/html/rfc5546#section-7.3|RFC 5546 section 7.3]].)
1.56 +
1.57 +Support is provided in the [[../Configuration|configuration]] of imip-agent
1.58 +for interpreting `REQUEST` messages that should really be `COUNTER` messages,
1.59 +generated by some mail programs. See the `IMIP_COUNTER_AS_REQUEST` setting in
1.60 +`config.py`.
1.61 +
1.62 +== iMIP ==
1.63 +
1.64 +Since attachments are not supported by the
1.65 +[[../CalendarManager|management interface]], imip-agent does not generate or
1.66 +interpret the various methods of referencing attachments in exchanged objects.
1.67 +(See [[https://tools.ietf.org/html/rfc6047#section-4.3|RFC 6047 section 4.3]].)
2.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
2.2 +++ b/docs/wiki/Downloads Mon Nov 02 20:08:20 2015 +0100
2.3 @@ -0,0 +1,40 @@
2.4 += Downloads =
2.5 +
2.6 +Ultimately, the aim is to be able to integrate imip-agent into Free Software
2.7 +operating system distributions such as Debian, providing packages that are
2.8 +trivially installed and that work with the rest of the system straight away.
2.9 +Until this is realised, the software will need to be downloaded manually.
2.10 +
2.11 +== Repository ==
2.12 +
2.13 +The source code repository is located at the following location:
2.14 +
2.15 +http://hgweb.boddie.org.uk/imip-agent
2.16 +
2.17 +The repository can be cloned using [[http://mercurial.selenic.com/|Mercurial]]
2.18 +as follows:
2.19 +
2.20 +{{{
2.21 +hg clone http://hgweb.boddie.org.uk/imip-agent
2.22 +}}}
2.23 +
2.24 +If you are familiar with version control systems and Mercurial in particular,
2.25 +it can be convenient to use this approach to obtain and update the software,
2.26 +although you should be aware that updates to the repository may cause the
2.27 +software to not function correctly on occasion, even if attempts are made to
2.28 +avoid such situations. Therefore, you should choose to update with care and
2.29 +be prepared to switch to a "known working" revision if necessary.
2.30 +
2.31 +== Releases ==
2.32 +
2.33 +Releases are tagged in the repository. The currently-supported releases are
2.34 +listed here for convenience:
2.35 +
2.36 +{{{#!table
2.37 +'''Release''' || '''Archives'''
2.38 +==
2.39 +0.1
2.40 +|| [[http://hgweb.boddie.org.uk/imip-agent/archive/rel-0-1.tar.bz2|tar.bz2]]
2.41 +.. [[http://hgweb.boddie.org.uk/imip-agent/archive/rel-0-1.tar.gz|tar.gz]]
2.42 +.. [[http://hgweb.boddie.org.uk/imip-agent/archive/rel-0-1.zip|zip]]
2.43 +}}}
3.1 --- a/docs/wiki/FrontPage Mon Nov 02 00:06:26 2015 +0100
3.2 +++ b/docs/wiki/FrontPage Mon Nov 02 20:08:20 2015 +0100
3.3 @@ -1,5 +1,10 @@
3.4 = imip-agent =
3.5
3.6 +{{{#!table
3.7 +[[/Downloads|Downloads]] || [[/GettingStarted|Getting started]] ||
3.8 +[[#Deployment|Deployment]] || [[#Notes|Design/Implementation Notes]]
3.9 +}}}
3.10 +
3.11 imip-agent is an extension for existing mail systems (such as
3.12 [[http://exim.org/|Exim]] and [[http://www.postfix.org/|Postfix]])
3.13 providing extra support for calendaring and scheduling.
3.14 @@ -123,19 +128,23 @@
3.15 According to your requirements, any or all of the above solutions can be
3.16 implemented, providing as much of a groupware solution as you need.
3.17
3.18 -== Deployment Notes ==
3.19 +<<Anchor(Deployment)>>
3.20 +== Deploying the Software ==
3.21
3.22 + * [[/Downloads|Downloads]]
3.23 * [[/GettingStarted|Getting Started]]
3.24 * [[/Configuration|Configuration]] and [[/Preferences|Preferences]]
3.25 * [[/CalendarManager|Calendar Management Interface]]
3.26 * [[/FreeBusyPublishing|Free/Busy Publishing]]
3.27 * [[/Usage|Usage]]
3.28
3.29 +<<Anchor(Notes)>>
3.30 == Design and Implementation Notes ==
3.31
3.32 Details of the mechanisms employed by imip-agent are described in the
3.33 following documents:
3.34
3.35 + * [[/CalendaringSupport|Calendaring Support]]
3.36 * [[/CounterProposals|Counter-Proposals and Offers]]
3.37 * [[/CronIntegration|Cron Task Scheduler Integration]]
3.38 * [[/EventRecurrences|Event Recurrences]]
4.1 --- a/docs/wiki/MailIntegration Mon Nov 02 00:06:26 2015 +0100
4.2 +++ b/docs/wiki/MailIntegration Mon Nov 02 20:08:20 2015 +0100
4.3 @@ -92,6 +92,15 @@
4.4 [[/Simple|Simple (list-based identification)]] || Exim, Postfix
4.5 }}}
4.6
4.7 +It is worth repeating that imip-agent does not try and validate users. Once
4.8 +the MTA has decided that a recipient can actually receive a message, and once
4.9 +that message is passed to one of the [[../AgentPrograms|agent programs]], the
4.10 +software will process that message and record information for the recipient in
4.11 +the [[../FilesystemUsage|filesystem structures]] for the user.
4.12 +
4.13 +See the [[../Usage|usage guide]] for information on preparing data stores for
4.14 +users in advance of any mail being received for them.
4.15 +
4.16 === The Calendar System Address ===
4.17
4.18 Since imip-agent may send messages on behalf of calendar users, the address
5.1 --- a/docs/wiki/Testing Mon Nov 02 00:06:26 2015 +0100
5.2 +++ b/docs/wiki/Testing Mon Nov 02 20:08:20 2015 +0100
5.3 @@ -1,5 +1,16 @@
5.4 = Testing =
5.5
5.6 +Before attempting to integrate imip-agent with other system components,
5.7 +it can be useful to check whether the different programs function as
5.8 +expected by themselves. Should errors or faults occur, these would need
5.9 +to be remedied first before attempting to get the software working with
5.10 +the [[../MailIntegration|mail]] and [[../WebIntegration|Web]] system
5.11 +components.
5.12 +
5.13 +<<TableOfContents(2,2)>>
5.14 +
5.15 +== How the Software Works ==
5.16 +
5.17 To see how the software operates, you can run one of the agent programs
5.18 provided in the distribution. For example:
5.19
5.20 @@ -70,3 +81,26 @@
5.21 consults its own records, makes a decision about scheduling the event,
5.22 and indicates the kind of response it would like to send back to the
5.23 requester.
5.24 +
5.25 +== The Test Suite ==
5.26 +
5.27 +A script called `test_all.sh` is provided that runs a test suite (found
5.28 +in the `tests` directory within the source code distribution), initialising
5.29 +new and separate data store instances for each test, running programs that
5.30 +are presented with message content, and testing for the desired effects of
5.31 +running those programs with such content.
5.32 +
5.33 +Individual tests may also be run directly from the topmost level of the
5.34 +source code distribution. For example:
5.35 +
5.36 +{{{
5.37 +tests/test_resource_invitation.sh
5.38 +}}}
5.39 +
5.40 +Should everything be functioning correctly, `Success` should be reported
5.41 +repeatedly as opposed to `Failed`. If the latter occurs, the output of the
5.42 +tests should be inspected: a number of files whose names end with `.tmp`
5.43 +will have been saved in the current directory, and these will contain the
5.44 +output from various commands from the last test script invocation; the
5.45 +`err.tmp` will contain tracebacks indicating serious error conditions,
5.46 +should any have occurred.
6.1 --- a/docs/wiki/Usage Mon Nov 02 00:06:26 2015 +0100
6.2 +++ b/docs/wiki/Usage Mon Nov 02 20:08:20 2015 +0100
6.3 @@ -15,3 +15,64 @@
6.4
6.5 In the background, imip-agent uses and updates information as described in the
6.6 [[../FilesystemUsage|filesystem usage guide]].
6.7 +
6.8 +== Creating User Data Stores ==
6.9 +
6.10 +The [[../MailIntegration|mail system]] mechanisms are responsible for
6.11 +determining whether a valid recipient has been specified in any given message,
6.12 +and imip-agent does not attempt to validate such information again. Therefore,
6.13 +when a message is received for a calendar user for whom no data store has been
6.14 +initialised in the [[../FilesystemUsage|filesystem]], the software will
6.15 +automatically create one.
6.16 +
6.17 +Consequently, users for whom such data stores have been created will experience
6.18 +the software using the default configuration, described in the
6.19 +[[../Preferences|preferences guide]]. It is for this reason that the default
6.20 +values in the [[../Configuration|configuration]] should be adjusted according
6.21 +to the policies decided for the deployment of this software.
6.22 +
6.23 +However, it is possible to create data stores for users in advance using the
6.24 +`tools/init_user.sh` script as in the following example:
6.25 +
6.26 +{{{
6.27 +tools/init_user.sh mailto:vincent.vole@example.com
6.28 +}}}
6.29 +
6.30 +Here, the user identity is given as a URI since this is how iCalendar references
6.31 +participants in scheduling operations. The result of the above command should be
6.32 +some new directories in the [[../FilesystemUsage|filesystem area]] dedicated to
6.33 +calendar information storage.
6.34 +
6.35 +=== Adjusting Preferences ===
6.36 +
6.37 +Once initialised, the user preferences can be adjusted by adding files to the
6.38 +`preferences` directory created by the above command. For example, if a user has
6.39 +elected to not participate in the calendar system, a file called `participating`
6.40 +can be added as follows:
6.41 +
6.42 +{{{
6.43 +echo 'no' > '/var/lib/imip-agent/preferences/mailto:vincent.vole@example.com/participating'
6.44 +}}}
6.45 +
6.46 +Here, the default storage location has been given in the filename.
6.47 +
6.48 +Normally, users should visit the [[../CalendarManager|management interface]] to
6.49 +change their preferences, but modifications done by administrators are more
6.50 +efficiently performed by directly interacting with the filesystem. For example,
6.51 +an administrator might initialise the common names of users by scripting changes
6.52 +to the `CN` file for each user, obtaining such names from some kind of database.
6.53 +
6.54 +== Excluding Users Entirely ==
6.55 +
6.56 +Since the [[../AgentPrograms|agent programs]] are installed as part of the mail
6.57 +handling workflow, even the configuration of non-participation in the calendar
6.58 +system for users will still result in those users' messages being passed along
6.59 +the workflow by imip-agent, which may result in a decrease in general mail
6.60 +delivery performance.
6.61 +
6.62 +To exclude users entirely, the routing configuration of the
6.63 +[[../MailIntegration|MTA]] needs to be changed so that such users identities are
6.64 +not recognised as calendar system participants, thus preventing their messages
6.65 +from being routed via imip-agent. This is as simple as either not listing the
6.66 +identity in [[../MailIntegration/Simple|lists of addresses]] or by adjusting
6.67 +[[../MailIntegration/LDAP|queries yielding calendar users]].