offlineimap/head/manual.txt

OFFLINEIMAP(1)          OfflineIMAP manual         OFFLINEIMAP(1)



NAME
       OfflineIMAP  -  Powerful  IMAP/Maildir synchronization and
       reader support

SYNOPSIS
       offlineimap [ -1 ] [ -a accountlist ] [ -c configfile ]
       [ -d ] [ -u interface ]

       offlineimap -h | --help

DESCRIPTION
       OfflineIMAP is a tool to  simplify  your  e-mail  reading.
       With  OfflineIMAP, you can read the same mailbox from mul-
       tiple 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 pro-
       vide disconnected operation.

       OfflineIMAP  is FAST; 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.

       OfflineIMAP  is  FLEXIBLE; 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  fea-
       tures  are  supported  to  ensure  compatibility  with the
       widest variety of IMAP servers.

       OfflineIMAP is SAFE; it uses an algorithm designed to pre-
       vent  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.

   METHOD OF OPERATION
       OfflineIMAP  operates  by  maintaining a hierarchy of mail
       folders in Maildir format locally.  Your own  mail  reader
       will  read  mail  from this tree, and need never know that
       the mail comes from IMAP.  OfflineIMAP will detect changes
       to  the mail folders on your IMAP server and your own com-
       puter  and  bi-directionally  synchronize  them,  copying,
       marking, and deleting messages as necessary.

INSTALLATION
       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 instal-
       lation with other systems, and a single-user installation.
       You  can  download  the latest version of OfflineIMAP from
       http://quux.org/devel/offlineimap/.

   PREREQUISITES
       In order to use OfflineIMAP, you need to have these condi-
       tions satisfied:

       o      Your  mail server must support IMAP.  Most Internet
              Service Providers and corporate  networks  do,  and
              most  operating systems have an IMAP implementation
              readily available.

       o      You  must  have  Python  version  2.2.1  or   above
              installed.  If you are running on Debian GNU/Linux,
              this requirement will automatically be  taken  care
              of  for  you.   If  you do not have Python already,
              check with your system administrator  or  operating
              system     vendor;    or,    download    it    from
              http://www.python.org/.  If you intend to  use  the
              Tk  interface,  you  must  have  Tkiner (python-tk)
              installed.  If you intend to use the SSL interface,
              your  Python must have been built with SSL support.

       o      Have a mail reader that supports the Maildir  mail-
              box  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  compati-
              ble with it will work with OfflineIMAP.

   DEBIAN SYSTEM-WIDE INSTALLATION
       If  you  are  tracking  Debian  unstable,  you may install
       OfflineIMAP by simply running  the  following  command  as
       root:

       apt-get install offlineimap

       If  you  are  not  tracking  Debian unstable, download the
       Debian .deb package from the OfflineIMAP website and  then
       run  dpkg  -i to install the downloaded package.  Then, go
       to CONFIGURATION below.   You  will  type  offlineimap  to
       invoke the program.

   OTHER SYSTEM-WIDE INSTALLATION
       Download  the  tar.gz version of the package from the web-
       site.  Then run these commands:

       tar -zxvf offlineimap-x.y.z.tar.gz
       cd offlineimap-x.y.z
       python2.2 setup.py

       Some systems will need to use python instead of python2.2.
       Next, proceed to configuration.  You will type offlineimap
       to invoke the program.

   SINGLE-ACCOUNT INSTALLATION
       Download the tar.gz version of the package from  the  web-
       site.  Then run these commands:

       tar -zxvf offlineimap-x.y.z.tar.gz
       cd offlineimap-x.y.z

       When  you  want  to run OfflineIMAP, you will issue the cd
       command as above and then type ./offlineimap; there is  no
       installation step necessary.

CONFIGURATION
       OfflineIMAP  is  regulated by a configuration file that is
       normally stored in  ~/.offlineimaprc.   OfflineIMAP  ships
       with a file named offlineimap.conf 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.

OPTIONS
       Most  configuration  is  done  via the configuration file.
       Nevertheless, there are a few options that you may set for
       OfflineIMAP.

       -1     Disable   all  multithreading  operations  and  use
              solely a single-thread sync.  This effectively sets
              the maxsyncaccounts and all maxconnections configu-
              ration file variables to 1.

       -a accountlist
              Overrides the accounts section in the config  file.
              Lets  you  specify  a  particular account or set of
              accounts to sync without having to edit the  config
              file.   You  might  use  this  to  exclude  certain
              accounts, or to sync some accounts  that  you  nor-
              mally prefer not to.

       -c configfile
              Specifies  a  configuration  file to use in lieu of
              the default, ~/.offlineimaprc.

       -d     Enables IMAP protocol stream and parsing debugging.
              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 -1 in
              order to make the results more sensible.  Note that
              this  output  will  contain  full  IMAP protocol in
              plain text, including passwords, so  take  care  to
              remove  that from the debugging output before send-
              ing it to anyone else.

       -h, --help
              Show summary of options.

       -u interface
              Specifies an alternative user interface  module  to
              use.   This  overrides the default specified in the
              configuration file.  The UI specified with -u  will
              be  forced to be used, even if its isuable() method
              states that it cannot be.   Use  this  option  with
              care.

EXAMPLES
       Here  is  an example configuration for a particularly com-
       plex situation; more examples will be added later.

   MULTIPLE ACCOUNTS WITH MUTT
       This example shows you how to set up OfflineIMAP  to  syn-
       chronize multiple accounts with the mutt mail reader.

       Start by creating a directory to hold your folders:
       mkdir ~/Mail

       In your ~/.offlineimaprc, specify this:
       accounts = Personal, Work

       Make  sure  that  you  have both a [Personal] and a [Work]
       section, with different localfolder pathnames  and  enable
       [mbnames].

       In each account section, do something like this:
       localfolders = ~/Mail/Personal

       Add these lines to your ~/.muttrc:
       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
       set spoolfile=+Personal/INBOX

       That's it!

ERRORS
       If you get one of some frequently-encountered or confusing
       errors, please check this section.

   UID validity problem for folder
       IMAP servers use a unique ID (UID) to refer to a  specific
       message.  This number is guaranteed to be unique to a par-
       ticular message FOREVER.  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.

       Sometimes, the UIDs on the server might get  reset.   Usu-
       ally  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.

       You  can  fix  it  by removing your local folder and cache
       data.  For instance, if your folders are  under  ~/Folders
       and the folder with the problem is INBOX, you'd type this:

       rm -r ~/Folders/INBOX
       rm ~/.offlineimap/AccountName/INBOX

       (replacing AccountName with the account name as  specified
       in ~/.offlineimaprc)

       Next  time  you  run  OfflineIMAP, it will re-download the
       folder with the new UIDs.  Note that the procedure  speci-
       fied above will lose any local changes made to the folder.

       Some IMAP servers are broken and do not support UIDs prop-
       erly.   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)


OTHER FREQUENTLY ASKED QUESTIONS
       There are some other FAQs that might not fit into  another
       section of this document, and they are enumerated here.

       What platforms does OfflineIMAP run on?
              It  should  run  on  most  platforms  supported  by
              Python, which are quite a few.

       I'm using Mutt. Other IMAP sync programs require me to use
       set  maildir_trash=yes  .  Do  I  need  to  do  that  with
       OfflineIMAP?
              No.  OfflineIMAP is smart enough to figure out mes-
              sage  deletion  without  this extra crutch.  You'll
              get the best results if you don't use this setting,
              in fact.

       How do I specify the names of my folders?
              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 folderfilter and foldertrans  configuration
              file  options to request certain folders and rename
              them as they come in if you like.

       How can I prevent certain folders from being synced?
              Use the folderfilter option  in  the  configuration
              file.

       How can I add or delete a folder?
              OfflineIMAP  does  not  currently provide this fea-
              ture, but if you create a new folder  on  the  IMAP
              server, it will be created locally automatically.

       Are there any other warnings that I should be aware of?
              Yes; see the NOTES section below.

       What is the mailbox name recorder (mbnames) for?
              The  Mutt  mail  reader is not capable of automati-
              cally determining  the  names  of  your  mailboxes.
              OfflineIMAP  can  help  it (or many other) programs
              out be writing these names  out  in  a  format  you
              specify.  See the example offlineimap.conf file for
              details.

       Can I synchronize multiple accounts with OfflineIMAP?
              Sure.  Just name them all in the accounts  line  in
              the  general  section of the config file, and add a
              per-account section for each one.

       Does OfflineIMAP support POP?
              No.  POP is not robust enough to  do  a  completely
              reliable    multi-machine    synchronization   like
              OfflineIMAP can do.  OfflineIMAP will  not  support
              it.

       Do you support mailbox formats other than Maildir?
              Not  at  present.  There is no technical reason not
              to; just no demand yet.  Maildir is a superior for-
              mat anyway.

       [technical]  Why  are  your  Maildir  message filenames so
       huge?
              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 usu-
              ally be as well, BUT some mail  clients  move  mes-
              sages  between  folders  by simply moving the file,
              leaving the name intact.

              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  facili-
              tate this.

       What is the speed of OfflineIMAP's sync?
              OfflineIMAP versions 2.0 and above contain a multi-
              threaded system.  A good way to  experiment  is  by
              setting  maxsyncaccounts to 3 and maxconnections to
              3 in each account clause.

              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.

              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.   Administra-
              tors  might  take  unkindly to this, and the server
              might bog down.  There are many  variables  in  the
              optimal setting; experimentation may help.

              An  informal  benchmark yields these results for my
              setup:

              10 minutes with MacOS X Mail.app "manual cache"
              5 minutes with GNUS agent sync
              20 seconds with OfflineIMAP 1.x
              9 seconds with OfflineIMAP 2.x
              3 seconds with OfflineIMAP 3.x "cold start"
              2 seconds with OfflineIMAP 3.x "held connection"

CONFORMING TO
       o      Internet  Message  Access  Protocol  version  4rev1
              (IMAP 4rev1) as specified in RFC2060

       o      Maildir as specified in http://www.qmail.org/qmail-
              manual-html/man5/maildir.html                   and
              http://cr.yp.to/proto/maildir.html.

       o      Standard  Python 2.2.1 as implemented on POSIX-com-
              pliant systems.

NOTES
   DELETING LOCAL FOLDERS
       OfflineIMAP does a two-way synchronization.  That  is,  if
       you  make  a  change to the mail on the server, it will be
       propogated to your local copy, and vise-versa.  Some  peo-
       ple  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 sta-
       tus  cache  (~/.offlineimap   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)

   MAILING LIST
       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.

BUGS
       Should  be reported to the author at the address specified
       below.

COPYRIGHT
       OfflineIMAP is Copyright (C) 2002 John Goerzen.

       This program is free software;  you  can  redistribute  it
       and/or modify it under the terms of the GNU General Public
       License as published  by  the  Free  Software  Foundation;
       either  version  2 of the License, or (at your option) any
       later version.

       This program is distributed in the hope that  it  will  be
       useful, but WITHOUT ANY WARRANTY; without even the implied
       warranty of MERCHANTABILITY or FITNESS  FOR  A  PARTICULAR
       PURPOSE.   See  the  GNU  General  Public License for more
       details.

       You should have received a copy of the GNU General  Public
       License along with this program; if not, write to:

       Free Software Foundation, Inc.
       59 Temple Place
       Suite 330
       Boston, MA  02111-1307
       USA

AUTHOR
       OfflineIMAP,   its   libraries,   documentation,  and  all
       included files, except where noted, was  written  by  John
       Goerzen  <jgoerzen@complete.org>  and copyright is held as
       stated in the COPYRIGHT section.

       OfflineIMAP may be downloaded, and information found, from
       its homepage via either Gopher or HTTP:

       gopher://quux.org/1/devel/offlineimap
       http://quux.org/devel/offlineimap


SEE ALSO
       mutt(1), python(1).



John Goerzen              July 11, 2002            OFFLINEIMAP(1)