--- name: "ctl_backups" section: "8" platform: "linux" package: "cyrus-common" version: "3.10.2-1+deb13u2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/ctl_backups" --- # ctl\_backups(8) Cyrus IMAP documentation Perform administrative operations directly on Cyrus backups. ## NAME ctl\_backups - Cyrus IMAP documentation Perform administrative operations directly on Cyrus backups. ## 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... ``` ## DESCRIPTION **NOTE:** *Cyrus Backups are experimental, incomplete, and deprecated as of 3.10.* **ctl\_backups** *is a tool for performing administrative operations on Cyrus* *backups.* **ctl\_backups** *reads its configuration options out of the [imapd.conf(5)](/imapd.conf/5.md) file unless specified otherwise by* **-C***.* *In all invocations, backup is interpreted according to the specified MODE.* *See Modes below.* **ctl\_backups** *provides the following sub-commands:* - **compact** *Reduce storage required by the named backups. Compact behaviour is* *influenced by the* **backup\_compact\_minsize***,* **backup\_compact\_maxsize***,* **backup\_compact\_work\_threshold***, and* **backup\_retention\_days** *configuration settings. See [imapd.conf(5)](/imapd.conf/5.md) for details.* *This should generally be invoked regularly, such as by adding an* *entry to the EVENTS section of [cyrus.conf(5)](/cyrus.conf/5.md). See* *Examples for an example.* *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.* - **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, lists all* *known backups (as if invoked with the* **-A** *mode).* - **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.* - **reindex** *Rebuild the indexes for the named backups, based on the raw backup data.* *This is useful if their index files have been corrupted, or if the index* *format has changed.* *If the* **backup\_keep\_previous** *configuration setting is enabled,* *reindex will preserve the original index file (renaming it with a* *timestamp). This is 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.* - **verify** *Verify consistency of the named backups by performing deep checks on both* *the raw backup data and its index.* ## OPTIONS - **-C config-file** *Use the specified configuration file config-file rather than the default [imapd.conf(5)](/imapd.conf/5.md).* - **-F, --force** *Force the operation to occur, even if it is determined to be unnecessary.* *This is mostly useful with the* **compact** *sub-command.* - **-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.* - **-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.* - **-j, --json** *Produce output in JSON format. The default is plain text.* - **-v, --verbose** *Increase the verbosity. Can be specified multiple times.* - **-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.* ## LIST OPTIONS *Options that apply only to the* **list** *sub-command.* - **-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.* ## LOCK OPTIONS *Options that apply only to the* **lock** *sub-command.* - **-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.* - **-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.* - **-s, --sqlite3** *Locks the named backup, and with the lock held, opens its index file in* *the* **[sqlite3(1)](/sqlite3/1.md)** *program. The lock is automatically released when* *sqlite3 exits.* - **-x command, --execute=command** *Locks the named backup, and with the lock held, executes command using* **/bin/sh** *(as per* **[system(3)](/system/3.md)***). 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.* ## 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.* - **-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.* - **-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.* ## EXAMPLES *Scheduling* **ctl\_backups compact** *to run each morning using the EVENTS* *section of [cyrus.conf(5)](/cyrus.conf/5.md):* ``` EVENTS { checkpoint cmd="ctl_cyrusdb -c" period=30 compact cmd="ctl_backups compact -A" at=0400 } ``` ## HISTORY ## FILES ## SEE ALSO *[imapd.conf(5)](/imapd.conf/5.md)***,** **[sqlite3(1)](/sqlite3/1.md),** **[system(3)](/system/3.md)** ## AUTHOR **The Cyrus Team** ## COPYRIGHT **1993–2025, The Cyrus Team**