imip-agent

Annotated docs/wiki/Administration

1384:9baa0aae5b43
1216:d2c6bd93269a
2017-10-31 Paul Boddie file changeset files shortlog Provided a convenience function for instantiating handler objects. Added a mode that produces output instead of sending messages without also producing debugging information. client-editing-simplification
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@1061    119 
The `scheduling_function` setting employs functions that reside within modules
 
 paul@1061    120 
in the `imiptools.handlers.scheduling` package. Extra modules can be installed
 
 paul@1061    121 
in this package by adding files to the `scheduling` directory within the
 
 paul@1061    122 
software installation.
 
 paul@1028    123 
 
 paul@1206    124 
== Adding Storage Modules ==
 
 paul@1206    125 
 
 paul@1206    126 
Storage modules reside in the `imiptools.stores` package. Extra modules can be
 
 paul@1216    127 
installed in this package by adding files or directories to the `stores` 
 
 paul@1206    128 
directory within the software installation.
 
 paul@1206    129 
 
 paul@1149    130 
== Copying Stores and Changing Store Types ==
 
 paul@1149    131 
 
 paul@1149    132 
A rudimentary tool is provided that can copy data between stores, even those of
 
 paul@1149    133 
different types, thus allowing the migration of data from one kind of store to
 
 paul@1149    134 
another. Although it does not perform the copying in the most efficient manner,
 
 paul@1149    135 
it provides a convenient method of copying that uses the software's own general
 
 paul@1149    136 
interfaces for store access and thus acts as a way of verifying that these are
 
 paul@1149    137 
functioning correctly.
 
 paul@1149    138 
 
 paul@1149    139 
To copy a configured store to another filesystem location:
 
 paul@1149    140 
 
 paul@1149    141 
{{{
 
 paul@1149    142 
tools/copy_store.py -t file /tmp/store /tmp/journal
 
 paul@1149    143 
}}}
 
 paul@1149    144 
 
 paul@1149    145 
To copy a configured store to a database (which must have been initialised):
 
 paul@1149    146 
 
 paul@1149    147 
{{{
 
 paul@1149    148 
tools/copy_store.py -t postgresql 'dbname=store' 'dbname=journal'
 
 paul@1149    149 
}}}
 
 paul@1149    150 
 
 paul@1149    151 
To copy an explicitly-specified file store to another filesystem location:
 
 paul@1149    152 
 
 paul@1149    153 
{{{
 
 paul@1149    154 
tools/copy_store.py \
 
 paul@1149    155 
  -f file /var/lib/imip-agent/store /var/lib/imip-agent/journal \
 
 paul@1149    156 
  -t file /tmp/store /tmp/journal
 
 paul@1149    157 
}}}
 
 paul@1149    158 
 
 paul@1149    159 
The help message for the tool provides general guidance for its use:
 
 paul@1149    160 
 
 paul@1149    161 
{{{
 
 paul@1149    162 
tools/copy_store.py --help
 
 paul@1149    163 
}}}