1DSYNC(1) Dovecot DSYNC(1)
2
6 dsync - Dovecot's mailbox synchronization utility
7
9 dsync [options] mirror location2
10 dsync [options] backup location2
11
13 dsync is Dovecot's mailbox synchronization utility. It can be used for
14 several different use cases: Two-way synchronization of mailboxes in
15 different servers (via ssh(1)), creating backups of mails to a remote
16 server, and convert mailboxes from/to different mailbox formats.
17 The syncing is done as perfectly as possible: an IMAP or a POP3 client
19 shouldn't be able to notice any differences between the two mailboxes.
20 Two-way syncing means that it's safe to do any kind of modifications in
21 both sides, and dsync will merge the changes without losing any changes
22 done on either side. This is possible because dsync can access Dove‐
23 cot's index logs that keep track of changes. It's of course possible to
24 have conflicts during merging, these are resolved in a safe way. See
25 the dsync design document for more information.
26 dsync uses the same configuration files as the rest of Dovecot (via
28 doveconf binary). The entire configuration can be changed by giving -c
29 parameter to another configuration file, or using -o parameter to over‐
30 ride specific settings. When executing a remote dsync program it works
31 the same way: it uses its own local configuration.
32 dsync can be run completely standalone. It doesn't require any Dovecot
34 server processes to be running, except when using -u parameter to do a
35 userdb lookup from auth process.
36 dsync can currently sync only one user at a time. If you want to dsync
38 all users, you'll need to get a list of all users and execute dsync
39 separately for each one.
40 Any errors are written to stderr.
42
44 dsync recognizes the following command line options:
45 -c config-file
47 read configuration from the given config-file. By default
48 /etc/dovecot/dovecot.conf will be used. -C alt_char Specifies
49 an alternative mailbox name character. If source and destina‐
50 tion mailbox formats are different, it's possible that on one
51 side there exists a mailbox name that isn't valid for the other
52 side. These invalid mailbox names are fixed by replacing such
53 invalid characters with the given alt_char. The default is '_'.
54 -D Activates debug messages and makes dsync more verbose.
56 -f Makes dsync run in "full sync" mode rather than "fast sync"
58 mode. In fast sync mode dsync might skip syncing a mailbox, if
59 both locations had modified it equally many times (i.e. high‐
60 est-modseqs were equal), but with different changes.
61 -m mailbox
63 Specifies the mailbox that should be synchronized or from which
64 mails should be converted. The default is to synchronize all
65 respectively convert from all mailboxes.
66 -o setting=value
68 Overrides the configuration setting from /etc/dovecot/dove‐
69 cot.conf and from the userdb with the given value. In order to
70 override multiple settings to -o option may be specified multi‐
71 ple times.
72 -R Reverse backup direction, so mails in location2 are backed up to
74 default mail location.
75 -u user
77 Specifies that the userdb lookup for the given user should be
78 done and used to set up the environment (uid, gid, home, etc.).
79 By default the system user's current environment will be used.
80 -v Makes dsync more verbose.
82
84 location2
85 The first mail location is based on configuration (mail_location
86 or userdb settings). It's also possible to override it by giv‐
87 ing -o mail_location=mail_location setting. This parameter
88 defines the other mail location that is used.
89 If the location is on local filesystem, you can use a regular
91 mail_location, such as maildir:/backup/user/Maildir
92 If the location is on a remote server, dsync can ssh to it by
94 giving host or user@host as the parameter. If user is speci‐
95 fied, it's given as -u parameter to dsync, not to ssh. The ssh
96 username is always the default.
97 The final way to specify a location is to give a full command
99 line or a path to a script that executes the dsync. For exam‐
100 ple:
101 ssh mailuser@host dsync -u user
103
105 dsync provides the following commands:
106 mirror
108 Does a two-way synchronization between two mail locations. Changes in
109 both locations are synchronized to the other one, without losing any
110 changes made by either of them. Any potential UID conflicts are
111 resolved by giving them new UIDs.
112 backup
114 Backup mails from default mail location to location2 (or vice versa, if
115 -R parameter is given). No changes are ever done to the source loca‐
116 tion. Any changes done in destination are discarded.
117
119 dsync will exit with one of the following values:
120 0 Synchronization was done perfectly.
122 2 Synchronization was done without errors, but some changes couldn't
124 be done, so the mailboxes aren't perfectly synchronized. Running
125 dsync again usually fixes this. Typically this occurs for message
126 modification sequences with newly created mailboxes. It can also
127 occur if one of the mailboxes change during the syncing.
128 1, >2
130 Synchronization failed.
131
133 MIRRORING
134 Mirror mailboxes to a remote server. Any errors are written to stderr.
135 dsync -u username mirror username@example.com
137 If you need more complex parameters to ssh, you can use e.g.:
139 dsync -u username mirror ssh -i id_dsa.dovecot mailuser@example.com dsync -u username
141 CONVERTING
143 Assuming that the mail_location setting in /etc/dove‐
144 cot/conf.d/10-mail.conf is set to: mail_location = mdbox:~/mdbox, a
145 logged in system user may convert her/his mails from its Maildir in
146 her/his home directory to the mdbox mailbox format. The user has to
147 execute the command:
148 dsync mirror maildir:~/Maildir
150 If you want to do this without any downtime, you can do the conversion
152 one user at a time. Initially:
153 · Configuration uses mail_location = maildir:~/Maildir
155 · Set up the possibility of doing per-user mail location using
157 userdb extra fields.
158 Then for each user:
160 1. Run dsync mirror once to do the initial conversion.
162 2. Run dsync mirror again, because the initial conversion could
164 have taken a while and new changes could have occurred during
165 it. This second time only applies changes, so it should be
166 fast.
167 3. Update mail extra field in userdb to mdbox:~/mdbox. If you're
169 using auth cache, you need to flush it.
170 4. Wait for a few seconds and then kill the user's all existing
172 imap and pop3 sessions (that are still using maildir).
173 5. Run dsync mirror once more to apply final changes that were
175 possibly done. After this there should be no changes to
176 Maildir, because the user's mail location has been changed and
177 all existing processes using it have been killed.
178 Once all users have been converted, you can set the default mail_loca‐
180 tion to mdbox and remove the per-user mail locations from userdb.
181
183 Report bugs, including doveconf -n output, to the Dovecot Mailing List
184 <dovecot@dovecot.org>. Information about reporting bugs is available
185 at: http://dovecot.org/bugreport.html
186
188 doveadm(1), doveadm-kick(1), doveconf(1), dovecot(1)
189 Additional resources:
191 dsync design
193 http://wiki2.dovecot.org/Design/Dsync
194Dovecot v2.0 2010-07-02 DSYNC(1)