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
107 Force the operation to occur, even if it is determined to be un‐
108 necessary. This is mostly useful with the compact sub-command.
109 -S, --stop-on-error
111 Stop-on-error. With this option, if a sub-command fails for any
112 particular backup, ctl_backups will immediately exit with an er‐
113 ror, without processing further backups.
114 The default is to log the error, and continue with the next
116 backup.
117 -V, --no-verify
119 Don't verify backup checksums for read-only operations.
120 The read-only operations list and stat will normally perform a
122 "quick" verification of the backup file being read, which checks
123 the checksums of the most recent chunk. This can be slow for
124 backups whose most recent backup chunk is very large.
125 With this option, the verification step will be skipped.
127 -j, --json
129 Produce output in JSON format. The default is plain text.
130 -v, --verbose
132 Increase the verbosity. Can be specified multiple times.
133 -w, --wait-for-locks
135 Wait for locks. With this option, if a backup named on the com‐
136 mand line is locked, execution will block until the lock becomes
137 available.
138 The default is to skip backups that are currently locked.
140
142 Options that apply only to the list sub-command.
143 -t [hours], --stale[=hours]
145 List stale backups only, that is, backups that have received no
146 updates in hours. If hours is unspecified, it defaults to 24.
147
149 Options that apply only to the lock sub-command.
150 -c, --create
152 Exclusively create the named backup while obtaining the lock.
153 Exits immediately with an error if the named backup already ex‐
154 ists.
155 When the lock is successfully obtained, continue as per the
157 other options.
158 -p, --pause
160 Locks the named backup, and then waits for EOF on the standard
161 input stream. Unlocks the backup and exits once EOF is re‐
162 ceived. This is the default mode of operation.
163 -s, --sqlite3
165 Locks the named backup, and with the lock held, opens its index
166 file in the sqlite3(1) program. The lock is automatically re‐
167 leased when sqlite3 exits.
168 -x command, --execute=command
170 Locks the named backup, and with the lock held, executes command
171 using /bin/sh (as per system(3)). The lock is automatically re‐
172 leased when command completes.
173 The filenames of the backup data and index are made available to
175 command in the environment variables $ctl_back‐
176 ups_lock_data_fname and $ctl_backups_lock_index_fname, respec‐
177 tively.
178
180 -A, --all
181 Run sub-command over all known backups.
182 Known backups are recorded in the database specified by the
184 backup_db and backup_db_path configuration options.
185 -D, --domains
187 Backups specified on the command line are interpreted as do‐
188 mains. Run sub-command over known backups for users in these
189 domains.
190 -P, --prefixes
192 Backups specified on the command line are interpreted as userid
193 prefixes. Run sub-command over known backups for users matching
194 these prefixes.
195 -f, --filenames
197 Backups specified on the command line are interpreted as file‐
198 names. Run sub-command over the matching backup files. The
199 backup files do not need to be known about in the backups data‐
200 base.
201 -m, --mailboxes
203 Backups specified on the command line are interpreted as mailbox
204 names. Run sub-command over known backups containing these
205 mailboxes.
206 -u, --userids
208 Backups specified on the command line are interpreted as
209 userids. Run sub-command over known backups for matching users.
210 This is the default if no mode is specified.
212
214 Scheduling ctl_backups compact to run each morning using the EVENTS
215 section of cyrus.conf(5):
216 EVENTS {
218 checkpoint cmd="ctl_cyrusdb -c" period=30
219 compact cmd="ctl_backups compact -A" at=0400
221 }
222
226 imapd.conf(5), sqlite3(1), system(3)
227
229 The Cyrus Team
230
232 1993–2023, The Cyrus Team
2333.8.1 Sep 11, 2023 CTL_BACKUPS(8)