1mbsync(1) General Commands Manual mbsync(1)
2
6 mbsync - synchronize IMAP4 and Maildir mailboxes
7
9 mbsync [options ...] {{channel[:box[{,|\n}...]]|group} ...|-a}
10
12 mbsync is a command line application which synchronizes mailboxes; cur‐
13 rently Maildir and IMAP4 mailboxes are supported. New messages, mes‐
14 sage deletions and flag changes can be propagated both ways; the opera‐
15 tion set can be selected in a fine-grained manner.
16 Synchronization is based on unique message identifiers (UIDs), so no
17 identification conflicts can occur (as opposed to some other mail syn‐
18 chronizers). OTOH, mbsync is susceptible to UID validity changes (that
19 should never happen, but see "Compatibility" in the README). Synchro‐
20 nization state is kept in one local text file per mailbox pair; multi‐
21 ple replicas of a mailbox can be maintained.
22
24 -c, --config file
25 Read configuration from file. By default, the configuration is
26 read from ~/.mbsyncrc.
27 -a, --all
29 Select all configured channels. Any channel/group specifications
30 on the command line are ignored.
31 -l, --list
33 Don't synchronize anything, but list all mailboxes in the
34 selected channels and exit.
35 -C[m][s], --create[-master|-slave]
37 Override any Create options from the config file. See below.
38 -X[m][s], --expunge[-master|-slave]
40 Override any Expunge options from the config file. See below.
41 {-n|-N|-d|-f|-0|-F}, {--new|--renew|--delete|--flags|--noop|--full}
43 {-L|-H}[n][N][d][f], {--pull|--push}[-new|-renew|-delete|-flags]
44 Override any Sync options from the config file. See below.
46 -h, --help
48 Display a summary of command line options.
49 -v, --version
51 Display version information.
52 -V, --verbose
54 Enable verbose mode, which displays the IMAP4 network traffic.
55 -D, --debug
57 Enable printing debug information.
58 -q, --quiet
60 Suppress informational messages. If specified twice, suppress
61 warning messages as well.
62
64 The configuration file is mandatory; mbsync will not run without it.
65 Lines starting with a hash mark (#) are comments and are ignored
66 entirely. Configuration items are keywords followed by one or more
67 arguments; arguments containing spaces must be enclosed in double
68 quotes ("). All keywords (including those used as arguments) are case-
69 insensitive. There are a few global options, the rest applies to par‐
70 ticular sections. Sections are started by a section keyword and are
71 terminated by an empty line or end of file. Every section defines an
72 object with a an identifier unique within that object class.
73 There are two basic object classes: Stores and Channels. A Store
75 defines a collection of mailboxes; basically a folder, either local or
76 remote. A Channel connects two Stores, describing the way the two are
77 synchronized.
78 There are two auxiliary object classes: Accounts and Groups. An Account
79 describes the connection part of remote Stores, so a server connection
80 can be shared between multiple Stores. A Group aggregates multiple
81 Channels to save typing on the command line.
82 All Stores
84 These options can be used in all supported Store types.
85 In this context, the term "remote" describes the second Store within a
86 Channel, and not necessarily a remote server.
87 The special mailbox INBOX exists in every Store; its physical location
88 in the file system is Store type specific.
89 Path path
91 The location of the Store in the (server's) file system. If
92 this is no absolute path, the reference point is Store type spe‐
93 cific. This string is prepended to the mailbox names addressed
94 in this Store, but is not considered part of them; this is
95 important for Patterns in the Channels section. Note that you
96 must append a slash if you want to specify an entire directory.
97 (Default: "")
98 MaxSize size[k|m][b]
100 Messages larger than that will not be propagated into this
101 Store. This is useful for weeding out messages with large
102 attachments. K and M can be appended to the size to specify
103 KiBytes resp. MeBytes instead of bytes. B is accepted but
104 superflous. If size is 0, the maximum message size is unlim‐
105 ited. (Default: 0)
106 MapInbox mailbox
108 Create a virtual mailbox (relative to Path), which is backed by
109 the INBOX. Makes sense in conjunction with Patterns in the Chan‐
110 nels section.
111 Trash mailbox
113 Specifies a mailbox (relative to Path) to copy deleted messages
114 to prior to expunging. See INHERENT PROBLEMS below. (Default:
115 none)
116 TrashNewOnly yes|no
118 When trashing, copy only not yet propagated messages. This makes
119 sense if the remote Store has a Trash as well (with TrashNewOnly
120 no). (Default: no)
121 TrashRemoteNew yes|no
123 When expunging the remote Store, copy not yet propagated mes‐
124 sages to this Store's Trash. When using this, the remote Store
125 does not need an own Trash at all, yet all messages are
126 archived. (Default: no)
127 Maildir Stores
129 The reference point for relative Paths is $HOME.
130 As mbsync needs UIDs, but no standardized UID storage scheme exists for
132 Maildir, mbsync supports two schemes, each with its pros and cons.
133 The native scheme is stolen from the latest Maildir patches to c-client
134 and is therefore compatible with pine. The UID validity is stored in a
135 file named .uidvalidity; the UIDs are encoded in the file names of the
136 messages.
137 The alternative scheme is based on the UID mapping used by isync ver‐
138 sions 0.8 and 0.9.x. The invariant parts of the file names of the mes‐
139 sages are used as keys into a Berkeley database named .isyncuidmap.db,
140 which holds the UID validity as well.
141 The native scheme is faster, more space efficient, endianess indepen‐
142 dent and "human readable", but will be disrupted if a message is copied
143 from another mailbox without getting a new file name; this would result
144 in duplicated UIDs sooner or later, which in turn results in a UID
145 validity change, making synchronization fail. The alternative scheme
146 would fail if a MUA changed a message's file name in a part mbsync con‐
147 siders invariant; this would be interpreted as a message deletion and a
148 new message, resulting in unnecessary traffic.
149 Mutt is known to work fine with both schemes.
150 Use mdconvert to convert mailboxes from one scheme to the other.
151 MaildirStore name
153 Define the Maildir Store name, opening a section for its parame‐
154 ters.
155 AltMap yes|no
157 Use the alternative UID storage scheme for mailboxes in this
158 Store. This does not affect mailboxes that do already have a
159 UID storage scheme; use mdconvert to change it. (Default: no)
160 Inbox path
162 The location of the INBOX. This is not relative to Path.
163 (Default: ~/Maildir)
164 IMAP4 Accounts
166 IMAPAccount name
167 Define the IMAP4 Account name, opening a section for its parame‐
168 ters.
169 Host host
171 Specify the DNS name or IP address of the IMAP server.
172 Port port
174 Specify the TCP port number of the IMAP server. (Default: 143
175 for IMAP, 993 for IMAPS)
176 User username
178 Specify the login name on the IMAP server. (Default: current
179 local user)
180 Pass password
182 Specify the password for username on the IMAP server. Note that
183 this option is NOT required. If no password is specified in the
184 configuration file, mbsync will prompt you for it.
185 Tunnel command
187 Specify a command to run to establish a connection rather than
188 opening a TCP socket. This allows you to run an IMAP session
189 over an SSH tunnel, for example. This makes most other IMAPAc‐
190 count options superflous.
191 RequireCRAM yes|no
193 If set to yes, mbsync will abort the connection if no CRAM-MD5
194 authentication is possible. (Default: no)
195 UseIMAPS yes|no
197 If set to yes, the default for Port is changed to 993 and mbsync
198 will start SSL negotiation immediately after establishing the
199 connection to the server.
200 Note that modern servers support SSL on the regular IMAP port
201 143 via the STARTTLS extension, which will be used automatically
202 by default.
203 RequireSSL yes|no
205 mbsync will abort the connection if a TLS/SSL session cannot be
206 established with the IMAP server. (Default: yes)
207 CertificateFile path
209 File containing X.509 CA certificates used to verify server
210 identities. This option is mandatory if SSL is used. See SSL
211 CERTIFICATES below.
212 UseSSLv2 yes|no
214 Use SSLv2 for communication with the IMAP server over SSL?
215 Note that this option is deprecated for security reasons.
216 (Default: no)
217 UseSSLv3 yes|no
219 Use SSLv3 for communication with the IMAP server over SSL?
220 (Default: no)
221 UseTLSv1 yes|no
223 Use TLSv1 for communication with the IMAP server over SSL?
224 (Default: yes)
225 IMAP Stores
227 The reference point for relative Paths is whatever the server likes it
228 to be; probably the user's $HOME or $HOME/Mail on that server. The
229 location of INBOX is up to the server as well and is usually irrele‐
230 vant.
231 IMAPStore name
233 Define the IMAP4 Store name, opening a section for its parame‐
234 ters.
235 Account account
237 Specify which IMAP4 Account to use. Instead of defining an
238 Account and referencing it here, it is also possible to specify
239 all the Account options directly in the Store's section - this
240 makes sense if an Account is used for one Store only anyway.
241 UseNamespace yes|no
243 Selects whether the server's first "personal" NAMESPACE should
244 be prefixed to mailbox names. Disabling this makes sense for
245 some broken IMAP servers. This option is meaningless if a Path
246 was specified. (Default: yes)
247 Channels
249 Channel name
250 Define the Channel name, opening a section for its parameters.
251 {Master|Slave} :store:[mailbox]
253 Specify the Master resp. Slave Store to be connected by this
254 Channel. If mailbox is omitted, INBOX is assumed. The mailbox
255 specification can be overridden by Patterns, which in turn can
256 be overridden by a mailbox list in a Channel reference (a Group
257 specification or the command line).
258 Pattern[s] [!]pattern ...
260 Instead of synchronizing only one mailbox pair, synchronize all
261 mailboxes that match the pattern(s). The mailbox names are the
262 same on both Master and Slave. Patterns are IMAP4 patterns,
263 i.e., * matches anything and % matches anything up to the next
264 hierarchy delimiter. Prepending ! to a pattern makes it an
265 exclusion. Multiple patterns can be specified (either by supply‐
266 ing multiple arguments or by using Pattern multiple times);
267 later matches take precedence. Example: "Patterns % !Trash"
268 MaxSize size[k|m][b]
270 Analogous to the homonymous option in the Stores section, but
271 applies equally to Master and Slave. Note that this actually
272 modifies the Stores, so take care not to provide conflicting
273 settings if you use the Stores in multiple Channels.
274 MaxMessages count
276 Sets the maximum number of messages to keep in each Slave mail‐
277 box. This is useful for mailboxes where you keep a complete ar‐
278 chive on the server, but want to mirror only the last messages
279 (for instance, for mailing lists). The messages that were the
280 first to arrive in the mailbox (independently of the actual date
281 of the message) will be deleted first. Messages that are
282 flagged (marked as important) and recent messages will not be
283 automatically deleted. If count is 0, the maximum number of
284 messages is unlimited (Default: 0).
285 Sync {None|[Pull] [Push] [New] [ReNew] [Delete] [Flags]|Full}
287 Select the synchronization operation(s) to perform:
288 Pull - propagate changes from Master to Slave.
289 Push - propagate changes from Slave to Master.
290 New - propagate newly appeared messages.
291 ReNew - previously refused messages are re-evaluated for propa‐
292 gation. Useful after flagging affected messages in the source
293 Store or enlarging MaxSize in the destination Store.
294 Delete - propagate message deletions. This applies only to mes‐
295 sages that are actually gone, i.e., were expunged. The affected
296 messages in the remote Store are marked as deleted only, i.e.,
297 they won't be really deleted until that Store is expunged.
298 Flags - propagate flag changes. Note that Deleted/Trashed is a
299 flag as well; this is particularily interesting if you use mutt
300 with the maildir_trash option.
301 All (--full on the command line) - all of the above. This is
302 the global default.
303 None (--noop on the command line) - don't propagate anything.
304 Useful if you want to expunge only.
305 Pull and Push are direction flags, while New, ReNew, Delete and
307 Flags are type flags. The two flag classes make up a two-dimen‐
308 sional matrix (a table). Its cells are the individual actions to
309 perform. There are two styles of asserting the cells:
310 In the first style, the flags select entire rows/colums in the
311 matrix. Only the cells which are selected both horizontally and
312 vertically are asserted. Specifying no flags from a class is
313 like specifying all flags from this class. For example,
314 "Sync Pull New Flags" will propagate new messages and flag
315 changes from the Master to the Slave, "Sync New Delete" will
316 propagate message arrivals and deletions both ways, and
317 "Sync Push" will propagate all changes from the Slave to the
318 Master.
319 In the second style, direction flags are concatenated with type
320 flags; every compound flag immediately asserts a cell in the
321 matrix. In addition to at least one compound flag, the individ‐
322 ual flags can be used as well, but as opposed to the first
323 style, they immediately assert all cells in their respective
324 row/column. For example, "Sync PullNew PullDelete Push" will
325 propagate message arrivals and deletions from the Master to the
326 Slave and any changes from the Slave to the Master. Note that
327 it is not allowed to assert a cell in two ways, e.g.
328 "Sync PullNew Pull" and "Sync PullNew Delete Push" induce error
329 messages.
330 Create {None|Master|Slave|Both}
332 Automatically create missing mailboxes [on the Master/Slave].
333 Otherwise print an error message and skip that mailbox pair if a
334 mailbox does not exist. (Global default: None)
335 Expunge {None|Master|Slave|Both}
337 Permanently remove all messages [on the Master/Slave] marked for
338 deletion. (Global default: None)
339 Sync, Create and Expunge can be used outside any section for a global
341 effect. The global settings are overridden by Channel-specific options,
342 which in turn are overridden by command line switches.
343 SyncState {*|path}
345 Set the location of this Channel's synchronization state files.
346 * means that the state should be saved in a file named .mbsync‐
347 state in the Slave mailbox itself; this has the advantage that
348 you needn't to care for the state file if you delete the mail‐
349 box, but it works only with Maildir mailboxes, obviously. Other‐
350 wise this is interpreted as a string to prepend to the Slave
351 mailbox name to make up a complete path.
352 This option can be used outside any section for a global effect.
353 In this case the appended string is made up according to the
354 pattern :master:master-box_:slave:slave-box.
355 (Global default: ~/.mbsync/).
356 Groups
358 Group name [channel[:box[,...]]] ...
359 Define the Group name, opening a section for its parameters.
360 Note that even though Groups have an own namespace, they will
361 "hide" Channels with the same name on the command line.
362 One or more Channels can be specified on the same line.
363 If you supply one or more boxes to a channel, they will be used
364 instead of what is specified in the Channel. The same can be
365 done on the command line, except that there newlines can be used
366 as mailbox name separators as well.
367 Channel[s] channel[:box[,...]] ...
369 Add the specified channels to the group. This option can be
370 specified multiple times within a Group.
371
373 [to be done]
374
376 Changes done after mbsync has retrieved the message list will not be
377 synchronised until the next time mbsync is invoked.
378 Using Trash on IMAP Stores bears a race condition: messages will be
380 lost if they are marked as deleted after the message list was retrieved
381 but before the mailbox is expunged. There is no risk as long as the
382 IMAP mailbox is not simultaneously accessed by mbsync and another mail
383 client.
384
386 ~/.mbsyncrc
387 Default configuration file
388 ~/.mbsync/
390 Directory containing synchronization state files
391
393 mdconvert(1), isync(1), mutt(1), maildir(5)
394 Up to date information on mbsync can be found at http://isync.sf.net/
396
398 Written by Michael R. Elkins <me@mutt.org>,
399 rewritten and maintained by Oswald Buddenhagen <ossi@users.sf.net>,
400 contributions by Theodore Y. Ts'o <tytso@mit.edu>.
401 2004 Mar 27 mbsync(1)