code.delx.au - offlineimap/blob - offlineimap.sgml

   1 <!DOCTYPE reference PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
   2   <!ENTITY OfflineIMAP "<application>OfflineIMAP</application>">
   3 ]>
   4 <!--      "file:///usr/share/sgml/docbook/dtd/xml/4.2/docbookx.dtd"> -->
   5
   6 <reference>
   7   <title>OfflineIMAP Manual</title>
   8
   9   <refentry>
  10     <refentryinfo>
  11       <address><email>jgoerzen@complete.org</email></address>
  12       <author><firstname>John</firstname><surname>Goerzen</surname></author>
  13     </refentryinfo>
  14
  15     <refmeta>
  16       <refentrytitle>offlineimap</refentrytitle>
  17       <manvolnum>1</manvolnum>
  18       <refmiscinfo>John Goerzen</refmiscinfo>
  19     </refmeta>
  20
  21     <refnamediv>
  22       <refname>OfflineIMAP</refname>
  23       <refpurpose>Powerful IMAP/Maildir synchronization
  24         and reader support</refpurpose>
  25     </refnamediv>
  26
  27     <refsynopsisdiv>
  28       <cmdsynopsis>
  29         <command>offlineimap</command>
  30         <arg>-1</arg>
  31         <arg>-P <replaceable>profiledir</replaceable></arg>
  32         <arg>-a <replaceable>accountlist</replaceable></arg>
  33         <arg>-c <replaceable>configfile</replaceable></arg>
  34         <arg>-d <replaceable>debugtype[,...]</replaceable></arg>
  35         <arg>-f <replaceable>foldername[,...]</replaceable></arg>
  36         <arg>-k <replaceable>[section:]option=value</replaceable></arg>
  37         <arg>-l <replaceable>filename</replaceable></arg>
  38         <arg>-o</arg>
  39         <arg>-u <replaceable>interface</replaceable></arg>
  40       </cmdsynopsis>
  41       <cmdsynopsis>
  42         <command>offlineimap</command>
  43         <group choice="plain"><arg>-h</arg><arg>--help</arg></group>
  44       </cmdsynopsis>
  45     </refsynopsisdiv>
  46
  47     <refsect1>
  48       <title>Description</title>
  49
  50       <para>&OfflineIMAP; is  a  tool  to  simplify  your  e-mail
  51         reading.  With &OfflineIMAP;, you can read the same mailbox
  52         from multiple computers.  You get a current copy of your
  53         messages on each computer, and changes you make one place will be
  54         visible on all other systems.  For instance, you can delete a message
  55         on your home computer, and it will appear deleted on your work
  56         computer as well.  &OfflineIMAP; is also useful if you want to
  57         use a mail reader that does not have IMAP support, has poor IMAP
  58         support, or does not provide disconnected operation.
  59       </para>
  60
  61       <para>&OfflineIMAP; is <emphasis>FAST</emphasis>; it synchronizes
  62         my two accounts with over 50 folders in 3 seconds.  Other
  63         similar tools might take over a minute, and achieve a
  64         less-reliable result.  Some mail readers can take over 10
  65         minutes to do the same thing, and some don't even support it
  66         at all.  Unlike other mail tools, &OfflineIMAP; features a
  67         multi-threaded synchronization algorithm that can dramatically
  68         speed up performance in many situations by synchronizing
  69         several different things simultaneously.
  70       </para>
  71
  72       <para>&OfflineIMAP; is <emphasis>FLEXIBLE</emphasis>; you can
  73         customize which folders are synced via regular expressions,
  74         lists, or Python expressions; a versatile and comprehensive
  75         configuration file is used to control behavior; two user
  76         interfaces are built-in; fine-tuning of synchronization
  77         performance is possible; internal or external automation is
  78         supported; SSL and PREAUTH tunnels are both supported; offline
  79         (or "unplugged") reading is supported; and esoteric IMAP
  80         features are supported to ensure compatibility with the widest
  81         variety of IMAP servers.
  82       </para>
  83
  84       <para>&OfflineIMAP; is <emphasis>SAFE</emphasis>; it uses an
  85         algorithm designed to prevent mail loss at all costs.  Because
  86         of the design of this algorithm, even programming errors
  87         should not result in loss of mail.  I am so confident in the
  88         algorithm that I use my own personal and work accounts for
  89         testing of &OfflineIMAP; pre-release, development, and beta
  90         releases.  Of course, legally speaking, &OfflineIMAP; comes
  91         with no warranty, so I am not responsible if this turns out
  92         to be wrong.
  93       </para>
  94
  95       <refsect2>
  96         <title>Method of Operation</title>
  97
  98         <para>&OfflineIMAP; traditionally
  99           operates by maintaining a hierarchy of
 100           mail folders in Maildir format locally.  Your own mail
 101           reader will read mail from this tree, and need never know
 102           that the mail comes from IMAP.  &OfflineIMAP; will detect
 103           changes to the mail folders on your IMAP server and your own
 104           computer and bi-directionally synchronize them, copying,
 105           marking, and deleting messages as necessary.
 106         </para>
 107         <para>
 108           With &OfflineIMAP; 4.0, a powerful new ability has been
 109           introduced -- the program can now synchronize two IMAP
 110           servers with each other, with no need to have a Maildir
 111           layer in-between.  Many people use this if they use a mail
 112           reader on their local machine that does not support
 113           Maildirs.  People may install an IMAP server on their local
 114           machine, and point both &OfflineIMAP; and their mail reader
 115           of choice at it.  This is often preferable to the mail
 116           reader's own IMAP support since &OfflineIMAP; supports many
 117           features (offline reading, for one) that most IMAP-aware
 118           readers don't.  However, this feature is not as time-tested
 119           as traditional syncing, so my advice is to stick with normal
 120           methods of operation for the time being.
 121         </para>
 122       </refsect2>
 123     </refsect1>
 124
 125     <refsect1>
 126       <title>Quick Start</title>
 127       <para>If you have already installed &OfflineIMAP; system-wide,
 128         or your system administrator has done that for you, your task
 129         for setting up &OfflineIMAP; for the first time is quite
 130         simple.  You just need to set up your configuration file, make
 131         your folder directory, and run it!
 132       </para>
 133
 134         <para>You can quickly set up your configuration file.  The distribution
 135           includes a file <filename>offlineimap.conf.minimal</filename>
 136           (Debian users
 137         may find this at
 138           <filename>/usr/share/doc/offlineimap/examples/offlineimap.conf.minimal</filename>) that is a basic example of setting of &OfflineIMAP;.  You can
 139           simply copy this file into your home directory and name it
 140           <filename>.offlineimaprc</filename> (note the leading period).  A
 141           command such as <command>cp offlineimap.conf.minimal ~/.offlineimaprc</command> will do it.  Or, if you prefer, you can just copy this text to
 142           <filename>~/.offlineimaprc</filename>:
 143         </para>
 144
 145         <PROGRAMLISTING>[general]
 146 accounts = Test
 147
 148 [Account Test]
 149 localrepository = Local
 150 remoterepository = Remote
 151
 152 [Repository Local]
 153 type = Maildir
 154 localfolders = ~/Test
 155
 156 [Repository Remote]
 157 type = IMAP
 158 remotehost = examplehost
 159 remoteuser = jgoerzen
 160 </PROGRAMLISTING>
 161
 162         <para>Now, edit the <filename>~/.offlineimaprc</filename> file with
 163           your favorite editor.  All you have to do is specify a directory
 164           for your folders to be in (on the <property>localfolders</property>
 165           line), the host name of your IMAP server (on the
 166           <property>remotehost</property> line), and your login name on
 167           the remote (on the <property>remoteuser</property> line).  That's
 168           it!</para>
 169
 170         <para>To run &OfflineIMAP;, you just have to say
 171           <command>offlineimap</command> -- it will fire up, ask you for
 172           a login password if necessary, synchronize your folders, and exit.
 173           See?  You can just throw away the rest of this finely-crafted,
 174           perfectly-honed manual!  Of course, if you want to see how you can
 175           make &OfflineIMAP; FIVE TIMES FASTER FOR JUST $19.95 (err, well,
 176           $0), you have to read on!
 177         </para>
 178
 179     </refsect1>
 180
 181     <refsect1>
 182       <title>Installation</title>
 183
 184       <para>If you are reading this document via the "man" command, it is
 185         likely
 186         that you have no installation tasks to perform; your system
 187         administrator has already installed it.  If you need to install it
 188         yourself, you have three options: a system-wide installation with
 189         Debian, system-wide installation with other systems, and a single-user
 190         installation.  You can download the latest version of &OfflineIMAP; from
 191         <ulink url="http://software.complete.org/offlineimap/">the &OfflineIMAP;
 192         website</ulink>.
 193       </para>
 194
 195       <refsect2>
 196         <title>Prerequisites</title>
 197
 198         <para>In order to use &OfflineIMAP;, you need to have these conditions
 199           satisfied:
 200         </para>
 201
 202         <itemizedlist>
 203           <listitem>
 204             <para>Your mail server must support IMAP.  Most Internet Service
 205               Providers
 206               and corporate networks do, and most operating systems
 207               have an IMAP
 208               implementation readily available.
 209               A special <property>Gmail</property> mailbox type is
 210               available to interface with Gmail's IMAP front-end.
 211             </para>
 212           </listitem>
 213           <listitem>
 214             <para>
 215               You must have Python version 2.4 or above installed.
 216               If you are
 217               running on Debian GNU/Linux, this requirement will automatically be
 218               taken care of for you.  If you do not have Python already, check with
 219               your system administrator or operating system vendor; or, download it from
 220               <ulink url="http://www.python.org/">the Python website</ulink>.
 221                 If you intend to use the SSL interface, your
 222                 Python must have been built with SSL support.
 223             </para>
 224           </listitem>
 225           <listitem>
 226             <para>
 227               Have a mail reader that supports the Maildir mailbox
 228               format.  Most modern mail readers have this support
 229               built-in, so you can choose from a wide variety of mail
 230               servers.  This format is also known as the "qmail"
 231               format, so any mail reader compatible with it will work
 232               with &OfflineIMAP;.  If you do not have a mail reader
 233               that supports Maildir, you can often install a local
 234               IMAP server and point both &OfflineIMAP; and your mail
 235               reader at it.
 236             </para>
 237           </listitem>
 238         </itemizedlist>
 239       </refsect2>
 240
 241       <refsect2>
 242         <title>System-Wide Installation, Debian</title>
 243         <para>
 244           If you are tracking Debian unstable, you may install
 245           &OfflineIMAP; by simply running the following command as root:
 246         </para>
 247         <para>
 248           <command>apt-get install offlineimap</command>
 249         </para>
 250         <para>
 251           If you are not tracking Debian unstable, download the Debian .deb
 252           package from the <ulink url="http://software.complete.org/offlineimap/">&OfflineIMAP; website</ulink>
 253           and then run <command>dpkg -i</command> to install the downloaded
 254           package.  Then, skip to <xref linkend="configuration" endterm="configuration-title"> below.  You will type <command>offlineimap</command> to
 255           invoke the program.
 256         </para>
 257       </refsect2>
 258
 259       <refsect2>
 260         <title>System-Wide Installation, Other</title>
 261         <para>
 262           Download the tar.gz version of the package from the
 263           <ulink url="http://software.complete.org/offlineimap/">website</ulink>.
 264           Then run
 265           these commands, making sure that you are the "root" user first:
 266         </para>
 267
 268         <ProgramListing>tar -zxvf offlineimap_x.y.z.tar.gz
 269 cd offlineimap-x.y.z
 270 python2.2 setup.py install</ProgramListing>
 271         <para>On some systems, you will need to use
 272           <command>python</command> instead of <command>python2.2</command>.
 273           Next, proceed to <xref linkend="configuration" endterm="configuration-title"> below.  You will type <command>offlineimap</command> to
 274           invoke the program.
 275         </para>
 276       </refsect2>
 277
 278       <refsect2>
 279         <title>Single-Account Installation</title>
 280         <para>
 281           Download the tar.gz version of the package from the
 282           <ulink url="http://software.complete.org/offlineimap/">website</ulink>.
 283           Then run these commands:
 284         </para>
 285
 286         <ProgramListing>tar -zxvf offlineimap_x.y.z.tar.gz
 287 cd offlineimap-x.y.z</ProgramListing>
 288
 289         <para>When you want to run &OfflineIMAP;, you will issue the
 290           <command>cd</command> command as above and then type
 291           <command>./offlineimap.py</command>; there is no installation
 292           step necessary.
 293         </para>
 294       </refsect2>
 295     </refsect1>
 296
 297     <refsect1 id="configuration">
 298       <title id="configuration-title">Configuration</title>
 299       <para>
 300         &OfflineIMAP; is regulated by a configuration file that is normally
 301         stored in <filename>~/.offlineimaprc</filename>.  &OfflineIMAP;
 302         ships with a file named <filename>offlineimap.conf</filename>
 303         that you should copy to that location and then edit.  This file is
 304         vital to proper operation of the system; it sets everything you need
 305         to run &OfflineIMAP;.  Full documentation for the configuration file
 306         is included within the sample file.
 307       </para>
 308       <para>
 309         &OfflineIMAP; also ships a file named
 310         <filename>offlineimap.conf.minimal</filename> that you can also try.
 311           It's useful if you want to get started with
 312           the most basic feature set, and you can read about other features
 313           later with <filename>offlineimap.conf</filename>.
 314       </para>
 315     </refsect1>
 316
 317     <refsect1>
 318       <title>Options</title>
 319       <para>
 320         Most configuration is done via the configuration file.  Nevertheless,
 321         there are a few command-line options that you may set for
 322         &OfflineIMAP;.
 323       </para>
 324
 325       <variablelist>
 326         <varlistentry><term>-1</term>
 327           <listitem><para>Disable most multithreading operations and use
 328             solely a single-connection
 329             sync.  This effectively sets the
 330               <property>maxsyncaccounts</property>
 331             and all <property>maxconnections</property> configuration file
 332             variables to 1.
 333           </para></listitem>
 334         </varlistentry>
 335         <varlistentry><term>-P <replaceable>profiledir</replaceable></term>
 336           <listitem><para>Sets &OfflineIMAP; into profile mode.  The program
 337             will create <replaceable>profiledir</replaceable>
 338             (it must not already exist).  As it runs, Python profiling
 339             information
 340             about each thread is logged into profiledir.  Please note: This option
 341             is present for debugging and optimization only, and should NOT be used
 342             unless you have a specific reason to do so.  It will significantly
 343             slow program performance, may reduce reliability, and can generate
 344             huge amounts of data.  You must use the <option>-1</option> option when
 345             you use <option>-P</option>.
 346           </para></listitem>
 347         </varlistentry>
 348         <varlistentry><term>-a <replaceable>accountlist</replaceable></term>
 349           <listitem><para>Overrides the <property>accounts</property> option
 350             in the <property>general</property> section of the configuration
 351             file.  You might use this to exclude certain accounts, or to sync
 352             some accounts that you normally prefer not to.  Separate the
 353             accounts by commas, and use no embedded spaces.
 354           </para></listitem>
 355         </varlistentry>
 356         <varlistentry><term>-c <replaceable>configfile</replaceable></term>
 357           <listitem><para>Specifies a configuration file to use in lieu of
 358             the default, <filename>~/.offlineimaprc</filename>.
 359           </para></listitem>
 360         </varlistentry>
 361         <varlistentry><term>-d <replaceable>debugtype[,...]</replaceable></term>
 362           <listitem><para>Enables debugging for OfflineIMAP.  This is useful if
 363             you are trying to track down a malfunction or figure out what is going
 364             on under the hood.  I suggest that you use this with
 365             <option>-1</option> to make the results more sensible.</para>
 366
 367             <para><option>-d</option> requires one or more debugtypes,
 368               separated by commas.  These define what exactly will be
 369               debugged, and include three options: <property>imap</property>,
 370               <property>maildir</property>, and <property>thread</property>.
 371               The <property>imap</property>
 372               option will enable IMAP protocol stream and parsing debugging.  Note
 373               that the output may contain passwords, so take care to remove that
 374               from the debugging output before sending it to anyone else.  The
 375               <property>maildir</property> option will enable debugging for
 376               certain Maildir operations.  And <property>thread</property>
 377               will debug the threading model.
 378             </para></listitem>
 379           </varlistentry>
 380         <varlistentry><term>-f <replaceable>foldername</replaceable>[,<replaceable>foldername</replaceable>]</term>
 381           <listitem><para> Only sync the specified folders.  The
 382               <replaceable>foldername</replaceable>s are the
 383               untranslated foldernames.  This command-line option
 384               overrides any <property>folderfilter</property>
 385               and <property>folderincludes</property> options in the
 386               configuration file.
 387           </para></listitem>
 388         </varlistentry>
 389         <varlistentry><term>-k [<replaceable>section</replaceable>:]<replaceable>option</replaceable>=<replaceable>value</replaceable>
 390           </term>
 391           <listitem><para> Override configuration file option.  If
 392               "section" is omitted, it defaults
 393               to <property>general</property>.  Any underscores "_" in
 394               the section name are replaced with spaces: for instance,
 395               to override option <property>autorefresh</property> in
 396               the "[Account Personal]" section in the config file one
 397               would use "-k Account_Personal:autorefresh=30".
 398           </para></listitem>
 399         </varlistentry>
 400           <varlistentry><term>-l
 401           <replaceable>filename</replaceable></term>
 402             <listitem><para>
 403               Enables logging to filename.  This will log everything
 404               that goes to the screen to the specified file.
 405               Additionally, if any debugging is specified with -d,
 406               then debug messages will not go to the screen, but
 407               instead to the logfile only.</para>
 408           </listitem>
 409         </varlistentry>
 410           <varlistentry><term>-o</term>
 411             <listitem><para>Run only once, ignoring all
 412               <property>autorefresh</property> settings in the configuration
 413               file.</para>
 414             </listitem>
 415           </varlistentry>
 416           <varlistentry><term>-q</term>
 417             <listitem><para>Run only quick synchronizations.   Ignore any flag
 418               updates on IMAP servers.</para>
 419             </listitem>
 420           </varlistentry>
 421           <varlistentry><term>-h</term> <term>--help</term>
 422             <listitem><para>Show summary of options.</para></listitem>
 423           </varlistentry>
 424           <varlistentry><term>-u <replaceable>interface</replaceable></term>
 425             <listitem><para>Specifies an alternative user interface module
 426               to use.  This overrides the default specified in the
 427               configuration file.  The pre-defined options are listed in
 428               the User Interfaces section.</para>
 429             </listitem>
 430           </varlistentry>
 431       </variablelist>
 432     </refsect1>
 433     <refsect1>
 434       <title>User Interfaces</title>
 435       <para>&OfflineIMAP; has a pluggable user interface system that lets you choose how the
 436         program communicates information to you.  There are two graphical
 437         interfaces, two terminal interfaces, and two noninteractive interfaces
 438         suitable for scripting or logging purposes.  The
 439         <property>ui</property> option in the configuration file specifies
 440         user interface preferences.  The <option>-u</option> command-line
 441         option can override the configuration file setting.  The available
 442         values for the configuration file or command-line are described
 443         in this section.</para>
 444
 445       <refsect2>
 446         <title>Curses.Blinkenlights</title>
 447         <para>
 448                 Curses.Blinkenlights is an interface designed to be sleek, fun to watch, and
 449           informative of the overall picture of what &OfflineIMAP;
 450           is doing.  I consider it to be the best general-purpose interface in
 451           &OfflineIMAP;.
 452         </para>
 453         <para>
 454           Curses.Blinkenlights contains a row of
 455           "LEDs" with command buttons and a log.
 456           The  log shows more
 457           detail about what is happening and is color-coded to match the color
 458           of the lights.
 459         </para>
 460         <para>
 461           Each light in the Blinkenlights interface represents a thread
 462           of execution -- that is, a particular task that &OfflineIMAP;
 463           is performing right now.  The colors indicate what task
 464           the particular thread is performing, and are as follows:
 465         </para>
 466         <variablelist>
 467           <varlistentry>
 468             <term>Black</term>
 469             <listitem><para>indicates that this light's thread has terminated; it will light up
 470               again later when new threads start up.  So, black indicates no
 471               activity.
 472             </para></listitem>
 473           </varlistentry>
 474           <varlistentry>
 475             <term>Red (Meaning 1)</term>
 476             <listitem><para>is the color of the main program's thread, which basically does
 477               nothing but monitor the others.  It might remind you of HAL 9000 in
 478               <citation>2001</citation>.
 479             </para></listitem>
 480           </varlistentry>
 481           <varlistentry>
 482             <term>Gray</term>
 483             <listitem><para>indicates that the thread is establishing a new connection to the IMAP
 484               server.
 485             </para></listitem>
 486           </varlistentry>
 487           <varlistentry>
 488             <term>Purple</term>
 489             <listitem><para>is the color of an account synchronization thread that is monitoring
 490               the progress of the folders in that account (not generating any I/O).
 491             </para></listitem>
 492           </varlistentry>
 493           <varlistentry>
 494             <term>Cyan</term>
 495             <listitem><para>indicates that the thread is syncing a folder.
 496             </para></listitem>
 497           </varlistentry>
 498           <varlistentry>
 499             <term>Green</term>
 500             <listitem><para>means that a folder's message list is being loaded.
 501             </para></listitem>
 502           </varlistentry>
 503           <varlistentry>
 504             <term>Blue</term>
 505             <listitem><para>is the color of a message synchronization controller thread.
 506             </para></listitem>
 507           </varlistentry>
 508           <varlistentry>
 509             <term>Orange</term>
 510             <listitem><para>indicates that an actual message is being copied.
 511               (We use fuchsia for fake messages.)
 512             </para></listitem>
 513           </varlistentry>
 514           <varlistentry>
 515             <term>Red (meaning 2)</term>
 516             <listitem><para>indicates that a message is being deleted.
 517             </para></listitem>
 518           </varlistentry>
 519           <varlistentry>
 520             <term>Yellow / bright orange</term>
 521             <listitem><para>indicates that message flags are being added.
 522             </para></listitem>
 523           </varlistentry>
 524           <varlistentry>
 525             <term>Pink / bright red</term>
 526             <listitem><para>indicates that message flags are being removed.
 527             </para></listitem>
 528           </varlistentry>
 529           <varlistentry>
 530             <term>Red / Black Flashing</term>
 531             <listitem><para>corresponds to the countdown timer that runs between
 532               synchronizations.
 533             </para></listitem>
 534           </varlistentry>
 535         </variablelist>
 536         <para>The name of this interfaces derives from a bit of computer
 537           history.  Eric Raymond's <citation>Jargon File</citation> defines
 538           <firstterm>blinkenlights</firstterm>, in part, as:
 539         </para>
 540         <blockquote>
 541           <para>Front-panel diagnostic
 542             lights on a computer, esp. a dinosaur. Now that dinosaurs are rare,
 543             this term usually refers to status lights on a modem, network hub, or
 544             the like.
 545           </para>
 546           <para>
 547             This term derives from the last word of the famous blackletter-Gothic
 548             sign in mangled pseudo-German that once graced about half the computer
 549             rooms in the English-speaking world. One version ran in its entirety as
 550             follows:
 551           </para>
 552           <para>
 553             <emphasis>ACHTUNG!  ALLES LOOKENSPEEPERS!</emphasis>
 554           </para>
 555           <para>
 556             Das computermachine ist nicht fuer gefingerpoken und mittengrabben.
 557             Ist easy schnappen der springenwerk, blowenfusen und poppencorken
 558             mit spitzensparken.  Ist nicht fuer gewerken bei das dumpkopfen.
 559             Das rubbernecken sichtseeren keepen das cotten-pickenen hans in das
 560             pockets muss; relaxen und watchen das blinkenlichten.
 561           </para>
 562         </blockquote>
 563       </refsect2>
 564
 565       <refsect2>
 566         <title>TTY.TTYUI</title>
 567         <para>
 568           TTY.TTYUI interface is for people running in basic, non-color terminals.  It
 569           prints out basic status messages and is generally friendly to use on a console
 570           or xterm.
 571         </para>
 572       </refsect2>
 573
 574       <refsect2>
 575         <title>Noninteractive.Basic</title>
 576         <para>
 577           Noninteractive.Basic is designed for situations in which &OfflineIMAP;
 578           will be run non-attended and the status of its execution will be
 579           logged.  You might use it, for instance, to have the system run
 580           automatically and
 581           e-mail you the results of the synchronization.  This user interface
 582           is not capable of reading a password from the keyboard; account
 583           passwords must be specified using one of the configuration file options.
 584         </para>
 585       </refsect2>
 586
 587       <refsect2>
 588         <title>Noninteractive.Quiet</title>
 589         <para>
 590           Noninteractive.Quiet is designed for non-attended running in situations
 591           where normal status messages are not desired.  It will output nothing
 592           except errors and serious warnings.  Like Noninteractive.Basic,
 593           this user interface
 594           is not capable of reading a password from the keyboard; account
 595           passwords must be specified using one of the configuration file options.
 596         </para>
 597       </refsect2>
 598
 599       <refsect2>
 600         <title>Machine.MachineUI</title>
 601         <para>
 602            Machine.MachineUI generates output in a machine-parsable format.
 603            It is designed for other programs that will interface
 604            to OfflineIMAP.
 605         </para>
 606       </refsect2>
 607
 608     </refsect1>
 609
 610     <refsect1>
 611       <title>Examples</title>
 612       <para>Here are some example configurations for various situations.
 613         Please e-mail any other examples you have that may be useful to
 614         me.
 615       </para>
 616
 617       <refsect2>
 618         <title>Multiple Accounts with Mutt</title>
 619         <para>
 620           This example shows you how to set up &OfflineIMAP; to
 621           synchronize multiple accounts with the mutt mail reader.
 622         </para>
 623         <para>
 624           Start by creating a directory to hold your folders by running
 625           <command>mkdir ~/Mail</command>.  Then, in your
 626           <filename>~/.offlineimaprc</filename>, specify:
 627         </para>
 628         <programlisting>accounts = Personal, Work</programlisting>
 629         <para>
 630           Make sure that you have both an
 631           <property>[Account Personal]</property>
 632           and an <property>[Account Work]</property> section.  The
 633           local repository for each account must have different
 634           <property>localfolder</> path names.
 635           Also, make sure
 636           to enable <property>[mbnames]</property>.
 637         </para>
 638         <para>
 639           In each local repository section, write something like this:
 640         </para>
 641         <programlisting>localfolders = ~/Mail/Personal</programlisting>
 642         <para>
 643           Finally, add these lines to your <filename>~/.muttrc</filename>:
 644         </para>
 645         <programlisting>source ~/path-to-mbnames-muttrc-mailboxes
 646 folder-hook Personal set from="youremail@personal.com"
 647 folder-hook Work set from="youremail@work.com"
 648 set mbox_type=Maildir
 649 set folder=$HOME/Mail
 650 spoolfile=+Personal/INBOX</programlisting>
 651         <para>
 652           That's it!
 653         </para>
 654       </refsect2>
 655
 656       <refsect2>
 657         <title>UW-IMAPD and References</title>
 658         <para>Some users with a UW-IMAPD server need to use &OfflineIMAP;'s
 659           "reference" feature to get at their mailboxes, specifying a reference
 660           of "~/Mail" or "#mh/" depending on the configuration.  The below
 661           configuration from (originally from docwhat@gerf.org)
 662           shows using a <property>reference</property> of Mail, a <property>nametrans</property>
 663           that strips
 664           the leading Mail/ off incoming folder names, and a
 665           <property>folderfilter</property> that
 666           limits the folders synced to just three.
 667         </para>
 668         <programlisting>[Account Gerf]
 669 localrepository = GerfLocal
 670 remoterepository = GerfRemote
 671
 672 [Repository GerfLocal]
 673 type = Maildir
 674 localfolders = ~/Mail
 675
 676 [Repository GerfRemote]
 677 type = IMAP
 678 remotehost = gerf.org
 679 ssl = yes
 680 remoteuser = docwhat
 681 reference = Mail
 682 # Trims off the preceeding Mail on all the folder names.
 683 nametrans = lambda foldername: \
 684             re.sub('^Mail/', '', foldername)
 685 # Yeah, you have to mention the Mail dir, even though it
 686 # would seem intuitive that reference would trim it.
 687 folderfilter = lambda foldername: foldername in [
 688       'Mail/INBOX',
 689       'Mail/list/zaurus-general',
 690       'Mail/list/zaurus-dev',
 691       ]
 692 maxconnections = 1
 693 holdconnectionopen = no</programlisting>
 694       </refsect2>
 695
 696       <refsect2>
 697         <title>pythonfile Configuration File Option</title>
 698         <para>You can have &OfflineIMAP;
 699           load up a Python file before evaluating the
 700           configuration file options that are Python expressions.  This example
 701           is based on one supplied by Tommi Virtanen for this feature.
 702         </para>
 703         <para>
 704           In <filename>~/.offlineimaprc</filename>, he adds these options:
 705         </para>
 706         <programlisting>[general]
 707 pythonfile=~/.offlineimap.py
 708 [Repository foo]
 709 foldersort=mycmp</programlisting>
 710         <para>
 711           Then, the <filename>~/.offlineimap.py</filename> file will
 712           contain:
 713         </para>
 714         <programlisting>prioritized = ['INBOX', 'personal', 'announce', 'list']
 715
 716 def mycmp(x, y):
 717    for prefix in prioritized:
 718        xsw = x.startswith(prefix)
 719        ysw = y.startswith(prefix)
 720        if xsw and ysw:
 721           return cmp(x, y)
 722        elif xsw:
 723           return -1
 724        elif ysw:
 725           return +1
 726    return cmp(x, y)
 727
 728 def test_mycmp():
 729    import os, os.path
 730    folders=os.listdir(os.path.expanduser('~/data/mail/tv@hq.yok.utu.fi'))
 731    folders.sort(mycmp)
 732    print folders</programlisting>
 733         <para>
 734           This code snippet illustrates how the <property>foldersort</property>
 735           option can be customized with a Python function from the
 736           <property>pythonfile</property> to always synchronize certain
 737           folders first.
 738         </para>
 739       </refsect2>
 740     </refsect1>
 741
 742     <refsect1>
 743             <title>Signals</title>
 744             <para>
 745                     OfflineIMAP writes its current PID into
 746                     <filename>~/.offlineimap/pid</filename> when it is
 747                     running.  It is not guaranteed that this file will
 748                     not exist when OfflineIMAP is not running.
 749             </para>
 750             <!-- not done yet
 751             <para>
 752                     You can send SIGINT to OfflineIMAP using this file to
 753                     kill it.  SIGUSR1 will force an immediate resync of
 754                     all accounts.  This will be ignored for all accounts
 755                     for which a resync is already in progress.
 756             </para>
 757             -->
 758     </refsect1>
 759
 760     <refsect1>
 761       <title>Errors</title>
 762       <para>
 763         If you get one of some frequently-encountered or confusing errors,
 764         please check this section.
 765       </para>
 766
 767       <refsect2>
 768         <title>UID validity problem for folder</title>
 769         <para>IMAP servers use a unique ID (UID) to refer to a specific message.
 770           This number is guaranteed to be unique to a particular message
 771           <emphasis>forever</emphasis>.
 772           No other message in the same folder will ever get the same
 773           UID.  UIDs are an integral part of &OfflineIMAP;'s synchronization
 774           scheme; they are used to match up messages on your computer to
 775           messages on the server.
 776         </para>
 777
 778         <para>
 779           Sometimes, the UIDs on the server might get reset.  Usually this will
 780           happen if you delete and then recreate a folder.  When you create a
 781           folder, the server will often start the UID back from 1.  But
 782           &OfflineIMAP; might still have the UIDs from the previous folder by the
 783           same name stored.  &OfflineIMAP; will detect this condition and skip the
 784           folder.  This is GOOD, because it prevents data loss.
 785         </para>
 786
 787         <para>
 788           You can fix it by removing your local folder and cache data.  For
 789           instance, if your folders are under <filename>~/Folders</filename>
 790           and the folder with the problem is INBOX, you'd type this:
 791         </para>
 792
 793         <programlisting>rm -r ~/Folders/INBOX
 794 rm -r ~/.offlineimap/Account-<replaceable>AccountName</>/LocalStatus/INBOX
 795 rm -r ~/.offlineimap/Repository-<replaceable>RemoteRepositoryName</>/FolderValidity/INBOX</programlisting>
 796
 797         <para>
 798           (Of course, replace AccountName and RemoteRepositoryName
 799           with the names as specified
 800           in <filename>~/.offlineimaprc</filename>).
 801         </para>
 802
 803         <para>Next time you run &OfflineIMAP;, it will re-download
 804           the folder with the
 805           new UIDs.  Note that the procedure specified above will lose any local
 806           changes made to the folder.
 807         </para>
 808
 809         <para>
 810           Some IMAP servers are broken and do not support UIDs properly.  If you
 811           continue to get this error for all your folders even after performing
 812           the above procedure, it is likely that your IMAP server falls into
 813           this category.  &OfflineIMAP; is incompatible with such servers.
 814           Using &OfflineIMAP; with them will not destroy any mail, but at the same time,
 815           it will not actually synchronize it either.  (&OfflineIMAP; will detect
 816           this condition and abort prior to synchronization.)
 817         </para>
 818         <para>
 819           This question comes up frequently on the
 820           <ulink
 821           url="http://lists.complete.org/offlineimap@complete.org/">&OfflineIMAP;
 822           mailing list</ulink>.  You can find a
 823           <ulink
 824           url="http://lists.complete.org/offlineimap@complete.org/2003/04/msg00012.html.gz">detailed
 825           discussion</ulink> of the problem there.
 826         </para>
 827       </refsect2>
 828     </refsect1>
 829     <refsect1>
 830       <title>Conforming To</title>
 831       <itemizedlist>
 832         <listitem><para>Internet Message Access Protocol version 4rev1 (IMAP 4rev1) as
 833           specified in RFC2060 and RFC3501</para></listitem>
 834         <listitem><para>CRAM-MD5 as specified in RFC2195</para></listitem>
 835         <listitem><para>Maildir as specified in
 836           <ulink url="http://www.qmail.org/qmail-manual-html/man5/maildir.html">the Maildir manpage</ulink> and
 837           <ulink url="http://cr.yp.to/proto/maildir.html">the qmail website</ulink>.</para></listitem>
 838         <listitem><para>Standard Python 2.2.1 as implemented on POSIX-compliant systems.</para></listitem>
 839       </itemizedlist>
 840     </refsect1>
 841
 842     <refsect1>
 843       <title>Notes</title>
 844       <refsect2>
 845         <title>Deleting Local Folders</title>
 846         <para>&OfflineIMAP; does a two-way synchronization.  That is, if you
 847           make a change to the mail on the server, it will be propagated to your
 848           local copy, and vise-versa.  Some people might think that it would be
 849           wise to just delete all their local mail folders periodically.  If you
 850           do this with &OfflineIMAP;, remember to also remove your local status
 851           cache (<filename>~/.offlineimap</filename> by default).  Otherwise, &OfflineIMAP; will take
 852           this as an intentional deletion of many messages and will interpret
 853           your action as requesting them to be deleted from the server as well.
 854           (If you don't understand this, don't worry; you probably won't
 855           encounter this situation)
 856         </para>
 857       </refsect2>
 858
 859       <refsect2>
 860         <title>Multiple Instances</title>
 861         <para>&OfflineIMAP; is not designed to have several instances (for instance, a cron job and an interactive invocation) run over the same
 862           mailbox simultaneously.  It will perform a check on startup and
 863           abort if another &OfflineIMAP; is already running.  If you need
 864           to schedule synchronizations, you'll probably find
 865           <property>autorefresh</property> settings more convenient than cron.
 866           Alternatively, you can set a separate <property>metadata</property>
 867           directory for each instance.
 868         </para>
 869       </refsect2>
 870
 871       <refsect2>
 872         <title>Copying Messages Between Folders</title>
 873         <para>
 874           Normally, when you copy a message between folders or add a new message
 875           to a folder locally, &OfflineIMAP;
 876           will just do the right thing.  However, sometimes this can be tricky
 877           -- if your IMAP server does not provide the SEARCH command, or does
 878           not return something useful, &OfflineIMAP;
 879           cannot determine the new UID of the message.  So, in these rare
 880           instances, OfflineIMAP will upload the message to the IMAP server and
 881           delete it from your local folder.  Then, on your next sync, the
 882           message will be re-downloaded with the proper UID.
 883           &OfflineIMAP; makes sure that the message was properly uploaded before deleting it,
 884           so there should be no risk of data loss.
 885         </para>
 886       </refsect2>
 887
 888
 889       <refsect2>
 890         <title>Mailing List</title>
 891         <para>There is an OfflineIMAP mailing list available.
 892           To subscribe, send the text "Subscribe" in the subject of a mail to
 893           offlineimap-request@complete.org.  To post, send the message to
 894           offlineimap@complete.org.  Archives are available at
 895           <ulink url="http://lists.complete.org/offlineimap@complete.org/"></>.
 896         </para>
 897       </refsect2>
 898
 899       <refsect2>
 900         <title>Bugs</title>
 901         <para>
 902           Reports of bugs should be reported online at the
 903           &OfflineIMAP; homepage.
 904           Debian users are encouraged to instead use the
 905         Debian
 906           bug-tracking system.
 907         </para>
 908       </refsect2>
 909     </refsect1>
 910
 911     <refsect1 id="upgrading.4.0">
 912       <title>Upgrading to 4.0</title>
 913       <para>
 914         If you are upgrading from a version of &OfflineIMAP; prior to
 915         3.99.12, you will find that you will get errors when
 916         &OfflineIMAP; starts up (relating to ConfigParser or
 917         AccountHashGenerator) and the
 918         configuration file.  This is because the config file format
 919         had to change to accommodate new features in 4.0.  Fortunately,
 920         it's not difficult to adjust it to suit.
 921       </para>
 922       <para>
 923         First thing you need to do is stop any running &OfflineIMAP;
 924         instance, making sure first that it's synced all your mail.
 925         Then, modify your
 926         <filename>~/.offlineimaprc</filename> file.  You'll need to
 927         split up each account section (make sure that it now starts
 928         with "Account ") into two Repository sections (one for the
 929         local side and another for the remote side.)  See the files
 930         <filename>offlineimap.conf.minimal</filename> and
 931         <filename>offlineimap.conf</filename> in the distribution if
 932         you need more assistance.
 933       </para>
 934       <para>
 935         &OfflineIMAP;'s status directory area has also changed.
 936         Therefore, you should delete everything in ~/.offlineimap as
 937         well as your local mail folders.
 938       </para>
 939       <para>
 940         When you start up &OfflineIMAP; 4.0, it will re-download all
 941         your mail from the server and then you can continue using it
 942         like normal.
 943       </para>
 944     </refsect1>
 945
 946
 947     <refsect1>
 948       <title>Copyright</title>
 949       <para>OfflineIMAP, and this manual, are Copyright &copy; 2002 - 2006 John Goerzen.</para>
 950
 951       <para>
 952         This program is free software; you can redistribute it and/or modify
 953         it under the terms of the GNU General Public License as published by
 954         the Free Software Foundation; either version 2 of the License, or
 955         (at your option) any later version.
 956       </para>
 957
 958       <para>
 959         This program is distributed in the hope that it will be useful,
 960         but WITHOUT ANY WARRANTY; without even the implied warranty of
 961         MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 962         GNU General Public License for more details.
 963       </para>
 964
 965       <para>
 966         You should have received a copy of the GNU General Public License
 967         along with this program; if not, write to the Free Software
 968         Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA</para>
 969
 970       <para>imaplib.py comes from the Python dev tree and is licensed under
 971         the GPL-compatible PSF license as stated in the file
 972         <filename>COPYRIGHT</filename> in the &OfflineIMAP;
 973          distribution.
 974       </para>
 975     </refsect1>
 976
 977     <refsect1>
 978       <title>Author</title>
 979       <para>&OfflineIMAP;, its libraries, documentation, and all included files, except where
 980         noted, was written by John Goerzen <email>jgoerzen@complete.org</email> and
 981         copyright is held as stated in the COPYRIGHT section.
 982       </para>
 983
 984       <para>
 985         &OfflineIMAP; may be downloaded, and information found, from its
 986         <ulink url="http://software.complete.org/offlineimap">homepage</ulink>.
 987       </para>
 988
 989     </refsect1>
 990
 991     <refsect1>
 992       <title>See Also</title>
 993       <para><application>mutt</application>(1),
 994         <application>python</application>(1)
 995       </para>
 996     </refsect1>
 997
 998     <refsect1>
 999       <title>History</title>
1000       <para>
1001         Detailed history may be found in the file ChangeLog in the
1002         &OfflineIMAP; distribution.  Feature and bug histories may be
1003         found in the file debian/changelog which, despite its name, is
1004         not really Debian-specific.  This section provides a large
1005         overview.
1006       </para>
1007       <para>
1008         Development on &OfflineIMAP; began on June 18, 2002.  Version
1009         1.0.0 was released three days later on June 21, 2002.  Point
1010         releases followed, including speed optimizations and some
1011         compatibility fixes.
1012       </para>
1013       <para>Version 2.0.0 was released on July 3, 2002, and
1014         represented the first time the synchronization became
1015         multithreaded and, to the best of my knowledge, the first
1016         multithreaded IMAP syncrhonizing application in existance.
1017         The last 2.0.x release, 2.0.8, was made on July 9.
1018       </para>
1019       <para>
1020         Version 3.0.0 was released on July 11, 2002, and introduced
1021         modular user interfaces and the first GUI interface for
1022         &OfflineIMAP;.  This manual also was introduced with 3.0.0,
1023         along with many command-line options.  Version 3.1.0 was
1024         released on July 21, adding the Noninteractive user
1025         interfaces, profiling support, and several bugfixes.  3.2.0
1026         was released on July 24, adding support for the Blinkenlights
1027         GUI interface.  &OfflineIMAP; entered maintenance mode for
1028         awhile, as it had reached a feature-complete milestone in my
1029         mind.
1030       </para>
1031       <para>
1032         The 3.99.x branch began in on October 7, 2002, to begin work
1033         for 4.0.  The Curses.Blinkenlights interface was added in
1034         3.99.6, and many architectural changes were made.
1035       </para>
1036       <para>
1037         4.0.0 was released on July 18, 2003, including the ability to
1038             synchronize directly between two IMAP servers, the first
1039             re-architecting of the configuration file to refine the
1040             notion of an account, and the new Curses interface.
1041       </para>
1042     </refsect1>
1043   </refentry>
1044 </reference>
1045
1046 <!--
1047 Local Variables:
1048 mode: sgml
1049 sgml-set-face: T
1050 End:
1051 -->