docs: full refactoring of the MANUAL
Signed-off-by: Nicolas Sebrecht <nicolas.s-dev@laposte.net>
This commit is contained in:
Nicolas Sebrecht
408
docs/offlineimap.txt
Normal file
408
docs/offlineimap.txt
Normal file
@ -0,0 +1,408 @@
|
||||
|
||||
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 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>.
|
||||
|
||||
|
||||
-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.
|
||||
|
||||
|
||||
-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, 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 continueing,
|
||||
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 know 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 fingerprint is
|
||||
being planned, it is not implemented yet. 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 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:
|
||||
|
||||
* 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
|
||||
|
||||
* 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
|
||||
|
||||
* 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.
|
||||
|
||||
|
||||
* 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.
|
||||
|
||||
|
||||
Authors
|
||||
-------
|
||||
|
||||
John Goerzen, Sebastian Spaetz, Eygene Ryabinkin, Nicolas Sebrecht.
|
||||
|
||||
|
||||
See Also
|
||||
--------
|
||||
|
||||
offlineimapui(7), openssl(1), signal(7), sqlite3(1).
|
||||
http://offlineimap.github.io
|
||||
Reference in New Issue
Block a user