imip-agent

Annotated docs/wiki/Administration

1061:5f9f96eb4f8f
1053:068aa85f0c45
1039:a12150034cbd
2016-02-08 Paul Boddie file changeset files shortlog Made the retraction operation a complete transaction. Tidied up the locking and unlocking function application.
paul@994 1 
= Administering imip-agent =
paul@988 2 
 
 paul@988      3 
With imip-agent deployed, usage of the software should occur automatically.
 
 paul@988      4 
However, evidence of its operation will only emerge when calendar-related
 
 paul@988      5 
messages are exchanged between e-mail users. This will cause a few different
 
 paul@988      6 
things to happen:
 
 paul@988      7 
 
 paul@988      8 
 * Summary messages may be sent by the calendar system to mail recipients
 
 paul@988      9 
 
 paul@988     10 
 * Replies to calendar-related messages may be received by the senders of
 
 paul@988     11 
 those messages
 
 paul@988     12 
 
 paul@988     13 
 * Free/busy information will become available, either in responses to
 
 paul@988     14 
 requests sent over e-mail, or [[../FreeBusyPublishing|over the Web]]
 
 paul@988     15 
 
 paul@988     16 
In the background, imip-agent uses and updates information as described in the
 
 paul@988     17 
[[../FilesystemUsage|filesystem usage guide]].
 
 paul@989     18 
 
 paul@1028     19 
<<TableOfContents(2,3)>>
 
 paul@1028     20 
 
 paul@1003     21 
== Initialising the System ==
 
 paul@1003     22 
 
 paul@1003     23 
As described in the [[../GettingStarted|getting started guide]], the system is
 
 paul@1003     24 
initialised by running the initialisation script:
 
 paul@1003     25 
 
 paul@1003     26 
{{{
 
 paul@1003     27 
tools/init.sh
 
 paul@1003     28 
}}}
 
 paul@1003     29 
 
 paul@1003     30 
== Creating Data Stores for Individual Users ==
 
 paul@989     31 
 
 paul@989     32 
The [[../MailIntegration|mail system]] mechanisms are responsible for
 
 paul@989     33 
determining whether a valid recipient has been specified in any given message,
 
 paul@989     34 
and imip-agent does not attempt to validate such information again. Therefore,
 
 paul@989     35 
when a message is received for a calendar user for whom no data store has been
 
 paul@989     36 
initialised in the [[../FilesystemUsage|filesystem]], the software will
 
 paul@989     37 
automatically create one.
 
 paul@989     38 
 
 paul@989     39 
Consequently, users for whom such data stores have been created will experience
 
 paul@989     40 
the software using the default configuration, described in the
 
 paul@989     41 
[[../Preferences|preferences guide]]. It is for this reason that the default
 
 paul@989     42 
values in the [[../Configuration|configuration]] should be adjusted according
 
 paul@989     43 
to the policies decided for the deployment of this software.
 
 paul@989     44 
 
 paul@989     45 
However, it is possible to create data stores for users in advance using the
 
 paul@989     46 
`tools/init_user.sh` script as in the following example:
 
 paul@989     47 
 
 paul@989     48 
{{{
 
 paul@989     49 
tools/init_user.sh mailto:vincent.vole@example.com
 
 paul@989     50 
}}}
 
 paul@989     51 
 
 paul@989     52 
Here, the user identity is given as a URI since this is how iCalendar references
 
 paul@989     53 
participants in scheduling operations. The result of the above command should be
 
 paul@989     54 
some new directories in the [[../FilesystemUsage|filesystem area]] dedicated to
 
 paul@989     55 
calendar information storage.
 
 paul@989     56 
 
 paul@994     57 
=== Initialising Resources ===
 
 paul@994     58 
 
 paul@994     59 
Resources belong to a class of user whose preferences should be configured in
 
 paul@994     60 
advance because their policies may differ on a case-by-case basis. For example,
 
 paul@994     61 
some resources may benefit from employing the `permitted_times` setting so that
 
 paul@994     62 
a granularity on event times may be imposed, meaning that such resources would
 
 paul@994     63 
be "handed over" at regular intervals.
 
 paul@994     64 
 
 paul@994     65 
The `freebusy_offers` setting, together with the `scheduling_function` setting,
 
 paul@1028     66 
allows different kinds of resources to "keep open" tentatively-suggested
 
 paul@994     67 
periods for different lengths of time, allowing frequently-requested resources
 
 paul@994     68 
to respond to scheduling requests in a timely fashion, whilst also allowing
 
 paul@994     69 
other resources to give more time to event organisers to respond to their
 
 paul@994     70 
counter-proposals.
 
 paul@994     71 
 
 paul@1032     72 
See the [[../Resources|resources guide]] for more information about configuring
 
 paul@1032     73 
resources.
 
 paul@1032     74 
 
 paul@989     75 
=== Adjusting Preferences ===
 
 paul@989     76 
 
 paul@989     77 
Once initialised, the user preferences can be adjusted by adding files to the
 
 paul@989     78 
`preferences` directory created by the above command. For example, if a user has
 
 paul@989     79 
elected to not participate in the calendar system, a file called `participating`
 
 paul@989     80 
can be added as follows:
 
 paul@989     81 
 
 paul@989     82 
{{{
 
 paul@989     83 
echo 'no' > '/var/lib/imip-agent/preferences/mailto:vincent.vole@example.com/participating'
 
 paul@989     84 
}}}
 
 paul@989     85 
 
 paul@989     86 
Here, the default storage location has been given in the filename.
 
 paul@989     87 
 
 paul@989     88 
Normally, users should visit the [[../CalendarManager|management interface]] to
 
 paul@989     89 
change their preferences, but modifications done by administrators are more
 
 paul@989     90 
efficiently performed by directly interacting with the filesystem. For example,
 
 paul@989     91 
an administrator might initialise the common names of users by scripting changes
 
 paul@989     92 
to the `CN` file for each user, obtaining such names from some kind of database.
 
 paul@989     93 
 
 paul@999     94 
The permissions on any created files must be consistent with those defined when
 
 paul@999     95 
configuring the [[../SystemUsers|system users]] for imip-agent. To reset file
 
 paul@999     96 
permissions, use the appropriate tool script:
 
 paul@999     97 
 
 paul@999     98 
{{{
 
 paul@999     99 
tools/fix.sh
 
 paul@999    100 
}}}
 
 paul@999    101 
 
 paul@989    102 
== Excluding Users Entirely ==
 
 paul@989    103 
 
 paul@989    104 
Since the [[../AgentPrograms|agent programs]] are installed as part of the mail
 
 paul@989    105 
handling workflow, even the configuration of non-participation in the calendar
 
 paul@989    106 
system for users will still result in those users' messages being passed along
 
 paul@989    107 
the workflow by imip-agent, which may result in a decrease in general mail
 
 paul@989    108 
delivery performance.
 
 paul@989    109 
 
 paul@989    110 
To exclude users entirely, the routing configuration of the
 
 paul@989    111 
[[../MailIntegration|MTA]] needs to be changed so that such users identities are
 
 paul@989    112 
not recognised as calendar system participants, thus preventing their messages
 
 paul@989    113 
from being routed via imip-agent. This is as simple as either not listing the
 
 paul@989    114 
identity in [[../MailIntegration/Simple|lists of addresses]] or by adjusting
 
 paul@989    115 
[[../MailIntegration/LDAP|queries yielding calendar users]].
 
 paul@1028    116 
 
 paul@1039    117 
== Adding Scheduling-Related Functions ==
 
 paul@1028    118 
 
 paul@1039    119 
The `confirmation_function`, `retraction_function` and `scheduling_function`
 
 paul@1039    120 
settings employ functions that reside within modules in the
 
 paul@1039    121 
`imiptools.handlers.scheduling` package. Extra modules can be installed in
 
 paul@1028    122 
this package by adding files to the `scheduling` directory within the software
 
 paul@1028    123 
installation.
 
 paul@1028    124 
 
 paul@1028    125 
After adding modules, a tool must be run to register the new modules:
 
 paul@1028    126 
 
 paul@1028    127 
{{{
 
 paul@1028    128 
tools/update_scheduling_modules.py
 
 paul@1028    129 
}}}
 
 paul@1028    130 
 
 paul@1028    131 
It is envisaged that the installation of additional scheduling modules and the
 
 paul@1028    132 
use of this tool will be performed by the packaging system provided by an
 
 paul@1039    133 
operating system distribution. The `tools/install.sh` script runs the above
 
 paul@1039    134 
tool as part of the installation process.