1.1 --- a/README.txt Wed Oct 28 00:37:57 2015 +0100
1.2 +++ b/README.txt Wed Oct 28 00:38:45 2015 +0100
1.3 @@ -11,134 +11,10 @@
1.4 ===============
1.5
1.6 Eventually, this information should be incorporated into packages for various
1.7 -operating system distributions, and these instructions should be largely
1.8 -superfluous for most users.
1.9 -
1.10 -Installing the Software
1.11 -=======================
1.12 -
1.13 -The tools/install.sh script should install the software in appropriate
1.14 -locations. See the prerequisites below for other software that will be
1.15 -required.
1.16 -
1.17 -System User and Filesystem Access
1.18 -=================================
1.19 -
1.20 -The data handled by imip-agent needs to be accessible to other software,
1.21 -notably mail handling software and Web server software. Two approaches are
1.22 -described here: LMTP delivery and local SMTP delivery.
1.23 -
1.24 -LMTP Delivery
1.25 --------------
1.26 -
1.27 -Here, imip-agent's programs run in a way that permits LMTP delivery (requiring
1.28 -suitable local privileges to communicate with the mail storage solution)
1.29 -whilst allowing the Web server to read data written by those programs.
1.30 -
1.31 -A system group needs to be created for LMTP delivery and for certain users to
1.32 -share resources:
1.33 -
1.34 - addgroup lmtp
1.35 -
1.36 -This group should be employed for LMTP delivery by systems like Cyrus and
1.37 -Dovecot. See the section on configuring mail systems for delivery for more
1.38 -information.
1.39 -
1.40 -A system user needs to be created and to belong to certain groups in order to
1.41 -deliver messages to mail stores and to publish resources on the Web:
1.42 -
1.43 - useradd -d /var/lib/imip-agent -m -U -G lmtp,www-data -r imip-agent
1.44 -
1.45 -Store details and published resources need to be accessible by the imip-agent
1.46 -and www-data users. Thus, www-data also needs to belong to the lmtp group:
1.47 -
1.48 - adduser www-data lmtp
1.49 -
1.50 -Local SMTP Delivery
1.51 --------------------
1.52 -
1.53 -Here, imip-agent's programs run in a way that permits local SMTP delivery
1.54 -(which merely needs the ability to connect to a local network service) whilst
1.55 -allowing the Web server to read data written by those programs.
1.56 -
1.57 -A system user needs to be created and to belong to certain groups in order to
1.58 -deliver messages to mail stores and to publish resources on the Web:
1.59 -
1.60 - useradd -d /var/lib/imip-agent -m -U -G www-data -r imip-agent
1.61 -
1.62 -Again, the tools/init.sh script will initialise directories for stored and
1.63 -published data. The tools/config.sh script should be edited and the group
1.64 -redefined as follows:
1.65 -
1.66 - IMIP_AGENT_GROUP=www-data
1.67 -
1.68 -If already installed, the /etc/imip-agent/config.sh script should be edited
1.69 -instead.
1.70 +operating system distributions, and the accompanying instructions should be
1.71 +largely superfluous for most users.
1.72
1.73 -With local SMTP delivery, the mail system will need to be configured to route
1.74 -messages for local recipients. See the description of mail configuration for
1.75 -more information.
1.76 -
1.77 -Initialising the Software
1.78 -=========================
1.79 -
1.80 -Once a suitable system user has been chosen, stored and published data is then
1.81 -initialised using the tools/init.sh script. The script employs the setgid flag
1.82 -on the directories initialised for stored and published data so that new files
1.83 -and directories have the appropriate group associated with them.
1.84 -
1.85 -It should be possible to omit all arguments to the init.sh script, but it is
1.86 -also worth reading the help message:
1.87 -
1.88 - tools/init.sh --help
1.89 -
1.90 -Fixing ownership can be done using the tools/fix.sh script, in case some form
1.91 -of modification has altered the ownership or membership of the created files
1.92 -and directories.
1.93 -
1.94 -Configuring Other Software
1.95 -==========================
1.96 -
1.97 -The conf directory contains subdirectories for different systems:
1.98 -
1.99 - apache Apache 2 site configuration for publishing resources
1.100 - cron Cron command scheduling for free/busy updates
1.101 - exim Exim 4 routing and transport configuration
1.102 - ldap Some LDAP-related resources
1.103 - postfix Postfix routing and transport configuration
1.104 -
1.105 -Either Exim or Postfix can be chosen as a mail system supporting the agent.
1.106 -
1.107 -Configuring Mail Systems for the Agent
1.108 -======================================
1.109 -
1.110 -The essential aspect of mail system configuration involves mail transports and
1.111 -the integration of agent programs into the mail processing pipeline. Thus, the
1.112 -following files are of particular interest:
1.113 -
1.114 -For Exim (in conf/exim)...
1.115 -
1.116 - 30_exim4-config_people Integration of agent programs
1.117 - 30_exim4-config_people_outgoing ...
1.118 - 30_exim4-config_resources ...
1.119 -
1.120 -For Postfix (in conf/postfix)...
1.121 -
1.122 - master.cf.items Integration of agent programs (for
1.123 - inclusion in master.cf)
1.124 - transport Configuration of agent transports
1.125 - virtual Configuration of outgoing mail routing
1.126 -
1.127 -Such files need adjusting for the deployment environment so that, for example,
1.128 -the example.com domain would be replaced with a suitable value.
1.129 -
1.130 -If local SMTP delivery is being used, the 30_exim4-config_people file (in
1.131 -conf/exim) or the master.cf.items file (in conf/postfix) will need adjusting.
1.132 -
1.133 -If LMTP is being used, instances of LMTP_SOCKET in the example configuration
1.134 -files will need to be replaced with a suitable filesystem path. Where the lmtp
1.135 -system group is employed, it may be replaced with a different group. See
1.136 -below for a discussion of LMTP and mail delivery.
1.137 +See: docs/wiki/GettingStarted
1.138
1.139 Configuring Mail Systems for Mail Recipients
1.140 ============================================
1.141 @@ -152,114 +28,9 @@
1.142 disregarded in favour of other ways of defining mail recipients, subject to
1.143 the needs of any given environment.
1.144
1.145 -Using LDAP with Exim
1.146 ---------------------
1.147 -
1.148 -For Exim (in conf/exim/ldap)...
1.149 -
1.150 - 010_exim4-config_ldap_people_outgoing Defines recipients and outgoing
1.151 - mail routing
1.152 - 020_exim4-config_ldap_people ...
1.153 - 020_exim4-config_ldap_resources ...
1.154 - 020_exim4-config_ldap_people_outgoing_recipients
1.155 -
1.156 -Using LDAP with Postfix
1.157 ------------------------
1.158 -
1.159 -For Postfix (in conf/postfix/ldap)...
1.160 -
1.161 - main.cf.example Defines recipients and outgoing
1.162 - mail routing (for inclusion in
1.163 - main.cf)
1.164 -
1.165 - virtual_alias_maps_people.cf Defines recipients and outgoing
1.166 - virtual_alias_maps_people_outgoing.cf mail routing
1.167 - virtual_alias_maps_resources.cf ...
1.168 -
1.169 -Using Lists of Identities
1.170 --------------------------
1.171 -
1.172 -Since the use of LDAP can be somewhat challenging and also excessive in some
1.173 -situations, examples of maintaining recipient information using a simpler
1.174 -approach are provided.
1.175 -
1.176 -In this simpler environment, recipient details must be manually edited in the
1.177 -virtual identity files, but this permits a very transparent way of
1.178 -administering the system.
1.179 -
1.180 -Using Lists with Exim
1.181 ----------------------
1.182 -
1.183 -For Exim (in conf/exim/simple)...
1.184 -
1.185 - 010_exim4-config_people_outgoing Defines recipients and outgoing
1.186 - mail routing
1.187 - 020_exim4-config_people ...
1.188 - 020_exim4-config_resources ...
1.189 - 020_exim4-config_people_outgoing_recipients
1.190 -
1.191 - virtual_people Defines recipient identities
1.192 - virtual_people_outgoing_recipients belonging to known domains
1.193 - virtual_resources ...
1.194 -
1.195 - virtual_domains Defines recipient domains
1.196 -
1.197 -To add support for delivery to local mailboxes, the following additional file
1.198 -is provided as an example:
1.199 -
1.200 - virtual_people_local Defines recipients and local users
1.201 -
1.202 -And to route bounced messages back to the generic calendar address, an
1.203 -addition to the /etc/aliases file is provided:
1.204 -
1.205 - aliases.example Routes calendar to root
1.206 -
1.207 -Using Lists with Postfix
1.208 -------------------------
1.209 -
1.210 -For Postfix (in conf/postfix/simple)...
1.211 -
1.212 - main.cf.example Defines recipients and outgoing
1.213 - mail routing (for inclusion in
1.214 - main.cf)
1.215 -
1.216 - virtual_alias_maps Defines recipients and outgoing
1.217 - virtual_alias_maps_people_outgoing mail routing
1.218 -
1.219 -To add support for delivery to local mailboxes, the following alternative to
1.220 -virtual_alias_maps is provided as an example:
1.221 -
1.222 - virtual_alias_maps_local Defines recipients and local users
1.223 -
1.224 -LDAP Representations for Mail Recipients
1.225 -----------------------------------------
1.226 -
1.227 -Relevant LDAP resources for structuring recipient information include the
1.228 -following:
1.229 -
1.230 - RFC 4524 Defines the mail attribute
1.231 - http://tools.ietf.org/html/rfc4524
1.232 -
1.233 - RFC 2798 Defines the inetOrgPerson object
1.234 - http://tools.ietf.org/html/rfc2798 class
1.235 -
1.236 - RFC 2739 Defines the calEntry object class
1.237 - https://tools.ietf.org/html/rfc2739 supporting calFBURL
1.238 -
1.239 -An additional draft RFC describes the mailRecipient object class:
1.240 -
1.241 - https://tools.ietf.org/html/draft-lachman-ldap-mail-routing-03
1.242 -
1.243 -Resource schemas for LDAP are not effectively standardised for the purposes of
1.244 -this software. A useful object class, inetResource, was defined for the
1.245 -iPlanet Calendar Server:
1.246 -
1.247 - http://docs.oracle.com/cd/E19566-01/819-4437/6n6jckqrf/index.html#anocg
1.248 - http://docs.oracle.com/cd/E19566-01/819-4437/6n6jckqr8/index.html
1.249 -
1.250 -Although Kolab maintains notions of resources, they are tied up with the
1.251 -notion of a shared folder and the kolabSharedFolder object class, although the
1.252 -mailRecipient object class is employed by resources in Kolab.
1.253 +See: docs/wiki/MailIntegration
1.254 +See: docs/wiki/MailIntegration--LDAP
1.255 +See: docs/wiki/MailIntegration--Simple
1.256
1.257 Configuring Mail Systems for Mail Delivery
1.258 ==========================================
1.259 @@ -268,53 +39,9 @@
1.260 performed either using local SMTP or by using LMTP to a suitable mailbox
1.261 provider.
1.262
1.263 -If employing local SMTP, the burden of routing messages to suitable storage
1.264 -becomes a configuration problem within the mail system itself, but given that
1.265 -routing to local system users is typically supported "out of the box", this
1.266 -can provide a usable solution with minimal effort.
1.267 -
1.268 -Where the mail system must instead route messages to mailbox providers
1.269 -employing LMTP, some more effort is required. For Exim, some sample
1.270 -configuration files are provided in conf/exim/lmtp to route messages for local
1.271 -users to LMTP endpoints.
1.272 -
1.273 -By using LMTP from the agent software, the issue of configuring the mail
1.274 -system to integrate with storage solutions is avoided, but then those
1.275 -solutions must expose their LMTP interface appropriately.
1.276 -
1.277 -Configuring Mail Storage Providers for LMTP
1.278 --------------------------------------------
1.279 -
1.280 -Although this topic is largely beyond the scope of this document, systems such
1.281 -as Cyrus and Dovecot can be configured to provide a Unix domain socket
1.282 -offering support for LMTP connections.
1.283 -
1.284 -For Cyrus, the following bug report is pertinent:
1.285 -
1.286 -https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=494746
1.287 -
1.288 -A permanent change in permissions on the Cyrus LMTP socket is therefore
1.289 -required to make delivery available to the lmtp group:
1.290 -
1.291 - dpkg-statoverride --force --update --add \
1.292 - cyrus lmtp 750 /var/run/cyrus/socket
1.293 -
1.294 -Configuring Cron for Free/Busy Updates
1.295 -======================================
1.296 -
1.297 -The periods occupied by recurring events are not expanded beyond a certain
1.298 -window of time by imip-agent. As a consequence, free/busy collections need to
1.299 -be progressively expanded over time to include periods occupied by such events
1.300 -that were not previously recorded in those collections.
1.301 -
1.302 -The conf/cron/cron.daily/imip-agent file contains commands that update
1.303 -free/busy collections for all known users, and this should be copied to the
1.304 -appropriate destination. For example:
1.305 -
1.306 -cp conf/cron/cron.daily/imip-agent /etc/cron.daily/
1.307 -
1.308 -Where frequency-specific directories are not supported by cron on a system, a
1.309 -crontab entry of the appropriate format is required instead.
1.310 +See: docs/wiki/MailIntegration
1.311 +See: docs/wiki/MailIntegration--LMTP
1.312 +See: docs/wiki/MailIntegration--LocalSMTP
1.313
1.314 Configuring Web Servers for Free/Busy Publishing
1.315 ================================================
1.316 @@ -353,38 +80,3 @@
1.317 as follows:
1.318
1.319 a2enmod authnz_ldap
1.320 -
1.321 -Prerequisites
1.322 -=============
1.323 -
1.324 -Depending on the mail transport agent (MTA) chosen, the following packages are
1.325 -required for this software to work on Debian systems:
1.326 -
1.327 - Exim: exim4-daemon-heavy
1.328 - Postfix: postfix postfix-ldap
1.329 -
1.330 -The software itself requires the following packages:
1.331 -
1.332 - Python: python
1.333 - pytz: python-tz
1.334 -
1.335 -To update free/busy details periodically, the following software is
1.336 -recommended:
1.337 -
1.338 - Cron: cron
1.339 -
1.340 -The management Web interface requires the following packages:
1.341 -
1.342 - Apache: apache2
1.343 - Babel: python-babel
1.344 -
1.345 -Although not necessarily within the scope of the deployment of this software,
1.346 -the following mail storage solutions would be used to receive and hold
1.347 -messages:
1.348 -
1.349 - Cyrus: cyrus-imapd
1.350 - Dovecot: dovecot-imapd dovecot-ldap dovecot-lmtpd
1.351 -
1.352 -Some test programs need additional programs provided by other packages:
1.353 -
1.354 - envsubst: gettext-base