dovecot-2.2: man: Reworked dsync.1 and renamed it to doveadm-syn...
dovecot at dovecot.org
dovecot at dovecot.org
Mon Oct 6 13:42:59 UTC 2014
details: http://hg.dovecot.org/dovecot-2.2/rev/b57fe99a69c0
changeset: 17891:b57fe99a69c0
user: Pascal Volk <user at localhost.localdomain.org>
date: Sun Oct 05 20:18:20 2014 +0000
description:
man: Reworked dsync.1 and renamed it to doveadm-sync.1.
diffstat:
.hgignore | 4 +-
doc/man/Makefile.am | 10 +-
doc/man/doveadm-backup.1 | 1 +
doc/man/doveadm-sync.1.in | 361 ++++++++++++++++++++++++++++++++++++++++++++++
doc/man/dsync.1 | 1 +
doc/man/dsync.1.in | 302 --------------------------------------
6 files changed, 371 insertions(+), 308 deletions(-)
diffs (truncated from 742 to 300 lines):
diff -r bf086c6f6e4a -r b57fe99a69c0 .hgignore
--- a/.hgignore Mon Oct 06 13:17:00 2014 +0300
+++ b/.hgignore Sun Oct 05 20:18:20 2014 +0000
@@ -105,5 +105,5 @@
syntax: regexp
src/.*/test-[^\.]*$
-doc/man/doveadm-(acl|altmove|auth|batch|deduplicate|director|dump|exec|expunge|fetch|flags|fts|import|instance|index|force-resync|help|kick|log|mailbox|mount|move|penalty|purge|pw|quota|search|user|who)\.1$
-doc/man/(doveadm|doveconf|dovecot-lda|dovecot|dsync)\.1$
+doc/man/doveadm-(acl|altmove|auth|batch|deduplicate|director|dump|exec|expunge|fetch|flags|fts|import|instance|index|force-resync|help|kick|log|mailbox|mount|move|penalty|purge|pw|quota|search|sync|user|who)\.1$
+doc/man/(doveadm|doveconf|dovecot-lda|dovecot)\.1$
diff -r bf086c6f6e4a -r b57fe99a69c0 doc/man/Makefile.am
--- a/doc/man/Makefile.am Mon Oct 06 13:17:00 2014 +0300
+++ b/doc/man/Makefile.am Sun Oct 05 20:18:20 2014 +0000
@@ -4,10 +4,12 @@
dist_man1_MANS = \
deliver.1 \
+ doveadm-backup.1 \
doveadm-config.1 \
doveadm-copy.1 \
doveadm-reload.1 \
- doveadm-stop.1
+ doveadm-stop.1 \
+ dsync.1
dist_man7_MANS = \
doveadm-search-query.7
@@ -41,12 +43,12 @@
doveadm-pw.1 \
doveadm-quota.1 \
doveadm-search.1 \
+ doveadm-sync.1 \
doveadm-user.1 \
doveadm-who.1 \
doveconf.1 \
dovecot.1 \
- dovecot-lda.1 \
- dsync.1
+ dovecot-lda.1
man_includefiles = \
$(srcdir)/global-options-formatter.inc \
@@ -85,12 +87,12 @@
doveadm-pw.1.in \
doveadm-quota.1.in \
doveadm-search.1.in \
+ doveadm-sync.1.in \
doveadm-user.1.in \
doveadm-who.1.in \
doveconf.1.in \
dovecot.1.in \
dovecot-lda.1.in \
- dsync.1.in \
sed.sh \
$(man_includefiles)
diff -r bf086c6f6e4a -r b57fe99a69c0 doc/man/doveadm-backup.1
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/man/doveadm-backup.1 Sun Oct 05 20:18:20 2014 +0000
@@ -0,0 +1,1 @@
+.so man1/doveadm-sync.1
\ No newline at end of file
diff -r bf086c6f6e4a -r b57fe99a69c0 doc/man/doveadm-sync.1.in
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/man/doveadm-sync.1.in Sun Oct 05 20:18:20 2014 +0000
@@ -0,0 +1,361 @@
+.\" Copyright (c) 2014 Dovecot authors, see the included COPYING file
+.TH DOVEADM\-SYNC 1 "2014-10-05" "Dovecot v2.2" "Dovecot"
+.SH NAME
+doveadm\-sync \- Dovecot\(aqs two\-way mailbox synchronization utility
+.br
+doveadm\-backup \- Dovecot\(aqs one\-way mailbox synchronization utility
+.\"------------------------------------------------------------------------
+.SH SYNOPSIS
+.BR "doveadm sync" " [" \-Dv ]
+[\fB\-u\fP \fIuser\fP|\fB\-A\fP]
+[\fB\-S\fP \fIsocket_path\fP]
+.RB [ \-1fPRU ]
+[\fB\-l\fP \fIsecs\fP]
+[\fB\-r\fP \fIrawlog_path\fP]
+[\fB\-m\fP \fImailbox\fP]
+[\fB\-g\fP \fImailbox_guid\fP]
+[\fB\-n\fP \fInamespace\fP|\fB\-N\fP]
+[\fB\-x\fP \fIexclude\fP]
+[\fB\-s\fP \fIstate\fP]
+\fB\-d\fP|\fIdestination\fP
+.\"-------------------------------------
+.PP
+.BR "doveadm backup" " [" \-Dv ]
+[\fB\-u\fP \fIuser\fP|\fB\-A\fP]
+[\fB\-S\fP \fIsocket_path\fP]
+.RB [ \-fPRU ]
+[\fB\-l\fP \fIsecs\fP]
+[\fB\-r\fP \fIrawlog_path\fP]
+[\fB\-m\fP \fImailbox\fP]
+[\fB\-g\fP \fImailbox_guid\fP]
+[\fB\-n\fP \fInamespace\fP|\fB\-N\fP]
+[\fB\-x\fP \fIexclude\fP]
+[\fB\-s\fP \fIstate\fP]
+\fB\-d\fP|\fIdestination\fP
+.\"------------------------------------------------------------------------
+.SH DESCRIPTION
+dsync is Dovecot\(aqs mailbox synchronization utility.
+It can be used for several different use cases: Two\-way synchronization of
+mailboxes, creating backups of mails, and convert mailboxes from/to
+different mailbox formats.
+All of these can be used within the same server or between different
+servers (via
+.BR ssh (1)
+or tcp connections).
+Remote mailboxes can be accessed also via IMAP protocol, which allows using
+dsync for mailbox migration purposes.
+.PP
+You can run dsync in one of three modes:
+.RS \(bu 4
+.\"-------------------------------------
+.IP \(bu
+.B doveadm backup
+performs one\-way synchronization.
+If there are any changes in the destination they will be deleted, so the
+destination will look exactly like the source.
+.\"-------------------------------------
+.IP \(bu
+.B doveadm sync
+performs two\-way synchronization.
+It merges all changes without losing anything.
+Both the mailboxes will end up looking identical after the synchronization
+is finished.
+.\"-------------------------------------
+.IP \(bu
+.B doveadm sync \-1
+performs one\-way synchronization, but it merges the changes in destination
+without deleting anything.
+This doesn\(aqt currently work perfectly, so its use should be limited.
+Its main purpose is that during mailbox migration you can run
+.B doveadm backup
+multiple times, then switch mails to be delivered to the new mailbox and
+run
+.B doveadm sync \-1
+once more to transfer any last new mails from the old mailbox.
+.\"-------------------------------------
+.RE
+.PP
+There are also three different synchronization algorithms:
+.RS \(bu 4
+.\"-------------------------------------
+.IP \(bu
+Full synchronization (\-f parameter) scans through all the messages in all
+the mailboxes.
+This guarantees that everything will be synchronized, but it\(aqs
+unnecessarily slow for incremental synchronization.
+.\"-------------------------------------
+.IP \(bu
+Fast synchronization (default) first attempts to find mailboxes that have
+changed, and synchronize only those.
+This is done by checking the mailboxes\(aq metadata (NEXTUID and
+HIGHESTMODSEQ).
+Usually this works fine, especially with one\-way synchronization, but if
+both sides do exactly the same number of changes, the metadata may end up
+containing the same values even if the changes were different.
+.\"-------------------------------------
+.IP \(bu
+Stateful synchronization (\-s parameter) is the most efficient way to
+synchronize mailboxes.
+It relies on having the earlier dsync run\(aqs state saved somewhere and
+being passed to the next dsync run.
+Based on this state dsync can send only the changes that happened after the
+previous dsync run.
+As long as the state or the mailboxes aren\(aqt corrupted this algorithm
+should work perfectly.
+The replicator process uses this internally to perform most of the
+synchronization.
+.\"-------------------------------------
+.RE
+.PP
+The syncing is done as perfectly as possible: an IMAP or a POP3 client
+shouldn\(aqt be able to notice any differences between the two mailboxes.
+Two\-way syncing means that it\(aqs safe to do any kind of modifications in
+both sides, and dsync will merge the changes without losing any changes
+done on either side.
+This is possible because dsync can access Dovecot\(aqs index logs that keep
+track of changes.
+It\(aqs of course possible to have conflicts during merging, these are
+resolved in a safe way.
+See the
+.I dsync design
+document for more information.
+.PP
+dsync uses the same configuration files as the rest of Dovecot (via
+.BR doveconf (1)
+binary).
+The entire configuration can be changed by giving \-c parameter to another
+configuration file, or using \-o parameter to override specific settings.
+When executing a remote dsync program it works the same way:
+it uses its own local configuration.
+.PP
+dsync can be run completely standalone.
+It doesn\(aqt require any Dovecot server processes to be running, except
+when using \-u parameter to do a
+.I userdb
+lookup from auth process.
+.PP
+dsync can sync either one or multiple users using the \-u or \-A
+parameters.
+For continuous replication you can use the Dovecot replicator process,
+which automatically runs dsync whenever messages have changed.
+.\"------------------------------------------------------------------------
+ at INCLUDE:global-options@
+.\" --- command specific options --- "/.
+.PP
+Command specific
+.IR options :
+.TP
+.B \-1
+Do one\-way synchronization instead of two\-way synchronization.
+.\"-------------------------------------
+ at INCLUDE:option-A@
+.\"-------------------------------------
+.TP
+.B \-N
+Synchronize all the available namespaces.
+By default only namespaces that don\(aqt have explicit location setting
+are synchronized.
+.\"-------------------------------------
+.TP
+.B \-P
+Run a
+.BR doveadm\-purge (1)
+for the destination (remote) storage after synchronization.
+.\"-------------------------------------
+ at INCLUDE:option-S-socket@
+.\"-------------------------------------
+.TP
+.B \-U
+This is used internally by replicator to have dsync notify it when the
+synchronization is finished.
+.\"-------------------------------------
+.TP
+.B \-d
+Use the default destination, which is looked up from the
+.I mail_replica userdb
+extra field.
+.\"-------------------------------------
+.TP
+.BI \-g \ mailbox_guid
+Same as \-m, but find the mailbox to be synchronized by its GUID instead
+of by name.
+.\"-------------------------------------
+.TP
+.BI \-l \ secs
+Lock the dsync for this user.
+Wait for maximum
+.I secs
+before giving up.
+This parameter should be used to avoid broken synchronization if it\(aqs
+possible that dsync is being run concurrently for the same user.
+.\"-------------------------------------
+.TP
+.BI \-n \ namespace
+Synchronize only the specified namespace.
+This parameter can be used multiple times.
+.\"-------------------------------------
+.TP
+.BI \-r \ rawlog_path
+Running dsync remotely, write the remote input/output traffic to the
+specified log file.
+.\"-------------------------------------
+.TP
+.BI \-s \ previous_state
+Use stateful synchronization.
+If the previous state is unknown, use an empty string.
+The new state is always printed to standard output.
+.\"-------------------------------------
+ at INCLUDE:option-u-user@
+.\"-------------------------------------
+.TP
+.BI \-x \ mailbox_mask
+Exclude the specified mailbox name/mask.
+The mask may contain \(dq\fB?\fP\(dq and \(dq\fB*\fP\(dq wildcards.
+This parameter can be used multiple times.
+.\"------------------------------------------------------------------------
+.SH ARGUMENTS
+.TP
+.I destination
+This argument specifies the synchronized destination.
+It can be one of:
+.RS
+.TP
+location
+Same as
+.I mail_location
+setting, e.g. maildir:\(ti/Maildir
+.TP
+.BI remote: login at host
+Uses
+.I dsync_remote_cmd
+setting to connect to the remote host (usually via ssh)
+.TP
+.I remoteprefix:login at host
More information about the dovecot-cvs
mailing list