850 lines
28 KiB
Groff
850 lines
28 KiB
Groff
.\" Hey, EMACS: -*- nroff -*-
|
|
.\" First parameter, NAME, should be all caps
|
|
.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
|
|
.\" other parameters are allowed: see man(7), man(1)
|
|
.TH OFFLINEIMAP 1 "July 12, 2002" "John Goerzen" "OfflineIMAP manual"
|
|
.\" Please adjust this date whenever revising the manpage.
|
|
.\"
|
|
.\" Some roff macros, for reference:
|
|
.\" .nh disable hyphenation
|
|
.\" .hy enable hyphenation
|
|
.\" .ad l left justify
|
|
.\" .ad b justify to both left and right margins
|
|
.\" .nf disable filling
|
|
.\" .fi enable filling
|
|
.\" .br insert line break
|
|
.\" .sp <n> insert n+1 empty lines
|
|
.\" for manpage-specific macros, see man(7)
|
|
.SH NAME
|
|
OfflineIMAP \- Powerful IMAP/Maildir synchronization and reader support
|
|
.SH SYNOPSIS
|
|
.B offlineimap
|
|
[
|
|
.BI \-1
|
|
]
|
|
[
|
|
.BI \-P \ profiledir
|
|
]
|
|
[
|
|
.BI \-a \ accountlist
|
|
]
|
|
[
|
|
.BI \-c \ configfile
|
|
]
|
|
.\".br
|
|
[
|
|
.BI \-d \ debugtype[,debugtype...]
|
|
]
|
|
[
|
|
.BI \-o
|
|
]
|
|
[
|
|
.BI \-u " interface"
|
|
]
|
|
|
|
.\".RI [ -c \ foo ]
|
|
.\".RI [ options ] " files" ...
|
|
.br
|
|
.B offlineimap
|
|
.B \-h
|
|
|
|
|
.B \-\-help
|
|
.\".RI [ options ] " files" ...
|
|
.SH DESCRIPTION
|
|
.B OfflineIMAP
|
|
is a tool to simplify your e-mail reading. With
|
|
.B OfflineIMAP,
|
|
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.
|
|
.B OfflineIMAP
|
|
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
|
|
.B OfflineIMAP
|
|
is
|
|
.I FAST;
|
|
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,
|
|
.B OfflineIMAP
|
|
features a multi-threaded synchronization algorithm that can
|
|
dramatically speed up performance in many situations by synchronizing
|
|
several different things simultaneously.
|
|
.PP
|
|
.B OfflineIMAP
|
|
is
|
|
.I FLEXIBLE;
|
|
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
|
|
.B OfflineIMAP
|
|
is
|
|
.I SAFE;
|
|
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
|
|
.B OfflineIMAP
|
|
pre-release, development, and beta releases.
|
|
.SS "METHOD OF OPERATION"
|
|
.B OfflineIMAP
|
|
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.
|
|
.B OfflineIMAP
|
|
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 INSTALLATION
|
|
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 OfflineIMAP from
|
|
.UR http://quux.org/devel/offlineimap/
|
|
http://quux.org/devel/offlineimap/.
|
|
.UE
|
|
.SS PREREQUISITES
|
|
In order to use OfflineIMAP, you need to have these conditions
|
|
satisfied:
|
|
.IP \(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.
|
|
.IP \(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
|
|
.UR http://www.python.org/
|
|
http://www.python.org/.
|
|
.UE
|
|
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.
|
|
.IP \(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
|
|
OfflineIMAP.
|
|
.SS DEBIAN SYSTEM-WIDE INSTALLATION
|
|
If you are tracking Debian unstable, you may install
|
|
.B OfflineIMAP
|
|
by simply running the following command as root:
|
|
.PP
|
|
.B apt-get install offlineimap
|
|
.PP
|
|
If you are not tracking Debian unstable, download the Debian .deb
|
|
package from the OfflineIMAP website
|
|
and then run
|
|
.B dpkg -i
|
|
to install the downloaded package. Then, go to CONFIGURATION below.
|
|
You will type
|
|
.B offlineimap
|
|
to invoke the program.
|
|
.SS OTHER SYSTEM-WIDE INSTALLATION
|
|
Download the tar.gz version of the package from the website. Then run
|
|
these commands:
|
|
.PP
|
|
.B tar -zxvf offlineimap-x.y.z.tar.gz
|
|
.br
|
|
.B cd offlineimap-x.y.z
|
|
.br
|
|
.B python2.2 setup.py
|
|
.PP
|
|
Some systems will need to use
|
|
.B python
|
|
instead of
|
|
.B python2.2.
|
|
Next, proceed to configuration. You will type
|
|
.B offlineimap
|
|
to invoke the program.
|
|
.SS SINGLE-ACCOUNT INSTALLATION
|
|
Download the tar.gz version of the package from the website. Then run
|
|
these commands:
|
|
.PP
|
|
.B tar -zxvf offlineimap-x.y.z.tar.gz
|
|
.br
|
|
.B cd offlineimap-x.y.z
|
|
.PP
|
|
When you want to run
|
|
.B OfflineIMAP,
|
|
you will issue the
|
|
.B cd
|
|
command as above and then type
|
|
.B ./offlineimap.py;
|
|
there is no installation step necessary.
|
|
.\"##################################################
|
|
.SH CONFIGURATION
|
|
.B OfflineIMAP
|
|
is regulated by a configuration file that is normally stored in
|
|
.I ~/.offlineimaprc.
|
|
.B OfflineIMAP
|
|
ships with a file named
|
|
.I offlineimap.conf
|
|
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
|
|
.B OfflineIMAP.
|
|
Full documentation for the configuration file is included within the
|
|
sample file.
|
|
.\"##################################################
|
|
.\" TeX users may be more comfortable with the \fB<whatever>\fP and
|
|
.\" \fI<whatever>\fP escape sequences to invode bold face and italics,
|
|
.\" respectively.
|
|
.\"\fBofflineimap\fP is a program that...
|
|
.SH OPTIONS
|
|
Most configuration is done via the configuration file. Nevertheless,
|
|
there are a few options that you may set for
|
|
.B OfflineIMAP.
|
|
.TP
|
|
.B \-1
|
|
Disable all multithreading operations and use solely a single-thread
|
|
sync. This effectively sets the
|
|
.B maxsyncaccounts
|
|
and all
|
|
.B maxconnections
|
|
configuration file variables to 1.
|
|
.TP
|
|
.BI \-P \ profiledir
|
|
Sets
|
|
.B OfflineIMAP
|
|
into profile mode. The program will create
|
|
.B profiledir
|
|
(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
|
|
.B \-1
|
|
option when you use
|
|
.B -P.
|
|
|
|
.TP
|
|
.BI \-a \ accountlist
|
|
Overrides the
|
|
.B 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.
|
|
.TP
|
|
.BI \-c \ configfile
|
|
Specifies a configuration file to use in lieu of the default,
|
|
.I ~/.offlineimaprc.
|
|
.TP
|
|
.BI \-d \ debugtype[,debugtype...]
|
|
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
|
|
.BI \-1
|
|
in order to make the results more sensible.
|
|
.IP
|
|
-d now requires one or more debugtypes, separated by commas. These
|
|
define what exactly will be debugged, and so far include two options:
|
|
.B imap
|
|
and
|
|
.B maildir.
|
|
The
|
|
.B 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
|
|
.B maildir
|
|
option will enable debugging for certain Maildir operations.
|
|
.TP
|
|
.B \-o
|
|
Run only once, ignoring any autorefresh setting in the config file.
|
|
.TP
|
|
.B \-h, \-\-help
|
|
Show summary of options.
|
|
.TP
|
|
.BI \-u \ interface
|
|
Specifies an alternative user interface module to use. This overrides
|
|
the default specified in the configuration file. The UI specified
|
|
with
|
|
.B -u
|
|
will be forced to be used, even if its
|
|
.B isuable()
|
|
method states that it cannot be. Use this option with care.
|
|
The pre-defined options are listed in the USER INTERFACES section.
|
|
.SH USER INTERFACES
|
|
.B OfflineIMAP
|
|
has a pluggable user interface system that lets you choose how the
|
|
program communicates information to you. There are two graphical
|
|
interfaces, one terminal interface, and two noninteractive interfaces
|
|
suitable for scripting or logging purposes. The
|
|
.I ui
|
|
option in the configuration file specifies the user interface
|
|
preferences. The
|
|
.I \-u
|
|
command-line option can override the configuration file. The
|
|
available values for the configuration file or command-line are
|
|
describef in this section.
|
|
.SS Tk.Blinkenlights
|
|
This is an interface designed to be sleek, fun to watch, and
|
|
informative of the overall picture of what
|
|
.B OfflineIMAP
|
|
is doing. I consider it to be the best general-purpose interface in
|
|
.B OfflineIMAP.
|
|
Tk.Blinkenlights contains, by default, a small window with a row of
|
|
LEDs 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. There is also an optional, toggable, log that 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
|
|
.I offlineimap.conf
|
|
for more details.
|
|
.PP
|
|
Each light in the Tk.Blinkenlights interface represents a thread of
|
|
execution -- that is, a particular task that
|
|
.B OfflineIMAP
|
|
is performing right now. The color indicates what task the particular
|
|
thread is performing, and are as follows:
|
|
.TP
|
|
.B Black
|
|
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
|
|
.B Red (Meaning 1)
|
|
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
|
|
.I 2001.
|
|
.TP
|
|
.B Gray
|
|
indicates that the thread is establishing a new connection to the IMAP
|
|
server.
|
|
.TP
|
|
.B Purple
|
|
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
|
|
.B Cyan
|
|
indicates that the thread is syncing a folder.
|
|
.TP
|
|
.B Green
|
|
means that a folder's message list is being loaded.
|
|
.TP
|
|
.B Blue
|
|
is the color of a message synchronization controller thread.
|
|
.TP
|
|
.B Orange
|
|
indicates that an actual message is being copied.
|
|
.TP
|
|
.B Red (Meaning 2)
|
|
indicates that a message is being deleted.
|
|
.TP
|
|
.B Yellow
|
|
(bright orange) indicates that message flags are being added.
|
|
.TP
|
|
.B Pink
|
|
(bright red) indicates that message flags are being removed.
|
|
.TP
|
|
.B Red / Black Flashing
|
|
corresponds to the countdown timer that runs between synchronizations.
|
|
.PP
|
|
The name of this interface derives from a bit of computer science
|
|
history. Eric Raymond's
|
|
.I Jargon File
|
|
defines blinkenlights, in part, as:
|
|
.PP
|
|
.RS
|
|
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
|
|
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
|
|
.B ACHTUNG! ALLES LOOKENSPEEPERS!
|
|
.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.
|
|
.SS Tk.VerboseUI
|
|
This interface (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
|
|
This interface is the default for people running in terminals. It
|
|
prints out basic status messages, has an interruptible timer like the
|
|
graphical interfaces do, and is generally friendly to use on a console
|
|
or xterm.
|
|
.SS Noninteractive.Basic
|
|
This interface is designed for situations where
|
|
.B OfflineIMAP
|
|
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
|
|
This interface 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.
|
|
.\".TP
|
|
.\".B \-v, \-\-version
|
|
.\"Show version of program.
|
|
.\"**********************************************************************
|
|
.SH EXAMPLES
|
|
Here is an example configuration for a particularly complex situation;
|
|
more examples will be added later.
|
|
.\"********************
|
|
.SS MULTIPLE ACCOUNTS WITH MUTT
|
|
This example shows you how to set up
|
|
.B OfflineIMAP
|
|
to synchronize multiple accounts with the mutt mail reader.
|
|
|
|
Start by creating a directory to hold your folders:
|
|
.br
|
|
.B mkdir ~/Mail
|
|
|
|
In your
|
|
.I ~/.offlineimaprc,
|
|
specify this:
|
|
.br
|
|
.B accounts = Personal, Work
|
|
|
|
Make sure that you have both a
|
|
.B [Personal]
|
|
and a
|
|
.B [Work]
|
|
section, with different localfolder pathnames and enable
|
|
.B [mbnames].
|
|
|
|
In each account section, do something like this:
|
|
.br
|
|
.B localfolders = ~/Mail/Personal
|
|
|
|
Add these lines to your
|
|
.I ~/.muttrc:
|
|
.br
|
|
.B source ~/path-to-mbnames-muttrc-mailboxes
|
|
.br
|
|
.B folder-hook Personal set from="youremail@personal.com"
|
|
.br
|
|
.B folder-hook Work set from="youremail@work.com"
|
|
.br
|
|
.B set mbox_type=Maildir
|
|
.br
|
|
.B set folder=$HOME/Mail
|
|
.br
|
|
.B set spoolfile=+Personal/INBOX
|
|
|
|
That's it!
|
|
.\"********************
|
|
.SS UW-IMAPD AND REFERENCES
|
|
Some users with a UW-IMAPD server need to use
|
|
.B OfflineIMAP'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 reference of Mail, a nametrans that strips
|
|
the leading Mail/ off incoming folder names, and a folderfilter that
|
|
limits the folders synced to just three.
|
|
|
|
.B [Gerf]
|
|
.br
|
|
.B localfolders = ~/Mail
|
|
.br
|
|
.B remotehost = gerf.org
|
|
.br
|
|
.B ssl = yes
|
|
.br
|
|
.B remoteuser = docwhat
|
|
.br
|
|
.B reference = Mail
|
|
.br
|
|
.B # Trims off the preceeding Mail on all the folder names.
|
|
.br
|
|
.B nametrans = lambda foldername: \\\\
|
|
.br
|
|
.B " re.sub('^Mail/', '', foldername)"
|
|
.br
|
|
.B # Yeah, you have to mention the Mail dir, even though it
|
|
.br
|
|
.B # would seem intuitive that reference would trim it.
|
|
.br
|
|
.B folderfilter = lambda foldername: foldername in [
|
|
.br
|
|
.B " 'Mail/INBOX',"
|
|
.br
|
|
.B " 'Mail/list/zaurus-general',"
|
|
.br
|
|
.B " 'Mail/list/zaurus-dev',"
|
|
.br
|
|
.B " ]"
|
|
.br
|
|
.B maxconnections = 1
|
|
.br
|
|
.B holdconnectionopen = no
|
|
.\"********************
|
|
.SS PYTHONFILE CONFIGURATION FILE OPTION
|
|
You can have OfflineIMAP 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.
|
|
|
|
In \fI~/.offlineimap.rc\fP, he adds these options:
|
|
|
|
.B [general]
|
|
.br
|
|
.B pythonfile=~/.offlineimap.py
|
|
.br
|
|
.br
|
|
.B [foo]
|
|
.br
|
|
.B foldersort=mycmp
|
|
|
|
Then, the \fI~/.offlineimap.py\fP file will contain:
|
|
|
|
.B prioritized = ['INBOX', 'personal', 'announce', 'list']
|
|
|
|
.B def mycmp(x, y):
|
|
.br
|
|
.B " for prefix in prioritized:"
|
|
.br
|
|
.B " if x.startswith(prefix):"
|
|
.br
|
|
.B " return -1"
|
|
.br
|
|
.B " elif y.startswith(prefix):"
|
|
.br
|
|
.B " return +1"
|
|
.br
|
|
.B " return cmp(x, y)"
|
|
|
|
.B def test_mycmp():
|
|
.br
|
|
.B " import os, os.path"
|
|
.br
|
|
.B " folders=os.listdir(os.path.expanduser('~/data/mail/tv@hq.yok.utu.fi'))"
|
|
.br
|
|
.B " folders.sort(mycmp)"
|
|
.br
|
|
.B " print folders"
|
|
|
|
This code snippet illustrates how the \fBfoldersort\fP option can be
|
|
customized with a Python function from the \fBpythonfile\fP to always
|
|
synchronize certain folders first.
|
|
.\"**********************************************************************
|
|
.SH ERRORS
|
|
If you get one of some frequently-encountered or confusing errors,
|
|
please check this section.
|
|
.SS UID validity problem for folder
|
|
IMAP servers use a unique ID (UID) to refer to a specific message.
|
|
This number is guaranteed to be unique to a particular message
|
|
FOREVER. No other message in the same folder will ever get the same
|
|
UID. 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.
|
|
.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
|
|
.B OfflineIMAP
|
|
might still have the UIDs from the previous folder by the
|
|
same name stored.
|
|
.B OfflineIMAP
|
|
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
|
|
.I ~/Folders
|
|
and the folder with the
|
|
problem is INBOX, you'd type this:
|
|
.PP
|
|
.B rm -r ~/Folders/INBOX
|
|
.br
|
|
.B rm ~/.offlineimap/AccountName/INBOX
|
|
.PP
|
|
(replacing AccountName with the account name as specified in
|
|
.I ~/.offlineimaprc)
|
|
.PP
|
|
Next time you run
|
|
.B 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.
|
|
.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.
|
|
.B OfflineIMAP
|
|
is incompatible with such servers. Using
|
|
.B 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)
|
|
|
|
.SH OTHER FREQUENTLY ASKED QUESTIONS
|
|
There are some other FAQs that might not fit into another section of
|
|
this document, and they are enumerated here.
|
|
.TP
|
|
.B What platforms does OfflineIMAP run on?
|
|
It should run on most platforms supported by Python, which are quite a
|
|
few.
|
|
.TP
|
|
.B I'm using Mutt. Other IMAP sync programs require me to use "set maildir_trash=yes". Do I need to do that with OfflineIMAP?
|
|
No.
|
|
.B OfflineIMAP
|
|
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
|
|
.B How do I specify the names of my folders?
|
|
You do not need to.
|
|
.B OfflineIMAP
|
|
is smart enough to automatically figure out what folders are present
|
|
on the IMAP server and synchronize them. You can use the
|
|
.B folderfilter
|
|
and
|
|
.B foldertrans
|
|
configuration file options to request certain folders and rename them
|
|
as they come in if you like.
|
|
.TP
|
|
.B How can I prevent certain folders from being synced?
|
|
Use the
|
|
.B folderfilter
|
|
option in the configuration file.
|
|
.TP
|
|
.B How can I add or delete a folder?
|
|
.B OfflineIMAP
|
|
does not currently provide this feature, but if you create a new
|
|
folder on the IMAP server, it will be created locally automatically.
|
|
.TP
|
|
.B Are there any other warnings that I should be aware of?
|
|
Yes; see the NOTES section below.
|
|
.TP
|
|
.B What is the mailbox name recorder (mbnames) for?
|
|
The Mutt mail reader is not capable of automatically determining
|
|
the names of your mailboxes. OfflineIMAP can help it (or many other)
|
|
programs out be writing these names out in a format you specify. See
|
|
the example offlineimap.conf file for details.
|
|
.TP
|
|
.B Can I synchronize multiple accounts with OfflineIMAP?
|
|
Sure. Just name them all in the accounts line in the general
|
|
section of the config file, and add a per-account section for each one.
|
|
.TP
|
|
.B Does OfflineIMAP support POP?
|
|
No. POP is not robust enough to do a completely reliable
|
|
multi-machine synchronization like OfflineIMAP can do. OfflineIMAP
|
|
will not support it.
|
|
.TP
|
|
.B Do you support mailbox formats other than Maildir?
|
|
Not at present. There is no technical reason not to; just no
|
|
demand yet. Maildir is a superior format anyway.
|
|
.TP
|
|
.B [technical] Why are your Maildir message filenames so huge?
|
|
.B OfflineIMAP
|
|
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,
|
|
.B 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.
|
|
.IP
|
|
So,
|
|
.B OfflineIMAP
|
|
must store both a UID folder ID. The folder ID is
|
|
necessary so
|
|
.B OfflineIMAP
|
|
can detect a message moved to a different
|
|
folder.
|
|
.B OfflineIMAP
|
|
stores the UID (U= number) and an md5sum of the
|
|
foldername (FMD5= number) to facilitate this.
|
|
.TP
|
|
.B What is the speed of OfflineIMAP's sync?
|
|
.B 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.
|
|
.IP
|
|
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.
|
|
.IP
|
|
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.
|
|
.IP
|
|
An informal benchmark yields these results for my setup:
|
|
.IP
|
|
10 minutes with MacOS X Mail.app "manual cache"
|
|
.br
|
|
5 minutes with GNUS agent sync
|
|
.br
|
|
20 seconds with OfflineIMAP 1.x
|
|
.br
|
|
9 seconds with OfflineIMAP 2.x
|
|
.br
|
|
3 seconds with OfflineIMAP 3.x "cold start"
|
|
.br
|
|
2 seconds with OfflineIMAP 3.x "held connection"
|
|
.SH CONFORMING TO
|
|
.IP \(bu
|
|
Internet Message Access Protocol version 4rev1 (IMAP 4rev1) as
|
|
specified in RFC2060
|
|
.IP \(bu
|
|
Maildir as specified in
|
|
.UR http://www.qmail.org/qmail-manual-html/man5/maildir.html
|
|
http://www.qmail.org/qmail-manual-html/man5/maildir.html
|
|
.UE
|
|
and
|
|
.UR http://cr.yp.to/proto/maildir.html
|
|
http://cr.yp.to/proto/maildir.html.
|
|
.UE
|
|
.IP \(bu
|
|
Standard Python 2.2.1 as implemented on POSIX-compliant systems.
|
|
.SH NOTES
|
|
.SS DELETING LOCAL FOLDERS
|
|
.B OfflineIMAP
|
|
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 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)
|
|
.SS COPYING MESSAGES BETWEEN FOLDERS
|
|
Normally, when you copy a message between folders or add a new message
|
|
to a folder locally,
|
|
.B 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,
|
|
.B 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.
|
|
.B OfflineIMAP
|
|
makes sure that the message was properly uploaded before deleting it,
|
|
so there should be no risk of data loss.
|
|
.SS MAILING LIST
|
|
There is an OfflineIMAP mailing list available.
|
|
.PP
|
|
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.
|
|
.SH BUGS
|
|
Reports of bugs should be sent via e-mail to the
|
|
.B OfflineIMAP
|
|
bug-tracking system (BTS) at
|
|
.UR mailto:offlineimap@bugs.complete.org
|
|
offlineimap@bugs.complete.org
|
|
.UE
|
|
or submitted on-line using the Web interface at
|
|
.UR http://bugs.complete.org/
|
|
http://bugs.complete.org/.
|
|
.UE
|
|
The Web site also lists all current bugs, where you can check their
|
|
status or contribute to fixing them.
|
|
.SH COPYRIGHT
|
|
OfflineIMAP is Copyright (C) 2002 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:
|
|
.PP
|
|
Free Software Foundation, Inc.
|
|
.br
|
|
59 Temple Place
|
|
.br
|
|
Suite 330
|
|
.br
|
|
Boston, MA 02111-1307
|
|
.br
|
|
USA
|
|
.SH AUTHOR
|
|
.B OfflineIMAP,
|
|
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
|
|
OfflineIMAP may be downloaded, and information found, from its
|
|
homepage via either Gopher or HTTP:
|
|
.PP
|
|
.UR gopher://quux.org/1/devel/offlineimap
|
|
gopher://quux.org/1/devel/offlineimap
|
|
.UE
|
|
.br
|
|
.UR http://quux.org/devel/offlineimap
|
|
http://quux.org/devel/offlineimap
|
|
.UE
|
|
.PP
|
|
OfflineIMAP 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:
|
|
.PP
|
|
.UR http://svn.complete.org/
|
|
http://svn.complete.org/
|
|
.UE
|
|
.SH SEE ALSO
|
|
.BR mutt (1),
|
|
.BR python (1).
|
|
.\".BR bar (1),
|
|
.\".BR baz (1).
|
|
.\".br
|
|
.\"The programs are documented fully by
|
|
.\".IR "The Rise and Fall of a Fooish Bar" ,
|
|
.\"available via the Info system.
|
|
.\".SH AUTHOR
|
|
.\"This manual page was written by John Goerzen <jgoerzen@complete.org>,
|
|
.\"for the Debian GNU/Linux system (but may be used by others).
|