CTL_BACKUPS(8)

📦
version 3.10.4 · 8 versions
, in fedora 43

💖 CTL_BACKUPS — the ctl_backups(8) page, but make it cute 💖

okay bestie, welcome to ctl_backups, section 8 of the Cyrus IMAP manual. this is the girl who does administrative operations directly on Cyrus backups and she's very good at her job. come sit with me 🫶

✨ NAME ✨

ctl_backups — Cyrus IMAP documentation, and also the tool that does administrative operations directly on Cyrus backups. no middleman, no drama, just vibes 💅

✨ SYNOPSIS ✨

ctl_backups [OPTIONS] compact [MODE] backup...
ctl_backups [OPTIONS] list [LIST OPTIONS] [[MODE] backup...]
ctl_backups [OPTIONS] lock [LOCK OPTIONS] [MODE] backup
ctl_backups [OPTIONS] reindex [MODE] backup...
ctl_backups [OPTIONS] stat [MODE] backup...
ctl_backups [OPTIONS] verify [MODE] backup...

like, six whole sub-commands, one icon 🎀

✨ DESCRIPTION ✨

⚠️ NOTE, and I need you to actually read this one bestie: Cyrus Backups are experimental, incomplete, and deprecated as of 3.10. she's a legacy queen. we love her but she's retired.

ctl_backups is a tool for performing administrative operations on Cyrus backups. that's the whole job description, periodt.

ctl_backups reads its configuration options out of the imapd.conf(5) file unless you tell it otherwise with -C. so unless you say something, she's reading her settings from imapd.conf(5). lowkey considerate.

In all invocations, backup is interpreted according to the specified MODE. that's a big deal — check the Modes section below, don't skip it, i'm watching 👀

ctl_backups provides the following sub-commands:

  • compact — Reduce storage required by the named backups. her whole behaviour gets influenced by the backup_compact_minsize, backup_compact_maxsize, backup_compact_work_threshold, and backup_retention_days configuration settings — see imapd.conf(5) for the deets.

This should generally be invoked regularly, like by adding an entry to the EVENTS section of cyrus.conf(5). there's a whole example down in Examples if you want the recipe 🍓

If the backup_keep_previous configuration setting is enabled, compact will preserve the original data and index files (renaming them with a timestamp). this is useful for debugging — she keeps receipts, iconic 💅

  • list — List backups. See List Options for options specific to the list sub-command. Columns are separated by tabs, and are:
    • end time of latest chunk
    • size of backup data file on disk
    • userid to which the backup belongs
    • path to backup data file

If no mode or backups are specified, she lists all known backups (as if invoked with the -A mode). queen of defaults 👑

  • lock — Obtain and hold a lock on the named backup. Useful for operating on Cyrus backup files using non-Cyrus tools (such as UNIX tools or custom scripts) in relative safety. See Lock Options for details. she's basically a bodyguard 🫶
  • reindex — Rebuild the indexes for the named backups, based on the raw backup data. useful if their index files have been corrupted, or if the index format has changed. glow-up era ✨

If the backup_keep_previous configuration setting is enabled, reindex will preserve the original index file (renaming it with a timestamp). useful for debugging.

  • stat — Display stats for the named backups. Columns are separated by tabs, and are:
    • userid or filename
    • compressed (i.e. on disk) size
    • uncompressed size
    • compactable size
    • compression ratio
    • utilisation ratio
    • start time of latest chunk
    • end time of latest chunk

The compactable size is an approximation of how much uncompressed data would remain after compact is performed. The utilisation ratio is this figure expressed as a percentage of the uncompressed size. Note that this approximation is an underestimate. That is to say, a backup that has just been compacted will probably still report less than 100% utilisation. she's humble like that, don't read into it 😭

  • verify — Verify consistency of the named backups by performing deep checks on both the raw backup data and its index. the vibe check of vibe checks 🧚

✨ OPTIONS ✨

  • -C config-file — Use the specified configuration file config-file rather than the default imapd.conf(5). your config, your rules 💅
  • -F, --force — Force the operation to occur, even if it is determined to be unnecessary. This is mostly useful with the compact sub-command. she said "i'm doing it anyway" 🔥
  • -S, --stop-on-error — Stop-on-error. With this option, if a sub-command fails for any particular backup, ctl_backups will immediately exit with an error, without processing further backups.

The default is to log the error, and continue with the next backup. so default her = forgiving, -S her = zero tolerance 💀

  • -V, --no-verify — Don't verify backup checksums for read-only operations.

The read-only operations list and stat will normally perform a "quick" verification of the backup file being read, which checks the checksums of the most recent chunk. This can be slow for backups whose most recent backup chunk is very large.

With this option, the verification step will be skipped. skipping the check-in, no cap 🦋

  • -j, --json — Produce output in JSON format. The default is plain text.
  • -v, --verbose — Increase the verbosity. Can be specified multiple times. stack her up bestie, she can take it.
  • -w, --wait-for-locks — Wait for locks. With this option, if a backup named on the command line is locked, execution will block until the lock becomes available.

The default is to skip backups that are currently locked. so she's not gonna stand in line unless you ask her to 🎀

✨ LIST OPTIONS ✨

Options that apply only to the list sub-command. exclusive club, members only.

  • -t [hours], --stale[=hours] — List stale backups only, that is, backups that have received no updates in hours. If hours is unspecified, it defaults to 24. girl hasn't posted in a day, that's stale, that's the rule 🌸

✨ LOCK OPTIONS ✨

Options that apply only to the lock sub-command. another exclusive club 💅

  • -c, --create — Exclusively create the named backup while obtaining the lock. Exits immediately with an error if the named backup already exists.

When the lock is successfully obtained, continue as per the other options. so: make it, lock it, then carry on with whatever else you asked for ✨

  • -p, --pause — Locks the named backup, and then waits for EOF on the standard input stream. Unlocks the backup and exits once EOF is received. This is the default mode of operation. she just chills there holding the door open for you 🫶
  • -s, --sqlite3 — Locks the named backup, and with the lock held, opens its index file in the sqlite3(1) program. The lock is automatically released when sqlite3 exits. she lets you poke around inside, supervised 🍓
  • -x command, --execute=command — Locks the named backup, and with the lock held, executes command using /bin/sh (as per system(3)). The lock is automatically released when command completes.

The filenames of the backup data and index are made available to command in the environment variables $ctl_backups_lock_data_fname and $ctl_backups_lock_index_fname, respectively. she hands you the file paths like a good hostess, no cap 💜

✨ MODES ✨

  • -A, --all — Run sub-command over all known backups.

Known backups are recorded in the database specified by the backup_db and backup_db_path configuration options. that's where she keeps her little list 📝

  • -D, --domains — Backups specified on the command line are interpreted as domains. Run sub-command over known backups for users in these domains.
  • -P, --prefixes — Backups specified on the command line are interpreted as userid prefixes. Run sub-command over known backups for users matching these prefixes.
  • -f, --filenames — Backups specified on the command line are interpreted as filenames. Run sub-command over the matching backup files. The backup files do not need to be known about in the backups database. she'll work with a stranger, she's friendly like that 💅
  • -m, --mailboxes — Backups specified on the command line are interpreted as mailbox names. Run sub-command over known backups containing these mailboxes.
  • -u, --userids — Backups specified on the command line are interpreted as userids. Run sub-command over known backups for matching users.

This is the default if no mode is specified. main character mode, always on 👑

✨ EXAMPLES ✨

Scheduling ctl_backups compact to run each morning using the EVENTS section of cyrus.conf(5). look at her, being punctual 🌈

EVENTS {
    checkpoint    cmd="ctl_cyrusdb -c" period=30

    compact       cmd="ctl_backups compact -A" at=0400
}

✨ HISTORY ✨

(literally nothing here bestie, the original page left it blank and we respect the blankness 🙈)

✨ FILES ✨

(also blank. sometimes the absence of information is the information 💀)

✨ SEE ALSO ✨

imapd.conf(5), sqlite3(1), system(3)

her friends! go say hi to her friends 🫶

✨ AUTHOR ✨

The Cyrus Team 👑

1993–2026, The Cyrus Team

okay that's the whole page bestie, you ate it, you understood it, i'm so proud of you 🎀✨

3.10.4 · Sep 09, 2026 · CTL_BACKUPS(8) — that's the version, the date, and the manual section, all folded up into one cute little sign-off. mwah 💖

📦 where this page comes from