1CTL_BACKUPS(8)                    Cyrus IMAP                    CTL_BACKUPS(8)
2
3
4

NAME

6       ctl_backups - Cyrus IMAP documentation
7
8       Perform administrative operations directly on Cyrus backups.
9

SYNOPSIS

11       ctl_backups [OPTIONS] compact [MODE] backup...
12       ctl_backups [OPTIONS] list [LIST OPTIONS] [[MODE] backup...]
13       ctl_backups [OPTIONS] lock [LOCK OPTIONS] [MODE] backup
14       ctl_backups [OPTIONS] reindex [MODE] backup...
15       ctl_backups [OPTIONS] stat [MODE] backup...
16       ctl_backups [OPTIONS] verify [MODE] backup...
17

DESCRIPTION

19       ctl_backups is a tool for performing administrative operations on Cyrus
20       backups.
21
22       ctl_backups reads its configuration options out  of  the  imapd.conf(5)
23       file unless specified otherwise by -C.
24
25       In  all  invocations,  backup is interpreted according to the specified
26       MODE.  See Modes below.
27
28       ctl_backups provides the following sub-commands:
29
30       compact
31              Reduce storage required by the named backups.  Compact behaviour
32              is influenced by the backup_compact_minsize, backup_compact_max‐
33              size, backup_compact_work_threshold,  and  backup_retention_days
34              configuration settings.  See imapd.conf(5) for details.
35
36              This should generally be invoked regularly, such as by adding an
37              entry to the EVENTS section of cyrus.conf(5).  See Examples  for
38              an example.
39
40              If  the  backup_keep_previous  configuration setting is enabled,
41              compact will preserve the original data and index files  (renam‐
42              ing them with a timestamp).  This is useful for debugging.
43
44       list   List backups.  See List Options for options specific to the list
45              sub-command.  Columns are separated by tabs, and are:
46
47              · end time of latest chunk
48
49              · size of backup data file on disk
50
51              · userid to which the backup belongs
52
53              · path to backup data file
54
55              If no mode or backups are specified, lists all known backups (as
56              if invoked with the -A mode).
57
58       lock   Obtain  and hold a lock on the named backup.  Useful for operat‐
59              ing on Cyrus backup files using non-Cyrus tools  (such  as  UNIX
60              tools  or  custom scripts) in relative safety.  See Lock Options
61              for details.
62
63       reindex
64              Rebuild the indexes for the named  backups,  based  on  the  raw
65              backup data.  This is useful if their index files have been cor‐
66              rupted, or if the index format has changed.
67
68              If the backup_keep_previous configuration  setting  is  enabled,
69              reindex  will preserve the original index file (renaming it with
70              a timestamp).  This is useful for debugging.
71
72       stat   Display stats for the named backups.  Columns are  separated  by
73              tabs, and are:
74
75              · userid or filename
76
77              · compressed (i.e. on disk) size
78
79              · uncompressed size
80
81              · compactable size
82
83              · compression ratio
84
85              · utilisation ratio
86
87              · start time of latest chunk
88
89              · end time of latest chunk
90
91              The  compactable  size  is  an  approximation of how much uncom‐
92              pressed data would remain after compact is performed.  The util‐
93              isation  ratio  is  this figure expressed as a percentage of the
94              uncompressed size.  Note that this approximation is an  underes‐
95              timate.   That  is to say, a backup that has just been compacted
96              will probably still report less than 100% utilisation.
97
98       verify Verify consistency of  the  named  backups  by  performing  deep
99              checks on both the raw backup data and its index.
100

OPTIONS

102       -C config-file
103              Use the specified configuration file config-file rather than the
104              default imapd.conf(5).
105
106       -F     Force the operation to occur, even if it  is  determined  to  be
107              unnecessary.   This  is  mostly useful with the compact sub-com‐
108              mand.
109
110       -S     Stop-on-error.  With this option, if a sub-command fails for any
111              particular  backup,  ctl_backups  will  immediately exit with an
112              error, without processing further backups.
113
114              The default is to log the error,  and  continue  with  the  next
115              backup.
116
117       -V     Don't verify backup checksums for read-only operations.
118
119              The  read-only  operations list and stat will normally perform a
120              "quick" verification of the backup file being read, which checks
121              the  checksums  of  the most recent chunk.  This can be slow for
122              backups whose most recent backup chunk is very large.
123
124              With this option, the verification step will be skipped.
125
126       -v     Increase the verbosity.  Can be specified multiple times.
127
128       -w     Wait for locks.  With this option, if a backup named on the com‐
129              mand line is locked, execution will block until the lock becomes
130              available.
131
132              The default is to skip backups that are currently locked.
133

LIST OPTIONS

135       Options that apply only to the list sub-command.
136
137       -t [hours]
138              List stale backups only, that is, backups that have received  no
139              updates in hours.  If hours is unspecified, it defaults to 24.
140

LOCK OPTIONS

142       Options that apply only to the lock sub-command.
143
144       -c     Exclusively  create  the  named backup while obtaining the lock.
145              Exits immediately with an error  if  the  named  backup  already
146              exists.
147
148              When  the  lock  is  successfully  obtained, continue as per the
149              other options.
150
151       -p     Locks the named backup, and then waits for EOF on  the  standard
152              input  stream.   Unlocks  the  backup  and  exits  once  EOF  is
153              received.  This is the default mode of operation.
154
155       -s     Locks the named backup, and with the lock held, opens its  index
156              file  in  the  sqlite3(1)  program.   The  lock is automatically
157              released when sqlite3 exits.
158
159       -x command
160              Locks the named backup, and with the lock held, executes command
161              using  /bin/sh  (as  per  system(3)).  The lock is automatically
162              released when command completes.
163
164              The filenames of the backup data and index are made available to
165              command     in     the    environment    variables    $ctl_back‐
166              ups_lock_data_fname and  $ctl_backups_lock_index_fname,  respec‐
167              tively.
168

MODES

170       -A     Run sub-command over all known backups.
171
172              Known  backups  are  recorded  in  the database specified by the
173              backup_db and backup_db_path configuration options.
174
175       -D     Backups  specified  on  the  command  line  are  interpreted  as
176              domains.   Run sub-command over known backups for users in these
177              domains.
178
179       -P     Backups specified on the command line are interpreted as  userid
180              prefixes.  Run sub-command over known backups for users matching
181              these prefixes.
182
183       -f     Backups specified on the command line are interpreted  as  file‐
184              names.   Run  sub-command  over  the matching backup files.  The
185              backup files do not need to be known about in the backups  data‐
186              base.
187
188       -m     Backups specified on the command line are interpreted as mailbox
189              names.  Run sub-command  over  known  backups  containing  these
190              mailboxes.
191
192       -u     Backups  specified  on  the  command  line  are  interpreted  as
193              userids.  Run sub-command over known backups for matching users.
194
195              This is the default if no mode is specified.
196

EXAMPLES

198       Scheduling ctl_backups compact to run each  morning  using  the  EVENTS
199       section of cyrus.conf(5):
200
201       EVENTS {
202           checkpoint    cmd="ctl_cyrusdb -c" period=30
203
204           compact       cmd="ctl_backups compact -A" at=0400
205       }
206

HISTORY

FILES

SEE ALSO

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

AUTHOR

213       The Cyrus Team
214
216       1993-2017, The Cyrus Team
217
218
219
220
2213.0.12                         November 15, 2019                CTL_BACKUPS(8)
Impressum