1.1 --- a/docs/wiki/Configuration Sun Apr 10 02:34:00 2016 +0200
1.2 +++ b/docs/wiki/Configuration Sun Apr 17 23:47:19 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,12 +93,7 @@
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 -
1.102 -== System-Level and Tool Configuration ==
1.103 +=== System-Level and Tool Configuration ===
1.104
1.105 The `config.sh` file must indicate choices in the following areas:
1.106
1.107 @@ -27,7 +106,26 @@
1.108 must be made to the file in the `tools/config.sh` location before installation
1.109 can occur.
1.110
1.111 -== Software Configuration ==
1.112 +{{{#!table
1.113 +'''Setting''' || '''Example Value''' || '''Description'''
1.114 +==
1.115 +`IMIP_AGENT_USER` || `imip-agent`
1.116 +||<rowspan="2"> Indicates the system user and group identity that is used
1.117 +.. to run the software and access resources, decided when choosing a
1.118 +.. strategy for [[../SystemUsers|system users and groups]]
1.119 +==
1.120 +`IMIP_AGENT_GROUP` || `lmtp`
1.121 +==
1.122 +`INSTALL_DIR` || `/var/lib/imip-agent`
1.123 +||<rowspan="3"> Installation locations for data, Web resources and
1.124 +.. configuration respectively
1.125 +==
1.126 +`WEB_INSTALL_DIR` || `/var/www/imip-agent`
1.127 +==
1.128 +`CONFIG_DIR` || `/etc/imip-agent`
1.129 +}}}
1.130 +
1.131 +=== Software Configuration ===
1.132
1.133 Any changes to filesystem locations may need to be incorporated into the
1.134 `config.py` file, which is found in the `imiptools/config.py` location of
1.135 @@ -40,7 +138,7 @@
1.136 and file permissions), service-level settings (e-mail address and Web site
1.137 choices), and default policies for users of the software.
1.138
1.139 -== User Preferences ==
1.140 +=== User Preferences ===
1.141
1.142 Although the software configuration in `config.py` provides default policies,
1.143 users can choose to override these defaults by editing their own preferences.