doveadm-metacache

NAME

doveadm-metacache - Utility actions for Dovecot’s local metacache storage

SYNOPSIS

doveadm [GLOBAL OPTIONS] metacache command [arguments]

DESCRIPTION

doveadm metacache can be used to run actions that interact with and modify Dovecot’s local metacache storage.

GLOBAL OPTIONS

Global doveadm(1) options:

-D

Enables verbosity and debug messages.

-O

Do not read any config file, just use defaults.

-k

Preserve entire environment for doveadm, not just import_environment.

-v

Enables verbosity, including progress counter.

-i instance-name

If using multiple Dovecot instances, choose the config file based on this instance name. See instance_name setting for more information.

-c config-file

Read configuration from the given config-file. By default it first reads config socket, and then falls back to /etc/dovecot/dovecot.conf. You can also point this to config socket of some instance running compatible version.

-o setting=value

Overrides the configuration setting from /etc/dovecot/dovecot.conf and from the userdb with the given value. In order to override multiple settings, the -o option may be specified multiple times.

-f formatter

Specifies the formatter for formatting the output. Supported formatters are:

flow

prints each line with key=value pairs.

pager

prints each key: value pair on its own line and separates records with form feed character (^L).

tab

prints a table header followed by tab separated value lines.

table

prints a table header followed by adjusted value lines.

OPTIONS

-A

If the -A option is present, the command will be performed for all users. Using this option in combination with system users from userdb { driver = passwd } is not recommended, because it contains also users with a lower UID than the one configured with the first_valid_uid setting.

When the SQL userdb module is used make sure that the iterate_query setting in /etc/dovecot/dovecot-sql.conf.ext matches your database layout. When using the LDAP userdb module, make sure that the iterate_attrs and iterate_filter settings in /etc/dovecot/dovecot-ldap.conf.ext match your LDAP schema. Otherwise doveadm(1) will be unable to iterate over all users.

-F file

Execute the command for all the users in the file. This is similar to the -A option, but instead of getting the list of users from the userdb, they are read from the given file. The file contains one username per line.

-S socket_path

The option’s argument is either an absolute path to a local UNIX domain socket, or a hostname and port (hostname:port), in order to connect a remote host via a TCP socket.

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

-u user/mask

Run the command only for the given user. It’s also possible to use ‘*’ and ‘?’ wildcards (e.g. -u *@example.org).

PRIORITIES

There are 4 priorities for index files:

  1. User root indexes (highest priority)

  2. FTS indexes

  3. INBOX and \Junk folder indexes

  4. other folders’ indexes (lowest priority)

COMMANDS

metacache clean

doveadm metacache clean [-A|-u user|-F file] [-S socket_path] [-d days] [-p min_priority] [ namespace ]

Cleans old indexes for given users. If the indexes have not been flushed yet this command will fail.

-d

Cleans metacache only if it hasn’t been modified for specified number of days.

-p

Cleans metacache for given priority for the specified user(s).

metacache flush

doveadm metacache flush [-A|-u user|-F file] [-S socket_path] [-p min_priority] [-i] [ namespace ]

Flushes metacache to storage for the given user(s).

-p

Only flush changes that have at least min_priority. See PRIORITIES for the various priorities you can use.

-i

Only flush important changes.

metacache flushall

doveadm metacache flushall [-a metacache_socket_path] [-f userdb_field] [-i] [ user mask ]

Flush all matching users to storage. If no mask is specified, everything is flushed. WARNING: This can be expensive and long operation.

-a

Specify alternative metacache socket. Not usually needed.

-f

Use given field to match userdb. By default it’s username

-i

Only flush important changes.

metacache list

doveadm metacache list [-a metacache_socket_path] [ -f userdb_field ] [ user mask ]

List current metacache for matching users. If no mask is specified, lists all users’ metacache.

Output will contain

  • The primary username

  • Alternative usernames, if configured by returning user_* extra fields from userdb

  • This corresponds to the metacache_upload_interval setting.

  • Filesystem device where the user is located in. Filesystems are separately tracked by metacache, although currently support for multiple filesystems doesn’t work as well as it could.

  • Disk space used by index files of this priority in metacache.

  • UNIX timestamp of when the index files of this priority were last accessed in metacache.

  • “none” means the index files have no changes done locally since they were downloaded. “unimportant” means there are some changes, but nothing that couldn’t be regenerated if the server crashed. “important” means that there are changes that would be lost in case of a server crash. Currently the only important change is flag changes.

  • Last service that accessed this user. Note that metacache clean and flush operations (via metacache-worker or doveadm) won’t update this field.

  • Currently calculated weight when these indexes are cleaned up. Smaller numbers are cleaned up before larger numbers. Sorting the list output (with |sort -n) by this field will show the order in which the indexes would be cleaned. The cleanup weights are recalculated whenever the indexes are being accessed.

-a

Specify alternative metacache socket. Not usually needed.

-f

Use given field to match userdb. By default it’s username

metacache refresh

doveadm metacache refresh [-A|-u user|-F file] [-S socket_path] [ namespace ]

Force refreshing metacache for the given user(s) the next time it’s opened. The refresh is done for the user root index and all the folders.

metacache remove

doveadm metacache remove [-a metacache_socket_path] user mask

Remove metacache for matching users from metacache process. Mask is required parameter.

-a

Specify alternative metacache socket. Not usually needed.

metacache status

doveadm metacache status [-a metacache_socket_path] [ –roots ] [ -b ]

Print statistics about metacache usage.

–roots

Group the results by storage device instead than by time

-b

Force the result to be shown in bytes.

metacache update userdb

doveadm metacache update userdb [-a metacache_socket_path] username userdb_field value

Update alternative usernames (user_* fields) in doveadm metacache list output.

metacache unpack

doveadm metacache unpack bundle_file destination_dir

Unpack given bundle from storage to a given directory.

metacache pull

doveadm metacache pull [-A|-u user] [-S socket_path] [—latest-only] [—clean] source_backend_host

Pull all metacache for given user(s) from source backend host.

–clean

Metacache is cleaned for the user(s) that have been successfully pulled.

–latest-only

Pulling fails if there are newer bundles in storage than at source backend host.

EXAMPLE

Some examples

doveadm metacache flush -u user@domain

REPORTING BUGS

Report bugs, including doveconf -n output, to the Dovecot Mailing List <dovecot@dovecot.org>. Information about reporting bugs is available at: https://dovecot.org/bugreport.html

SEE ALSO

doveadm(1) doveadm-obox(1)