0db32b6393
- Slight renaming in offlineimap.conf.minimal to clarify things. - Documentation updated with information about new features. Closes: #189771. + Described IMAP-IMAP syncing + Updated minimal example with new offlineimap.conf.minimal + Updated UID information. Added link to recent mailing list discussion. + Described KMail syncing, which now works. + Added link to mailing list archives.
2084 lines
44 KiB
HTML
2084 lines
44 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||
<HTML
|
||
><HEAD
|
||
><TITLE
|
||
>OfflineIMAP Manual</TITLE
|
||
><META
|
||
NAME="GENERATOR"
|
||
CONTENT="Modular DocBook HTML Stylesheet Version 1.77+"></HEAD
|
||
><BODY
|
||
CLASS="REFERENCE"
|
||
BGCOLOR="#FFFFFF"
|
||
TEXT="#000000"
|
||
LINK="#0000FF"
|
||
VLINK="#840084"
|
||
ALINK="#0000FF"
|
||
><DIV
|
||
CLASS="REFERENCE"
|
||
><A
|
||
NAME="AEN1"
|
||
></A
|
||
><DIV
|
||
CLASS="TITLEPAGE"
|
||
><H1
|
||
CLASS="TITLE"
|
||
>I. OfflineIMAP Manual</H1
|
||
><DIV
|
||
CLASS="TOC"
|
||
><DL
|
||
><DT
|
||
><B
|
||
>Table of Contents</B
|
||
></DT
|
||
><DT
|
||
><A
|
||
HREF="#AEN3"
|
||
>offlineimap</A
|
||
> -- Powerful IMAP/Maildir synchronization
|
||
and reader support</DT
|
||
></DL
|
||
></DIV
|
||
></DIV
|
||
><H1
|
||
><A
|
||
NAME="AEN3"
|
||
></A
|
||
>offlineimap</H1
|
||
><DIV
|
||
CLASS="REFNAMEDIV"
|
||
><A
|
||
NAME="AEN15"
|
||
></A
|
||
><H2
|
||
>Name</H2
|
||
>OfflineIMAP -- Powerful IMAP/Maildir synchronization
|
||
and reader support</DIV
|
||
><DIV
|
||
CLASS="REFSYNOPSISDIV"
|
||
><A
|
||
NAME="AEN18"
|
||
></A
|
||
><H2
|
||
>Synopsis</H2
|
||
><P
|
||
><B
|
||
CLASS="COMMAND"
|
||
>offlineimap</B
|
||
> [-1] [-P <TT
|
||
CLASS="REPLACEABLE"
|
||
><I
|
||
>profiledir</I
|
||
></TT
|
||
>] [-a <TT
|
||
CLASS="REPLACEABLE"
|
||
><I
|
||
>accountlist</I
|
||
></TT
|
||
>] [-c <TT
|
||
CLASS="REPLACEABLE"
|
||
><I
|
||
>configfile</I
|
||
></TT
|
||
>] [-d <TT
|
||
CLASS="REPLACEABLE"
|
||
><I
|
||
>debugtype[,...]</I
|
||
></TT
|
||
>] [-o] [-u <TT
|
||
CLASS="REPLACEABLE"
|
||
><I
|
||
>interface</I
|
||
></TT
|
||
>]</P
|
||
><P
|
||
><B
|
||
CLASS="COMMAND"
|
||
>offlineimap</B
|
||
> -h | --help </P
|
||
></DIV
|
||
><DIV
|
||
CLASS="REFSECT1"
|
||
><A
|
||
NAME="AEN38"
|
||
></A
|
||
><H2
|
||
>Description</H2
|
||
><P
|
||
><SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
> is a tool to simplify your e-mail
|
||
reading. With <SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
>, you can read the same mailbox
|
||
from multiple computers. You get a current copy of your
|
||
messages on each computer, and changes you make one place will be
|
||
visible on all other systems. For instance, you can delete a message
|
||
on your home computer, and it will appear deleted on your work
|
||
computer as well. <SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
> is also useful if you want to
|
||
use a mail reader that does not have IMAP support, has poor IMAP
|
||
support, or does not provide disconnected operation.
|
||
</P
|
||
><P
|
||
><SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
> is <SPAN
|
||
CLASS="emphasis"
|
||
><I
|
||
CLASS="EMPHASIS"
|
||
>FAST</I
|
||
></SPAN
|
||
>; it synchronizes
|
||
my two accounts with over 50 folders in 3 seconds. Other
|
||
similar tools might take over a minute, and achieve a
|
||
less-reliable result. Some mail readers can take over 10
|
||
minutes to do the same thing, and some don't even support it
|
||
at all. Unlike other mail tools, <SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
> features a
|
||
multi-threaded synchronization algorithm that can dramatically
|
||
speed up performance in many situations by synchronizing
|
||
several different things simultaneously.
|
||
</P
|
||
><P
|
||
><SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
> is <SPAN
|
||
CLASS="emphasis"
|
||
><I
|
||
CLASS="EMPHASIS"
|
||
>FLEXIBLE</I
|
||
></SPAN
|
||
>; you can
|
||
customize which folders are synced via regular expressions,
|
||
lists, or Python expressions; a versatile and comprehensive
|
||
configuration file is used to control behavior; two user
|
||
interfaces are built-in; fine-tuning of synchronization
|
||
performance is possible; internal or external automation is
|
||
supported; SSL and PREAUTH tunnels are both supported; offline
|
||
(or "unplugged") reading is supported; and esoteric IMAP
|
||
features are supported to ensure compatibility with the widest
|
||
variety of IMAP servers.
|
||
</P
|
||
><P
|
||
><SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
> is <SPAN
|
||
CLASS="emphasis"
|
||
><I
|
||
CLASS="EMPHASIS"
|
||
>SAFE</I
|
||
></SPAN
|
||
>; it uses an
|
||
algorithm designed to prevent mail loss at all costs. Because
|
||
of the design of this algorithm, even programming errors
|
||
should not result in loss of mail. I am so confident in the
|
||
algorithm that I use my own personal and work accounts for
|
||
testing of <SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
> pre-release, development, and beta
|
||
releases. Of course, legally speaking, <SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
> comes
|
||
with no warranty, so I am not responsible if this turns out
|
||
to be wrong.
|
||
</P
|
||
><DIV
|
||
CLASS="REFSECT2"
|
||
><A
|
||
NAME="AEN56"
|
||
></A
|
||
><H3
|
||
>Method of Operation</H3
|
||
><P
|
||
><SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
> traditionally
|
||
operates by maintaining a hierarchy of
|
||
mail folders in Maildir format locally. Your own mail
|
||
reader will read mail from this tree, and need never know
|
||
that the mail comes from IMAP. <SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
> will detect
|
||
changes to the mail folders on your IMAP server and your own
|
||
computer and bi-directionally synchronize them, copying,
|
||
marking, and deleting messages as necessary.
|
||
</P
|
||
><P
|
||
> With <SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
> 4.0, a powerful new ability has been
|
||
introduced -- the program can now synchronize two IMAP
|
||
servers with each other, with no need to have a Maildir
|
||
layer in-between. Many people use this if they use a mail
|
||
reader on their local machine that does not support
|
||
Maildirs. People may install an IMAP server on their local
|
||
machine, and point both <SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
> and their mail reader
|
||
of choice at it. This is often preferable to the mail
|
||
reader's own IMAP support since <SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
> supports many
|
||
features (offline reading, for one) that most IMAP-aware
|
||
readers don't.
|
||
</P
|
||
></DIV
|
||
></DIV
|
||
><DIV
|
||
CLASS="REFSECT1"
|
||
><A
|
||
NAME="AEN65"
|
||
></A
|
||
><H2
|
||
>Quick Start</H2
|
||
><P
|
||
>If you have already installed <SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
> system-wide,
|
||
or your system adminstrator has done that for you, your task
|
||
for setting up <SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
> for the first time is quite
|
||
simple. You just need to set up your configuration file, make
|
||
your folder directory, and run it!
|
||
</P
|
||
><P
|
||
>You can quickly set up your configuration file. The distribution
|
||
includes a file <TT
|
||
CLASS="FILENAME"
|
||
>offlineimap.conf.minimal</TT
|
||
>
|
||
(Debian users
|
||
may find this at
|
||
<TT
|
||
CLASS="FILENAME"
|
||
>/usr/share/doc/offlineimap/examples/offlineimap.conf.minimal</TT
|
||
>) that is a basic example of setting of <SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
>. You can
|
||
simply copy this file into your home directory and name it
|
||
<TT
|
||
CLASS="FILENAME"
|
||
>.offlineimaprc</TT
|
||
> (note the leading period). A
|
||
command such as <B
|
||
CLASS="COMMAND"
|
||
>cp offlineimap.conf.minimal ~/.offlineimaprc</B
|
||
> will do it. Or, if you prefer, you can just copy this text to
|
||
<TT
|
||
CLASS="FILENAME"
|
||
>~/.offlineimaprc</TT
|
||
>:
|
||
</P
|
||
><PRE
|
||
CLASS="PROGRAMLISTING"
|
||
>[general]
|
||
accounts = Test
|
||
|
||
[Account Test]
|
||
localrepository = Local
|
||
remoterepository = Remote
|
||
|
||
[Repository Local]
|
||
type = Maildir
|
||
localfolders = ~/Test
|
||
|
||
[Repository Remote]
|
||
type = IMAP
|
||
remotehost = examplehost
|
||
remoteuser = jgoerzen</PRE
|
||
><P
|
||
>Now, edit the <TT
|
||
CLASS="FILENAME"
|
||
>~/.offlineimaprc</TT
|
||
> file with
|
||
your favorite editor. All you have to do is specify a directory
|
||
for your folders to be in (on the <SPAN
|
||
CLASS="PROPERTY"
|
||
>localfolders</SPAN
|
||
>
|
||
line), the host name of your IMAP server (on the
|
||
<SPAN
|
||
CLASS="PROPERTY"
|
||
>remotehost</SPAN
|
||
> line), and your login name on
|
||
the remote (on the <SPAN
|
||
CLASS="PROPERTY"
|
||
>remoteuser</SPAN
|
||
> line). That's
|
||
it!</P
|
||
><P
|
||
>To run <SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
>, you just have to say
|
||
<B
|
||
CLASS="COMMAND"
|
||
>offlineimap</B
|
||
> -- it will fire up, ask you for
|
||
a login password if necessary, synchronize your folders, and exit.
|
||
See? You can just throw away the rest of this finely-crafted,
|
||
perfectly-honed manual! Of course, if you want to see how you can
|
||
make <SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
> FIVE TIMES FASTER FOR JUST $19.95 (err, well,
|
||
$0), you have to read on!
|
||
</P
|
||
></DIV
|
||
><DIV
|
||
CLASS="REFSECT1"
|
||
><A
|
||
NAME="AEN87"
|
||
></A
|
||
><H2
|
||
>Installation</H2
|
||
><P
|
||
>If you are reading this document via the "man" command, it is
|
||
likely
|
||
that you have no installation tasks to perform; your system
|
||
administrator has already installed it. If you need to install it
|
||
yourself, you have three options: a system-wide installation with
|
||
Debian, system-wide installation with other systems, and a single-user
|
||
installation. You can download the latest version of <SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
> from
|
||
<A
|
||
HREF="http://quux.org/devel/offlineimap/"
|
||
TARGET="_top"
|
||
>the <SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
>
|
||
website</A
|
||
>.
|
||
</P
|
||
><DIV
|
||
CLASS="REFSECT2"
|
||
><A
|
||
NAME="AEN93"
|
||
></A
|
||
><H3
|
||
>Prerequisites</H3
|
||
><P
|
||
>In order to use <SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
>, you need to have these conditions
|
||
satisfied:
|
||
</P
|
||
><P
|
||
></P
|
||
><UL
|
||
><LI
|
||
><P
|
||
>Your mail server must support IMAP. Most Internet Service
|
||
Providers
|
||
and corporate networks do, and most operating systems
|
||
have an IMAP
|
||
implementation readily available.
|
||
</P
|
||
></LI
|
||
><LI
|
||
><P
|
||
> You must have Python version 2.2.1 or above installed.
|
||
If you are
|
||
running on Debian GNU/Linux, this requirement will automatically be
|
||
taken care of for you. If you do not have Python already, check with
|
||
your system administrator or operating system vendor; or, download it from
|
||
<A
|
||
HREF="http://www.python.org/"
|
||
TARGET="_top"
|
||
>the Python website</A
|
||
>.
|
||
If you intend to use the Tk interface, you must have Tkinter
|
||
(python-tk) installed. If you intend to use the SSL interface, your
|
||
Python must have been built with SSL support.
|
||
</P
|
||
></LI
|
||
><LI
|
||
><P
|
||
> 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 <SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
>. If you do not have a mail reader
|
||
that supports Maildir, you can often install a local
|
||
IMAP server and point both <SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
> and your mail
|
||
reader at it.
|
||
</P
|
||
></LI
|
||
></UL
|
||
></DIV
|
||
><DIV
|
||
CLASS="REFSECT2"
|
||
><A
|
||
NAME="AEN107"
|
||
></A
|
||
><H3
|
||
>System-Wide Installation, Debian</H3
|
||
><P
|
||
> If you are tracking Debian unstable, you may install
|
||
<SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
> by simply running the following command as root:
|
||
</P
|
||
><P
|
||
> <B
|
||
CLASS="COMMAND"
|
||
>apt-get install offlineimap</B
|
||
>
|
||
</P
|
||
><P
|
||
> If you are not tracking Debian unstable, download the Debian .deb
|
||
package from the <A
|
||
HREF="http://quux.org/devel/offlineimap/"
|
||
TARGET="_top"
|
||
><SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
> website</A
|
||
>
|
||
and then run <B
|
||
CLASS="COMMAND"
|
||
>dpkg -i</B
|
||
> to install the downloaded
|
||
package. Then, skip to <A
|
||
HREF="#CONFIGURATION"
|
||
><I
|
||
>Configruation</I
|
||
></A
|
||
> below. You will type <B
|
||
CLASS="COMMAND"
|
||
>offlineimap</B
|
||
> to
|
||
invoke the program.
|
||
</P
|
||
></DIV
|
||
><DIV
|
||
CLASS="REFSECT2"
|
||
><A
|
||
NAME="AEN119"
|
||
></A
|
||
><H3
|
||
>System-Wide Installation, Other</H3
|
||
><P
|
||
> Download the tar.gz version of the package from the
|
||
<A
|
||
HREF="http://quux.org/devel/offlineimap/"
|
||
TARGET="_top"
|
||
>website</A
|
||
>.
|
||
Then run
|
||
these commands, making sure that you are the "root" user first:
|
||
</P
|
||
><PRE
|
||
CLASS="PROGRAMLISTING"
|
||
>tar -zxvf offlineimap_x.y.z.tar.gz
|
||
cd offlineimap-x.y.z
|
||
python2.2 setup.py install</PRE
|
||
><P
|
||
>On some systems, you will need to use
|
||
<B
|
||
CLASS="COMMAND"
|
||
>python</B
|
||
> instead of <B
|
||
CLASS="COMMAND"
|
||
>python2.2</B
|
||
>.
|
||
Next, proceed to <A
|
||
HREF="#CONFIGURATION"
|
||
><I
|
||
>Configruation</I
|
||
></A
|
||
> below. You will type <B
|
||
CLASS="COMMAND"
|
||
>offlineimap</B
|
||
> to
|
||
invoke the program.
|
||
</P
|
||
></DIV
|
||
><DIV
|
||
CLASS="REFSECT2"
|
||
><A
|
||
NAME="AEN129"
|
||
></A
|
||
><H3
|
||
>Single-Account Installation</H3
|
||
><P
|
||
> Download the tar.gz version of the package from the
|
||
<A
|
||
HREF="http://quux.org/devel/offlineimap/"
|
||
TARGET="_top"
|
||
>website</A
|
||
>.
|
||
Then run these commands:
|
||
</P
|
||
><PRE
|
||
CLASS="PROGRAMLISTING"
|
||
>tar -zxvf offlineimap_x.y.z.tar.gz
|
||
cd offlineimap-x.y.z</PRE
|
||
><P
|
||
>When you want to run <SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
>, you will issue the
|
||
<B
|
||
CLASS="COMMAND"
|
||
>cd</B
|
||
> command as above and then type
|
||
<B
|
||
CLASS="COMMAND"
|
||
>./offlineimap.py</B
|
||
>; there is no installation
|
||
step necessary.
|
||
</P
|
||
></DIV
|
||
></DIV
|
||
><DIV
|
||
CLASS="REFSECT1"
|
||
><A
|
||
NAME="CONFIGURATION"
|
||
></A
|
||
><H2
|
||
>Configruation</H2
|
||
><P
|
||
> <SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
> is regulated by a configuration file that is normally
|
||
stored in <TT
|
||
CLASS="FILENAME"
|
||
>~/.offlineimaprc</TT
|
||
>. <SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
>
|
||
ships with a file named <TT
|
||
CLASS="FILENAME"
|
||
>offlineimap.conf</TT
|
||
>
|
||
that you should copy to that location and then edit. This file is
|
||
vital to proper operation of the system; it sets everything you need
|
||
to run <SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
>. Full documentation for the configuration file
|
||
is included within the sample file.
|
||
</P
|
||
><P
|
||
> <SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
> also ships a file named
|
||
<TT
|
||
CLASS="FILENAME"
|
||
>offlineimap.conf.minimal</TT
|
||
> that you can also try.
|
||
It's useful if you want to get started with
|
||
the most basic feature set, and you can read about other features
|
||
later with <TT
|
||
CLASS="FILENAME"
|
||
>offlineimap.conf</TT
|
||
>.
|
||
</P
|
||
></DIV
|
||
><DIV
|
||
CLASS="REFSECT1"
|
||
><A
|
||
NAME="AEN150"
|
||
></A
|
||
><H2
|
||
>Options</H2
|
||
><P
|
||
> Most configuration is done via the configuration file. Nevertheless,
|
||
there are a few command-line options that you may set for
|
||
<SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
>.
|
||
</P
|
||
><P
|
||
></P
|
||
><DIV
|
||
CLASS="VARIABLELIST"
|
||
><DL
|
||
><DT
|
||
>-1</DT
|
||
><DD
|
||
><P
|
||
>Disable most multithreading operations and use
|
||
solely a single-connection
|
||
sync. This effectively sets the
|
||
<SPAN
|
||
CLASS="PROPERTY"
|
||
>maxsyncaccounts</SPAN
|
||
>
|
||
and all <SPAN
|
||
CLASS="PROPERTY"
|
||
>maxconnections</SPAN
|
||
> configuration file
|
||
variables to 1.
|
||
</P
|
||
></DD
|
||
><DT
|
||
>-P <TT
|
||
CLASS="REPLACEABLE"
|
||
><I
|
||
>profiledir</I
|
||
></TT
|
||
></DT
|
||
><DD
|
||
><P
|
||
>Sets <SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
> into profile mode. The program
|
||
will create <TT
|
||
CLASS="REPLACEABLE"
|
||
><I
|
||
>profiledir</I
|
||
></TT
|
||
>
|
||
(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. You must use the <TT
|
||
CLASS="OPTION"
|
||
>-1</TT
|
||
> option when
|
||
you use <TT
|
||
CLASS="OPTION"
|
||
>-P</TT
|
||
>.
|
||
</P
|
||
></DD
|
||
><DT
|
||
>-a <TT
|
||
CLASS="REPLACEABLE"
|
||
><I
|
||
>accountlist</I
|
||
></TT
|
||
></DT
|
||
><DD
|
||
><P
|
||
>Overrides the <SPAN
|
||
CLASS="PROPERTY"
|
||
>accounts</SPAN
|
||
> option
|
||
in the <SPAN
|
||
CLASS="PROPERTY"
|
||
>general</SPAN
|
||
> section of the configuration
|
||
file. You might use this to exclude certain accounts, or to sync
|
||
some accounts that you normally prefer not to. Separate the
|
||
accounts by commas, and use no embedded spaces.
|
||
</P
|
||
></DD
|
||
><DT
|
||
>-c <TT
|
||
CLASS="REPLACEABLE"
|
||
><I
|
||
>configfile</I
|
||
></TT
|
||
></DT
|
||
><DD
|
||
><P
|
||
>Specifies a configuration file to use in lieu of
|
||
the default, <TT
|
||
CLASS="FILENAME"
|
||
>~/.offlineimaprc</TT
|
||
>.
|
||
</P
|
||
></DD
|
||
><DT
|
||
>-d <TT
|
||
CLASS="REPLACEABLE"
|
||
><I
|
||
>debugtype[,...]</I
|
||
></TT
|
||
></DT
|
||
><DD
|
||
><P
|
||
>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
|
||
<TT
|
||
CLASS="OPTION"
|
||
>-1</TT
|
||
> to make the results more sensible.</P
|
||
><P
|
||
><TT
|
||
CLASS="OPTION"
|
||
>-d</TT
|
||
> requires one or more debugtypes,
|
||
separated by commas. These define what exactly will be
|
||
debugged, and include three options: <SPAN
|
||
CLASS="PROPERTY"
|
||
>imap</SPAN
|
||
>,
|
||
<SPAN
|
||
CLASS="PROPERTY"
|
||
>maildir</SPAN
|
||
>, and <SPAN
|
||
CLASS="PROPERTY"
|
||
>thread</SPAN
|
||
>.
|
||
The <SPAN
|
||
CLASS="PROPERTY"
|
||
>imap</SPAN
|
||
>
|
||
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
|
||
<SPAN
|
||
CLASS="PROPERTY"
|
||
>maildir</SPAN
|
||
> option will enable debugging for
|
||
certain Maildir operations. And <SPAN
|
||
CLASS="PROPERTY"
|
||
>thread</SPAN
|
||
>
|
||
will debug the threading model.
|
||
</P
|
||
></DD
|
||
><DT
|
||
>-o</DT
|
||
><DD
|
||
><P
|
||
>Run only once, ignoring all
|
||
<SPAN
|
||
CLASS="PROPERTY"
|
||
>autorefresh</SPAN
|
||
> settings in the configuration
|
||
file.</P
|
||
></DD
|
||
><DT
|
||
>-h, --help</DT
|
||
><DD
|
||
><P
|
||
>Show summary of options.</P
|
||
></DD
|
||
><DT
|
||
>-u <TT
|
||
CLASS="REPLACEABLE"
|
||
><I
|
||
>interface</I
|
||
></TT
|
||
></DT
|
||
><DD
|
||
><P
|
||
>Specifies an alternative user interface module
|
||
to use. This overrides the defailt specified in the
|
||
configuration file. The pre-defined options are listed in
|
||
the User Interfaces section.</P
|
||
></DD
|
||
></DL
|
||
></DIV
|
||
></DIV
|
||
><DIV
|
||
CLASS="REFSECT1"
|
||
><A
|
||
NAME="AEN212"
|
||
></A
|
||
><H2
|
||
>User Interfaces</H2
|
||
><P
|
||
><SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
> has a pluggable user interface system that lets you choose how the
|
||
program communicates information to you. There are two graphical
|
||
interfaces, two terminal interfaces, and two noninteractive interfaces
|
||
suitable for scripting or logging purposes. The
|
||
<SPAN
|
||
CLASS="PROPERTY"
|
||
>ui</SPAN
|
||
> option in the configuration file specifies
|
||
user interface preferences. The <TT
|
||
CLASS="OPTION"
|
||
>-u</TT
|
||
> command-line
|
||
option can override the configuration file setting. The available
|
||
values for the configuration file or command-line are described
|
||
in this section.</P
|
||
><DIV
|
||
CLASS="REFSECT2"
|
||
><A
|
||
NAME="AEN218"
|
||
></A
|
||
><H3
|
||
>Tk.Blinkenlights</H3
|
||
><P
|
||
>Tk.Blinkenlights is an interface designed to be sleek, fun to watch, and
|
||
informative of the overall picture of what <SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
>
|
||
is doing. I consider it to be the best general-purpose interface in
|
||
<SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
>.
|
||
</P
|
||
><P
|
||
> Tk.Blinkenlights contains, by default, a small window with a row of
|
||
LEDs, a small log, and a row of command buttons.
|
||
The total size of the window is
|
||
very small, so it uses little desktop space, yet it is quite
|
||
functional. The optional, toggleable, log shows more
|
||
detail about what is happening and is color-coded to match the color
|
||
of the lights.
|
||
</P
|
||
><P
|
||
> Tk.Blinkenlights is the only user interface that has configurable
|
||
parameters; see the example <TT
|
||
CLASS="FILENAME"
|
||
>offlineimap.conf</TT
|
||
>
|
||
for more details.
|
||
</P
|
||
><P
|
||
> Each light in the Blinkenlights interface represents a thread
|
||
of execution -- that is, a particular task that <SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
>
|
||
is performing right now. The colors indicate what task
|
||
the particular thread is performing, and are as follows:
|
||
</P
|
||
><P
|
||
></P
|
||
><DIV
|
||
CLASS="VARIABLELIST"
|
||
><DL
|
||
><DT
|
||
>Black</DT
|
||
><DD
|
||
><P
|
||
>indicates that this light's thread has terminated; it will light up
|
||
again later when new threads start up. So, black indicates no
|
||
activity.
|
||
</P
|
||
></DD
|
||
><DT
|
||
>Red (Meaning 1)</DT
|
||
><DD
|
||
><P
|
||
>is the color of the main program's thread, which basically does
|
||
nothing but monitor the others. It might remind you of HAL 9000 in
|
||
[<SPAN
|
||
CLASS="CITATION"
|
||
>2001</SPAN
|
||
>].
|
||
</P
|
||
></DD
|
||
><DT
|
||
>Gray</DT
|
||
><DD
|
||
><P
|
||
>indicates that the thread is establishing a new connection to the IMAP
|
||
server.
|
||
</P
|
||
></DD
|
||
><DT
|
||
>Purple</DT
|
||
><DD
|
||
><P
|
||
>is the color of an account synchronization thread that is monitoring
|
||
the progress of the folders in that account (not generating any I/O).
|
||
</P
|
||
></DD
|
||
><DT
|
||
>Cyan</DT
|
||
><DD
|
||
><P
|
||
>indicates that the thread is syncing a folder.
|
||
</P
|
||
></DD
|
||
><DT
|
||
>Green</DT
|
||
><DD
|
||
><P
|
||
>means that a folder's message list is being loaded.
|
||
</P
|
||
></DD
|
||
><DT
|
||
>Blue</DT
|
||
><DD
|
||
><P
|
||
>is the color of a message synchronization controller thread.
|
||
</P
|
||
></DD
|
||
><DT
|
||
>Orange</DT
|
||
><DD
|
||
><P
|
||
>indicates that an actual message is being copied.
|
||
(We use fuschia for fake messages.)
|
||
</P
|
||
></DD
|
||
><DT
|
||
>Red (meaning 2)</DT
|
||
><DD
|
||
><P
|
||
>indicates that a message is being deleted.
|
||
</P
|
||
></DD
|
||
><DT
|
||
>Yellow / bright orange</DT
|
||
><DD
|
||
><P
|
||
>indicates that message flags are being added.
|
||
</P
|
||
></DD
|
||
><DT
|
||
>Pink / bright red</DT
|
||
><DD
|
||
><P
|
||
>indicates that message flags are being removed.
|
||
</P
|
||
></DD
|
||
><DT
|
||
>Red / Black Flashing</DT
|
||
><DD
|
||
><P
|
||
>corresponds to the countdown timer that runs between
|
||
synchronizations.
|
||
</P
|
||
></DD
|
||
></DL
|
||
></DIV
|
||
><P
|
||
>The name of this interfaces derives from a bit of computer
|
||
history. Eric Raymond's [<SPAN
|
||
CLASS="CITATION"
|
||
>Jargon File</SPAN
|
||
>] defines
|
||
<I
|
||
CLASS="FIRSTTERM"
|
||
>blinkenlights</I
|
||
>, in part, as:
|
||
</P
|
||
><A
|
||
NAME="AEN281"
|
||
></A
|
||
><BLOCKQUOTE
|
||
CLASS="BLOCKQUOTE"
|
||
><P
|
||
>Front-panel diagnostic
|
||
lights on a computer, esp. a dinosaur. Now that dinosaurs are rare,
|
||
this term usually refers to status lights on a modem, network hub, or
|
||
the like.
|
||
</P
|
||
><P
|
||
> This term derives from the last word of the famous blackletter-Gothic
|
||
sign in mangled pseudo-German that once graced about half the computer
|
||
rooms in the English-speaking world. One version ran in its entirety as
|
||
follows:
|
||
</P
|
||
><P
|
||
> <SPAN
|
||
CLASS="emphasis"
|
||
><I
|
||
CLASS="EMPHASIS"
|
||
>ACHTUNG! ALLES LOOKENSPEEPERS!</I
|
||
></SPAN
|
||
>
|
||
</P
|
||
><P
|
||
> Das computermachine ist nicht fuer gefingerpoken und mittengrabben.
|
||
Ist easy schnappen der springenwerk, blowenfusen und poppencorken
|
||
mit spitzensparken. Ist nicht fuer gewerken bei das dumpkopfen.
|
||
Das rubbernecken sichtseeren keepen das cotten-pickenen hans in das
|
||
pockets muss; relaxen und watchen das blinkenlichten.
|
||
</P
|
||
></BLOCKQUOTE
|
||
></DIV
|
||
><DIV
|
||
CLASS="REFSECT2"
|
||
><A
|
||
NAME="AEN287"
|
||
></A
|
||
><H3
|
||
>Curses.Blinkenlights</H3
|
||
><P
|
||
> Curses.Blinkenlights is an interface very similar to Tk.Blinkenlights,
|
||
but is designed to be run in a console window (an xterm, Linux virtual
|
||
terminal, etc.) Since it doesn't have access to graphics, it isn't
|
||
quite as pretty, but it still gets the job done.
|
||
</P
|
||
><P
|
||
>Please see the Tk.Blinkenlights section above for more
|
||
information about the colors used in this interface.
|
||
</P
|
||
></DIV
|
||
><DIV
|
||
CLASS="REFSECT2"
|
||
><A
|
||
NAME="AEN291"
|
||
></A
|
||
><H3
|
||
>Tk.VerboseUI</H3
|
||
><P
|
||
> Tk.VerboseUI (formerly known as Tk.TkUI) is a graphical interface
|
||
that presents a variable-sized window. In the window, each
|
||
currently-executing thread has a section where its name and current
|
||
status are displayed. This interface is best suited to people running
|
||
on slower connections, as you get a lot of detail, but for fast
|
||
connections, the detail may go by too quickly to be useful. People
|
||
with fast connections may wish to use Tk.Blinkenlights instead.
|
||
</P
|
||
></DIV
|
||
><DIV
|
||
CLASS="REFSECT2"
|
||
><A
|
||
NAME="AEN294"
|
||
></A
|
||
><H3
|
||
>TTY.TTYUI</H3
|
||
><P
|
||
> TTY.TTYUI interface is for people running in basic, non-color terminals. It
|
||
prints out basic status messages and is generally friendly to use on a console
|
||
or xterm.
|
||
</P
|
||
></DIV
|
||
><DIV
|
||
CLASS="REFSECT2"
|
||
><A
|
||
NAME="AEN297"
|
||
></A
|
||
><H3
|
||
>Noninteractive.Basic</H3
|
||
><P
|
||
> Noninteractive.Basic is designed for situations in which <SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
>
|
||
will be run non-attended and the status of its execution will be
|
||
logged. You might use it, for instance, to have the system run
|
||
automatically and
|
||
e-mail you the results of the synchronization. This user interface
|
||
is not capable of reading a password from the keyboard; account
|
||
passwords must be specified using one of the configuration file options.
|
||
</P
|
||
></DIV
|
||
><DIV
|
||
CLASS="REFSECT2"
|
||
><A
|
||
NAME="AEN301"
|
||
></A
|
||
><H3
|
||
>Noninteractive.Quiet</H3
|
||
><P
|
||
> Noninteractive.Quiet is designed for non-attended running in situations
|
||
where normal status messages are not desired. It will output nothing
|
||
except errors and serious warnings. Like Noninteractive.Basic,
|
||
this user interface
|
||
is not capable of reading a password from the keyboard; account
|
||
passwords must be specified using one of the configuration file options.
|
||
</P
|
||
></DIV
|
||
></DIV
|
||
><DIV
|
||
CLASS="REFSECT1"
|
||
><A
|
||
NAME="AEN304"
|
||
></A
|
||
><H2
|
||
>Examples</H2
|
||
><P
|
||
>Here are some example configurations for various situations.
|
||
Please e-mail any other examples you have that may be useful to
|
||
me.
|
||
</P
|
||
><DIV
|
||
CLASS="REFSECT2"
|
||
><A
|
||
NAME="AEN307"
|
||
></A
|
||
><H3
|
||
>Multiple Accounts with Mutt</H3
|
||
><P
|
||
> This example shows you how to set up <SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
> to
|
||
synchronize multiple accounts with the mutt mail reader.
|
||
</P
|
||
><P
|
||
> Start by creating a directory to hold your folders by running
|
||
<B
|
||
CLASS="COMMAND"
|
||
>mkdir ~/Mail</B
|
||
>. Then, in your
|
||
<TT
|
||
CLASS="FILENAME"
|
||
>~/.offlineimaprc</TT
|
||
>, specify:
|
||
</P
|
||
><PRE
|
||
CLASS="PROGRAMLISTING"
|
||
>accounts = Personal, Work</PRE
|
||
><P
|
||
> Make sure that you have both an
|
||
<SPAN
|
||
CLASS="PROPERTY"
|
||
>[Account Personal]</SPAN
|
||
>
|
||
and an <SPAN
|
||
CLASS="PROPERTY"
|
||
>[Account Work]</SPAN
|
||
> section. The
|
||
local repository for each account must have different
|
||
<SPAN
|
||
CLASS="PROPERTY"
|
||
>localfolder</SPAN
|
||
> path names.
|
||
Also, make sure
|
||
to enable <SPAN
|
||
CLASS="PROPERTY"
|
||
>[mbnames]</SPAN
|
||
>.
|
||
</P
|
||
><P
|
||
> In each local repository section, write something like this:
|
||
</P
|
||
><PRE
|
||
CLASS="PROGRAMLISTING"
|
||
>localfolders = ~/Mail/Personal</PRE
|
||
><P
|
||
> Finally, add these lines to your <TT
|
||
CLASS="FILENAME"
|
||
>~/.muttrc</TT
|
||
>:
|
||
</P
|
||
><PRE
|
||
CLASS="PROGRAMLISTING"
|
||
>source ~/path-to-mbnames-muttrc-mailboxes
|
||
folder-hook Personal set from="youremail@personal.com"
|
||
folder-hook Work set from="youremail@work.com"
|
||
set mbox_type=Maildir
|
||
set folder=$HOME/Mail
|
||
spoolfile=+Personal/INBOX</PRE
|
||
><P
|
||
> That's it!
|
||
</P
|
||
></DIV
|
||
><DIV
|
||
CLASS="REFSECT2"
|
||
><A
|
||
NAME="AEN326"
|
||
></A
|
||
><H3
|
||
>UW-IMAPD and References</H3
|
||
><P
|
||
>Some users with a UW-IMAPD server need to use <SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
>'s
|
||
"reference" feature to get at their mailboxes, specifying a reference
|
||
of "~/Mail" or "#mh/" depending on the configuration. The below
|
||
configuration from (originally from docwhat@gerf.org)
|
||
shows using a <SPAN
|
||
CLASS="PROPERTY"
|
||
>reference</SPAN
|
||
> of Mail, a <SPAN
|
||
CLASS="PROPERTY"
|
||
>nametrans</SPAN
|
||
>
|
||
that strips
|
||
the leading Mail/ off incoming folder names, and a
|
||
<SPAN
|
||
CLASS="PROPERTY"
|
||
>folderfilter</SPAN
|
||
> that
|
||
limits the folders synced to just three.
|
||
</P
|
||
><PRE
|
||
CLASS="PROGRAMLISTING"
|
||
>[Account Gerf]
|
||
localrepository = GerfLocal
|
||
remoterepository = GerfRemote
|
||
|
||
[Repository GerfLocal]
|
||
type = Maildir
|
||
localfolders = ~/Mail
|
||
|
||
[Repository GerfRemote]
|
||
type = IMAP
|
||
remotehost = gerf.org
|
||
ssl = yes
|
||
remoteuser = docwhat
|
||
reference = Mail
|
||
# Trims off the preceeding Mail on all the folder names.
|
||
nametrans = lambda foldername: \
|
||
re.sub('^Mail/', '', foldername)
|
||
# Yeah, you have to mention the Mail dir, even though it
|
||
# would seem intuitive that reference would trim it.
|
||
folderfilter = lambda foldername: foldername in [
|
||
'Mail/INBOX',
|
||
'Mail/list/zaurus-general',
|
||
'Mail/list/zaurus-dev',
|
||
]
|
||
maxconnections = 1
|
||
holdconnectionopen = no</PRE
|
||
></DIV
|
||
><DIV
|
||
CLASS="REFSECT2"
|
||
><A
|
||
NAME="AEN334"
|
||
></A
|
||
><H3
|
||
>pythonfile Configuration File Option</H3
|
||
><P
|
||
>You can have <SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
>
|
||
load up a Python file before evaluating the
|
||
configuration file options that are Python expressions. This example
|
||
is based on one supplied by Tommi Virtanen for this feature.
|
||
</P
|
||
><P
|
||
> In <TT
|
||
CLASS="FILENAME"
|
||
>~/.offlineimap.rc</TT
|
||
>, he adds these options:
|
||
</P
|
||
><PRE
|
||
CLASS="PROGRAMLISTING"
|
||
>[general]
|
||
pythonfile=~/.offlineimap.py
|
||
[Repository foo]
|
||
foldersort=mycmp</PRE
|
||
><P
|
||
> Then, the <TT
|
||
CLASS="FILENAME"
|
||
>~/.offlineimap.py</TT
|
||
> file will
|
||
contain:
|
||
</P
|
||
><PRE
|
||
CLASS="PROGRAMLISTING"
|
||
>prioritized = ['INBOX', 'personal', 'announce', 'list']
|
||
|
||
def mycmp(x, y):
|
||
for prefix in prioritized:
|
||
if x.startswith(prefix):
|
||
return -1
|
||
elif y.startswith(prefix):
|
||
return +1
|
||
return cmp(x, y)
|
||
|
||
def test_mycmp():
|
||
import os, os.path
|
||
folders=os.listdir(os.path.expanduser('~/data/mail/tv@hq.yok.utu.fi'))
|
||
folders.sort(mycmp)
|
||
print folders</PRE
|
||
><P
|
||
> This code snippet illustrates how the <SPAN
|
||
CLASS="PROPERTY"
|
||
>foldersort</SPAN
|
||
>
|
||
option can be customized with a Python function from the
|
||
<SPAN
|
||
CLASS="PROPERTY"
|
||
>pythonfile</SPAN
|
||
> to always synchronize certain
|
||
folders first.
|
||
</P
|
||
></DIV
|
||
></DIV
|
||
><DIV
|
||
CLASS="REFSECT1"
|
||
><A
|
||
NAME="AEN347"
|
||
></A
|
||
><H2
|
||
>Errors</H2
|
||
><P
|
||
> If you get one of some frequently-encountered or confusing errors,
|
||
please check this section.
|
||
</P
|
||
><DIV
|
||
CLASS="REFSECT2"
|
||
><A
|
||
NAME="AEN350"
|
||
></A
|
||
><H3
|
||
>UID validity problem for folder</H3
|
||
><P
|
||
>IMAP servers use a unique ID (UID) to refer to a specific message.
|
||
This number is guaranteed to be unique to a particular message
|
||
<SPAN
|
||
CLASS="emphasis"
|
||
><I
|
||
CLASS="EMPHASIS"
|
||
>forever</I
|
||
></SPAN
|
||
>.
|
||
No other message in the same folder will ever get the same
|
||
UID. UIDs are an integral part of <SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
>'s synchronization
|
||
scheme; they are used to match up messages on your computer to
|
||
messages on the server.
|
||
</P
|
||
><P
|
||
> 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
|
||
<SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
> might still have the UIDs from the previous folder by the
|
||
same name stored. <SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
> will detect this condition and skip the
|
||
folder. This is GOOD, because it prevents data loss.
|
||
</P
|
||
><P
|
||
> You can fix it by removing your local folder and cache data. For
|
||
instance, if your folders are under <TT
|
||
CLASS="FILENAME"
|
||
>~/Folders</TT
|
||
>
|
||
and the folder with the problem is INBOX, you'd type this:
|
||
</P
|
||
><PRE
|
||
CLASS="PROGRAMLISTING"
|
||
>rm -r ~/Folders/INBOX
|
||
rm -r ~/.offlineimap/Account-<TT
|
||
CLASS="REPLACEABLE"
|
||
><I
|
||
>AccountName</I
|
||
></TT
|
||
>
|
||
rm -r ~/.offlineimap/Repository-<TT
|
||
CLASS="REPLACEABLE"
|
||
><I
|
||
>RepositoryName</I
|
||
></TT
|
||
></PRE
|
||
><P
|
||
> (Of course, replace AccountName and RepositoryName
|
||
with the names as specified
|
||
in <TT
|
||
CLASS="FILENAME"
|
||
>~/.offlineimaprc</TT
|
||
>).
|
||
</P
|
||
><P
|
||
>Next time you run <SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
>, 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.
|
||
</P
|
||
><P
|
||
> 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. <SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
> is incompatible with such servers.
|
||
Using <SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
> with them will not destroy any mail, but at the same time,
|
||
it will not actually synchronize it either. (<SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
> will detect
|
||
this condition and abort prior to synchronization.)
|
||
</P
|
||
><P
|
||
> This question comes up frequently on the
|
||
<A
|
||
HREF="http://lists.complete.org/offlineimap@complete.org/"
|
||
TARGET="_top"
|
||
><SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
>
|
||
mailing list</A
|
||
>. You can find a
|
||
<A
|
||
HREF="http://lists.complete.org/offlineimap@complete.org/2003/04/msg00012.html.gz"
|
||
TARGET="_top"
|
||
>detailed
|
||
discussion</A
|
||
> of the problem there.
|
||
</P
|
||
></DIV
|
||
></DIV
|
||
><DIV
|
||
CLASS="REFSECT1"
|
||
><A
|
||
NAME="AEN375"
|
||
></A
|
||
><H2
|
||
>Other Frequently Asked Questions</H2
|
||
><P
|
||
>There are some other FAQs that might not fit into another section
|
||
of the document, so they are discussed here.
|
||
</P
|
||
><P
|
||
></P
|
||
><DIV
|
||
CLASS="VARIABLELIST"
|
||
><DL
|
||
><DT
|
||
>What platforms does <SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
> run on?</DT
|
||
><DD
|
||
><P
|
||
> It should run on most platforms supported by Python, which are quite a
|
||
few.
|
||
</P
|
||
></DD
|
||
><DT
|
||
>I'm using Mutt. Other IMAP sync programs require me to use "set maildir_trash=yes". Do I need to do that with <SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
>?</DT
|
||
><DD
|
||
><P
|
||
> No. <SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
> is smart enough to figure out message deletion without this extra
|
||
crutch. You'll get the best results if you don't use this setting, in
|
||
fact.
|
||
</P
|
||
></DD
|
||
><DT
|
||
>How do I specify the names of my folders?</DT
|
||
><DD
|
||
><P
|
||
> You do not need to. <SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
> is smart
|
||
enough to automatically figure out what folders are present
|
||
on the IMAP server and synchronize them. You can use the
|
||
<SPAN
|
||
CLASS="PROPERTY"
|
||
>folderfilter</SPAN
|
||
> and <SPAN
|
||
CLASS="PROPERTY"
|
||
>foldertrans</SPAN
|
||
>
|
||
configuration file options to request certain folders and rename them
|
||
as they come in if you like.
|
||
</P
|
||
></DD
|
||
><DT
|
||
>How can I prevent certain folders from being synced?</DT
|
||
><DD
|
||
><P
|
||
> Use the <SPAN
|
||
CLASS="PROPERTY"
|
||
>folderfilter</SPAN
|
||
> option in the configuration file.
|
||
</P
|
||
></DD
|
||
><DT
|
||
>How can I add or delete a folder?</DT
|
||
><DD
|
||
><P
|
||
> <SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
> does not currently provide this feature, but if you create a new
|
||
folder on the IMAP server, it will be created locally automatically.
|
||
</P
|
||
></DD
|
||
><DT
|
||
>Are there any other warnings that I should be aware of?</DT
|
||
><DD
|
||
><P
|
||
> Yes; see the Notes section below.
|
||
</P
|
||
></DD
|
||
><DT
|
||
>What is the mailbox name recorder (mbnames) for?</DT
|
||
><DD
|
||
><P
|
||
>Some mail readers, such as Mutt, are not capable
|
||
of automatically determining the names of your mailboxes.
|
||
<SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
> can help these programs by writing the names
|
||
of the folders ni a format you specify. See the example
|
||
<TT
|
||
CLASS="FILENAME"
|
||
>offlineimap.conf</TT
|
||
> for details.
|
||
</P
|
||
></DD
|
||
><DT
|
||
>Can I synchronize multiple accounts with <SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
>?</DT
|
||
><DD
|
||
><P
|
||
>Sure. Just name them all in the
|
||
<SPAN
|
||
CLASS="PROPERTY"
|
||
>accounts</SPAN
|
||
> line in the <SPAN
|
||
CLASS="PROPERTY"
|
||
>general</SPAN
|
||
>
|
||
section of the configuration file, and add a per-account section
|
||
for each one.
|
||
</P
|
||
></DD
|
||
><DT
|
||
>Does <SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
> support POP?</DT
|
||
><DD
|
||
><P
|
||
>No. POP is not robust enough to do a completely reliable
|
||
multi-machine synchronization like <SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
> can do. <SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
>
|
||
will not support it.
|
||
</P
|
||
></DD
|
||
><DT
|
||
>Does <SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
> support mailbox formats other than Maildir?</DT
|
||
><DD
|
||
><P
|
||
>Not at present. There is no technical reason not to; just no
|
||
demand yet. Maildir is a superior format anyway.
|
||
However, <SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
> can sync between two IMAP
|
||
servers, and some IMAP servers support other formats. You
|
||
could install an IMAP server on your local machine and have
|
||
<SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
> sync to that.
|
||
</P
|
||
></DD
|
||
><DT
|
||
>[technical] Why are your Maildir message filenames so huge?</DT
|
||
><DD
|
||
><P
|
||
><SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
> has two relevant principles: 1) never modifying your
|
||
messages in any way and 2) ensuring 100% reliable synchronizations.
|
||
In order to do a reliable sync, <SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
>
|
||
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.
|
||
</P
|
||
><P
|
||
> So, <SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
> must store both a UID folder ID. The folder ID is
|
||
necessary so <SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
> can detect a message moved to a different
|
||
folder. <SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
> stores the UID (U= number) and an md5sum of the
|
||
foldername (FMD5= number) to facilitate this.
|
||
</P
|
||
></DD
|
||
><DT
|
||
>What is the speed of <SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
>'s sync?</DT
|
||
><DD
|
||
><P
|
||
>OfflineIMAP
|
||
versions 2.0 and above contain a multithreaded system. A good way to
|
||
experiment is by setting <SPAN
|
||
CLASS="PROPERTY"
|
||
>maxsyncaccounts</SPAN
|
||
> to 3 and <SPAN
|
||
CLASS="PROPERTY"
|
||
>maxconnections</SPAN
|
||
> to 3
|
||
in each account clause.
|
||
</P
|
||
><P
|
||
>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.
|
||
</P
|
||
><P
|
||
>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.
|
||
</P
|
||
><P
|
||
>An informal benchmark yields these results for my setup:
|
||
</P
|
||
><P
|
||
></P
|
||
><UL
|
||
><LI
|
||
><P
|
||
>10 minutes with MacOS X Mail.app "manual cache"
|
||
</P
|
||
></LI
|
||
><LI
|
||
><P
|
||
>5 minutes with GNUS agent sync</P
|
||
></LI
|
||
><LI
|
||
><P
|
||
>20 seconds with OfflineIMAP 1.x</P
|
||
></LI
|
||
><LI
|
||
><P
|
||
>9 seconds with OfflineIMAP 2.x</P
|
||
></LI
|
||
><LI
|
||
><P
|
||
>3 seconds with OfflineIMAP 3.x "cold start"</P
|
||
></LI
|
||
><LI
|
||
><P
|
||
>2 seconds with OfflineIMAP 3.x "held connection"</P
|
||
></LI
|
||
></UL
|
||
></DD
|
||
></DL
|
||
></DIV
|
||
></DIV
|
||
><DIV
|
||
CLASS="REFSECT1"
|
||
><A
|
||
NAME="AEN471"
|
||
></A
|
||
><H2
|
||
>Conforming To</H2
|
||
><P
|
||
></P
|
||
><UL
|
||
><LI
|
||
><P
|
||
>Internet Message Access Protocol version 4rev1 (IMAP 4rev1) as
|
||
specified in RFC2060</P
|
||
></LI
|
||
><LI
|
||
><P
|
||
>CRAM-MD5 as specified in RFC2195</P
|
||
></LI
|
||
><LI
|
||
><P
|
||
>Maildir as specified in
|
||
<A
|
||
HREF="http://www.qmail.org/qmail-manual-html/man5/maildir.html"
|
||
TARGET="_top"
|
||
>the Maildir manpage</A
|
||
> and
|
||
<A
|
||
HREF="http://cr.yp.to/proto/maildir.html"
|
||
TARGET="_top"
|
||
>the qmail website</A
|
||
>.</P
|
||
></LI
|
||
><LI
|
||
><P
|
||
>Standard Python 2.2.1 as implemented on POSIX-compliant systems.</P
|
||
></LI
|
||
></UL
|
||
></DIV
|
||
><DIV
|
||
CLASS="REFSECT1"
|
||
><A
|
||
NAME="AEN484"
|
||
></A
|
||
><H2
|
||
>Notes</H2
|
||
><DIV
|
||
CLASS="REFSECT2"
|
||
><A
|
||
NAME="AEN486"
|
||
></A
|
||
><H3
|
||
>Deleting Local Folders</H3
|
||
><P
|
||
><SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
> does a two-way synchronization. That is, if you
|
||
make a change to the mail on the server, it will be propogated 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 <SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
>, remember to also remove your local status
|
||
cache (<TT
|
||
CLASS="FILENAME"
|
||
>~/.offlineimap</TT
|
||
> by default). Otherwise, <SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
> 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)
|
||
</P
|
||
></DIV
|
||
><DIV
|
||
CLASS="REFSECT2"
|
||
><A
|
||
NAME="AEN493"
|
||
></A
|
||
><H3
|
||
>Multiple Instances</H3
|
||
><P
|
||
><SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
> 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 <SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
> is already running. If you need
|
||
to schedule synchronizations, please use the
|
||
<SPAN
|
||
CLASS="PROPERTY"
|
||
>autorefresh</SPAN
|
||
> settings rather than cron.
|
||
Alternatively, you can set a separate <SPAN
|
||
CLASS="PROPERTY"
|
||
>metadata</SPAN
|
||
>
|
||
directory for each instance.
|
||
</P
|
||
></DIV
|
||
><DIV
|
||
CLASS="REFSECT2"
|
||
><A
|
||
NAME="AEN500"
|
||
></A
|
||
><H3
|
||
>Copying Messages Between Folders</H3
|
||
><P
|
||
> Normally, when you copy a message between folders or add a new message
|
||
to a folder locally, <SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
>
|
||
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, <SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
>
|
||
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.
|
||
<SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
> makes sure that the message was properly uploaded before deleting it,
|
||
so there should be no risk of data loss.
|
||
</P
|
||
></DIV
|
||
><DIV
|
||
CLASS="REFSECT2"
|
||
><A
|
||
NAME="AEN506"
|
||
></A
|
||
><H3
|
||
>Use with Evolution</H3
|
||
><P
|
||
><SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
> can work with Evolution. To do so, first configure
|
||
your <SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
> account to have
|
||
<TT
|
||
CLASS="OPTION"
|
||
>sep = /</TT
|
||
> 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
|
||
<SPAN
|
||
CLASS="emphasis"
|
||
><I
|
||
CLASS="EMPHASIS"
|
||
>inside</I
|
||
></SPAN
|
||
> your <SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
> storage location.
|
||
You're now set!
|
||
</P
|
||
></DIV
|
||
><DIV
|
||
CLASS="REFSECT2"
|
||
><A
|
||
NAME="AEN514"
|
||
></A
|
||
><H3
|
||
>Use with KMail</H3
|
||
><P
|
||
>At this time, I believe that <SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
> 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
|
||
<SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
>.
|
||
</P
|
||
><P
|
||
> However, I have made KMail version 3 work well with
|
||
<SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
> by installing an IMAP server on my local
|
||
machine, having <SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
> sync to that, and pointing
|
||
KMail at the same server.
|
||
</P
|
||
></DIV
|
||
><DIV
|
||
CLASS="REFSECT2"
|
||
><A
|
||
NAME="AEN522"
|
||
></A
|
||
><H3
|
||
>Mailing List</H3
|
||
><P
|
||
>There is an OfflineIMAP mailing list available.
|
||
To subscribe, send the text "Subscribe" in the subject of a mail to
|
||
offlineimap-request@complete.org. To post, send the message to
|
||
offlineimap@complete.org. Archives are available at
|
||
<A
|
||
HREF="http://lists.complete.org/offlineimap@complete.org/"
|
||
TARGET="_top"
|
||
>http://lists.complete.org/offlineimap@complete.org/</A
|
||
>.
|
||
</P
|
||
></DIV
|
||
><DIV
|
||
CLASS="REFSECT2"
|
||
><A
|
||
NAME="AEN526"
|
||
></A
|
||
><H3
|
||
>Bugs</H3
|
||
><P
|
||
>Reports of bugs should be sent via e-mail to the
|
||
<SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
> bug-tracking system (BTS) at
|
||
offlineimap@bugs.complete.org or submitted online using
|
||
the <A
|
||
HREF="http://bugs.complete.org/"
|
||
TARGET="_top"
|
||
>web interface</A
|
||
>.
|
||
</P
|
||
><P
|
||
> The Web site also lists all current bugs, where you can check their
|
||
status or contribute to fixing them.
|
||
</P
|
||
></DIV
|
||
></DIV
|
||
><DIV
|
||
CLASS="REFSECT1"
|
||
><A
|
||
NAME="AEN532"
|
||
></A
|
||
><H2
|
||
>Copyright</H2
|
||
><P
|
||
>OfflineIMAP, and this manual, are Copyright <20> 2002, 2003 John Goerzen.</P
|
||
><P
|
||
> This program is free software; you can redistribute it and/or modify
|
||
it under the terms of the GNU General Public License as published by
|
||
the Free Software Foundation; either version 2 of the License, or
|
||
(at your option) any later version.
|
||
</P
|
||
><P
|
||
> This program is distributed in the hope that it will be useful,
|
||
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||
GNU General Public License for more details.
|
||
</P
|
||
><P
|
||
> You should have received a copy of the GNU General Public License
|
||
along with this program; if not, write to the Free Software
|
||
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA</P
|
||
><P
|
||
>imaplib.py comes from the Python dev tree and is licensed under
|
||
the GPL-compatible PSF license as stated in the file
|
||
<TT
|
||
CLASS="FILENAME"
|
||
>COPYRIGHT</TT
|
||
> in the <SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
>
|
||
distribution.
|
||
</P
|
||
></DIV
|
||
><DIV
|
||
CLASS="REFSECT1"
|
||
><A
|
||
NAME="AEN541"
|
||
></A
|
||
><H2
|
||
>Author</H2
|
||
><P
|
||
><SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
>, its libraries, documentation, and all included files, except where
|
||
noted, was written by John Goerzen <TT
|
||
CLASS="EMAIL"
|
||
><<A
|
||
HREF="mailto:jgoerzen@complete.org"
|
||
>jgoerzen@complete.org</A
|
||
>></TT
|
||
> and
|
||
copyright is held as stated in the COPYRIGHT section.
|
||
</P
|
||
><P
|
||
> <SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
> may be downloaded, and information found, from its
|
||
homepage via either <A
|
||
HREF="gopher://quux.org/1/devel/offlineimap"
|
||
TARGET="_top"
|
||
>Gopher</A
|
||
>
|
||
or <A
|
||
HREF="http://quux.org/devel/offlineimap"
|
||
TARGET="_top"
|
||
>HTTP</A
|
||
>.
|
||
</P
|
||
><P
|
||
> <SPAN
|
||
CLASS="APPLICATION"
|
||
>OfflineIMAP</SPAN
|
||
> may also be downloaded using Subversion. Additionally,
|
||
the distributed tar.gz may be updated with a simple "svn update"
|
||
command; it is ready to go. For information on getting OfflineIMAP
|
||
with Subversion, please visit the
|
||
<A
|
||
HREF="http://svn.complete.org/"
|
||
TARGET="_top"
|
||
>complete.org Subversion page</A
|
||
>.
|
||
</P
|
||
></DIV
|
||
><DIV
|
||
CLASS="REFSECT1"
|
||
><A
|
||
NAME="AEN553"
|
||
></A
|
||
><H2
|
||
>See Also</H2
|
||
><P
|
||
><SPAN
|
||
CLASS="APPLICATION"
|
||
>mutt</SPAN
|
||
>(1),
|
||
<SPAN
|
||
CLASS="APPLICATION"
|
||
>python</SPAN
|
||
>(1)
|
||
</P
|
||
></DIV
|
||
></DIV
|
||
></BODY
|
||
></HTML
|
||
> |