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
       (unlike with some other mail synchronizers).  OTOH, mbsync is susceptible to UID  validity  changes  (but
       will recover just fine if the change is unfounded).  Synchronization state is kept in one local text file
       per mailbox pair; these files are protected against concurrent mbsync processes.  Mailboxes can be safely
       modified while mbsync operates (see INHERENT PROBLEMS below for a minor exception).  Multiple replicas of
       each 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.

       -R[m][s], --remove[-master|-slave]
              Override any Remove 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 what is currently happening.

       -D[C][d|D][m][M][n|N][s]], --debug[-crash|-driver|-driver-all|-maildir|-main|-net|-net-all|-sync]
              Enable debugging categories:
                  C, crash - use built-in crash handler
                  d, driver - print driver calls (metadata only)
                  D, driver-all - print driver calls (including messages)
                  m, maildir - print maildir debug info
                  M, main - print main debug info
                  n, net - print network traffic (protocol only)
                  N, net-all - print network traffic (including payloads)
                  s, sync - print synchronization debug info
              All  categories  except  crash implictly enable verbose mode.  Without category specification, all
              categories except net-all are enabled.

       -q, --quiet
              Suppress progress counters (this is implicit if stdout is no TTY, or any debugging categories  are
              enabled) and notices.  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:
none)

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. See
RECOMMENDATIONS below. (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)

InfoDelimiter delim
The character used to delimit the info field from a message's basename. The Maildir standard
defines this to be the colon, but this is incompatible with DOS/Windows file systems. (Default:
the value of FieldDelimiter)

SubFolders Verbatim|Maildir++|Legacy
The on-disk folder naming style used for hierarchical mailboxes. This has option has no effect
when Flatten is used.
Suppose mailboxes with the canonical paths top/sub/subsub and INBOX/sub/subsub, the styles will
yield the following on-disk paths:
Verbatim - Path/top/sub/subsub and Inbox/sub/subsub (this is the style you probably want to use)
Maildir++ - Inbox/.top.sub.subsub and Inbox/..sub.subsub (this style is compatible with Courier
and Dovecot - but note that the mailbox metadata format is not compatible). Note that attempts to
set Path are rejected in this mode.
Legacy - Path/top/.sub/.subsub and Inbox/.sub/.subsub (this is mbsync's historical style)
(Default: unset; will error out when sub-folders are encountered)

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.
If Tunnel is used, this setting is needed only if SSLType is not None and CertificateFile is not
used, in which case the host name is used for certificate subject verification.

Port port
Specify the TCP port number of the IMAP server. (Default: 143 for IMAP, 993 for IMAPS)
If Tunnel is used, this setting is ignored.

Timeout timeout
Specify the connect and data timeout for the IMAP server in seconds. Zero means unlimited.
(Default: 20)

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. Prepend + to the command to indicate that it produces TTY
output (e.g., a decryption password prompt); failure to do so will merely produce messier output.

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.

AuthMechs type ...
The list of acceptable authentication mechanisms. In addition to the mechanisms listed in the
SASL registry (link below), the legacy IMAP LOGIN mechanism is known. The wildcard * represents
all mechanisms that are deemed secure enough for the current SSLType setting. The actually used
mechanism is the most secure choice from the intersection of this list, the list supplied by the
server, and the installed SASL modules. (Default: *)

SSLType {None|STARTTLS|IMAPS}
Select the connection security/encryption method:
None - no security. This is the default when Tunnel is set, as tunnels are usually secure.
STARTTLS - security is established via the STARTTLS extension after connecting the regular IMAP
port 143. Most servers support this, so it is the default (unless a tunnel is used).
IMAPS - security is established by starting SSL/TLS negotiation right after connecting the secure
IMAP port 993.

SSLVersions [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2]
Select the acceptable SSL/TLS versions. Use old versions only when the server has problems with
newer ones. (Default: [TLSv1] [TLSv1.1] [TLSv1.2]).

SystemCertificates yes|no
Whether the system's default root cerificate store should be loaded. (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 (unless SystemCertificates is
disabled) and should not be specified here.

ClientCertificate path
File containing a client certificate to send to the server. ClientKey should also be specified.
Note that client certificate verification is usually not required, so it is unlikely that you need
this option.

ClientKey path
File containing the private key corresponding to ClientCertificate.

PipelineDepth depth
Maximum number of IMAP commands which can be simultaneously in flight. Setting this to 1 disables
pipelining. This is mostly a debugging option, but may also be used to limit average bandwidth
consumption (GMail may require this if you have a very fast connection), or to spare flaky servers
like M$ Exchange. (Default: unlimited)

DisableExtension[s] extension ...
Disable the use of specific IMAP extensions. This can be used to work around bugs in servers (and
possibly mbsync itself). (Default: empty)

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 and the corresponding sync state does not exist. (Global
default: None)

Remove {None|Master|Slave|Both}
Propagate mailbox deletions [to the Master/Slave]. Otherwise print an error message and skip that
mailbox pair if a mailbox does not exist but the corresponding sync state does.
For MailDir mailboxes it is sufficient to delete the cur/ subdirectory to mark them as deleted.
This ensures compatibility with SyncState *.
Note that for safety, non-empty mailboxes are never deleted.
(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, Remove, 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 (see also FieldDelimiter
below).
(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)

FieldDelimiter delim
The character to use to delimit fields in the string appended to a global SyncState. mbsync
prefers to use the colon, but this is incompatible with DOS/Windows file systems. This option is
meaningless for SyncState if the latter is *, obviously. However, it also determines the default
of InfoDelimiter. (Global default: ; on Windows, : everywhere else)

BufferLimit size[k|m][b]
The per-Channel, per-direction instantaneous memory usage above which mbsync will refrain from
using more memory. Note that this is no absolute limit, as even a single message can consume more
memory than this. (Default: 10M)

CONSOLE OUTPUT

       If mbsync's output is connected to a console, it will print progress counters by default. The output will
       look like this:

           C: 1/2  B: 3/4  M: +13/13 *23/42 #0/0  S: +0/7 *0/0 #0/0

       This  represents the cumulative progress over channels, boxes, and messages affected on master and slave,
       respectively.  The message counts represent added messages, messages  with  updated  flags,  and  trashed
       messages, respectively.  No attempt is made to calculate the totals in advance, so they grow over time as
       more information is gathered.

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.

Use of the Trash option with M$ Exchange 2013 requires the use of DisableExtension MOVE due to a server
bug.

When using the more efficient default UID mapping scheme, it is important that the MUA renames files when
moving them between Maildir folders. Mutt always does that, while mu4e needs to be configured to do it:
(setq mu4e-change-filenames-when-moving t)

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.

                                                   2015 Mar 22                                         mbsync(1)