CTL_MBOXLIST(8)

📦
version 3.12.4 · 6 versions
, in fedora 44

💖 CTL_MBOXLIST 💖

okay bestie, sit down, hydrate, because today we're talking about ctl_mboxlist from the Cyrus IMAP docs. she's a section 8 girlie (that means admin commands, iykyk) and she does operations on the mailbox list database. yes. THE mailbox list database. the whole vibe. 🎀

✨ NAME ✨

ctl_mboxlist — Cyrus IMAP documentation. perform operations on the mailbox list database. that's the whole job description, and she does it flawlessly. 💅

🌸 SYNOPSIS 🌸

ctl_mboxlist [ -C config-file ] -d [ -x ] [-y] [ -p partition ] [ -f filename ]
ctl_mboxlist [ -C config-file ] -u [ -f filename ] [ -L ]
ctl_mboxlist [ -C config-file ] -m [ -a ] [ -w ] [ -i ] [ -f filename ]
ctl_mboxlist [ -C config-file ] -v [ -f filename ]

four whole modes, four whole moods. pick your fighter. 🦋

💜 DESCRIPTION 💜

ctl_mboxlist is your girl for doing various administrative operations on the mailbox list database. she's not here to chat, she's here to work.

here's the tea: ctl_mboxlist reads her configuration options out of the imapd.conf(5) file — unless you tell her otherwise with -C. and the configdirectory option inside imapd.conf(5)? that's what decides the default location of the mailboxes database. so if you're ever like "where does she even look" — that's the answer, bestie. 🫶

💅 OPTIONS 💅

  • -C config-file — use the config file you specify, config-file, instead of the default imapd.conf(5). main character energy: she'll read whatever you hand her. 👑
  • -d, --dump — dump the contents of the database to standard output in JSON format. iconic. structured. slay.
  • -x, --remove-dumped — when you're doing a dump, remove the mailboxes that got dumped from the mailbox list. mostly useful when you use it together with -p. she takes them OUT. ✨
  • -y, --include-intermediaries — when dumping, also list the intermediary mailboxes — the ones that would normally be hidden from IMAP. no more secrets, bestie. 🙈
  • -p partition, --partition=partition — when dumping, only dump the mailboxes that live on partition. one neighborhood only. 🏡
  • -f filename, --filename=filename — use the database named by filename instead of the default (configdirectory/mailboxes.db*). your file, your rules. 🎀
  • -L, --legacy — when undumping, use the legacy dump parser instead of the JSON parser. this might be useful if you're importing a dump produced by an older version of Cyrus. throwback era, but make it functional. ⭐
  • -u, --undump — load (aka "undump") the contents of the database from standard input. the input MUST be a valid JSON file, unless you also pass -L.
IMPORTANT: USE THIS OPTION WITH CARE. 😭 if you modified the dump file since it was dumped, or if the file wasn't produced by -d in the first place, or if it was produced on a different server — you can easily break your mailboxes.db. Undump will refuse to process a syntactically-invalid dump file, but it can't do much to protect you from a valid file containing bad data. it's giving "trust me bro" and you should NOT trust it, fr fr. 💀
  • -m, --sync-mupdate — for backend servers in the Cyrus Murder, synchronize the local mailbox list file with the MUPDATE server. keeping everybody on the same page. literally. 🌈
  • -a, --authoritative — when used with -m, assume the local mailboxes file is authoritative. meaning: only change the mupdate server, do not delete any local mailboxes.
IMPORTANT: USE THIS OPTION WITH CARE, because it allows namespace collisions into the murder. yeah. that. be careful, bestie. 😭
  • -w, --warn-only — when used with -m, print out what would be done but do not actually perform the operations. a dress rehearsal, a mood board, a dry run. 🦋
  • -i, --interactive — when used with -m, she asks for verification before deleting local mailboxes. consent first, always. 🫶
  • -v, --verify — verify the consistency of the mailbox list database and the spool partition(s). here's what gets reported: mailboxes present in the database and not located on a spool partition, AND those located on a spool partition (directory containing a valid cyrus.header file) and not present in the database. note that this function is very I/O intensive. she's gonna be working hard, ok, be nice to her. 🔥

🌟 EXAMPLES 🌟

ctl_mboxlist -d

dump the mailboxes list to standard output in JSON format. chef's kiss. ✨

ctl_mboxlist -u < newmboxlist.dump

undump (restore) the mailboxes database from newmboxlist.dump, where newmboxlist.dump is a JSON file produced by ctl_mboxlist -d.

NOTE: be very careful with this option. like, VERY careful. 😭
ctl_mboxlist -m

synchronize our mailboxes database with the MUPDATE server. (one may commonly put a command like this into the START section of cyrus.conf(5) on backend nodes of a Murder cluster, to cause the backend to synchronize its mailbox list with the mupdate master upon startup). set it and forget it, but like, responsibly. 👑

ctl_mboxlist -m -w

the same as above, but only show us what would be done. don't actually do it. peek, don't touch. 🙈

ctl_mboxlist -m -a

populate the Mupdate server from our copy of the mailboxes database.

NOTE: be very careful with this option, because it can create conflicts in the Murder. 🫠
ctl_mboxlist -m -i

synchronize our mailboxes database with the MUPDATE server interactively, asking for verification before deleting any local mailboxes. polite AND effective. 💅

🎀 FILES 🎀

  • /etc/imapd.conf
  • <configdirectory>/mailboxes.db

these are her hangout spots. 🌸

🦋 SEE ALSO 🦋

go read those too, bestie, they're part of the lore. 💜

🌈 AUTHOR 🌈

The Cyrus Team, Nic Bernstein (Onlight), Jeroen van Meeuwen (Kolab Systems). absolute legends, no cap. 👑

1993–2026, The Cyrus Team.

and that's the whole page!! you ate that. 🍓

this was Cyrus IMAP ctl_mboxlist, version 3.12.4, dated Sep 09, 2026 — periodt, go dump responsibly, mwah 💖✨🎀

📦 where this page comes from