.\" 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 .
.\"------------------------------------------------------------------------
.SH OPTIONS
Global
.BR doveadm (1)
.IR options :
.TP
.B \-D
Enables verbosity and debug messages.
.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
Command specific
.IR options :
.\"-------------------------------------
.TP
.B \-A
If the
.B \-A
option is present, the
.I command
will be performed for all 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
.I first_valid_uid
setting.
.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.
.\"-------------------------------------
.TP
.BI \-F\  file
Execute the
.I command
for all the users in the
.IR file .
This is similar to the
.B \-A
option,
but instead of getting the list of users from the userdb,
they are read from the given
.IR file .
The
.I file
contains one username per line.
.\"-------------------------------------
.TP
.BI \-S\  socket_path
The option\(aqs argument is either an absolute path to a local UNIX domain
socket, or a hostname and port
.RI ( hostname : port ),
in order to connect a remote host via a TCP socket.
.sp
This allows an administrator to execute
.BR doveadm (1)
mail commands through the given socket.
.\"-------------------------------------
.TP
.BI \-u\  user/mask
Run the
.I command
only for the given
.IR user .
It\(aqs also possible to use
.RB \(aq * \(aq
and
.RB \(aq ? \(aq
wildcards (e.g. \-u *@example.org).
.br
When neither the
.B \-A
option, nor the
.BI \-F\  file
option, nor the
.BI \-u\  user
was specified, the
.I command
will be executed with the environment of the
currently logged in 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
.\"------------------------------------------------------------------------
.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)