1CTL_BACKUPS(8) Cyrus IMAP CTL_BACKUPS(8)
2
6 ctl_backups - Cyrus IMAP documentation
7 Perform administrative operations directly on Cyrus backups.
9
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
19 ctl_backups is a tool for performing administrative operations on Cyrus
20 backups.
21 ctl_backups reads its configuration options out of the imapd.conf(5)
23 file unless specified otherwise by -C.
24 In all invocations, backup is interpreted according to the specified
26 MODE. See Modes below.
27 ctl_backups provides the following sub-commands:
29 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 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 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 list List backups. See List Options for options specific to the list
45 sub-command. Columns are separated by tabs, and are:
46 • end time of latest chunk
48 • size of backup data file on disk
50 • userid to which the backup belongs
52 • path to backup data file
54 If no mode or backups are specified, lists all known backups (as
56 if invoked with the -A mode).
57 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 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 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 stat Display stats for the named backups. Columns are separated by
73 tabs, and are:
74 • userid or filename
76 • compressed (i.e. on disk) size
78 • uncompressed size
80 • compactable size
82 • compression ratio
84 • utilisation ratio
86 • start time of latest chunk
88 • end time of latest chunk
90 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 verify Verify consistency of the named backups by performing deep
99 checks on both the raw backup data and its index.
100
102 -C config-file
103 Use the specified configuration file config-file rather than the
104 default imapd.conf(5).
105 -F Force the operation to occur, even if it is determined to be un‐
107 necessary. This is mostly useful with the compact sub-command.
108 -S Stop-on-error. With this option, if a sub-command fails for any
110 particular backup, ctl_backups will immediately exit with an er‐
111 ror, without processing further backups.
112 The default is to log the error, and continue with the next
114 backup.
115 -V Don’t verify backup checksums for read-only operations.
117 The read-only operations list and stat will normally perform a
119 “quick” verification of the backup file being read, which checks
120 the checksums of the most recent chunk. This can be slow for
121 backups whose most recent backup chunk is very large.
122 With this option, the verification step will be skipped.
124 -j Produce output in JSON format. The default is plain text.
126 -v Increase the verbosity. Can be specified multiple times.
128 -w Wait for locks. With this option, if a backup named on the com‐
130 mand line is locked, execution will block until the lock becomes
131 available.
132 The default is to skip backups that are currently locked.
134
136 Options that apply only to the list sub-command.
137 -t [hours]
139 List stale backups only, that is, backups that have received no
140 updates in hours. If hours is unspecified, it defaults to 24.
141
143 Options that apply only to the lock sub-command.
144 -c Exclusively create the named backup while obtaining the lock.
146 Exits immediately with an error if the named backup already ex‐
147 ists.
148 When the lock is successfully obtained, continue as per the
150 other options.
151 -p Locks the named backup, and then waits for EOF on the standard
153 input stream. Unlocks the backup and exits once EOF is re‐
154 ceived. This is the default mode of operation.
155 -s Locks the named backup, and with the lock held, opens its index
157 file in the sqlite3(1) program. The lock is automatically re‐
158 leased when sqlite3 exits.
159 -x command
161 Locks the named backup, and with the lock held, executes command
162 using /bin/sh (as per system(3)). The lock is automatically re‐
163 leased when command completes.
164 The filenames of the backup data and index are made available to
166 command in the environment variables $ctl_back‐
167 ups_lock_data_fname and $ctl_backups_lock_index_fname, respec‐
168 tively.
169
171 -A Run sub-command over all known backups.
172 Known backups are recorded in the database specified by the
174 backup_db and backup_db_path configuration options.
175 -D Backups specified on the command line are interpreted as do‐
177 mains. Run sub-command over known backups for users in these
178 domains.
179 -P Backups specified on the command line are interpreted as userid
181 prefixes. Run sub-command over known backups for users matching
182 these prefixes.
183 -f Backups specified on the command line are interpreted as file‐
185 names. Run sub-command over the matching backup files. The
186 backup files do not need to be known about in the backups data‐
187 base.
188 -m Backups specified on the command line are interpreted as mailbox
190 names. Run sub-command over known backups containing these
191 mailboxes.
192 -u Backups specified on the command line are interpreted as
194 userids. Run sub-command over known backups for matching users.
195 This is the default if no mode is specified.
197
199 Scheduling ctl_backups compact to run each morning using the EVENTS
200 section of cyrus.conf(5):
201 EVENTS {
203 checkpoint cmd="ctl_cyrusdb -c" period=30
204 compact cmd="ctl_backups compact -A" at=0400
206 }
207
211 imapd.conf(5), sqlite3(1), system(3)
212
214 The Cyrus Team
215
217 1993–2022, The Cyrus Team
2183.6.0 December 12, 2022 CTL_BACKUPS(8)