move some documentation to the website
Signed-off-by: Nicolas Sebrecht <nicolas.s-dev@laposte.net>
This commit is contained in:
Nicolas Sebrecht
parent
171a7a0797
commit
bbc84ead0f
161
docs/INSTALL.rst
161
docs/INSTALL.rst
|
|
@ -1,161 +0,0 @@
|
|||
.. -*- coding: utf-8 -*-
|
||||
.. _OfflineIMAP: https://github.com/OfflineIMAP/offlineimap
|
||||
.. _OLI_git_repo: git://github.com/OfflineIMAP/offlineimap.git
|
||||
|
||||
============
|
||||
Installation
|
||||
============
|
||||
|
||||
.. contents::
|
||||
.. .. sectnum::
|
||||
|
||||
-----------------
|
||||
Development state
|
||||
-----------------
|
||||
|
||||
Since several months, the official maintainers Nicolas Sebrecht and Sebatian
|
||||
Spaeth are too much busy to actively contribute to this project.
|
||||
|
||||
In order to preserve contributions, a team of official maintainers have been
|
||||
promoted to have write access to the official repository at `OfflineIMAP`_.
|
||||
OfflineIMAP is now maintained by occasional contributors and the official
|
||||
maintainers. All the documentation links might not be up-to-date to reflect
|
||||
this change.
|
||||
|
||||
The best place to get the latest news about the development state is at the
|
||||
mailing list.
|
||||
|
||||
-------------
|
||||
Prerequisites
|
||||
-------------
|
||||
|
||||
In order to use `OfflineIMAP`_, you need to have these conditions satisfied:
|
||||
|
||||
1. Your mail server must support IMAP. Mail access via POP is not
|
||||
supported. A special Gmail mailbox type is available to interface
|
||||
with Gmail's IMAP front-end, although Gmail has a very peculiar and
|
||||
non-standard implementation of its IMAP interface.
|
||||
|
||||
2. You must have Python version 2.6 or above installed. If you are
|
||||
running on Debian GNU/Linux, this requirement will automatically be
|
||||
taken care of for you. If you intend to use the SSL interface,
|
||||
your Python must have been built with SSL support.
|
||||
|
||||
3. If you use OfflineImap as an IMAP<->Maildir synchronizer, you will
|
||||
obviously need to have a mail reader that supports the Maildir
|
||||
mailbox format. Most modern mail readers have this support built-in,
|
||||
so you can choose from a wide variety of mail servers. This format
|
||||
is also known as the "qmail" format, so any mail reader compatible
|
||||
with it will work with `OfflineIMAP`_.
|
||||
|
||||
|
||||
------------
|
||||
Installation
|
||||
------------
|
||||
|
||||
Installing OfflineImap should usually be quite easy, as you can simply unpack
|
||||
and run OfflineImap in place if you wish to do so. There are a number of options
|
||||
though:
|
||||
|
||||
#. system-wide :ref:`installation via your distribution package manager <inst_pkg_man>`
|
||||
#. system-wide or single user :ref:`installation from the source package <inst_src_tar>`
|
||||
#. system-wide or single user :ref:`installation from a git checkout <inst_git>`
|
||||
|
||||
Having installed OfflineImap, you will need to configure it, to be actually
|
||||
useful. Please check the :ref:`Configuration` section in the :doc:`MANUAL` for
|
||||
more information on the configuration step.
|
||||
|
||||
.. _inst_pkg_man:
|
||||
|
||||
System-Wide Installation via distribution
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
The easiest way to install OfflineIMAP is via your distribution's package
|
||||
manager. OfflineImap is available under the name `offlineimap` in most Linux and
|
||||
BSD distributions.
|
||||
|
||||
|
||||
.. _inst_src_tar:
|
||||
|
||||
Installation from source package
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Download the latest source archive from our `download page
|
||||
<https://github.com/spaetz/offlineimap/downloads>`_. Simply click the "Download
|
||||
as .zip" or "Download as .tar.gz" buttons to get the latest "stable" code from
|
||||
the master branch. If you prefer command line, you will want to use: wget
|
||||
https://github.com/spaetz/offlineimap/tarball/master
|
||||
|
||||
Unpack and continue with the :ref:`system-wide installation <system_wide_inst>`
|
||||
or the :ref:`single-user installation <single_user_inst>` section.
|
||||
|
||||
|
||||
.. _inst_git:
|
||||
|
||||
Installation from git checkout
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Get your own copy of the `official git repository <OLI_git_repo>`_ at `OfflineIMAP`_::
|
||||
|
||||
git clone https://github.com/OfflineIMAP/offlineimap.git
|
||||
|
||||
This will download the source with history. By default, git sets up the
|
||||
`master` branch up, which is most likely what you want. If not, you can
|
||||
checkout a particular release like this::
|
||||
|
||||
cd offlineimap
|
||||
git checkout v6.5.2.1
|
||||
|
||||
You have now a source tree available and proceed with either the
|
||||
:ref:`system-wide installation <system_wide_inst>` or the :ref:`single-user
|
||||
installation <single_user_inst>`.
|
||||
|
||||
|
||||
.. _system_wide_inst:
|
||||
|
||||
System-wide installation
|
||||
++++++++++++++++++++++++
|
||||
|
||||
Then run these commands, to build the python package::
|
||||
|
||||
make clean
|
||||
make
|
||||
|
||||
Finally, install the program (as root)::
|
||||
|
||||
python setup.py install
|
||||
|
||||
Next, proceed to below. Type `offlineimap` to invoke the program.
|
||||
|
||||
|
||||
.. _single_user_inst:
|
||||
|
||||
Single-user installation
|
||||
++++++++++++++++++++++++
|
||||
|
||||
Download the git repository as described above. Instead of installing the
|
||||
program as root, you type `./offlineimap.py`; there is no installation step
|
||||
necessary.
|
||||
|
||||
---------
|
||||
Uninstall
|
||||
---------
|
||||
|
||||
If you installed a system-wide installation via "python setup.py
|
||||
install", there are a few files to purge to cleanly uninstall
|
||||
`OfflineImap`_ again. Assuming that `/usr/local` is the standard prefix of
|
||||
your system and that you use python 2.7, you need to:
|
||||
|
||||
#) Delete the OfflineImap installation itself::
|
||||
|
||||
/usr/local/lib/python2.7/dist-packages/offlineimap-6.4.4.egg-info
|
||||
/usr/local/lib/python2.7/dist-packages/offlineimap
|
||||
|
||||
In case, you did the single-user installation, simply delete your
|
||||
offlineimap directory.
|
||||
|
||||
#) Delete all files that OfflineImap creates during its operation.
|
||||
- The cache at (default location) ~/.offlineimap
|
||||
- Your manually created (default loc) ~/.offlineimaprc
|
||||
(It is possible that you created those in different spots)
|
||||
|
||||
That's it. Have fun without OfflineImap.
|
||||
|
|
@ -1,516 +0,0 @@
|
|||
.. -*- coding: utf-8 -*-
|
||||
|
||||
.. NOTE TO MAINTAINERS: Please add new questions to the end of their
|
||||
sections, so section/question numbers remain stable.
|
||||
|
||||
.. _mailing list: http://lists.alioth.debian.org/mailman/listinfo/offlineimap-project
|
||||
.. _OfflineIMAP: https://github.com/OfflineIMAP/offlineimap
|
||||
.. _ssl.wrap_socket: http://docs.python.org/library/ssl.html#ssl.wrap_socket
|
||||
.. _Advanced Git: https://github.com/OfflineIMAP/offlineimap/blob/next/docs/doc-src/GitAdvanced.rst
|
||||
.. _FAQ: https://github.com/OfflineIMAP/offlineimap/blob/next/docs/doc-src/FAQ.rst
|
||||
.. _Contributing: https://github.com/OfflineIMAP/offlineimap/blob/next/CONTRIBUTING.rst
|
||||
|
||||
|
||||
|
||||
|
||||
=============================================
|
||||
OfflineIMAP FAQ (Frequently Asked Questions)
|
||||
=============================================
|
||||
|
||||
:Web site: https://github.com/nicolas33/offlineimap
|
||||
:Copyright: This document is licensed under GPLv2.
|
||||
|
||||
.. contents::
|
||||
.. sectnum::
|
||||
|
||||
|
||||
Please feel free to ask questions and/or provide answers; send email to the
|
||||
`mailing list`_.
|
||||
|
||||
Most recent `FAQ`_.
|
||||
|
||||
|
||||
OfflineIMAP
|
||||
===========
|
||||
|
||||
Where do I get OfflineIMAP?
|
||||
---------------------------
|
||||
|
||||
See the information on the Home page `OfflineIMAP`_.
|
||||
|
||||
How fast is it?
|
||||
---------------
|
||||
|
||||
OfflineIMAP has a multithreaded sync, so it should have very nice performance.
|
||||
|
||||
OfflineIMAP versions 2.0 and above contain a multithreaded system. A good way
|
||||
to experiment is by setting maxsyncaccounts to 3 and maxconnections to 3 in
|
||||
each account clause.
|
||||
|
||||
This lets OfflineIMAP open up multiple connections simultaneously. That will
|
||||
let it process multiple folders and messages at once. In most cases, this will
|
||||
increase performance of the sync.
|
||||
|
||||
Don’t set the number too high. If you do that, things might actually slow down
|
||||
as your link gets saturated. Also, too many connections can cause mail servers
|
||||
to have excessive load. Administrators might take unkindly to this, and the
|
||||
server might bog down. There are many variables in the optimal setting; experimentation may help.
|
||||
|
||||
See the Performance section in the MANUAL for some tips.
|
||||
|
||||
What platforms does OfflineIMAP support?
|
||||
----------------------------------------
|
||||
|
||||
It should run on most platforms supported by Python, with one exception: we do not support Windows, but some have made it work there.
|
||||
|
||||
The following has been reported by OfflineIMAP users. We do not test
|
||||
OfflineIMAP on Windows, so we can’t directly address their accuracy.
|
||||
|
||||
The basic answer is that it’s possible and doesn’t require hacking OfflineIMAP
|
||||
source code. However, it’s not necessarily trivial. The information below is
|
||||
based in instructions submitted by Chris Walker::
|
||||
|
||||
First, you must run OfflineIMAP in the Cygwin environment. The Windows
|
||||
filesystem is not powerful enough to accomodate Maildir by itself.
|
||||
|
||||
Next, you’ll need to mount your Maildir directory in a special
|
||||
way. There is information for doing that at
|
||||
http://barnson.org/node/295. That site gives this example::
|
||||
|
||||
mount -f -s -b -o managed "d:/tmp/mail" "/home/of/mail"
|
||||
|
||||
That URL also has more details on making OfflineIMAP work with Windows.
|
||||
|
||||
|
||||
Does OfflineIMAP supports XDG Base Directory specification?
|
||||
-----------------------------------------------------------
|
||||
|
||||
Yes. We are trying to use `$XDG_CONFIG_HOME/offlineimap/config`
|
||||
as the primary configuration file, falling back to `~/.offlineimaprc`
|
||||
if configuration file location was not explicitely specified at the
|
||||
command line.
|
||||
|
||||
|
||||
Does OfflineIMAP support mbox, mh, or anything else other than Maildir?
|
||||
-----------------------------------------------------------------------
|
||||
|
||||
Not directly. Maildir was the easiest to implement. We are not planning
|
||||
to write an mbox-backend, though if someone sent me well-written mbox
|
||||
support and pledged to support it, it would be committed it to the tree.
|
||||
|
||||
However, OfflineIMAP can directly sync accounts on two different IMAP servers
|
||||
together. So you could install an IMAP server on your local machine that
|
||||
supports mbox, sync to it, and then instruct your mail readers to use the
|
||||
mboxes.
|
||||
|
||||
Or you could install whatever IMAP server you like on the local machine, and
|
||||
point your mail readers to that IMAP server on localhost.
|
||||
|
||||
What is the UID validity problem for folder?
|
||||
--------------------------------------------
|
||||
|
||||
IMAP servers use a folders UIDVALIDITY value in combination with a
|
||||
unique ID (UID) to refer to a specific message. This is guaranteed to
|
||||
be unique to a particular message forever. No other message in the same
|
||||
folder will ever get the same UID as long as UIDVALIDITY remains
|
||||
unchanged. UIDs are an integral part of `OfflineIMAP`_'s
|
||||
synchronization scheme; they are used to match up messages on your
|
||||
computer to messages on the server.
|
||||
|
||||
Sometimes, the UIDs on the server might get reset. Usually this will
|
||||
happen if you delete and then recreate a folder. When you create a
|
||||
folder, the server will often start the UID back from 1. But
|
||||
`OfflineIMAP`_ might still have the UIDs from the previous folder by the
|
||||
same name stored. `OfflineIMAP`_ will detect this condition because of
|
||||
the changed UIDVALIDITY value and skip the folder. This is GOOD,
|
||||
because it prevents data loss.
|
||||
|
||||
In the IMAP<->Maildir case, you can fix it by removing your local folder
|
||||
and cache data. For instance, if your folders are under `~/Folders` and
|
||||
the folder with the problem is INBOX, you'd type this::
|
||||
|
||||
rm -r ~/Folders/INBOX
|
||||
rm -r ~/.offlineimap/Account-AccountName/LocalStatus/INBOX
|
||||
rm -r ~/.offlineimap/Repository-RemoteRepositoryName/FolderValidity/INBOX
|
||||
|
||||
(Of course, replace AccountName and RemoteRepositoryName with the names as
|
||||
specified in `~/.offlineimaprc`).
|
||||
|
||||
Next time you run `OfflineIMAP`_, it will re-download the folder with the new
|
||||
UIDs. Note that the procedure specified above will lose any local changes made
|
||||
to the folder.
|
||||
|
||||
Some IMAP servers are broken and do not support UIDs properly. If you continue
|
||||
to get this error for all your folders even after performing the above
|
||||
procedure, it is likely that your IMAP server falls into this category.
|
||||
`OfflineIMAP`_ is incompatible with such servers. Using `OfflineIMAP`_ with
|
||||
them will not destroy any mail, but at the same time, it will not actually
|
||||
synchronize it either. (`OfflineIMAP`_ will detect this condition and abort
|
||||
prior to synchronization.)
|
||||
|
||||
|
||||
This question comes up frequently on the `mailing list`_. You can find a detailed
|
||||
discussion of the problem there
|
||||
http://lists.complete.org/offlineimap@complete.org/2003/04/msg00012.html.gz.
|
||||
|
||||
How do I automatically delete a folder?
|
||||
---------------------------------------
|
||||
|
||||
OfflineIMAP does not currently provide this feature. You will have to delete folders manually. See next entry too.
|
||||
|
||||
May I delete local folders?
|
||||
---------------------------
|
||||
|
||||
`OfflineIMAP`_ does a two-way synchronization. That is, if you make a change
|
||||
to the mail on the server, it will be propagated to your local copy, and
|
||||
vise-versa. Some people might think that it would be wise to just delete all
|
||||
their local mail folders periodically. If you do this with `OfflineIMAP`_,
|
||||
remember to also remove your local status cache (`~/.offlineimap` by default).
|
||||
Otherwise, `OfflineIMAP`_ will take this as an intentional deletion of many
|
||||
messages and will interpret your action as requesting them to be deleted from
|
||||
the server as well. (If you don't understand this, don't worry; you probably
|
||||
won't encounter this situation.)
|
||||
|
||||
Can I run multiple instances?
|
||||
-----------------------------
|
||||
|
||||
`OfflineIMAP`_ is not designed to have several instances (for instance, a cron
|
||||
job and an interactive invocation) run over the same mailbox simultaneously.
|
||||
It will perform a check on startup and abort if another `OfflineIMAP`_ is
|
||||
already running. If you need to schedule synchronizations, you'll probably
|
||||
find autorefresh settings more convenient than cron. Alternatively, you can
|
||||
set a separate metadata directory for each instance.
|
||||
In the future, we will lock each account individually rather than having one global lock.
|
||||
|
||||
Can I copy messages between folders?
|
||||
---------------------------------------
|
||||
|
||||
Normally, when you copy a message between folders or add a new message to a
|
||||
folder locally, `OfflineIMAP`_ will just do the right thing. However,
|
||||
sometimes this can be tricky ― if your IMAP server does not provide the SEARCH
|
||||
command, or does not return something useful, `OfflineIMAP`_ cannot determine
|
||||
the new UID of the message. So, in these rare instances, OfflineIMAP will
|
||||
upload the message to the IMAP server and delete it from your local folder.
|
||||
Then, on your next sync, the message will be re-downloaded with the proper UID.
|
||||
`OfflineIMAP`_ makes sure that the message was properly uploaded before
|
||||
deleting it, so there should be no risk of data loss.
|
||||
|
||||
But if you try to sync between two IMAP servers, where both are unable to
|
||||
provide you with UID of the new message, then this will lead to infinite loop.
|
||||
`OfflineIMAP`_ will upload the message to one server and delete on second. On
|
||||
next run it will upload the message to second server and delete on first, etc.
|
||||
|
||||
Does OfflineIMAP support POP?
|
||||
-----------------------------
|
||||
|
||||
No.
|
||||
|
||||
How is OfflineIMAP conformance?
|
||||
-------------------------------
|
||||
|
||||
* Internet Message Access Protocol version 4rev1 (IMAP 4rev1) as specified in
|
||||
`2060`:RFC: and `3501`:RFC:
|
||||
* CRAM-MD5 as specified in `2195`:RFC:
|
||||
* Maildir as specified in the Maildir manpage and the qmail website.
|
||||
* Standard Python 2.7 as implemented on POSIX-compliant systems.
|
||||
|
||||
Can I force OfflineIMAP to sync a folder right now?
|
||||
---------------------------------------------------
|
||||
|
||||
Yes:
|
||||
|
||||
1) if you use the `Blinkenlights` UI. That UI shows the active
|
||||
accounts as follows::
|
||||
|
||||
4: [active] *Control: .
|
||||
3: [ 4:36] personal:
|
||||
2: [ 3:37] work: .
|
||||
1: [ 6:28] uni:
|
||||
|
||||
Simply press the appropriate digit (`3` for `personal`, etc.) to
|
||||
resync that account immediately. This will be ignored if a resync is
|
||||
already in progress for that account.
|
||||
|
||||
2) While in sleep mode, you can also send a SIGUSR1. See the :ref:`UNIX
|
||||
signals` section in the MANUAL for details.
|
||||
|
||||
|
||||
I get a "Mailbox already exists" error
|
||||
--------------------------------------
|
||||
|
||||
**Q:** When synchronizing, I receive errors such as::
|
||||
|
||||
Folder 'sent'[main-remote] could not be created. Server responded:
|
||||
('NO', ['Mailbox already exists.'])
|
||||
|
||||
**A:** IMAP folders are usually case sensitive. But some IMAP servers seem
|
||||
to treat "special" folders as case insensitive (e.g. the initial
|
||||
INBOX. part, or folders such as "Sent" or "Trash"). If you happen to
|
||||
have a folder "sent" on one side of things and a folder called "Sent"
|
||||
on the other side, OfflineIMAP will try to create those folders on
|
||||
both sides. If you server happens to treat those folders as
|
||||
case-insensitive you can then see this warning.
|
||||
|
||||
You can solve this by excluding the "sent" folder by filtering it from
|
||||
the repository settings::
|
||||
|
||||
folderfilter= lambda f: f not in ['sent']
|
||||
|
||||
|
||||
Configuration Questions
|
||||
=======================
|
||||
|
||||
Can I synchronize multiple accounts with OfflineIMAP?
|
||||
-----------------------------------------------------
|
||||
|
||||
Of course!
|
||||
|
||||
Just name them all in the accounts line in the general section of the
|
||||
configuration file, and add a per-account section for each one.
|
||||
|
||||
You can also optionally use the -a option when you run OfflineIMAP to request
|
||||
that it only operate upon a subset of the accounts for a particular run.
|
||||
|
||||
How do I specify the names of folders?
|
||||
--------------------------------------
|
||||
|
||||
You do not need to. OfflineIMAP is smart enough to automatically figure out
|
||||
what folders are present on the IMAP server and synchronize them. You can use
|
||||
the folderfilter and nametrans configuration file options to request only
|
||||
certain folders and rename them as they come in if you like.
|
||||
|
||||
Also you can configure OfflineImap to only synchronize "subscribed" folders.
|
||||
|
||||
How do I prevent certain folders from being synced?
|
||||
---------------------------------------------------
|
||||
|
||||
Use the folderfilter option. See the MANUAL for details and examples.
|
||||
|
||||
What is the mailbox name recorder (mbnames) for?
|
||||
------------------------------------------------
|
||||
|
||||
Some mail readers, such as mutt, are not capable of automatically determining the names of your mailboxes. OfflineIMAP can help these programs by writing the names of the folders in a format you specify. See the example offlineimap.conf for details.
|
||||
|
||||
Does OfflineIMAP verify SSL certificates?
|
||||
-----------------------------------------
|
||||
|
||||
You can verify an imapserver's certificate by specifying the CA
|
||||
certificate on a per-repository basis by setting the `sslcacertfile`
|
||||
option in the config file. (See the example offlineimap.conf for
|
||||
details.) If you do not specify any CA certificate, you will be presented with the server's certificate fingerprint and add that to the configuration file, to make sure it remains unchanged.
|
||||
No verification happens if connecting via STARTTLS.
|
||||
|
||||
How do I generate an `sslcacertfile` file?
|
||||
------------------------------------------
|
||||
|
||||
The `sslcacertfile` file must contain an SSL certificate (or a concatenated
|
||||
certificates chain) in PEM format. (See the documentation of
|
||||
`ssl.wrap_socket`_'s `certfile` parameter for the gory details.) You can use either openssl or gnutls to create a certificate file in the required format.
|
||||
|
||||
#. via openssl::
|
||||
|
||||
openssl s_client -CApath /etc/ssl/certs -connect ${hostname}:imaps -showcerts \
|
||||
| perl -ne 'print if /BEGIN/../END/; print STDERR if /return/' > $sslcacertfile
|
||||
^D
|
||||
|
||||
|
||||
#. via gnutls::
|
||||
gnutls-cli --print-cert -p imaps ${host} </dev/null | sed -n \
|
||||
| '/^-----BEGIN CERT/,/^-----END CERT/p' > $sslcacertfile
|
||||
|
||||
|
||||
The path `/etc/ssl/certs` is not standardized; your system may store
|
||||
SSL certificates elsewhere. (On some systems it may be in
|
||||
`/usr/local/share/certs/`.)
|
||||
|
||||
Before using the resulting file, ensure that openssl verified the certificate
|
||||
successfully. In case of problems, you can test the certificate using a command such as (credits to Daniel Shahaf for this) to verify the certificate::
|
||||
|
||||
% openssl s_client -CAfile $sslcacertfile -connect ${hostname}:imaps 2>&1 </dev/null
|
||||
|
||||
If the server uses STARTTLS, pass the -starttls option and the 'imap' port.
|
||||
|
||||
Also, you can test using gnutls::
|
||||
gnutls-cli --x509cafile certs/mail.mydomain.eu.cert -p 993 mail.mydomain.eu
|
||||
|
||||
IMAP Server Notes
|
||||
=================
|
||||
|
||||
In general, OfflineIMAP works with any IMAP server that provides compatibility
|
||||
with the IMAP RFCs. Some servers provide imperfect compatibility that may be
|
||||
good enough for general clients. OfflineIMAP needs more features, specifically
|
||||
support for UIDs, in order to do its job accurately and completely.
|
||||
|
||||
|
||||
Client Notes
|
||||
============
|
||||
|
||||
What clients does OfflineIMAP work with?
|
||||
----------------------------------------
|
||||
|
||||
Any client that supports Maildir. Popular ones include mutt, Evolution and
|
||||
KMail. Thunderbird does not have maildir suppport.
|
||||
|
||||
With OfflineIMAP’s IMAP-to-IMAP syncing, this can be even wider; see the next
|
||||
question.
|
||||
|
||||
Evolution
|
||||
---------
|
||||
|
||||
OfflineIMAP can work with Evolution. To do so, first configure your OfflineIMAP
|
||||
account to have sep = / in its configuration. Then, configure Evolution with
|
||||
the “Maildir-format mail directories” server type. For the path, you will need
|
||||
to specify the name of the top-level folder inside your OfflineIMAP storage
|
||||
location. You’re now set!
|
||||
|
||||
KMail
|
||||
-----
|
||||
|
||||
At this time, I believe that OfflineIMAP with Maildirs is not compatible with
|
||||
KMail. KMail cannot work in any mode other than to move all messages out of all
|
||||
folders immediately, which (besides being annoying and fundamentally broken) is
|
||||
incompatible with OfflineIMAP.
|
||||
|
||||
However, I have made KMail version 3 work well with OfflineIMAP by installing
|
||||
an IMAP server on my local machine, having OfflineIMAP sync to that, and
|
||||
pointing KMail at the same server.
|
||||
|
||||
Another way to see mails downloaded with offlineimap in KMail (KDE4) is to
|
||||
create a local folder (e.g. Backup) and then use ``ln -s
|
||||
localfolders_in_offlineimaprc ~/.kde/share/apps/kmail/mail/.Backup.directory``.
|
||||
Maybe you have to rebuild the index of the new folder. Works well with KMail
|
||||
1.11.4 (KDE4.x), offlineimap 6.1.2 and ArchLinux and sep = / in .offlineimaprc.
|
||||
|
||||
Mutt
|
||||
----
|
||||
|
||||
* Do I need to use set maildir_trash?
|
||||
|
||||
Other IMAP sync programs require you to do this. OfflineIMAP does not. You’ll
|
||||
get the best results without it, in fact, though turning it on won’t hurt
|
||||
anything.
|
||||
|
||||
* How do I set up mbnames with mutt?
|
||||
|
||||
The example offlineimap.conf file has this example. In your offlineimap.conf,
|
||||
you’ll list this::
|
||||
|
||||
[mbnames]
|
||||
enabled = yes
|
||||
filename = ~/Mutt/muttrc.mailboxes
|
||||
header = "mailboxes "
|
||||
peritem = "+%(accountname)s/%(foldername)s"
|
||||
sep = " "
|
||||
footer = "\n"
|
||||
|
||||
Then in your ``.muttrc``::
|
||||
|
||||
source ~/Mutt/muttrc.mailboxes
|
||||
|
||||
|
||||
You might also want to set::
|
||||
|
||||
set mbox_type=Maildir
|
||||
set folder=$HOME/Maildirpath
|
||||
|
||||
The OfflineIMAP manual has a more detailed example for doing this for multiple
|
||||
accounts.
|
||||
|
||||
Miscellaneous Questions
|
||||
=======================
|
||||
|
||||
I'm using git to install OfflineIMAP and found these branches called "master", "maint", "next", "pu" and "gh-pages". What are they?
|
||||
-----------------------------------------------------------------------------------------------------------------------------------
|
||||
|
||||
To be brief:
|
||||
|
||||
* **gh-pages**: branch used to maintain the home page at github.
|
||||
* **master**: classical mainline branch.
|
||||
* **next**: this is the branch for recent merged patches. Used for testing OfflineIMAP.
|
||||
* **pu** ("proposed updates"): patches not ready for inclusion. This should **never** be checkouted!
|
||||
* **maint**: our long-living maintenance branch. We maintain this branch
|
||||
(security and bugfixes) for users who don't want or can't upgrade to the
|
||||
latest release.
|
||||
|
||||
For more information about the branching model and workflow, see `Advanced
|
||||
Git`_.
|
||||
|
||||
|
||||
Why are your Maildir message filenames so long?
|
||||
-----------------------------------------------
|
||||
|
||||
OfflineIMAP has two relevant principles:
|
||||
|
||||
1. Never modifying your messages in any way.
|
||||
2. Ensure 100% reliable synchronizations.
|
||||
|
||||
In order to do a reliable sync, OfflineIMAP must have a way to uniquely identify
|
||||
each e-mail. Three pieces of information are required to do this: your account
|
||||
name, the folder name, and the message UID. The account name can be calculated
|
||||
from the path in which your messages are. The folder name can usually be as
|
||||
well, BUT some mail clients move messages between folders by simply moving the
|
||||
file, leaving the name intact.
|
||||
|
||||
So, OfflineIMAP must store both a message UID and a folder ID. The
|
||||
folder ID is necessary so OfflineIMAP can detect a message being moved
|
||||
to a different folder. OfflineIMAP stores the UID (U= number) and an
|
||||
md5sum of the foldername (FMD5= number) to facilitate this.
|
||||
|
||||
|
||||
What can I do to ensure OfflineIMAP is still running and hasn’t crashed?
|
||||
------------------------------------------------------------------------
|
||||
|
||||
This shell script will restart OfflineIMAP if it has crashed. Sorry, its
|
||||
written in Korn, so you’ll need ksh, pdksh, or mksh to run it::
|
||||
|
||||
#!/bin/ksh
|
||||
# remove any old instances of this shell script or offlineimap
|
||||
for pid in $(pgrep offlineimap)
|
||||
do
|
||||
if $pid -ne $$
|
||||
then
|
||||
kill $pid
|
||||
fi
|
||||
done
|
||||
|
||||
# wait for compiz (or whatever) to start and setup wifi
|
||||
sleep 20
|
||||
# If offlineimap exits, restart it
|
||||
while true
|
||||
do
|
||||
( exec /usr/bin/offlineimap -u Noninteractive.Quiet )
|
||||
sleep 60 # prevents extended failure condition
|
||||
|
||||
|
||||
Contributing
|
||||
============
|
||||
|
||||
How to test OfflineIMAP?
|
||||
------------------------
|
||||
|
||||
We don't have a testing tool, for now. As a IMAP client, we need an available
|
||||
IMAP server for that purpose. But it doesn't mean you can do anything.
|
||||
|
||||
Recent patches are merged in the next branch before being in the mainline. Once
|
||||
you have your own copy of the official repository, track this next branch::
|
||||
|
||||
$ git checkout -t origin/next
|
||||
|
||||
Update this branch in a regular basis with::
|
||||
|
||||
$ git checkout next
|
||||
$ git pull
|
||||
|
||||
Notice you're not supposed to install OfflineIMAP each time. You may simply
|
||||
run it like this::
|
||||
|
||||
$ ./offlineimap.py
|
||||
|
||||
The choice is up to you. :-)
|
||||
|
||||
|
||||
How to submit a patch?
|
||||
----------------------
|
||||
|
||||
Read `Contributing`_.
|
||||
|
||||
|
|
@ -1 +0,0 @@
|
|||
../INSTALL.rst
|
||||
|
|
@ -1,59 +1,23 @@
|
|||
.. OfflineImap documentation master file
|
||||
.. _OfflineImap: http://offlineimap.org
|
||||
.. _OfflineIMAP: http://offlineimap.github.io
|
||||
|
||||
|
||||
Welcome to :mod:`offlineimaps`'s documentation
|
||||
==============================================
|
||||
|
||||
`OfflineImap`_ synchronizes email between an IMAP server and a MailDir or
|
||||
between two IMAP servers. It offers very powerful and flexible configuration
|
||||
options, that allow things such as the filtering of folders, transposing of
|
||||
names via static configuration or python scripting. It plays well with mutt and
|
||||
other MailDir consuming email clients.
|
||||
|
||||
The documentation contains the end user documentation in a first part. It also
|
||||
contains use cases and example configurations. It is followed by the internal
|
||||
:doc:`API documentation <API>` for those interested in modifying the source code
|
||||
or otherwise peek into the OfflineImap internals in a second part.
|
||||
|
||||
|
||||
If you just want to get started with minimal fuzz, have a look at our `online
|
||||
quick start guide <http://offlineimap.org/#ref-quick-start>`_. Do note though,
|
||||
that our configuration options are many and powerful. Perusing our precious
|
||||
documentation does often pay off!
|
||||
|
||||
More information on specific topics can be found on the following pages:
|
||||
|
||||
**User documentation**
|
||||
* :doc:`Overview and features <features>`
|
||||
* :doc:`installation/uninstall <INSTALL>`
|
||||
Welcome to OfflineIMAP's documentation
|
||||
======================================
|
||||
|
||||
**Configuration**
|
||||
* :doc:`user manual/Configuration <MANUAL>`
|
||||
* :doc:`Folder filtering & name transformation guide <nametrans>`
|
||||
* :doc:`maxage <advanced_config>`
|
||||
* :doc:`command line options <offlineimap>`
|
||||
* :doc:`Frequently Asked Questions <FAQ>`
|
||||
|
||||
**Developer documentation**
|
||||
* :doc:`Contributing <CONTRIBUTING>`
|
||||
* :doc:`Advanced Git <GitAdvanced>`
|
||||
* :doc:`API documentation <API>` for internal details on the
|
||||
:mod:`offlineimap` module
|
||||
|
||||
**OfflineIMAP APIs**
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
|
||||
features
|
||||
INSTALL
|
||||
MANUAL
|
||||
nametrans
|
||||
advanced_config
|
||||
offlineimap
|
||||
FAQ
|
||||
|
||||
CONTRIBUTING
|
||||
GitAdvanced
|
||||
API
|
||||
repository
|
||||
ui
|
||||
|
|
|
|||
|
|
@ -1,233 +0,0 @@
|
|||
.. _folder_filtering_and_name_translation:
|
||||
|
||||
Folder filtering and Name translation
|
||||
=====================================
|
||||
|
||||
OfflineImap provides advanced and potentially complex possibilities for
|
||||
filtering and translating folder names. If you don't need any of this, you can
|
||||
safely skip this section.
|
||||
|
||||
.. warning::
|
||||
Starting with v6.4.0, OfflineImap supports the creation of folders on the remote repostory. This change means that people that only had a nametrans option on the remote repository (everyone) will need to have a nametrans setting on the local repository too that will reverse the name transformation. See section `Reverse nametrans`_ for details.
|
||||
|
||||
folderfilter
|
||||
------------
|
||||
|
||||
If you do not want to synchronize all your folders, you can specify a
|
||||
`folderfilter`_ function that determines which folders to include in a sync and
|
||||
which to exclude. Typically, you would set a folderfilter option on the remote
|
||||
repository only, and it would be a lambda or any other python function.
|
||||
|
||||
The only parameter to that function is the folder name. If the filter
|
||||
function returns True, the folder will be synced, if it returns False,
|
||||
it. will be skipped. The folderfilter operates on the *UNTRANSLATED*
|
||||
name (before any `nametrans`_ fudging takes place). Consider the
|
||||
examples below to get an idea of what they do.
|
||||
|
||||
Example 1: synchronizing only INBOX and Sent::
|
||||
|
||||
folderfilter = lambda folder: folder in ['INBOX', 'Sent']
|
||||
|
||||
Example 2: synchronizing everything except Trash::
|
||||
|
||||
folderfilter = lambda folder: folder not in ['Trash']
|
||||
|
||||
Example 3: Using a regular expression to exclude Trash and all folders
|
||||
containing the characters "Del"::
|
||||
|
||||
folderfilter = lambda folder: not re.search('(^Trash$|Del)', folder)
|
||||
|
||||
.. note::
|
||||
If folderfilter is not specified, ALL remote folders will be
|
||||
synchronized.
|
||||
|
||||
You can span multiple lines by indenting the others. (Use backslashes
|
||||
at the end when required by Python syntax) For instance::
|
||||
|
||||
folderfilter = lambda foldername: foldername in
|
||||
['INBOX', 'Sent Mail', 'Deleted Items',
|
||||
'Received']
|
||||
|
||||
Usually it suffices to put a `folderfilter`_ setting in the remote repository
|
||||
section. You might want to put a folderfilter option on the local repository if
|
||||
you want to prevent some folders on the local repository to be created on the
|
||||
remote one. (Even in this case, folder filters on the remote repository will
|
||||
prevent that)
|
||||
|
||||
folderincludes
|
||||
--------------
|
||||
|
||||
You can specify `folderincludes`_ to manually include additional folders to be
|
||||
synced, even if they had been filtered out by a folderfilter setting.
|
||||
`folderincludes`_ should return a Python list.
|
||||
|
||||
This can be used to 1) add a folder that was excluded by your
|
||||
folderfilter rule, 2) to include a folder that your server does not specify
|
||||
with its LIST option, or 3) to include a folder that is outside your basic
|
||||
`reference`. The `reference` value will not be prefixed to this folder
|
||||
name, even if you have specified one. For example::
|
||||
|
||||
folderincludes = ['debian.user', 'debian.personal']
|
||||
|
||||
This will add the "debian.user" and "debian.personal" folders even if you
|
||||
have filtered out everything starting with "debian" in your folderfilter
|
||||
settings.
|
||||
|
||||
|
||||
createfolders
|
||||
-------------
|
||||
|
||||
By default OfflineImap propagates new folders in both
|
||||
directions. Sometimes this is not what you want. E.g. you might want
|
||||
new folders on your IMAP server to propagate to your local MailDir,
|
||||
but not the other way around. The 'readonly' setting on a repository
|
||||
will not help here, as it prevents any change from occuring on that
|
||||
repository. This is what the `createfolders` setting is for. By
|
||||
default it is `True`, meaning that new folders can be created on this
|
||||
repository. To prevent folders from ever being created on a
|
||||
repository, set this to `False`. If you set this to False on the
|
||||
REMOTE repository, you will not have to create the `Reverse
|
||||
nametrans`_ rules on the LOCAL repository.
|
||||
|
||||
|
||||
nametrans
|
||||
----------
|
||||
|
||||
Sometimes, folders need to have different names on the remote and the local
|
||||
repositories. To achieve this you can specify a folder name translator. This
|
||||
must be a eval-able Python expression that takes a foldername arg and returns
|
||||
the new value. We suggest a lambda function, but it could be any python
|
||||
function really. If you use nametrans rules, you will need to set them both on
|
||||
the remote and the local repository, see `Reverse nametrans`_ just below for
|
||||
details. The following examples are thought to be put in the remote repository
|
||||
section.
|
||||
|
||||
The below will remove "INBOX." from the leading edge of folders (great
|
||||
for Courier IMAP users)::
|
||||
|
||||
nametrans = lambda folder: re.sub('^INBOX\.', '', folder)
|
||||
|
||||
Using Courier remotely and want to duplicate its mailbox naming
|
||||
locally? Try this::
|
||||
|
||||
nametrans = lambda folder: re.sub('^INBOX\.*', '.', folder)
|
||||
|
||||
.. warning::
|
||||
You MUST construct nametrans rules such that it NEVER returns the
|
||||
same value for two folders, UNLESS the second values are filtered
|
||||
out by folderfilter below. That is, two filters on one side may
|
||||
never point to the same folder on the other side. Failure to follow
|
||||
this rule will result in undefined behavior. See also *Sharing a
|
||||
maildir with multiple IMAP servers* in the :ref:`pitfalls` section.
|
||||
|
||||
|
||||
Reverse nametrans
|
||||
+++++++++++++++++
|
||||
|
||||
Since 6.4.0, OfflineImap supports the creation of folders on the remote
|
||||
repository and that complicates things. Previously, only one nametrans setting
|
||||
on the remote repository was needed and that transformed a remote to a local
|
||||
name. However, nametrans transformations are one-way, and OfflineImap has no way
|
||||
using those rules on the remote repository to back local names to remote names.
|
||||
|
||||
Take a remote nametrans rule `lambda f: re.sub('^INBOX/','',f)` which cuts off
|
||||
any existing INBOX prefix. Now, if we parse a list of local folders, finding
|
||||
e.g. a folder "Sent", is it supposed to map to "INBOX/Sent" or to "Sent"? We
|
||||
have no way of knowing. This is why **every nametrans setting on a remote
|
||||
repository requires an equivalent nametrans rule on the local repository that
|
||||
reverses the transformation**.
|
||||
|
||||
Take the above examples. If your remote nametrans setting was::
|
||||
|
||||
nametrans = lambda folder: re.sub('^INBOX\.', '', folder)
|
||||
|
||||
then you will want to have this in your local repository, prepending "INBOX." to
|
||||
any local folder name::
|
||||
|
||||
nametrans = lambda folder: 'INBOX.' + folder
|
||||
|
||||
Failure to set the local nametrans rule will lead to weird-looking error
|
||||
messages of -for instance- this type::
|
||||
|
||||
ERROR: Creating folder moo.foo on repository remote
|
||||
Folder 'moo.foo'[remote] could not be created. Server responded: ('NO', ['Unknown namespace.'])
|
||||
|
||||
(This indicates that you attempted to create a folder "Sent" when all remote
|
||||
folders needed to be under the prefix of "INBOX.").
|
||||
|
||||
OfflineImap will make some sanity checks if it needs to create a new
|
||||
folder on the remote side and a back-and-forth nametrans-lation does not
|
||||
yield the original foldername (as that could potentially lead to
|
||||
infinite folder creation cycles).
|
||||
|
||||
You can probably already see now that creating nametrans rules can be a pretty
|
||||
daunting and complex endeavour. Check out the Use cases in the manual. If you
|
||||
have some interesting use cases that we can present as examples here, please let
|
||||
us know.
|
||||
|
||||
Debugging folderfilter and nametrans
|
||||
------------------------------------
|
||||
|
||||
Given the complexity of the functions and regexes involved, it is easy to
|
||||
misconfigure things. One way to test your configuration without danger to
|
||||
corrupt anything or to create unwanted folders is to invoke offlineimap with the
|
||||
`--info` option.
|
||||
|
||||
It will output a list of folders and their transformations on the screen (save
|
||||
them to a file with -l info.log), and will help you to tweak your rules as well
|
||||
as to understand your configuration. It also provides good output for bug
|
||||
reporting.
|
||||
|
||||
FAQ on nametrans
|
||||
----------------
|
||||
|
||||
Where to put nametrans rules, on the remote and/or local repository?
|
||||
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||||
|
||||
If you never intend to create new folders on the LOCAL repository that
|
||||
need to be synced to the REMOTE repository, it is sufficient to create a
|
||||
nametrans rule on the remote Repository section. This will be used to
|
||||
determine the names of new folder names on the LOCAL repository, and to
|
||||
match existing folders that correspond.
|
||||
|
||||
*IF* you create folders on the local repository, that are supposed to be
|
||||
automatically created on the remote repository, you will need to create
|
||||
a nametrans rule that provides the reverse name translation.
|
||||
|
||||
(A nametrans rule provides only a one-way translation of names and in
|
||||
order to know which names folders on the LOCAL side would have on the
|
||||
REMOTE side, you need to specify the reverse nametrans rule on the local
|
||||
repository)
|
||||
|
||||
OfflineImap will complain if it needs to create a new folder on the
|
||||
remote side and a back-and-forth nametrans-lation does not yield the
|
||||
original foldername (as that could potentially lead to infinite folder
|
||||
creation cycles).
|
||||
|
||||
What folder separators do I need to use in nametrans rules?
|
||||
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||||
|
||||
**Q:** If I sync from an IMAP server with folder separator '/' to a
|
||||
Maildir using the default folder separator '.' which do I need to use
|
||||
in nametrans rules?::
|
||||
|
||||
nametrans = lambda f: "INBOX/" + f
|
||||
|
||||
or::
|
||||
nametrans = lambda f: "INBOX." + f
|
||||
|
||||
**A:** Generally use the folder separator as defined in the repository
|
||||
you write the nametrans rule for. That is, use '/' in the above
|
||||
case. We will pass in the untranslated name of the IMAP folder as
|
||||
parameter (here `f`). The translated name will ultimately have all
|
||||
folder separators be replaced with the destination repositories'
|
||||
folder separator.
|
||||
|
||||
So if 'f' was "Sent", the first nametrans yields the translated name
|
||||
"INBOX/Sent" to be used on the other side. As that repository uses the
|
||||
folder separator '.' rather than '/', the ultimate name to be used will
|
||||
be "INBOX.Sent".
|
||||
|
||||
(As a final note, the smart will see that both variants of the above
|
||||
nametrans rule would have worked identically in this case)
|
||||
|
||||
|
|
@ -1,92 +0,0 @@
|
|||
The offlineimap 'binary' command line options
|
||||
=============================================
|
||||
|
||||
Offlineimap is invoked with the following pattern: `offlineimap [args...]`.
|
||||
|
||||
Where [args...] are as follows:
|
||||
|
||||
Options:
|
||||
--dry-run This mode protects us from performing any actual action.
|
||||
It will not precisely give the exact information what
|
||||
will happen. If e.g. it would 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.
|
||||
--version show program's version number and exit
|
||||
-h, --help show this help message and exit
|
||||
-1 Disable all multithreading operations and use solely a
|
||||
single-thread sync. This effectively sets the
|
||||
maxsyncaccounts and all maxconnections configuration
|
||||
file variables to 1.
|
||||
-P DIR Sets 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 slow program
|
||||
performance, may reduce reliability, and can generate
|
||||
huge amounts of data. This option implies the
|
||||
singlethreading option (-1).
|
||||
-a ACCOUNTS Overrides the accounts section in the config file.
|
||||
Lets you specify a particular account or set of
|
||||
accounts to sync without having to edit the config
|
||||
file. You might use this to exclude certain accounts,
|
||||
or to sync some accounts that you normally prefer not
|
||||
to.
|
||||
-c FILE Specifies a configuration file to use in lieu of
|
||||
~/.offlineimaprc.
|
||||
|
||||
-d type1,[type2...] Enables debugging for OfflineIMAP. This is useful if
|
||||
you are trying to track down a malfunction or figure
|
||||
out what is going on under the hood. I suggest that
|
||||
you use this with -1 in order to make the results more
|
||||
sensible. This option requires one or more debugtypes,
|
||||
separated by commas. These define what exactly will
|
||||
be debugged, and so far include the 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.
|
||||
|
||||
-l FILE Log to FILE
|
||||
|
||||
-f folder1,[folder2...]
|
||||
Only sync the specified folders. The 'folder's are the
|
||||
*untranslated* foldernames. This command-line option
|
||||
overrides any 'folderfilter' and 'folderincludes'
|
||||
options in the configuration file.
|
||||
|
||||
-k `[section:]option=value`
|
||||
Override 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".
|
||||
|
||||
-o Run only once, ignoring any autorefresh setting in the
|
||||
configuration file.
|
||||
-q Run only quick synchronizations. Ignore any flag
|
||||
updates on IMAP servers.
|
||||
-u INTERFACE 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: Curses.Blinkenlights,
|
||||
TTY.TTYUI, Noninteractive.Basic, Noninteractive.Quiet,
|
||||
Machine.MachineUI
|
||||
|
||||
|
||||
|
||||
Indices and tables
|
||||
==================
|
||||
|
||||
* :ref:`genindex`
|
||||
* :ref:`search`
|
||||
|
||||
Loading…
Reference in New Issue