Inspect and Safely Change Dovecot's Abstract Storage with doveadm fs

You will finish with a repeatable way to inspect Dovecot's abstract mail storage, copy or add one object, and remove data only after checking the exact path. The commands use the doveadm fs interface, so the storage driver and its arguments come from your Dovecot configuration rather than from a hard-coded filesystem layout.

Allow about fifteen minutes for a read-only inspection, or longer if you need to identify the correct driver settings. You need Dovecot's administrative command and a configured filesystem driver. The examples below use placeholders because fs-driver, fs-args and object paths are deployment-specific. Read-only commands usually need the same account that can read Dovecot's configuration and storage. Use elevated privileges only when your installation's permissions require them, and do not add sudo automatically.

1. Confirm the installed command

Start by checking the package version and the command's own usage. This does not change mail storage:

$ dovecot --version
2.3.21 (47349e2482)
$ dpkg-query -W -f='${Package} ${Version}\n' dovecot-core
dovecot-core 1:2.3.21+dfsg1-2ubuntu6.5
$ doveadm fs
usage: doveadm [-Dv] [-f <formatter>] fs <command> [<args>]

The exact version string and help text vary by package build. On this host, the installed package is Dovecot 2.3.21, while the local compressed manpage is labelled Dovecot v2.3. Keep the local manpage as the contract for the commands in this guide and check the help output before copying a command into a script.

2. Identify the driver and arguments

Every operation takes three storage-specific values: the driver, its argument string, and the object path. The manpage calls these fs-driver, fs-args and path. Do not substitute a normal mail root unless your configuration explicitly defines that as the driver argument.

Inspect the effective configuration with the Dovecot configuration tool and locate the settings for the storage area you intend to use. The names depend on the configured driver. For a command that uses a POSIX driver, a shell shape looks like this:

$ FS_DRIVER='posix'
$ FS_ARGS='/srv/dovecot/objects'
$ ROOT_PATH='customer-a/'
$ printf 'driver=%s\nargs=%s\npath=%s\n' "$FS_DRIVER" "$FS_ARGS" "$ROOT_PATH"
driver=posix
args=/srv/dovecot/objects
path=customer-a/

Those values are examples of shell variables, not universal defaults. Replace them with values from your own configuration. Keep the path separate from the driver arguments: joining them by hand can inspect a different object or expose data from the wrong tenant.

3. List directories and objects before touching data

Use iter-dirs to enumerate directories below a path and iter to enumerate data files. Both are read-only inspection commands:

$ doveadm fs iter-dirs "$FS_DRIVER" "$FS_ARGS" "$ROOT_PATH"
customer-a/index/
customer-a/messages/
$ doveadm fs iter "$FS_DRIVER" "$FS_ARGS" "$ROOT_PATH"
customer-a/messages/00000001
customer-a/messages/00000002

The returned paths are illustrative. Your driver may use different names or return no records. Treat an empty result as a finding, not as permission to guess another path. If the output is hard to scan, the global -f option can choose flow, pager, tab or the default table formatter where that command produces structured records.

4. Inspect size and content

Use stat to retrieve the status of an object. The local manpage documents the current result as the total size in bytes:

$ OBJECT_PATH='customer-a/messages/00000001'
$ doveadm fs stat "$FS_DRIVER" "$FS_ARGS" "$OBJECT_PATH"
driver-specific status output, including the total size in bytes

The exact output and key spelling can vary with the installed build, so treat the result as data rather than parsing a display label without checking it. The local manpage guarantees the total size, not a particular display key. To retrieve the object itself, use get. Redirect it to a new, explicitly named file so an existing local file is not truncated:

$ OUTPUT='/tmp/dovecot-object-check.bin'
$ doveadm fs get "$FS_DRIVER" "$FS_ARGS" "$OBJECT_PATH" > "$OUTPUT"
$ test -s "$OUTPUT" && echo 'retrieved a non-empty object'
retrieved a non-empty object

The output may be binary or otherwise unsuitable for a terminal. Keep it in a restricted temporary location, inspect it with a tool appropriate to its format, and remove it when no longer needed. The retrieval does not modify the Dovecot object.

5. Copy an object without overwriting your source

copy takes one source path and one destination path. Pick a destination that is known to be unused, then verify it:

$ SOURCE_PATH='customer-a/messages/00000001'
$ DEST_PATH='customer-a/recovery/00000001'
$ doveadm fs copy "$FS_DRIVER" "$FS_ARGS" "$SOURCE_PATH" "$DEST_PATH"
$ doveadm fs stat "$FS_DRIVER" "$FS_ARGS" "$DEST_PATH"
driver-specific status output, including the total size in bytes

A successful command is not a substitute for checking the destination. Compare its status with the source and use get if you need to verify content. Copying creates storage state, so record the destination if you need to remove this test later. There is no general undo command: recovery is another explicit copy or a restore from your storage backup.

6. Add data with put, then verify it

Prepare a local input file without changing the Dovecot object first. The put command takes the input path followed by the destination object path:

$ INPUT_PATH='/srv/recovery/00000001.bin'
$ DEST_PATH='customer-a/recovery/00000001'
$ test -r "$INPUT_PATH" || { echo 'input is not readable' >&2; exit 1; }
$ doveadm fs put "$FS_DRIVER" "$FS_ARGS" "$INPUT_PATH" "$DEST_PATH"
$ doveadm fs stat "$FS_DRIVER" "$FS_ARGS" "$DEST_PATH"
total-size=18432

Do not assume that put is append-only. An existing destination may be replaced according to the driver implementation. Use a new path for a first test, and preserve the source until the result has been checked. If the operation fails, leave the source in place and investigate the error before retrying.

7. Delete only an identified object

$ printf 'about to delete: driver=%s args=%s path=%s\n' "$FS_DRIVER" "$FS_ARGS" "$DEST_PATH"
about to delete: driver=posix args=/srv/dovecot/objects path=customer-a/recovery/00000001
$ doveadm fs delete "$FS_DRIVER" "$FS_ARGS" "$DEST_PATH"
$ doveadm fs stat "$FS_DRIVER" "$FS_ARGS" "$DEST_PATH"
object not found

The final error text is driver-specific; a non-zero status or a missing-object result is the useful check. The default delete operation is not recursive. The -R option explicitly enables recursive deletion, and -n count limits parallel operations. Avoid both until you have a tested recovery plan, and never use -R on a path copied from an unvalidated variable.

8. Use diagnostics without changing the operation

Global -D enables debug messages and -v enables verbose output including a progress counter. Use them when a read or write fails, but review the output for paths and other sensitive storage details before sharing it:

$ doveadm -D -v fs stat "$FS_DRIVER" "$FS_ARGS" "$OBJECT_PATH"
$ printf 'exit status: %s\n' "$?"
exit status: 0

Global -o setting=value overrides configuration for that invocation and can be supplied more than once. Treat it as a configuration change for the command, not as a harmless display option. Test overrides against a disposable object and record them with the command used.