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 since the summer of 2003, but it
    has been rewritten extensively as part of the integration into the
    mainstream Cyrus codebase. The replication code as integrated into
    Cyrus 2.3 has been running in production at Fastmail.fm and
    Columbia.edu since early 2006 and will be put into production at CMU in
    winter 2007. 

    The Cyrus team owes a debt of gratitude to the kind folks at Cambridge,
    Columbia, and Fastmail for their considerable effort in helping to
    identify and correct the bugs the in Cyrus 2.3 replication code. 

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. The "replica" server MUST NOT be configured to be part of a
    Murder (it should only be configured into the Murder at the point at
    which it replaces a failed backend "master").

     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. 

Compression

    If you are running replication over a remote link, then the tradeoff
    between bandwidth and CPU usage will tilt strongly in favour of
    enabling compression to save bandwidth at a slight increase in CPU
    cost. You can set the 'sync_compress' imapd.conf value, or pass the
    '-z' flag to sync_client. 

     1. sync_compress: 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. 

    You can also run cyr_synclog(8) instead, which will insert the record
    into the rolling replication log. 

Failover