NAME
mbsync - synchronize IMAP4 and Maildir mailboxes
SYNOPSIS
mbsync [options ...] {{channel[:box[{,|\n}...]]|group} ...|-a}
DESCRIPTION
mbsync is a command line application which synchronizes mailboxes;
currently Maildir and IMAP4 mailboxes are supported. New messages,
message deletions and flag changes can be propagated both ways; the
operation set can be selected in a fine-grained manner.
Synchronization is based on unique message identifiers (UIDs), so no
identification conflicts can occur (as opposed to some other mail
synchronizers). OTOH, mbsync is susceptible to UID validity changes
(that should never happen, but see "Compatibility" in the README).
Synchronization state is kept in one local text file per mailbox pair;
multiple replicas of a mailbox can be maintained.
OPTIONS
-c, --config file
Read configuration from file. By default, the configuration is
read from ~/.mbsyncrc.
-a, --all
Select all configured channels. Any channel/group specifications
on the command line are ignored.
-l, --list
Don’t synchronize anything, but list all mailboxes in the
selected channels and exit.
-C[m][s], --create[-master|-slave]
Override any Create options from the config file. See below.
-X[m][s], --expunge[-master|-slave]
Override any Expunge options from the config file. See below.
{-n|-N|-d|-f|-0|-F}, {--new|--renew|--delete|--flags|--noop|--full}
{-L|-H}[n][N][d][f], {--pull|--push}[-new|-renew|-delete|-flags]
Override any Sync options from the config file. See below.
-h, --help
Display a summary of command line options.
-v, --version
Display version information.
-V, --verbose
Enable verbose mode, which displays the IMAP4 network traffic.
-D, --debug
Enable printing debug information.
-q, --quiet
Suppress informational messages. If specified twice, suppress
warning messages as well.
CONFIGURATION
The configuration file is mandatory; mbsync will not run without it.
Lines starting with a hash mark (#) are comments and are ignored
entirely. Configuration items are keywords followed by one or more
arguments; arguments containing spaces must be enclosed in double
quotes ("). All keywords (including those used as arguments) are case-
insensitive. There are a few global options, the rest applies to
particular sections. Sections are started by a section keyword and are
terminated by an empty line or end of file. Every section defines an
object with a an identifier unique within that object class.
There are two basic object classes: Stores and Channels. A Store
defines a collection of mailboxes; basically a folder, either local or
remote. A Channel connects two Stores, describing the way the two are
synchronized.
There are two auxiliary object classes: Accounts and Groups. An Account
describes the connection part of remote Stores, so a server connection
can be shared between multiple Stores. A Group aggregates multiple
Channels to save typing on the command line.
All Stores
These options can be used in all supported Store types.
In this context, the term "remote" describes the second Store within a
Channel, and not necessarily a remote server.
The special mailbox INBOX exists in every Store; its physical location
in the file system is Store type specific.
Path path
The location of the Store in the (server’s) file system. If
this is no absolute path, the reference point is Store type
specific. This string is prepended to the mailbox names
addressed in this Store, but is not considered part of them;
this is important for Patterns in the Channels section. Note
that you must append a slash if you want to specify an entire
directory. (Default: "")
MaxSize size[k|m][b]
Messages larger than that will not be propagated into this
Store. This is useful for weeding out messages with large
attachments. K and M can be appended to the size to specify
KiBytes resp. MeBytes instead of bytes. B is accepted but
superflous. If size is 0, the maximum message size is
unlimited. (Default: 0)
MapInbox mailbox
Create a virtual mailbox (relative to Path), which is backed by
the INBOX. Makes sense in conjunction with Patterns in the
Channels section.
Trash mailbox
Specifies a mailbox (relative to Path) to copy deleted messages
to prior to expunging. See INHERENT PROBLEMS below. (Default:
none)
TrashNewOnly yes|no
When trashing, copy only not yet propagated messages. This makes
sense if the remote Store has a Trash as well (with TrashNewOnly
no). (Default: no)
TrashRemoteNew yes|no
When expunging the remote Store, copy not yet propagated
messages to this Store’s Trash. When using this, the remote
Store does not need an own Trash at all, yet all messages are
archived. (Default: no)
Maildir Stores
The reference point for relative Paths is $HOME.
As mbsync needs UIDs, but no standardized UID storage scheme exists for
Maildir, mbsync supports two schemes, each with its pros and cons.
The native scheme is stolen from the latest Maildir patches to c-client
and is therefore compatible with pine. The UID validity is stored in a
file named .uidvalidity; the UIDs are encoded in the file names of the
messages.
The alternative scheme is based on the UID mapping used by isync
versions 0.8 and 0.9.x. The invariant parts of the file names of the
messages are used as keys into a Berkeley database named
.isyncuidmap.db, which holds the UID validity as well.
The native scheme is faster, more space efficient, endianess
independent and "human readable", but will be disrupted if a message is
copied from another mailbox without getting a new file name; this would
result in duplicated UIDs sooner or later, which in turn results in a
UID validity change, making synchronization fail. The alternative
scheme would fail if a MUA changed a message’s file name in a part
mbsync considers invariant; this would be interpreted as a message
deletion and a new message, resulting in unnecessary traffic.
Mutt is known to work fine with both schemes.
Use mdconvert to convert mailboxes from one scheme to the other.
MaildirStore name
Define the Maildir Store name, opening a section for its
parameters.
AltMap yes|no
Use the alternative UID storage scheme for mailboxes in this
Store. This does not affect mailboxes that do already have a
UID storage scheme; use mdconvert to change it. (Default: no)
Inbox path
The location of the INBOX. This is not relative to Path.
(Default: ~/Maildir)
IMAP4 Accounts
IMAPAccount name
Define the IMAP4 Account name, opening a section for its
parameters.
Host host
Specify the DNS name or IP address of the IMAP server.
Port port
Specify the TCP port number of the IMAP server. (Default: 143
for IMAP, 993 for IMAPS)
User username
Specify the login name on the IMAP server. (Default: current
local user)
Pass password
Specify the password for username on the IMAP server. Note that
this option is NOT required. If no password is specified in the
configuration file, mbsync will prompt you for it.
Tunnel command
Specify a command to run to establish a connection rather than
opening a TCP socket. This allows you to run an IMAP session
over an SSH tunnel, for example. This makes most other
IMAPAccount options superflous.
RequireCRAM yes|no
If set to yes, mbsync will abort the connection if no CRAM-MD5
authentication is possible. (Default: no)
UseIMAPS yes|no
If set to yes, the default for Port is changed to 993 and mbsync
will start SSL negotiation immediately after establishing the
connection to the server.
Note that modern servers support SSL on the regular IMAP port
143 via the STARTTLS extension, which will be used automatically
by default.
RequireSSL yes|no
mbsync will abort the connection if a TLS/SSL session cannot be
established with the IMAP server. (Default: yes)
CertificateFile path
File containing X.509 CA certificates used to verify server
identities. This option is mandatory if SSL is used. See SSL
CERTIFICATES below.
UseSSLv2 yes|no
Use SSLv2 for communication with the IMAP server over SSL?
Note that this option is deprecated for security reasons.
(Default: no)
UseSSLv3 yes|no
Use SSLv3 for communication with the IMAP server over SSL?
(Default: no)
UseTLSv1 yes|no
Use TLSv1 for communication with the IMAP server over SSL?
(Default: yes)
IMAP Stores
The reference point for relative Paths is whatever the server likes it
to be; probably the user’s $HOME or $HOME/Mail on that server. The
location of INBOX is up to the server as well and is usually
irrelevant.
IMAPStore name
Define the IMAP4 Store name, opening a section for its
parameters.
Account account
Specify which IMAP4 Account to use. Instead of defining an
Account and referencing it here, it is also possible to specify
all the Account options directly in the Store’s section - this
makes sense if an Account is used for one Store only anyway.
UseNamespace yes|no
Selects whether the server’s first "personal" NAMESPACE should
be prefixed to mailbox names. Disabling this makes sense for
some broken IMAP servers. This option is meaningless if a Path
was specified. (Default: yes)
Channels
Channel name
Define the Channel name, opening a section for its parameters.
{Master|Slave} :store:[mailbox]
Specify the Master resp. Slave Store to be connected by this
Channel. If mailbox is omitted, INBOX is assumed. The mailbox
specification can be overridden by Patterns, which in turn can
be overridden by a mailbox list in a Channel reference (a Group
specification or the command line).
Pattern[s] [!]pattern ...
Instead of synchronizing only one mailbox pair, synchronize all
mailboxes that match the pattern(s). The mailbox names are the
same on both Master and Slave. Patterns are IMAP4 patterns,
i.e., * matches anything and % matches anything up to the next
hierarchy delimiter. Prepending ! to a pattern makes it an
exclusion. Multiple patterns can be specified (either by
supplying multiple arguments or by using Pattern multiple
times); later matches take precedence. Example:
"Patterns % !Trash"
MaxSize size[k|m][b]
Analogous to the homonymous option in the Stores section, but
applies equally to Master and Slave. Note that this actually
modifies the Stores, so take care not to provide conflicting
settings if you use the Stores in multiple Channels.
MaxMessages count
Sets the maximum number of messages to keep in each Slave
mailbox. This is useful for mailboxes where you keep a complete
archive on the server, but want to mirror only the last messages
(for instance, for mailing lists). The messages that were the
first to arrive in the mailbox (independently of the actual date
of the message) will be deleted first. Messages that are
flagged (marked as important) and recent messages will not be
automatically deleted. If count is 0, the maximum number of
messages is unlimited (Default: 0).
Sync {None|[Pull] [Push] [New] [ReNew] [Delete] [Flags]|Full}
Select the synchronization operation(s) to perform:
Pull - propagate changes from Master to Slave.
Push - propagate changes from Slave to Master.
New - propagate newly appeared messages.
ReNew - previously refused messages are re-evaluated for
propagation. Useful after flagging affected messages in the
source Store or enlarging MaxSize in the destination Store.
Delete - propagate message deletions. This applies only to
messages that are actually gone, i.e., were expunged. The
affected messages in the remote Store are marked as deleted
only, i.e., they won’t be really deleted until that Store is
expunged.
Flags - propagate flag changes. Note that Deleted/Trashed is a
flag as well; this is particularily interesting if you use mutt
with the maildir_trash option.
All (--full on the command line) - all of the above. This is
the global default.
None (--noop on the command line) - don’t propagate anything.
Useful if you want to expunge only.
Pull and Push are direction flags, while New, ReNew, Delete and
Flags are type flags. The two flag classes make up a two-
dimensional matrix (a table). Its cells are the individual
actions to perform. There are two styles of asserting the cells:
In the first style, the flags select entire rows/colums in the
matrix. Only the cells which are selected both horizontally and
vertically are asserted. Specifying no flags from a class is
like specifying all flags from this class. For example,
"Sync Pull New Flags" will propagate new messages and flag
changes from the Master to the Slave, "Sync New Delete" will
propagate message arrivals and deletions both ways, and
"Sync Push" will propagate all changes from the Slave to the
Master.
In the second style, direction flags are concatenated with type
flags; every compound flag immediately asserts a cell in the
matrix. In addition to at least one compound flag, the
individual flags can be used as well, but as opposed to the
first style, they immediately assert all cells in their
respective row/column. For example,
"Sync PullNew PullDelete Push" will propagate message arrivals
and deletions from the Master to the Slave and any changes from
the Slave to the Master. Note that it is not allowed to assert
a cell in two ways, e.g. "Sync PullNew Pull" and
"Sync PullNew Delete Push" induce error messages.
Create {None|Master|Slave|Both}
Automatically create missing mailboxes [on the Master/Slave].
Otherwise print an error message and skip that mailbox pair if a
mailbox does not exist. (Global default: None)
Expunge {None|Master|Slave|Both}
Permanently remove all messages [on the Master/Slave] marked for
deletion. (Global default: None)
Sync, Create and Expunge can be used outside any section for a global
effect. The global settings are overridden by Channel-specific options,
which in turn are overridden by command line switches.
SyncState {*|path}
Set the location of this Channel’s synchronization state files.
* means that the state should be saved in a file named
.mbsyncstate in the Slave mailbox itself; this has the advantage
that you needn’t to care for the state file if you delete the
mailbox, but it works only with Maildir mailboxes, obviously.
Otherwise this is interpreted as a string to prepend to the
Slave mailbox name to make up a complete path.
This option can be used outside any section for a global effect.
In this case the appended string is made up according to the
pattern :master:master-box_:slave:slave-box.
(Global default: ~/.mbsync/).
Groups
Group name [channel[:box[,...]]] ...
Define the Group name, opening a section for its parameters.
Note that even though Groups have an own namespace, they will
"hide" Channels with the same name on the command line.
One or more Channels can be specified on the same line.
If you supply one or more boxes to a channel, they will be used
instead of what is specified in the Channel. The same can be
done on the command line, except that there newlines can be used
as mailbox name separators as well.
Channel[s] channel[:box[,...]] ...
Add the specified channels to the group. This option can be
specified multiple times within a Group.
SSL CERTIFICATES
[to be done]
INHERENT PROBLEMS
Changes done after mbsync has retrieved the message list will not be
synchronised until the next time mbsync is invoked.
Using Trash on IMAP Stores bears a race condition: messages will be
lost if they are marked as deleted after the message list was retrieved
but before the mailbox is expunged. There is no risk as long as the
IMAP mailbox is not simultaneously accessed by mbsync and another mail
client.
FILES
~/.mbsyncrc
Default configuration file
~/.mbsync/
Directory containing synchronization state files
SEE ALSO
mdconvert(1), isync(1), mutt(1), maildir(5)
Up to date information on mbsync can be found at http://isync.sf.net/
AUTHOR
Written by Michael R. Elkins <me@mutt.org>,
rewritten and maintained by Oswald Buddenhagen <ossi@users.sf.net>,
contributions by Theodore Y. Ts’o <tytso@mit.edu>.
2004 Mar 27 mbsync(1)