<refentryinfo>
<address><email>jgoerzen@complete.org</email></address>
<author><firstname>John</firstname><surname>Goerzen</surname></author>
- <date> $Date: 2003-04-17 13:25:30 -0500 (Thu, 17 Apr 2003) $ </date>
+ <date> $Date: 2003-07-18 15:59:56 -0500 (Fri, 18 Jul 2003) $ </date>
</refentryinfo>
<refmeta>
<arg>-a <replaceable>accountlist</replaceable></arg>
<arg>-c <replaceable>configfile</replaceable></arg>
<arg>-d <replaceable>debugtype[,...]</replaceable></arg>
+ <arg>-l <replaceable>filename</replaceable></arg>
<arg>-o</arg>
<arg>-u <replaceable>interface</replaceable></arg>
</cmdsynopsis>
<refsect2>
<title>Method of Operation</title>
- <para>&OfflineIMAP; operates by maintaining a hierarchy of
+ <para>&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
computer and bi-directionally synchronize them, copying,
marking, and deleting messages as necessary.
</para>
+ <para>
+ 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.
+ </para>
</refsect2>
</refsect1>
<PROGRAMLISTING>[general]
accounts = Test
-[Test]
+[Account Test]
+localrepository = Local
+remoterepository = Remote
+
+[Repository Local]
+type = Maildir
localfolders = ~/Test
+
+[Repository Remote]
+type = IMAP
remotehost = examplehost
remoteuser = jgoerzen
</PROGRAMLISTING>
</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;.
+ 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.
+ </para>
</itemizedlist>
</refsect2>
</refsect1>
<refsect1 id="configuration">
- <title id="configuration-title">Configruation</title>
+ <title id="configuration-title">Configuration</title>
<para>
&OfflineIMAP; is regulated by a configuration file that is normally
stored in <filename>~/.offlineimaprc</filename>. &OfflineIMAP;
<varlistentry><term>-1</term>
<listitem><para>Disable most multithreading operations and use
solely a single-connection
- sync. This effectively sets the <property>maxsyncaccounts</property>
+ sync. This effectively sets the
+ <property>maxsyncaccounts</property>
and all <property>maxconnections</property> configuration file
variables to 1.
</para></listitem>
will debug the threading model.
</para></listitem>
</varlistentry>
+ <varlistentry><term>-l
+ <replaceable>filename</replaceable></term>
+ <listitem><para>
+ 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.</para>
+ </listitem>
+ </varlistentry>
<varlistentry><term>-o</term>
<listitem><para>Run only once, ignoring all
<property>autorefresh</property> settings in the configuration
</para>
<programlisting>accounts = Personal, Work</programlisting>
<para>
- Make sure that you have both a <property>[Personal]</property>
- and a <property>[Work]</property> section, each with different
- <property>localfolder</property> path names. Also, make sure
+ Make sure that you have both an
+ <property>[Account Personal]</property>
+ and an <property>[Account Work]</property> section. The
+ local repository for each account must have different
+ <property>localfolder</> path names.
+ Also, make sure
to enable <property>[mbnames]</property>.
</para>
<para>
- In each account section, write something like this:
+ In each local repository section, write something like this:
</para>
<programlisting>localfolders = ~/Mail/Personal</programlisting>
<para>
<para>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 docwhat@gerf.org
+ configuration from (originally from docwhat@gerf.org)
shows using a <property>reference</property> of Mail, a <property>nametrans</property>
that strips
the leading Mail/ off incoming folder names, and a
<property>folderfilter</property> that
limits the folders synced to just three.
</para>
- <programlisting>[Gerf]
+ <programlisting>[Account Gerf]
+localrepository = GerfLocal
+remoterepository = GerfRemote
+
+[Repository GerfLocal]
+type = Maildir
localfolders = ~/Mail
+
+[Repository GerfRemote]
+type = IMAP
remotehost = gerf.org
ssl = yes
remoteuser = docwhat
</para>
<programlisting>[general]
pythonfile=~/.offlineimap.py
-[foo]
+[Repository foo]
foldersort=mycmp</programlisting>
<para>
Then, the <filename>~/.offlineimap.py</filename> file will
</para>
<programlisting>rm -r ~/Folders/INBOX
-rm -r ~/.offlineimap/AccountName/INBOX</programlisting>
+rm -r ~/.offlineimap/Account-<replaceable>AccountName</>
+rm -r ~/.offlineimap/Repository-<replaceable>RepositoryName</></programlisting>
<para>
- (Of course, replace AccountName with the account name as specified
+ (Of course, replace AccountName and RepositoryName
+ with the names as specified
in <filename>~/.offlineimaprc</filename>).
</para>
it will not actually synchronize it either. (&OfflineIMAP; will detect
this condition and abort prior to synchronization.)
</para>
+ <para>
+ This question comes up frequently on the
+ <ulink
+ url="http://lists.complete.org/offlineimap@complete.org/">&OfflineIMAP;
+ mailing list</ulink>. You can find a
+ <ulink
+ url="http://lists.complete.org/offlineimap@complete.org/2003/04/msg00012.html.gz">detailed
+ discussion</ulink> of the problem there.
+ </para>
</refsect2>
</refsect1>
<refsect1>
</para></listitem>
</varlistentry>
+ <varlistentry><term>I've upgraded and now &OfflineIMAP;
+ crashes when I start it up! Why?</term>
+ <listitem><para>You need to upgrade your configuration
+ file. See <xref linkend="upgrading.4.0"> at the end of this
+ manual.
+ </para>
+ </listitem>
+ </varlistentry>
+
<varlistentry><term>How do I specify the names of my folders?</term>
<listitem><para>
You do not need to. &OfflineIMAP; is smart
<varlistentry><term>Does &OfflineIMAP; support mailbox formats other than Maildir?</term>
<listitem><para>Not at present. There is no technical reason not to; just no
demand yet. Maildir is a superior format anyway.
+ However, &OfflineIMAP; can sync between two IMAP
+ servers, and some IMAP servers support other formats. You
+ could install an IMAP server on your local machine and have
+ &OfflineIMAP sync to that.
</para></listitem>
</varlistentry>
<title>Conforming To</title>
<itemizedlist>
<listitem><para>Internet Message Access Protocol version 4rev1 (IMAP 4rev1) as
- specified in RFC2060</para></listitem>
+ specified in RFC2060 and RFC3501</para></listitem>
<listitem><para>CRAM-MD5 as specified in RFC2195</para></listitem>
<listitem><para>Maildir as specified in
<ulink url="http://www.qmail.org/qmail-manual-html/man5/maildir.html">the Maildir manpage</ulink> and
<refsect2>
<title>Use with KMail</title>
- <para>At this time, I believe that &OfflineIMAP; is not compatible
+ <para>At this time, I believe that &OfflineIMAP; with Maildirs
+ is not compatible
with KMail. KMail cannot work in any mode other than to move
all messages out of all folders immediately, which (besides being annoying
- and fundamentally broken) is incompatible with &OfflineIMAP;.
+ and fundamentally broken) is incompatible with
+ &OfflineIMAP;.
+ </para>
+ <para>
+ However, I have made KMail version 3 work well with
+ &OfflineIMAP; by installing an IMAP server on my local
+ machine, having &OfflineIMAP; sync to that, and pointing
+ KMail at the same server.
</para>
</refsect2>
<para>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.
+ offlineimap@complete.org. Archives are available at
+ <ulink url="http://lists.complete.org/offlineimap@complete.org/"></>.
</para>
</refsect2>
</refsect2>
</refsect1>
+ <refsect1 id="upgrading.4.0">
+ <title>Upgrading to 4.0</title>
+ <para>
+ 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
+ configuration file. This is because the config file format
+ had to change to accomodate new features in 4.0. Fortunately,
+ it's not difficult to adjust it to suit.
+ </para>
+ <para>
+ 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
+ <filename>~/.offlineimaprc</filename> 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
+ <filename>offlineimap.conf.minimal</filename> and
+ <filename>offlineimap.conf</filename> in the distribution if
+ you need more assistance.
+ </para>
+ <para>
+ &OfflineIMAP;'s status directory area has also changed.
+ Therefore, you should delete everything in ~/.offlineimap as
+ well as your local mail folders.
+ </para>
+ <para>
+ 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.
+ </para>
+ </refsect1>
+
+
<refsect1>
<title>Copyright</title>
<para>OfflineIMAP, and this manual, are Copyright © 2002, 2003 John Goerzen.</para>