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

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