810 lines
30 KiB
Groff
810 lines
30 KiB
Groff
.\" This manpage has been automatically generated by docbook2man
|
|
.\" from a DocBook document. This tool can be found at:
|
|
.\" <http://shell.ipoline.com/~elmert/comp/docbook2X/>
|
|
.\" Please send any bug reports, improvements, comments, patches,
|
|
.\" etc. to Steve Cheng <steve@ggi-project.org>.
|
|
.TH "OFFLINEIMAP" "1" "05 February 2003" "John Goerzen" "OfflineIMAP Manual"
|
|
|
|
.SH NAME
|
|
OfflineIMAP \- Powerful IMAP/Maildir synchronization and reader support
|
|
.SH SYNOPSIS
|
|
|
|
\fBofflineimap\fR [ \fB-1\fR ] [ \fB-P \fIprofiledir\fB\fR ] [ \fB-a \fIaccountlist\fB\fR ] [ \fB-c \fIconfigfile\fB\fR ] [ \fB-d \fIdebugtype[,...]\fB\fR ] [ \fB-o\fR ] [ \fB-u \fIinterface\fB\fR ]
|
|
|
|
|
|
\fBofflineimap\fR \fB-h\fR | \fB--help\fR
|
|
|
|
.SH "DESCRIPTION"
|
|
.PP
|
|
\fBOfflineIMAP\fR is a tool to simplify your e-mail
|
|
reading. With \fBOfflineIMAP\fR, 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. \fBOfflineIMAP\fR 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.
|
|
.PP
|
|
\fBOfflineIMAP\fR is \fBFAST\fR; 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, \fBOfflineIMAP\fR features a
|
|
multi-threaded synchronization algorithm that can dramatically
|
|
speed up performance in many situations by synchronizing
|
|
several different things simultaneously.
|
|
.PP
|
|
\fBOfflineIMAP\fR is \fBFLEXIBLE\fR; 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.
|
|
.PP
|
|
\fBOfflineIMAP\fR is \fBSAFE\fR; 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 \fBOfflineIMAP\fR pre-release, development, and beta
|
|
releases. Of course, legally speaking, \fBOfflineIMAP\fR comes
|
|
with no warranty, so I am not responsible if this turns out
|
|
to be wrong.
|
|
.SS "METHOD OF OPERATION"
|
|
.PP
|
|
\fBOfflineIMAP\fR 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. \fBOfflineIMAP\fR 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.
|
|
.SH "QUICK START"
|
|
.PP
|
|
If you have already installed \fBOfflineIMAP\fR system-wide,
|
|
or your system adminstrator has done that for you, your task
|
|
for setting up \fBOfflineIMAP\fR for the first time is quite
|
|
simple. You just need to set up your configuration file, make
|
|
your folder directory, and run it!
|
|
.PP
|
|
You can quickly set up your configuration file. The distribution
|
|
includes a file \fIofflineimap.conf.minimal\fR
|
|
(Debian users
|
|
may find this at
|
|
\fI/usr/share/doc/offlineimap/examples/offlineimap.conf.minimal\fR) that is a basic example of setting of \fBOfflineIMAP\fR. You can
|
|
simply copy this file into your home directory and name it
|
|
\fI.offlineimaprc\fR (note the leading period). A
|
|
command such as \fBcp offlineimap.conf.minimal ~/.offlineimaprc\fR will do it. Or, if you prefer, you can just copy this text to
|
|
\fI~/.offlineimaprc\fR:
|
|
|
|
.nf
|
|
[general]
|
|
accounts = Test
|
|
|
|
[Test]
|
|
localfolders = ~/Test
|
|
remotehost = examplehost
|
|
remoteuser = jgoerzen
|
|
.fi
|
|
.PP
|
|
Now, edit the \fI~/.offlineimaprc\fR file with
|
|
your favorite editor. All you have to do is specify a directory
|
|
for your folders to be in (on the \fIlocalfolders\fR
|
|
line), the host name of your IMAP server (on the
|
|
\fIremotehost\fR line), and your login name on
|
|
the remote (on the \fIremoteuser\fR line). That's
|
|
it!
|
|
.PP
|
|
To run \fBOfflineIMAP\fR, you just have to say
|
|
\fBofflineimap\fR -- 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 \fBOfflineIMAP\fR FIVE TIMES FASTER FOR JUST $19.95 (err, well,
|
|
$0), you have to read on!
|
|
.SH "INSTALLATION"
|
|
.PP
|
|
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 \fBOfflineIMAP\fR from
|
|
the \fBOfflineIMAP\fR
|
|
website <URL:http://quux.org/devel/offlineimap/>.
|
|
.SS "PREREQUISITES"
|
|
.PP
|
|
In order to use \fBOfflineIMAP\fR, you need to have these conditions
|
|
satisfied:
|
|
.TP 0.2i
|
|
\(bu
|
|
Your mail server must support IMAP. Most Internet Service
|
|
Providers
|
|
and corporate networks do, and most operating systems
|
|
have an IMAP
|
|
implementation readily available.
|
|
.TP 0.2i
|
|
\(bu
|
|
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
|
|
the Python website <URL:http://www.python.org/>.
|
|
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.
|
|
.TP 0.2i
|
|
\(bu
|
|
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
|
|
\fBOfflineIMAP\fR.
|
|
.SS "SYSTEM-WIDE INSTALLATION, DEBIAN"
|
|
.PP
|
|
If you are tracking Debian unstable, you may install
|
|
\fBOfflineIMAP\fR by simply running the following command as root:
|
|
.PP
|
|
\fBapt-get install offlineimap\fR
|
|
.PP
|
|
If you are not tracking Debian unstable, download the Debian .deb
|
|
package from the \fBOfflineIMAP\fR website <URL:http://quux.org/devel/offlineimap/>
|
|
and then run \fBdpkg -i\fR to install the downloaded
|
|
package. Then, skip to [XRef to CONFIGURATION] below. You will type \fBofflineimap\fR to
|
|
invoke the program.
|
|
.SS "SYSTEM-WIDE INSTALLATION, OTHER"
|
|
.PP
|
|
Download the tar.gz version of the package from the
|
|
website <URL:http://quux.org/devel/offlineimap/>.
|
|
Then run
|
|
these commands, making sure that you are the "root" user first:
|
|
|
|
.nf
|
|
tar -zxvf offlineimap_x.y.z.tar.gz
|
|
cd offlineimap-x.y.z
|
|
python2.2 setup.py install
|
|
.fi
|
|
.PP
|
|
On some systems, you will need to use
|
|
\fBpython\fR instead of \fBpython2.2\fR.
|
|
Next, proceed to [XRef to CONFIGURATION] below. You will type \fBofflineimap\fR to
|
|
invoke the program.
|
|
.SS "SINGLE-ACCOUNT INSTALLATION"
|
|
.PP
|
|
Download the tar.gz version of the package from the
|
|
website <URL:http://quux.org/devel/offlineimap/>.
|
|
Then run these commands:
|
|
|
|
.nf
|
|
tar -zxvf offlineimap_x.y.z.tar.gz
|
|
cd offlineimap-x.y.z
|
|
.fi
|
|
.PP
|
|
When you want to run \fBOfflineIMAP\fR, you will issue the
|
|
\fBcd\fR command as above and then type
|
|
\fB./offlineimap.py\fR; there is no installation
|
|
step necessary.
|
|
.SH "CONFIGRUATION"
|
|
.PP
|
|
\fBOfflineIMAP\fR is regulated by a configuration file that is normally
|
|
stored in \fI~/.offlineimaprc\fR. \fBOfflineIMAP\fR
|
|
ships with a file named \fIofflineimap.conf\fR
|
|
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 \fBOfflineIMAP\fR. Full documentation for the configuration file
|
|
is included within the sample file.
|
|
.PP
|
|
\fBOfflineIMAP\fR also ships a file named
|
|
\fIofflineimap.conf.minimal\fR 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 \fIofflineimap.conf\fR.
|
|
.SH "OPTIONS"
|
|
.PP
|
|
Most configuration is done via the configuration file. Nevertheless,
|
|
there are a few command-line options that you may set for
|
|
\fBOfflineIMAP\fR.
|
|
.TP
|
|
\fB-1\fR
|
|
Disable most multithreading operations and use
|
|
solely a single-connection
|
|
sync. This effectively sets the \fImaxsyncaccounts\fR
|
|
and all \fImaxconnections\fR configuration file
|
|
variables to 1.
|
|
.TP
|
|
\fB-P \fIprofiledir\fB\fR
|
|
Sets \fBOfflineIMAP\fR into profile mode. The program
|
|
will create \fIprofiledir\fR
|
|
(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 \fB-1\fR option when
|
|
you use \fB-P\fR.
|
|
.TP
|
|
\fB-a \fIaccountlist\fB\fR
|
|
Overrides the \fIaccounts\fR option
|
|
in the \fIgeneral\fR 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.
|
|
.TP
|
|
\fB-c \fIconfigfile\fB\fR
|
|
Specifies a configuration file to use in lieu of
|
|
the default, \fI~/.offlineimaprc\fR.
|
|
.TP
|
|
\fB-d \fIdebugtype[,...]\fB\fR
|
|
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
|
|
\fB-1\fR to make the results more sensible.
|
|
|
|
\fB-d\fR requires one or more debugtypes,
|
|
separated by commas. These define what exactly will be
|
|
debugged, and include two options: \fIimap\fR
|
|
and \fImaildir\fR. The \fIimap\fR
|
|
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
|
|
\fImaildir\fR option will enable debugging for
|
|
certain Maildir operations.
|
|
.TP
|
|
\fB-o\fR
|
|
Run only once, ignoring all
|
|
\fIautorefresh\fR settings in the configuration
|
|
file.
|
|
.TP
|
|
\fB-h\fR
|
|
.TP
|
|
\fB--help\fR
|
|
Show summary of options.
|
|
.TP
|
|
\fB-u \fIinterface\fB\fR
|
|
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.
|
|
.SH "USER INTERFACES"
|
|
.PP
|
|
\fBOfflineIMAP\fR 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
|
|
\fIui\fR option in the configuration file specifies
|
|
user interface preferences. The \fB-u\fR command-line
|
|
option can override the configuration file setting. The available
|
|
values for the configuration file or command-line are described
|
|
in this section.
|
|
.SS "TK.BLINKENLIGHTS"
|
|
.PP
|
|
Tk.Blinkenlights is an interface designed to be sleek, fun to watch, and
|
|
informative of the overall picture of what \fBOfflineIMAP\fR
|
|
is doing. I consider it to be the best general-purpose interface in
|
|
\fBOfflineIMAP\fR.
|
|
.PP
|
|
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.
|
|
.PP
|
|
Tk.Blinkenlights is the only user interface that has configurable
|
|
parameters; see the example \fIofflineimap.conf\fR
|
|
for more details.
|
|
.PP
|
|
Each light in the Blinkenlights interface represents a thread
|
|
of execution -- that is, a particular task that \fBOfflineIMAP\fR
|
|
is performing right now. The colors indicate what task
|
|
the particular thread is performing, and are as follows:
|
|
.TP
|
|
\fBBlack\fR
|
|
indicates that this light's thread has terminated; it will light up
|
|
again later when new threads start up. So, black indicates no
|
|
activity.
|
|
.TP
|
|
\fBRed (Meaning 1)\fR
|
|
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
|
|
2001.
|
|
.TP
|
|
\fBGray\fR
|
|
indicates that the thread is establishing a new connection to the IMAP
|
|
server.
|
|
.TP
|
|
\fBPurple\fR
|
|
is the color of an account synchronization thread that is monitoring
|
|
the progress of the folders in that account (not generating any I/O).
|
|
.TP
|
|
\fBCyan\fR
|
|
indicates that the thread is syncing a folder.
|
|
.TP
|
|
\fBGreen\fR
|
|
means that a folder's message list is being loaded.
|
|
.TP
|
|
\fBBlue\fR
|
|
is the color of a message synchronization controller thread.
|
|
.TP
|
|
\fBOrange\fR
|
|
indicates that an actual message is being copied.
|
|
(We use fuschia for fake messages.)
|
|
.TP
|
|
\fBRed (meaning 2)\fR
|
|
indicates that a message is being deleted.
|
|
.TP
|
|
\fBYellow / bright orange\fR
|
|
indicates that message flags are being added.
|
|
.TP
|
|
\fBPink / bright red\fR
|
|
indicates that message flags are being removed.
|
|
.TP
|
|
\fBRed / Black Flashing\fR
|
|
corresponds to the countdown timer that runs between
|
|
synchronizations.
|
|
.PP
|
|
The name of this interfaces derives from a bit of computer
|
|
history. Eric Raymond's Jargon File defines
|
|
\fIblinkenlights\fR, in part, as:
|
|
.sp
|
|
.RS
|
|
.PP
|
|
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.
|
|
.PP
|
|
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:
|
|
.PP
|
|
\fBACHTUNG! ALLES LOOKENSPEEPERS!\fR
|
|
.PP
|
|
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.
|
|
.RE
|
|
.SS "CURSES.BLINKENLIGHTS"
|
|
.PP
|
|
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.
|
|
.PP
|
|
Please see the Tk.Blinkenlights section above for more
|
|
information about the colors used in this interface.
|
|
.SS "TK.VERBOSEUI"
|
|
.PP
|
|
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.
|
|
.SS "TTY.TTYUI"
|
|
.PP
|
|
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.
|
|
.SS "NONINTERACTIVE.BASIC"
|
|
.PP
|
|
Noninteractive.Basic is designed for situations in which \fBOfflineIMAP\fR
|
|
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.
|
|
.SS "NONINTERACTIVE.QUIET"
|
|
.PP
|
|
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.
|
|
.SH "EXAMPLES"
|
|
.PP
|
|
Here are some example configurations for various situations.
|
|
Please e-mail any other examples you have that may be useful to
|
|
me.
|
|
.SS "MULTIPLE ACCOUNTS WITH MUTT"
|
|
.PP
|
|
This example shows you how to set up \fBOfflineIMAP\fR to
|
|
synchronize multiple accounts with the mutt mail reader.
|
|
.PP
|
|
Start by creating a directory to hold your folders by running
|
|
\fBmkdir ~/Mail\fR. Then, in your
|
|
\fI~/.offlineimaprc\fR, specify:
|
|
|
|
.nf
|
|
accounts = Personal, Work
|
|
.fi
|
|
.PP
|
|
Make sure that you have both a \fI[Personal]\fR
|
|
and a \fI[Work]\fR section, each with different
|
|
\fIlocalfolder\fR path names. Also, make sure
|
|
to enable \fI[mbnames]\fR.
|
|
.PP
|
|
In each account section, write something like this:
|
|
|
|
.nf
|
|
localfolders = ~/Mail/Personal
|
|
.fi
|
|
.PP
|
|
Finally, add these lines to your \fI~/.muttrc\fR:
|
|
|
|
.nf
|
|
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
|
|
.fi
|
|
.PP
|
|
That's it!
|
|
.SS "UW-IMAPD AND REFERENCES"
|
|
.PP
|
|
Some users with a UW-IMAPD server need to use \fBOfflineIMAP\fR's
|
|
"reference" feature to get at their mailboxes, specifying a reference
|
|
of "~/Mail" or "#mh/" depending on the configuration. The below
|
|
configuration from docwhat@gerf.org
|
|
shows using a \fIreference\fR of Mail, a \fInametrans\fR
|
|
that strips
|
|
the leading Mail/ off incoming folder names, and a
|
|
\fIfolderfilter\fR that
|
|
limits the folders synced to just three.
|
|
|
|
.nf
|
|
[Gerf]
|
|
localfolders = ~/Mail
|
|
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
|
|
.fi
|
|
.SS "PYTHONFILE CONFIGURATION FILE OPTION"
|
|
.PP
|
|
You can have \fBOfflineIMAP\fR
|
|
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.
|
|
.PP
|
|
In \fI~/.offlineimap.rc\fR, he adds these options:
|
|
|
|
.nf
|
|
[general]
|
|
pythonfile=~/.offlineimap.py
|
|
[foo]
|
|
foldersort=mycmp
|
|
.fi
|
|
.PP
|
|
Then, the \fI~/.offlineimap.py\fR file will
|
|
contain:
|
|
|
|
.nf
|
|
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
|
|
.fi
|
|
.PP
|
|
This code snippet illustrates how the \fIfoldersort\fR
|
|
option can be customized with a Python function from the
|
|
\fIpythonfile\fR to always synchronize certain
|
|
folders first.
|
|
.SH "ERRORS"
|
|
.PP
|
|
If you get one of some frequently-encountered or confusing errors,
|
|
please check this section.
|
|
.SS "UID VALIDITY PROBLEM FOR FOLDER"
|
|
.PP
|
|
IMAP servers use a unique ID (UID) to refer to a specific message.
|
|
This number is guaranteed to be unique to a particular message
|
|
\fBforever\fR.
|
|
No other message in the same folder will ever get the same
|
|
UID. UIDs are an integral part of \fBOfflineIMAP\fR's synchronization
|
|
scheme; they are used to match up messages on your computer to
|
|
messages on the server.
|
|
.PP
|
|
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
|
|
\fBOfflineIMAP\fR might still have the UIDs from the previous folder by the
|
|
same name stored. \fBOfflineIMAP\fR will detect this condition and skip the
|
|
folder. This is GOOD, because it prevents data loss.
|
|
.PP
|
|
You can fix it by removing your local folder and cache data. For
|
|
instance, if your folders are under \fI~/Folders\fR
|
|
and the folder with the problem is INBOX, you'd type this:
|
|
|
|
.nf
|
|
rm -r ~/Folders/INBOX
|
|
rm -r ~/.offlineimap/AccountName/INBOX
|
|
.fi
|
|
.PP
|
|
(Of course, replace AccountName with the account name as specified
|
|
in \fI~/.offlineimaprc\fR).
|
|
.PP
|
|
Next time you run \fBOfflineIMAP\fR, 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.
|
|
.PP
|
|
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. \fBOfflineIMAP\fR is incompatible with such servers.
|
|
Using \fBOfflineIMAP\fR with them will not destroy any mail, but at the same time,
|
|
it will not actually synchronize it either. (\fBOfflineIMAP\fR will detect
|
|
this condition and abort prior to synchronization.)
|
|
.SH "OTHER FREQUENTLY ASKED QUESTIONS"
|
|
.PP
|
|
There are some other FAQs that might not fit into another section
|
|
of the document, so they are discussed here.
|
|
.TP
|
|
\fBWhat platforms does OfflineIMAP run on?\fR
|
|
It should run on most platforms supported by Python, which are quite a
|
|
few.
|
|
.TP
|
|
\fBI'm using Mutt. Other IMAP sync programs require me to use "set maildir_trash=yes". Do I need to do that with OfflineIMAP?\fR
|
|
No. \fBOfflineIMAP\fR 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.
|
|
.TP
|
|
\fBHow do I specify the names of my folders?\fR
|
|
You do not need to. \fBOfflineIMAP\fR is smart
|
|
enough to automatically figure out what folders are present
|
|
on the IMAP server and synchronize them. You can use the
|
|
\fIfolderfilter\fR and \fIfoldertrans\fR
|
|
configuration file options to request certain folders and rename them
|
|
as they come in if you like.
|
|
.TP
|
|
\fBHow can I prevent certain folders from being synced?\fR
|
|
Use the \fIfolderfilter\fR option in the configuration file.
|
|
.TP
|
|
\fBHow can I add or delete a folder?\fR
|
|
\fBOfflineIMAP\fR does not currently provide this feature, but if you create a new
|
|
folder on the IMAP server, it will be created locally automatically.
|
|
.TP
|
|
\fBAre there any other warnings that I should be aware of?\fR
|
|
Yes; see the Notes section below.
|
|
.TP
|
|
\fBWhat is the mailbox name recorder (mbnames) for?\fR
|
|
Some mail readers, such as Mutt, are not capable
|
|
of automatically determining the names of your mailboxes.
|
|
\fBOfflineIMAP\fR can help these programs by writing the names
|
|
of the folders ni a format you specify. See the example
|
|
\fIofflineimap.conf\fR for details.
|
|
.TP
|
|
\fBCan I synchronize multiple accounts with OfflineIMAP?\fR
|
|
Sure. Just name them all in the
|
|
\fIaccounts\fR line in the \fIgeneral\fR
|
|
section of the configuration file, and add a per-account section
|
|
for each one.
|
|
.TP
|
|
\fBDoes OfflineIMAP support POP?\fR
|
|
No. POP is not robust enough to do a completely reliable
|
|
multi-machine synchronization like \fBOfflineIMAP\fR can do. \fBOfflineIMAP\fR
|
|
will not support it.
|
|
.TP
|
|
\fBDoes OfflineIMAP support mailbox formats other than Maildir?\fR
|
|
Not at present. There is no technical reason not to; just no
|
|
demand yet. Maildir is a superior format anyway.
|
|
.TP
|
|
\fB[technical] Why are your Maildir message filenames so huge?\fR
|
|
\fBOfflineIMAP\fR 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, \fBOfflineIMAP\fR
|
|
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, \fBOfflineIMAP\fR must store both a UID folder ID. The folder ID is
|
|
necessary so \fBOfflineIMAP\fR can detect a message moved to a different
|
|
folder. \fBOfflineIMAP\fR stores the UID (U= number) and an md5sum of the
|
|
foldername (FMD5= number) to facilitate this.
|
|
.TP
|
|
\fBWhat is the speed of OfflineIMAP's sync?\fR
|
|
OfflineIMAP
|
|
versions 2.0 and above contain a multithreaded system. A good way to
|
|
experiment is by setting \fImaxsyncaccounts\fR to 3 and \fImaxconnections\fR 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.
|
|
|
|
An informal benchmark yields these results for my setup:
|
|
.RS
|
|
.TP 0.2i
|
|
\(bu
|
|
10 minutes with MacOS X Mail.app "manual cache"
|
|
.TP 0.2i
|
|
\(bu
|
|
5 minutes with GNUS agent sync
|
|
.TP 0.2i
|
|
\(bu
|
|
20 seconds with OfflineIMAP 1.x
|
|
.TP 0.2i
|
|
\(bu
|
|
9 seconds with OfflineIMAP 2.x
|
|
.TP 0.2i
|
|
\(bu
|
|
3 seconds with OfflineIMAP 3.x "cold start"
|
|
.TP 0.2i
|
|
\(bu
|
|
2 seconds with OfflineIMAP 3.x "held connection"
|
|
.RE
|
|
.SH "CONFORMING TO"
|
|
.TP 0.2i
|
|
\(bu
|
|
Internet Message Access Protocol version 4rev1 (IMAP 4rev1) as
|
|
specified in RFC2060
|
|
.TP 0.2i
|
|
\(bu
|
|
CRAM-MD5 as specified in RFC2195
|
|
.TP 0.2i
|
|
\(bu
|
|
Maildir as specified in
|
|
the Maildir manpage <URL:http://www.qmail.org/qmail-manual-html/man5/maildir.html> and
|
|
the qmail website <URL:http://cr.yp.to/proto/maildir.html>.
|
|
.TP 0.2i
|
|
\(bu
|
|
Standard Python 2.2.1 as implemented on POSIX-compliant systems.
|
|
.SH "NOTES"
|
|
.SS "DELETING LOCAL FOLDERS"
|
|
.PP
|
|
\fBOfflineIMAP\fR 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 \fBOfflineIMAP\fR, remember to also remove your local status
|
|
cache (\fI~/.offlineimap\fR by default). Otherwise, \fBOfflineIMAP\fR 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)
|
|
.SS "MULTIPLE INSTANCES"
|
|
.PP
|
|
\fBOfflineIMAP\fR 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 \fBOfflineIMAP\fR is already running. If you need
|
|
to schedule synchronizations, please use the
|
|
\fIautorefresh\fR settings rather than cron.
|
|
Alternatively, you can set a separate \fImetadata\fR
|
|
directory for each instance.
|
|
.SS "COPYING MESSAGES BETWEEN FOLDERS"
|
|
.PP
|
|
Normally, when you copy a message between folders or add a new message
|
|
to a folder locally, \fBOfflineIMAP\fR
|
|
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, \fBOfflineIMAP\fR
|
|
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.
|
|
\fBOfflineIMAP\fR makes sure that the message was properly uploaded before deleting it,
|
|
so there should be no risk of data loss.
|
|
.SS "USE WITH EVOLUTION"
|
|
.PP
|
|
\fBOfflineIMAP\fR can work with Evolution. To do so, first configure
|
|
your \fBOfflineIMAP\fR account to have
|
|
\fBsep = /\fR 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
|
|
\fBinside\fR your \fBOfflineIMAP\fR storage location.
|
|
You're now set!
|
|
.SS "USE WITH KMAIL"
|
|
.PP
|
|
At this time, I believe that \fBOfflineIMAP\fR 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 \fBOfflineIMAP\fR.
|
|
.SS "MAILING LIST"
|
|
.PP
|
|
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.
|
|
.SS "BUGS"
|
|
.PP
|
|
Reports of bugs should be sent via e-mail to the
|
|
\fBOfflineIMAP\fR bug-tracking system (BTS) at
|
|
offlineimap@bugs.complete.org or submitted online using
|
|
the web interface <URL:http://bugs.complete.org/>.
|
|
.PP
|
|
The Web site also lists all current bugs, where you can check their
|
|
status or contribute to fixing them.
|
|
.SH "COPYRIGHT"
|
|
.PP
|
|
OfflineIMAP, and this manual, are Copyright (C) 2002, 2003 John Goerzen.
|
|
.PP
|
|
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.
|
|
.PP
|
|
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.
|
|
.PP
|
|
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
|
|
.PP
|
|
imaplib.py comes from the Python dev tree and is licensed under
|
|
the GPL-compatible PSF license as stated in the file
|
|
\fICOPYRIGHT\fR in the \fBOfflineIMAP\fR
|
|
distribution.
|
|
.SH "AUTHOR"
|
|
.PP
|
|
\fBOfflineIMAP\fR, its libraries, documentation, and all included files, except where
|
|
noted, was written by John Goerzen <jgoerzen@complete.org> and
|
|
copyright is held as stated in the COPYRIGHT section.
|
|
.PP
|
|
\fBOfflineIMAP\fR may be downloaded, and information found, from its
|
|
homepage via either Gopher <URL:gopher://quux.org/1/devel/offlineimap>
|
|
or HTTP <URL:http://quux.org/devel/offlineimap>.
|
|
.PP
|
|
\fBOfflineIMAP\fR 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
|
|
complete.org Subversion page <URL:http://svn.complete.org/>.
|
|
.SH "SEE ALSO"
|
|
.PP
|
|
\fBmutt\fR(1),
|
|
\fBpython\fR(1)
|