| 1 |
.. _imap-developer-guidance-replication-examples: |
| 2 |
|
| 3 |
.. Note: This document was converted from the original by Nic Bernstein |
| 4 |
(Onlight). Any formatting mistakes are my fault and not the |
| 5 |
original author's. |
| 6 |
|
| 7 |
Cyrus IMAP Server: Replication Examples |
| 8 |
======================================= |
| 9 |
|
| 10 |
Introduction |
| 11 |
------------ |
| 12 |
|
| 13 |
The replication system creates a link between two Cyrus mailstores: a |
| 14 |
master and a replica system. Both systems can be live mailstores with |
| 15 |
active users: here in Cambridge we install systems in pairs. |
| 16 |
|
| 17 |
Typically half of the users will be using each system, and each system |
| 18 |
replicates to its partner. In the event of a failover everyone uses the |
| 19 |
remaining system in a pair. This is typically safe as the IMAP/POP/SMTP |
| 20 |
servers define which of the two systems is the live server for any given |
| 21 |
account, and the replica just plays a game of follow my leader. |
| 22 |
|
| 23 |
Occasionally I think about introducing some form of sanity check so that |
| 24 |
we have to explicitly issue a command to the remaining backend system as |
| 25 |
well as the proxies in the event of a failover. |
| 26 |
|
| 27 |
A short example of replication in action |
| 28 |
---------------------------------------- |
| 29 |
|
| 30 |
:: |
| 31 |
|
| 32 |
Index: |
| 33 |
|
| 34 |
#: Annotation |
| 35 |
C: Command issued by client |
| 36 |
S: Command issued by server |
| 37 |
|
| 38 |
# Authentication between systems is done using SSH key based authentication: |
| 39 |
|
| 40 |
C: $ ssh -x cyrus-2 /usr/local/cyrus/bin/sync_server |
| 41 |
S: * Sync Server v0.0 [EXPERIMENTAL] |
| 42 |
|
| 43 |
# Create new auth_state and ask for all information about given list of |
| 44 |
# folders (namely user.dpc22). Returns: |
| 45 |
# |
| 46 |
# "**" unsolicited response for each mailbox. Returns: |
| 47 |
# Folder UniqueID, Name, ACL, UIDlast, timestamp for last seen update. |
| 48 |
# |
| 49 |
# "*" response for each mail message in folder: |
| 50 |
# UID, GUID, flags (other than \Seen state) |
| 51 |
|
| 52 |
C: user_some dpc22 user.dpc22 |
| 53 |
S: ** 6b98205c796c6c61 user.dpc22 \ |
| 54 |
S: "dpc22 lrswipcda anonymous 0 " 4151 1062945305 |
| 55 |
S: * 1 000000000000000000000000 () |
| 56 |
S: * 3697 0101003f4c56b00545000000 () |
| 57 |
S: * 3919 0101003f4c56b04b2900000d () |
| 58 |
S: * 3937 0101003f4c56b0514900001f () |
| 59 |
S: * 4066 0101003f4c56b07422000002 () |
| 60 |
S: * 4089 0101003f4c56b07e56000023 (\answered) |
| 61 |
S: * 4118 0101003f4c56b08328000016 () |
| 62 |
S: * 4131 0101003f4c56b084d7000002 () |
| 63 |
S: * 4136 0101003f4c56b087f3000001 () |
| 64 |
S: * 4140 0101003f4c56b08c9d000026 () |
| 65 |
S: OK User_Some finished |
| 66 |
|
| 67 |
# Select a folder to work with |
| 68 |
|
| 69 |
C: select user.dpc22 |
| 70 |
S: OK 6b98205c796c6c61 4151 1062945305 |
| 71 |
|
| 72 |
# Remove message with UID "1" from folder list (message which has been |
| 73 |
# sitting in my inbox since January, has no GUID defined) |
| 74 |
|
| 75 |
C: expunge 1 |
| 76 |
S: OK Expunge Complete |
| 77 |
|
| 78 |
# Set some user flags on message UID "4140" |
| 79 |
|
| 80 |
C: setflags 4140 (hello world) |
| 81 |
S: OK Updated flags on 1 messages okay |
| 82 |
|
| 83 |
# Demonstrate that something has changed: |
| 84 |
|
| 85 |
C: status |
| 86 |
S: * 3697 0101003f4c56b00545000000 () |
| 87 |
S: * 3919 0101003f4c56b04b2900000d () |
| 88 |
S: * 3937 0101003f4c56b0514900001f () |
| 89 |
S: * 4066 0101003f4c56b07422000002 () |
| 90 |
S: * 4089 0101003f4c56b07e56000023 (\answered) |
| 91 |
S: * 4118 0101003f4c56b08328000016 () |
| 92 |
S: * 4131 0101003f4c56b084d7000002 () |
| 93 |
S: * 4136 0101003f4c56b087f3000001 () |
| 94 |
S: * 4140 0101003f4c56b08c9d000026 (hello world) |
| 95 |
S: OK 4151 |
| 96 |
|
| 97 |
# Now lets correct the damage that we just inflicted: |
| 98 |
|
| 99 |
C: $ replicate -s cyrus-2 -v -v -m user.dpc22 |
| 100 |
S: MAILBOXES user.dpc22 |
| 101 |
S: USER_SOME dpc22 user.dpc22 |
| 102 |
S: SELECT user.dpc22 |
| 103 |
S: SETFLAGS [1 msgs] |
| 104 |
S: UPLOAD [1 msgs] |
| 105 |
S: SETSEEN dpc22 ... |
| 106 |
S: ENDUSER |
| 107 |
|
| 108 |
C: $ ssh -x cyrus-2 /usr/local/cyrus/bin/sync_server |
| 109 |
S: * Sync Server v0.0 [EXPERIMENTAL] |
| 110 |
S: user_some dpc22 user.dpc22 |
| 111 |
S: ** 6b98205c796c6c61 user.dpc22 \ |
| 112 |
S: "dpc22 lrswipcda anonymous 0 " 4156 1062968731 |
| 113 |
S: * 1 000000000000000000000000 () |
| 114 |
S: * 3697 0101003f4c56b00545000000 () |
| 115 |
S: * 3919 0101003f4c56b04b2900000d () |
| 116 |
S: * 3937 0101003f4c56b0514900001f () |
| 117 |
S: * 4066 0101003f4c56b07422000002 () |
| 118 |
S: * 4089 0101003f4c56b07e56000023 (\answered) |
| 119 |
S: * 4118 0101003f4c56b08328000016 () |
| 120 |
S: * 4131 0101003f4c56b084d7000002 () |
| 121 |
S: * 4136 0101003f4c56b087f3000001 () |
| 122 |
S: * 4140 0101003f4c56b08c9d000026 () |
| 123 |
S: OK User_Some finished |
| 124 |
|
| 125 |
# Back where we started: the replication engine reinserted message UID 0 |
| 126 |
# which was missing, and removed "hello world" from message UID 4140 |
| 127 |
|
| 128 |
Tracking messages between folders |
| 129 |
--------------------------------- |
| 130 |
|
| 131 |
:: |
| 132 |
|
| 133 |
# I've just saved a message from my inbox into a folder named "zzz", |
| 134 |
# creating the folder the process. |
| 135 |
|
| 136 |
C: $ replicate -s cyrus-2 -v -v -m user.dpc22 user.dpc22.zzz |
| 137 |
|
| 138 |
Replication action on two MAILBOX objects: |
| 139 |
|
| 140 |
S: MAILBOXES user.dpc22 user.dpc22.zzz |
| 141 |
|
| 142 |
Ask server for contents of the two folders: |
| 143 |
|
| 144 |
S: USER_SOME dpc22 ... |
| 145 |
|
| 146 |
Reserve message with given GUID in user.dpc22 so that it can be moved |
| 147 |
|
| 148 |
S: RESERVE user.dpc22 ... |
| 149 |
|
| 150 |
Remove message from source folder (reserved copy left behind) |
| 151 |
|
| 152 |
S: SELECT user.dpc22 |
| 153 |
S: EXPUNGE [1 msgs] |
| 154 |
S: SETSEEN dpc22 ... |
| 155 |
|
| 156 |
Create target folder and copy in message that we reserved (doesn't have to |
| 157 |
be uploaded again) |
| 158 |
|
| 159 |
S: CREATE user.dpc22.zzz 7f6f384c3f5ba99a |
| 160 |
S: "dpc22 lrswipcda anonymous 0 " 0 1062971802 |
| 161 |
S: SELECT user.dpc22.zzz |
| 162 |
S: UPLOAD [1 msgs] |
| 163 |
S: SETSEEN dpc22 ... |
| 164 |
S: ENDUSER |