Ubuntu Manpage: ctl_backups - Cyrus IMAP documentation

Provided by: cyrus-common_3.8.2-1ubuntu0.2_amd64

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

ctl_backups is a tool for performing administrative operations on Cyrus backups.

ctl_backups reads its configuration options out of the imapd.conf(5) 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) for details.

This should generally be invoked regularly, such as by adding an entry to the EVENTS section of
cyrus.conf(5). 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).

-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)  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)).
              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):

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

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

HISTORY

FILES

AUTHOR

       The Cyrus Team

COPYRIGHT

       1993–2024, The Cyrus Team

3.8.2                                             Mar 13, 2024                                    CTL_BACKUPS(8)