RESTORE(8)

📦
version 3.10.4 · 3 versions
, in fedora 43

🌸 restore — the Cyrus IMAP page, section 8 🌸

okay bestie, so this whole page is from the Cyrus IMAP manual, and it's literally the glow-up guide for getting your stuff back. buckle up 💖

💖 NAME 💖

restore — Cyrus IMAP documentation

it's the tool that restores content from Cyrus backups. that's the whole job. slay.

✨ SYNOPSIS ✨

restore [OPTIONS] server [MODE] backup [ mboxname | uniqueid | guid ]...

🦋 DESCRIPTION 🦋

NOTE: Cyrus Backups are experimental, incomplete, and deprecated as of 3.10. not me warning you first thing, but here we are 🙈

okay so restore is a tool for restoring messages and mailboxes from a Cyrus backup onto a Cyrus IMAP server. and the vibe check is real: it must be run from the server that's holding the backup storage. no exceptions, no cap.

restore reads its configuration options out of the imapd.conf(5) file, unless you say otherwise with -C.

server is the destination server — where all your content is going. 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 (peep services(5)) or a decimal port number. if port is omitted, imap gets tried first, followed by csync.

the destination server has to point to either an imapd(8) instance with the replication capability enabled, or a sync_server(8) instance. either way? it must be Cyrus version 3.0 or newer. we don't do old versions here 💅

restore will authenticate to the destination server according to the restore_authname, restore_password and restore_realm configuration options. those credentials should correspond with one of the destination server's admins. main character credentials only 👑

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 exist) will not have their ACLs altered. periodt.

💅 OPTIONS 💅

  • -A [acl], --override-acl[=acl] — apply the 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. very "moving in with your bestie" energy 🫶

  • -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. so you can leave cute little notes to yourself in there 💬

  • -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. it's giving "no one even noticed you were gone" ✨

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. yes, even though nothing happens. rules are rules 💀

  • -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. spam it, queen 📣
  • -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. the "oops bestie I didn't mean to delete that" rescue mission 🙈

see also -X.

  • -z, --require-compression — require compression for the server connection. the restore will abort if compression is unavailable. all or nothing, fr fr.

🌈 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. it's a free spirit, it answers to no 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. so if you're not sure? it's this one 👑

🍓 EXAMPLES 🍓

this section is empty in the original. no examples, bestie. we're doing it live 😭

🕰️ HISTORY 🕰️

also empty. the lore is lost to time 🦋

📁 FILES 📁

empty too. nothing to see here, moving on 💅

👀 SEE ALSO 👀

🫶 AUTHOR 🫶

The Cyrus Team. icons, honestly.

1993–2026, The Cyrus Team.

and that's the whole page, bestie! this was version 3.10.4, dated Sep 09, 2026 — go restore something iconic and text me when it's done 💖✨🎀🦋

📦 where this page comes from