Provided by: cyrus-common_3.6.1-2ubuntu1_amd64 bug

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–2023, The Cyrus Team