Debian Codegraph @

doc/html/_sources/imap/developer/guidance/replication_examples.rst.txt

raw
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