code.delx.au - offlineimap/blob - offlineimap/head/manual.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <HTML
   3 ><HEAD
   4 ><TITLE
   5 >OfflineIMAP Manual</TITLE
   6 ><META
   7 NAME="GENERATOR"
   8 CONTENT="Modular DocBook HTML Stylesheet Version 1.77+"></HEAD
   9 ><BODY
  10 CLASS="REFERENCE"
  11 BGCOLOR="#FFFFFF"
  12 TEXT="#000000"
  13 LINK="#0000FF"
  14 VLINK="#840084"
  15 ALINK="#0000FF"
  16 ><DIV
  17 CLASS="REFERENCE"
  18 ><A
  19 NAME="AEN1"
  20 ></A
  21 ><DIV
  22 CLASS="TITLEPAGE"
  23 ><H1
  24 CLASS="TITLE"
  25 >I. OfflineIMAP Manual</H1
  26 ><DIV
  27 CLASS="TOC"
  28 ><DL
  29 ><DT
  30 ><B
  31 >Table of Contents</B
  32 ></DT
  33 ><DT
  34 ><A
  35 HREF="#AEN3"
  36 >offlineimap</A
  37 >&nbsp;--&nbsp;Powerful IMAP/Maildir synchronization
  38         and reader support</DT
  39 ></DL
  40 ></DIV
  41 ></DIV
  42 ><H1
  43 ><A
  44 NAME="AEN3"
  45 ></A
  46 >offlineimap</H1
  47 ><DIV
  48 CLASS="REFNAMEDIV"
  49 ><A
  50 NAME="AEN15"
  51 ></A
  52 ><H2
  53 >Name</H2
  54 >OfflineIMAP&nbsp;--&nbsp;Powerful IMAP/Maildir synchronization
  55         and reader support</DIV
  56 ><DIV
  57 CLASS="REFSYNOPSISDIV"
  58 ><A
  59 NAME="AEN18"
  60 ></A
  61 ><H2
  62 >Synopsis</H2
  63 ><P
  64 ><B
  65 CLASS="COMMAND"
  66 >offlineimap</B
  67 >  [-1] [-P <TT
  68 CLASS="REPLACEABLE"
  69 ><I
  70 >profiledir</I
  71 ></TT
  72 >] [-a <TT
  73 CLASS="REPLACEABLE"
  74 ><I
  75 >accountlist</I
  76 ></TT
  77 >] [-c <TT
  78 CLASS="REPLACEABLE"
  79 ><I
  80 >configfile</I
  81 ></TT
  82 >] [-d <TT
  83 CLASS="REPLACEABLE"
  84 ><I
  85 >debugtype[,...]</I
  86 ></TT
  87 >] [-o] [-u <TT
  88 CLASS="REPLACEABLE"
  89 ><I
  90 >interface</I
  91 ></TT
  92 >]</P
  93 ><P
  94 ><B
  95 CLASS="COMMAND"
  96 >offlineimap</B
  97 >   -h | --help </P
  98 ></DIV
  99 ><DIV
 100 CLASS="REFSECT1"
 101 ><A
 102 NAME="AEN38"
 103 ></A
 104 ><H2
 105 >Description</H2
 106 ><P
 107 ><SPAN
 108 CLASS="APPLICATION"
 109 >OfflineIMAP</SPAN
 110 > is  a  tool  to  simplify  your  e-mail
 111         reading.  With <SPAN
 112 CLASS="APPLICATION"
 113 >OfflineIMAP</SPAN
 114 >, you can read the same mailbox
 115         from multiple computers.  You get a current copy of your
 116         messages on each computer, and changes you make one place will be
 117         visible on all other systems.  For instance, you can delete a message
 118         on your home computer, and it will appear deleted on your work
 119         computer as well.  <SPAN
 120 CLASS="APPLICATION"
 121 >OfflineIMAP</SPAN
 122 > is also useful if you want to
 123         use a mail reader that does not have IMAP support, has poor IMAP
 124         support, or does not provide disconnected operation.
 125       </P
 126 ><P
 127 ><SPAN
 128 CLASS="APPLICATION"
 129 >OfflineIMAP</SPAN
 130 > is <SPAN
 131 CLASS="emphasis"
 132 ><I
 133 CLASS="EMPHASIS"
 134 >FAST</I
 135 ></SPAN
 136 >; it synchronizes
 137         my two accounts with over 50 folders in 3 seconds.  Other
 138         similar tools might take over a minute, and achieve a
 139         less-reliable result.  Some mail readers can take over 10
 140         minutes to do the same thing, and some don't even support it
 141         at all.  Unlike other mail tools, <SPAN
 142 CLASS="APPLICATION"
 143 >OfflineIMAP</SPAN
 144 > features a
 145         multi-threaded synchronization algorithm that can dramatically
 146         speed up performance in many situations by synchronizing
 147         several different things simultaneously.
 148       </P
 149 ><P
 150 ><SPAN
 151 CLASS="APPLICATION"
 152 >OfflineIMAP</SPAN
 153 > is <SPAN
 154 CLASS="emphasis"
 155 ><I
 156 CLASS="EMPHASIS"
 157 >FLEXIBLE</I
 158 ></SPAN
 159 >; you can
 160         customize which folders are synced via regular expressions,
 161         lists, or Python expressions; a versatile and comprehensive
 162         configuration file is used to control behavior; two user
 163         interfaces are built-in; fine-tuning of synchronization
 164         performance is possible; internal or external automation is
 165         supported; SSL and PREAUTH tunnels are both supported; offline
 166         (or "unplugged") reading is supported; and esoteric IMAP
 167         features are supported to ensure compatibility with the widest
 168         variety of IMAP servers.
 169       </P
 170 ><P
 171 ><SPAN
 172 CLASS="APPLICATION"
 173 >OfflineIMAP</SPAN
 174 > is <SPAN
 175 CLASS="emphasis"
 176 ><I
 177 CLASS="EMPHASIS"
 178 >SAFE</I
 179 ></SPAN
 180 >; it uses an
 181         algorithm designed to prevent mail loss at all costs.  Because
 182         of the design of this algorithm, even programming errors
 183         should not result in loss of mail.  I am so confident in the
 184         algorithm that I use my own personal and work accounts for
 185         testing of <SPAN
 186 CLASS="APPLICATION"
 187 >OfflineIMAP</SPAN
 188 > pre-release, development, and beta
 189         releases.  Of course, legally speaking, <SPAN
 190 CLASS="APPLICATION"
 191 >OfflineIMAP</SPAN
 192 > comes
 193         with no warranty, so I am not responsible if this turns out
 194         to be wrong.
 195       </P
 196 ><DIV
 197 CLASS="REFSECT2"
 198 ><A
 199 NAME="AEN56"
 200 ></A
 201 ><H3
 202 >Method of Operation</H3
 203 ><P
 204 ><SPAN
 205 CLASS="APPLICATION"
 206 >OfflineIMAP</SPAN
 207 > operates by maintaining a hierarchy of
 208           mail folders in Maildir format locally.  Your own mail
 209           reader will read mail from this tree, and need never know
 210           that the mail comes from IMAP.  <SPAN
 211 CLASS="APPLICATION"
 212 >OfflineIMAP</SPAN
 213 > will detect
 214           changes to the mail folders on your IMAP server and your own
 215           computer and bi-directionally synchronize them, copying,
 216           marking, and deleting messages as necessary.
 217         </P
 218 ></DIV
 219 ></DIV
 220 ><DIV
 221 CLASS="REFSECT1"
 222 ><A
 223 NAME="AEN61"
 224 ></A
 225 ><H2
 226 >Quick Start</H2
 227 ><P
 228 >If you have already installed <SPAN
 229 CLASS="APPLICATION"
 230 >OfflineIMAP</SPAN
 231 > system-wide,
 232         or your system adminstrator has done that for you, your task
 233         for setting up <SPAN
 234 CLASS="APPLICATION"
 235 >OfflineIMAP</SPAN
 236 > for the first time is quite
 237         simple.  You just need to set up your configuration file, make
 238         your folder directory, and run it!
 239       </P
 240 ><P
 241 >You can quickly set up your configuration file.  The distribution
 242           includes a file <TT
 243 CLASS="FILENAME"
 244 >offlineimap.conf.minimal</TT
 245 >
 246           (Debian users
 247           may find this at
 248           <TT
 249 CLASS="FILENAME"
 250 >/usr/share/doc/offlineimap/examples/offlineimap.conf.minimal</TT
 251 >) that is a basic example of setting of <SPAN
 252 CLASS="APPLICATION"
 253 >OfflineIMAP</SPAN
 254 >.  You can
 255           simply copy this file into your home directory and name it
 256           <TT
 257 CLASS="FILENAME"
 258 >.offlineimaprc</TT
 259 > (note the leading period).  A
 260           command such as <B
 261 CLASS="COMMAND"
 262 >cp offlineimap.conf.minimal ~/.offlineimaprc</B
 263 > will do it.  Or, if you prefer, you can just copy this text to
 264           <TT
 265 CLASS="FILENAME"
 266 >~/.offlineimaprc</TT
 267 >:
 268         </P
 269 ><PRE
 270 CLASS="PROGRAMLISTING"
 271 >[general]
 272 accounts = Test
 273
 274 [Test]
 275 localfolders = ~/Test
 276 remotehost = examplehost
 277 remoteuser = jgoerzen</PRE
 278 ><P
 279 >Now, edit the <TT
 280 CLASS="FILENAME"
 281 >~/.offlineimaprc</TT
 282 > file with
 283           your favorite editor.  All you have to do is specify a directory
 284           for your folders to be in (on the <SPAN
 285 CLASS="PROPERTY"
 286 >localfolders</SPAN
 287 >
 288           line), the host name of your IMAP server (on the
 289           <SPAN
 290 CLASS="PROPERTY"
 291 >remotehost</SPAN
 292 > line), and your login name on
 293           the remote (on the <SPAN
 294 CLASS="PROPERTY"
 295 >remoteuser</SPAN
 296 > line).  That's
 297           it!</P
 298 ><P
 299 >To run <SPAN
 300 CLASS="APPLICATION"
 301 >OfflineIMAP</SPAN
 302 >, you just have to say
 303           <B
 304 CLASS="COMMAND"
 305 >offlineimap</B
 306 > -- it will fire up, ask you for
 307           a login password if necessary, synchronize your folders, and exit.
 308           See?  You can just throw away the rest of this finely-crafted,
 309           perfectly-honed manual!  Of course, if you want to see how you can
 310           make <SPAN
 311 CLASS="APPLICATION"
 312 >OfflineIMAP</SPAN
 313 > FIVE TIMES FASTER FOR JUST $19.95 (err, well,
 314           $0), you have to read on!
 315         </P
 316 ></DIV
 317 ><DIV
 318 CLASS="REFSECT1"
 319 ><A
 320 NAME="AEN83"
 321 ></A
 322 ><H2
 323 >Installation</H2
 324 ><P
 325 >If you are reading this document via the "man" command, it is
 326         likely
 327         that you have no installation tasks to perform; your system
 328         administrator has already installed it.  If you need to install it
 329         yourself, you have three options: a system-wide installation with
 330         Debian, system-wide installation with other systems, and a single-user
 331         installation.  You can download the latest version of <SPAN
 332 CLASS="APPLICATION"
 333 >OfflineIMAP</SPAN
 334 > from
 335         <A
 336 HREF="http://quux.org/devel/offlineimap/"
 337 TARGET="_top"
 338 >the <SPAN
 339 CLASS="APPLICATION"
 340 >OfflineIMAP</SPAN
 341 >
 342         website</A
 343 >.
 344       </P
 345 ><DIV
 346 CLASS="REFSECT2"
 347 ><A
 348 NAME="AEN89"
 349 ></A
 350 ><H3
 351 >Prerequisites</H3
 352 ><P
 353 >In order to use <SPAN
 354 CLASS="APPLICATION"
 355 >OfflineIMAP</SPAN
 356 >, you need to have these conditions
 357           satisfied:
 358         </P
 359 ><P
 360 ></P
 361 ><UL
 362 ><LI
 363 ><P
 364 >Your mail server must support IMAP.  Most Internet Service
 365               Providers
 366               and corporate networks do, and most operating systems
 367               have an IMAP
 368               implementation readily available.
 369             </P
 370 ></LI
 371 ><LI
 372 ><P
 373 >             You must have Python version 2.2.1 or above installed.
 374               If you are
 375               running on Debian GNU/Linux, this requirement will automatically be
 376               taken care of for you.  If you do not have Python already, check with
 377               your system administrator or operating system vendor; or, download it from
 378               <A
 379 HREF="http://www.python.org/"
 380 TARGET="_top"
 381 >the Python website</A
 382 >.
 383               If you intend to use the Tk interface, you must have Tkinter
 384                 (python-tk) installed.  If you intend to use the SSL interface, your
 385                 Python must have been built with SSL support.
 386             </P
 387 ></LI
 388 ><LI
 389 ><P
 390 >             Have a mail reader that supports the Maildir mailbox format.  Most
 391               modern mail readers have this support built-in, so you can choose from
 392               a wide variety of mail servers.  This format is also known as the
 393               "qmail" format, so any mail reader compatible with it will work with
 394               <SPAN
 395 CLASS="APPLICATION"
 396 >OfflineIMAP</SPAN
 397 >.
 398         </P
 399 ></LI
 400 ></UL
 401 ></DIV
 402 ><DIV
 403 CLASS="REFSECT2"
 404 ><A
 405 NAME="AEN102"
 406 ></A
 407 ><H3
 408 >System-Wide Installation, Debian</H3
 409 ><P
 410 >         If you are tracking Debian unstable, you may install
 411           <SPAN
 412 CLASS="APPLICATION"
 413 >OfflineIMAP</SPAN
 414 > by simply running the following command as root:
 415         </P
 416 ><P
 417 >         <B
 418 CLASS="COMMAND"
 419 >apt-get install offlineimap</B
 420 >
 421         </P
 422 ><P
 423 >         If you are not tracking Debian unstable, download the Debian .deb
 424           package from the <A
 425 HREF="http://quux.org/devel/offlineimap/"
 426 TARGET="_top"
 427 ><SPAN
 428 CLASS="APPLICATION"
 429 >OfflineIMAP</SPAN
 430 > website</A
 431 >
 432           and then run <B
 433 CLASS="COMMAND"
 434 >dpkg -i</B
 435 > to install the downloaded
 436           package.  Then, skip to <A
 437 HREF="#CONFIGURATION"
 438 ><I
 439 >Configruation</I
 440 ></A
 441 > below.  You will type <B
 442 CLASS="COMMAND"
 443 >offlineimap</B
 444 > to
 445           invoke the program.
 446         </P
 447 ></DIV
 448 ><DIV
 449 CLASS="REFSECT2"
 450 ><A
 451 NAME="AEN114"
 452 ></A
 453 ><H3
 454 >System-Wide Installation, Other</H3
 455 ><P
 456 >         Download the tar.gz version of the package from the
 457           <A
 458 HREF="http://quux.org/devel/offlineimap/"
 459 TARGET="_top"
 460 >website</A
 461 >.
 462           Then run
 463           these commands, making sure that you are the "root" user first:
 464         </P
 465 ><PRE
 466 CLASS="PROGRAMLISTING"
 467 >tar -zxvf offlineimap_x.y.z.tar.gz
 468 cd offlineimap-x.y.z
 469 python2.2 setup.py install</PRE
 470 ><P
 471 >On some systems, you will need to use
 472           <B
 473 CLASS="COMMAND"
 474 >python</B
 475 > instead of <B
 476 CLASS="COMMAND"
 477 >python2.2</B
 478 >.
 479           Next, proceed to <A
 480 HREF="#CONFIGURATION"
 481 ><I
 482 >Configruation</I
 483 ></A
 484 > below.  You will type <B
 485 CLASS="COMMAND"
 486 >offlineimap</B
 487 > to
 488           invoke the program.
 489         </P
 490 ></DIV
 491 ><DIV
 492 CLASS="REFSECT2"
 493 ><A
 494 NAME="AEN124"
 495 ></A
 496 ><H3
 497 >Single-Account Installation</H3
 498 ><P
 499 >         Download the tar.gz version of the package from the
 500           <A
 501 HREF="http://quux.org/devel/offlineimap/"
 502 TARGET="_top"
 503 >website</A
 504 >.
 505           Then run these commands:
 506         </P
 507 ><PRE
 508 CLASS="PROGRAMLISTING"
 509 >tar -zxvf offlineimap_x.y.z.tar.gz
 510 cd offlineimap-x.y.z</PRE
 511 ><P
 512 >When you want to run <SPAN
 513 CLASS="APPLICATION"
 514 >OfflineIMAP</SPAN
 515 >, you will issue the
 516           <B
 517 CLASS="COMMAND"
 518 >cd</B
 519 > command as above and then type
 520           <B
 521 CLASS="COMMAND"
 522 >./offlineimap.py</B
 523 >; there is no installation
 524           step necessary.
 525         </P
 526 ></DIV
 527 ></DIV
 528 ><DIV
 529 CLASS="REFSECT1"
 530 ><A
 531 NAME="CONFIGURATION"
 532 ></A
 533 ><H2
 534 >Configruation</H2
 535 ><P
 536 >       <SPAN
 537 CLASS="APPLICATION"
 538 >OfflineIMAP</SPAN
 539 > is regulated by a configuration file that is normally
 540         stored in <TT
 541 CLASS="FILENAME"
 542 >~/.offlineimaprc</TT
 543 >.  <SPAN
 544 CLASS="APPLICATION"
 545 >OfflineIMAP</SPAN
 546 >
 547         ships with a file named <TT
 548 CLASS="FILENAME"
 549 >offlineimap.conf</TT
 550 >
 551         that you should copy to that location and then edit.  This file is
 552         vital to proper operation of the system; it sets everything you need
 553         to run <SPAN
 554 CLASS="APPLICATION"
 555 >OfflineIMAP</SPAN
 556 >.  Full documentation for the configuration file
 557         is included within the sample file.
 558       </P
 559 ><P
 560 >       <SPAN
 561 CLASS="APPLICATION"
 562 >OfflineIMAP</SPAN
 563 > also ships a file named
 564         <TT
 565 CLASS="FILENAME"
 566 >offlineimap.conf.minimal</TT
 567 > that you can also try.
 568           It's useful if you want to get started with
 569           the most basic feature set, and you can read about other features
 570           later with <TT
 571 CLASS="FILENAME"
 572 >offlineimap.conf</TT
 573 >.
 574       </P
 575 ></DIV
 576 ><DIV
 577 CLASS="REFSECT1"
 578 ><A
 579 NAME="AEN145"
 580 ></A
 581 ><H2
 582 >Options</H2
 583 ><P
 584 >       Most configuration is done via the configuration file.  Nevertheless,
 585         there are a few command-line options that you may set for
 586         <SPAN
 587 CLASS="APPLICATION"
 588 >OfflineIMAP</SPAN
 589 >.
 590       </P
 591 ><P
 592 ></P
 593 ><DIV
 594 CLASS="VARIABLELIST"
 595 ><DL
 596 ><DT
 597 >-1</DT
 598 ><DD
 599 ><P
 600 >Disable most multithreading operations and use
 601             solely a single-connection
 602             sync.  This effectively sets the <SPAN
 603 CLASS="PROPERTY"
 604 >maxsyncaccounts</SPAN
 605 >
 606             and all <SPAN
 607 CLASS="PROPERTY"
 608 >maxconnections</SPAN
 609 > configuration file
 610             variables to 1.
 611           </P
 612 ></DD
 613 ><DT
 614 >-P <TT
 615 CLASS="REPLACEABLE"
 616 ><I
 617 >profiledir</I
 618 ></TT
 619 ></DT
 620 ><DD
 621 ><P
 622 >Sets <SPAN
 623 CLASS="APPLICATION"
 624 >OfflineIMAP</SPAN
 625 > into profile mode.  The program
 626             will create <TT
 627 CLASS="REPLACEABLE"
 628 ><I
 629 >profiledir</I
 630 ></TT
 631 >
 632             (it must not already exist).  As it runs, Python profiling
 633             information
 634             about each thread is logged into profiledir.  Please note: This option
 635             is present for debugging and optimization only, and should NOT be used
 636             unless you have a specific reason to do so.  It will significantly
 637             slow program performance, may reduce reliability, and can generate
 638             huge amounts of data.  You must use the <TT
 639 CLASS="OPTION"
 640 >-1</TT
 641 > option when
 642             you use <TT
 643 CLASS="OPTION"
 644 >-P</TT
 645 >.
 646           </P
 647 ></DD
 648 ><DT
 649 >-a <TT
 650 CLASS="REPLACEABLE"
 651 ><I
 652 >accountlist</I
 653 ></TT
 654 ></DT
 655 ><DD
 656 ><P
 657 >Overrides the <SPAN
 658 CLASS="PROPERTY"
 659 >accounts</SPAN
 660 > option
 661             in the <SPAN
 662 CLASS="PROPERTY"
 663 >general</SPAN
 664 > section of the configuration
 665             file.  You might use this to exclude certain accounts, or to sync
 666             some accounts that you normally prefer not to.  Separate the
 667             accounts by commas, and use no embedded spaces.
 668           </P
 669 ></DD
 670 ><DT
 671 >-c <TT
 672 CLASS="REPLACEABLE"
 673 ><I
 674 >configfile</I
 675 ></TT
 676 ></DT
 677 ><DD
 678 ><P
 679 >Specifies a configuration file to use in lieu of
 680             the default, <TT
 681 CLASS="FILENAME"
 682 >~/.offlineimaprc</TT
 683 >.
 684           </P
 685 ></DD
 686 ><DT
 687 >-d <TT
 688 CLASS="REPLACEABLE"
 689 ><I
 690 >debugtype[,...]</I
 691 ></TT
 692 ></DT
 693 ><DD
 694 ><P
 695 >Enables debugging for OfflineIMAP.  This is useful if
 696             you are trying to track down a malfunction or figure out what is going
 697             on under the hood.  I suggest that you use this with
 698             <TT
 699 CLASS="OPTION"
 700 >-1</TT
 701 > to make the results more sensible.</P
 702 ><P
 703 ><TT
 704 CLASS="OPTION"
 705 >-d</TT
 706 > requires one or more debugtypes,
 707               separated by commas.  These define what exactly will be
 708               debugged, and include two options: <SPAN
 709 CLASS="PROPERTY"
 710 >imap</SPAN
 711 >
 712               and <SPAN
 713 CLASS="PROPERTY"
 714 >maildir</SPAN
 715 >.  The <SPAN
 716 CLASS="PROPERTY"
 717 >imap</SPAN
 718 >
 719               option will enable IMAP protocol stream and parsing debugging.  Note
 720               that the output may contain passwords, so take care to remove that
 721               from the debugging output before sending it to anyone else.  The
 722               <SPAN
 723 CLASS="PROPERTY"
 724 >maildir</SPAN
 725 > option will enable debugging for
 726               certain Maildir operations.
 727             </P
 728 ></DD
 729 ><DT
 730 >-o</DT
 731 ><DD
 732 ><P
 733 >Run only once, ignoring all
 734               <SPAN
 735 CLASS="PROPERTY"
 736 >autorefresh</SPAN
 737 > settings in the configuration
 738               file.</P
 739 ></DD
 740 ><DT
 741 >-h, --help</DT
 742 ><DD
 743 ><P
 744 >Show summary of options.</P
 745 ></DD
 746 ><DT
 747 >-u <TT
 748 CLASS="REPLACEABLE"
 749 ><I
 750 >interface</I
 751 ></TT
 752 ></DT
 753 ><DD
 754 ><P
 755 >Specifies an alternative user interface module
 756               to use.  This overrides the defailt specified in the
 757               configuration file.  The pre-defined options are listed in
 758               the User Interfaces section.</P
 759 ></DD
 760 ></DL
 761 ></DIV
 762 ></DIV
 763 ><DIV
 764 CLASS="REFSECT1"
 765 ><A
 766 NAME="AEN205"
 767 ></A
 768 ><H2
 769 >User Interfaces</H2
 770 ><P
 771 ><SPAN
 772 CLASS="APPLICATION"
 773 >OfflineIMAP</SPAN
 774 > has a pluggable user interface system that lets you choose how the
 775         program communicates information to you.  There are two graphical
 776         interfaces, two terminal interfaces, and two noninteractive interfaces
 777         suitable for scripting or logging purposes.  The
 778         <SPAN
 779 CLASS="PROPERTY"
 780 >ui</SPAN
 781 > option in the configuration file specifies
 782         user interface preferences.  The <TT
 783 CLASS="OPTION"
 784 >-u</TT
 785 > command-line
 786         option can override the configuration file setting.  The available
 787         values for the configuration file or command-line are described
 788         in this section.</P
 789 ><DIV
 790 CLASS="REFSECT2"
 791 ><A
 792 NAME="AEN211"
 793 ></A
 794 ><H3
 795 >Tk.Blinkenlights</H3
 796 ><P
 797 >Tk.Blinkenlights is an interface designed to be sleek, fun to watch, and
 798           informative of the overall picture of what <SPAN
 799 CLASS="APPLICATION"
 800 >OfflineIMAP</SPAN
 801 >
 802           is doing.  I consider it to be the best general-purpose interface in
 803           <SPAN
 804 CLASS="APPLICATION"
 805 >OfflineIMAP</SPAN
 806 >.
 807         </P
 808 ><P
 809 >         Tk.Blinkenlights contains, by default, a small window with a row of
 810           LEDs, a small log, and a row of command buttons.
 811           The total size of the window is
 812           very small, so it uses little desktop space, yet it is quite
 813           functional.  The optional, toggleable, log shows more
 814           detail about what is happening and is color-coded to match the color
 815           of the lights.
 816         </P
 817 ><P
 818 >         Tk.Blinkenlights is the only user interface that has configurable
 819           parameters; see the example <TT
 820 CLASS="FILENAME"
 821 >offlineimap.conf</TT
 822 >
 823           for more details.
 824         </P
 825 ><P
 826 >         Each light in the Blinkenlights interface represents a thread
 827           of execution -- that is, a particular task that <SPAN
 828 CLASS="APPLICATION"
 829 >OfflineIMAP</SPAN
 830 >
 831           is performing right now.  The colors indicate what task
 832           the particular thread is performing, and are as follows:
 833         </P
 834 ><P
 835 ></P
 836 ><DIV
 837 CLASS="VARIABLELIST"
 838 ><DL
 839 ><DT
 840 >Black</DT
 841 ><DD
 842 ><P
 843 >indicates that this light's thread has terminated; it will light up
 844               again later when new threads start up.  So, black indicates no
 845               activity.
 846             </P
 847 ></DD
 848 ><DT
 849 >Red (Meaning 1)</DT
 850 ><DD
 851 ><P
 852 >is the color of the main program's thread, which basically does
 853               nothing but monitor the others.  It might remind you of HAL 9000 in
 854               [<SPAN
 855 CLASS="CITATION"
 856 >2001</SPAN
 857 >].
 858             </P
 859 ></DD
 860 ><DT
 861 >Gray</DT
 862 ><DD
 863 ><P
 864 >indicates that the thread is establishing a new connection to the IMAP
 865               server.
 866             </P
 867 ></DD
 868 ><DT
 869 >Purple</DT
 870 ><DD
 871 ><P
 872 >is the color of an account synchronization thread that is monitoring
 873               the progress of the folders in that account (not generating any I/O).
 874             </P
 875 ></DD
 876 ><DT
 877 >Cyan</DT
 878 ><DD
 879 ><P
 880 >indicates that the thread is syncing a folder.
 881             </P
 882 ></DD
 883 ><DT
 884 >Green</DT
 885 ><DD
 886 ><P
 887 >means that a folder's message list is being loaded.
 888             </P
 889 ></DD
 890 ><DT
 891 >Blue</DT
 892 ><DD
 893 ><P
 894 >is the color of a message synchronization controller thread.
 895             </P
 896 ></DD
 897 ><DT
 898 >Orange</DT
 899 ><DD
 900 ><P
 901 >indicates that an actual message is being copied.
 902               (We use fuschia for fake messages.)
 903             </P
 904 ></DD
 905 ><DT
 906 >Red (meaning 2)</DT
 907 ><DD
 908 ><P
 909 >indicates that a message is being deleted.
 910             </P
 911 ></DD
 912 ><DT
 913 >Yellow / bright orange</DT
 914 ><DD
 915 ><P
 916 >indicates that message flags are being added.
 917             </P
 918 ></DD
 919 ><DT
 920 >Pink / bright red</DT
 921 ><DD
 922 ><P
 923 >indicates that message flags are being removed.
 924             </P
 925 ></DD
 926 ><DT
 927 >Red / Black Flashing</DT
 928 ><DD
 929 ><P
 930 >corresponds to the countdown timer that runs between
 931               synchronizations.
 932             </P
 933 ></DD
 934 ></DL
 935 ></DIV
 936 ><P
 937 >The name of this interfaces derives from a bit of computer
 938           history.  Eric Raymond's [<SPAN
 939 CLASS="CITATION"
 940 >Jargon File</SPAN
 941 >] defines
 942           <I
 943 CLASS="FIRSTTERM"
 944 >blinkenlights</I
 945 >, in part, as:
 946         </P
 947 ><A
 948 NAME="AEN274"
 949 ></A
 950 ><BLOCKQUOTE
 951 CLASS="BLOCKQUOTE"
 952 ><P
 953 >Front-panel diagnostic
 954             lights on a computer, esp. a dinosaur. Now that dinosaurs are rare,
 955             this term usually refers to status lights on a modem, network hub, or
 956             the like.
 957           </P
 958 ><P
 959 >           This term derives from the last word of the famous blackletter-Gothic
 960             sign in mangled pseudo-German that once graced about half the computer
 961             rooms in the English-speaking world. One version ran in its entirety as
 962             follows:
 963           </P
 964 ><P
 965 >           <SPAN
 966 CLASS="emphasis"
 967 ><I
 968 CLASS="EMPHASIS"
 969 >ACHTUNG!  ALLES LOOKENSPEEPERS!</I
 970 ></SPAN
 971 >
 972           </P
 973 ><P
 974 >           Das computermachine ist nicht fuer gefingerpoken und mittengrabben.
 975             Ist easy schnappen der springenwerk, blowenfusen und poppencorken
 976             mit spitzensparken.  Ist nicht fuer gewerken bei das dumpkopfen.
 977             Das rubbernecken sichtseeren keepen das cotten-pickenen hans in das
 978             pockets muss; relaxen und watchen das blinkenlichten.
 979           </P
 980 ></BLOCKQUOTE
 981 ></DIV
 982 ><DIV
 983 CLASS="REFSECT2"
 984 ><A
 985 NAME="AEN280"
 986 ></A
 987 ><H3
 988 >Curses.Blinkenlights</H3
 989 ><P
 990 >         Curses.Blinkenlights is an interface very similar to Tk.Blinkenlights,
 991           but is designed to be run in a console window (an xterm, Linux virtual
 992           terminal, etc.)  Since it doesn't have access to graphics, it isn't
 993           quite as pretty, but it still gets the job done.
 994         </P
 995 ><P
 996 >Please see the Tk.Blinkenlights section above for more
 997           information about the colors used in this interface.
 998         </P
 999 ></DIV
1000 ><DIV
1001 CLASS="REFSECT2"
1002 ><A
1003 NAME="AEN284"
1004 ></A
1005 ><H3
1006 >Tk.VerboseUI</H3
1007 ><P
1008 >         Tk.VerboseUI (formerly known as Tk.TkUI) is a graphical interface
1009           that presents a variable-sized window.  In the window, each
1010           currently-executing thread has a section where its name and current
1011           status are displayed.  This interface is best suited to people running
1012           on slower connections, as you get a lot of detail, but for fast
1013           connections, the detail may go by too quickly to be useful.  People
1014           with fast connections may wish to use Tk.Blinkenlights instead.
1015         </P
1016 ></DIV
1017 ><DIV
1018 CLASS="REFSECT2"
1019 ><A
1020 NAME="AEN287"
1021 ></A
1022 ><H3
1023 >TTY.TTYUI</H3
1024 ><P
1025 >         TTY.TTYUI interface is for people running in basic, non-color terminals.  It
1026           prints out basic status messages and is generally friendly to use on a console
1027           or xterm.
1028         </P
1029 ></DIV
1030 ><DIV
1031 CLASS="REFSECT2"
1032 ><A
1033 NAME="AEN290"
1034 ></A
1035 ><H3
1036 >Noninteractive.Basic</H3
1037 ><P
1038 >         Noninteractive.Basic is designed for situations in which <SPAN
1039 CLASS="APPLICATION"
1040 >OfflineIMAP</SPAN
1041 >
1042           will be run non-attended and the status of its execution will be
1043           logged.  You might use it, for instance, to have the system run
1044           automatically and
1045           e-mail you the results of the synchronization.  This user interface
1046           is not capable of reading a password from the keyboard; account
1047           passwords must be specified using one of the configuration file options.
1048         </P
1049 ></DIV
1050 ><DIV
1051 CLASS="REFSECT2"
1052 ><A
1053 NAME="AEN294"
1054 ></A
1055 ><H3
1056 >Noninteractive.Quiet</H3
1057 ><P
1058 >         Noninteractive.Quiet is designed for non-attended running in situations
1059           where normal status messages are not desired.  It will output nothing
1060           except errors and serious warnings.  Like Noninteractive.Basic,
1061           this user interface
1062           is not capable of reading a password from the keyboard; account
1063           passwords must be specified using one of the configuration file options.
1064         </P
1065 ></DIV
1066 ></DIV
1067 ><DIV
1068 CLASS="REFSECT1"
1069 ><A
1070 NAME="AEN297"
1071 ></A
1072 ><H2
1073 >Examples</H2
1074 ><P
1075 >Here are some example configurations for various situations.
1076         Please e-mail any other examples you have that may be useful to
1077         me.
1078       </P
1079 ><DIV
1080 CLASS="REFSECT2"
1081 ><A
1082 NAME="AEN300"
1083 ></A
1084 ><H3
1085 >Multiple Accounts with Mutt</H3
1086 ><P
1087 >         This example shows you how to set up <SPAN
1088 CLASS="APPLICATION"
1089 >OfflineIMAP</SPAN
1090 > to
1091           synchronize multiple accounts with the mutt mail reader.
1092         </P
1093 ><P
1094 >         Start by creating a directory to hold your folders by running
1095           <B
1096 CLASS="COMMAND"
1097 >mkdir ~/Mail</B
1098 >.  Then, in your
1099           <TT
1100 CLASS="FILENAME"
1101 >~/.offlineimaprc</TT
1102 >, specify:
1103         </P
1104 ><PRE
1105 CLASS="PROGRAMLISTING"
1106 >accounts = Personal, Work</PRE
1107 ><P
1108 >         Make sure that you have both a <SPAN
1109 CLASS="PROPERTY"
1110 >[Personal]</SPAN
1111 >
1112           and a <SPAN
1113 CLASS="PROPERTY"
1114 >[Work]</SPAN
1115 > section, each with different
1116           <SPAN
1117 CLASS="PROPERTY"
1118 >localfolder</SPAN
1119 > path names.  Also, make sure
1120           to enable <SPAN
1121 CLASS="PROPERTY"
1122 >[mbnames]</SPAN
1123 >.
1124         </P
1125 ><P
1126 >         In each account section, write something like this:
1127         </P
1128 ><PRE
1129 CLASS="PROGRAMLISTING"
1130 >localfolders = ~/Mail/Personal</PRE
1131 ><P
1132 >         Finally, add these lines to your <TT
1133 CLASS="FILENAME"
1134 >~/.muttrc</TT
1135 >:
1136         </P
1137 ><PRE
1138 CLASS="PROGRAMLISTING"
1139 >source ~/path-to-mbnames-muttrc-mailboxes
1140 folder-hook Personal set from="youremail@personal.com"
1141 folder-hook Work set from="youremail@work.com"
1142 set mbox_type=Maildir
1143 set folder=$HOME/Mail
1144 spoolfile=+Personal/INBOX</PRE
1145 ><P
1146 >         That's it!
1147         </P
1148 ></DIV
1149 ><DIV
1150 CLASS="REFSECT2"
1151 ><A
1152 NAME="AEN319"
1153 ></A
1154 ><H3
1155 >UW-IMAPD and References</H3
1156 ><P
1157 >Some users with a UW-IMAPD server need to use <SPAN
1158 CLASS="APPLICATION"
1159 >OfflineIMAP</SPAN
1160 >'s
1161           "reference" feature to get at their mailboxes, specifying a reference
1162           of "~/Mail" or "#mh/" depending on the configuration.  The below
1163           configuration from docwhat@gerf.org
1164           shows using a <SPAN
1165 CLASS="PROPERTY"
1166 >reference</SPAN
1167 > of Mail, a <SPAN
1168 CLASS="PROPERTY"
1169 >nametrans</SPAN
1170 >
1171           that strips
1172           the leading Mail/ off incoming folder names, and a
1173           <SPAN
1174 CLASS="PROPERTY"
1175 >folderfilter</SPAN
1176 > that
1177           limits the folders synced to just three.
1178         </P
1179 ><PRE
1180 CLASS="PROGRAMLISTING"
1181 >[Gerf]
1182 localfolders = ~/Mail
1183 remotehost = gerf.org
1184 ssl = yes
1185 remoteuser = docwhat
1186 reference = Mail
1187 # Trims off the preceeding Mail on all the folder names.
1188 nametrans = lambda foldername: \
1189             re.sub('^Mail/', '', foldername)
1190 # Yeah, you have to mention the Mail dir, even though it
1191 # would seem intuitive that reference would trim it.
1192 folderfilter = lambda foldername: foldername in [
1193       'Mail/INBOX',
1194       'Mail/list/zaurus-general',
1195       'Mail/list/zaurus-dev',
1196       ]
1197 maxconnections = 1
1198 holdconnectionopen = no</PRE
1199 ></DIV
1200 ><DIV
1201 CLASS="REFSECT2"
1202 ><A
1203 NAME="AEN327"
1204 ></A
1205 ><H3
1206 >pythonfile Configuration File Option</H3
1207 ><P
1208 >You can have <SPAN
1209 CLASS="APPLICATION"
1210 >OfflineIMAP</SPAN
1211 >
1212           load up a Python file before evaluating the
1213           configuration file options that are Python expressions.  This example
1214           is based on one supplied by Tommi Virtanen for this feature.
1215         </P
1216 ><P
1217 >         In <TT
1218 CLASS="FILENAME"
1219 >~/.offlineimap.rc</TT
1220 >, he adds these options:
1221         </P
1222 ><PRE
1223 CLASS="PROGRAMLISTING"
1224 >[general]
1225 pythonfile=~/.offlineimap.py
1226 [foo]
1227 foldersort=mycmp</PRE
1228 ><P
1229 >         Then, the <TT
1230 CLASS="FILENAME"
1231 >~/.offlineimap.py</TT
1232 > file will
1233           contain:
1234         </P
1235 ><PRE
1236 CLASS="PROGRAMLISTING"
1237 >prioritized = ['INBOX', 'personal', 'announce', 'list']
1238
1239 def mycmp(x, y):
1240    for prefix in prioritized:
1241        if x.startswith(prefix):
1242            return -1
1243        elif y.startswith(prefix):
1244            return +1
1245    return cmp(x, y)
1246
1247 def test_mycmp():
1248    import os, os.path
1249    folders=os.listdir(os.path.expanduser('~/data/mail/tv@hq.yok.utu.fi'))
1250    folders.sort(mycmp)
1251    print folders</PRE
1252 ><P
1253 >         This code snippet illustrates how the <SPAN
1254 CLASS="PROPERTY"
1255 >foldersort</SPAN
1256 >
1257           option can be customized with a Python function from the
1258           <SPAN
1259 CLASS="PROPERTY"
1260 >pythonfile</SPAN
1261 > to always synchronize certain
1262           folders first.
1263         </P
1264 ></DIV
1265 ></DIV
1266 ><DIV
1267 CLASS="REFSECT1"
1268 ><A
1269 NAME="AEN340"
1270 ></A
1271 ><H2
1272 >Errors</H2
1273 ><P
1274 >       If you get one of some frequently-encountered or confusing errors,
1275         please check this section.
1276       </P
1277 ><DIV
1278 CLASS="REFSECT2"
1279 ><A
1280 NAME="AEN343"
1281 ></A
1282 ><H3
1283 >UID validity problem for folder</H3
1284 ><P
1285 >IMAP servers use a unique ID (UID) to refer to a specific message.
1286           This number is guaranteed to be unique to a particular message
1287           <SPAN
1288 CLASS="emphasis"
1289 ><I
1290 CLASS="EMPHASIS"
1291 >forever</I
1292 ></SPAN
1293 >.
1294           No other message in the same folder will ever get the same
1295           UID.  UIDs are an integral part of <SPAN
1296 CLASS="APPLICATION"
1297 >OfflineIMAP</SPAN
1298 >'s synchronization
1299           scheme; they are used to match up messages on your computer to
1300           messages on the server.
1301         </P
1302 ><P
1303 >         Sometimes, the UIDs on the server might get reset.  Usually this will
1304           happen if you delete and then recreate a folder.  When you create a
1305           folder, the server will often start the UID back from 1.  But
1306           <SPAN
1307 CLASS="APPLICATION"
1308 >OfflineIMAP</SPAN
1309 > might still have the UIDs from the previous folder by the
1310           same name stored.  <SPAN
1311 CLASS="APPLICATION"
1312 >OfflineIMAP</SPAN
1313 > will detect this condition and skip the
1314           folder.  This is GOOD, because it prevents data loss.
1315         </P
1316 ><P
1317 >         You can fix it by removing your local folder and cache data.  For
1318           instance, if your folders are under <TT
1319 CLASS="FILENAME"
1320 >~/Folders</TT
1321 >
1322           and the folder with the problem is INBOX, you'd type this:
1323         </P
1324 ><PRE
1325 CLASS="PROGRAMLISTING"
1326 >rm -r ~/Folders/INBOX
1327 rm -r ~/.offlineimap/AccountName/INBOX</PRE
1328 ><P
1329 >         (Of course, replace AccountName with the account name as specified
1330           in <TT
1331 CLASS="FILENAME"
1332 >~/.offlineimaprc</TT
1333 >).
1334         </P
1335 ><P
1336 >Next time you run <SPAN
1337 CLASS="APPLICATION"
1338 >OfflineIMAP</SPAN
1339 >, it will re-download
1340           the folder with the
1341           new UIDs.  Note that the procedure specified above will lose any local
1342           changes made to the folder.
1343         </P
1344 ><P
1345 >         Some IMAP servers are broken and do not support UIDs properly.  If you
1346           continue to get this error for all your folders even after performing
1347           the above procedure, it is likely that your IMAP server falls into
1348           this category.  <SPAN
1349 CLASS="APPLICATION"
1350 >OfflineIMAP</SPAN
1351 > is incompatible with such servers.
1352           Using <SPAN
1353 CLASS="APPLICATION"
1354 >OfflineIMAP</SPAN
1355 > with them will not destroy any mail, but at the same time,
1356           it will not actually synchronize it either.  (<SPAN
1357 CLASS="APPLICATION"
1358 >OfflineIMAP</SPAN
1359 > will detect
1360           this condition and abort prior to synchronization.)
1361         </P
1362 ></DIV
1363 ></DIV
1364 ><DIV
1365 CLASS="REFSECT1"
1366 ><A
1367 NAME="AEN362"
1368 ></A
1369 ><H2
1370 >Other Frequently Asked Questions</H2
1371 ><P
1372 >There are some other FAQs that might not fit into another section
1373         of the document, so they are discussed here.
1374       </P
1375 ><P
1376 ></P
1377 ><DIV
1378 CLASS="VARIABLELIST"
1379 ><DL
1380 ><DT
1381 >What platforms does <SPAN
1382 CLASS="APPLICATION"
1383 >OfflineIMAP</SPAN
1384 > run on?</DT
1385 ><DD
1386 ><P
1387 >           It should run on most platforms supported by Python, which are quite a
1388             few.
1389           </P
1390 ></DD
1391 ><DT
1392 >I'm using Mutt.  Other IMAP sync programs require me to use "set maildir_trash=yes".  Do I need to do that with <SPAN
1393 CLASS="APPLICATION"
1394 >OfflineIMAP</SPAN
1395 >?</DT
1396 ><DD
1397 ><P
1398 >           No.  <SPAN
1399 CLASS="APPLICATION"
1400 >OfflineIMAP</SPAN
1401 > is smart enough to figure out message deletion without this extra
1402             crutch.  You'll get the best results if you don't use this setting, in
1403             fact.
1404           </P
1405 ></DD
1406 ><DT
1407 >How do I specify the names of my folders?</DT
1408 ><DD
1409 ><P
1410 >           You do not need to.  <SPAN
1411 CLASS="APPLICATION"
1412 >OfflineIMAP</SPAN
1413 > is smart
1414             enough to automatically figure out what folders are present
1415             on the IMAP server and synchronize them.  You can use the
1416             <SPAN
1417 CLASS="PROPERTY"
1418 >folderfilter</SPAN
1419 > and <SPAN
1420 CLASS="PROPERTY"
1421 >foldertrans</SPAN
1422 >
1423             configuration file options to request certain folders and rename them
1424             as they come in if you like.
1425           </P
1426 ></DD
1427 ><DT
1428 >How can I prevent certain folders from being synced?</DT
1429 ><DD
1430 ><P
1431 >           Use the <SPAN
1432 CLASS="PROPERTY"
1433 >folderfilter</SPAN
1434 > option in the configuration file.
1435           </P
1436 ></DD
1437 ><DT
1438 >How can I add or delete a folder?</DT
1439 ><DD
1440 ><P
1441 >           <SPAN
1442 CLASS="APPLICATION"
1443 >OfflineIMAP</SPAN
1444 > does not currently provide this feature, but if you create a new
1445             folder on the IMAP server, it will be created locally automatically.
1446           </P
1447 ></DD
1448 ><DT
1449 >Are there any other warnings that I should be aware of?</DT
1450 ><DD
1451 ><P
1452 >           Yes; see the Notes section below.
1453           </P
1454 ></DD
1455 ><DT
1456 >What is the mailbox name recorder (mbnames) for?</DT
1457 ><DD
1458 ><P
1459 >Some mail readers, such as Mutt, are not capable
1460             of automatically determining the names of your mailboxes.
1461             <SPAN
1462 CLASS="APPLICATION"
1463 >OfflineIMAP</SPAN
1464 > can help these programs by writing the names
1465             of the folders ni a format you specify.  See the example
1466             <TT
1467 CLASS="FILENAME"
1468 >offlineimap.conf</TT
1469 > for details.
1470           </P
1471 ></DD
1472 ><DT
1473 >Can I synchronize multiple accounts with <SPAN
1474 CLASS="APPLICATION"
1475 >OfflineIMAP</SPAN
1476 >?</DT
1477 ><DD
1478 ><P
1479 >Sure.  Just name them all in the
1480             <SPAN
1481 CLASS="PROPERTY"
1482 >accounts</SPAN
1483 > line in the <SPAN
1484 CLASS="PROPERTY"
1485 >general</SPAN
1486 >
1487             section of the configuration file, and add a per-account section
1488             for each one.
1489           </P
1490 ></DD
1491 ><DT
1492 >Does <SPAN
1493 CLASS="APPLICATION"
1494 >OfflineIMAP</SPAN
1495 > support POP?</DT
1496 ><DD
1497 ><P
1498 >No.  POP is not robust enough to do a completely reliable
1499             multi-machine synchronization like <SPAN
1500 CLASS="APPLICATION"
1501 >OfflineIMAP</SPAN
1502 > can do.  <SPAN
1503 CLASS="APPLICATION"
1504 >OfflineIMAP</SPAN
1505 >
1506             will not support it.
1507           </P
1508 ></DD
1509 ><DT
1510 >Does <SPAN
1511 CLASS="APPLICATION"
1512 >OfflineIMAP</SPAN
1513 > support mailbox formats other than Maildir?</DT
1514 ><DD
1515 ><P
1516 >Not at present.  There is no technical reason not to; just no
1517             demand yet.  Maildir is a superior format anyway.
1518           </P
1519 ></DD
1520 ><DT
1521 >[technical] Why are your Maildir message filenames so huge?</DT
1522 ><DD
1523 ><P
1524 ><SPAN
1525 CLASS="APPLICATION"
1526 >OfflineIMAP</SPAN
1527 > has two relevant principles: 1) never modifying your
1528             messages in any way and 2) ensuring 100% reliable synchronizations.
1529             In order to do a reliable sync, <SPAN
1530 CLASS="APPLICATION"
1531 >OfflineIMAP</SPAN
1532 >
1533             must have a way to
1534             uniquely identify each e-mail.  Three pieces of information are
1535             required to do this: your account name, the folder name, and the
1536             message UID.  The account name can be calculated from the path in
1537             which your messages are.  The folder name can usually be as well, BUT
1538             some mail clients move messages between folders by simply moving the
1539             file, leaving the name intact.
1540           </P
1541 ><P
1542 >           So, <SPAN
1543 CLASS="APPLICATION"
1544 >OfflineIMAP</SPAN
1545 > must store both a UID folder ID.  The folder ID is
1546             necessary so <SPAN
1547 CLASS="APPLICATION"
1548 >OfflineIMAP</SPAN
1549 > can detect a message moved to a different
1550             folder.  <SPAN
1551 CLASS="APPLICATION"
1552 >OfflineIMAP</SPAN
1553 > stores the UID (U= number) and an md5sum of the
1554             foldername (FMD5= number) to facilitate this.
1555           </P
1556 ></DD
1557 ><DT
1558 >What is the speed of <SPAN
1559 CLASS="APPLICATION"
1560 >OfflineIMAP</SPAN
1561 >'s sync?</DT
1562 ><DD
1563 ><P
1564 >OfflineIMAP
1565             versions 2.0 and above contain a multithreaded system.  A good way to
1566             experiment is by setting <SPAN
1567 CLASS="PROPERTY"
1568 >maxsyncaccounts</SPAN
1569 > to 3 and <SPAN
1570 CLASS="PROPERTY"
1571 >maxconnections</SPAN
1572 > to 3
1573             in each account clause.
1574           </P
1575 ><P
1576 >This lets OfflineIMAP open up multiple connections simultaneously.
1577             That will let it process multiple folders and messages at once.  In
1578             most cases, this will increase performance of the sync.
1579           </P
1580 ><P
1581 >Don't set the number too high.  If you do that, things might actually
1582             slow down as your link gets saturated.  Also, too many connections can
1583             cause mail servers to have excessive load.  Administrators might take
1584             unkindly to this, and the server might bog down.  There are many
1585             variables in the optimal setting; experimentation may help.
1586           </P
1587 ><P
1588 >An informal benchmark yields these results for my setup:
1589           </P
1590 ><P
1591 ></P
1592 ><UL
1593 ><LI
1594 ><P
1595 >10 minutes with MacOS X Mail.app "manual cache"
1596               </P
1597 ></LI
1598 ><LI
1599 ><P
1600 >5 minutes with GNUS agent sync</P
1601 ></LI
1602 ><LI
1603 ><P
1604 >20 seconds with OfflineIMAP 1.x</P
1605 ></LI
1606 ><LI
1607 ><P
1608 >9 seconds with OfflineIMAP 2.x</P
1609 ></LI
1610 ><LI
1611 ><P
1612 >3 seconds with OfflineIMAP 3.x "cold start"</P
1613 ></LI
1614 ><LI
1615 ><P
1616 >2 seconds with OfflineIMAP 3.x "held connection"</P
1617 ></LI
1618 ></UL
1619 ></DD
1620 ></DL
1621 ></DIV
1622 ></DIV
1623 ><DIV
1624 CLASS="REFSECT1"
1625 ><A
1626 NAME="AEN456"
1627 ></A
1628 ><H2
1629 >Conforming To</H2
1630 ><P
1631 ></P
1632 ><UL
1633 ><LI
1634 ><P
1635 >Internet Message Access Protocol version 4rev1 (IMAP 4rev1) as
1636           specified in RFC2060</P
1637 ></LI
1638 ><LI
1639 ><P
1640 >CRAM-MD5 as specified in RFC2195</P
1641 ></LI
1642 ><LI
1643 ><P
1644 >Maildir as specified in
1645           <A
1646 HREF="http://www.qmail.org/qmail-manual-html/man5/maildir.html"
1647 TARGET="_top"
1648 >the Maildir manpage</A
1649 > and
1650           <A
1651 HREF="http://cr.yp.to/proto/maildir.html"
1652 TARGET="_top"
1653 >the qmail website</A
1654 >.</P
1655 ></LI
1656 ><LI
1657 ><P
1658 >Standard Python 2.2.1 as implemented on POSIX-compliant systems.</P
1659 ></LI
1660 ></UL
1661 ></DIV
1662 ><DIV
1663 CLASS="REFSECT1"
1664 ><A
1665 NAME="AEN469"
1666 ></A
1667 ><H2
1668 >Notes</H2
1669 ><DIV
1670 CLASS="REFSECT2"
1671 ><A
1672 NAME="AEN471"
1673 ></A
1674 ><H3
1675 >Deleting Local Folders</H3
1676 ><P
1677 ><SPAN
1678 CLASS="APPLICATION"
1679 >OfflineIMAP</SPAN
1680 > does a two-way synchronization.  That is, if you
1681           make a change to the mail on the server, it will be propogated to your
1682           local copy, and vise-versa.  Some people might think that it would be
1683           wise to just delete all their local mail folders periodically.  If you
1684           do this with <SPAN
1685 CLASS="APPLICATION"
1686 >OfflineIMAP</SPAN
1687 >, remember to also remove your local status
1688           cache (<TT
1689 CLASS="FILENAME"
1690 >~/.offlineimap</TT
1691 > by default).  Otherwise, <SPAN
1692 CLASS="APPLICATION"
1693 >OfflineIMAP</SPAN
1694 > will take
1695           this as an intentional deletion of many messages and will interpret
1696           your action as requesting them to be deleted from the server as well.
1697           (If you don't understand this, don't worry; you probably won't
1698           encounter this situation)
1699         </P
1700 ></DIV
1701 ><DIV
1702 CLASS="REFSECT2"
1703 ><A
1704 NAME="AEN478"
1705 ></A
1706 ><H3
1707 >Multiple Instances</H3
1708 ><P
1709 ><SPAN
1710 CLASS="APPLICATION"
1711 >OfflineIMAP</SPAN
1712 > is not designed to have several instances (for instance, a cron job and an interactive invocation) run over the same
1713           mailbox simultaneously.  It will perform a check on startup and
1714           abort if another <SPAN
1715 CLASS="APPLICATION"
1716 >OfflineIMAP</SPAN
1717 > is already running.  If you need
1718           to schedule synchronizations, please use the
1719           <SPAN
1720 CLASS="PROPERTY"
1721 >autorefresh</SPAN
1722 > settings rather than cron.
1723           Alternatively, you can set a separate <SPAN
1724 CLASS="PROPERTY"
1725 >metadata</SPAN
1726 >
1727           directory for each instance.
1728         </P
1729 ></DIV
1730 ><DIV
1731 CLASS="REFSECT2"
1732 ><A
1733 NAME="AEN485"
1734 ></A
1735 ><H3
1736 >Copying Messages Between Folders</H3
1737 ><P
1738 >         Normally, when you copy a message between folders or add a new message
1739           to a folder locally, <SPAN
1740 CLASS="APPLICATION"
1741 >OfflineIMAP</SPAN
1742 >
1743           will just do the right thing.  However, sometimes this can be tricky
1744           -- if your IMAP server does not provide the SEARCH command, or does
1745           not return something useful, <SPAN
1746 CLASS="APPLICATION"
1747 >OfflineIMAP</SPAN
1748 >
1749           cannot determine the new UID of the message.  So, in these rare
1750           instances, OfflineIMAP will upload the message to the IMAP server and
1751           delete it from your local folder.  Then, on your next sync, the
1752           message will be re-downloaded with the proper UID.
1753           <SPAN
1754 CLASS="APPLICATION"
1755 >OfflineIMAP</SPAN
1756 > makes sure that the message was properly uploaded before deleting it,
1757           so there should be no risk of data loss.
1758         </P
1759 ></DIV
1760 ><DIV
1761 CLASS="REFSECT2"
1762 ><A
1763 NAME="AEN491"
1764 ></A
1765 ><H3
1766 >Use with Evolution</H3
1767 ><P
1768 ><SPAN
1769 CLASS="APPLICATION"
1770 >OfflineIMAP</SPAN
1771 > can work with Evolution.  To do so, first configure
1772           your <SPAN
1773 CLASS="APPLICATION"
1774 >OfflineIMAP</SPAN
1775 > account to have
1776           <TT
1777 CLASS="OPTION"
1778 >sep = /</TT
1779 > in its configuration.  Then, configure
1780           Evolution with the
1781           "Maildir-format mail directories" server type.  For the path, you will need to
1782           specify the name of the top-level folder
1783           <SPAN
1784 CLASS="emphasis"
1785 ><I
1786 CLASS="EMPHASIS"
1787 >inside</I
1788 ></SPAN
1789 > your <SPAN
1790 CLASS="APPLICATION"
1791 >OfflineIMAP</SPAN
1792 > storage location.
1793           You're now set!
1794         </P
1795 ></DIV
1796 ><DIV
1797 CLASS="REFSECT2"
1798 ><A
1799 NAME="AEN499"
1800 ></A
1801 ><H3
1802 >Use with KMail</H3
1803 ><P
1804 >At this time, I believe that <SPAN
1805 CLASS="APPLICATION"
1806 >OfflineIMAP</SPAN
1807 > is not compatible
1808           with KMail.  KMail cannot work in any mode other than to move
1809           all messages out of all folders immediately, which (besides being annoying
1810           and fundamentally broken) is incompatible with <SPAN
1811 CLASS="APPLICATION"
1812 >OfflineIMAP</SPAN
1813 >.
1814         </P
1815 ></DIV
1816 ><DIV
1817 CLASS="REFSECT2"
1818 ><A
1819 NAME="AEN504"
1820 ></A
1821 ><H3
1822 >Mailing List</H3
1823 ><P
1824 >There is an OfflineIMAP mailing list available.
1825           To subscribe, send the text "Subscribe" in the subject of a mail to
1826           offlineimap-request@complete.org.  To post, send the message to
1827           offlineimap@complete.org.
1828         </P
1829 ></DIV
1830 ><DIV
1831 CLASS="REFSECT2"
1832 ><A
1833 NAME="AEN507"
1834 ></A
1835 ><H3
1836 >Bugs</H3
1837 ><P
1838 >Reports of bugs should be sent via e-mail to the
1839           <SPAN
1840 CLASS="APPLICATION"
1841 >OfflineIMAP</SPAN
1842 > bug-tracking system (BTS) at
1843           offlineimap@bugs.complete.org or submitted online using
1844           the <A
1845 HREF="http://bugs.complete.org/"
1846 TARGET="_top"
1847 >web interface</A
1848 >.
1849         </P
1850 ><P
1851 >         The Web site also lists all current bugs, where you can check their
1852           status or contribute to fixing them.
1853         </P
1854 ></DIV
1855 ></DIV
1856 ><DIV
1857 CLASS="REFSECT1"
1858 ><A
1859 NAME="AEN513"
1860 ></A
1861 ><H2
1862 >Copyright</H2
1863 ><P
1864 >OfflineIMAP, and this manual, are Copyright &copy; 2002, 2003 John Goerzen.</P
1865 ><P
1866 >       This program is free software; you can redistribute it and/or modify
1867         it under the terms of the GNU General Public License as published by
1868         the Free Software Foundation; version 2 of the License.
1869       </P
1870 ><P
1871 >       This program is distributed in the hope that it will be useful,
1872         but WITHOUT ANY WARRANTY; without even the implied warranty of
1873         MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
1874         GNU General Public License for more details.
1875       </P
1876 ><P
1877 >       You should have received a copy of the GNU General Public License
1878         along with this program; if not, write to the Free Software
1879         Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA</P
1880 ><P
1881 >imaplib.py comes from the Python dev tree and is licensed under
1882         the GPL-compatible PSF license as stated in the file
1883         <TT
1884 CLASS="FILENAME"
1885 >COPYRIGHT</TT
1886 > in the <SPAN
1887 CLASS="APPLICATION"
1888 >OfflineIMAP</SPAN
1889 >
1890          distribution.
1891       </P
1892 ></DIV
1893 ><DIV
1894 CLASS="REFSECT1"
1895 ><A
1896 NAME="AEN522"
1897 ></A
1898 ><H2
1899 >Author</H2
1900 ><P
1901 ><SPAN
1902 CLASS="APPLICATION"
1903 >OfflineIMAP</SPAN
1904 >, its libraries, documentation, and all included files, except where
1905         noted, was written by John Goerzen <TT
1906 CLASS="EMAIL"
1907 >&#60;<A
1908 HREF="mailto:jgoerzen@complete.org"
1909 >jgoerzen@complete.org</A
1910 >&#62;</TT
1911 > and
1912         copyright is held as stated in the COPYRIGHT section.
1913       </P
1914 ><P
1915 >       <SPAN
1916 CLASS="APPLICATION"
1917 >OfflineIMAP</SPAN
1918 > may be downloaded, and information found, from its
1919         homepage via either <A
1920 HREF="gopher://quux.org/1/devel/offlineimap"
1921 TARGET="_top"
1922 >Gopher</A
1923 >
1924         or <A
1925 HREF="http://quux.org/devel/offlineimap"
1926 TARGET="_top"
1927 >HTTP</A
1928 >.
1929       </P
1930 ><P
1931 >       <SPAN
1932 CLASS="APPLICATION"
1933 >OfflineIMAP</SPAN
1934 > may also be downloaded using Subversion.  Additionally,
1935         the distributed tar.gz may be updated with a simple "svn update"
1936         command; it is ready to go.  For information on getting OfflineIMAP
1937         with Subversion, please visit the
1938         <A
1939 HREF="http://svn.complete.org/"
1940 TARGET="_top"
1941 >complete.org Subversion page</A
1942 >.
1943       </P
1944 ></DIV
1945 ><DIV
1946 CLASS="REFSECT1"
1947 ><A
1948 NAME="AEN534"
1949 ></A
1950 ><H2
1951 >See Also</H2
1952 ><P
1953 ><SPAN
1954 CLASS="APPLICATION"
1955 >mutt</SPAN
1956 >(1),
1957         <SPAN
1958 CLASS="APPLICATION"
1959 >python</SPAN
1960 >(1)
1961       </P
1962 ></DIV
1963 ></DIV
1964 ></BODY
1965 ></HTML
1966 >