OfflineIMAP

<!DOCTYPE reference PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [

  <!ENTITY OfflineIMAP "<application>OfflineIMAP</application>">

]>

<!--      "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>

    </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>-f <replaceable>foldername[,...]</replaceable></arg>

        <arg>-k <replaceable>[section:]option=value</replaceable></arg>

	<arg>-l <replaceable>filename</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; 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.

        </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>

    <refsect1>

      <title>Quick Start</title>

      <para>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!

      </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

[Account Test]

localrepository = Local

remoterepository = Remote

[Repository Local]

type = Maildir

localfolders = ~/Test

[Repository Remote]

type = IMAP

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://software.complete.org/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.

              A special <property>Gmail</property> mailbox type is

              available to interface with Gmail's IMAP front-end.

	    </para>

	  </listitem>

	  <listitem>

	    <para>

	      You must have Python version 2.4 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 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;.  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>

	  </listitem>

	</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://software.complete.org/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://software.complete.org/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://software.complete.org/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">Configuration</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>Options</title>

      <para>

	Most configuration is done via the configuration file.  Nevertheless,

	there are a few command-line options that you may set for

	&OfflineIMAP;.

      </para>

      <variablelist>

        <varlistentry><term>-1</term>

          <listitem><para>Disable most multithreading operations and use

	    solely a single-connection

	    sync.  This effectively sets the

	      <property>maxsyncaccounts</property>

	    and all <property>maxconnections</property> configuration file

	    variables to 1.

	  </para></listitem>

	</varlistentry>

	<varlistentry><term>-P <replaceable>profiledir</replaceable></term>

	  <listitem><para>Sets &OfflineIMAP; into profile mode.  The program

	    will create <replaceable>profiledir</replaceable>

	    (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 <option>-1</option> option when

	    you use <option>-P</option>.

	  </para></listitem>

	</varlistentry>

	<varlistentry><term>-a <replaceable>accountlist</replaceable></term>

	  <listitem><para>Overrides the <property>accounts</property> option

	    in the <property>general</property> 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.

	  </para></listitem>

	</varlistentry>

	<varlistentry><term>-c <replaceable>configfile</replaceable></term>

	  <listitem><para>Specifies a configuration file to use in lieu of

	    the default, <filename>~/.offlineimaprc</filename>.

	  </para></listitem>

	</varlistentry>

	<varlistentry><term>-d <replaceable>debugtype[,...]</replaceable></term>

	  <listitem><para>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

	    <option>-1</option> to make the results more sensible.</para>

	    <para><option>-d</option> requires one or more debugtypes,

	      separated by commas.  These define what exactly will be

	      debugged, and include three options: <property>imap</property>,

	      <property>maildir</property>, and <property>thread</property>.

	      The <property>imap</property>

	      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

	      <property>maildir</property> option will enable debugging for

	      certain Maildir operations.  And <property>thread</property>

	      will debug the threading model.

	    </para></listitem>

	  </varlistentry>

        <varlistentry><term>-f <replaceable>foldername</replaceable>[,<replaceable>foldername</replaceable>]</term>

          <listitem><para> Only sync the specified folders.  The

              <replaceable>foldername</replaceable>s are the

              untranslated foldernames.  This command-line option

              overrides any <property>folderfilter</property>

              and <property>folderincludes</property> options in the

              configuration file.

          </para></listitem>

        </varlistentry>

        <varlistentry><term>-k [<replaceable>section</replaceable>:]<replaceable>option</replaceable>=<replaceable>value</replaceable>

          </term>

          <listitem><para> Override configuration file option.  If

              "section" is omitted, it defaults

              to <property>general</property>.  Any underscores "_" in

              the section name are replaced with spaces: for instance,

              to override option <property>autorefresh</property> in

              the "[Account Personal]" section in the config file one

              would use "-k Account_Personal:autorefresh=30".

          </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

	      file.</para>

	    </listitem>

	  </varlistentry>

	  <varlistentry><term>-q</term>

	    <listitem><para>Run only quick synchronizations.   Ignore any flag

              updates on IMAP servers.</para>

	    </listitem>

	  </varlistentry>

	  <varlistentry><term>-h</term> <term>--help</term>

	    <listitem><para>Show summary of options.</para></listitem>

	  </varlistentry>

	  <varlistentry><term>-u <replaceable>interface</replaceable></term>

	    <listitem><para>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.</para>

	    </listitem>

	  </varlistentry>

      </variablelist>

    </refsect1>

    <refsect1>

      <title>User Interfaces</title>

      <para>&OfflineIMAP; 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

	<property>ui</property> option in the configuration file specifies

	user interface preferences.  The <option>-u</option> command-line

	option can override the configuration file setting.  The available

	values for the configuration file or command-line are described

	in this section.</para>

      <refsect2>

	<title>Curses.Blinkenlights</title>

	<para>

                Curses.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;.

	</para>

	<para>

	  Curses.Blinkenlights contains a row of

          "LEDs" with command buttons and a log.

	  The  log shows more

	  detail about what is happening and is color-coded to match the color

	  of the lights.

	</para>

	<para>

	  Each light in the Blinkenlights interface represents a thread

	  of execution -- that is, a particular task that &OfflineIMAP;

	  is performing right now.  The colors indicate what task

	  the particular thread is performing, and are as follows:

	</para>

	<variablelist>

	  <varlistentry>

	    <term>Black</term>

	    <listitem><para>indicates that this light's thread has terminated; it will light up

	      again later when new threads start up.  So, black indicates no

	      activity.

	    </para></listitem>

	  </varlistentry>

	  <varlistentry>

	    <term>Red (Meaning 1)</term>

	    <listitem><para>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

	      <citation>2001</citation>.

	    </para></listitem>

	  </varlistentry>

	  <varlistentry>

	    <term>Gray</term>

	    <listitem><para>indicates that the thread is establishing a new connection to the IMAP

	      server.

	    </para></listitem>

	  </varlistentry>

	  <varlistentry>

	    <term>Purple</term>

	    <listitem><para>is the color of an account synchronization thread that is monitoring

	      the progress of the folders in that account (not generating any I/O).

	    </para></listitem>

	  </varlistentry>

	  <varlistentry>

	    <term>Cyan</term>

	    <listitem><para>indicates that the thread is syncing a folder.

	    </para></listitem>

	  </varlistentry>

	  <varlistentry>

	    <term>Green</term>

	    <listitem><para>means that a folder's message list is being loaded.

	    </para></listitem>

	  </varlistentry>

	  <varlistentry>

	    <term>Blue</term>

	    <listitem><para>is the color of a message synchronization controller thread.

	    </para></listitem>

	  </varlistentry>

	  <varlistentry>

	    <term>Orange</term>

	    <listitem><para>indicates that an actual message is being copied.

	      (We use fuchsia for fake messages.)

	    </para></listitem>

	  </varlistentry>

	  <varlistentry>

	    <term>Red (meaning 2)</term>

	    <listitem><para>indicates that a message is being deleted.

	    </para></listitem>

	  </varlistentry>

	  <varlistentry>

	    <term>Yellow / bright orange</term>

	    <listitem><para>indicates that message flags are being added.

	    </para></listitem>

	  </varlistentry>

	  <varlistentry>

	    <term>Pink / bright red</term>

	    <listitem><para>indicates that message flags are being removed.

	    </para></listitem>

	  </varlistentry>

	  <varlistentry>

	    <term>Red / Black Flashing</term>

	    <listitem><para>corresponds to the countdown timer that runs between

	      synchronizations.

	    </para></listitem>

	  </varlistentry>

	</variablelist>

	<para>The name of this interfaces derives from a bit of computer

	  history.  Eric Raymond's <citation>Jargon File</citation> defines

	  <firstterm>blinkenlights</firstterm>, in part, as:

	</para>

	<blockquote>

	  <para>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.

	  </para>

	  <para>

	    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:

	  </para>

	  <para>

	    <emphasis>ACHTUNG!  ALLES LOOKENSPEEPERS!</emphasis>

	  </para>

	  <para>

	    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.

	  </para>

	</blockquote>

      </refsect2>

      <refsect2>

	<title>TTY.TTYUI</title>

	<para>

	  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.

	</para>

      </refsect2>

      <refsect2>

	<title>Noninteractive.Basic</title>

	<para>

	  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

	  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.

	</para>

      </refsect2>

      <refsect2>

	<title>Noninteractive.Quiet</title>

	<para>

	  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.

	</para>

      </refsect2>

      <refsect2>

        <title>Machine.MachineUI</title>

        <para>

           Machine.MachineUI generates output in a machine-parsable format.

           It is designed for other programs that will interface

           to OfflineIMAP.

        </para>

      </refsect2>

    </refsect1>

    <refsect1>

      <title>Examples</title>

      <para>Here are some example configurations for various situations.

	Please e-mail any other examples you have that may be useful to

	me.

      </para>

      <refsect2>

	<title>Multiple Accounts with Mutt</title>

	<para>

	  This example shows you how to set up &OfflineIMAP; to

	  synchronize multiple accounts with the mutt mail reader.

	</para>

	<para>

	  Start by creating a directory to hold your folders by running

	  <command>mkdir ~/Mail</command>.  Then, in your

	  <filename>~/.offlineimaprc</filename>, specify:

	</para>

	<programlisting>accounts = Personal, Work</programlisting>

	<para>

	  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 local repository section, write something like this:

	</para>

	<programlisting>localfolders = ~/Mail/Personal</programlisting>

	<para>

	  Finally, add these lines to your <filename>~/.muttrc</filename>:

	</para>

	<programlisting>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</programlisting>

	<para>

	  That's it!

	</para>

      </refsect2>

      <refsect2>

	<title>UW-IMAPD and References</title>

	<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 (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>[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</programlisting>

      </refsect2>

      <refsect2>

	<title>pythonfile Configuration File Option</title>

	<para>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.

	</para>

	<para>

	  In <filename>~/.offlineimaprc</filename>, he adds these options:

	</para>

	<programlisting>[general]

pythonfile=~/.offlineimap.py

[Repository foo]

foldersort=mycmp</programlisting>

	<para>

	  Then, the <filename>~/.offlineimap.py</filename> file will

	  contain:

	</para>

	<programlisting>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</programlisting>

	<para>

	  This code snippet illustrates how the <property>foldersort</property>

	  option can be customized with a Python function from the

	  <property>pythonfile</property> to always synchronize certain

	  folders first.

	</para>

      </refsect2>

    </refsect1>

    <refsect1>

            <title>Signals</title>

            <para>

                    OfflineIMAP writes its current PID into

                    <filename>~/.offlineimap/pid</filename> when it is

                    running.  It is not guaranteed that this file will

                    not exist when OfflineIMAP is not running.

            </para>

            <!-- not done yet 

            <para>

                    You can send SIGINT to OfflineIMAP using this file to

                    kill it.  SIGUSR1 will force an immediate resync of

                    all accounts.  This will be ignored for all accounts

                    for which a resync is already in progress.

            </para>

            -->

    </refsect1>

    <refsect1>

      <title>Errors</title>

      <para>

	If you get one of some frequently-encountered or confusing errors,

	please check this section.

      </para>

      <refsect2>

	<title>UID validity problem for folder</title>

	<para>IMAP servers use a unique ID (UID) to refer to a specific message.

	  This number is guaranteed to be unique to a particular message

	  <emphasis>forever</emphasis>.

	  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.

	</para>

	<para>

	  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.

	</para>

	<para>

	  You can fix it by removing your local folder and cache data.  For

	  instance, if your folders are under <filename>~/Folders</filename>

	  and the folder with the problem is INBOX, you'd type this:

	</para>

	<programlisting>rm -r ~/Folders/INBOX

rm -r ~/.offlineimap/Account-<replaceable>AccountName</>/LocalStatus/INBOX

rm -r ~/.offlineimap/Repository-<replaceable>RemoteRepositoryName</>/FolderValidity/INBOX</programlisting>

	<para>

	  (Of course, replace AccountName and RemoteRepositoryName 

	  with the names as specified

	  in <filename>~/.offlineimaprc</filename>).

	</para>

	<para>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.

	</para>

	<para>

	  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.)

	</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>

      <title>Conforming To</title>

      <itemizedlist>

	<listitem><para>Internet Message Access Protocol version 4rev1 (IMAP 4rev1) as

	  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

	  <ulink url="http://cr.yp.to/proto/maildir.html">the qmail website</ulink>.</para></listitem>

	<listitem><para>Standard Python 2.2.1 as implemented on POSIX-compliant systems.</para></listitem>

      </itemizedlist>

    </refsect1>

    <refsect1>

      <title>Notes</title>

      <refsect2>

	<title>Deleting Local Folders</title>

	<para>&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 (<filename>~/.offlineimap</filename> 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.)

	</para>

      </refsect2>

      <refsect2>

	<title>Multiple Instances</title>

	<para>&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 synchronizations, you'll probably find

	  <property>autorefresh</property> settings more convenient than cron.

	  Alternatively, you can set a separate <property>metadata</property>

	  directory for each instance.

	</para>

      </refsect2>

      <refsect2>

	<title>Copying Messages Between Folders</title>

	<para>

	  Normally, when you copy a message between folders or add a new message

	  to a folder locally, &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, &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.

	</para>

      </refsect2>

      <refsect2>

	<title>Mailing List</title>

	<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.  Archives are available at

	  <ulink url="http://lists.complete.org/offlineimap@complete.org/"></>.

	</para>

      </refsect2>

      <refsect2>

	<title>Bugs</title>

	<para>

          Reports of bugs should be reported online at the

          &OfflineIMAP; homepage.

          Debian users are encouraged to instead use the

	Debian

          bug-tracking system.

	</para>

      </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 accommodate 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>