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:
User root indexes (highest priority)
FTS indexes
INBOX and \Junk folder indexes
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