DOVEADM-MAIL-FS(1)

✨ NAME ✨

doveadm-mail-fs — literally just vibing with the abstract mail storage filesystem, but in user context. that's it, that's the whole thing 💅

---

🦋 SYNOPSIS 🦋

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

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

---

💅 DESCRIPTION 💅

okay so bestie, the doveadm fs commands are how you abstractly poke at whatever storage driver your Dovecot config has going on. it's giving "I don't need to know how the storage driver was designed, I just want in" ✨ — you get access to the mailbox structure without having to learn the driver's whole lore. no cap.

config-filter-name

this is the filter name used when looking up the fs settings. like, for example mail_attachments, obox, metacache, fts/dovecot. also, plot twist: you can use an empty filter name and just specify the fs settings yourself with the -o parameter. main character energy fr fr 🫶

---

🌈 GLOBAL OPTIONS 🌈

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

• -D — turns on verbosity AND debug messages. the yapper setting 🗣️
• -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. rawdogging the defaults, iconic
• -k — preserve the entire environment for doveadm, not just the import_environment setting
• -v — enables verbosity, including the progress counter. watching that little counter tick is so satisfying ngl
• -i instance-name — if you're running multiple Dovecot instances, this picks the config file based on the 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, 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 stack -o as many times as you want, no judgement 💜
• -f formatter — specifies the formatter for formatting the output. the 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 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 matches your database layout. and when you're on the LDAP userdb module, make sure the userdb_fields setting and the userdb_ldap_iterate_fields setting match your LDAP schema. otherwise doveadm(1) will be straight up unable to iterate over all users. not a vibe.

• -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. this is similar to the -A option, except instead of pulling the user list from the userdb, they get read from the given file. the file contains one username per line. simple as 🍓
• -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), so you can connect to a remote host via a TCP socket. this lets an administrator execute doveadm(1) mail commands through the given socket 🫶

---

👑 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 the source-path to the dest-path. yes it's giving "duplicate my files 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. all of it. gone. 💀

• -R — recursively delete files. go deeper 🌀
• -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 the data associated with the path provided. hand it over 💅

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 the data files in the path provided. every single one. we're thorough here 🧚

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 the directories in the path provided. dirs only, we're being picky 🎀

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. put it there, king 👑

• -h hash — save the provided hash as content hash. must be either MD5 or SHA256 in hexdigits. no other options, periodt.
• -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. so like, check your driver first bestie 🙈

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. that's the whole stat. short and sweet 🍓

---

😭 REPORTING BUGS 😭

found a bug? report it, including the doveconf -n output, to the Dovecot Mailing List ⟨dovecot@dovecot.org⟩. info about reporting bugs lives at: ⟨https://dovecot.org/bugreport.html⟩. don't be shy, they want to know 🫶

---

🍓 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)

---

and that's the whole page bestie, you ate it up 💖 this was doveadm-mail-fs(1) from the Dovecot manual — revision f979264, dated April 2026. go forth and abstractly interact with your storage filesystem, no cap 🌸💅🦋