.\" Copyright (c) 2010-2013 Dovecot authors, see the included COPYING file
.TH DOVEADM\-INDEX 1M "2013-11-23" "Dovecot v2.2" "Dovecot"
.SH NAME
doveadm index \- Index mailboxes
.\"------------------------------------------------------------------------
.SH SYNOPSIS
.nh
.na
.HP
\" ./global-options-short.inc
\" ./master-options-short.inc
\" ./mail-options-short.inc
\fBdoveadm index\fR [\-D] [\-F\ \fIformatter\fR] [\-v] [\-c\ \fIfile\fR|\-i\ \fIinstance\fR] [\-k] [\-L] [\-O] [\-o\ \fIsetting\fB=\fIvalue\fR]...  [\-S\ \fIsocket\fR] [\-A|\-u\ \fIuser\fR] [\-q] [\-n\ \fImax_recent\fR] \fImailbox\fR
.ad
.hy
.\"------------------------------------------------------------------------
.SH DESCRIPTION
Add unindexed messages in a mailbox into index/cache file. If full text
search is enabled, also add unindexed messages to the fts database.
.P
The caching adds only the fields that were previously added to the
mailbox\'s caching decisions, so it won\'t do anything useful for
mailboxes that user\'s client hasn\'t accessed yet. You can use
.B doveadm dump
command to show a specific mailbox\'s current caching decisions.
.P
Messages can also be added automatically to full text search index using

.RS 3
.nf
plugin {
  ...
  fts_autoindex = yes
}
.fi
.RE

in
.IR /etc/dovecot/conf.d/90\-plugin.conf .
.\"------------------------------------------------------------------------
.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').
\" ./mail-options.inc

\" vim: ts=4 sw=4 filetype=nroff
.TP
.BI \-S\  socket
The option\'s argument \fIsocket\fR is either an absolute path to a local UNIX
domain socket, or a \fIhostname\fB:\fIport\fR pair,
in order to connect a remote host via a TCP socket.

This allows an administrator to execute
.BR doveadm (1M)
mail commands through the given socket.

.TP
.B \-A
Run this command for \fBall\fR 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 \fIfirst_valid_uid\fR setting.

When the SQL userdb module is used make sure that the \fIiterate_query\fR
setting in
.I /etc/dovecot/conf.d/sql.conf
matches your database layout.  When using the LDAP userdb module, make sure
that the \fIiterate_attrs\fR and \fIiterate_filter\fR settings in
.I /etc/dovecot/conf.d/ldap.conf
match your LDAP schema.  Otherwise
.BR doveadm (1M)
will be unable to iterate over \fBall\fR users.

.TP
.BI \-u\  user
Run this command for the specified \fIuser\fR, only.  It is also possible to
use \'\fB*\fR\' and \'\fB?\fR\' wildcards (e.g. \-u \e*@example.org).

When neither the \fB\-A\fR nor \fB\-u\ \fIuser\fR option was specified,
this command will be executed with the environment of the currently logged
in user, i.e. dovecot will use the value of the environment variable \fBUSER\fR
as user name. If it is unset, the command fails.

.P
Command specific options:

.TP
.BI \-n \ max_recent
An integer value, which specifies the maximum number of \fBRecent\fR
messages in mailboxes.
If the mailbox contains more than
.I max_recent
messages with \fBRecent\fR flag set, the mailbox will not be indexed.
This may be useful to avoid unnecessary indexing for large mailboxes that
are never opened.

.TP
.B \-q
Queues the indexing to be run by indexer process.
Without \-q the indexing is done directly by the
.BR doveadm (1M)
process.
Some backends like fts\-lucene can\'t handle multiple processes updating
the indexes simultaneously, so \-q should usually be used on production.
.\"------------------------------------------------------------------------
.SH OPERANDS
.TP
.I mailbox
The name of the mailbox to index.
.\"------------------------------------------------------------------------
.SH EXAMPLES
Index bob\'s INBOX:

.RS 3
.nf
.B doveadm index \-u bob INBOX
.fi
.RE
.\"------------------------------------------------------------------------
.SH SEE ALSO
.BR doveadm (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