# HG changeset patch # User Paul Boddie # Date 1446052120 -3600 # Node ID 0bf0e235f9e22414f57f8cd6f69e916460f42a98 # Parent d432763ecc3cc2087003b214267e2c0dfa04f3de Incorporated more of the existing documentation into the wiki pages. Added some extra material about configuration, agent programs, and the management interface. diff -r d432763ecc3c -r 0bf0e235f9e2 README.txt --- a/README.txt Wed Oct 28 17:06:44 2015 +0100 +++ b/README.txt Wed Oct 28 18:08:40 2015 +0100 @@ -42,41 +42,3 @@ See: docs/wiki/MailIntegration See: docs/wiki/MailIntegration--LMTP See: docs/wiki/MailIntegration--LocalSMTP - -Configuring Web Servers for Free/Busy Publishing -================================================ - -Each user may request the publishing of their free/busy information by -configuring certain settings. The conf/apache/imip-agent.conf file provides a -configuration file for deployment with the Apache Web server software that -exposes a directory for Web publishing containing the published free/busy -information. - -Access to free/busy information may not be moderated, but Web server -directives can be introduced to impose access controls. Mail programs that -wish to consult the free/busy information may have problems in dealing with -authentication mechanisms, however, and it may be regarded as acceptable in -certain environments to expose such information publicly or with -network-specific access constraints. - -Configuring Web Servers for the Calendar Management Interface -============================================================= - -A calendar management interface is provided to allow users to view and -interact with their calendars through the Web. The -conf/apache/imip-manager.conf file provides a configuration file for -deployment with the Apache Web server software that enables this interface. - -The management interface is deployed as a CGI program, meaning that a suitable -module must be enabled in the Apache configuration. On Debian, this is done as -follows: - -a2enmod cgi - -Since such access to calendars should only be performed by identified -users, access controls are suggested in the configuration file. Modules -providing additional authentication support may need to be enabled. For -example, on Debian, the LDAP authentication/authorisation support is enabled -as follows: - -a2enmod authnz_ldap diff -r d432763ecc3c -r 0bf0e235f9e2 docs/wiki/AgentPrograms --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/wiki/AgentPrograms Wed Oct 28 18:08:40 2015 +0100 @@ -0,0 +1,19 @@ += Agent Programs = + +A collection of programs are provided to handle messages for different kinds of +mail participants. Currently, the following programs are provided: + +|| '''Program''' || '''Purpose''' || +|| `imip_person.py` ||<|2> Maintain scheduling information on behalf of people || +|| `imip_person_outgoing.py` || +|| `imip_resource.py` || Act as an autonomous resource that can be reserved || + +For people, the role of the agent programs concerned is to construct a schedule +that can be accessed via the [[../CalendarManager|management interface]] and to +maintain a free/busy record for event scheduling purposes. + +For resources, the role of the agent program concerned is also to maintain +schedule and free/busy records, but also to act autonomously - that is, without +manual intervention - and to respond to event invitations or booking requests +according to policies defined in the [[../Configuration|configuration]] of the +system. diff -r d432763ecc3c -r 0bf0e235f9e2 docs/wiki/CalendarManager --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/wiki/CalendarManager Wed Oct 28 18:08:40 2015 +0100 @@ -0,0 +1,7 @@ += Calendar Management Interface = + +Since some users of the calendar system may not have a calendar program or a +mail program that understands calendar data, a Web-based interface is provided +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. diff -r d432763ecc3c -r 0bf0e235f9e2 docs/wiki/Configuration --- a/docs/wiki/Configuration Wed Oct 28 17:06:44 2015 +0100 +++ b/docs/wiki/Configuration Wed Oct 28 18:08:40 2015 +0100 @@ -1,14 +1,15 @@ = Configuration = -There are two principal configuration files in imip-agent: +There are three levels of configuration in imip-agent: - * `config.py` provides the configuration to the software itself * `config.sh` provides system-level and tool configuration + * `config.py` provides the configuration of the software itself + * User preferences reside as files in separate user-specific directories 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 == +== System-Level and Tool Configuration == Given a choice of [[../SystemUsers|system users and groups]], the resulting configuration must be indicated in the `config.sh` file. Since @@ -16,7 +17,7 @@ be made to the file in the `tools/config.sh` location before installation can occur. -== Agent System Configuration == +== Software 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 @@ -28,3 +29,13 @@ `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. + +== User Preferences == + +Although the software configuration in `config.py` provides default policies, +users can choose to override these defaults by editing their own preferences. +The most convenient way of doing this is to use the profile page provided by +the [[../CalendarManager|management interface]]. + +The settings for the different policies are described in the +[[../Preferences|preferences guide]]. diff -r d432763ecc3c -r 0bf0e235f9e2 docs/wiki/FreeBusyPublishing --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/wiki/FreeBusyPublishing Wed Oct 28 18:08:40 2015 +0100 @@ -0,0 +1,24 @@ += Free/Busy Publishing = + +Although iTIP [[http://tools.ietf.org/html/rfc5546#section-3.3|specifies]] the exchange +of free/busy information through requests and replies, many mail-based calendar clients +do not support these particular operations over e-mail when providing general +[[http://tools.ietf.org/html/rfc6047|iMIP]] support. However, they may support the +acquisition of free/busy information over HTTP. + +The publishing of free/busy resources for users can be enabled by default in the +[[../Configuration|configuration]] by changing the `PUBLISHING_DEFAULT` setting: + +{{{ +PUBLISHING_DEFAULT = "publish" +}}} + +For this setting to have an effect, the `SHARING_DEFAULT` setting will need to be +changed to enable free/busy sharing by default: + +{{{ +SHARING_DEFAULT = "share" +}}} + +Users can enable sharing and publishing themselves by accessing their profile in the +[[../CalendarManager|management interface]]. diff -r d432763ecc3c -r 0bf0e235f9e2 docs/wiki/FrontPage --- a/docs/wiki/FrontPage Wed Oct 28 17:06:44 2015 +0100 +++ b/docs/wiki/FrontPage Wed Oct 28 18:08:40 2015 +0100 @@ -68,20 +68,20 @@ || Although [[https://tools.ietf.org/html/rfc6047|iMIP]] supports this, most mail programs do not, so imip-agent will gather information about events and -publish it for retrieval via HTTP. It will also respond to any iMIP requests -for free/busy information via mail. +[[/FreeBusyPublishing|publish it for retrieval via HTTP]]. It will also respond +to any iMIP requests for free/busy information via mail. == Organisations may want to coordinate access to resources using calendaring. || -Here, imip-agent can provide autonomous agents that can respond to event -invitations, allowing users to book resources and to see published -availability information for those resources. +Here, imip-agent can provide [[/AgentPrograms|autonomous agents]] that can +respond to event invitations, allowing users to book resources and to see +published availability information for those resources. == Some users may not be using mail programs that understand calendars and events. || -Here, imip-agent can provide a Web interface to let them respond to -invitations and to create and schedule their own events. +Here, imip-agent can provide a [[/CalendarManager|Web interface]] to let +them respond to invitations and to create and schedule their own events. }}} According to your requirements, any or all of the above solutions can be diff -r d432763ecc3c -r 0bf0e235f9e2 docs/wiki/GettingStarted --- a/docs/wiki/GettingStarted Wed Oct 28 17:06:44 2015 +0100 +++ b/docs/wiki/GettingStarted Wed Oct 28 18:08:40 2015 +0100 @@ -34,6 +34,10 @@ appropriate locations. You may need to be `root` or use `sudo` to successfully use this script. +{{{ +tools/install.sh +}}} + See the [[../Prerequisites|prerequisites]] for other software that will be required for the software to function. @@ -59,16 +63,31 @@ 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 || +{{{#!table +'''Directory''' || '''Description''' || '''Guide''' +== +`apache` +|| Apache 2 site configuration for publishing resources +|| [[../WebServerIntegration|Web Server Integration]] +== +`cron` +|| Cron command scheduling for free/busy updates +|| [[../CronIntegration|Cron Task Scheduler Integration]] +== +`exim` +|| Exim 4 routing and transport configuration +|| [[../MailIntegration|E-Mail Integration]] +== +`ldap` +|| Some LDAP-related resources +|| +== +`postfix` +|| Postfix routing and transport configuration +|| [[../MailIntegration|E-Mail Integration]] +}}} -The configuration activities associated with these directories are covered in -the following documents: +== Configuring the Software == - * [[../CronIntegration|Cron Task Scheduler Integration]] - * [[../MailIntegration|E-Mail Integration]] - * [[../WebServerIntegration|Web Server Integration]] +The behaviour of the imip-agent software itself can be configured using +mechanisms described in the [[../Configuration|configuration guide]]. diff -r d432763ecc3c -r 0bf0e235f9e2 docs/wiki/Preferences --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/wiki/Preferences Wed Oct 28 18:08:40 2015 +0100 @@ -0,0 +1,255 @@ += Preferences = + +The correspondence between user preferences (stored in user preference +directories) and the default settings (stored in `config.py`) is described +below. + +|| '''Preference''' || '''Default Setting''' || +|| `LANG` || `LANG` || +|| `add_method_response` || `ADD_RESPONSE_DEFAULT` || +|| `event_refreshing` || `REFRESHING_DEFAULT` || +|| `freebusy_bundling` || `BUNDLING_DEFAULT` || +|| `freebusy_messages` || `NOTIFYING_DEFAULT` || +|| `freebusy_offers` || `FREEBUSY_OFFER_DEFAULT` || +|| `freebusy_publishing` || `PUBLISHING_DEFAULT` || +|| `freebusy_sharing` || `SHARING_DEFAULT` || +|| `incoming` || `INCOMING_DEFAULT` || +|| `organiser_replacement` || `ORGANISER_REPLACEMENT_DEFAULT` || +|| `participating` || `PARTICIPATING_DEFAULT` || + +See the [[../Configuration|configuration guide]] for more information about +the `config.py` file. + +== User Preference Settings == + +<> + +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. + +=== CN === + + Default:: (none) + Alternatives:: (see below) + +The common name of the user, employed in iCalendar objects and user +interfaces. + +=== LANG === + + Default:: `en` (English) + Alternatives:: (any recognised and supported locale) + +The language for messages and user interface text. + +=== TZID === + + Default:: system timezone (see `/etc/timezone`) + Alternatives:: (any recognised Olson time zone identifier) + +The default time zone/regime for calendars, new events and local times. + +=== add_method_response === + + Default:: `refresh` + Alternatives:: (see below) + +Indicate how `ADD` methods shall be responded to when received by a recipient: + +{{{#!table +`add` || apply them to events as received +== +`ignore` || ignore attempts to add event occurrences +== +`refresh` || respond with a `REFRESH` message to obtain a proper request with + .. all event details +}}} + +=== event_refreshing === + + Default:: `never` + Alternative:: `always` + +Indicate whether messages requesting a refresh of event details shall be +handled automatically. If not, such messages will be passed on to the +recipient for their mail program to handle. + +=== freebusy_bundling === + + Default:: `never` + Alternative:: `always` + +Indicate whether to bundle free/busy details with other payloads such as +event and free/busy objects. The `freebusy_sharing` setting must be +configured for bundling to operate. + +=== freebusy_messages === + + Default:: `none` + Alternative:: `notify` + +Indicate whether recipients are notified about received free/busy payloads. + +=== freebusy_offers === + + Default:: (none) + Alternative:: (see below) + +Define the period for which free/busy offers are extended by participants +supporting this setting when counter-proposals are made during event +scheduling. + +This setting requires a value indicating a duration as described in the +iCalendar format specification: + +http://tools.ietf.org/html/rfc5545#section-3.3.6 + +For example: + +|| `PT10M` || extend scheduling offers for 10 minutes || +|| `PT600S` || extend scheduling offers for 600 seconds (10 minutes) || +|| `PT1D` || extend offers for 1 day || + +=== freebusy_publishing === + + Default:: `no` + Alternative:: `publish` + +Indicate whether to publish free/busy details as Web resources. The +`freebusy_sharing` setting must be configured for publishing to operate. + +=== freebusy_sharing === + + Default:: `no` + Alternative:: `share` + +Share free/busy details generally: + + * bundling in e-mail messages if bundling is configured + * responding to free/busy requests via e-mail + * publishing as Web resources if a static Web resource is configured and if + publishing is configured + +=== incoming === + + Default:: `summary-wraps-message` + Alternatives:: (see below) + +Define how incoming event messages are delivered to recipients: + +{{{#!table +`message-only` +|| deliver only the incoming message as it was received +== +`message-then-summary` +|| deliver the message first followed by a summary message +== +`summary-then-message` +|| deliver a summary first followed by the message +== +`summary-only` +|| deliver only a summary of the message +== +`summary-wraps-message` +|| deliver a summary that includes the original message as an attachment +}}} + +=== organiser_replacement === + + Default:: `attendee` + Alternatives:: (see below) + +Indicate whether the organiser of an event can be replaced and the nature of +any replacement: + +{{{#!table +`any` || any identity, regardless of whether it is already present or even + .. previously unknown, may become the organiser +== +`attendee` || any new organiser must be a previously-recognised attendee +== +`never` || forbid the replacement of an event's organiser +}}} + +=== participating === + + Default:: `participate` + Alternative:: `no` + +Indicate whether a recipient participates in the calendar system. Note that +participation by default occurs because the handler programs will be defined +in the mail system for recipients fulfilling certain criteria; other +recipients will be handled in other ways. Thus, initial non-participation must +be defined by initialising this setting to "no" for all eligible users, if +this is the general policy on initial calendar system participation. + +=== permitted_times === + + Default:: (none) + Alternatives:: (see below) + +Define the time values at which events can be scheduled. In its simplest form, +this indicates the resolution of a calendar for a participant supporting this +setting, with the given minute values being those allowed for the start and +end of an event. This setting requires a value of one of the following forms: + +{{{ + +: +:: +}}} + +Each list of values is a comma-separated collection of permissible values for +the unit of time being constrained. Any unspecified list is taken to permit +all normally permissible values for that unit of time. For example: + +{{{#!table +`0,15,30,45` || every 15 minutes from the start of each hour +== +`10,12,14,16:0,20,40` || every 20 minutes from 10:00 until 16:40 inclusive +== +`12::0,30` || every 30 seconds from the start of each minute + .. during the period from 12:00:00 until 12:59:30 + .. inclusive +}}} + +The purpose of this setting is not necessarily to impose availability +constraints but instead to impose a "grid" to which event start and end points +shall be "locked". + +The values are interpreted in the local time of the participant. Thus, a time +represented in UTC may have apparently inappropriate hour (and for some zones) +minute values that correspond to permitted values in this participant's own +time zone. + +=== scheduling_function === + + Default:: `schedule_in_freebusy` + Alternatives:: (see below) + +Indicates the scheduling function used by resources to find an appropriate +period for an event. The `imiptools.handlers.scheduling` module contains the +built-in scheduling functions which include the following: + +{{{#!table +`schedule_in_freebusy` || accept an invitation if the event periods are free + .. according to the free/busy records for the resource; + .. decline otherwise +== +`schedule_corrected_in_freebusy` || correct periods in an event according to + .. the permitted_times setting (see above), + .. then attempt to schedule the event according to the + .. free/busy records for the resource +== +`schedule_next_available_in_freebusy` || correct periods in an event according + .. to the permitted_times setting (see + .. above), if configured, and attempt to schedule the + .. event according to the free/busy records for the + .. resource and for any attendees for whom records are + .. available, seeking the next available free period for + .. each period that conflicts with an existing event +}}} + +The scheduling mechanism can be extended by implementing additional scheduling +functions or by extending the handler framework directly. diff -r d432763ecc3c -r 0bf0e235f9e2 docs/wiki/WebServerIntegration --- a/docs/wiki/WebServerIntegration Wed Oct 28 17:06:44 2015 +0100 +++ b/docs/wiki/WebServerIntegration Wed Oct 28 18:08:40 2015 +0100 @@ -3,13 +3,13 @@ Although imip-agent is mostly concerned with e-mail messaging, it can integrate with a Web server for the following purposes: - * To publish free/busy information for calendar users - * To provide a management interface for calendar users + * To [[../FreeBusyPublishing|publish free/busy information]] for calendar users + * To provide a [[../CalendarManager|management interface]] for calendar users Currently, imip-agent provides configuration files for Apache, but other Web servers may also be supported. -== Authentication and Access Control == +== Authentication and Access Control in Apache == Apache supports a range of mechanisms for protecting resources and authenticating users. Most usefully for imip-agent given the @@ -17,3 +17,43 @@ [[http://httpd.apache.org/docs/2.4/mod/mod_authnz_ldap.html|LDAP]] and [[http://httpd.apache.org/docs/2.4/mod/mod_auth_basic.html|text-based lists]] of users are available for such purposes. + +== Configuring Web Servers for Free/Busy Publishing == + +Each user may request the [[../FreeBusyPublishing|publishing]] of their +free/busy information by configuring certain settings. The +`conf/apache/imip-agent.conf` file provides a configuration file for +deployment with the Apache Web server software that exposes a directory for +Web publishing containing the published free/busy information. + +Access to free/busy information may not be moderated, but Web server +directives can be introduced to impose access controls. Mail programs that +wish to consult the free/busy information may have problems in dealing with +authentication mechanisms, however, and it may be regarded as acceptable in +certain environments to expose such information publicly or with +network-specific access constraints. + +== Configuring Web Servers for the Calendar Management Interface == + +A [[../CalendarManager|calendar management interface]] is provided to allow +users to view and interact with their calendars through the Web. The +`conf/apache/imip-manager.conf` file provides a configuration file for +deployment with the Apache Web server software that enables this interface. + +The management interface is deployed as a CGI program, meaning that a suitable +module must be enabled in the Apache configuration. On Debian, this is done as +follows: + +{{{ +a2enmod cgi +}}} + +Since such access to calendars should only be performed by identified +users, access controls are suggested in the configuration file. Modules +providing additional authentication support may need to be enabled. For +example, on Debian, the LDAP authentication/authorisation support is enabled +as follows: + +{{{ +a2enmod authnz_ldap +}}}