RESTORE(8) Cyrus IMAP RESTORE(8)
restore - Cyrus IMAP documentation
Restore content from Cyrus backups.
restore [OPTIONS] server [MODE] backup [ mboxname | uniqueid | guid ]...
restore is a tool for restoring messages and mailboxes from a Cyrus
backup to a Cyrus IMAP server. It must be run from the server contain‐
ing the backup storage.
restore reads its configuration options out of the imapd.conf(5) file
unless specified otherwise by -C.
server specifies the destination server to which content should be re‐
stored. It should be of the form ‘host[:port]’, where host is either a
hostname, an IPv4 address, or an IPv6 address, and where the optional
port is either a known service name (see services(5)) or a decimal port
number. If port is omitted, imap will be tried first, followed by
The destination server must point to either an imapd(8) instance with
the replication capability enabled, or a sync_server(8) instance. In
either case it must be Cyrus version 3.0 or newer.
restore will authenticate to the destination server according to the
restore_authname, restore_password and restore_realm configuration op‐
tions. The credentials should correspond with one of the destination
backup is interpreted according to the specified MODE. See Modes be‐
If neither -a nor -F options were provided, then the remaining argu‐
ments constitute a list of objects to be restored. These may be mail‐
boxes (specified by either mboxname or uniqueid) or messages (specified
by their guid). The objects may be specified in any order, and both
mailboxes and individual messages may be restored in one go.
cyr_backup(8) can be used to identify objects to restore from a Cyrus
Selected mailboxes will have their messages restored to a mailbox of
the same name, which will be created if necessary. Individually-se‐
lected messages will be restored to the mailboxes in which they previ‐
ously existed. In both cases the -M option can be used to override the
destination mailbox (see below), but note the consequences of doing
this when multiple mailbox objects have been specified, or when the -r
option is in use.
Mailboxes that are created during the restoration process will have
their ACL set to the one stored in the backup. The -A option can be
used to override this. Mailboxes that are not created during the
restoration process (i.e. when restoring into mailboxes that already
exists) will not have their ACLs altered.
Apply specified acl to restored mailboxes, rather than their
ACLs as stored in the backup.
If acl is the empty string (e.g. -A "") or is unspecified, mail‐
boxes will be restored with the default ACL for their destina‐
tion owner. This is mostly useful when restoring folders from
one user’s backup into a different user’s mailbox.
Use the specified configuration file config-file rather than the
-D Don’t trim deletedprefix from mailbox names prior to restoring.
This is mainly useful for rebuilding failed servers, where
deleted mailboxes should be restored as deleted mailboxes, not
as new ones.
The default is to trim the prefix before restoring.
If the original server from which the backups were produced had
delete_mode set to immediate, then the mailboxes in the backup
will not have such a prefix, and this option won’t have any use‐
See imapd.conf(5) for information about the deletedprefix and
delete_mode configuration options.
Get the list of mailboxes or messages from input-file instead of
from the command line arguments.
input-file should contain one object specification (either an
mboxname, a uniqueid, or a guid) per line. Empty lines, and
lines beginning with a ‘#’ character, are ignored.
-L Local operations only. Actions required to restore the re‐
quested mailboxes and messages will be performed on the destina‐
tion server only. mupdate(8) actions will not occur.
The default is for mupdate actions to occur if the destination
server is part of a murder.
This option has no effect if the destination server is not part
of a murder.
Messages are restored to the mailbox with the specified mbox‐
name. If no mailbox of this name exists, one will be created.
If multiple mailbox objects are to be restored, whether due to
being specified on the command line, in an input-file, or via
the -r option, then the collective contents of all such mail‐
boxes will be restored to the single mailbox mboxname. This may
not be what you want!
The default when restoring mailboxes is to restore their respec‐
tive contents into mailboxes of the same names.
The default when restoring individual messages is to restore
them into their original mailboxes.
Restore mailboxes to the specified partition
-U Try to preserve uidvalidity and other related fields, such that
the restored mailboxes and messages appear like they never left,
and IMAP clients can avoid expensive state updates.
This can only occur if the mailboxes to be restored do not al‐
ready exist on the destination server. As such, this option is
mainly useful when rebuilding a failed server.
If the destination mailboxes already exist, restored messages
will be appended as if newly delivered, regardless of whether
the -U option was specified.
-X Do not restore messages that are marked as expunged in the
See also -x.
-a Try to restore all mailboxes in the specified backup.
-n Do nothing. The work required to perform the restoration will
be calculated (and reported depending on verbosity level), but
no restoration will take place, and no connection will be made
to the destination server.
Note that the server argument is still mandatory with this op‐
-r Recurse into submailboxes. When restoring mailboxes, also re‐
store any mailboxes contained within them.
The default is to restore only explicitly-specified mailboxes.
-v Increase the verbosity level. This option can be specified mul‐
tiple times for additional verbosity.
Wait seconds before starting. This is useful for attaching a
-x Only restore messages that are marked as expunged in the backup.
This can be convenient for restoring messages that were acciden‐
tally deleted by the user, without needing to track down indi‐
vidual message guids.
See also -X.
-z Require compression for server connection. The restore will
abort if compression is unavailable.
-f backup is interpreted as a filename. The named file does not
need to be known about in the backups database.
-m backup is interpreted as a mailbox name. There must be a known
backup for the user whose mailbox this is.
Known backups are recorded in the database specified by the
backup_db and backup_db_path configuration options.
-u backup is interpreted as a userid. There must be a known backup
for the specified user.
This is the default if no mode is specified.
imapd.conf(5), services(5), cyr_backup(8), imapd(8), mupdate(8),
The Cyrus Team
1993-2018, The Cyrus Team
3.2.8 September 01, 2021 RESTORE(8)