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]
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 Don’t trim deletedprefix from mailbox names prior to restoring.
77 This is mainly useful for rebuilding failed servers, where
78 deleted mailboxes should be restored as deleted mailboxes, not
79 as new ones.
80 The default is to trim the prefix before restoring.
82 If the original server from which the backups were produced had
84 delete_mode set to immediate, then the mailboxes in the backup
85 will not have such a prefix, and this option won’t have any use‐
86 ful effect.
87 See imapd.conf(5) for information about the deletedprefix and
89 delete_mode configuration options.
90 -F input-file
92 Get the list of mailboxes or messages from input-file instead of
93 from the command line arguments.
94 input-file should contain one object specification (either an
96 mboxname, a uniqueid, or a guid) per line. Empty lines, and
97 lines beginning with a ‘#’ character, are ignored.
98 -L Local operations only. Actions required to restore the re‐
100 quested mailboxes and messages will be performed on the destina‐
101 tion server only. mupdate(8) actions will not occur.
102 The default is for mupdate actions to occur if the destination
104 server is part of a murder.
105 This option has no effect if the destination server is not part
107 of a murder.
108 -M mboxname
110 Messages are restored to the mailbox with the specified mbox‐
111 name. If no mailbox of this name exists, one will be created.
112 If multiple mailbox objects are to be restored, whether due to
114 being specified on the command line, in an input-file, or via
115 the -r option, then the collective contents of all such mail‐
116 boxes will be restored to the single mailbox mboxname. This may
117 not be what you want!
118 The default when restoring mailboxes is to restore their respec‐
120 tive contents into mailboxes of the same names.
121 The default when restoring individual messages is to restore
123 them into their original mailboxes.
124 -P partition
126 Restore mailboxes to the specified partition
127 -U Try to preserve uidvalidity and other related fields, such that
129 the restored mailboxes and messages appear like they never left,
130 and IMAP clients can avoid expensive state updates.
131 This can only occur if the mailboxes to be restored do not al‐
133 ready exist on the destination server. As such, this option is
134 mainly useful when rebuilding a failed server.
135 If the destination mailboxes already exist, restored messages
137 will be appended as if newly delivered, regardless of whether
138 the -U option was specified.
139 -X Do not restore messages that are marked as expunged in the
141 backup.
142 See also -x.
144 -a Try to restore all mailboxes in the specified backup.
146 -n Do nothing. The work required to perform the restoration will
148 be calculated (and reported depending on verbosity level), but
149 no restoration will take place, and no connection will be made
150 to the destination server.
151 Note that the server argument is still mandatory with this op‐
153 tion.
154 -r Recurse into submailboxes. When restoring mailboxes, also re‐
156 store any mailboxes contained within them.
157 The default is to restore only explicitly-specified mailboxes.
159 -v Increase the verbosity level. This option can be specified mul‐
161 tiple times for additional verbosity.
162 -w seconds
164 Wait seconds before starting. This is useful for attaching a
165 debugger.
166 -x Only restore messages that are marked as expunged in the backup.
168 This can be convenient for restoring messages that were acciden‐
170 tally deleted by the user, without needing to track down indi‐
171 vidual message guids.
172 See also -X.
174 -z Require compression for server connection. The restore will
176 abort if compression is unavailable.
177
179 -f backup is interpreted as a filename. The named file does not
180 need to be known about in the backups database.
181 -m backup is interpreted as a mailbox name. There must be a known
183 backup for the user whose mailbox this is.
184 Known backups are recorded in the database specified by the
186 backup_db and backup_db_path configuration options.
187 -u backup is interpreted as a userid. There must be a known backup
189 for the specified user.
190 This is the default if no mode is specified.
192
197 imapd.conf(5), services(5), cyr_backup(8), imapd(8), mupdate(8),
198 sync_server(8)
199
201 The Cyrus Team
202
204 1993-2018, The Cyrus Team
2053.4.4 June 27, 2022 RESTORE(8)