install-replication [plain text]
Cyrus replication
Note that Cyrus replication is still relatively young in the grand
scheme of things, and if you choose to deploy you are doing so at your
own risk. The core of the replication code has been used successfully
in production at Cambridge University for about a year, but it has been
rewritten extensively as part of the integration into the mainstream
Cyrus codebase.
Also note that the replication protocol currently does not have the
facility to support the IMAP CONDSTORE extension (modification
sequences). It is recommended that you do not try to use both CONDSTORE
and replication at this time. The deficiencies in the replication
protocol will be fixed in version 2.3.9.
Introduction & Assumptions
The Cyrus replication engine is designed to replicate the mailstore on
standalone Cyrus servers or "backend" servers in a Cyrus Murder to
provide a high-availability environment. It is NOT intended to
replicate "frontend" servers or the "mupdate master" in a Cyrus Murder.
Note that load balancing is not possible with the current replication
code, but it is intended to be supported in the future.
This document assumes that you have successfully been able to setup
atleast one Cyrus IMAP server. This server will become your first
"master" server. It also assumes that you are familliar with the
administration and day to day operations of the Cyrus IMAP server and
the SASL authentication library. If you feel uncomfortable with this,
please refer to the rest of the documentation first.
Installation
You will need to build Cyrus IMAPd with the --enable-replication
configure option. This builds the replication client/server
applications and utilities.
Requirements
* Atleast one standalone or "backend" Cyrus IMAP server.
* Atleast one machine that will become the first "replica" server.
Configuring the "replica" server
The "replica" server is a standalone server which listens for and
processes synchronization messages from a "master" server. The
"replica" server needs to be configured to accept these synchonization
messages.
1. Configure a standalone server as described in the rest of the
documentation.
2. Add the following line to the "/etc/services" file.
csync 2005/tcp
Note that the port number is arbitrary as long as its not being
used by any other services on your network.
3. Add a line similar to the following in the SERVICES section of
cyrus.conf:
syncserver cmd="/usr/cyrus/bin/sync_server" listen="csync"
4. Start/restart "/usr/cyrus/bin/master".
Configuring the "master" server
The "master" server is the standalone or "backend" server which is
actively serving mailboxes to clients. This server needs to be
configured to synchronize its mailstore with a "replica" server.
1. Add the following line to the "/etc/services" file.
csync 2005/tcp
Note that the port number MUST be the same as that used on the
"replica" server.
2. Specify the hostname of the "replica" server and how to
authenticate to it using the following imap.conf options:
* sync_host
* sync_authname
* sync_realm
* sync_password
Note that sync_authname MUST be an admin on the "replica" server.
Also note that sync_realm and sync_password may not be necessary
depending on the SASL mechanism used for authentication.
Universally Unique Identifiers (UUIDs)
An optional, but recommended step is to enable UUIDs for messages. Use
of UUIDs improves efficiency by eliminating the synchronization of
messages which the "replica" has already received from the "master".
Note that UUIDs can be safely enabled and disabled at any time.
1. Define the sync_machineid option in imapd.conf. This option
specifies the numeric identifier (1 - 255) of the "master" machine
which is used in constructing the UUID for each message on the
server. This identifier MUST be unique across all active "backend"
servers in a Murder. Example:
sync_machineid: 1
2. For each IMAP, NNTP and LMTP service in cyrus.conf, enable the
provide_uuid argument. Example:
imap cmd="imapd" listen="imap" prefork=5 provide_uuid=1
"Rolling" replication
"Rolling" replication means that the "master" server continuously
synchonizes itself with the replica. To configure "rolling"
replication, perform the following:
1. Enable the sync_log option in imapd.conf. This allows the imapd,
pop3d, nntpd, and lmtpd services to log synchonization actions
which will be periodically serviced by sync_client.
2. Optionally, adjust the sync_repeat_interval in imapd.conf.
3. Add a line similar to the following in the STARTUP section of
cyrus.conf:
syncclient cmd="/usr/cyrus/bin/sync_client -r"
4. Start/restart "/usr/cyrus/bin/master".
Administration
Manual replication
To manually synchonize any part of the mailstore, simply run
sync_client(8) with the appropriate command line options. Note that you
CAN manually synchonize even if "rolling" replication has been
configured.
Failover