.\" Copyright (c) 2013 Dovecot authors, see the included COPYING file
.TH DOVEADM\-EXEC 1M "2013-08-05" "Dovecot v2.2" "Dovecot"
.SH NAME
doveadm exec \- easily execute commands from dovecot\'s helpers directory
.\"------------------------------------------------------------------------
.SH SYNOPSIS
.nh
.na
.HP
\" ./global-options-short.inc
\" ./master-options-short.inc
\fBdoveadm exec\fR [\-D] [\-F\ \fIformatter\fR] [\-v] [\-c\ \fIfile\fR|\-i\ \fIinstance\fR] [\-k] [\-L] [\-O] [\-o\ \fIsetting\fB=\fIvalue\fR]...  [\fB\-\-\fR] \fItarget\fR
.ad
.hy
.\"------------------------------------------------------------------------
.SH DESCRIPTION
This command allows administrators and local users to simply execute
commands from within dovecot\'s helpers directory.
So for example a logged in system user could start a pre\-authenticated
imap session, using the command: \fBdoveadm\ exec\ imap\fR.  An administrator
would use the command: \fBdoveadm\ exec\ imap\ \-u\ \fIusername\fR.

To make sure, that non-POSIX compliant implementations of getopt (like GNU
getopt) do not pick up the wrong options one should always add a double-dash
(\-\-) infront of the operands aka \fItarget\fR.
.\"------------------------------------------------------------------------
.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').

.\"------------------------------------------------------------------------
.SH OPERANDS
.TP
.I target
The name of an executable located in dovecot\'s helpers directory which is per
default \fB/usr/lib/dovecot/helpers/\fR, optionally followed by any options and 
operands to be passed through to the binary.
.\"------------------------------------------------------------------------
.SH EXAMPLES
This example demonstrates how to deliver a message from a file to a
user\'s mailbox.

.RS 3
.nf
\fBdoveadm exec -- dovecot\-lda \-d user@example.net \e
	\-f admin@example.net < /stuff/welcome.msg\fR
.fi
.RE
.\"------------------------------------------------------------------------
.SH SEE ALSO
.BR doveadm (1M),
.BR dovecot\-lda (1M)
.\"------------------------------------------------------------------------
\" ./reporting-bugs.inc

.SH REPORTING BUGS
Report bugs, including \fBdoveconf \-n\fR
output, to the dovecot Mailing List <dovecot@dovecot.org>.
Information about reporting bugs is available at:
http://dovecot.org/bugreport.html