doveadm-metacache(1) - 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. The dovecot_storage_version defaults to the latest version, but can be overridden with -o.

-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 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.

json

prints a JSON array of JSON objects.

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 userdb_sql_iterate_query setting matches your database layout.

When using the LDAP userdb module, make sure that the userdb_fields and userdb_ldap_iterate_fields settings 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.

--no-userdb-lookup

Do not perform userdb lookup. Use the USER environment variable to specify the username.

-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 [GLOBAL OPTIONS] metacache clean [-A | -u user | -F file | --no-userdb-lookup] [-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 [GLOBAL OPTIONS] metacache flush [-A | -u user | -F file | --no-userdb-lookup] [-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 [GLOBAL OPTIONS] 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 an 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 [GLOBAL OPTIONS] metacache list [ -a metacache_socket_path ] [ -f userdb_field ] [ -W ] [ --keyvalues ] [ user mask ]

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

If --keyvalues is given, the matching users' key-value database is written.

Otherwise, 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.

-W

If set, warns if the userdb field is not found.

metacache refresh

doveadm [GLOBAL OPTIONS] metacache refresh [-A | -u user | -F file | --no-userdb-lookup] [-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 pull

doveadm [GLOBAL OPTIONS] metacache pull [-A | -u user | -F file | --no-userdb-lookup] [-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. Cleaning is done asynchronously on the server after the client has already exited.

--latest-only

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

metacache remove

doveadm [GLOBAL OPTIONS] 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 rescan

doveadm [GLOBAL OPTIONS] metacache rescan [-a metacache_socket_path]

Triggers an explicit metacache rescan, which makes sure the disk space usage tracked by metacache process matches what really exists on filesystem.

-a

Specify alternative metacache socket. Not usually needed.

metacache status

doveadm [GLOBAL OPTIONS] metacache status [-a metacache_socket_path] [--roots | --oldest-safe-timestamp] [-b]

Print statistics about metacache usage.

--roots

Group the results by storage device instead than by time

--oldest-safe-timestamp

Output the oldest safe timestamp. Any indexes accessed before that may or may not be corrupted, but indexes after that are known not to be corrupted.

-b

Force the result to be shown in bytes.

metacache update userdb

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

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

metacache unpack

doveadm [GLOBAL OPTIONS] metacache unpack [--bundle-name bundle_name] bundle_file destination_dir

Unpack given bundle from storage to a given directory.

--bundle-name

The bundle name to use. By default, tries to extract name from the bundle.

EXAMPLE

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)