1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/docs/wiki/Administration Tue Nov 03 18:09:26 2015 +0100
1.3 @@ -0,0 +1,93 @@
1.4 += Administering imip-agent =
1.5 +
1.6 +With imip-agent deployed, usage of the software should occur automatically.
1.7 +However, evidence of its operation will only emerge when calendar-related
1.8 +messages are exchanged between e-mail users. This will cause a few different
1.9 +things to happen:
1.10 +
1.11 + * Summary messages may be sent by the calendar system to mail recipients
1.12 +
1.13 + * Replies to calendar-related messages may be received by the senders of
1.14 + those messages
1.15 +
1.16 + * Free/busy information will become available, either in responses to
1.17 + requests sent over e-mail, or [[../FreeBusyPublishing|over the Web]]
1.18 +
1.19 +In the background, imip-agent uses and updates information as described in the
1.20 +[[../FilesystemUsage|filesystem usage guide]].
1.21 +
1.22 +== Creating User Data Stores ==
1.23 +
1.24 +The [[../MailIntegration|mail system]] mechanisms are responsible for
1.25 +determining whether a valid recipient has been specified in any given message,
1.26 +and imip-agent does not attempt to validate such information again. Therefore,
1.27 +when a message is received for a calendar user for whom no data store has been
1.28 +initialised in the [[../FilesystemUsage|filesystem]], the software will
1.29 +automatically create one.
1.30 +
1.31 +Consequently, users for whom such data stores have been created will experience
1.32 +the software using the default configuration, described in the
1.33 +[[../Preferences|preferences guide]]. It is for this reason that the default
1.34 +values in the [[../Configuration|configuration]] should be adjusted according
1.35 +to the policies decided for the deployment of this software.
1.36 +
1.37 +However, it is possible to create data stores for users in advance using the
1.38 +`tools/init_user.sh` script as in the following example:
1.39 +
1.40 +{{{
1.41 +tools/init_user.sh mailto:vincent.vole@example.com
1.42 +}}}
1.43 +
1.44 +Here, the user identity is given as a URI since this is how iCalendar references
1.45 +participants in scheduling operations. The result of the above command should be
1.46 +some new directories in the [[../FilesystemUsage|filesystem area]] dedicated to
1.47 +calendar information storage.
1.48 +
1.49 +=== Initialising Resources ===
1.50 +
1.51 +Resources belong to a class of user whose preferences should be configured in
1.52 +advance because their policies may differ on a case-by-case basis. For example,
1.53 +some resources may benefit from employing the `permitted_times` setting so that
1.54 +a granularity on event times may be imposed, meaning that such resources would
1.55 +be "handed over" at regular intervals.
1.56 +
1.57 +The `freebusy_offers` setting, together with the `scheduling_function` setting,
1.58 +would allow different kinds of resources to "keep open" tentatively-suggested
1.59 +periods for different lengths of time, allowing frequently-requested resources
1.60 +to respond to scheduling requests in a timely fashion, whilst also allowing
1.61 +other resources to give more time to event organisers to respond to their
1.62 +counter-proposals.
1.63 +
1.64 +=== Adjusting Preferences ===
1.65 +
1.66 +Once initialised, the user preferences can be adjusted by adding files to the
1.67 +`preferences` directory created by the above command. For example, if a user has
1.68 +elected to not participate in the calendar system, a file called `participating`
1.69 +can be added as follows:
1.70 +
1.71 +{{{
1.72 +echo 'no' > '/var/lib/imip-agent/preferences/mailto:vincent.vole@example.com/participating'
1.73 +}}}
1.74 +
1.75 +Here, the default storage location has been given in the filename.
1.76 +
1.77 +Normally, users should visit the [[../CalendarManager|management interface]] to
1.78 +change their preferences, but modifications done by administrators are more
1.79 +efficiently performed by directly interacting with the filesystem. For example,
1.80 +an administrator might initialise the common names of users by scripting changes
1.81 +to the `CN` file for each user, obtaining such names from some kind of database.
1.82 +
1.83 +== Excluding Users Entirely ==
1.84 +
1.85 +Since the [[../AgentPrograms|agent programs]] are installed as part of the mail
1.86 +handling workflow, even the configuration of non-participation in the calendar
1.87 +system for users will still result in those users' messages being passed along
1.88 +the workflow by imip-agent, which may result in a decrease in general mail
1.89 +delivery performance.
1.90 +
1.91 +To exclude users entirely, the routing configuration of the
1.92 +[[../MailIntegration|MTA]] needs to be changed so that such users identities are
1.93 +not recognised as calendar system participants, thus preventing their messages
1.94 +from being routed via imip-agent. This is as simple as either not listing the
1.95 +identity in [[../MailIntegration/Simple|lists of addresses]] or by adjusting
1.96 +[[../MailIntegration/LDAP|queries yielding calendar users]].