← Back to branch summary

~ubuntu-branches/ubuntu/trusty/dovecot/trusty-updates

« back to all changes in this revision

Viewing changes to doc/wiki/Replication.txt

  • Committer: Package Import Robot
  • Author(s): James Page
  • Date: 2014-01-08 09:35:49 UTC
  • mfrom: (1.15.3) (96.1.1 trusty-proposed)
  • Revision ID: package-import@ubuntu.com-20140108093549-814nkqdcxfbvgktg
Tags: 1:2.2.9-1ubuntu1
* Merge from Debian unstable, remaining changes:
  + Add mail-stack-delivery package:
    - Update d/rules
    - d/control: convert existing dovecot-postfix package to a dummy
      package and add new mail-stack-delivery package.
    - Update maintainer scripts.
    - Rename d/dovecot-postfix.* to debian/mail-stack-delivery.*
    - d/mail-stack-delivery.preinst: Move previously installed backups and
      config files to a new package namespace.
    - d/mail-stack-delivery.prerm: Added to handle downgrades.
  + Use Snakeoil SSL certificates by default:
    - d/control: Depend on ssl-cert.
    - d/dovecot-core.postinst: Relax grep for SSL_* a bit.
  + Add autopkgtest to debian/tests/*.
  + Add ufw integration:
    - d/dovecot-core.ufw.profile: new ufw profile.
    - d/rules: install profile in dovecot-core.
    - d/control: dovecot-core - suggest ufw.
  + d/dovecot-core.dirs: Added usr/share/doc/dovecot-core
  + Add apport hook:
    - d/rules, d/source_dovecot.py
  + Add upstart job:
    - d/rules, d/dovecot-core.dovecot.upstart, d/control,
      d/dovecot-core.dirs, dovecot-imapd.{postrm, postinst, prerm},
      d/dovecot-pop3d.{postinst, postrm, prerm}.
      d/mail-stack-deliver.postinst: Convert init script to upstart.
  + Use the autotools-dev dh addon to update config.guess/config.sub for
    arm64.
* Dropped changes, included in Debian:
  - Update Dovecot name to reflect distribution in login greeting.
  - Update Drac plugin for >= 2.0.0 support.
* d/control: Drop dovecot-postfix package as its no longer required.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/wiki/Replication.txt
 
1
Replication with dsync
 
2
======================
 
3
 
 
4
Dovecot supports master/master replication using dsync. It's recommended that
 
5
the same user always gets redirected to the same replica, but no changes get
 
6
lost even if the same user modifies mails simultaneously on both replicas, some
 
7
mails just might have to be redownloaded. The replication is done
 
8
asynchronously, so high latency between the replicas isn't a problem. The
 
9
replication is done by looking at Dovecot index files (not what exists in
 
10
filesystem), so no mails get lost due to filesystem corruption or an accidental
 
11
rm -rf, they will simply be replicated back.
 
12
 
 
13
NOTE: v2.2 is highly recommended for this. Earlier versions can't do
 
14
incremental metadata syncing. This means that the more mails a mailbox has, the
 
15
slower it is to sync it.
 
16
 
 
17
Make sure that user listing is configured for your userdb, this is required by
 
18
replication:
 
19
 
 
20
---%<-------------------------------------------------------------------------
 
21
doveadm user '*'
 
22
---%<-------------------------------------------------------------------------
 
23
 
 
24
Enable the replication plugin globally (most likely you'll need to do this in
 
25
10-mail.conf):
 
26
 
 
27
---%<-------------------------------------------------------------------------
 
28
mail_plugins = $mail_plugins notify replication
 
29
---%<-------------------------------------------------------------------------
 
30
 
 
31
Replicator process should be started at startup, so it can start replicating
 
32
users immediately:
 
33
 
 
34
---%<-------------------------------------------------------------------------
 
35
service replicator {
 
36
  process_min_avail = 1
 
37
}
 
38
---%<-------------------------------------------------------------------------
 
39
 
 
40
You need to configure how and where to replicate. Using SSH for example:
 
41
 
 
42
---%<-------------------------------------------------------------------------
 
43
dsync_remote_cmd = ssh -l%{login} %{host} doveadm dsync-server -u%u
 
44
plugin {
 
45
  mail_replica = remote:vmail@anotherhost.example.com
 
46
}
 
47
---%<-------------------------------------------------------------------------
 
48
 
 
49
The mail processes need to have access to the replication-notify fifo and
 
50
socket. If you have a single vmail UID, you can do:
 
51
 
 
52
---%<-------------------------------------------------------------------------
 
53
service aggregator {
 
54
  fifo_listener replication-notify-fifo {
 
55
    user = vmail
 
56
  }
 
57
  unix_listener replication-notify {
 
58
    user = vmail
 
59
  }
 
60
}
 
61
---%<-------------------------------------------------------------------------
 
62
 
 
63
The replication-notify only notifies the replicator processes that there is
 
64
work to be done, so it's not terribly insecure either to just set 'mode=0666'.
 
65
 
 
66
Enable doveadm replicator commands by setting:
 
67
 
 
68
---%<-------------------------------------------------------------------------
 
69
service replicator {
 
70
  unix_listener replicator-doveadm {
 
71
    mode = 0600
 
72
  }
 
73
}
 
74
---%<-------------------------------------------------------------------------
 
75
 
 
76
dsync over TCP connections (v2.2+)
 
77
----------------------------------
 
78
 
 
79
Create a listener for doveadm-server:
 
80
 
 
81
---%<-------------------------------------------------------------------------
 
82
service doveadm {
 
83
  inet_listener {
 
84
    port = 12345
 
85
  }
 
86
}
 
87
---%<-------------------------------------------------------------------------
 
88
 
 
89
And tell doveadm client to use this port by default:
 
90
 
 
91
---%<-------------------------------------------------------------------------
 
92
doveadm_port = 12345
 
93
---%<-------------------------------------------------------------------------
 
94
 
 
95
Both the client and the server also need to have a shared secret:
 
96
 
 
97
---%<-------------------------------------------------------------------------
 
98
doveadm_password = secret
 
99
---%<-------------------------------------------------------------------------
 
100
 
 
101
Now you can use 'tcp:hostname' as the dsync target. You can also override the
 
102
port with 'tcp:hostname:port'.
 
103
 
 
104
---%<-------------------------------------------------------------------------
 
105
plugin {
 
106
  mail_replica = tcp:anotherhost.example.com # use doveadm_port
 
107
  #mail_replica = tcp:anotherhost.example.com:12345 # use port 12345 explicitly
 
108
}
 
109
---%<-------------------------------------------------------------------------
 
110
 
 
111
SSL
 
112
---
 
113
 
 
114
You can also use SSL for the connection:
 
115
 
 
116
---%<-------------------------------------------------------------------------
 
117
service doveadm {
 
118
  inet_listener {
 
119
    port = 12345
 
120
    ssl = yes
 
121
  }
 
122
}
 
123
---%<-------------------------------------------------------------------------
 
124
 
 
125
The client must be able to verify that the SSL certificate is valid, so you
 
126
need to specify the directory containing valid SSL CA roots:
 
127
 
 
128
---%<-------------------------------------------------------------------------
 
129
ssl_client_ca_dir = /etc/ssl/certs # Debian/Ubuntu
 
130
ssl_client_ca_file = /etc/pki/tls/cert.pem # RedHat
 
131
---%<-------------------------------------------------------------------------
 
132
 
 
133
Now you can use 'tcps:hostname' or 'tcps:hostname:port' as the dsync target.
 
134
 
 
135
Note that the SSL certificate must be signed by one of the CAs in the
 
136
'ssl_client_ca_dir' or 'ssl_client_ca_file'. You can't use a self-signed
 
137
certificate or a private CA, unless you correctly set them up into the CA
 
138
file/directory (see openssl documentation for details).
 
139
 
 
140
dsync wrapper script for root SSH login (v2.2+)
 
141
-----------------------------------------------
 
142
 
 
143
If you're using multiple UIDs, dsync needs to be started as root, which means
 
144
you need to log in as root with ssh (or use sudo). Another possibility is to
 
145
allow root to run only a wrapper script. There is some built-in support for
 
146
this in v2.2+ to make it easier:
 
147
 
 
148
dovecot.conf:
 
149
 
 
150
---%<-------------------------------------------------------------------------
 
151
dsync_remote_cmd = /usr/bin/ssh -i /root/.ssh/id_dsa.dsync %{host}
 
152
/usr/local/bin/dsync-in-wrapper.sh
 
153
plugin {
 
154
  mail_replica = remoteprefix:vmail@anotherhost.example.com
 
155
}
 
156
---%<-------------------------------------------------------------------------
 
157
 
 
158
/root/.ssh/authorized_keys:
 
159
 
 
160
---%<-------------------------------------------------------------------------
 
161
command="/usr/local/bin/dsync-in-wrapper.sh",no-port-forwarding,no-X11-forwarding,no-agent-forwarding,no-pty
 
162
<ssh key>
 
163
---%<-------------------------------------------------------------------------
 
164
 
 
165
/usr/local/bin/dsync-in-wrapper.sh:
 
166
 
 
167
---%<-------------------------------------------------------------------------
 
168
read username
 
169
ulimit -c unlimited # for debugging any crashes
 
170
/usr/local/bin/doveadm dsync-server -u $username
 
171
---%<-------------------------------------------------------------------------
 
172
 
 
173
dsync parameters
 
174
----------------
 
175
 
 
176
With v2.2.9+ you can configure what parameters replicator uses for the 'doveadm
 
177
sync' command:
 
178
 
 
179
---%<-------------------------------------------------------------------------
 
180
replication_dsync_parameters = -d -N -l 30 -U
 
181
---%<-------------------------------------------------------------------------
 
182
 
 
183
The '-f' and '-s' parameters are added automatically when needed.
 
184
 
 
185
Usually the only change you may want to do is replace '-N' (= sync all
 
186
namespaces) with '-n <namespace>' or maybe just add '-x <exclude>'
 
187
parameter(s).
 
188
 
 
189
Notes
 
190
-----
 
191
 
 
192
Random things to remember:
 
193
 
 
194
 * The replicas can't share the same quota database, since both will always
 
195
   update it
 
196
 * With mdbox format "doveadm purge" won't be replicated
 
197
 * "doveadm force-resync", "doveadm quota recalc" and other similar fixing
 
198
   commands don't get replicated
 
199
 * The servers must have different hostnames or the locking doesn't work and
 
200
   can cause replication problems.
 
201
    * v2.2.6+: If you're having trouble, verify that 'dovecot --hostdomain'
 
202
      returns different values for the servers.
 
203
 
 
204
(This file was created from the wiki on 2013-11-24 04:42)