.\" Copyright (c) 2014-2018 Dovecot authors, see the included COPYING file
.TH DOVEADM\-REPLICATOR 1 "2014-10-05" "Dovecot v2.3" "Dovecot"
.SH NAME
doveadm\-replicator \- Manage users\(aq mail replication
.\"------------------------------------------------------------------------
.SH SYNOPSIS
.BR doveadm " [" \-Dv ]
[\fB\-f\fP \fIformatter\fP]
.BI replicator \ command
.RI [ OPTIONS ]\ [ ARGUMENTS ]
.\"------------------------------------------------------------------------
.SH DESCRIPTION
The
doveadm replicator
.I COMMANDS
can be used to manage the automated replication of users\(aq mail.
.\"------------------------------------------------------------------------
.SH OPTIONS
Global
.BR doveadm (1)
.IR options :
.TP
.B \-D
Enables verbosity and debug messages.
.TP
.BI \-f\  formatter
Specifies the
.I formatter
for formatting the output.
Supported formatters are:
.RS
.TP
.B flow
prints each line with
.IB key = value
pairs.
.TP
.B pager
prints each
.IR key :\  value
pair on its own line and separates records with form feed character
.RB ( ^L ).
.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
.BI \-o\  setting = value
Overrides the configuration
.I setting
from
.I /etc/dovecot/dovecot.conf
and from the userdb with the given
.IR value .
In order to override multiple settings, the
.B \-o
option may be specified multiple times.
.TP
.B \-v
Enables verbosity, including progress counter.
.\" --- command specific options --- "/.
.PP
This command uses by default the output formatter
.B flow
(without the
.IR key =
prefix).
.PP
Command specific
.IR options :
.TP
.BI \-a \ replicator_socket_path
This option is used to specify an absolute path to an alternative UNIX
domain socket.
.sp
By default
.BR doveadm (1)
will use the socket
.IR /run/dovecot/replicator\-doveadm .
The socket may be located in another directory, when the default
.I base_dir
setting was overridden in
.IR /etc/dovecot/dovecot.conf .
.\"------------------------------------------------------------------------
.SH ARGUMENTS
.TP
.I user_mask
Specifies for which users the command should be executed.
In most cases you would like to use patterns which contains wildcards,
e.g. \(rs*@example.net for all users of the example.net domain, or simply
\(rs* for all users.
.sp
When the SQL userdb module is used make sure that the
.I iterate_query
setting in
.I /etc/dovecot/dovecot\-sql.conf.ext
matches your database layout.
When using the LDAP userdb module, make sure that the
.IR iterate_attrs " and " iterate_filter
settings in
.I /etc/dovecot/dovecot\-ldap.conf.ext
match your LDAP schema.
Otherwise
.BR doveadm (1)
will be unable to iterate over all users.
.\"------------------------------------------------------------------------
.SH COMMANDS
.SS replicator add
.B doveadm replicator add
[\fB\-a\fP \fIreplicator_socket_path\fP]
.I user_mask
.PP
Add the specified user(s) to the replicator.
If the
.I user_mask
contains \(dq?\(dq or \(dq*\(dq wildcards, the list of usernames is looked
up from the
.IR userdb .
.\"-------------------------------------
.SS replicator dsync\-status
.B doveadm replicator dsync\-status
[\fB\-a\fP \fIreplicator_socket_path\fP]
.PP
Show the status for the currently running dsync processes.
.\"-------------------------------------
.SS replicator remove
.B doveadm replicator remove
[\fB\-a\fP \fIreplicator_socket_path\fP]
.I username
.PP
Remove the specified user from replicator.
.\"-------------------------------------
.SS replicator replicate
.B doveadm replicator replicate
[\fB\-a\fP \fIreplicator_socket_path\fP]
.RB [ \-f ]
[\fB\-p\fP \fIpriority\fP]
.I user_mask
.PP
Start replication for the specified users now.
If the \-f parameter is given, full replication is done for the user.
You can also specify the priority, which can be either
.B high " or " low.
If the user mask contains \(dq?\(dq or \(dq*\(dq wildcards, the list of
usernames is looked up from the users that currently exist in replicator
(not from the
.IR userdb ).
.\"-------------------------------------
.SS replicator status
.B doveadm replicator status
[\fB\-a\fP \fIreplicator_socket_path\fP]
.I user_mask
.PP
Show the replication status for users.
.\"------------------------------------------------------------------------
.SH REPORTING BUGS
Report bugs, including
.I doveconf \-n
output, to the Dovecot Mailing List <dovecot@dovecot.org>.
Information about reporting bugs is available at:
http://dovecot.org/bugreport.html
.\"------------------------------------------------------------------------
.SH SEE ALSO
.BR doveadm (1),
.BR doveadm\-sync (1),
.\"-------------------------------------
.PP
Additional resources:
.IP "Replication with dsync"
http://wiki2.dovecot.org/Replication