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 === Adjusting Preferences === 73 74 Once initialised, the user preferences can be adjusted by adding files to the 75 `preferences` directory created by the above command. For example, if a user has 76 elected to not participate in the calendar system, a file called `participating` 77 can be added as follows: 78 79 {{{ 80 echo 'no' > '/var/lib/imip-agent/preferences/mailto:vincent.vole@example.com/participating' 81 }}} 82 83 Here, the default storage location has been given in the filename. 84 85 Normally, users should visit the [[../CalendarManager|management interface]] to 86 change their preferences, but modifications done by administrators are more 87 efficiently performed by directly interacting with the filesystem. For example, 88 an administrator might initialise the common names of users by scripting changes 89 to the `CN` file for each user, obtaining such names from some kind of database. 90 91 The permissions on any created files must be consistent with those defined when 92 configuring the [[../SystemUsers|system users]] for imip-agent. To reset file 93 permissions, use the appropriate tool script: 94 95 {{{ 96 tools/fix.sh 97 }}} 98 99 == Excluding Users Entirely == 100 101 Since the [[../AgentPrograms|agent programs]] are installed as part of the mail 102 handling workflow, even the configuration of non-participation in the calendar 103 system for users will still result in those users' messages being passed along 104 the workflow by imip-agent, which may result in a decrease in general mail 105 delivery performance. 106 107 To exclude users entirely, the routing configuration of the 108 [[../MailIntegration|MTA]] needs to be changed so that such users identities are 109 not recognised as calendar system participants, thus preventing their messages 110 from being routed via imip-agent. This is as simple as either not listing the 111 identity in [[../MailIntegration/Simple|lists of addresses]] or by adjusting 112 [[../MailIntegration/LDAP|queries yielding calendar users]]. 113 114 == Adding Scheduling Functions == 115 116 The `scheduling_function` setting employs functions that reside within modules in 117 the `imiptools.handlers.scheduling` package. Extra modules can be installed in 118 this package by adding files to the `scheduling` directory within the software 119 installation. 120 121 After adding modules, a tool must be run to register the new modules: 122 123 {{{ 124 tools/update_scheduling_modules.py 125 }}} 126 127 It is envisaged that the installation of additional scheduling modules and the 128 use of this tool will be performed by the packaging system provided by an 129 operating system distribution.