Ubuntu Manpage: mbsync - synchronize IMAP4 and Maildir mailboxes

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 ("), 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 "INBOXdelim" 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. (Default: current local user)

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

AUTHORS

       Originally written by Michael R. Elkins, rewritten  and  currently  maintained  by  Oswald
       Buddenhagen, contributions by Theodore Y. Ts'o.

                                           2013 Dec 14                                  mbsync(1)