1.1 --- a/docs/wiki/Configuration Sun Apr 17 23:39:50 2016 +0200
1.2 +++ b/docs/wiki/Configuration Sun Apr 17 23:40:49 2016 +0200
1.3 @@ -1,5 +1,89 @@
1.4 = Configuration =
1.5
1.6 +When deploying imip-agent, configuration of the way it integrates with
1.7 +other software components must be performed. Once this has been done,
1.8 +certain details are then carried forward into the configuration of imip-agent
1.9 +itself.
1.10 +
1.11 +== Configuring the Integration ==
1.12 +
1.13 +The `conf` directory provides a selection of template configuration files
1.14 +for different software components that may integrate with imip-agent. To
1.15 +simplify the process of customising these files, a helper tool is provided
1.16 +to apply configuration choices and to generate configuration files that may
1.17 +then be deployed within the configuration of these other components.
1.18 +
1.19 +Taking an example set of choices, the tool is run as follows:
1.20 +
1.21 +{{{
1.22 +conf/tools/configure.sh conf/configure.example outconf
1.23 +}}}
1.24 +
1.25 +This will generate parameterised versions of several files within `conf`
1.26 +and place them in a similar directory structure within the newly-created
1.27 +directory `outconf`, using the settings found in `conf/configure.example`.
1.28 +
1.29 +It is recommended that the example definitions file be copied and edited,
1.30 +and that each definition or choice in the new definitions file be adjusted
1.31 +according to the specific needs of the deployment. A summary of the choices
1.32 +are given below.
1.33 +
1.34 +{{{#!table
1.35 +'''Choice''' || '''Example Value''' || '''Description'''
1.36 +==
1.37 +`MAIL_DOMAIN` || `example.com`
1.38 +|| The mail domain for which imip-agent will be handling messages
1.39 +==
1.40 +`MAILBOX_DELIVERY` || `LocalSMTP`
1.41 +|| How messages are delivered to mailboxes, either using `LocalSMTP`
1.42 +.. ([[../MailIntegration/LocalSMTP|local SMTP]]) or `LMTP`
1.43 +.. ([[../MailIntegration/LMTP|LMTP]]) mechanisms
1.44 +==
1.45 +`MAILBOX_DELIVERY_LMTP_GROUP` || `no`
1.46 +|| Whether a special lmtp group will be used even with local SMTP,
1.47 +.. as discussed in the [[../SystemUsers|system users and groups]]
1.48 +.. documentation
1.49 +==
1.50 +`LMTP_SOCKET` || `/var/run/cyrus/socket/lmtp`
1.51 +|| The location of the LMTP socket used to communicate with a mail
1.52 +.. storage solution (if LMTP is employed)
1.53 +==
1.54 +`LOCAL_SYSTEM_USERS` || `no`
1.55 +|| Whether local system users are supported, as described in the
1.56 +.. [[../MailIntegration/LocalSMTP|local SMTP]] documentation.
1.57 +==
1.58 +`USER_DATABASE` || `Simple`
1.59 +|| How the database of calendar users is managed, either using `Simple`
1.60 +.. ([[../MailIntegration/Simple|simple]]) or `LDAP`
1.61 +.. ([[../MailIntegration/LDAP|LDAP]]) mechanisms
1.62 +==
1.63 +<colspan="3"> ''LDAP-specific choices (for when calendar users are managed
1.64 +using [[../MailIntegration/LDAP|LDAP]])''
1.65 +==
1.66 +`LDAP_SCHEME` || `ldap`
1.67 +|| LDAP access mechanism, either using `ldap` or `ldaps`
1.68 +==
1.69 +`LDAP_HOST` || `localhost`
1.70 +||<rowspan="2"> LDAP server connection details, with the port being omitted
1.71 +.. unless a non-standard port has been chosen
1.72 +==
1.73 +`LDAP_PORT` ||
1.74 +==
1.75 +`LDAP_BASE_DN` || `"dc=example,dc=com"`
1.76 +|| Search criteria used in the selection of calendar users
1.77 +==
1.78 +`LDAP_SERVICE_BIND_DN` || `"uid=imip-agent,ou=Special Users,dc=example,dc=com"`
1.79 +||<rowspan="2"> Credentials for the identity employed by imip-agent to connect
1.80 +.. to the LDAP server
1.81 +==
1.82 +`LDAP_SERVICE_PASSWORD` ||
1.83 +}}}
1.84 +
1.85 +The eventual destination of each of the customised files obviously depends on
1.86 +the nature of the component such files will be configuring.
1.87 +
1.88 +== Configuring the Software Itself ==
1.89 +
1.90 There are three levels of configuration in imip-agent:
1.91
1.92 * `config.sh` provides system-level and tool configuration
1.93 @@ -9,20 +93,35 @@
1.94 These files are by default installed into the `/etc/imip-agent` directory
1.95 and they can be changed in that location once the system is installed.
1.96
1.97 -{{{#!wiki tip
1.98 -=== Text Encoding ===
1.99 -The textual encoding employed by the preferences files is UTF-8.
1.100 -}}}
1.101 +=== System-Level and Tool Configuration ===
1.102
1.103 -== System-Level and Tool Configuration ==
1.104 -
1.105 -Given a choice of [[../SystemUsers|system users and groups]], the
1.106 +Given a choice of [[../SystemUsers|system users and groups]], and the choices
1.107 +made when configuring how imip-agent integrates with other components, the
1.108 resulting configuration must be indicated in the `config.sh` file. Since
1.109 the `tools/install.sh` script depends on this configuration, changes must
1.110 be made to the file in the `tools/config.sh` location before installation
1.111 can occur.
1.112
1.113 -== Software Configuration ==
1.114 +{{{#!table
1.115 +'''Setting''' || '''Example Value''' || '''Description'''
1.116 +==
1.117 +`IMIP_AGENT_USER` || `imip-agent`
1.118 +||<rowspan="2"> Indicates the system user and group identity that is used
1.119 +.. to run the software and access resources, decided when choosing a
1.120 +.. strategy for [[../SystemUsers|system users and groups]]
1.121 +==
1.122 +`IMIP_AGENT_GROUP` || `lmtp`
1.123 +==
1.124 +`INSTALL_DIR` || `/var/lib/imip-agent`
1.125 +||<rowspan="3"> Installation locations for data, Web resources and
1.126 +.. configuration respectively
1.127 +==
1.128 +`WEB_INSTALL_DIR` || `/var/www/imip-agent`
1.129 +==
1.130 +`CONFIG_DIR` || `/etc/imip-agent`
1.131 +}}}
1.132 +
1.133 +=== Software Configuration ===
1.134
1.135 Any changes to filesystem locations may need to be incorporated into the
1.136 `config.py` file, which is found in the `imiptools/config.py` location of
1.137 @@ -35,7 +134,7 @@
1.138 and file permissions), service-level settings (e-mail address and Web site
1.139 choices), and default policies for users of the software.
1.140
1.141 -== User Preferences ==
1.142 +=== User Preferences ===
1.143
1.144 Although the software configuration in `config.py` provides default policies,
1.145 users can choose to override these defaults by editing their own preferences.