1RESTORE(8) Cyrus IMAP RESTORE(8)
2
6 restore - Cyrus IMAP documentation
7 Restore content from Cyrus backups.
9
11 restore [OPTIONS] server [MODE] backup [ mboxname | uniqueid | guid ]...
12
14 restore is a tool for restoring messages and mailboxes from a Cyrus
15 backup to a Cyrus IMAP server. It must be run from the server contain‐
16 ing the backup storage.
17 restore reads its configuration options out of the imapd.conf(5) file
19 unless specified otherwise by -C.
20 server specifies the destination server to which content should be re‐
22 stored. It should be of the form 'host[:port]', where host is either a
23 hostname, an IPv4 address, or an IPv6 address, and where the optional
24 port is either a known service name (see services(5)) or a decimal port
25 number. If port is omitted, imap will be tried first, followed by
26 csync.
27 The destination server must point to either an imapd(8) instance with
29 the replication capability enabled, or a sync_server(8) instance. In
30 either case it must be Cyrus version 3.0 or newer.
31 restore will authenticate to the destination server according to the
33 restore_authname, restore_password and restore_realm configuration op‐
34 tions. The credentials should correspond with one of the destination
35 server's admins.
36 backup is interpreted according to the specified MODE. See Modes be‐
38 low.
39 If neither -a nor -F options were provided, then the remaining argu‐
41 ments constitute a list of objects to be restored. These may be mail‐
42 boxes (specified by either mboxname or uniqueid) or messages (specified
43 by their guid). The objects may be specified in any order, and both
44 mailboxes and individual messages may be restored in one go.
45 cyr_backup(8) can be used to identify objects to restore from a Cyrus
46 backup.
47 Selected mailboxes will have their messages restored to a mailbox of
49 the same name, which will be created if necessary. Individually-se‐
50 lected messages will be restored to the mailboxes in which they previ‐
51 ously existed. In both cases the -M option can be used to override the
52 destination mailbox (see below), but note the consequences of doing
53 this when multiple mailbox objects have been specified, or when the -r
54 option is in use.
55 Mailboxes that are created during the restoration process will have
57 their ACL set to the one stored in the backup. The -A option can be
58 used to override this. Mailboxes that are not created during the
59 restoration process (i.e. when restoring into mailboxes that already
60 exists) will not have their ACLs altered.
61
63 -A [acl], --override-acl[=acl]
64 Apply specified acl to restored mailboxes, rather than their
65 ACLs as stored in the backup.
66 If acl is the empty string (e.g. -A "") or is unspecified, mail‐
68 boxes will be restored with the default ACL for their destina‐
69 tion owner. This is mostly useful when restoring folders from
70 one user's backup into a different user's mailbox.
71 -C config-file
73 Use the specified configuration file config-file rather than the
74 default imapd.conf(5).
75 -D, --keep-deletedprefix
77 Don't trim deletedprefix from mailbox names prior to restoring.
78 This is mainly useful for rebuilding failed servers, where
79 deleted mailboxes should be restored as deleted mailboxes, not
80 as new ones.
81 The default is to trim the prefix before restoring.
83 If the original server from which the backups were produced had
85 delete_mode set to immediate, then the mailboxes in the backup
86 will not have such a prefix, and this option won't have any use‐
87 ful effect.
88 See imapd.conf(5) for information about the deletedprefix and
90 delete_mode configuration options.
91 -F input-file, --input-file=input-file
93 Get the list of mailboxes or messages from input-file instead of
94 from the command line arguments.
95 input-file should contain one object specification (either an
97 mboxname, a uniqueid, or a guid) per line. Empty lines, and
98 lines beginning with a '#' character, are ignored.
99 -L, --local-only
101 Local operations only. Actions required to restore the re‐
102 quested mailboxes and messages will be performed on the destina‐
103 tion server only. mupdate(8) actions will not occur.
104 The default is for mupdate actions to occur if the destination
106 server is part of a murder.
107 This option has no effect if the destination server is not part
109 of a murder.
110 -M mboxname, --dest-mailbox=mboxname
112 Messages are restored to the mailbox with the specified mbox‐
113 name. If no mailbox of this name exists, one will be created.
114 If multiple mailbox objects are to be restored, whether due to
116 being specified on the command line, in an input-file, or via
117 the -r option, then the collective contents of all such mail‐
118 boxes will be restored to the single mailbox mboxname. This may
119 not be what you want!
120 The default when restoring mailboxes is to restore their respec‐
122 tive contents into mailboxes of the same names.
123 The default when restoring individual messages is to restore
125 them into their original mailboxes.
126 -P partition, --dest-partition=partition
128 Restore mailboxes to the specified partition
129 -U, --keep-uidvalidity
131 Try to preserve uidvalidity and other related fields, such that
132 the restored mailboxes and messages appear like they never left,
133 and IMAP clients can avoid expensive state updates.
134 This can only occur if the mailboxes to be restored do not al‐
136 ready exist on the destination server. As such, this option is
137 mainly useful when rebuilding a failed server.
138 If the destination mailboxes already exist, restored messages
140 will be appended as if newly delivered, regardless of whether
141 the -U option was specified.
142 -X, --skip-expunged
144 Do not restore messages that are marked as expunged in the
145 backup.
146 See also -x.
148 -a, --all-mailboxes
150 Try to restore all mailboxes in the specified backup.
151 -n, --dry-run
153 Do nothing. The work required to perform the restoration will
154 be calculated (and reported depending on verbosity level), but
155 no restoration will take place, and no connection will be made
156 to the destination server.
157 Note that the server argument is still mandatory with this op‐
159 tion.
160 -r, --recursive
162 Recurse into submailboxes. When restoring mailboxes, also re‐
163 store any mailboxes contained within them.
164 The default is to restore only explicitly-specified mailboxes.
166 -v, --verbose
168 Increase the verbosity level. This option can be specified mul‐
169 tiple times for additional verbosity.
170 -w seconds, --delayed-startup=seconds
172 Wait seconds before starting. This is useful for attaching a
173 debugger.
174 -x, --only-expunged
176 Only restore messages that are marked as expunged in the backup.
177 This can be convenient for restoring messages that were acciden‐
179 tally deleted by the user, without needing to track down indi‐
180 vidual message guids.
181 See also -X.
183 -z, --require-compression
185 Require compression for server connection. The restore will
186 abort if compression is unavailable.
187
189 -f backup, --file=backup
190 backup is interpreted as a filename. The named file does not
191 need to be known about in the backups database.
192 -m backup, --mailbox=backup
194 backup is interpreted as a mailbox name. There must be a known
195 backup for the user whose mailbox this is.
196 Known backups are recorded in the database specified by the
198 backup_db and backup_db_path configuration options.
199 -u backup, --userid=backup
201 backup is interpreted as a userid. There must be a known backup
202 for the specified user.
203 This is the default if no mode is specified.
205
210 imapd.conf(5), services(5), cyr_backup(8), imapd(8), mupdate(8),
211 sync_server(8)
212
214 The Cyrus Team
215
217 1993–2023, The Cyrus Team
2183.8.1 Sep 11, 2023 RESTORE(8)