imip-agent

Annotated docs/wiki/Configuration

1334:f490ac87ee22
1285:4af5f81f5301
2017-10-17 Paul Boddie file changeset files shortlog Fixed debugging output. client-editing-simplification
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@1285     93 
The `config` files are by default installed into the `/etc/imip-agent` directory
 
 paul@1285     94 
and they can be changed in that location once the system is installed. User
 
 paul@1285     95 
preferences can be configured directly in the filesystem or can be edited in the
 
 paul@1285     96 
[[../CalendarManager|management interface]] by each user.
 
 paul@955     97 
 
 paul@1112     98 
=== System-Level and Tool Configuration ===
 
 paul@999     99 
 
 paul@1093    100 
The `config.sh` file must indicate choices in the following areas:
 
 paul@1093    101 
 
 paul@1093    102 
 * The [[../DataStore|data store]] type to be employed
 
 paul@1093    103 
 
 paul@1093    104 
 * The [[../SystemUsers|system users and groups]] involved with running the
 
 paul@1093    105 
 software and storing data
 
 paul@1093    106 
 
 paul@1093    107 
Since the `tools/install.sh` script depends on this configuration, changes
 
 paul@1093    108 
must be made to the file in the `tools/config.sh` location before installation
 
 paul@955    109 
can occur.
 
 paul@955    110 
 
 paul@1112    111 
{{{#!table
 
 paul@1112    112 
'''Setting''' || '''Example Value''' || '''Description'''
 
 paul@1112    113 
==
 
 paul@1112    114 
`IMIP_AGENT_USER` || `imip-agent`
 
 paul@1112    115 
||<rowspan="2"> Indicates the system user and group identity that is used
 
 paul@1112    116 
.. to run the software and access resources, decided when choosing a
 
 paul@1112    117 
.. strategy for [[../SystemUsers|system users and groups]]
 
 paul@1112    118 
==
 
 paul@1112    119 
`IMIP_AGENT_GROUP` || `lmtp`
 
 paul@1112    120 
==
 
 paul@1112    121 
`INSTALL_DIR` || `/var/lib/imip-agent`
 
 paul@1112    122 
||<rowspan="3"> Installation locations for data, Web resources and
 
 paul@1112    123 
.. configuration respectively
 
 paul@1112    124 
==
 
 paul@1112    125 
`WEB_INSTALL_DIR` || `/var/www/imip-agent`
 
 paul@1112    126 
==
 
 paul@1112    127 
`CONFIG_DIR` || `/etc/imip-agent`
 
 paul@1112    128 
}}}
 
 paul@1112    129 
 
 paul@1112    130 
=== Software Configuration ===
 
 paul@955    131 
 
 paul@955    132 
Any changes to filesystem locations may need to be incorporated into the
 
 paul@1214    133 
`config.txt` file, which is found in the `imiptools/config.txt` location of
 
 paul@955    134 
the distribution. There is, however, no urgency in changing this file
 
 paul@955    135 
before installation, and it can be edited in its installed location to
 
 paul@955    136 
achieve the same effects.
 
 paul@955    137 
 
 paul@955    138 
The agent system configuration dictates how the software behaves, and the
 
 paul@1214    139 
`config.txt` file provides system-level settings (filesystem locations
 
 paul@955    140 
and file permissions), service-level settings (e-mail address and Web site
 
 paul@955    141 
choices), and default policies for users of the software.
 
 paul@961    142 
 
 paul@1285    143 
The syntax of `config.txt` is the same as Python, but only simple value
 
 paul@1285    144 
assignments can be defined, along with comments. Strings must appear within
 
 paul@1285    145 
quotes and thus numbers, boolean values and strings can be expressed. The
 
 paul@1285    146 
following examples employ necessary quoting.
 
 paul@1285    147 
 
 paul@1285    148 
{{{#!table
 
 paul@1285    149 
'''Setting''' || '''Example Value''' || '''Description'''
 
 paul@1285    150 
==
 
 paul@1285    151 
`MESSAGE_SENDER` || `"calendar@example.com"`
 
 paul@1285    152 
|| The address from which messages sent by the agent originate
 
 paul@1285    153 
==
 
 paul@1285    154 
`LOCAL_PREFIX` || `"local"`
 
 paul@1285    155 
|| The prefix employed by the mail system to identify local recipients
 
 paul@1285    156 
==
 
 paul@1285    157 
`OUTGOING_PREFIX` || `"people-outgoing"`
 
 paul@1285    158 
|| The prefix employed by the mail system to identify local recipients
 
 paul@1285    159 
.. being the senders of outgoing messages
 
 paul@1285    160 
==
 
 paul@1285    161 
`STORE_TYPE` || `"file"`
 
 paul@1285    162 
|| The store and journal type
 
 paul@1285    163 
==
 
 paul@1285    164 
`STORE_DIR` || `"/var/lib/imip-agent/store"`
 
 paul@1285    165 
|| The location of the stored calendar information, defined in a form
 
 paul@1285    166 
.. appropriate to the selected `STORE_TYPE`
 
 paul@1285    167 
==
 
 paul@1285    168 
`PUBLISH_DIR` || `"/var/www/imip-agent/static"`
 
 paul@1285    169 
|| The location of published static free/busy information, which if
 
 paul@1285    170 
.. given as `None` will cause any such publishing to be disabled
 
 paul@1285    171 
==
 
 paul@1285    172 
`PREFERENCES_DIR` || `"/var/lib/imip-agent/preferences"`
 
 paul@1285    173 
|| The location of user preferences information
 
 paul@1285    174 
==
 
 paul@1285    175 
`JOURNAL_DIR` || `"/var/lib/imip-agent/journal"`
 
 paul@1285    176 
|| The location of quota-related journal information
 
 paul@1285    177 
==
 
 paul@1285    178 
`DEFAULT_PERMISSIONS` || `0660`
 
 paul@1285    179 
|| The octal permission flags for files accessed by Web users and the
 
 paul@1285    180 
.. agent programs
 
 paul@1285    181 
==
 
 paul@1285    182 
`DEFAULT_DIR_PERMISSIONS` || `02770`
 
 paul@1285    183 
|| The octal permission flags for directories, intended to preserve
 
 paul@1285    184 
.. group ownership
 
 paul@1285    185 
==
 
 paul@1285    186 
`LOCALE_DIR` || `"/usr/share/locale"`
 
 paul@1285    187 
|| The location of message translations on the system
 
 paul@1285    188 
==
 
 paul@1285    189 
`TRANS_DOMAIN` || `"imip-agent"`
 
 paul@1285    190 
|| The name of the application used to find message translations
 
 paul@1285    191 
==
 
 paul@1285    192 
`MANAGER_INTERFACE` || `True`
 
 paul@1285    193 
|| Advertise the Web management interface in mails sent to calendar users
 
 paul@1285    194 
==
 
 paul@1285    195 
`MANAGER_PATH` || `"/imip-manager"`
 
 paul@1285    196 
|| The server-relative path at which the management interface is deployed
 
 paul@1285    197 
.. in the Web server environment
 
 paul@1285    198 
==
 
 paul@1285    199 
`MANAGER_URL` || `None`
 
 paul@1285    200 
|| The full URL of the manager application excluding the above path,
 
 paul@1285    201 
.. used to provide specific hostname details instead of those deduced from
 
 paul@1285    202 
.. the environment (when set to None)
 
 paul@1285    203 
==
 
 paul@1285    204 
`MANAGER_URL_SCHEME` || `"http://"`
 
 paul@1285    205 
|| The protocol scheme used if constructing URLs
 
 paul@1285    206 
}}}
 
 paul@1285    207 
 
 paul@1112    208 
=== User Preferences ===
 
 paul@961    209 
 
 paul@1214    210 
Although the software configuration in `config.txt` provides default policies,
 
 paul@961    211 
users can choose to override these defaults by editing their own preferences.
 
 paul@961    212 
The most convenient way of doing this is to use the profile page provided by
 
 paul@961    213 
the [[../CalendarManager|management interface]].
 
 paul@961    214 
 
 paul@961    215 
The settings for the different policies are described in the
 
 paul@961    216 
[[../Preferences|preferences guide]].