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 After adding modules, a tool must be run to register the new modules: 125 126 {{{ 127 tools/update_scheduling_modules.py 128 }}} 129 130 It is envisaged that the installation of additional scheduling modules and the 131 use of this tool will be performed by the packaging system provided by an 132 operating system distribution. The `tools/install.sh` script runs the above 133 tool as part of the installation process.