# HG changeset patch # User Paul Boddie # Date 1460929249 -7200 # Node ID 692c89e110bb82ba15a8c676dea2d45f09a4f195 # Parent 4ba028a3683b9d7f56e7ad519daa37b8155ebaea Updated the documentation to describe the configuration tool and various settings in the integration-related and final configuration files. diff -r 4ba028a3683b -r 692c89e110bb docs/wiki/Configuration --- a/docs/wiki/Configuration Sun Apr 17 23:39:50 2016 +0200 +++ b/docs/wiki/Configuration Sun Apr 17 23:40:49 2016 +0200 @@ -1,5 +1,89 @@ = Configuration = +When deploying imip-agent, configuration of the way it integrates with +other software components must be performed. Once this has been done, +certain details are then carried forward into the configuration of imip-agent +itself. + +== Configuring the Integration == + +The `conf` directory provides a selection of template configuration files +for different software components that may integrate with imip-agent. To +simplify the process of customising these files, a helper tool is provided +to apply configuration choices and to generate configuration files that may +then be deployed within the configuration of these other components. + +Taking an example set of choices, the tool is run as follows: + +{{{ +conf/tools/configure.sh conf/configure.example outconf +}}} + +This will generate parameterised versions of several files within `conf` +and place them in a similar directory structure within the newly-created +directory `outconf`, using the settings found in `conf/configure.example`. + +It is recommended that the example definitions file be copied and edited, +and that each definition or choice in the new definitions file be adjusted +according to the specific needs of the deployment. A summary of the choices +are given below. + +{{{#!table +'''Choice''' || '''Example Value''' || '''Description''' +== +`MAIL_DOMAIN` || `example.com` +|| The mail domain for which imip-agent will be handling messages +== +`MAILBOX_DELIVERY` || `LocalSMTP` +|| How messages are delivered to mailboxes, either using `LocalSMTP` +.. ([[../MailIntegration/LocalSMTP|local SMTP]]) or `LMTP` +.. ([[../MailIntegration/LMTP|LMTP]]) mechanisms +== +`MAILBOX_DELIVERY_LMTP_GROUP` || `no` +|| Whether a special lmtp group will be used even with local SMTP, +.. as discussed in the [[../SystemUsers|system users and groups]] +.. documentation +== +`LMTP_SOCKET` || `/var/run/cyrus/socket/lmtp` +|| The location of the LMTP socket used to communicate with a mail +.. storage solution (if LMTP is employed) +== +`LOCAL_SYSTEM_USERS` || `no` +|| Whether local system users are supported, as described in the +.. [[../MailIntegration/LocalSMTP|local SMTP]] documentation. +== +`USER_DATABASE` || `Simple` +|| How the database of calendar users is managed, either using `Simple` +.. ([[../MailIntegration/Simple|simple]]) or `LDAP` +.. ([[../MailIntegration/LDAP|LDAP]]) mechanisms +== + ''LDAP-specific choices (for when calendar users are managed +using [[../MailIntegration/LDAP|LDAP]])'' +== +`LDAP_SCHEME` || `ldap` +|| LDAP access mechanism, either using `ldap` or `ldaps` +== +`LDAP_HOST` || `localhost` +|| LDAP server connection details, with the port being omitted +.. unless a non-standard port has been chosen +== +`LDAP_PORT` || +== +`LDAP_BASE_DN` || `"dc=example,dc=com"` +|| Search criteria used in the selection of calendar users +== +`LDAP_SERVICE_BIND_DN` || `"uid=imip-agent,ou=Special Users,dc=example,dc=com"` +|| Credentials for the identity employed by imip-agent to connect +.. to the LDAP server +== +`LDAP_SERVICE_PASSWORD` || +}}} + +The eventual destination of each of the customised files obviously depends on +the nature of the component such files will be configuring. + +== Configuring the Software Itself == + There are three levels of configuration in imip-agent: * `config.sh` provides system-level and tool configuration @@ -9,20 +93,35 @@ These files are by default installed into the `/etc/imip-agent` directory and they can be changed in that location once the system is installed. -{{{#!wiki tip -=== Text Encoding === -The textual encoding employed by the preferences files is UTF-8. -}}} +=== System-Level and Tool Configuration === -== System-Level and Tool Configuration == - -Given a choice of [[../SystemUsers|system users and groups]], the +Given a choice of [[../SystemUsers|system users and groups]], and the choices +made when configuring how imip-agent integrates with other components, the resulting configuration must be indicated in the `config.sh` file. Since the `tools/install.sh` script depends on this configuration, changes must be made to the file in the `tools/config.sh` location before installation can occur. -== Software Configuration == +{{{#!table +'''Setting''' || '''Example Value''' || '''Description''' +== +`IMIP_AGENT_USER` || `imip-agent` +|| Indicates the system user and group identity that is used +.. to run the software and access resources, decided when choosing a +.. strategy for [[../SystemUsers|system users and groups]] +== +`IMIP_AGENT_GROUP` || `lmtp` +== +`INSTALL_DIR` || `/var/lib/imip-agent` +|| Installation locations for data, Web resources and +.. configuration respectively +== +`WEB_INSTALL_DIR` || `/var/www/imip-agent` +== +`CONFIG_DIR` || `/etc/imip-agent` +}}} + +=== Software Configuration === Any changes to filesystem locations may need to be incorporated into the `config.py` file, which is found in the `imiptools/config.py` location of @@ -35,7 +134,7 @@ and file permissions), service-level settings (e-mail address and Web site choices), and default policies for users of the software. -== User Preferences == +=== User Preferences === Although the software configuration in `config.py` provides default policies, users can choose to override these defaults by editing their own preferences. diff -r 4ba028a3683b -r 692c89e110bb docs/wiki/GettingStarted --- a/docs/wiki/GettingStarted Sun Apr 17 23:39:50 2016 +0200 +++ b/docs/wiki/GettingStarted Sun Apr 17 23:40:49 2016 +0200 @@ -29,6 +29,10 @@ If you already use mail storage solutions that employ LMTP, you may decide to choose the [[../MailIntegration/LMTP|LMTP delivery]] approach. +Once you have decided which approach is the most preferable, you will be +able to use this choice to influence the configuration process mentioned +below. + == Installing the Software == Ideally, an operating system distribution package should be used to @@ -99,6 +103,16 @@ .. [[../MailboxIntegration|Mailbox Integration]] }}} +In addition, a `tools` directory provides a configuration helper tool +that can be used to quickly customise the above resources and produce +files that, after review, may be deployed. + +{{{ +conf/tools/configure.sh --help +}}} + +Use of this tool is covered in the [[../Configuration|configuration guide]]. + == Configuring the Software == The behaviour of the imip-agent software itself can be configured using diff -r 4ba028a3683b -r 692c89e110bb docs/wiki/Preferences --- a/docs/wiki/Preferences Sun Apr 17 23:39:50 2016 +0200 +++ b/docs/wiki/Preferences Sun Apr 17 23:40:49 2016 +0200 @@ -20,6 +20,11 @@ See the [[../Configuration|configuration guide]] for more information about the `config.py` file. +{{{#!wiki tip +=== Text Encoding === +The textual encoding employed by all preferences files is UTF-8. +}}} + == User Preference Settings == <> diff -r 4ba028a3683b -r 692c89e110bb docs/wiki/Prerequisites --- a/docs/wiki/Prerequisites Sun Apr 17 23:39:50 2016 +0200 +++ b/docs/wiki/Prerequisites Sun Apr 17 23:40:49 2016 +0200 @@ -32,6 +32,7 @@ Cyrus:: cyrus-imapd Dovecot:: dovecot-imapd dovecot-ldap dovecot-lmtpd -Some test programs need additional programs provided by other packages: +Some test programs and the configuration helper tool need additional programs +provided by other packages: envsubst:: gettext-base