1RESTORE(8)                        Cyrus IMAP                        RESTORE(8)
2
3
4

NAME

6       restore - Cyrus IMAP documentation
7
8       Restore content from Cyrus backups.
9

SYNOPSIS

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

DESCRIPTION

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
18       restore  reads  its configuration options out of the imapd.conf(5) file
19       unless specified otherwise by -C.
20
21       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
28       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
32       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
37       backup is interpreted according to the specified MODE.  See  Modes  be‐
38       low.
39
40       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
48       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
56       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

OPTIONS

63       -A [acl]
64              Apply  specified  acl  to  restored mailboxes, rather than their
65              ACLs as stored in the backup.
66
67              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
72       -C config-file
73              Use the specified configuration file config-file rather than the
74              default imapd.conf(5).
75
76       -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
81              The default is to trim the prefix before restoring.
82
83              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
88              See imapd.conf(5) for information about  the  deletedprefix  and
89              delete_mode configuration options.
90
91       -F input-file
92              Get the list of mailboxes or messages from input-file instead of
93              from the command line arguments.
94
95              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
99       -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
103              The default is for mupdate actions to occur if  the  destination
104              server is part of a murder.
105
106              This  option has no effect if the destination server is not part
107              of a murder.
108
109       -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
113              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
119              The default when restoring mailboxes is to restore their respec‐
120              tive contents into mailboxes of the same names.
121
122              The default when restoring individual  messages  is  to  restore
123              them into their original mailboxes.
124
125       -P partition
126              Restore mailboxes to the specified partition
127
128       -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
132              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
136              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
140       -X     Do  not  restore  messages  that  are  marked as expunged in the
141              backup.
142
143              See also -x.
144
145       -a     Try to restore all mailboxes in the specified backup.
146
147       -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
152              Note  that  the server argument is still mandatory with this op‐
153              tion.
154
155       -r     Recurse into submailboxes.  When restoring mailboxes,  also  re‐
156              store any mailboxes contained within them.
157
158              The default is to restore only explicitly-specified mailboxes.
159
160       -v     Increase the verbosity level.  This option can be specified mul‐
161              tiple times for additional verbosity.
162
163       -w seconds
164              Wait seconds before starting.  This is useful  for  attaching  a
165              debugger.
166
167       -x     Only restore messages that are marked as expunged in the backup.
168
169              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
173              See also -X.
174
175       -z     Require  compression  for  server  connection.  The restore will
176              abort if compression is unavailable.
177

MODES

179       -f     backup is interpreted as a filename.  The named  file  does  not
180              need to be known about in the backups database.
181
182       -m     backup  is interpreted as a mailbox name.  There must be a known
183              backup for the user whose mailbox this is.
184
185              Known backups are recorded in  the  database  specified  by  the
186              backup_db and backup_db_path configuration options.
187
188       -u     backup is interpreted as a userid.  There must be a known backup
189              for the specified user.
190
191              This is the default if no mode is specified.
192

EXAMPLES

HISTORY

FILES

SEE ALSO

197       imapd.conf(5),  services(5),   cyr_backup(8),   imapd(8),   mupdate(8),
198       sync_server(8)
199

AUTHOR

201       The Cyrus Team
202
204       1993-2018, The Cyrus Team
205
206
207
208
2093.4.4                            June 27, 2022                      RESTORE(8)
Impressum