imip-agent

docs/wiki/Administration

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