1 = Configuration = 2 3 When deploying imip-agent, configuration of the way it integrates with 4 other software components must be performed. Once this has been done, 5 certain details are then carried forward into the configuration of imip-agent 6 itself. 7 8 == Configuring the Integration == 9 10 The `conf` directory provides a selection of template configuration files 11 for different software components that may integrate with imip-agent. To 12 simplify the process of customising these files, a helper tool is provided 13 to apply configuration choices and to generate configuration files that may 14 then be deployed within the configuration of these other components. 15 16 Taking an example set of choices, the tool is run as follows: 17 18 {{{ 19 conf/tools/configure.sh conf/configure.example outconf 20 }}} 21 22 This will generate parameterised versions of several files within `conf` 23 and place them in a similar directory structure within the newly-created 24 directory `outconf`, using the settings found in `conf/configure.example`. 25 26 It is recommended that the example definitions file be copied and edited, 27 and that each definition or choice in the new definitions file be adjusted 28 according to the specific needs of the deployment. A summary of the choices 29 are given below. 30 31 {{{#!table 32 '''Choice''' || '''Example Value''' || '''Description''' 33 == 34 `MAIL_DOMAIN` || `example.com` 35 || The mail domain for which imip-agent will be handling messages 36 == 37 `MAILBOX_DELIVERY` || `LocalSMTP` 38 || How messages are delivered to mailboxes, either using `LocalSMTP` 39 .. ([[../MailIntegration/LocalSMTP|local SMTP]]) or `LMTP` 40 .. ([[../MailIntegration/LMTP|LMTP]]) mechanisms 41 == 42 `MAILBOX_DELIVERY_LMTP_GROUP` || `no` 43 || Whether a special lmtp group will be used even with local SMTP, 44 .. as discussed in the [[../SystemUsers|system users and groups]] 45 .. documentation 46 == 47 `LMTP_SOCKET` || `/var/run/cyrus/socket/lmtp` 48 || The location of the LMTP socket used to communicate with a mail 49 .. storage solution (if LMTP is employed) 50 == 51 `LOCAL_SYSTEM_USERS` || `no` 52 || Whether local system users are supported, as described in the 53 .. [[../MailIntegration/LocalSMTP|local SMTP]] documentation. 54 == 55 `USER_DATABASE` || `Simple` 56 || How the database of calendar users is managed, either using `Simple` 57 .. ([[../MailIntegration/Simple|simple]]) or `LDAP` 58 .. ([[../MailIntegration/LDAP|LDAP]]) mechanisms 59 == 60 <colspan="3"> ''LDAP-specific choices (for when calendar users are managed 61 using [[../MailIntegration/LDAP|LDAP]])'' 62 == 63 `LDAP_SCHEME` || `ldap` 64 || LDAP access mechanism, either using `ldap` or `ldaps` 65 == 66 `LDAP_HOST` || `localhost` 67 ||<rowspan="2"> LDAP server connection details, with the port being omitted 68 .. unless a non-standard port has been chosen 69 == 70 `LDAP_PORT` || 71 == 72 `LDAP_BASE_DN` || `"dc=example,dc=com"` 73 || Search criteria used in the selection of calendar users 74 == 75 `LDAP_SERVICE_BIND_DN` || `"uid=imip-agent,ou=Special Users,dc=example,dc=com"` 76 ||<rowspan="2"> Credentials for the identity employed by imip-agent to connect 77 .. to the LDAP server 78 == 79 `LDAP_SERVICE_PASSWORD` || 80 }}} 81 82 The eventual destination of each of the customised files obviously depends on 83 the nature of the component such files will be configuring. 84 85 == Configuring the Software Itself == 86 87 There are three levels of configuration in imip-agent: 88 89 * `config.sh` provides system-level and tool configuration 90 * `config.txt` provides the configuration of the software itself 91 * User preferences reside as files in separate user-specific directories 92 93 The `config` files are by default installed into the `/etc/imip-agent` directory 94 and they can be changed in that location once the system is installed. User 95 preferences can be configured directly in the filesystem or can be edited in the 96 [[../CalendarManager|management interface]] by each user. 97 98 === System-Level and Tool Configuration === 99 100 The `config.sh` file must indicate choices in the following areas: 101 102 * The [[../DataStore|data store]] type to be employed 103 104 * The [[../SystemUsers|system users and groups]] involved with running the 105 software and storing data 106 107 Since the `tools/install.sh` script depends on this configuration, changes 108 must be made to the file in the `tools/config.sh` location before installation 109 can occur. 110 111 {{{#!table 112 '''Setting''' || '''Example Value''' || '''Description''' 113 == 114 `IMIP_AGENT_USER` || `imip-agent` 115 ||<rowspan="2"> Indicates the system user and group identity that is used 116 .. to run the software and access resources, decided when choosing a 117 .. strategy for [[../SystemUsers|system users and groups]] 118 == 119 `IMIP_AGENT_GROUP` || `lmtp` 120 == 121 `INSTALL_DIR` || `/var/lib/imip-agent` 122 ||<rowspan="3"> Installation locations for data, Web resources and 123 .. configuration respectively 124 == 125 `WEB_INSTALL_DIR` || `/var/www/imip-agent` 126 == 127 `CONFIG_DIR` || `/etc/imip-agent` 128 }}} 129 130 === Software Configuration === 131 132 Any changes to filesystem locations may need to be incorporated into the 133 `config.txt` file, which is found in the `imiptools/config.txt` location of 134 the distribution. There is, however, no urgency in changing this file 135 before installation, and it can be edited in its installed location to 136 achieve the same effects. 137 138 The agent system configuration dictates how the software behaves, and the 139 `config.txt` file provides system-level settings (filesystem locations 140 and file permissions), service-level settings (e-mail address and Web site 141 choices), and default policies for users of the software. 142 143 The syntax of `config.txt` is the same as Python, but only simple value 144 assignments can be defined, along with comments. Strings must appear within 145 quotes and thus numbers, boolean values and strings can be expressed. The 146 following examples employ necessary quoting. 147 148 {{{#!table 149 '''Setting''' || '''Example Value''' || '''Description''' 150 == 151 `MESSAGE_SENDER` || `"calendar@example.com"` 152 || The address from which messages sent by the agent originate 153 == 154 `LOCAL_PREFIX` || `"local"` 155 || The prefix employed by the mail system to identify local recipients 156 == 157 `OUTGOING_PREFIX` || `"people-outgoing"` 158 || The prefix employed by the mail system to identify local recipients 159 .. being the senders of outgoing messages 160 == 161 `STORE_TYPE` || `"file"` 162 || The store and journal type 163 == 164 `STORE_DIR` || `"/var/lib/imip-agent/store"` 165 || The location of the stored calendar information, defined in a form 166 .. appropriate to the selected `STORE_TYPE` 167 == 168 `PUBLISH_DIR` || `"/var/www/imip-agent/static"` 169 || The location of published static free/busy information, which if 170 .. given as `None` will cause any such publishing to be disabled 171 == 172 `PREFERENCES_DIR` || `"/var/lib/imip-agent/preferences"` 173 || The location of user preferences information 174 == 175 `JOURNAL_DIR` || `"/var/lib/imip-agent/journal"` 176 || The location of quota-related journal information 177 == 178 `DEFAULT_PERMISSIONS` || `0660` 179 || The octal permission flags for files accessed by Web users and the 180 .. agent programs 181 == 182 `DEFAULT_DIR_PERMISSIONS` || `02770` 183 || The octal permission flags for directories, intended to preserve 184 .. group ownership 185 == 186 `LOCALE_DIR` || `"/usr/share/locale"` 187 || The location of message translations on the system 188 == 189 `TRANS_DOMAIN` || `"imip-agent"` 190 || The name of the application used to find message translations 191 == 192 `MANAGER_INTERFACE` || `True` 193 || Advertise the Web management interface in mails sent to calendar users 194 == 195 `MANAGER_PATH` || `"/imip-manager"` 196 || The server-relative path at which the management interface is deployed 197 .. in the Web server environment 198 == 199 `MANAGER_URL` || `None` 200 || The full URL of the manager application excluding the above path, 201 .. used to provide specific hostname details instead of those deduced from 202 .. the environment (when set to None) 203 == 204 `MANAGER_URL_SCHEME` || `"http://"` 205 || The protocol scheme used if constructing URLs 206 }}} 207 208 === User Preferences === 209 210 Although the software configuration in `config.txt` provides default policies, 211 users can choose to override these defaults by editing their own preferences. 212 The most convenient way of doing this is to use the profile page provided by 213 the [[../CalendarManager|management interface]]. 214 215 The settings for the different policies are described in the 216 [[../Preferences|preferences guide]].