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}
- r{-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 (
"), and literal double quotes and backslashes (
\) must be
backslash-escaped. All keywords (including those used as arguments) are
case-insensitive. Bash-like home directory expansion using the tilde (
~) is supported in all options which represent local paths. 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 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.
File system locations (in particular,
Path and
Inbox) use the
Store's internal path separators, which may be slashes, periods, etc., or even
combinations thereof.
Mailbox names, OTOH, always use canonical path separators, which are Unix-like
forward slashes.
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 superfluous. If size is
0, the maximum message size is unlimited. (Default: 0)
- MapInbox mailbox
- Create a virtual mailbox (relative to Path) which aliases the
INBOX. Makes sense in conjunction with Patterns in the
Channels section, though with a Maildir slave, you probably want to place
Inbox under Path instead. This virtual mailbox does not
support subfolders.
- Flatten delim
- Flatten the hierarchy within this Store by substituting the canonical
hierarchy delimiter / with delim. This can be useful when
the MUA used to access the Store provides suboptimal handling of
hierarchical mailboxes, as is the case with Mutt. A common choice
for the delimiter is ..
Note that flattened sub-folders of the INBOX always end up under
Path, including the "INBOX delim" prefix.
- Trash mailbox
- Specifies a mailbox (relative to Path) to copy deleted messages to
prior to expunging. See RECOMMENDATIONS and 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 the current working directory.
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, endianness 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, but it is allowed to place the INBOX inside the
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.
- Pass password
- Specify the password for username on the IMAP server. Note that
this option is NOT required. If neither a password nor a password
command is specified in the configuration file, mbsync will prompt
you for a password.
- PassCmd command
- Specify a shell command to obtain a password rather than specifying a
password directly. This allows you to use password files and agents. The
command must produce exactly one line on stdout; the trailing newline is
optional.
- 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. Host and Port are ignored when Tunnel is
set.
- 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 additional X.509 certificates used to verify server
identities. Directly matched peer certificates are always trusted,
regardless of validity.
Note that the system's default certificate store is always used and should
not be specified here.
- 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)
- UseTLSv1.1 yes|no
- Use TLSv1.1 for communication with the IMAP server over SSL? (Default:
no)
- UseTLSv1.2 yes|no
- Use TLSv1.2 for communication with the IMAP server over SSL? (Default:
no)
- PipelineDepth depth
- Maximum number of IMAP commands which can be simultaneously in flight.
Setting this to 1 disables pipelining. This is mostly a debugging
only option. (Default: unlimited)
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)
- PathDelimiter delim
- Specify the server's hierarchy delimiter. (Default: taken from the
server's first "personal" NAMESPACE)
Do NOT abuse this to re-interpret the hierarchy. Use Flatten
instead.
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
Patterns are specified, mailbox is interpreted as a prefix
which is not matched against the patterns, and which is not affected by
mailbox list overrides. Otherwise, if mailbox is omitted,
INBOX is assumed.
- 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.
Note that INBOX is not matched by wildcards, unless it lives under
Path.
The mailbox list selected by Patterns can be overridden by a mailbox
list in a channel reference (a Group specification or the command
line).
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 (by default) unread messages will
not be automatically deleted. If count is 0, the maximum number of
messages is unlimited (Default: 0).
- ExpireUnread yes|no
- Selects whether unread messages should be affected by MaxMessages.
Normally, unread messages are considered important and thus never expired.
This ensures that you never miss new messages even after an extended
absence. However, if your archive contains large amounts of unread
messages by design, treating them as important would practically defeat
MaxMessages. In this case you need to enable this option. (Default:
no).
- Sync {None|[Pull] [Push] [New]
[ReNew] [ Delete] [Flags]|All}
- 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 particularly 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.
See RECOMMENDATIONS below. (Global default: None)
- CopyArrivalDate {yes|no}
- Selects whether their arrival time should be propagated together with the
messages. Enabling this makes sense in order to keep the time stamp based
message sorting intact. Note that IMAP does not guarantee that the time
stamp (termed internal date) is actually the arrival time,
but it is usually close enough. (Default: no)
Sync,
Create,
Expunge,
MaxMessages, and
CopyArrivalDate can be used before 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's Patterns. 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.
Global Options¶
- FSync yes|no
-
Selects whether mbsync performs forced flushing, which determines the
level of data safety after system crashes and power outages. Disabling it
is reasonably safe for file systems which are mounted with data=ordered
mode. Enabling it is a wise choice for file systems mounted with
data=writeback, in particular modern systems like ext4, btrfs and xfs. The
performance impact on older file systems may be disproportionate.
(Default: yes)
RECOMMENDATIONS¶
Make sure your IMAP server does not auto-expunge deleted messages - it is slow,
and semantically somewhat questionable. Specifically, Gmail needs to be
configured not to do it.
By default,
mbsync will not delete any messages - deletions are
propagated by marking the messages as deleted on the remote store. Once you
have verified that your setup works, you will typically want to set
Expunge to
Both, so that deletions become effective.
mbsync's built-in trash functionality relies on
mbsync doing the
expunging of deleted messages. This is the case when it propagates deletions
of previously propagated messages, and the trash is on the target store
(typically your IMAP server).
However, when you intend
mbsync to trash messages which were not
propagated yet, the MUA must mark the messages as deleted without expunging
them (e.g.,
Mutt's
maildir_trash option). Note that most
messages are propagated a long time before they are deleted, so this is a
corner case you probably do not want to optimize for. This also implies that
the
TrashNewOnly and
TrashRemoteNew options are typically not
very useful.
If your server supports auto-trashing (as Gmail does), it is probably a good
idea to rely on that instead of
mbsync's trash functionality. If you do
that, and intend to synchronize the trash like other mailboxes, you should not
use
mbsync's
Trash option at all.
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 without the UIDPLUS extension (notably, M$
Exchange up to at least 2010) 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 accessed
by only one client (including
mbsync) at a time.
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/
AUTHORS¶
Originally written by Michael R. Elkins, rewritten and currently maintained by
Oswald Buddenhagen, contributions by Theodore Y. Ts'o.