293 lines
11 KiB
Plaintext
293 lines
11 KiB
Plaintext
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
|
|
<!ENTITY OfflineIMAP "<application>OfflineIMAP</application>">
|
|
]>
|
|
<!-- -*- DocBook -*- -->
|
|
<!-- "file:///usr/share/sgml/docbook/dtd/xml/4.2/docbookx.dtd"> -->
|
|
|
|
<reference>
|
|
<title>OfflineIMAP Manual</title>
|
|
|
|
<refentry>
|
|
<refentryinfo>
|
|
<address><email>jgoerzen@complete.org</email></address>
|
|
<author><firstname>John</firstname><surname>Goerzen</surname></author>
|
|
<date>$Date$</date>
|
|
</refentryinfo>
|
|
|
|
<refmeta>
|
|
<refentrytitle>offlineimap</refentrytitle>
|
|
<manvolnum>1</manvolnum>
|
|
<refmiscinfo>John Goerzen</refmiscinfo>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>OfflineIMAP</refname>
|
|
<refpurpose>Powerful IMAP/Maildir synchronization
|
|
and reader support</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<cmdsynopsis>
|
|
<command>offlineimap</command>
|
|
<arg>-1</arg>
|
|
<arg>-P <replaceable>profiledir</replaceable></arg>
|
|
<arg>-a <replaceable>accountlist</replaceable></arg>
|
|
<arg>-c <replaceable>configfile</replaceable></arg>
|
|
<arg>-d <replaceable>debugtype[,...]</replaceable></arg>
|
|
<arg>-o</arg>
|
|
<arg>-u <replaceable>interface</replaceable></arg>
|
|
</cmdsynopsis>
|
|
<cmdsynopsis>
|
|
<command>offlineimap</command>
|
|
<group choice="plain"><arg>-h</arg><arg>--help</arg></group>
|
|
</cmdsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>&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.
|
|
</para>
|
|
|
|
<para>&OfflineIMAP; is <emphasis>FAST</emphasis>; 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, &OfflineIMAP; features a
|
|
multi-threaded synchronization algorithm that can dramatically
|
|
speed up performance in many situations by synchronizing
|
|
several different things simultaneously.
|
|
</para>
|
|
|
|
<para>&OfflineIMAP; is <emphasis>FLEXIBLE</emphasis>; 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.
|
|
</para>
|
|
|
|
<para>&OfflineIMAP; is <emphasis>SAFE</emphasis>; 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 &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.
|
|
</para>
|
|
|
|
<refsect2>
|
|
<title>Method of Operation</title>
|
|
|
|
<para>&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. &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.
|
|
</para>
|
|
</refsect2>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Quick Start</title>
|
|
<para>If you have already installed &OfflineIMAP; system-wide,
|
|
or your system adminstrator 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!
|
|
</para>
|
|
|
|
<para>You can quickly set up your configuration file. The distribution
|
|
includes a file <filename>offlineimap.conf.minimal</filename>
|
|
(Debian users
|
|
may find this at
|
|
<filename>/usr/share/doc/offlineimap/examples/offlineimap.conf.minimal</filename>) that is a basic example of setting of &OfflineIMAP;. You can
|
|
simply copy this file into your home directory and name it
|
|
<filename>.offlineimaprc</filename> (note the leading period). A
|
|
command such as <command>cp offlineimap.conf.minimal ~/.offlineimaprc</command> will do it. Or, if you prefer, you can just copy this text to
|
|
<filename>~/.offlineimaprc</filename>:
|
|
</para>
|
|
|
|
<PROGRAMLISTING>[general]
|
|
accounts = Test
|
|
|
|
[Test]
|
|
localfolders = ~/Test
|
|
remotehost = examplehost
|
|
remoteuser = jgoerzen
|
|
</PROGRAMLISTING>
|
|
|
|
<para>Now, edit the <filename>~/.offlineimaprc</filename> file with
|
|
your favorite editor. All you have to do is specify a directory
|
|
for your folders to be in (on the <property>localfolders</property>
|
|
line), the host name of your IMAP server (on the
|
|
<property>remotehost</property> line), and your login name on
|
|
the remote (on the <property>remoteuser</property> line). That's
|
|
it!</para>
|
|
|
|
<para>To run &OfflineIMAP;, you just have to say
|
|
<command>offlineimap</command> -- 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 &OfflineIMAP; FIVE TIMES FASTER FOR JUST $19.95 (err, well,
|
|
$0), you have to read on!
|
|
</para>
|
|
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Installation</title>
|
|
|
|
<para>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
|
|
<ulink url="http://quux.org/devel/offlineimap/">the &OfflineIMAP;
|
|
website</ulink>.
|
|
</para>
|
|
|
|
<refsect2>
|
|
<title>Prerequisites</title>
|
|
|
|
<para>In order to use &OfflineIMAP;, you need to have these conditions
|
|
satisfied:
|
|
</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Your mail server must support IMAP. Most Internet Service
|
|
Providers
|
|
and corporate networks do, and most operating systems
|
|
have an IMAP
|
|
implementation readily available.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
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
|
|
<ulink url="http://www.python.org/">the Python website</ulink>.
|
|
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.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
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;.
|
|
</itemizedlist>
|
|
</refsect2>
|
|
|
|
<refsect2>
|
|
<title>System-Wide Installation, Debian</title>
|
|
<para>
|
|
If you are tracking Debian unstable, you may install
|
|
&OfflineIMAP; by simply running the following command as root:
|
|
</para>
|
|
<para>
|
|
<command>apt-get install offlineimap</command>
|
|
</para>
|
|
<para>
|
|
If you are not tracking Debian unstable, download the Debian .deb
|
|
package from the <ulink url="http://quux.org/devel/offlineimap/">&OfflineIMAP; website</ulink>
|
|
and then run <command>dpkg -i</command> to install the downloaded
|
|
package. Then, skip to <xref linkend="configuration" endterm="configuration-title"> below. You will type <command>offlineimap</command> to
|
|
invoke the program.
|
|
</para>
|
|
</refsect2>
|
|
|
|
<refsect2>
|
|
<title>System-Wide Installation, Other</title>
|
|
<para>
|
|
Download the tar.gz version of the package from the
|
|
<ulink url="http://quux.org/devel/offlineimap/">website</ulink>.
|
|
Then run
|
|
these commands, making sure that you are the "root" user first:
|
|
</para>
|
|
|
|
<ProgramListing>tar -zxvf offlineimap_x.y.z.tar.gz
|
|
cd offlineimap-x.y.z
|
|
python2.2 setup.py install</ProgramListing>
|
|
<para>On some systems, you will need to use
|
|
<command>python</command> instead of <command>python2.2</command>.
|
|
Next, proceed to <xref linkend="configuration" endterm="configuration-title"> below. You will type <command>offlineimap</command> to
|
|
invoke the program.
|
|
</para>
|
|
</refsect2>
|
|
|
|
<refsect2>
|
|
<title>Single-Account Installation</title>
|
|
<para>
|
|
Download the tar.gz version of the package from the
|
|
<ulink url="http://quux.org/devel/offlineimap/">website</ulink>.
|
|
Then run these commands:
|
|
</para>
|
|
|
|
<ProgramListing>tar -zxvf offlineimap_x.y.z.tar.gz
|
|
cd offlineimap-x.y.z</ProgramListing>
|
|
|
|
<para>When you want to run &OfflineIMAP;, you will issue the
|
|
<command>cd</command> command as above and then type
|
|
<command>./offlineimap.py</command>; there is no installation
|
|
step necessary.
|
|
</para>
|
|
</refsect2>
|
|
</refsect1>
|
|
|
|
<refsect1 id="configuration">
|
|
<title id="configuration-title">Configruation</title>
|
|
<para>
|
|
&OfflineIMAP; is regulated by a configuration file that is normally
|
|
stored in <filename>~/.offlineimaprc</filename>. &OfflineIMAP;
|
|
ships with a file named <filename>offlineimap.conf</filename>
|
|
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 &OfflineIMAP;. Full documentation for the configuration file
|
|
is included within the sample file.
|
|
</para>
|
|
<para>
|
|
&OfflineIMAP; also ships a file named
|
|
<filename>offlineimap.conf.minimal</filename> 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 <filename>offlineimap.conf</filename>.
|
|
</para>
|
|
</refsect1>
|
|
|
|
|
|
|
|
<refsect1>
|
|
<title>See Also</title>
|
|
<para>This is also a test. Foo bar.</para>
|
|
</refsect1>
|
|
</refentry>
|
|
</reference>
|