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  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.  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     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     Produce output in JSON format.  The default is plain text.

       -v     Increase the verbosity.  Can be specified multiple times.

       -w     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]
              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     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     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     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
              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     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     Backups  specified  on  the  command  line are interpreted as domains.  Run sub-command over known
              backups for users in these domains.

       -P     Backups specified on the command line are interpreted as userid prefixes.   Run  sub-command  over
              known backups for users matching these prefixes.

       -f     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     Backups specified on the command line are interpreted as  mailbox  names.   Run  sub-command  over
              known backups containing these mailboxes.

       -u     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

SEE ALSO

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

AUTHOR

       The Cyrus Team

COPYRIGHT

       1993-2018, The Cyrus Team

3.4.3                                           February 02, 2022                                 CTL_BACKUPS(8)