]> code.delx.au - offlineimap/blob - manual.html
delx.au / code / offlineimap / blob
summary | shortlog | log | commit | commitdiff | tree
history | raw | HEAD
Checkpointing for .8
[offlineimap] / 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 administrator 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 >Configuration</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 >Configuration</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 >Configuration</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 default 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 fuchsia 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 xsw = x.startswith(prefix)
1297 ysw = y.startswith(prefix)
1298 if xsw and ysw:
1299 return cmp(x, y)
1300 elif xsw:
1301 return -1
1302 elif ysw:
1303 return +1
1304 return cmp(x, y)
1305
1306 def test_mycmp():
1307 import os, os.path
1308 folders=os.listdir(os.path.expanduser('~/data/mail/tv@hq.yok.utu.fi'))
1309 folders.sort(mycmp)
1310 print folders</PRE
1311 ><P
1312 > This code snippet illustrates how the <SPAN
1313 CLASS="PROPERTY"
1314 >foldersort</SPAN
1315 >
1316 option can be customized with a Python function from the
1317 <SPAN
1318 CLASS="PROPERTY"
1319 >pythonfile</SPAN
1320 > to always synchronize certain
1321 folders first.
1322 </P
1323 ></DIV
1324 ></DIV
1325 ><DIV
1326 CLASS="REFSECT1"
1327 ><A
1328 NAME="AEN354"
1329 ></A
1330 ><H2
1331 >Errors</H2
1332 ><P
1333 > If you get one of some frequently-encountered or confusing errors,
1334 please check this section.
1335 </P
1336 ><DIV
1337 CLASS="REFSECT2"
1338 ><A
1339 NAME="AEN357"
1340 ></A
1341 ><H3
1342 >UID validity problem for folder</H3
1343 ><P
1344 >IMAP servers use a unique ID (UID) to refer to a specific message.
1345 This number is guaranteed to be unique to a particular message
1346 <SPAN
1347 CLASS="emphasis"
1348 ><I
1349 CLASS="EMPHASIS"
1350 >forever</I
1351 ></SPAN
1352 >.
1353 No other message in the same folder will ever get the same
1354 UID. UIDs are an integral part of <SPAN
1355 CLASS="APPLICATION"
1356 >OfflineIMAP</SPAN
1357 >'s synchronization
1358 scheme; they are used to match up messages on your computer to
1359 messages on the server.
1360 </P
1361 ><P
1362 > Sometimes, the UIDs on the server might get reset. Usually this will
1363 happen if you delete and then recreate a folder. When you create a
1364 folder, the server will often start the UID back from 1. But
1365 <SPAN
1366 CLASS="APPLICATION"
1367 >OfflineIMAP</SPAN
1368 > might still have the UIDs from the previous folder by the
1369 same name stored. <SPAN
1370 CLASS="APPLICATION"
1371 >OfflineIMAP</SPAN
1372 > will detect this condition and skip the
1373 folder. This is GOOD, because it prevents data loss.
1374 </P
1375 ><P
1376 > You can fix it by removing your local folder and cache data. For
1377 instance, if your folders are under <TT
1378 CLASS="FILENAME"
1379 >~/Folders</TT
1380 >
1381 and the folder with the problem is INBOX, you'd type this:
1382 </P
1383 ><PRE
1384 CLASS="PROGRAMLISTING"
1385 >rm -r ~/Folders/INBOX
1386 rm -r ~/.offlineimap/Account-<VAR
1387 CLASS="REPLACEABLE"
1388 >AccountName</VAR
1389 >
1390 rm -r ~/.offlineimap/Repository-<VAR
1391 CLASS="REPLACEABLE"
1392 >RepositoryName</VAR
1393 ></PRE
1394 ><P
1395 > (Of course, replace AccountName and RepositoryName
1396 with the names as specified
1397 in <TT
1398 CLASS="FILENAME"
1399 >~/.offlineimaprc</TT
1400 >).
1401 </P
1402 ><P
1403 >Next time you run <SPAN
1404 CLASS="APPLICATION"
1405 >OfflineIMAP</SPAN
1406 >, it will re-download
1407 the folder with the
1408 new UIDs. Note that the procedure specified above will lose any local
1409 changes made to the folder.
1410 </P
1411 ><P
1412 > Some IMAP servers are broken and do not support UIDs properly. If you
1413 continue to get this error for all your folders even after performing
1414 the above procedure, it is likely that your IMAP server falls into
1415 this category. <SPAN
1416 CLASS="APPLICATION"
1417 >OfflineIMAP</SPAN
1418 > is incompatible with such servers.
1419 Using <SPAN
1420 CLASS="APPLICATION"
1421 >OfflineIMAP</SPAN
1422 > with them will not destroy any mail, but at the same time,
1423 it will not actually synchronize it either. (<SPAN
1424 CLASS="APPLICATION"
1425 >OfflineIMAP</SPAN
1426 > will detect
1427 this condition and abort prior to synchronization.)
1428 </P
1429 ><P
1430 > This question comes up frequently on the
1431 <A
1432 HREF="http://lists.complete.org/offlineimap@complete.org/"
1433 TARGET="_top"
1434 ><SPAN
1435 CLASS="APPLICATION"
1436 >OfflineIMAP</SPAN
1437 >
1438 mailing list</A
1439 >. You can find a
1440 <A
1441 HREF="http://lists.complete.org/offlineimap@complete.org/2003/04/msg00012.html.gz"
1442 TARGET="_top"
1443 >detailed
1444 discussion</A
1445 > of the problem there.
1446 </P
1447 ></DIV
1448 ></DIV
1449 ><DIV
1450 CLASS="REFSECT1"
1451 ><A
1452 NAME="AEN382"
1453 ></A
1454 ><H2
1455 >Other Frequently Asked Questions</H2
1456 ><P
1457 >There are some other FAQs that might not fit into another section
1458 of the document, so they are discussed here.
1459 </P
1460 ><P
1461 ></P
1462 ><DIV
1463 CLASS="VARIABLELIST"
1464 ><DL
1465 ><DT
1466 >What platforms does <SPAN
1467 CLASS="APPLICATION"
1468 >OfflineIMAP</SPAN
1469 > run on?</DT
1470 ><DD
1471 ><P
1472 > It should run on most platforms supported by Python, which are quite a
1473 few. I do not support Windows myself, but some have made
1474 it work there; see the FAQ entry for that platform.
1475 </P
1476 ></DD
1477 ><DT
1478 >I'm using Mutt. Other IMAP sync programs require me to use "set maildir_trash=yes". Do I need to do that with <SPAN
1479 CLASS="APPLICATION"
1480 >OfflineIMAP</SPAN
1481 >?</DT
1482 ><DD
1483 ><P
1484 > No. <SPAN
1485 CLASS="APPLICATION"
1486 >OfflineIMAP</SPAN
1487 > is smart enough to figure out message deletion without this extra
1488 crutch. You'll get the best results if you don't use this setting, in
1489 fact.
1490 </P
1491 ></DD
1492 ><DT
1493 >I've upgraded and now <SPAN
1494 CLASS="APPLICATION"
1495 >OfflineIMAP</SPAN
1496 >
1497 crashes when I start it up! Why?</DT
1498 ><DD
1499 ><P
1500 >You need to upgrade your configuration
1501 file. See at the end of this
1502 manual.
1503 </P
1504 ></DD
1505 ><DT
1506 >How do I specify the names of my folders?</DT
1507 ><DD
1508 ><P
1509 > You do not need to. <SPAN
1510 CLASS="APPLICATION"
1511 >OfflineIMAP</SPAN
1512 > is smart
1513 enough to automatically figure out what folders are present
1514 on the IMAP server and synchronize them. You can use the
1515 <SPAN
1516 CLASS="PROPERTY"
1517 >folderfilter</SPAN
1518 > and <SPAN
1519 CLASS="PROPERTY"
1520 >foldertrans</SPAN
1521 >
1522 configuration file options to request certain folders and rename them
1523 as they come in if you like.
1524 </P
1525 ></DD
1526 ><DT
1527 >How can I prevent certain folders from being synced?</DT
1528 ><DD
1529 ><P
1530 > Use the <SPAN
1531 CLASS="PROPERTY"
1532 >folderfilter</SPAN
1533 > option in the configuration file.
1534 </P
1535 ></DD
1536 ><DT
1537 >How can I add or delete a folder?</DT
1538 ><DD
1539 ><P
1540 > <SPAN
1541 CLASS="APPLICATION"
1542 >OfflineIMAP</SPAN
1543 > does not currently provide this feature, but if you create a new
1544 folder on the IMAP server, it will be created locally automatically.
1545 </P
1546 ></DD
1547 ><DT
1548 >Are there any other warnings that I should be aware of?</DT
1549 ><DD
1550 ><P
1551 > Yes; see the Notes section below.
1552 </P
1553 ></DD
1554 ><DT
1555 >What is the mailbox name recorder (mbnames) for?</DT
1556 ><DD
1557 ><P
1558 >Some mail readers, such as Mutt, are not capable
1559 of automatically determining the names of your mailboxes.
1560 <SPAN
1561 CLASS="APPLICATION"
1562 >OfflineIMAP</SPAN
1563 > can help these programs by writing the names
1564 of the folders in a format you specify. See the example
1565 <TT
1566 CLASS="FILENAME"
1567 >offlineimap.conf</TT
1568 > for details.
1569 </P
1570 ></DD
1571 ><DT
1572 >Can I synchronize multiple accounts with <SPAN
1573 CLASS="APPLICATION"
1574 >OfflineIMAP</SPAN
1575 >?</DT
1576 ><DD
1577 ><P
1578 >Sure. Just name them all in the
1579 <SPAN
1580 CLASS="PROPERTY"
1581 >accounts</SPAN
1582 > line in the <SPAN
1583 CLASS="PROPERTY"
1584 >general</SPAN
1585 >
1586 section of the configuration file, and add a per-account section
1587 for each one.
1588 </P
1589 ></DD
1590 ><DT
1591 >Does <SPAN
1592 CLASS="APPLICATION"
1593 >OfflineIMAP</SPAN
1594 > support POP?</DT
1595 ><DD
1596 ><P
1597 >No. POP is not robust enough to do a completely reliable
1598 multi-machine synchronization like <SPAN
1599 CLASS="APPLICATION"
1600 >OfflineIMAP</SPAN
1601 > can do. <SPAN
1602 CLASS="APPLICATION"
1603 >OfflineIMAP</SPAN
1604 >
1605 will not support it.
1606 </P
1607 ></DD
1608 ><DT
1609 >Does <SPAN
1610 CLASS="APPLICATION"
1611 >OfflineIMAP</SPAN
1612 > support mailbox formats other than Maildir?</DT
1613 ><DD
1614 ><P
1615 >Not at present. There is no technical reason not to; just no
1616 demand yet. Maildir is a superior format anyway.
1617 However, <SPAN
1618 CLASS="APPLICATION"
1619 >OfflineIMAP</SPAN
1620 > can sync between two IMAP
1621 servers, and some IMAP servers support other formats. You
1622 could install an IMAP server on your local machine and have
1623 <SPAN
1624 CLASS="APPLICATION"
1625 >OfflineIMAP</SPAN
1626 > sync to that.
1627 </P
1628 ></DD
1629 ><DT
1630 >[technical] Why are your Maildir message filenames so huge?</DT
1631 ><DD
1632 ><P
1633 ><SPAN
1634 CLASS="APPLICATION"
1635 >OfflineIMAP</SPAN
1636 > has two relevant principles: 1) never modifying your
1637 messages in any way and 2) ensuring 100% reliable synchronizations.
1638 In order to do a reliable sync, <SPAN
1639 CLASS="APPLICATION"
1640 >OfflineIMAP</SPAN
1641 >
1642 must have a way to
1643 uniquely identify each e-mail. Three pieces of information are
1644 required to do this: your account name, the folder name, and the
1645 message UID. The account name can be calculated from the path in
1646 which your messages are. The folder name can usually be as well, BUT
1647 some mail clients move messages between folders by simply moving the
1648 file, leaving the name intact.
1649 </P
1650 ><P
1651 > So, <SPAN
1652 CLASS="APPLICATION"
1653 >OfflineIMAP</SPAN
1654 > must store both a UID folder ID. The folder ID is
1655 necessary so <SPAN
1656 CLASS="APPLICATION"
1657 >OfflineIMAP</SPAN
1658 > can detect a message moved to a different
1659 folder. <SPAN
1660 CLASS="APPLICATION"
1661 >OfflineIMAP</SPAN
1662 > stores the UID (U= number) and an md5sum of the
1663 foldername (FMD5= number) to facilitate this.
1664 </P
1665 ></DD
1666 ><DT
1667 >What is the speed of <SPAN
1668 CLASS="APPLICATION"
1669 >OfflineIMAP</SPAN
1670 >'s sync?</DT
1671 ><DD
1672 ><P
1673 >OfflineIMAP
1674 versions 2.0 and above contain a multithreaded system. A good way to
1675 experiment is by setting <SPAN
1676 CLASS="PROPERTY"
1677 >maxsyncaccounts</SPAN
1678 > to 3 and <SPAN
1679 CLASS="PROPERTY"
1680 >maxconnections</SPAN
1681 > to 3
1682 in each account clause.
1683 </P
1684 ><P
1685 >This lets OfflineIMAP open up multiple connections simultaneously.
1686 That will let it process multiple folders and messages at once. In
1687 most cases, this will increase performance of the sync.
1688 </P
1689 ><P
1690 >Don't set the number too high. If you do that, things might actually
1691 slow down as your link gets saturated. Also, too many connections can
1692 cause mail servers to have excessive load. Administrators might take
1693 unkindly to this, and the server might bog down. There are many
1694 variables in the optimal setting; experimentation may help.
1695 </P
1696 ><P
1697 >An informal benchmark yields these results for my setup:
1698 </P
1699 ><P
1700 ></P
1701 ><UL
1702 ><LI
1703 ><P
1704 >10 minutes with MacOS X Mail.app "manual cache"
1705 </P
1706 ></LI
1707 ><LI
1708 ><P
1709 >5 minutes with GNUS agent sync</P
1710 ></LI
1711 ><LI
1712 ><P
1713 >20 seconds with OfflineIMAP 1.x</P
1714 ></LI
1715 ><LI
1716 ><P
1717 >9 seconds with OfflineIMAP 2.x</P
1718 ></LI
1719 ><LI
1720 ><P
1721 >3 seconds with OfflineIMAP 3.x "cold start"</P
1722 ></LI
1723 ><LI
1724 ><P
1725 >2 seconds with OfflineIMAP 3.x "held connection"</P
1726 ></LI
1727 ></UL
1728 ></DD
1729 ><DT
1730 >Can I use <SPAN
1731 CLASS="APPLICATION"
1732 >OfflineIMAP</SPAN
1733 > on Windows?</DT
1734 ><DD
1735 ><P
1736 > These answers have been reported by <SPAN
1737 CLASS="APPLICATION"
1738 >OfflineIMAP</SPAN
1739 >
1740 users. I do not run <SPAN
1741 CLASS="APPLICATION"
1742 >OfflineIMAP</SPAN
1743 > on Windows myself, so
1744 I can't directly address their accuracy.
1745 </P
1746 ><P
1747 > The basic answer is that it's possible and doesn't
1748 require hacking <SPAN
1749 CLASS="APPLICATION"
1750 >OfflineIMAP</SPAN
1751 > source code. However,
1752 it's not necessarily trivial. The information below is
1753 based in instructions submitted by Chris Walker.
1754 </P
1755 ><P
1756 > First, you must run <SPAN
1757 CLASS="APPLICATION"
1758 >OfflineIMAP</SPAN
1759 > in the <A
1760 HREF="http://www.cygwin.com/"
1761 TARGET="_top"
1762 >Cygwin</A
1763 >
1764 environment.
1765 </P
1766 ><P
1767 > Next, you'll need to mount your Maildir directory in a
1768 special way. There is information for doing that at
1769 <A
1770 HREF="http://barnson.org/node/view/295"
1771 TARGET="_top"
1772 >http://barnson.org/node/view/295</A
1773 >.
1774 That site gives this example:
1775 </P
1776 ><PRE
1777 CLASS="PROGRAMLISTING"
1778 >mount -f -s -b -o managed "d:/tmp/mail" "/home/of/mail"
1779 </PRE
1780 ><P
1781 > That URL also has more details on making OfflineIMAP
1782 work with Windows.
1783 </P
1784 ></DD
1785 ></DL
1786 ></DIV
1787 ></DIV
1788 ><DIV
1789 CLASS="REFSECT1"
1790 ><A
1791 NAME="AEN500"
1792 ></A
1793 ><H2
1794 >Conforming To</H2
1795 ><P
1796 ></P
1797 ><UL
1798 ><LI
1799 ><P
1800 >Internet Message Access Protocol version 4rev1 (IMAP 4rev1) as
1801 specified in RFC2060 and RFC3501</P
1802 ></LI
1803 ><LI
1804 ><P
1805 >CRAM-MD5 as specified in RFC2195</P
1806 ></LI
1807 ><LI
1808 ><P
1809 >Maildir as specified in
1810 <A
1811 HREF="http://www.qmail.org/qmail-manual-html/man5/maildir.html"
1812 TARGET="_top"
1813 >the Maildir manpage</A
1814 > and
1815 <A
1816 HREF="http://cr.yp.to/proto/maildir.html"
1817 TARGET="_top"
1818 >the qmail website</A
1819 >.</P
1820 ></LI
1821 ><LI
1822 ><P
1823 >Standard Python 2.2.1 as implemented on POSIX-compliant systems.</P
1824 ></LI
1825 ></UL
1826 ></DIV
1827 ><DIV
1828 CLASS="REFSECT1"
1829 ><A
1830 NAME="AEN513"
1831 ></A
1832 ><H2
1833 >Notes</H2
1834 ><DIV
1835 CLASS="REFSECT2"
1836 ><A
1837 NAME="AEN515"
1838 ></A
1839 ><H3
1840 >Deleting Local Folders</H3
1841 ><P
1842 ><SPAN
1843 CLASS="APPLICATION"
1844 >OfflineIMAP</SPAN
1845 > does a two-way synchronization. That is, if you
1846 make a change to the mail on the server, it will be propagated to your
1847 local copy, and vise-versa. Some people might think that it would be
1848 wise to just delete all their local mail folders periodically. If you
1849 do this with <SPAN
1850 CLASS="APPLICATION"
1851 >OfflineIMAP</SPAN
1852 >, remember to also remove your local status
1853 cache (<TT
1854 CLASS="FILENAME"
1855 >~/.offlineimap</TT
1856 > by default). Otherwise, <SPAN
1857 CLASS="APPLICATION"
1858 >OfflineIMAP</SPAN
1859 > will take
1860 this as an intentional deletion of many messages and will interpret
1861 your action as requesting them to be deleted from the server as well.
1862 (If you don't understand this, don't worry; you probably won't
1863 encounter this situation)
1864 </P
1865 ></DIV
1866 ><DIV
1867 CLASS="REFSECT2"
1868 ><A
1869 NAME="AEN522"
1870 ></A
1871 ><H3
1872 >Multiple Instances</H3
1873 ><P
1874 ><SPAN
1875 CLASS="APPLICATION"
1876 >OfflineIMAP</SPAN
1877 > is not designed to have several instances (for instance, a cron job and an interactive invocation) run over the same
1878 mailbox simultaneously. It will perform a check on startup and
1879 abort if another <SPAN
1880 CLASS="APPLICATION"
1881 >OfflineIMAP</SPAN
1882 > is already running. If you need
1883 to schedule synchronizations, please use the
1884 <SPAN
1885 CLASS="PROPERTY"
1886 >autorefresh</SPAN
1887 > settings rather than cron.
1888 Alternatively, you can set a separate <SPAN
1889 CLASS="PROPERTY"
1890 >metadata</SPAN
1891 >
1892 directory for each instance.
1893 </P
1894 ></DIV
1895 ><DIV
1896 CLASS="REFSECT2"
1897 ><A
1898 NAME="AEN529"
1899 ></A
1900 ><H3
1901 >Copying Messages Between Folders</H3
1902 ><P
1903 > Normally, when you copy a message between folders or add a new message
1904 to a folder locally, <SPAN
1905 CLASS="APPLICATION"
1906 >OfflineIMAP</SPAN
1907 >
1908 will just do the right thing. However, sometimes this can be tricky
1909 -- if your IMAP server does not provide the SEARCH command, or does
1910 not return something useful, <SPAN
1911 CLASS="APPLICATION"
1912 >OfflineIMAP</SPAN
1913 >
1914 cannot determine the new UID of the message. So, in these rare
1915 instances, OfflineIMAP will upload the message to the IMAP server and
1916 delete it from your local folder. Then, on your next sync, the
1917 message will be re-downloaded with the proper UID.
1918 <SPAN
1919 CLASS="APPLICATION"
1920 >OfflineIMAP</SPAN
1921 > makes sure that the message was properly uploaded before deleting it,
1922 so there should be no risk of data loss.
1923 </P
1924 ></DIV
1925 ><DIV
1926 CLASS="REFSECT2"
1927 ><A
1928 NAME="AEN535"
1929 ></A
1930 ><H3
1931 >Use with Evolution</H3
1932 ><P
1933 ><SPAN
1934 CLASS="APPLICATION"
1935 >OfflineIMAP</SPAN
1936 > can work with Evolution. To do so, first configure
1937 your <SPAN
1938 CLASS="APPLICATION"
1939 >OfflineIMAP</SPAN
1940 > account to have
1941 <VAR
1942 CLASS="OPTION"
1943 >sep = /</VAR
1944 > in its configuration. Then, configure
1945 Evolution with the
1946 "Maildir-format mail directories" server type. For the path, you will need to
1947 specify the name of the top-level folder
1948 <SPAN
1949 CLASS="emphasis"
1950 ><I
1951 CLASS="EMPHASIS"
1952 >inside</I
1953 ></SPAN
1954 > your <SPAN
1955 CLASS="APPLICATION"
1956 >OfflineIMAP</SPAN
1957 > storage location.
1958 You're now set!
1959 </P
1960 ></DIV
1961 ><DIV
1962 CLASS="REFSECT2"
1963 ><A
1964 NAME="AEN543"
1965 ></A
1966 ><H3
1967 >Use with KMail</H3
1968 ><P
1969 >At this time, I believe that <SPAN
1970 CLASS="APPLICATION"
1971 >OfflineIMAP</SPAN
1972 > with Maildirs
1973 is not compatible
1974 with KMail. KMail cannot work in any mode other than to move
1975 all messages out of all folders immediately, which (besides being annoying
1976 and fundamentally broken) is incompatible with
1977 <SPAN
1978 CLASS="APPLICATION"
1979 >OfflineIMAP</SPAN
1980 >.
1981 </P
1982 ><P
1983 > However, I have made KMail version 3 work well with
1984 <SPAN
1985 CLASS="APPLICATION"
1986 >OfflineIMAP</SPAN
1987 > by installing an IMAP server on my local
1988 machine, having <SPAN
1989 CLASS="APPLICATION"
1990 >OfflineIMAP</SPAN
1991 > sync to that, and pointing
1992 KMail at the same server.
1993 </P
1994 ></DIV
1995 ><DIV
1996 CLASS="REFSECT2"
1997 ><A
1998 NAME="AEN551"
1999 ></A
2000 ><H3
2001 >Mailing List</H3
2002 ><P
2003 >There is an OfflineIMAP mailing list available.
2004 To subscribe, send the text "Subscribe" in the subject of a mail to
2005 offlineimap-request@complete.org. To post, send the message to
2006 offlineimap@complete.org. Archives are available at
2007 <A
2008 HREF="http://lists.complete.org/offlineimap@complete.org/"
2009 TARGET="_top"
2010 >http://lists.complete.org/offlineimap@complete.org/</A
2011 >.
2012 </P
2013 ></DIV
2014 ><DIV
2015 CLASS="REFSECT2"
2016 ><A
2017 NAME="AEN555"
2018 ></A
2019 ><H3
2020 >Bugs</H3
2021 ><P
2022 >Reports of bugs should be sent via e-mail to the
2023 <SPAN
2024 CLASS="APPLICATION"
2025 >OfflineIMAP</SPAN
2026 > bug-tracking system (BTS) at
2027 offlineimap@bugs.complete.org or submitted online using
2028 the <A
2029 HREF="http://bugs.complete.org/"
2030 TARGET="_top"
2031 >web interface</A
2032 >.
2033 </P
2034 ><P
2035 > The Web site also lists all current bugs, where you can check their
2036 status or contribute to fixing them.
2037 </P
2038 ></DIV
2039 ></DIV
2040 ><DIV
2041 CLASS="REFSECT1"
2042 ><A
2043 NAME="UPGRADING.4.0"
2044 ></A
2045 ><H2
2046 >Upgrading to 4.0</H2
2047 ><P
2048 > If you are upgrading from a version of <SPAN
2049 CLASS="APPLICATION"
2050 >OfflineIMAP</SPAN
2051 > prior to
2052 3.99.12, you will find that you will get errors when
2053 <SPAN
2054 CLASS="APPLICATION"
2055 >OfflineIMAP</SPAN
2056 > starts up (relating to ConfigParser or
2057 AccountHashGenerator) and the
2058 configuration file. This is because the config file format
2059 had to change to accommodate new features in 4.0. Fortunately,
2060 it's not difficult to adjust it to suit.
2061 </P
2062 ><P
2063 > First thing you need to do is stop any running <SPAN
2064 CLASS="APPLICATION"
2065 >OfflineIMAP</SPAN
2066 >
2067 instance, making sure first that it's synced all your mail.
2068 Then, modify your
2069 <TT
2070 CLASS="FILENAME"
2071 >~/.offlineimaprc</TT
2072 > file. You'll need to
2073 split up each account section (make sure that it now starts
2074 with "Account ") into two Repository sections (one for the
2075 local side and another for the remote side.) See the files
2076 <TT
2077 CLASS="FILENAME"
2078 >offlineimap.conf.minimal</TT
2079 > and
2080 <TT
2081 CLASS="FILENAME"
2082 >offlineimap.conf</TT
2083 > in the distribution if
2084 you need more assistance.
2085 </P
2086 ><P
2087 > <SPAN
2088 CLASS="APPLICATION"
2089 >OfflineIMAP</SPAN
2090 >'s status directory area has also changed.
2091 Therefore, you should delete everything in ~/.offlineimap as
2092 well as your local mail folders.
2093 </P
2094 ><P
2095 > When you start up <SPAN
2096 CLASS="APPLICATION"
2097 >OfflineIMAP</SPAN
2098 > 4.0, it will re-download all
2099 your mail from the server and then you can continue using it
2100 like normal.
2101 </P
2102 ></DIV
2103 ><DIV
2104 CLASS="REFSECT1"
2105 ><A
2106 NAME="AEN575"
2107 ></A
2108 ><H2
2109 >Copyright</H2
2110 ><P
2111 >OfflineIMAP, and this manual, are Copyright &copy; 2002, 2003 John Goerzen.</P
2112 ><P
2113 > This program is free software; you can redistribute it and/or modify
2114 it under the terms of the GNU General Public License as published by
2115 the Free Software Foundation; either version 2 of the License, or
2116 (at your option) any later version.
2117 </P
2118 ><P
2119 > This program is distributed in the hope that it will be useful,
2120 but WITHOUT ANY WARRANTY; without even the implied warranty of
2121 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
2122 GNU General Public License for more details.
2123 </P
2124 ><P
2125 > You should have received a copy of the GNU General Public License
2126 along with this program; if not, write to the Free Software
2127 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA</P
2128 ><P
2129 >imaplib.py comes from the Python dev tree and is licensed under
2130 the GPL-compatible PSF license as stated in the file
2131 <TT
2132 CLASS="FILENAME"
2133 >COPYRIGHT</TT
2134 > in the <SPAN
2135 CLASS="APPLICATION"
2136 >OfflineIMAP</SPAN
2137 >
2138 distribution.
2139 </P
2140 ></DIV
2141 ><DIV
2142 CLASS="REFSECT1"
2143 ><A
2144 NAME="AEN584"
2145 ></A
2146 ><H2
2147 >Author</H2
2148 ><P
2149 ><SPAN
2150 CLASS="APPLICATION"
2151 >OfflineIMAP</SPAN
2152 >, its libraries, documentation, and all included files, except where
2153 noted, was written by John Goerzen <CODE
2154 CLASS="EMAIL"
2155 >&#60;<A
2156 HREF="mailto:jgoerzen@complete.org"
2157 >jgoerzen@complete.org</A
2158 >&#62;</CODE
2159 > and
2160 copyright is held as stated in the COPYRIGHT section.
2161 </P
2162 ><P
2163 > <SPAN
2164 CLASS="APPLICATION"
2165 >OfflineIMAP</SPAN
2166 > may be downloaded, and information found, from its
2167 homepage via either <A
2168 HREF="gopher://quux.org/1/devel/offlineimap"
2169 TARGET="_top"
2170 >Gopher</A
2171 >
2172 or <A
2173 HREF="http://quux.org/devel/offlineimap"
2174 TARGET="_top"
2175 >HTTP</A
2176 >.
2177 </P
2178 ><P
2179 > <SPAN
2180 CLASS="APPLICATION"
2181 >OfflineIMAP</SPAN
2182 > may also be downloaded using Subversion. Additionally,
2183 the distributed tar.gz may be updated with a simple "svn update"
2184 command; it is ready to go. For information on getting OfflineIMAP
2185 with Subversion, please visit the
2186 <A
2187 HREF="http://svn.complete.org/"
2188 TARGET="_top"
2189 >complete.org Subversion page</A
2190 >.
2191 </P
2192 ></DIV
2193 ><DIV
2194 CLASS="REFSECT1"
2195 ><A
2196 NAME="AEN596"
2197 ></A
2198 ><H2
2199 >See Also</H2
2200 ><P
2201 ><SPAN
2202 CLASS="APPLICATION"
2203 >mutt</SPAN
2204 >(1),
2205 <SPAN
2206 CLASS="APPLICATION"
2207 >python</SPAN
2208 >(1)
2209 </P
2210 ></DIV
2211 ><DIV
2212 CLASS="REFSECT1"
2213 ><A
2214 NAME="AEN601"
2215 ></A
2216 ><H2
2217 >History</H2
2218 ><P
2219 > Detailed history may be found in the file ChangeLog in the
2220 <SPAN
2221 CLASS="APPLICATION"
2222 >OfflineIMAP</SPAN
2223 > distribution. Feature and bug histories may be
2224 found in the file debian/changelog which, despite its name, is
2225 not really Debian-specific. This section provides a large
2226 overview.
2227 </P
2228 ><P
2229 > Development on <SPAN
2230 CLASS="APPLICATION"
2231 >OfflineIMAP</SPAN
2232 > began on June 18, 2002. Version
2233 1.0.0 was released three days later on June 21, 2002. Point
2234 releases followed, including speed optimizations and some
2235 compatibility fixes.
2236 </P
2237 ><P
2238 >Version 2.0.0 was released on July 3, 2002, and
2239 represented the first time the synchronization became
2240 multithreaded and, to the best of my knowledge, the first
2241 multithreaded IMAP syncrhonizing application in existance.
2242 The last 2.0.x release, 2.0.8, was made on July 9.
2243 </P
2244 ><P
2245 > Version 3.0.0 was released on July 11, 2002, and introduced
2246 modular user interfaces and the first GUI interface for
2247 <SPAN
2248 CLASS="APPLICATION"
2249 >OfflineIMAP</SPAN
2250 >. This manual also was introduced with 3.0.0,
2251 along with many command-line options. Version 3.1.0 was
2252 released on July 21, adding the Noninteractive user
2253 interfaces, profiling support, and several bugfixes. 3.2.0
2254 was released on July 24, adding support for the Blinkenlights
2255 GUI interface. <SPAN
2256 CLASS="APPLICATION"
2257 >OfflineIMAP</SPAN
2258 > entered maintenance mode for
2259 awhile, as it had reached a feature-complete milestone in my
2260 mind.
2261 </P
2262 ><P
2263 > The 3.99.x branch began in on October 7, 2002, to begin work
2264 for 4.0. The Curses.Blinkenlights interface was added in
2265 3.99.6, and many architectural changes were made.
2266 </P
2267 ><P
2268 > 4.0.0 was released on July 18, 2003, including the ability to
2269 synchronize directly between two IMAP servers, the first
2270 re-architecting of the configuration file to refine the
2271 notion of an account, and the new Curses interface.
2272 </P
2273 ></DIV
2274 ></DIV
2275 ></BODY
2276 ></HTML
2277 >