432 lines
15 KiB
Plaintext
432 lines
15 KiB
Plaintext
|
|
offlineimap(1)
|
|
==============
|
|
|
|
NAME
|
|
----
|
|
offlineimap - Synchronize mailboxes and Maildirs
|
|
|
|
SYNOPSIS
|
|
--------
|
|
[verse]
|
|
'offlineimap' (options)
|
|
|
|
DESCRIPTION
|
|
-----------
|
|
|
|
Synchronize the accounts configured in the configuration file via IMAP. Each
|
|
account has two sides.
|
|
|
|
One of the side must be an IMAP server.
|
|
The other side can either be a Maildir or another IMAP server.
|
|
|
|
|
|
OPTIONS
|
|
-------
|
|
|
|
-h::
|
|
--help::
|
|
|
|
Display summary of options.
|
|
|
|
--version::
|
|
|
|
Output version.
|
|
|
|
--dry-run::
|
|
|
|
Run in dry run mode.
|
|
+
|
|
Do not actually modify any store but check and print what synchronization
|
|
actions would be taken if a sync would be performed. It will not precisely
|
|
give the exact information what will happen. If e.g. we need to create a
|
|
folder, it merely outputs 'Would create folder X', but not how many and which
|
|
mails it would transfer.
|
|
|
|
|
|
--info::
|
|
|
|
Output information on the configured email repositories.
|
|
+
|
|
Useful for debugging and bug reporting. Use in conjunction with the -a option
|
|
to limit the output to a single account. This mode will prevent any actual
|
|
sync to occur and exits after it outp ut the debug information.
|
|
|
|
|
|
-1::
|
|
|
|
Limit multithreading operations and run solely a single-thread sync.
|
|
+
|
|
This effectively sets the maxsyncaccounts and all maxconnections configuration
|
|
file variables to 1. This is 1, the number.
|
|
|
|
|
|
-P <directory>::
|
|
|
|
Set OfflineIMAP into profile mode.
|
|
+
|
|
The program will create DIR (it must not already exist). As it runs, Python
|
|
profiling information about each thread is logged into profiledir. Please
|
|
note: This option is present for debugging and optimization only, and should
|
|
NOT be used unless you have a specific reason to do so. It will significantly
|
|
decrease program performance, may reduce reliability, and can generate huge
|
|
amounts of data. This option implies the -1 option.
|
|
|
|
|
|
-a <account1[,account2[,...]]>::
|
|
|
|
Overrides the accounts section in the config file.
|
|
+
|
|
Allows one to specify a particular account or set of accounts to sync without
|
|
having to edit the config file.
|
|
|
|
|
|
-c <path/to/configuration_file>::
|
|
|
|
Specifies a configuration file to use.
|
|
|
|
|
|
-d <type1[,type2[,...]]>::
|
|
|
|
Enables debugging for OfflineIMAP.
|
|
+
|
|
This is useful if you are to track down a malfunction or figure out what is
|
|
going on under the hood. This option requires one or more debugtypes,
|
|
separated by commas. These define what exactly will be debugged, and so far
|
|
include two options: imap, thread, maildir or ALL. The imap option will enable
|
|
IMAP protocol stream and parsing debugging. Note that the output may contain
|
|
passwords, so take care to remove that from the debugging output before
|
|
sending it to anyone else. The maildir option will enable debugging for
|
|
certain Maildir operations. The use of any debug option (unless 'thread' is
|
|
included), implies the single-thread option -1.
|
|
|
|
|
|
-l <path/to/file.log>::
|
|
|
|
Send logs to <file.log>.
|
|
|
|
-s::
|
|
|
|
Send logs to syslog.
|
|
|
|
|
|
-f <folder1[,folder1[,...]]>::
|
|
|
|
Only sync the specified folders.
|
|
+
|
|
The folder names are the untranslated foldernames of the remote repository.
|
|
This command-line option overrides any 'folderfilter' and 'folderincludes'
|
|
options in the configuration file.
|
|
|
|
-k <[section:]option=value::
|
|
|
|
Override any configuration file option.
|
|
+
|
|
If "section" is omitted, it defaults to "general". Any underscores in the
|
|
section name are replaced with spaces: for instance, to override option
|
|
"autorefresh" in the "[Account Personal]" section in the config file one would
|
|
use "-k Account_Personal:autorefresh=30". Repeat this option as much as
|
|
necessary to redefine multiple options.
|
|
|
|
-o::
|
|
|
|
Run only once.
|
|
+
|
|
Ignore any autorefresh setting in the configuration file.
|
|
|
|
-q::
|
|
|
|
Run only quick synchronizations.
|
|
+
|
|
Ignore any flag updates on IMAP servers. If a flag on the remote IMAP changes,
|
|
and we have the message locally, it will be left untouched in a quick run. This
|
|
option is ignored if maxage is set.
|
|
|
|
|
|
-u <UI>::
|
|
|
|
Specifies an alternative user interface to use.
|
|
+
|
|
This overrides the default specified in the configuration file. The UI
|
|
specified with -u will be forced to be used, even if checks determine that it
|
|
is not usable. Possible interface choices are: quiet, basic, syslog, ttyui,
|
|
blinkenlights, machineui.
|
|
|
|
|
|
|
|
--column[=<options>]::
|
|
--no-column::
|
|
Display branch listing in columns. See configuration variable
|
|
column.branch for option syntax.`--column` and `--no-column`
|
|
without options are equivalent to 'always' and 'never' respectively.
|
|
+
|
|
This option is only applicable in non-verbose mode.
|
|
|
|
|
|
Synchronization Performance
|
|
---------------------------
|
|
|
|
By default, we use fairly conservative settings that are safe for syncing but
|
|
that might not be the best performing one. Once you got everything set up and
|
|
running, you might want to look into speeding up your synchronization. Here
|
|
are a couple of hints and tips on how to achieve this.
|
|
|
|
1. Use maxconnections > 1.
|
|
+
|
|
By default we only use one connection to an IMAP server. Using 2 or even 3
|
|
speeds things up considerably in most cases. This setting goes into the
|
|
[Repository XXX] section.
|
|
|
|
2. Use folderfilters.
|
|
+
|
|
The quickest sync is a sync that can ignore some folders. I sort my inbox into
|
|
monthly folders, and ignore every folder that is more than 2-3 months old,
|
|
this lets me only inspect a fraction of my Mails on every sync. If you haven't
|
|
done this yet, do it :). See the folderfilter section the example
|
|
offlineimap.conf.
|
|
|
|
3. The cache.
|
|
+
|
|
The default status cache is a plain text file that will write out the complete
|
|
file for each single new message (or even changed flag) to a temporary file.
|
|
If you have plenty of files in a folder, this is a few hundred kilo to
|
|
megabytes for each mail and is bound to make things slower. I recommend to use
|
|
the sqlite backend for that. See the status_backend = sqlite setting in the
|
|
example offlineimap.conf. You will need to have python-sqlite installed in
|
|
order to use this. This will save you plenty of disk activity. Do note that
|
|
the sqlite backend is still considered experimental as it has only been
|
|
included recently (although a loss of your status cache should not be a
|
|
tragedy as that file can be rebuilt automatically)
|
|
|
|
4. Use quick sync.
|
|
+
|
|
A regular sync will request all flags and all UIDs of all mails in each folder
|
|
which takes quite some time. A 'quick' sync only compares the number of
|
|
messages in a folder on the IMAP side (it will detect flag changes on the
|
|
Maildir side of things though). A quick sync on my smallish account will take
|
|
7 seconds rather than 40 seconds. Eg, I run a cron script that does a regular
|
|
sync once a day, and does quick syncs (-q) only synchronizing the "-f INBOX"
|
|
in between.
|
|
|
|
5. Turn off fsync.
|
|
+
|
|
In the [general] section you can set fsync to True or False. If you want to
|
|
play 110% safe and wait for all operations to hit the disk before continuing,
|
|
you can set this to True. If you set it to False, you lose some of that
|
|
safety, trading it for speed.
|
|
|
|
|
|
Upgrading from plain text to SQLite cache format
|
|
------------------------------------------------
|
|
|
|
OfflineImap uses a cache to store the last known status of mails (flags etc).
|
|
|
|
Historically that has meant plain text files, but recently we introduced
|
|
sqlite-based cache, which helps with performance and CPU usage on large
|
|
folders. Here is how to upgrade existing plain text cache installations to
|
|
sqlite based one:
|
|
|
|
1. Sync to make sure things are reasonably similar.
|
|
|
|
2. Change the account section to "status_backend = sqlite".
|
|
|
|
3. Run a new sync.
|
|
+
|
|
This will convert your plain text cache to an sqlite cache (but leave
|
|
the old plain text cache around for easy reverting). This must be quick and
|
|
not involve any mail up/downloading.
|
|
|
|
4. See if it works! :-)
|
|
|
|
5. If it does not work, go back to the old version or set "status_backend = plain"
|
|
|
|
6. Delete the old text cache files.
|
|
|
|
Once you are sure it works, you can delete the
|
|
~/.offlineimap/Account-foo/LocalStatus folder (the new cache will be in the
|
|
LocalStatus-sqlite folder)
|
|
|
|
|
|
Security and SSL
|
|
----------------
|
|
|
|
By default, OfflineIMAP will connect using any method that 'openssl' supports,
|
|
that is SSLv2, SSLv3, or TLSv1.
|
|
|
|
Do note that SSLv2 is notoriously insecure and deprecated. Unfortunately,
|
|
python2 does not offer easy ways to disable SSLv2. It is recommended you test
|
|
your setup and make sure that the mail server does not use an SSLv2
|
|
connection. Use e.g. "openssl s_client -host mail.server -port 443" to find
|
|
out the connection that is used by default.
|
|
|
|
* Certificate checking
|
|
+
|
|
Unfortunately, by default we will not verify the certificate of an IMAP
|
|
TLS/SSL server we connect to, so connecting by SSL is no guarantee against
|
|
man-in-the-middle attacks. While verifying a server certificate checking the
|
|
fingerprint is recommended. There is currently only one safe way
|
|
to ensure that you connect to the correct server in an encrypted manner: you
|
|
can specify a 'sslcacertfile' setting in your repository section of
|
|
offlineimap.conf pointing to a file that contains (among others) a CA
|
|
Certificate in PEM format which validating your server certificate. In this
|
|
case, we will check that:
|
|
|
|
1. The server SSL certificate is validated by the CA Certificate.
|
|
|
|
2. The server host name matches the SSL certificate.
|
|
|
|
3. The server certificate is not past its expiration date.
|
|
|
|
The FAQ has an entry on how to create your own certificate and CA certificate.
|
|
|
|
* StartTLS
|
|
+
|
|
If you have not configured your account to connect via SSL anyway, OfflineImap
|
|
will still attempt to set up an SSL connection via the STARTTLS function, in
|
|
case the imap server supports it.
|
|
+
|
|
There is no certificate or fingerprint checking involved at all, when using
|
|
STARTTLS (the underlying imaplib library does not support this yet). This
|
|
means that you will be protected against passively listening eavesdroppers and
|
|
they will not be able to see your password or email contents. However, this
|
|
will not protect you from active attacks, such as Man-In-The-Middle attacks
|
|
which cause you to connect to the wrong server and pretend to be your mail
|
|
server.
|
|
+
|
|
DO NOT RELY ON STARTTLS AS A SAFE CONNECTION GUARANTEEING THE AUTHENTICITY OF
|
|
YOUR IMAP SERVER!
|
|
|
|
|
|
Unix Signals
|
|
------------
|
|
|
|
OfflineImap listens to the unix signals SIGUSR1, SIGUSR2, SIGTERM, SIGINT,
|
|
SIGHUP, SIGQUIT.
|
|
|
|
* If sent a SIGUSR1 it will abort any current (or next future) sleep of all
|
|
accounts that are configured to "autorefresh". In effect, this will trigger a
|
|
full sync of all accounts to be performed as soon as possible.
|
|
|
|
* If sent a SIGUSR2, it will stop "autorefresh mode" for all accounts. That
|
|
is, accounts will abort any current sleep and will exit after a currently
|
|
running synchronization has finished. This signal can be used to gracefully
|
|
exit out of a running offlineimap "daemon".
|
|
|
|
* SIGTERM, SIGINT, SIGHUP are all treated to gracefully terminate as soon as
|
|
possible. This means it will finish syncing the current folder in each
|
|
account, close keep alive connections, remove locks on the accounts and exit.
|
|
+
|
|
It may take up to 10 seconds, if autorefresh option is used.
|
|
|
|
* If sent SIGQUIT, dumps stack traces for all threads and tries to dump
|
|
process core.
|
|
|
|
|
|
Known Issues
|
|
------------
|
|
|
|
* SSL3 write pending.
|
|
+
|
|
Users enabling SSL may hit a bug about "SSL3 write pending". If so, the
|
|
account(s) will stay unsynchronised from the time the bug appeared. Running
|
|
OfflineIMAP again can help. We are still working on this bug. Patches or
|
|
detailed bug reports would be appreciated. Please check you're running the
|
|
last stable version and send us a report to the mailing list including the
|
|
full log.
|
|
|
|
* IDLE support is incomplete and experimental. Bugs may be encountered.
|
|
|
|
- No hook exists for "run after an IDLE response".
|
|
+
|
|
Email will show up, but may not be processed until the next refresh cycle.
|
|
|
|
- nametrans may not be supported correctly.
|
|
|
|
- IMAP IDLE <-> IMAP IDLE doesn't work yet.
|
|
|
|
- IDLE might stop syncing on a system suspend/resume.
|
|
|
|
- IDLE may only work "once" per refresh.
|
|
+
|
|
If you encounter this bug, please send a report to the list!
|
|
|
|
* Maildir support in Windows drive.
|
|
+
|
|
Maildir uses colon caracter (:) in message file names. Colon is however
|
|
forbidden character in windows drives. There are several workarounds for that
|
|
situation:
|
|
|
|
. Enable file name character translation in windows registry (not tested).
|
|
- <http://support.microsoft.com/kb/289627>
|
|
|
|
. Use cygwin managed mount (not tested).
|
|
- not available anymore since cygwin 1.7
|
|
|
|
. Use "maildir-windows-compatible = yes" account OfflineIMAP configuration.
|
|
- That makes OfflineIMAP to use exclamation mark (!) instead of colon for
|
|
storing messages. Such files can be written to windows partitions. But
|
|
you will probably loose compatibility with other programs trying to
|
|
read the same Maildir.
|
|
+
|
|
- Exclamation mark was chosen because of the note in
|
|
http://docs.python.org/library/mailbox.html
|
|
+
|
|
- If you have some messages already stored without this option, you will
|
|
have to re-sync them again
|
|
|
|
* OfflineIMAP confused after system suspend.
|
|
+
|
|
When resuming a suspended session, OfflineIMAP does not cleanly handles the
|
|
broken socket(s) if socktimeout option is not set.
|
|
You should enable this option with a value like 10.
|
|
|
|
* OfflineIMAP confused when mails change while in a sync.
|
|
+
|
|
When OfflineIMAP is syncing, some events happening since the invocation on
|
|
remote or local side are badly handled. OfflineIMAP won't track for changes
|
|
during the sync.
|
|
|
|
|
|
* Sharing a maildir with multiple IMAP servers.
|
|
+
|
|
Generally a word of caution mixing IMAP repositories on the same Maildir root.
|
|
You have to be careful that you *never* use the same maildir folder for 2 IMAP
|
|
servers. In the best case, the folder MD5 will be different, and you will get
|
|
a loop where it will upload your mails to both servers in turn (infinitely!)
|
|
as it thinks you have placed new mails in the local Maildir. In the worst
|
|
case, the MD5 is the same (likely) and mail UIDs overlap (likely too!) and it
|
|
will fail to sync some mails as it thinks they are already existent.
|
|
+
|
|
I would create a new local Maildir Repository for the Personal Gmail and
|
|
use a different root to be on the safe side here. You could e.g. use
|
|
|
|
`~/mail/Pro` as Maildir root for the ProGmail and
|
|
`~/mail/Personal` as root for the personal one.
|
|
+
|
|
If you then point your local mutt, or whatever MUA you use to `~/mail/`
|
|
as root, it should still recognize all folders.
|
|
|
|
|
|
* Edge cases with maxage causing too many messages to be synced.
|
|
+
|
|
All messages from at most maxage days ago (+/- a few hours, depending on
|
|
timezones) are synced, but there are cases in which older messages can also be
|
|
synced. This happens when a message's UID is significantly higher than those of
|
|
other messages with similar dates, e.g. when messages are added to the local
|
|
folder behind offlineimap's back, causing them to get assigned a new UID, or
|
|
when offlineimap first syncs a pre-existing Maildir. In the latter case, it
|
|
could appear as if a noticeable and random subset of old messages are synced.
|
|
|
|
|
|
Main authors
|
|
------------
|
|
|
|
John Goerzen, Sebastian Spaetz, Eygene Ryabinkin, Nicolas Sebrecht.
|
|
|
|
|
|
See Also
|
|
--------
|
|
|
|
offlineimapui(7), openssl(1), signal(7), sqlite3(1).
|
|
http://www.offlineimap.org
|