--- name: "cyrus-restore" section: "8" platform: "linux" package: "cyrus-common" version: "3.10.2-1+deb13u2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/cyrus-restore" --- # cyrus-restore(8) Cyrus IMAP documentation Restore content from Cyrus backups. ## NAME restore - Cyrus IMAP documentation Restore content from Cyrus backups. ## SYNOPSIS ``` restore [OPTIONS] server [MODE] backup [ mboxname | uniqueid | guid ]... ``` ## DESCRIPTION **NOTE:** *Cyrus Backups are experimental, incomplete, and deprecated as of 3.10.* **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)](/imapd.conf/5.md) 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)](/services/5.md)***) 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)](/imapd/8.md) instance* *with the replication capability enabled, or a [sync\_server(8)](/sync_server/8.md)* *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)](/cyr_backup/8.md) 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)](/imapd.conf/5.md).* - **-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)](/imapd.conf/5.md) 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)](/imapd.conf/5.md),* **[services(5)](/services/5.md)***,* *[cyr\_backup(8)](/cyr_backup/8.md),* *[imapd(8)](/imapd/8.md),* *mupdate(8),* *[sync\_server(8)](/sync_server/8.md)* ## AUTHOR *The Cyrus Team* ## COPYRIGHT *1993–2025, The Cyrus Team*