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