Removed generated docs from source tree
This commit is contained in:
commit
19de4ee59d
1872
manual.html
1872
manual.html
File diff suppressed because it is too large
Load Diff
BIN
manual.pdf
BIN
manual.pdf
Binary file not shown.
691
manual.txt
691
manual.txt
@ -1,691 +0,0 @@
|
||||
OFFLINEIMAP(1) OfflineIMAP Manual OFFLINEIMAP(1)
|
||||
|
||||
|
||||
|
||||
NAME
|
||||
OfflineIMAP - Powerful IMAP/Maildir synchronization and reader support
|
||||
|
||||
SYNOPSIS
|
||||
offlineimap [ -1 ] [ -P profiledir ] [ -a accountlist ] [ -c configfile
|
||||
] [ -d debugtype[,...] ] [ -l filename ] [ -o ] [ -u interface ]
|
||||
|
||||
|
||||
offlineimap -h | --help
|
||||
|
||||
|
||||
DESCRIPTION
|
||||
OfflineIMAP is a tool to simplify your e-mail reading. With
|
||||
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. 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.
|
||||
|
||||
OfflineIMAP is FAST; it synchronizes my two accounts with over 50 fold-
|
||||
ers 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, OfflineIMAP features a multi-threaded synchro-
|
||||
nization algorithm that can dramatically speed up performance in many
|
||||
situations by synchronizing several different things simultaneously.
|
||||
|
||||
OfflineIMAP is FLEXIBLE; you can customize which folders are synced via
|
||||
regular expressions, lists, or Python expressions; a versatile and com-
|
||||
prehensive 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 sup-
|
||||
ported; and esoteric IMAP features are supported to ensure compatibil-
|
||||
ity with the widest variety of IMAP servers.
|
||||
|
||||
OfflineIMAP is SAFE; it uses an algorithm designed to prevent mail loss
|
||||
at all costs. Because of the design of this algorithm, even program-
|
||||
ming 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 OfflineIMAP pre-release, development, and beta releases. Of course,
|
||||
legally speaking, OfflineIMAP comes with no warranty, so I am not
|
||||
responsible if this turns out to be wrong.
|
||||
|
||||
METHOD OF OPERATION
|
||||
OfflineIMAP 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.
|
||||
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.
|
||||
|
||||
With OfflineIMAP 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 OfflineIMAP and their mail reader of choice at it. This
|
||||
is often preferable to the mail reader's own IMAP support since
|
||||
OfflineIMAP supports many features (offline reading, for one) that most
|
||||
IMAP-aware readers don't. However, this feature is not as time-tested
|
||||
as traditional syncing, so my advice is to stick with normal methods of
|
||||
operation for the time being.
|
||||
|
||||
QUICK START
|
||||
If you have already installed OfflineIMAP system-wide, or your system
|
||||
administrator has done that for you, your task for setting up
|
||||
OfflineIMAP for the first time is quite simple. You just need to set
|
||||
up your configuration file, make your folder directory, and run it!
|
||||
|
||||
You can quickly set up your configuration file. The distribution
|
||||
includes a file offlineimap.conf.minimal (Debian users may find this at
|
||||
/usr/share/doc/offlineimap/examples/offlineimap.conf.minimal) that is a
|
||||
basic example of setting of OfflineIMAP. You can simply copy this file
|
||||
into your home directory and name it .offlineimaprc (note the leading
|
||||
period). A command such as cp offlineimap.conf.minimal
|
||||
~/.offlineimaprc will do it. Or, if you prefer, you can just copy this
|
||||
text to ~/.offlineimaprc:
|
||||
|
||||
[general]
|
||||
accounts = Test
|
||||
|
||||
[Account Test]
|
||||
localrepository = Local
|
||||
remoterepository = Remote
|
||||
|
||||
[Repository Local]
|
||||
type = Maildir
|
||||
localfolders = ~/Test
|
||||
|
||||
[Repository Remote]
|
||||
type = IMAP
|
||||
remotehost = examplehost
|
||||
remoteuser = jgoerzen
|
||||
|
||||
Now, edit the ~/.offlineimaprc file with your favorite editor. All you
|
||||
have to do is specify a directory for your folders to be in (on the
|
||||
localfolders line), the host name of your IMAP server (on the remote-
|
||||
host line), and your login name on the remote (on the remoteuser line).
|
||||
That's it!
|
||||
|
||||
To run OfflineIMAP, you just have to say offlineimap -- it will fire
|
||||
up, ask you for a login password if necessary, synchronize your fold-
|
||||
ers, 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 OfflineIMAP FIVE TIMES FASTER FOR JUST $19.95 (err, well, $0),
|
||||
you have to read on!
|
||||
|
||||
INSTALLATION
|
||||
If you are reading this document via the "man" command, it is likely
|
||||
that you have no installation tasks to perform; your system administra-
|
||||
tor 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 the OfflineIMAP
|
||||
website <URL:http://software.complete.org/offlineimap/>.
|
||||
|
||||
PREREQUISITES
|
||||
In order to use OfflineIMAP, you need to have these conditions satis-
|
||||
fied:
|
||||
|
||||
o Your mail server must support IMAP. Most Internet Service Providers
|
||||
and corporate networks do, and most operating systems have an IMAP
|
||||
implementation readily available.
|
||||
|
||||
o 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.
|
||||
|
||||
o 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. If you do not have a mail reader that supports
|
||||
Maildir, you can often install a local IMAP server and point both
|
||||
OfflineIMAP and your mail reader at it.
|
||||
|
||||
SYSTEM-WIDE INSTALLATION, DEBIAN
|
||||
If you are tracking Debian unstable, you may install OfflineIMAP by
|
||||
simply running the following command as root:
|
||||
|
||||
apt-get install offlineimap
|
||||
|
||||
If you are not tracking Debian unstable, download the Debian .deb pack-
|
||||
age from the OfflineIMAP website <URL:http://software.com-
|
||||
plete.org/offlineimap/> and then run dpkg -i to install the downloaded
|
||||
package. Then, skip to [XRef to CONFIGURATION] below. You will type
|
||||
offlineimap to invoke the program.
|
||||
|
||||
SYSTEM-WIDE INSTALLATION, OTHER
|
||||
Download the tar.gz version of the package from the website
|
||||
<URL:http://software.complete.org/offlineimap/>. Then run these com-
|
||||
mands, making sure that you are the "root" user first:
|
||||
|
||||
tar -zxvf offlineimap_x.y.z.tar.gz
|
||||
cd offlineimap-x.y.z
|
||||
python2.2 setup.py install
|
||||
|
||||
On some systems, you will need to use python instead of python2.2.
|
||||
Next, proceed to [XRef to CONFIGURATION] below. You will type
|
||||
offlineimap to invoke the program.
|
||||
|
||||
SINGLE-ACCOUNT INSTALLATION
|
||||
Download the tar.gz version of the package from the website
|
||||
<URL:http://software.complete.org/offlineimap/>. Then run these com-
|
||||
mands:
|
||||
|
||||
tar -zxvf offlineimap_x.y.z.tar.gz
|
||||
cd offlineimap-x.y.z
|
||||
|
||||
When you want to run OfflineIMAP, you will issue the cd command as
|
||||
above and then type ./offlineimap.py; there is no installation step
|
||||
necessary.
|
||||
|
||||
CONFIGURATION
|
||||
OfflineIMAP is regulated by a configuration file that is normally
|
||||
stored in ~/.offlineimaprc. OfflineIMAP ships with a file named
|
||||
offlineimap.conf that you should copy to that location and then edit.
|
||||
This file is vital to proper operation of the system; it sets every-
|
||||
thing you need to run OfflineIMAP. Full documentation for the configu-
|
||||
ration file is included within the sample file.
|
||||
|
||||
OfflineIMAP also ships a file named offlineimap.conf.minimal 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
|
||||
offlineimap.conf.
|
||||
|
||||
OPTIONS
|
||||
Most configuration is done via the configuration file. Nevertheless,
|
||||
there are a few command-line options that you may set for OfflineIMAP.
|
||||
|
||||
-1 Disable most multithreading operations and use solely a single-
|
||||
connection sync. This effectively sets the maxsyncaccounts and
|
||||
all maxconnections configuration file variables to 1.
|
||||
|
||||
-P profiledir
|
||||
Sets OfflineIMAP into profile mode. The program will create
|
||||
profiledir (it must not already exist). As it runs, Python pro-
|
||||
filing information about each thread is logged into profiledir.
|
||||
Please note: This option is present for debugging and optimiza-
|
||||
tion only, and should NOT be used unless you have a specific
|
||||
reason to do so. It will significantly slow program perfor-
|
||||
mance, may reduce reliability, and can generate huge amounts of
|
||||
data. You must use the -1 option when you use -P.
|
||||
|
||||
-a accountlist
|
||||
Overrides the accounts option in the general section of the con-
|
||||
figuration 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.
|
||||
|
||||
-c configfile
|
||||
Specifies a configuration file to use in lieu of the default,
|
||||
~/.offlineimaprc.
|
||||
|
||||
-d 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 -1 to make
|
||||
the results more sensible.
|
||||
|
||||
-d requires one or more debugtypes, separated by commas. These
|
||||
define what exactly will be debugged, and include three options:
|
||||
imap, maildir, and thread. The imap option will enable IMAP
|
||||
protocol stream and parsing debugging. Note that the output may
|
||||
contain passwords, so take care to remove that from the debug-
|
||||
ging output before sending it to anyone else. The maildir
|
||||
option will enable debugging for certain Maildir operations.
|
||||
And thread will debug the threading model.
|
||||
|
||||
-l filename
|
||||
Enables logging to filename. This will log everything that goes
|
||||
to the screen to the specified file. Additionally, if any
|
||||
debugging is specified with -d, then debug messages will not go
|
||||
to the screen, but instead to the logfile only.
|
||||
|
||||
-o Run only once, ignoring all autorefresh settings in the configu-
|
||||
ration file.
|
||||
|
||||
-h
|
||||
|
||||
--help Show summary of options.
|
||||
|
||||
-u interface
|
||||
Specifies an alternative user interface module to use. This
|
||||
overrides the default specified in the configuration file. The
|
||||
pre-defined options are listed in the User Interfaces section.
|
||||
|
||||
USER INTERFACES
|
||||
OfflineIMAP has a pluggable user interface system that lets you choose
|
||||
how the program communicates information to you. There are two graphi-
|
||||
cal interfaces, two terminal interfaces, and two noninteractive inter-
|
||||
faces suitable for scripting or logging purposes. The ui option in the
|
||||
configuration file specifies user interface preferences. The -u com-
|
||||
mand-line option can override the configuration file setting. The
|
||||
available values for the configuration file or command-line are
|
||||
described in this section.
|
||||
|
||||
TK.BLINKENLIGHTS
|
||||
Tk.Blinkenlights is an interface designed to be sleek, fun to watch,
|
||||
and informative of the overall picture of what OfflineIMAP is doing. I
|
||||
consider it to be the best general-purpose interface in OfflineIMAP.
|
||||
|
||||
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.
|
||||
|
||||
Tk.Blinkenlights is the only user interface that has configurable
|
||||
parameters; see the example offlineimap.conf for more details.
|
||||
|
||||
Each light in the Blinkenlights interface represents a thread of execu-
|
||||
tion -- that is, a particular task that OfflineIMAP is performing right
|
||||
now. The colors indicate what task the particular thread is perform-
|
||||
ing, and are as follows:
|
||||
|
||||
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.
|
||||
|
||||
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 2001.
|
||||
|
||||
Gray indicates that the thread is establishing a new connection to
|
||||
the IMAP server.
|
||||
|
||||
Purple is the color of an account synchronization thread that is moni-
|
||||
toring the progress of the folders in that account (not generat-
|
||||
ing any I/O).
|
||||
|
||||
Cyan indicates that the thread is syncing a folder.
|
||||
|
||||
Green means that a folder's message list is being loaded.
|
||||
|
||||
Blue is the color of a message synchronization controller thread.
|
||||
|
||||
Orange indicates that an actual message is being copied. (We use fuch-
|
||||
sia for fake messages.)
|
||||
|
||||
Red (meaning 2)
|
||||
indicates that a message is being deleted.
|
||||
|
||||
Yellow / bright orange
|
||||
indicates that message flags are being added.
|
||||
|
||||
Pink / bright red
|
||||
indicates that message flags are being removed.
|
||||
|
||||
Red / Black Flashing
|
||||
corresponds to the countdown timer that runs between synchro-
|
||||
nizations.
|
||||
|
||||
The name of this interfaces derives from a bit of computer history.
|
||||
Eric Raymond's Jargon File defines blinkenlights, in part, as:
|
||||
|
||||
|
||||
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.
|
||||
|
||||
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:
|
||||
|
||||
ACHTUNG! ALLES LOOKENSPEEPERS!
|
||||
|
||||
Das computermachine ist nicht fuer gefingerpoken und mitten-
|
||||
grabben. 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.
|
||||
|
||||
CURSES.BLINKENLIGHTS
|
||||
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.
|
||||
|
||||
Please see the Tk.Blinkenlights section above for more information
|
||||
about the colors used in this interface.
|
||||
|
||||
TK.VERBOSEUI
|
||||
Tk.VerboseUI (formerly known as Tk.TkUI) is a graphical interface that
|
||||
presents a variable-sized window. In the window, each currently-exe-
|
||||
cuting thread has a section where its name and current status are dis-
|
||||
played. This interface is best suited to people running on slower con-
|
||||
nections, as you get a lot of detail, but for fast connections, the
|
||||
detail may go by too quickly to be useful. People with fast connec-
|
||||
tions may wish to use Tk.Blinkenlights instead.
|
||||
|
||||
TTY.TTYUI
|
||||
TTY.TTYUI interface is for people running in basic, non-color termi-
|
||||
nals. It prints out basic status messages and is generally friendly to
|
||||
use on a console or xterm.
|
||||
|
||||
NONINTERACTIVE.BASIC
|
||||
Noninteractive.Basic is designed for situations in which 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 auto-
|
||||
matically 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.
|
||||
|
||||
NONINTERACTIVE.QUIET
|
||||
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.
|
||||
|
||||
EXAMPLES
|
||||
Here are some example configurations for various situations. Please e-
|
||||
mail any other examples you have that may be useful to me.
|
||||
|
||||
MULTIPLE ACCOUNTS WITH MUTT
|
||||
This example shows you how to set up OfflineIMAP to synchronize multi-
|
||||
ple accounts with the mutt mail reader.
|
||||
|
||||
Start by creating a directory to hold your folders by running mkdir
|
||||
~/Mail. Then, in your ~/.offlineimaprc, specify:
|
||||
|
||||
accounts = Personal, Work
|
||||
|
||||
Make sure that you have both an [Account Personal] and an [Account
|
||||
Work] section. The local repository for each account must have differ-
|
||||
ent localfolder path names. Also, make sure to enable [mbnames].
|
||||
|
||||
In each local repository section, write something like this:
|
||||
|
||||
localfolders = ~/Mail/Personal
|
||||
|
||||
Finally, add these lines to your ~/.muttrc:
|
||||
|
||||
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
|
||||
|
||||
That's it!
|
||||
|
||||
UW-IMAPD AND REFERENCES
|
||||
Some users with a UW-IMAPD server need to use OfflineIMAP'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 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.
|
||||
|
||||
[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
|
||||
|
||||
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 ~/.offlineimap.rc, he adds these options:
|
||||
|
||||
[general]
|
||||
pythonfile=~/.offlineimap.py
|
||||
[Repository foo]
|
||||
foldersort=mycmp
|
||||
|
||||
Then, the ~/.offlineimap.py file will contain:
|
||||
|
||||
prioritized = ['INBOX', 'personal', 'announce', 'list']
|
||||
|
||||
def mycmp(x, y):
|
||||
for prefix in prioritized:
|
||||
xsw = x.startswith(prefix)
|
||||
ysw = y.startswith(prefix)
|
||||
if xsw and ysw:
|
||||
return cmp(x, y)
|
||||
elif xsw:
|
||||
return -1
|
||||
elif ysw:
|
||||
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
|
||||
|
||||
This code snippet illustrates how the foldersort option can be cus-
|
||||
tomized with a Python function from the pythonfile to always synchro-
|
||||
nize certain folders first.
|
||||
|
||||
ERRORS
|
||||
If you get one of some frequently-encountered or confusing errors,
|
||||
please check this section.
|
||||
|
||||
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.
|
||||
|
||||
Sometimes, the UIDs on the server might get reset. Usually this will
|
||||
happen if you delete and then recreate a folder. When you create a
|
||||
folder, the server will often start the UID back from 1. But
|
||||
OfflineIMAP might still have the UIDs from the previous folder by the
|
||||
same name stored. OfflineIMAP will detect this condition and skip the
|
||||
folder. This is GOOD, because it prevents data loss.
|
||||
|
||||
You can fix it by removing your local folder and cache data. For
|
||||
instance, if your folders are under ~/Folders and the folder with the
|
||||
problem is INBOX, you'd type this:
|
||||
|
||||
rm -r ~/Folders/INBOX
|
||||
rm -r ~/.offlineimap/Account-AccountName
|
||||
rm -r ~/.offlineimap/Repository-RepositoryName
|
||||
|
||||
(Of course, replace AccountName and RepositoryName with the names as
|
||||
specified in ~/.offlineimaprc).
|
||||
|
||||
Next time you run OfflineIMAP, it will re-download the folder with the
|
||||
new UIDs. Note that the procedure specified above will lose any local
|
||||
changes made to the folder.
|
||||
|
||||
Some IMAP servers are broken and do not support UIDs properly. If you
|
||||
continue to get this error for all your folders even after performing
|
||||
the above procedure, it is likely that your IMAP server falls into this
|
||||
category. OfflineIMAP is incompatible with such servers. Using
|
||||
OfflineIMAP with them will not destroy any mail, but at the same time,
|
||||
it will not actually synchronize it either. (OfflineIMAP will detect
|
||||
this condition and abort prior to synchronization.)
|
||||
|
||||
This question comes up frequently on the OfflineIMAP mailing list
|
||||
<URL:http://lists.complete.org/offlineimap@complete.org/>. You can
|
||||
find a detailed discussion <URL:http://lists.com-
|
||||
plete.org/offlineimap@complete.org/2003/04/msg00012.html.gz> of the
|
||||
problem there.
|
||||
|
||||
CONFORMING TO
|
||||
o Internet Message Access Protocol version 4rev1 (IMAP 4rev1) as speci-
|
||||
fied in RFC2060 and RFC3501
|
||||
|
||||
o CRAM-MD5 as specified in RFC2195
|
||||
|
||||
o 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>.
|
||||
|
||||
o Standard Python 2.2.1 as implemented on POSIX-compliant systems.
|
||||
|
||||
NOTES
|
||||
DELETING LOCAL FOLDERS
|
||||
OfflineIMAP does a two-way synchronization. That is, if you make a
|
||||
change to the mail on the server, it will be propagated to your local
|
||||
copy, and vise-versa. Some people might think that it would be wise to
|
||||
just delete all their local mail folders periodically. If you do this
|
||||
with OfflineIMAP, remember to also remove your local status cache
|
||||
(~/.offlineimap by default). Otherwise, OfflineIMAP will take this as
|
||||
an intentional deletion of many messages and will interpret your action
|
||||
as requesting them to be deleted from the server as well. (If you
|
||||
don't understand this, don't worry; you probably won't encounter this
|
||||
situation)
|
||||
|
||||
MULTIPLE INSTANCES
|
||||
OfflineIMAP is not designed to have several instances (for instance, a
|
||||
cron job and an interactive invocation) run over the same mailbox
|
||||
simultaneously. It will perform a check on startup and abort if
|
||||
another OfflineIMAP is already running. If you need to schedule syn-
|
||||
chronizations, please use the autorefresh settings rather than cron.
|
||||
Alternatively, you can set a separate metadata directory for each
|
||||
instance.
|
||||
|
||||
COPYING MESSAGES BETWEEN FOLDERS
|
||||
Normally, when you copy a message between folders or add a new message
|
||||
to a folder locally, OfflineIMAP will just do the right thing. How-
|
||||
ever, sometimes this can be tricky -- if your IMAP server does not pro-
|
||||
vide the SEARCH command, or does not return something useful,
|
||||
OfflineIMAP cannot determine the new UID of the message. So, in these
|
||||
rare instances, OfflineIMAP will upload the message to the IMAP server
|
||||
and delete it from your local folder. Then, on your next sync, the
|
||||
message will be re-downloaded with the proper UID. OfflineIMAP makes
|
||||
sure that the message was properly uploaded before deleting it, so
|
||||
there should be no risk of data loss.
|
||||
|
||||
MAILING LIST
|
||||
There is an OfflineIMAP mailing list available. To subscribe, send the
|
||||
text "Subscribe" in the subject of a mail to offlineimap-request@com-
|
||||
plete.org. To post, send the message to offlineimap@complete.org.
|
||||
Archives are available at
|
||||
<URL:http://lists.complete.org/offlineimap@complete.org/>.
|
||||
|
||||
BUGS
|
||||
Reports of bugs should be reported online at the OfflineIMAP homepage.
|
||||
Debian users are encouraged to instead use the Debian bug-tracking sys-
|
||||
tem.
|
||||
|
||||
UPGRADING TO 4.0
|
||||
If you are upgrading from a version of OfflineIMAP prior to 3.99.12,
|
||||
you will find that you will get errors when OfflineIMAP starts up
|
||||
(relating to ConfigParser or AccountHashGenerator) and the configura-
|
||||
tion file. This is because the config file format had to change to
|
||||
accommodate new features in 4.0. Fortunately, it's not difficult to
|
||||
adjust it to suit.
|
||||
|
||||
First thing you need to do is stop any running OfflineIMAP instance,
|
||||
making sure first that it's synced all your mail. Then, modify your
|
||||
~/.offlineimaprc file. You'll need to split up each account section
|
||||
(make sure that it now starts with "Account ") into two Repository sec-
|
||||
tions (one for the local side and another for the remote side.) See
|
||||
the files offlineimap.conf.minimal and offlineimap.conf in the distri-
|
||||
bution if you need more assistance.
|
||||
|
||||
OfflineIMAP's status directory area has also changed. Therefore, you
|
||||
should delete everything in ~/.offlineimap as well as your local mail
|
||||
folders.
|
||||
|
||||
When you start up OfflineIMAP 4.0, it will re-download all your mail
|
||||
from the server and then you can continue using it like normal.
|
||||
|
||||
COPYRIGHT
|
||||
OfflineIMAP, and this manual, are Copyright (C) 2002 - 2006 John
|
||||
Goerzen.
|
||||
|
||||
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.
|
||||
|
||||
This program is distributed in the hope that it will be useful, but
|
||||
WITHOUT ANY WARRANTY; without even the implied warranty of MER-
|
||||
CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
|
||||
Public License for more details.
|
||||
|
||||
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
|
||||
|
||||
imaplib.py comes from the Python dev tree and is licensed under the
|
||||
GPL-compatible PSF license as stated in the file COPYRIGHT in the
|
||||
OfflineIMAP distribution.
|
||||
|
||||
AUTHOR
|
||||
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.
|
||||
|
||||
OfflineIMAP may be downloaded, and information found, from its homepage
|
||||
<URL:http://software.complete.org/offlineimap>.
|
||||
|
||||
SEE ALSO
|
||||
mutt(1), python(1)
|
||||
|
||||
HISTORY
|
||||
Detailed history may be found in the file ChangeLog in the OfflineIMAP
|
||||
distribution. Feature and bug histories may be found in the file
|
||||
debian/changelog which, despite its name, is not really Debian-spe-
|
||||
cific. This section provides a large overview.
|
||||
|
||||
Development on OfflineIMAP began on June 18, 2002. Version 1.0.0 was
|
||||
released three days later on June 21, 2002. Point releases followed,
|
||||
including speed optimizations and some compatibility fixes.
|
||||
|
||||
Version 2.0.0 was released on July 3, 2002, and represented the first
|
||||
time the synchronization became multithreaded and, to the best of my
|
||||
knowledge, the first multithreaded IMAP syncrhonizing application in
|
||||
existance. The last 2.0.x release, 2.0.8, was made on July 9.
|
||||
|
||||
Version 3.0.0 was released on July 11, 2002, and introduced modular
|
||||
user interfaces and the first GUI interface for OfflineIMAP. This man-
|
||||
ual also was introduced with 3.0.0, along with many command-line
|
||||
options. Version 3.1.0 was released on July 21, adding the Noninterac-
|
||||
tive user interfaces, profiling support, and several bugfixes. 3.2.0
|
||||
was released on July 24, adding support for the Blinkenlights GUI
|
||||
interface. OfflineIMAP entered maintenance mode for awhile, as it had
|
||||
reached a feature-complete milestone in my mind.
|
||||
|
||||
The 3.99.x branch began in on October 7, 2002, to begin work for 4.0.
|
||||
The Curses.Blinkenlights interface was added in 3.99.6, and many archi-
|
||||
tectural changes were made.
|
||||
|
||||
4.0.0 was released on July 18, 2003, including the ability to synchro-
|
||||
nize directly between two IMAP servers, the first re-architecting of
|
||||
the configuration file to refine the notion of an account, and the new
|
||||
Curses interface.
|
||||
|
||||
|
||||
|
||||
John Goerzen 01 December 2006 OFFLINEIMAP(1)
|
803
offlineimap.1
803
offlineimap.1
@ -1,803 +0,0 @@
|
||||
.\" 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" "01 December 2006" "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-l \fIfilename\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 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. \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.
|
||||
.PP
|
||||
With \fBOfflineIMAP\fR 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 \fBOfflineIMAP\fR and their mail reader
|
||||
of choice at it. This is often preferable to the mail
|
||||
reader's own IMAP support since \fBOfflineIMAP\fR supports many
|
||||
features (offline reading, for one) that most IMAP-aware
|
||||
readers don't. However, this feature is not as time-tested
|
||||
as traditional syncing, so my advice is to stick with normal
|
||||
methods of operation for the time being.
|
||||
.SH "QUICK START"
|
||||
.PP
|
||||
If you have already installed \fBOfflineIMAP\fR system-wide,
|
||||
or your system administrator 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
|
||||
|
||||
[Account Test]
|
||||
localrepository = Local
|
||||
remoterepository = Remote
|
||||
|
||||
[Repository Local]
|
||||
type = Maildir
|
||||
localfolders = ~/Test
|
||||
|
||||
[Repository Remote]
|
||||
type = IMAP
|
||||
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://software.complete.org/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\&. If you do not have a mail reader
|
||||
that supports Maildir, you can often install a local
|
||||
IMAP server and point both \fBOfflineIMAP\fR and your mail
|
||||
reader at it.
|
||||
.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://software.complete.org/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://software.complete.org/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://software.complete.org/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 "CONFIGURATION"
|
||||
.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 three options: \fIimap\fR,
|
||||
\fImaildir\fR, and \fIthread\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. And \fIthread\fR
|
||||
will debug the threading model.
|
||||
.TP
|
||||
\fB-l \fIfilename\fB\fR
|
||||
Enables logging to filename. This will log everything
|
||||
that goes to the screen to the specified file.
|
||||
Additionally, if any debugging is specified with -d,
|
||||
then debug messages will not go to the screen, but
|
||||
instead to the logfile only.
|
||||
.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 default 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 fuchsia 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 an
|
||||
\fI[Account Personal]\fR
|
||||
and an \fI[Account Work]\fR section. The
|
||||
local repository for each account must have different
|
||||
\fIlocalfolder\fR path names.
|
||||
Also, make sure
|
||||
to enable \fI[mbnames]\fR\&.
|
||||
.PP
|
||||
In each local repository 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 (originally 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
|
||||
[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
|
||||
.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
|
||||
[Repository 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:
|
||||
xsw = x.startswith(prefix)
|
||||
ysw = y.startswith(prefix)
|
||||
if xsw and ysw:
|
||||
return cmp(x, y)
|
||||
elif xsw:
|
||||
return -1
|
||||
elif ysw:
|
||||
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/Account-\fIAccountName\fR
|
||||
rm -r ~/.offlineimap/Repository-\fIRepositoryName\fR
|
||||
.fi
|
||||
.PP
|
||||
(Of course, replace AccountName and RepositoryName
|
||||
with the names 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.)
|
||||
.PP
|
||||
This question comes up frequently on the
|
||||
\fBOfflineIMAP\fR
|
||||
mailing list <URL:http://lists.complete.org/offlineimap@complete.org/>\&. You can find a
|
||||
detailed
|
||||
discussion <URL:http://lists.complete.org/offlineimap@complete.org/2003/04/msg00012.html.gz> of the problem there.
|
||||
.SH "CONFORMING TO"
|
||||
.TP 0.2i
|
||||
\(bu
|
||||
Internet Message Access Protocol version 4rev1 (IMAP 4rev1) as
|
||||
specified in RFC2060 and RFC3501
|
||||
.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 propagated to your
|
||||
local copy, and vise-versa. Some people might think that it would be
|
||||
wise to just delete all their local mail folders periodically. If you
|
||||
do this with \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 "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. Archives are available at
|
||||
<URL:http://lists.complete.org/offlineimap@complete.org/>\&.
|
||||
.SS "BUGS"
|
||||
.PP
|
||||
Reports of bugs should be reported online at the
|
||||
\fBOfflineIMAP\fR homepage.
|
||||
Debian users are encouraged to instead use the
|
||||
Debian
|
||||
bug-tracking system.
|
||||
.SH "UPGRADING TO 4.0"
|
||||
.PP
|
||||
If you are upgrading from a version of \fBOfflineIMAP\fR prior to
|
||||
3.99.12, you will find that you will get errors when
|
||||
\fBOfflineIMAP\fR starts up (relating to ConfigParser or
|
||||
AccountHashGenerator) and the
|
||||
configuration file. This is because the config file format
|
||||
had to change to accommodate new features in 4.0. Fortunately,
|
||||
it's not difficult to adjust it to suit.
|
||||
.PP
|
||||
First thing you need to do is stop any running \fBOfflineIMAP\fR
|
||||
instance, making sure first that it's synced all your mail.
|
||||
Then, modify your
|
||||
\fI~/.offlineimaprc\fR file. You'll need to
|
||||
split up each account section (make sure that it now starts
|
||||
with "Account ") into two Repository sections (one for the
|
||||
local side and another for the remote side.) See the files
|
||||
\fIofflineimap.conf.minimal\fR and
|
||||
\fIofflineimap.conf\fR in the distribution if
|
||||
you need more assistance.
|
||||
.PP
|
||||
\fBOfflineIMAP\fR\&'s status directory area has also changed.
|
||||
Therefore, you should delete everything in ~/.offlineimap as
|
||||
well as your local mail folders.
|
||||
.PP
|
||||
When you start up \fBOfflineIMAP\fR 4.0, it will re-download all
|
||||
your mail from the server and then you can continue using it
|
||||
like normal.
|
||||
.SH "COPYRIGHT"
|
||||
.PP
|
||||
OfflineIMAP, and this manual, are Copyright (C) 2002 - 2006 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 <URL:http://software.complete.org/offlineimap>\&.
|
||||
.SH "SEE ALSO"
|
||||
.PP
|
||||
\fBmutt\fR(1),
|
||||
\fBpython\fR(1)
|
||||
.SH "HISTORY"
|
||||
.PP
|
||||
Detailed history may be found in the file ChangeLog in the
|
||||
\fBOfflineIMAP\fR distribution. Feature and bug histories may be
|
||||
found in the file debian/changelog which, despite its name, is
|
||||
not really Debian-specific. This section provides a large
|
||||
overview.
|
||||
.PP
|
||||
Development on \fBOfflineIMAP\fR began on June 18, 2002. Version
|
||||
1.0.0 was released three days later on June 21, 2002. Point
|
||||
releases followed, including speed optimizations and some
|
||||
compatibility fixes.
|
||||
.PP
|
||||
Version 2.0.0 was released on July 3, 2002, and
|
||||
represented the first time the synchronization became
|
||||
multithreaded and, to the best of my knowledge, the first
|
||||
multithreaded IMAP syncrhonizing application in existance.
|
||||
The last 2.0.x release, 2.0.8, was made on July 9.
|
||||
.PP
|
||||
Version 3.0.0 was released on July 11, 2002, and introduced
|
||||
modular user interfaces and the first GUI interface for
|
||||
\fBOfflineIMAP\fR\&. This manual also was introduced with 3.0.0,
|
||||
along with many command-line options. Version 3.1.0 was
|
||||
released on July 21, adding the Noninteractive user
|
||||
interfaces, profiling support, and several bugfixes. 3.2.0
|
||||
was released on July 24, adding support for the Blinkenlights
|
||||
GUI interface. \fBOfflineIMAP\fR entered maintenance mode for
|
||||
awhile, as it had reached a feature-complete milestone in my
|
||||
mind.
|
||||
.PP
|
||||
The 3.99.x branch began in on October 7, 2002, to begin work
|
||||
for 4.0. The Curses.Blinkenlights interface was added in
|
||||
3.99.6, and many architectural changes were made.
|
||||
.PP
|
||||
4.0.0 was released on July 18, 2003, including the ability to
|
||||
synchronize directly between two IMAP servers, the first
|
||||
re-architecting of the configuration file to refine the
|
||||
notion of an account, and the new Curses interface.
|
Loading…
Reference in New Issue
Block a user