.\" Copyright (c) 2010 Dovecot authors, see the included COPYING file .TH DOVEADM\-SYNC 1M "2011-01-16" "Dovecot v2.2" "Dovecot" .SH NAME doveadm sync \- Dovecot\'s mailbox synchronization utilities .\"------------------------------------------------------------------------ .SH SYNOPSIS .nh .na .HP \" ./global-options-short.inc \" ./master-options-short.inc \" ./mail-options-short.inc \fBdoveadm sync\fR|\fBbackup\fR [\-D] [\-F\ \fIformatter\fR] [\-v] [\-c\ \fIfile\fR|\-i\ \fIinstance\fR] [\-k] [\-L] [\-O] [\-o\ \fIsetting\fB=\fIvalue\fR]... [\-S\ \fIsocket\fR] [\-A|\-u\ \fIuser\fR] [\-E] [\-1] [\-f] [\-g\ \fIGUID\fR] [\-l\ \fItimeout\fR] [\-m\ \fImailbox\fR] [\-N] [\-n\ \fIns_prefix\fR] [\-P] [\-R] [\-r\ \fIlog_file\fR] \[\-s\ \fIstate\fR] [\-U] [\-x\ \fImailbox\fR]... -d|\fIlocation2\fR .HP \" ./global-options-short.inc \" ./master-options-short.inc \" ./mail-options-short.inc \fBdoveadm dsync\-server\fR [\-D] [\-F\ \fIformatter\fR] [\-v] [\-c\ \fIfile\fR|\-i\ \fIinstance\fR] [\-k] [\-L] [\-O] [\-o\ \fIsetting\fB=\fIvalue\fR]... [\-S\ \fIsocket\fR] [\-A|\-u\ \fIuser\fR] [\-E] [\-r\ \fIlog_file\fR] [\-U] .ad .hy .\"------------------------------------------------------------------------ .SH DESCRIPTION These commands represent dovecot\'s mailbox synchronization utilities. They can be used for several different use cases: Two\-way synchronization of mailboxes in different servers (via \fBssh\fR(1M)), creating backups of mails to a remote server, and convert mailboxes from/to different mailbox formats. .P The syncing is done as perfectly as possible: an IMAP or a POP3 client shouldn\'t be able to notice any differences between the two mailboxes. Two\-way syncing means that it\'s safe to do any kind of modifications in both sides, and \fBdoveadm\fR will merge the changes without losing any changes done on either side. This is possible because \fBdoveadm\fR can access dovecot\'s index logs that keep track of changes. It is of course possible to have conflicts during merging, these are resolved in a safe way. See the \fBdoveadm\fR\'s \fBdsync\fR design document for more information. .P The utilities can be run completely standalone. It doesn\'t require any dovecot server processes to be running, except when using the \fB\-u\fR parameter to do a \fBuserdb\fR lookup from the related auth process. .P The "\fBsource\fR" of an operation is the currently configured default mail location (dovecot.conf setting \fBmail_location\fR or a corresponding field in the \fBuserdb\fR). One may override it by using the \fB\-o\ mail_location=\fIvalue\fR option. .P The "\fBtarget\fR" of an operation can be set either by the option \fB\-d\fR or the operand \fIlocation2\fR. If the target is not located on the same host, \fBdoveadm\fR spawns an ssh for the related user to thát host (if not explicitly specified via \fIlocation2\fR) to start a dovecot sync server process for it. This one uses of course the dovecot configuration on that host, not the one from the "\fBsource\fR". .P The \fBsync\fR sub command does a two\-way synchronization between two mail locations. Changes in both locations are synchronized to the other one, without loosing any changes made by either of them. Any potential GUID conflicts are resolved by giving them new GUIDs. .P The \fBbackup\fR sub command can be used to backup mails from a certain "\fBsource\fR" to a certain "\fBtarget\fR" (send), or vice versa (receive) by using the option \fB\-R\fR. No changes are ever done to the source location. Any changes in the target location, which cannot be found in the source location, are discarded! .P Currently dovecot can sync only one user at a time. If you want to sync mailboxes for all users, you\'ll need to get a list of all users and execute the utility in question separately for each one. .P Any errors are written to stderr. .\"------------------------------------------------------------------------ .SH OPTIONS Common options: \" ./global-options.inc \" vim: ts=4 sw=4 filetype=nroff .TP .B \-D Enables verbosity and debug messages. .TP .BI \-F\ formatter Specifies the \fIformatter\fR for formatting the output. Supported formatters are: .RS .TP 2 .B flow Prints each line with .IB key = value pairs. .TP .B pager Prints each .IB key = value pair on its own line and separates records with form feed character (\fB^L\fR). .TP .B tab Prints a table header followed by tab separated value lines. .TP .B table Prints a table header followed by adjusted value lines. .RE .TP .B \-v Enables verbosity, including progress counter. \" ./master-options.inc \" vim: ts=4 sw=4 filetype=nroff .TP .BI \-c\ file Read configuration from the given \fIfile\fR. By default \fI/etc/dovecot/dovecot.conf\fR will be used. .TP .BI \-i\ instance Get the configuration from the instance with the name \fIinstance\fR. .TP .B \-k Keep environment, i.e. when executing a new process do not explicitly set the environment variables HOME, USER and when reading configurations, don\'t overwrite currently set environment variables with corresponding settings. Usually used internally, only. .TP .B \-L Log directly. .TP .B \-O Don\'t read settings, but use whatever is in the environment. .TP .BI \-o\ setting = value Overrides the \fIsetting\fR from the current configuration with the given \fIvalue\fR (can be specified multiple times). E.g. with \-o dsync_alt_char=c one is able to overwrite the character to use as an replacement for all invalid characters encountered within a mailbox name (per default \'\fB_\fR'). \" ./mail-options.inc \" vim: ts=4 sw=4 filetype=nroff .TP .BI \-S\ socket The option\'s argument \fIsocket\fR is either an absolute path to a local UNIX domain socket, or a \fIhostname\fB:\fIport\fR pair, in order to connect a remote host via a TCP socket. This allows an administrator to execute .BR doveadm (1M) mail commands through the given socket. .TP .B \-A Run this command for \fBall\fR users. Using this option in combination with system users from .B userdb { driver = passwd } is not recommended, because it contains also users with a lower UID than the one configured with the \fIfirst_valid_uid\fR setting. When the SQL userdb module is used make sure that the \fIiterate_query\fR setting in .I /etc/dovecot/conf.d/sql.conf matches your database layout. When using the LDAP userdb module, make sure that the \fIiterate_attrs\fR and \fIiterate_filter\fR settings in .I /etc/dovecot/conf.d/ldap.conf match your LDAP schema. Otherwise .BR doveadm (1M) will be unable to iterate over \fBall\fR users. .TP .BI \-u\ user Run this command for the specified \fIuser\fR, only. It is also possible to use \'\fB*\fR\' and \'\fB?\fR\' wildcards (e.g. \-u \e*@example.org). When neither the \fB\-A\fR nor \fB\-u\ \fIuser\fR option was specified, this command will be executed with the environment of the currently logged in user, i.e. dovecot will use the value of the environment variable \fBUSER\fR as user name. If it is unset, the command fails. .P Command specific options: .TP .B \-1 The number One implies a oneway backup, i.e. use the two-way syncing algorithm but actually skip any modifications of the "\fBsource\fR" mail location (useful during migration). It effectively turns the \fBsync\fR command into a \fBbackup\fR command. .TP .B \-d Use the user specific \fBmail_replica\fR value as "\fBtarget\fR" mailbox location. If the \fBuserdb\fR does not contain such a setting for the corresponding user or has no value aka empty string, synchronization fails. This option and the \fIlocation2\fR operand are mutually exclusive. .TP .B \-E \fBDon't use\fR. This option will be used by doveadm internally to note that the utility got started in legacy mode, i.e. using the older \fBdsync\fR command, which is still available for backward compatibility (it just converts given options and executes \fBdoveadm sync\ \-E\ ...\fR). .TP .B \-f Run in "full sync" mode rather than "fast sync" mode. In fast sync mode syncing a mailbox might be skipped, if both locations had modified it equally many times (i.e. highest\-modseqs were equal), but with different changes. .TP .BI \-g\ GUID Specifies that the mailbox with the given \fIGUID\fR should be synchronized or from which mails should be converted. An empty string ("") argument indicates, that no mail sync should be done, i.e. sync everything but the actual mails (e.g. mailbox creates, deletes). .TP .BI \-l\ timeout Try max. \fItimeout\fR seconds to obtain a lock for a corresponding mailbox . If a lock cannot be obtained, syncing fails. .TP .BI \-m\ mailbox Specifies the \fImailbox\fR that should be synchronized or from which mails should be converted. The default is to synchronize all respectively convert from all mailboxes. An empty string ("") argument indicates, that no mail sync should be done, i.e. sync everything but the actual mails (e.g. mailbox creates, deletes). .TP .B \-N Sync visible namespaces, only. This option is only valid in conjunction with a mailbox location on a different host. .TP .BI \-n\ ns_prefix Skip any mailbox outside of the namespace with the prefix \fIns_prefix\fR. .TP .B \-P Purge the target\'s disk space of expunged mails after syncing. .TP .B \-R Reverse backup direction, i.e. turn \fIlocation2\fR into the "\fBsource\fR" and the default mail location into the "\fBtarget\fR" so that mails in \fIlocation2\fR are backed up to default mail location. .TP .BI \-r\ file Log to the given \fIfile\fR instead of to the configured default destination . .TP .BI \-s \ state Internally used to describe the state of synchronization. If \fIstate\fR is an empty string ("") and full synchronization is requested, dovecot will use the saved state to find out, what has changed. If no saved state exists or is invalid full synchronization will be done. .TP .B \-U Internally used to indicate an incomming replicator notification or to signal the intent to receive replicator notifications. .TP .BI \-x\ mailbox Exclude the given \fImailbox\fR from syncing. .\"------------------------------------------------------------------------ .SH OPERANDS .TP .I location2 The \fIlocation2\fR parameter defines the "\fBtarget\fR" mail location that is used: If \fIlocation2\fR is on a local filesystem, you can use a regular mail location string, such as maildir:/backup/user/Maildir . If the target is on a remote server, one may use the operand \fIhost\fR or \fIuser\fB@\fIhost\fR. In this case dovecot tries to setup a ssh connection to the corresponding \fIhost\fR and start the \fBdsync-server\fR process. If \fIuser\fR is specified, it gets passed as \fB\-u\fR parameter to the remote command, not to ssh. The ssh username is always the default. If this is not sufficient and one needs more control, one may use the a script or specify the complete command to use to connect to the remote host and start the sync server process (see EXAMPLES below). .\"------------------------------------------------------------------------ .SH EXAMPLES .P Synchronize its own mailboxes with those on the remote server "my.home.org" with debug enabled (if one is not so familiar with terms used in this context, option \-D might help): .RS 3 .nf .B doveadm sync -D my.home.org .fi .RE .P Copy changes of the mailboxes on the remote server "mail.isp.com" to the localhost (mail.isp.com must allow ssh logins and must have dovecot installed of course): .RS 3 .nf .B doveadm backup -R mail.isp.com .fi .RE .P If you need more complex parameters to ssh, you can specify the whole command to connect and start the dsync-server as an operand. E.g. if your login name on the remote host is different (ruser) than on the localhost: .RS 3 .nf \fBdoveadm backup ssh \-i id_dsa.dovecot ruser@example.com \e 'doveadm dsync-server'\fR .fi .RE .SS NOTE .P If an error occurs during synchronization it may happen, that not all file locks are released or messages get duplicated. To fix the file lock problem, one may execute a \fBbackup\fR with the same options. After that, syncing should go through without any error/warning. If in doubt, and to avoid message duplication when synchronizing, always use the \fBbackup\fR command, first in one direction and than in the other using \fBbackup -R\fR. .\"------------------------------------------------------------------------ .SS CONVERTING Assuming that the .I mail_location setting in .I /etc/dovecot/conf.d/10\-mail.conf is set to "\fBmail_location\ =\ mdbox:~/mdbox\fR", a logged in system user may convert her/his mails from its Maildir in her/his home directory to the mdbox mailbox format. The user has to execute the command: .PP .RS 3 .nf .B doveadm sync maildir:~/Maildir .fi .RE .PP If you want to do this without any downtime, you can do the conversion one user at a time. Initially: .RS 2 .IP \(bu 4 Configuration uses .B mail_location = maildir:~/Maildir .IP \(bu Set up the possibility of doing per\-user mail location using .I userdb extra fields. .RE .PP Then for each user: .RS 4 .IP 1. 4 Run .B doveadm sync once to do the initial conversion. .IP 2. Run .B doveadm sync again, because the initial conversion could have taken a while and new changes could have occurred during it. This second time only applies changes, so it should be fast. .IP 3. Update mail extra field in userdb to .BR mdbox:~/mdbox . If you\'re using auth cache, you need to flush it. .IP 4. Wait for a few seconds and then kill the user\'s all existing imap and pop3 sessions (that are still using maildir). .IP 5. Run .B doveadm sync once more to apply final changes that were possibly done. After this there should be no changes to Maildir, because the user\'s mail location has been changed and all existing processes using it have been killed. .RE .PP Once all users have been converted, you can set the default .I mail_location to mdbox and remove the per\-user mail locations from .IR userdb . .\"------------------------------------------------------------------------ .SH "EXIT STATUS" .TP 4 .B 0 Synchronization was done perfectly. .TP .B 2 Synchronization was done without errors, but some changes couldn\'t be done, so the mailboxes aren\'t perfectly synchronized. Running sync again usually fixes this. Typically this occurs for message modification sequences with newly created mailboxes. It can also occur if one of the mailboxes change during the syncing. .TP .B 1, >2 Synchronization failed. .\"------------------------------------------------------------------------ .SH SEE ALSO .BR doveadm (1M), .BR doveadm\-kick (1M), .BR doveconf (1M), .BR dovecot (1M) .\"------------------------------------- .PP Additional resources: .IP "dsync design" http://wiki2.dovecot.org/Design/Dsync .\"------------------------------------------------------------------------ \" ./reporting-bugs.inc .SH REPORTING BUGS Report bugs, including \fBdoveconf \-n\fR output, to the dovecot Mailing List . Information about reporting bugs is available at: http://dovecot.org/bugreport.html