DOVEADM-FS(1)

💖 DOVEADM-FS(1) 💖

okay bestie, welcome to doveadm-fs — it's part of the Dovecot fam (you know, the mail server situation 👑) and it's literally your little backstage pass to the abstract mail storage filesystem. let's get into it 🦋

---

✨ NAME ✨

doveadm-fs — interact with the abstract mail storage filesystem. no cap, that's the whole vibe.

---

🌸 SYNOPSIS 🌸

doveadm [GLOBAL OPTIONS] fs command config-filter-name [ARGUMENTS]

doveadm [GLOBAL OPTIONS] mail fs command [OPTIONS] config-filter-name
[ARGUMENTS]

---

💅 DESCRIPTION 💅

so the doveadm fs commands are how you abstractly poke at the storage driver that's defined in your Dovecot config. it's giving "I don't need to know how the storage driver was designed internally, I just want in." you get access to the mailbox structure without having to care about the driver's whole lore. obsessed 😭

config-filter-name

filter name to use when looking up the fs settings. for example: mail_attachments, obox, metacache, fts/dovecot. and yes babes, you can also use an empty filter name and just specify the fs settings with the -o parameter instead. main character energy honestly.

---

🌈 GLOBAL OPTIONS 🌈

these are the global doveadm(1) options, iykyk:

• -D — enables verbosity and debug messages. turn it on when you need to see everything 🔍
• -O — do NOT read any config file, just use defaults. the dovecot_storage_version setting defaults to the latest version, but you can override it with -o.
• -k — preserve the entire environment for doveadm, not just the import_environment setting.
• -v — enables verbosity, including a progress counter. lil dopamine bar ✨
• -i instance-name — if you're running multiple Dovecot instances, pick the config file based on this instance name. see the instance_name setting for more info.
• -c config-file — read configuration from the given config-file. by default it first reads the config socket, and then falls back to /etc/dovecot/dovecot.conf. you can also point this at the config socket of some instance running a compatible version 👀
• -o setting=value — overrides the configuration setting from /etc/dovecot/dovecot.conf and from the userdb with the given value. wanna override multiple settings? just specify -o multiple times, she's flexible 💁
• -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 with system users from userdb { driver = passwd } is not recommended, because it also contains users with a lower UID than the one configured with the first_valid_uid setting. when the SQL userdb module is used, make sure the userdb_sql_iterate_query setting setting matches your database layout. when using the LDAP userdb module, make sure the userdb_fields setting and userdb_ldap_iterate_fields setting settings match your LDAP schema. otherwise doveadm(1) will be unable to iterate over all users. 😭
• -u user/mask — run the command only for the given user. you can also use '*' and '?' wildcards (e.g. -u *@example.org). slay 🦋
• -F file — execute the command for all the users in the file. similar to the -A option, but instead of getting the list of users from the userdb, they're 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 lets an administrator execute doveadm(1) mail commands through the given socket.

fr fr reminder: -A over a passwd userdb will sweep in low-UID system users, and LDAP/SQL setups need their iterate settings matched up or the whole thing just... won't. 💀

---

👑 COMMANDS 👑

copy

doveadm [GLOBAL OPTIONS] fs copy config-filter-name source-path dest-
path

doveadm [GLOBAL OPTIONS] mail fs copy [-A | -u user | -F file] [-S
socket_path] config-filter-name source-path dest-path

copy source path to the destination path. simple as that, bestie 💅

delete

doveadm [GLOBAL OPTIONS] fs delete [-R] [-n count] config-filter-name
path [path ...]

doveadm [GLOBAL OPTIONS] mail fs delete [-A | -u user | -F file] [-S
socket_path] [-R] [-n count] config-filter-name path [path ...]

delete all data associated with the path provided.

• -R — recursively delete files. 🔥
• -n count — maximum number of parallel operations to perform.

get

doveadm [GLOBAL OPTIONS] fs get config-filter-name path

doveadm [GLOBAL OPTIONS] mail fs get [-A | -u user | -F file] [-S
socket_path] config-filter-name path

retrieve data associated with the path provided. go get it 🫶

iter

doveadm [GLOBAL OPTIONS] fs iter config-filter-name path

doveadm [GLOBAL OPTIONS] mail fs iter [-A | -u user | -F file] [-S
socket_path] config-filter-name path

iterate through all data files in the path provided. one by one, no skips 🌈

iter-dirs

doveadm [GLOBAL OPTIONS] fs iter-dirs config-filter-name path

doveadm [GLOBAL OPTIONS] mail fs iter-dirs [-A | -u user | -F file] [-S
socket_path] config-filter-name path

iterate through all directories in the path provided. the dirs get their moment too 💜

put

doveadm [GLOBAL OPTIONS] fs put [-h hash] [-m key=value] config-filter-
name input_path path

doveadm [GLOBAL OPTIONS] mail fs put [-A | -u user | -F file] [-S
socket_path] [-h hash] [-m key=value] config-filter-name path

store data at the path provided. drop it right in there ✨

• -h hash — save provided hash as content hash. must be either MD5 or SHA256 in hexdigits.
• -m key=value — assign a value to a metadata. can be provided as many times as needed. requires either metawrap as driver or a metadata capable FS-driver.

stat

doveadm [GLOBAL OPTIONS] fs stat config-filter-name path

doveadm [GLOBAL OPTIONS] mail fs stat [-A | -u user | -F file] [-S
socket_path] config-filter-name path

retrieve files status for the path provided. currently, only the total size (in bytes) of the item is returned. just the size bestie, don't ask for more 🙈

---

🐛 REPORTING BUGS 🐛

found a bug? report it — including doveconf -n output — to the Dovecot Mailing List ⟨dovecot@dovecot.org⟩. info about reporting bugs lives at: ⟨https://dovecot.org/bugreport.html⟩. we love a reproducible issue report 💖

---

⭐ EXAMPLE ⭐

how to decompress a file:

doveadm -o fs=compress,posix -o fs/compress/fs_driver=compress -o fs/posix/fs_driver=posix -o fs_posix_prefix=/tmp/ fs get "" test.gz

using a named filter:

doveadm mail fs -u testuser get obox path/to/file

---

🧚 SEE ALSO 🧚

doveadm(1) — go read it, she's the parent page 💫

---

and that's the whole page bestie!! 🎀 this one came from the Dovecot fam, tagged f979264 and dated April 2026 — you're all caught up, now go interact with that storage filesystem responsibly 💅✨