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
107 unnecessary. This is mostly useful with the compact sub-com‐
108 mand.
109 -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 The default is to log the error, and continue with the next
115 backup.
116 -V Don't verify backup checksums for read-only operations.
118 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 With this option, the verification step will be skipped.
125 -v Increase the verbosity. Can be specified multiple times.
127 -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 The default is to skip backups that are currently locked.
133
135 Options that apply only to the list sub-command.
136 -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
142 Options that apply only to the lock sub-command.
143 -c Exclusively create the named backup while obtaining the lock.
145 Exits immediately with an error if the named backup already
146 exists.
147 When the lock is successfully obtained, continue as per the
149 other options.
150 -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 -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 -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 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
170 -A Run sub-command over all known backups.
171 Known backups are recorded in the database specified by the
173 backup_db and backup_db_path configuration options.
174 -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 -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 -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 -m Backups specified on the command line are interpreted as mailbox
189 names. Run sub-command over known backups containing these
190 mailboxes.
191 -u Backups specified on the command line are interpreted as
193 userids. Run sub-command over known backups for matching users.
194 This is the default if no mode is specified.
196
198 Scheduling ctl_backups compact to run each morning using the EVENTS
199 section of cyrus.conf(5):
200 EVENTS {
202 checkpoint cmd="ctl_cyrusdb -c" period=30
203 compact cmd="ctl_backups compact -A" at=0400
205 }
206
210 imapd.conf(5), sqlite3(1), system(3)
211
213 The Cyrus Team
214
216 1993-2017, The Cyrus Team
2173.0.12 November 15, 2019 CTL_BACKUPS(8)