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