<refentryinfo>
<address><email>jgoerzen@complete.org</email></address>
<author><firstname>John</firstname><surname>Goerzen</surname></author>
- <date> $Date: 2004-07-26 10:37:45 -0500 (Mon, 26 Jul 2004) $ </date>
</refentryinfo>
<refmeta>
<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>
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;
+ <ulink url="http://software.complete.org/offlineimap/">the &OfflineIMAP;
website</ulink>.
</para>
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.2.1 or above installed.
+ 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 Tk interface, you must have Tkinter
- (python-tk) installed. If you intend to use the SSL interface, your
+ If you intend to use the SSL interface, your
Python must have been built with SSL support.
</para>
</listitem>
IMAP server and point both &OfflineIMAP; and your mail
reader at it.
</para>
+ </listitem>
</itemizedlist>
</refsect2>
</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>
+ 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.
<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>.
+ <ulink url="http://software.complete.org/offlineimap/">website</ulink>.
Then run
these commands, making sure that you are the "root" user first:
</para>
<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>.
+ <ulink url="http://software.complete.org/offlineimap/">website</ulink>.
Then run these commands:
</para>
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>
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>
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>Tk.Blinkenlights</title>
- <para>Tk.Blinkenlights is an interface designed to be sleek, fun to watch, and
+ <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>
- 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
+ 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>
- Tk.Blinkenlights is the only user interface that has configurable
- parameters; see the example <filename>offlineimap.conf</filename>
- for more details.
- </para>
<para>
Each light in the Blinkenlights interface represents a thread
of execution -- that is, a particular task that &OfflineIMAP;
</blockquote>
</refsect2>
- <refsect2>
- <title>Curses.Blinkenlights</title>
- <para>
- 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.
- </para>
- <para>Please see the Tk.Blinkenlights section above for more
- information about the colors used in this interface.
- </para>
- </refsect2>
-
- <refsect2>
- <title>Tk.VerboseUI</title>
- <para>
- 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.
- </para>
- </refsect2>
-
<refsect2>
<title>TTY.TTYUI</title>
<para>
</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>
is based on one supplied by Tommi Virtanen for this feature.
</para>
<para>
- In <filename>~/.offlineimap.rc</filename>, he adds these options:
+ In <filename>~/.offlineimaprc</filename>, he adds these options:
</para>
<programlisting>[general]
pythonfile=~/.offlineimap.py
</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>
<programlisting>rm -r ~/Folders/INBOX
-rm -r ~/.offlineimap/Account-<replaceable>AccountName</>
-rm -r ~/.offlineimap/Repository-<replaceable>RepositoryName</></programlisting>
+rm -r ~/.offlineimap/Account-<replaceable>AccountName</>/LocalStatus/INBOX
+rm -r ~/.offlineimap/Repository-<replaceable>RemoteRepositoryName</>/FolderValidity/INBOX</programlisting>
<para>
- (Of course, replace AccountName and RepositoryName
+ (Of course, replace AccountName and RemoteRepositoryName
with the names as specified
in <filename>~/.offlineimaprc</filename>).
</para>
</para>
</refsect2>
</refsect1>
- <refsect1>
- <title>Other Frequently Asked Questions</title>
- <para>There are some other FAQs that might not fit into another section
- of the document, so they are discussed here.
- </para>
-
- <variablelist>
- <varlistentry><term>What platforms does &OfflineIMAP; run on?</term>
- <listitem><para>
- It should run on most platforms supported by Python, which are quite a
- few. I do not support Windows myself, but some have made
- it work there; see the FAQ entry for that platform.
- </para></listitem>
- </varlistentry>
-
- <varlistentry><term>I'm using Mutt. Other IMAP sync programs require me to use "set maildir_trash=yes". Do I need to do that with &OfflineIMAP;?</term>
- <listitem><para>
- No. &OfflineIMAP; is smart enough to figure out message deletion without this extra
- crutch. You'll get the best results if you don't use this setting, in
- fact.
- </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
- enough to automatically figure out what folders are present
- on the IMAP server and synchronize them. You can use the
- <property>folderfilter</property> and <property>foldertrans</property>
- configuration file options to request certain folders and rename them
- as they come in if you like.
- </para></listitem>
- </varlistentry>
-
- <varlistentry><term>How can I prevent certain folders from being synced?</term>
- <listitem><para>
- Use the <property>folderfilter</property> option in the configuration file.
- </para></listitem>
- </varlistentry>
-
- <varlistentry><term>How can I add or delete a folder?</term>
- <listitem><para>
- &OfflineIMAP; does not currently provide this feature, but if you create a new
- folder on the IMAP server, it will be created locally automatically.
- </para></listitem>
- </varlistentry>
-
- <varlistentry><term>Are there any other warnings that I should be aware of?</term>
- <listitem><para>
- Yes; see the Notes section below.
- </para></listitem>
- </varlistentry>
-
- <varlistentry><term>What is the mailbox name recorder (mbnames) for?</term>
- <listitem><para>Some mail readers, such as Mutt, are not capable
- of automatically determining the names of your mailboxes.
- &OfflineIMAP; can help these programs by writing the names
- of the folders in a format you specify. See the example
- <filename>offlineimap.conf</filename> for details.
- </para></listitem>
- </varlistentry>
-
- <varlistentry><term>Can I synchronize multiple accounts with &OfflineIMAP?</term>
- <listitem><para>Sure. Just name them all in the
- <property>accounts</property> line in the <property>general</property>
- section of the configuration file, and add a per-account section
- for each one.
- </para></listitem>
- </varlistentry>
-
- <varlistentry><term>Does &OfflineIMAP; support POP?</term>
- <listitem><para>No. POP is not robust enough to do a completely reliable
- multi-machine synchronization like &OfflineIMAP; can do. &OfflineIMAP;
- will not support it.
- </para></listitem>
- </varlistentry>
-
- <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>
-
- <varlistentry><term>[technical] Why are your Maildir message filenames so huge?</term>
- <listitem><para>&OfflineIMAP; has two relevant principles: 1) never modifying your
- messages in any way and 2) ensuring 100% reliable synchronizations.
- In order to do a reliable sync, &OfflineIMAP;
- must have a way to
- uniquely identify each e-mail. Three pieces of information are
- required to do this: your account name, the folder name, and the
- message UID. The account name can be calculated from the path in
- which your messages are. The folder name can usually be as well, BUT
- some mail clients move messages between folders by simply moving the
- file, leaving the name intact.
- </para>
- <para>
- So, &OfflineIMAP; must store both a UID folder ID. The folder ID is
- necessary so &OfflineIMAP; can detect a message moved to a different
- folder. &OfflineIMAP; stores the UID (U= number) and an md5sum of the
- foldername (FMD5= number) to facilitate this.
- </para></listitem>
- </varlistentry>
-
- <varlistentry><term>What is the speed of &OfflineIMAP;'s sync?</term>
- <listitem><para>OfflineIMAP
- versions 2.0 and above contain a multithreaded system. A good way to
- experiment is by setting <property>maxsyncaccounts</property> to 3 and <property>maxconnections</property> to 3
- in each account clause.
- </para>
- <para>This lets OfflineIMAP open up multiple connections simultaneously.
- That will let it process multiple folders and messages at once. In
- most cases, this will increase performance of the sync.
- </para>
- <para>Don't set the number too high. If you do that, things might actually
- slow down as your link gets saturated. Also, too many connections can
- cause mail servers to have excessive load. Administrators might take
- unkindly to this, and the server might bog down. There are many
- variables in the optimal setting; experimentation may help.
- </para>
- <para>An informal benchmark yields these results for my setup:
- </para>
- <itemizedlist>
- <listitem><para>10 minutes with MacOS X Mail.app "manual cache"
- </para></listitem>
- <listitem><para>5 minutes with GNUS agent sync</para></listitem>
- <listitem><para>20 seconds with OfflineIMAP 1.x</para></listitem>
- <listitem><para>9 seconds with OfflineIMAP 2.x</para></listitem>
- <listitem><para>3 seconds with OfflineIMAP 3.x "cold start"</para></listitem>
- <listitem><para>2 seconds with OfflineIMAP 3.x "held connection"</para></listitem>
- </itemizedlist>
- </listitem></varlistentry>
- <varlistentry><term>Can I use &OfflineIMAP; on Windows?</term>
- <listitem><para>
- These answers have been reported by &OfflineIMAP;
- users. I do not run &OfflineIMAP; on Windows myself, so
- I can't directly address their accuracy.
- </para>
- <para>
- The basic answer is that it's possible and doesn't
- require hacking &OfflineIMAP; source code. However,
- it's not necessarily trivial. The information below is
- based in instructions submitted by Chris Walker.
- </para>
- <para>
- First, you must run &OfflineIMAP; in the <ulink
- url="http://www.cygwin.com/">Cygwin</ulink>
- environment.
- </para>
- <para>
- Next, you'll need to mount your Maildir directory in a
- special way. There is information for doing that at
- <ulink url="http://barnson.org/node/view/295"></ulink>.
- That site gives this example:
- </para>
- <programlisting>
-mount -f -s -b -o managed "d:/tmp/mail" "/home/of/mail"
- </programlisting>
- <para>
- That URL also has more details on making OfflineIMAP
- work with Windows.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
<refsect1>
<title>Conforming To</title>
<itemizedlist>
<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, please use the
- <property>autorefresh</property> settings rather than cron.
+ 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>
</para>
</refsect2>
- <refsect2>
- <title>Use with Evolution</title>
- <para>&OfflineIMAP; can work with Evolution. To do so, first configure
- your &OfflineIMAP; account to have
- <option>sep = /</option> in its configuration. Then, configure
- Evolution with the
- "Maildir-format mail directories" server type. For the path, you will need to
- specify the name of the top-level folder
- <emphasis>inside</emphasis> your &OfflineIMAP; storage location.
- You're now set!
- </para>
- </refsect2>
-
- <refsect2>
- <title>Use with KMail</title>
- <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;.
- </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>
<refsect2>
<title>Mailing List</title>
<refsect2>
<title>Bugs</title>
- <para>Reports of bugs should be sent via e-mail to the
- &OfflineIMAP; mailing list at offlineimap at complete
- dot org. Debian users are encouraged to instead use the
+ <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>
<refsect1>
<title>Copyright</title>
- <para>OfflineIMAP, and this manual, are Copyright © 2002, 2003 John Goerzen.</para>
+ <para>OfflineIMAP, and this manual, are Copyright © 2002 - 2006 John Goerzen.</para>
<para>
This program is free software; you can redistribute it and/or modify
<para>
&OfflineIMAP; may be downloaded, and information found, from its
- homepage via either <ulink url="gopher://quux.org/1/devel/offlineimap">Gopher</ulink>
- or <ulink url="http://quux.org/devel/offlineimap">HTTP</ulink>.
- </para>
-
- <para>
- &OfflineIMAP; may also be downloaded using Subversion. Additionally,
- the distributed tar.gz may be updated with a simple "svn update"
- command; it is ready to go. For information on getting OfflineIMAP
- with Subversion, please visit the
- <ulink url="http://svn.complete.org/">complete.org Subversion page</ulink>.
+ <ulink url="http://software.complete.org/offlineimap">homepage</ulink>.
</para>
</refsect1>