imip-agent

Annotated docs/wiki/Configuration

1285:4af5f81f5301
1362:d96b4761e6f0
1214:3bc482b5f33e
2017-10-24 Paul Boddie file changeset files shortlog Remove superfluous result collection slicing and count method parameter.
paul@955 1 
= Configuration =
paul@955 2 
 
 paul@1112      3 
When deploying imip-agent, configuration of the way it integrates with
 
 paul@1112      4 
other software components must be performed. Once this has been done,
 
 paul@1112      5 
certain details are then carried forward into the configuration of imip-agent
 
 paul@1112      6 
itself.
 
 paul@1112      7 
 
 paul@1112      8 
== Configuring the Integration ==
 
 paul@1112      9 
 
 paul@1112     10 
The `conf` directory provides a selection of template configuration files
 
 paul@1112     11 
for different software components that may integrate with imip-agent. To
 
 paul@1112     12 
simplify the process of customising these files, a helper tool is provided
 
 paul@1112     13 
to apply configuration choices and to generate configuration files that may
 
 paul@1112     14 
then be deployed within the configuration of these other components.
 
 paul@1112     15 
 
 paul@1112     16 
Taking an example set of choices, the tool is run as follows:
 
 paul@1112     17 
 
 paul@1112     18 
{{{
 
 paul@1112     19 
conf/tools/configure.sh conf/configure.example outconf
 
 paul@1112     20 
}}}
 
 paul@1112     21 
 
 paul@1112     22 
This will generate parameterised versions of several files within `conf`
 
 paul@1112     23 
and place them in a similar directory structure within the newly-created
 
 paul@1112     24 
directory `outconf`, using the settings found in `conf/configure.example`.
 
 paul@1112     25 
 
 paul@1112     26 
It is recommended that the example definitions file be copied and edited,
 
 paul@1112     27 
and that each definition or choice in the new definitions file be adjusted
 
 paul@1112     28 
according to the specific needs of the deployment. A summary of the choices
 
 paul@1112     29 
are given below.
 
 paul@1112     30 
 
 paul@1112     31 
{{{#!table
 
 paul@1112     32 
'''Choice''' || '''Example Value''' || '''Description'''
 
 paul@1112     33 
==
 
 paul@1112     34 
`MAIL_DOMAIN` || `example.com`
 
 paul@1112     35 
|| The mail domain for which imip-agent will be handling messages
 
 paul@1112     36 
==
 
 paul@1112     37 
`MAILBOX_DELIVERY` || `LocalSMTP`
 
 paul@1112     38 
|| How messages are delivered to mailboxes, either using `LocalSMTP`
 
 paul@1112     39 
.. ([[../MailIntegration/LocalSMTP|local SMTP]]) or `LMTP`
 
 paul@1112     40 
.. ([[../MailIntegration/LMTP|LMTP]]) mechanisms
 
 paul@1112     41 
==
 
 paul@1112     42 
`MAILBOX_DELIVERY_LMTP_GROUP` || `no`
 
 paul@1112     43 
|| Whether a special lmtp group will be used even with local SMTP,
 
 paul@1112     44 
.. as discussed in the [[../SystemUsers|system users and groups]]
 
 paul@1112     45 
.. documentation
 
 paul@1112     46 
==
 
 paul@1112     47 
`LMTP_SOCKET` || `/var/run/cyrus/socket/lmtp`
 
 paul@1112     48 
|| The location of the LMTP socket used to communicate with a mail
 
 paul@1112     49 
.. storage solution (if LMTP is employed)
 
 paul@1112     50 
==
 
 paul@1112     51 
`LOCAL_SYSTEM_USERS` || `no`
 
 paul@1112     52 
|| Whether local system users are supported, as described in the
 
 paul@1112     53 
.. [[../MailIntegration/LocalSMTP|local SMTP]] documentation.
 
 paul@1112     54 
==
 
 paul@1112     55 
`USER_DATABASE` || `Simple`
 
 paul@1112     56 
|| How the database of calendar users is managed, either using `Simple`
 
 paul@1112     57 
.. ([[../MailIntegration/Simple|simple]]) or `LDAP`
 
 paul@1112     58 
.. ([[../MailIntegration/LDAP|LDAP]]) mechanisms
 
 paul@1112     59 
==
 
 paul@1112     60 
<colspan="3"> ''LDAP-specific choices (for when calendar users are managed
 
 paul@1112     61 
using [[../MailIntegration/LDAP|LDAP]])''
 
 paul@1112     62 
==
 
 paul@1112     63 
`LDAP_SCHEME` || `ldap`
 
 paul@1112     64 
|| LDAP access mechanism, either using `ldap` or `ldaps`
 
 paul@1112     65 
==
 
 paul@1112     66 
`LDAP_HOST` || `localhost`
 
 paul@1112     67 
||<rowspan="2"> LDAP server connection details, with the port being omitted
 
 paul@1112     68 
.. unless a non-standard port has been chosen
 
 paul@1112     69 
==
 
 paul@1112     70 
`LDAP_PORT` ||
 
 paul@1112     71 
==
 
 paul@1112     72 
`LDAP_BASE_DN` || `"dc=example,dc=com"`
 
 paul@1112     73 
|| Search criteria used in the selection of calendar users
 
 paul@1112     74 
==
 
 paul@1112     75 
`LDAP_SERVICE_BIND_DN` || `"uid=imip-agent,ou=Special Users,dc=example,dc=com"`
 
 paul@1112     76 
||<rowspan="2"> Credentials for the identity employed by imip-agent to connect
 
 paul@1112     77 
.. to the LDAP server
 
 paul@1112     78 
==
 
 paul@1112     79 
`LDAP_SERVICE_PASSWORD` ||
 
 paul@1112     80 
}}}
 
 paul@1112     81 
 
 paul@1112     82 
The eventual destination of each of the customised files obviously depends on
 
 paul@1112     83 
the nature of the component such files will be configuring.
 
 paul@1112     84 
 
 paul@1112     85 
== Configuring the Software Itself ==
 
 paul@1112     86 
 
 paul@961     87 
There are three levels of configuration in imip-agent:
 
 paul@955     88 
 
 paul@955     89 
 * `config.sh` provides system-level and tool configuration
 
 paul@1214     90 
 * `config.txt` provides the configuration of the software itself
 
 paul@961     91 
 * User preferences reside as files in separate user-specific directories
 
 paul@955     92 
 
 paul@955     93 
These files are by default installed into the `/etc/imip-agent` directory
 
 paul@955     94 
and they can be changed in that location once the system is installed.
 
 paul@955     95 
 
 paul@1112     96 
=== System-Level and Tool Configuration ===
 
 paul@999     97 
 
 paul@1093     98 
The `config.sh` file must indicate choices in the following areas:
 
 paul@1093     99 
 
 paul@1093    100 
 * The [[../DataStore|data store]] type to be employed
 
 paul@1093    101 
 
 paul@1093    102 
 * The [[../SystemUsers|system users and groups]] involved with running the
 
 paul@1093    103 
 software and storing data
 
 paul@1093    104 
 
 paul@1093    105 
Since the `tools/install.sh` script depends on this configuration, changes
 
 paul@1093    106 
must be made to the file in the `tools/config.sh` location before installation
 
 paul@955    107 
can occur.
 
 paul@955    108 
 
 paul@1112    109 
{{{#!table
 
 paul@1112    110 
'''Setting''' || '''Example Value''' || '''Description'''
 
 paul@1112    111 
==
 
 paul@1112    112 
`IMIP_AGENT_USER` || `imip-agent`
 
 paul@1112    113 
||<rowspan="2"> Indicates the system user and group identity that is used
 
 paul@1112    114 
.. to run the software and access resources, decided when choosing a
 
 paul@1112    115 
.. strategy for [[../SystemUsers|system users and groups]]
 
 paul@1112    116 
==
 
 paul@1112    117 
`IMIP_AGENT_GROUP` || `lmtp`
 
 paul@1112    118 
==
 
 paul@1112    119 
`INSTALL_DIR` || `/var/lib/imip-agent`
 
 paul@1112    120 
||<rowspan="3"> Installation locations for data, Web resources and
 
 paul@1112    121 
.. configuration respectively
 
 paul@1112    122 
==
 
 paul@1112    123 
`WEB_INSTALL_DIR` || `/var/www/imip-agent`
 
 paul@1112    124 
==
 
 paul@1112    125 
`CONFIG_DIR` || `/etc/imip-agent`
 
 paul@1112    126 
}}}
 
 paul@1112    127 
 
 paul@1112    128 
=== Software Configuration ===
 
 paul@955    129 
 
 paul@955    130 
Any changes to filesystem locations may need to be incorporated into the
 
 paul@1214    131 
`config.txt` file, which is found in the `imiptools/config.txt` location of
 
 paul@955    132 
the distribution. There is, however, no urgency in changing this file
 
 paul@955    133 
before installation, and it can be edited in its installed location to
 
 paul@955    134 
achieve the same effects.
 
 paul@955    135 
 
 paul@955    136 
The agent system configuration dictates how the software behaves, and the
 
 paul@1214    137 
`config.txt` file provides system-level settings (filesystem locations
 
 paul@955    138 
and file permissions), service-level settings (e-mail address and Web site
 
 paul@955    139 
choices), and default policies for users of the software.
 
 paul@961    140 
 
 paul@1112    141 
=== User Preferences ===
 
 paul@961    142 
 
 paul@1214    143 
Although the software configuration in `config.txt` provides default policies,
 
 paul@961    144 
users can choose to override these defaults by editing their own preferences.
 
 paul@961    145 
The most convenient way of doing this is to use the profile page provided by
 
 paul@961    146 
the [[../CalendarManager|management interface]].
 
 paul@961    147 
 
 paul@961    148 
The settings for the different policies are described in the
 
 paul@961    149 
[[../Preferences|preferences guide]].