Provided by: cyrus-common_3.8.2-1_amd64 
NAME
restore - Cyrus IMAP documentation
Restore content from Cyrus backups.
SYNOPSIS
restore [OPTIONS] server [MODE] backup [ mboxname | uniqueid | guid ]...
DESCRIPTION
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 containing 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 restored. 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 csync.
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 options. The credentials should
correspond with one of the destination server's admins.
backup is interpreted according to the specified MODE. See Modes below.
If neither -a nor -F options were provided, then the remaining arguments constitute a list
of objects to be restored. These may be mailboxes (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 backup.
Selected mailboxes will have their messages restored to a mailbox of the same name, which
will be created if necessary. Individually-selected messages will be restored to the
mailboxes in which they previously 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.
OPTIONS
-A [acl], --override-acl[=acl]
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, mailboxes will be
restored with the default ACL for their destination owner. This is mostly useful
when restoring folders from one user's backup into a different user's mailbox.
-C config-file
Use the specified configuration file config-file rather than the default
imapd.conf(5).
-D, --keep-deletedprefix
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 useful effect.
See imapd.conf(5) for information about the deletedprefix and delete_mode
configuration options.
-F input-file, --input-file=input-file
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-only
Local operations only. Actions required to restore the requested mailboxes and
messages will be performed on the destination 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.
-M mboxname, --dest-mailbox=mboxname
Messages are restored to the mailbox with the specified mboxname. 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 mailboxes will be restored to the single mailbox mboxname.
This may not be what you want!
The default when restoring mailboxes is to restore their respective contents into
mailboxes of the same names.
The default when restoring individual messages is to restore them into their
original mailboxes.
-P partition, --dest-partition=partition
Restore mailboxes to the specified partition
-U, --keep-uidvalidity
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 already 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, --skip-expunged
Do not restore messages that are marked as expunged in the backup.
See also -x.
-a, --all-mailboxes
Try to restore all mailboxes in the specified backup.
-n, --dry-run
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 option.
-r, --recursive
Recurse into submailboxes. When restoring mailboxes, also restore any mailboxes
contained within them.
The default is to restore only explicitly-specified mailboxes.
-v, --verbose
Increase the verbosity level. This option can be specified multiple times for
additional verbosity.
-w seconds, --delayed-startup=seconds
Wait seconds before starting. This is useful for attaching a debugger.
-x, --only-expunged
Only restore messages that are marked as expunged in the backup.
This can be convenient for restoring messages that were accidentally deleted by the
user, without needing to track down individual message guids.
See also -X.
-z, --require-compression
Require compression for server connection. The restore will abort if compression
is unavailable.
MODES
-f backup, --file=backup
backup is interpreted as a filename. The named file does not need to be known
about in the backups database.
-m backup, --mailbox=backup
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, --userid=backup
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.
EXAMPLES
HISTORY
FILES
SEE ALSO
imapd.conf(5), services(5), cyr_backup(8), imapd(8), mupdate(8), sync_server(8)
AUTHOR
The Cyrus Team
COPYRIGHT
1993–2024, The Cyrus Team