.\" Copyright (c) 2013-2018 Dovecot authors, see the included COPYING file
.TH DOVEADM\-BATCH 1 "2015-05-09" "Dovecot v2.3" "Dovecot"
.SH NAME
doveadm\-batch \- Execute multiple commands for multiple users
.\"------------------------------------------------------------------------
.SH SYNOPSIS
.BR doveadm " [" \-Dv "] " batch " [" \-S
.IR socket_path "] "
.BI \-A " sep command sep command"
[...]
.br
.\"-------------------------------------
.BR doveadm " [" \-Dv "] " batch " [" \-S
.IR socket_path "] "
.BI \-F " file sep command sep command"
[...]
.br
.\"-------------------------------------
.BR doveadm " [" \-Dv "] " batch " [" \-S
.IR socket_path "] "
.BI \-u " usermask sep command sep command"
[...]
.\"------------------------------------------------------------------------
.SH DESCRIPTION
The command
.B doveadm batch
is used to execute multiple
.BR doveadm (1)
.IR command s
sequentially for multiple users.
This is primarily an optimization where Dovecot can do all the mailbox
operations for the same user at once, instead of having to go through
the users multiple times.
.PP
In the first form
.BR doveadm (1)
will loop over all users, defined in the configured
.IR user_db (s),
and execute the sequence of
.IR command s
for each of them.
.PP
In the second form
.BR doveadm (1)
will loop over all users, listed in the given
.IR file .
.PP
In the third form the
.IR command s
will be executed for each user matching the given
.IR usermask .
.\"------------------------------------------------------------------------
@INCLUDE:global-options@
.\" --- command specific options --- "/.
.PP
Command specific
.IR options :
.\"-------------------------------------
@INCLUDE:option-A@
.\"-------------------------------------
@INCLUDE:option-F-file@
.\"-------------------------------------
@INCLUDE:option-S-socket@
.\"-------------------------------------
@INCLUDE:option-u-user@
.\"------------------------------------------------------------------------
.SH ARGUMENTS
.TP
.I command
Any
.BR doveadm (1)
command, with arguments and options \(em except for the
.BR \-A ", " \-S " and " \-u " options."
.\"-------------------------------------
.TP
.I sep
A single character used as command separator, e.g. \(aq:\(aq.
Be careful, unquoted characters, like
.BR ; " or " & ,
may be interpreted by your shell and
.BR doveadm (1)
will never see them.
.\"------------------------------------------------------------------------
.SH EXAMPLE
In this example we move seen mails, older than one month, for all
example.net users to the alternative storage under /nfsmount:
.br
.nf
mail_location = mdbox:~/mdbox:ALT=/nfsmount/%h/mdbox
.fi
The second command will remove messages with refcount=0 from the
primary storage.
.PP
.nf
.ft B
doveadm batch \-u \(rs*@example.net : altmove seen savedbefore 30d : purge
.ft P
.fi
.\"------------------------------------------------------------------------
@INCLUDE:reporting-bugs@
.\"------------------------------------------------------------------------
.SH SEE ALSO
.BR doveadm (1)