diff --git a/head/Makefile b/head/Makefile index 00c5195..6e09175 100644 --- a/head/Makefile +++ b/head/Makefile @@ -14,6 +14,7 @@ # You should have received a copy of the GNU General Public License # along with this program; if not, write to the Free Software # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA +SHELL=/bin/bash clean: -python2.2 setup.py clean --all @@ -28,3 +29,9 @@ changelog: cvs2cl cvs commit ChangeLog rm ChangeLog.bak + +docs: + man -t -l offlineimap.1 > manual.ps + ps2pdf manual.ps + groff -Tascii -man offlineimap.1 | sed $$'s/.\b//g' > manual.txt + groff -Thtml -man offlineimap.1 > manual.html diff --git a/head/README b/head/README deleted file mode 100644 index dd836e1..0000000 --- a/head/README +++ /dev/null @@ -1,298 +0,0 @@ -OfflineIMAP -Copyright (C) 2002 John Goerzen -This software comes with ABSOLUTELY NO WARRANTY; see the file -COPYING for details. This is free software, and you are welcome -to distribute it under the conditions laid out in COPYING. - -gopher://quux.org/1/devel/offlineimap -http://quux.org/devel/offlineimap - -================================================== -Welcome -================================================== - -OfflineIMAP is a tool to simplify your e-mail reading. With -OfflimeIMAP, you can: - - * Read the same mailbox from multiple computers, and have your - changes (deletions, etc.) be automatically reflected on - all computers - - * Use various mail clients to read a single mail box - - * Read mail while offline (on a laptop) and have all changes - synchronized when you get connected again - - * Read IMAP mail with mail readers that do not support IMAP - - * Use SSL (secure connections) to read IMAP mail even if your reader - doesn't support SSL - - * Synchronize your mail using a completely safe and fault-tolerant - algorithm. (At least I think it is!) - - * Customize which mailboxes to synchronize with regular expressions - or lists. - - * Synchronize your mail two to four times faster than with other tools - or other mail readers' internal IMAP support. - -In short, OfflineIMAP is a tool to let you read mail how YOU want to. - -================================================== -Requirements -================================================== - -To use OfflineIMAP, you must: - -1. Have your mail delivered to a server that supports IMAP - -2. Have Python 2.2 or above installed - -3. Have a mail reader that supports Maildirs (most modern ones do) - -These requirements are easy to meet, and most people will have met -them already without even being aware of it. - -If you do not have Python already, check your operating system vendor -or download it from http://www.python.org/ - -================================================== -Installation -================================================== - -Basic installation for a single user requires only these steps: - -1. Copy offlineimap.conf to ~/.offlineimaprc and edit that file - for your accounts. Full instructions are in it. - -2. Make the directory that you will store your folders in. - (~/Test in the example) - -You can then just run "python2.2 offlineimap.py" to synchronize your -mail. - ------------------------------- -Systemwide - -If you wish to install OfflineIMAP for all users on your system: - -1. Either install the Debian package or run "python2.2 setup.py" and - follow the prompts - -2. Advise users to perform steps 1 and 2 above - -3. Run OfflineIMAP by typing "offlineimap" - -That's it! - -================================================== -Frequently Asked Questions -================================================== - -Q. I get a message saying "UID validity problem for folder; skipping". -What does this mean and how do I fix it? - -A. IMAP servers use a unique ID (UID) to refer to a specific message. -This number is guaranteed to be unique to a particular message -FOREVER. No other message in the same folder will ever get the same -UID. UIDs are an integral part of OfflineIMAP's synchronization -scheme; they are used to match up messages on your computer to -messages on the server. - -Sometimes, the UIDs on the server might get reset. Usually this will -happen if you delete and then recreate a folder. When you create a -folder, the server will often start the UID back from 1. But -OfflineIMAP might still have the UIDs from the previous folder by the -same name stored. OfflineIMAP will detect this condition and skip the -folder. This is GOOD, because it prevents data loss. - -You can fix it by removing your local folder and cache data. For -instance, if your folders are under ~/Folders and the folder with the -problem is INBOX, you'd type this: - -rm -r ~/Folders/INBOX -rm ~/.offlineimap/AccountName/INBOX - -(replacing AccountName with the account name as specified in -~/.offlineimaprc) - -Next time you run OfflineIMAP, it will re-download the folder with the -new UIDs. Note that the procedure specified above will lose any local -changes made to the folder. - -Some IMAP servers are broken and do not support UIDs properly. If you -continue to get this error for all your folders even after performing -the above procedure, it is likely that your IMAP server falls into -this category. OfflineIMAP is incompatible with such servers. Using -OfflineIMAP with them will not destroy any mail, but at the same time, -it will not actually synchronize it either. (OfflineIMAP will detect -this condition and abort prior to synchronization) - --------------------------------------------------- - -Q. What platforms does OfflineIMAP run on? - -A. It should run on most platforms supported by Python, which are -quite a few. - --------------------------------------------------- - -Q. I'm using Mutt. Other IMAP synchronization programs require me to -"set maildir_trash=yes". Do I need to do that with OfflineIMAP? - -A. No. OfflineIMAP is smart enough to figure out message deletion -without this extra crutch. You'll get the best results if you don't -use that setting, in fact. - --------------------------------------------------- - -Q. How do I specify the names of my folders? - -A. You do not need to. OfflineIMAP is smart enough to automatically -figure out what folders are present on the IMAP server and synchronize -them. - --------------------------------------------------- - -Q. How can I prevent certain folders from being synced? - -A. This feature will be introduced in a future version of OfflineIMAP. - --------------------------------------------------- - -Q. How can I add or delete a folder? - -A. OfflineIMAP does not currently provide this feature. - --------------------------------------------------- - -Q. Are there any specific warnings or things I should be aware of -before using OfflineIMAP? - -A. Yes. OfflineIMAP does a two-way synchronization. That is, if you -make a change to the mail on the server, it will be propogated to your -local copy, and vise-versa. Some people might think that it would be -wise to just delete all their local mail folders periodically. If you -do this with OfflineIMAP, remember to also remove your local status -cache (~/.offlineimap by default). Otherwise, OfflineIMAP will take -this as an intentional deletion of many messages and will interpret -your action as requesting them to be deleted from the server as well. -(If you don't understand this, don't worry; you probably won't -encounter this situation) - --------------------------------------------------- - -Q. What's thie Mailbox name recorder (mbnames) thing all about? - -A. The Mutt mail reader is not capable of automatically determining -the names of your mailboxes. OfflineIMAP can help it (or many other) -programs out be writing these names out in a format you specify. See -the example offlineimap.conf file for details. - --------------------------------------------------- - -Q. Can I synchronize multiple accounts with OfflineIMAP? - -A. Sure. Just name them all in the accounts line in the general -section of the config file, and add a per-account section for each one. - --------------------------------------------------- - -Q. Do you support POP? - -A. No. POP is not robust enough to do a completely reliable -multi-machine synchronization like OfflineIMAP can do. OfflineIMAP -will not support it. - --------------------------------------------------- - -Q. Do you support mailbox formats other than Maildir? - -A. Not at present. There is no technical reason not to; just no -demand yet. Maildir is a superior format anyway. - --------------------------------------------------- - -Q. [technical] Why are your Maildir message filenames so huge? - -A. OfflineIMAP has two relevant principles: 1) never modifying your -messages in any way and 2) ensuring 100% reliable synchronizations. -In order to do a reliable sync, OfflineIMAP must have a way to -uniquely identify each e-mail. Three pieces of information are -required to do this: your account name, the folder name, and the -message UID. The account name can be calculated from the path in -which your messages are. The folder name can usually be as well, BUT -some mail clients move messages between folders by simply moving the -file, leaving the name intact. - -So, OfflineIMAP must store both a UID folder ID. The folder ID is -necessary so OfflineIMAP can detect a message moved to a different -folder. OfflineIMAP stores the UID (U= number) and an md5sum of the -foldername (FMD5= number) to facilitate this. - --------------------------------------------------- - -Q. Can you provide an example of using OfflineIMAP with Mutt and -multiple accounts? - -A. Sure. I set it up to have a single Mail directory with additional -directories under that for each account. So, mkdir ~/Mail. Then, -in your ~/.offlineimaprc: - -Set "accounts = Personal, Work" - -Make sure you have a [Personal] and a [Work] section, with different -pathnames. Enable [mbnames]. - -In each account section, do something like this: - -localfolders = ~/Mail/Personal - -or - -localfolders = ~/Mail/Work - -In Mutt: - -add lines like this to your ~/.muttrc: - -source ~/path-to-mbnames-muttrc-mailboxes - -folder-hook Personal set from="youremail@personal.com" -folder-hook Work set from="youremail@work.com" -set mbox_type=Maildir -set folder=$HOME/Mail -set spoolfile=+Personal/INBOX - -That's it! - --------------------------------------------------- - -Q. What about the speed of the sync? - -A. OfflineIMAP 2.0 contains a multithreaded system. A good way to -experiment is by setting maxsyncaccounts to 3 and maxconnections to 3 -in each account clause. - -This lets OfflineIMAP open up multiple connections simultaneously. -That will let it process multiple folders and messages at once. In -most cases, this will increase performance of the sync. - -Don't set the number too high. If you do that, things might actually -slow down as your link gets saturated. Also, too many connections can -cause mail servers to have excessive load. Administrators might take -unkindly to this, and the server might bog down. There are many -variables in the optimal setting; experimentation may help. - -An informal benchmark yields these results for my setup: - -OfflineIMAP 2.0 sync with multitreading: 9 seconds -OfflineIMAP 1.x sync w/o multithreading: 20 seconds -GNUS sync: 5 minutes -MacOS X Mail.app "manual cache" method: 10 minutes - -OfflineIMAP's default configuration example does not have -multithreading enabled. You must configure it yourself to gain these -performance benefits. This decision was taken to provide a "works out -of the box" experience. diff --git a/head/manual.html b/head/manual.html new file mode 100644 index 0000000..40708ec --- /dev/null +++ b/head/manual.html @@ -0,0 +1,960 @@ + + + + +OFFLINEIMAP + + + +

OFFLINEIMAP

+NAME
+SYNOPSIS
+DESCRIPTION
+INSTALLATION
+CONFIGURATION
+OPTIONS
+EXAMPLES
+ERRORS
+OTHER FREQUENTLY ASKED QUESTIONS
+CONFORMING TO
+NOTES
+BUGS
+COPYRIGHT
+AUTHOR
+SEE ALSO
+ +
+ + + +

NAME

+ + +
+OfflineIMAP - Powerful IMAP/Maildir synchronization and reader support
+ +

SYNOPSIS

+ + + +
+offlineimap [ -1 ] [ -a +accountlist ] [ -c configfile ]
+[ -d ] [ -u interface ]
+ + + +
+offlineimap -h | --help
+ +

DESCRIPTION

+ + + +
+OfflineIMAP is a tool to simplify your e-mail +reading. With OfflineIMAP, you can read the same +mailbox from multiple computers. You get a current copy of +your messages on each computer, and changes you make one +place will be visible on all other systems. For instance, +you can delete a message on your home computer, and it will +appear deleted on your work computer as well. +OfflineIMAP is also useful if you want to use a mail +reader that does not have IMAP support, has poor IMAP +support, or does not provide disconnected +operation.
+ + + +
+OfflineIMAP is FAST; it synchronizes my two +accounts with over 50 folders in 3 seconds. Other similar +tools might take over a minute, and achieve a less-reliable +result. Some mail readers can take over 10 minutes to do the +same thing, and some don't even support it at all. Unlike +other mail tools, OfflineIMAP features a +multi-threaded synchronization algorithm that can +dramatically speed up performance in many situations by +synchronizing several different things +simultaneously.
+ + + +
+OfflineIMAP is FLEXIBLE; you can customize +which folders are synced via regular expressions, lists, or +Python expressions; a versatile and comprehensive +configuration file is used to control behavior; two user +interfaces are built-in; fine-tuning of synchronization +performance is possible; internal or external automation is +supported; SSL and PREAUTH tunnels are both supported; +offline (or "unplugged") reading is supported; and +esoteric IMAP features are supported to ensure compatibility +with the widest variety of IMAP servers.
+ + + +
+OfflineIMAP is SAFE; it uses an algorithm +designed to prevent mail loss at all costs. Because of the +design of this algorithm, even programming errors should not +result in loss of mail. I am so confident in the algorithm +that I use my own personal and work accounts for testing of +OfflineIMAP pre-release, development, and beta +releases.
+ + + +
+METHOD OF OPERATION
+ + + +
+OfflineIMAP operates by maintaining a hierarchy of +mail folders in Maildir format locally. Your own mail reader +will read mail from this tree, and need never know that the +mail comes from IMAP. OfflineIMAP will detect changes +to the mail folders on your IMAP server and your own +computer and bi-directionally synchronize them, copying, +marking, and deleting messages as necessary.
+ +

INSTALLATION

+ + + +
+If you are reading this document via the "man" +command, it is likely that you have no installation tasks to +perform; your system administrator has already installed it. +If you need to install it yourself, you have three options: +a system-wide installation with Debian, system-wide +installation with other systems, and a single-user +installation. You can download the latest version of +OfflineIMAP from +http://quux.org/devel/offlineimap/.
+ + + +
+PREREQUISITES
+ + + +
+In order to use OfflineIMAP, you need to have these +conditions satisfied:
+ + + +
+Your mail server must support IMAP. Most Internet Service +Providers and corporate networks do, and most operating +systems have an IMAP implementation readily +available.
+ + + +
+You must have Python version 2.2.1 or above installed. If +you are running on Debian GNU/Linux, this requirement will +automatically be taken care of for you. If you do not have +Python already, check with your system administrator or +operating system vendor; or, download it from +http://www.python.org/. If you intend to use the Tk +interface, you must have Tkiner (python-tk) installed. If +you intend to use the SSL interface, your Python must have +been built with SSL support.
+ + + +
+Have a mail reader that supports the Maildir mailbox format. +Most modern mail readers have this support built-in, so you +can choose from a wide variety of mail servers. This format +is also known as the "qmail" format, so any mail +reader compatible with it will work with +OfflineIMAP.
+ + + +
+DEBIAN SYSTEM-WIDE INSTALLATION
+ + + +
+If you are tracking Debian unstable, you may install +OfflineIMAP by simply running the following command +as root:
+ + + +
+apt-get install offlineimap
+ + + +
+If you are not tracking Debian unstable, download the Debian +.deb package from the OfflineIMAP website and then run +dpkg -i to install the downloaded package. Then, go +to CONFIGURATION below. You will type offlineimap to +invoke the program.
+ + + +
+OTHER SYSTEM-WIDE INSTALLATION
+ + + +
+Download the tar.gz version of the package from the website. +Then run these commands:
+ + + +
+tar -zxvf offlineimap-x.y.z.tar.gz
+cd offlineimap-x.y.z
+python2.2 setup.py
+ + + +
+Some systems will need to use python instead of +python2.2. Next, proceed to configuration. You will +type offlineimap to invoke the program.
+ + + +
+SINGLE-ACCOUNT INSTALLATION
+ + + +
+Download the tar.gz version of the package from the website. +Then run these commands:
+ + + +
+tar -zxvf offlineimap-x.y.z.tar.gz
+cd offlineimap-x.y.z
+ + + +
+When you want to run OfflineIMAP, you will issue the +cd command as above and then type +./offlineimap; there is no installation step +necessary.
+ +

CONFIGURATION

+ + + +
+OfflineIMAP is regulated by a configuration file that +is normally stored in ~/.offlineimaprc. +OfflineIMAP ships with a file named +offlineimap.conf that you should copy to that +location and then edit. This file is vital to proper +operation of the system; it sets everything you need to run +OfflineIMAP. Full documentation for the configuration +file is included within the sample file.
+ +

OPTIONS

+ + + +
+Most configuration is done via the configuration file. +Nevertheless, there are a few options that you may set for +OfflineIMAP.
+ + + +
+-1
+ + + +
+Disable all multithreading operations and use solely a +single-thread sync. This effectively sets the +maxsyncaccounts and all maxconnections +configuration file variables to 1.
+ + + +
+-a accountlist
+ + + +
+Overrides the accounts section in the config file. +Lets you specify a particular account or set of accounts to +sync without having to edit the config file. You might use +this to exclude certain accounts, or to sync some accounts +that you normally prefer not to.
+ + + +
+-c configfile
+ + + +
+Specifies a configuration file to use in lieu of the +default, ~/.offlineimaprc.
+ + + +
+-d
+ + + +
+Enables IMAP protocol stream and parsing debugging. This is +useful if you are trying to track down a malfunction or +figure out what is going on under the hood. I suggest that +you use this with -1 in order to make the results +more sensible. Note that this output will contain full IMAP +protocol in plain text, including passwords, so take care to +remove that from the debugging output before sending it to +anyone else.
+ + + +
+-h, --help
+ + + +
+Show summary of options.
+ + + +
+-u interface
+ + + +
+Specifies an alternative user interface module to use. This +overrides the default specified in the configuration file. +The UI specified with -u will be forced to be used, +even if its isuable() method states that it cannot +be. Use this option with care.
+ +

EXAMPLES

+ + + +
+Here is an example configuration for a particularly complex +situation; more examples will be added later.
+ + + +
+MULTIPLE ACCOUNTS WITH MUTT
+ + + +
+This example shows you how to set up OfflineIMAP to +synchronize multiple accounts with the mutt mail +reader.
+ + + +
+Start by creating a directory to hold your folders:
+mkdir ~/Mail
+ + + +
+In your ~/.offlineimaprc, specify this:
+accounts = Personal, Work
+ + + +
+Make sure that you have both a [Personal] and a +[Work] section, with different localfolder pathnames +and enable [mbnames].
+ + + +
+In each account section, do something like this:
+localfolders = ~/Mail/Personal
+ + + +
+Add these lines to your ~/.muttrc:
+source ~/path-to-mbnames-muttrc-mailboxes
+folder-hook Personal set +from="youremail@personal.com"
+folder-hook Work set from="youremail@work.com"
+set mbox_type=Maildir
+set folder=$HOME/Mail
+set spoolfile=+Personal/INBOX
+ + + +
+That's it!
+ +

ERRORS

+ + + +
+If you get one of some frequently-encountered or confusing +errors, please check this section.
+ + + +
+UID validity problem for folder
+ + + +
+IMAP servers use a unique ID (UID) to refer to a specific +message. This number is guaranteed to be unique to a +particular message FOREVER. No other message in the same +folder will ever get the same UID. UIDs are an integral part +of OfflineIMAP's synchronization scheme; they are used to +match up messages on your computer to messages on the +server.
+ + + +
+Sometimes, the UIDs on the server might get reset. Usually +this will happen if you delete and then recreate a folder. +When you create a folder, the server will often start the +UID back from 1. But OfflineIMAP might still have the +UIDs from the previous folder by the same name stored. +OfflineIMAP will detect this condition and skip the +folder. This is GOOD, because it prevents data +loss.
+ + + +
+You can fix it by removing your local folder and cache data. +For instance, if your folders are under ~/Folders and +the folder with the problem is INBOX, you'd type +this:
+ + + +
+rm -r ~/Folders/INBOX
+rm ~/.offlineimap/AccountName/INBOX
+ + + +
+(replacing AccountName with the account name as specified in +~/.offlineimaprc)
+ + + +
+Next time you run OfflineIMAP, it will re-download +the folder with the new UIDs. Note that the procedure +specified above will lose any local changes made to the +folder.
+ + + +
+Some IMAP servers are broken and do not support UIDs +properly. If you continue to get this error for all your +folders even after performing the above procedure, it is +likely that your IMAP server falls into this category. +OfflineIMAP is incompatible with such servers. Using +OfflineIMAP with them will not destroy any mail, but +at the same time, it will not actually synchronize it +either. (OfflineIMAP will detect this condition and abort +prior to synchronization)
+ +

OTHER FREQUENTLY ASKED QUESTIONS

+ + + +
+There are some other FAQs that might not fit into another +section of this document, and they are enumerated +here.
+ + + +
+What platforms does OfflineIMAP run on?
+ + + +
+It should run on most platforms supported by Python, which +are quite a few.
+ + + +
+I'm using Mutt. Other IMAP sync programs require me to +use set maildir_trash=yes . Do I need to do that with +OfflineIMAP?
+ + + +
+No. OfflineIMAP is smart enough to figure out message +deletion without this extra crutch. You'll get the best +results if you don't use this setting, in fact.
+ + + +
+How do I specify the names of my +folders?
+ + + +
+You do not need to. OfflineIMAP is smart enough to +automatically figure out what folders are present on the +IMAP server and synchronize them. You can use the +folderfilter and foldertrans configuration +file options to request certain folders and rename them as +they come in if you like.
+ + + +
+How can I prevent certain folders from being +synced?
+ + + +
+Use the folderfilter option in the configuration +file.
+ + + +
+How can I add or delete a folder?
+ + + +
+OfflineIMAP does not currently provide this feature, +but if you create a new folder on the IMAP server, it will +be created locally automatically.
+ + + +
+Are there any other warnings that I should be aware +of?
+ + + +
+Yes; see the NOTES section below.
+ + + +
+What is the mailbox name recorder (mbnames) +for?
+ + + +
+The Mutt mail reader is not capable of automatically +determining the names of your mailboxes. OfflineIMAP can +help it (or many other) programs out be writing these names +out in a format you specify. See the example +offlineimap.conf file for details.
+ + + +
+Can I synchronize multiple accounts with +OfflineIMAP?
+ + + +
+Sure. Just name them all in the accounts line in the general +section of the config file, and add a per-account section +for each one.
+ + + +
+Does OfflineIMAP support POP?
+ + + +
+No. POP is not robust enough to do a completely reliable +multi-machine synchronization like OfflineIMAP can do. +OfflineIMAP will not support it.
+ + + +
+Do you support mailbox formats other than +Maildir?
+ + + +
+Not at present. There is no technical reason not to; just no +demand yet. Maildir is a superior format +anyway.
+ + + +
+[technical] Why are your Maildir message filenames so +huge?
+ + + +
+OfflineIMAP has two relevant principles: 1) never +modifying your messages in any way and 2) ensuring 100% +reliable synchronizations. In order to do a reliable sync, +OfflineIMAP must have a way to uniquely identify each +e-mail. Three pieces of information are required to do this: +your account name, the folder name, and the message UID. The +account name can be calculated from the path in which your +messages are. The folder name can usually be as well, BUT +some mail clients move messages between folders by simply +moving the file, leaving the name intact.
+ + + +
+So, OfflineIMAP must store both a UID folder ID. The +folder ID is necessary so OfflineIMAP can detect a +message moved to a different folder. OfflineIMAP +stores the UID (U= number) and an md5sum of the foldername +(FMD5= number) to facilitate this.
+ + + +
+What is the speed of OfflineIMAP's sync?
+ + + +
+OfflineIMAP versions 2.0 and above contain a +multithreaded system. A good way to experiment is by setting +maxsyncaccounts to 3 and maxconnections to 3 in each account +clause.
+ + + +
+This lets OfflineIMAP open up multiple connections +simultaneously. That will let it process multiple folders +and messages at once. In most cases, this will increase +performance of the sync.
+ + + +
+Don't set the number too high. If you do that, things might +actually slow down as your link gets saturated. Also, too +many connections can cause mail servers to have excessive +load. Administrators might take unkindly to this, and the +server might bog down. There are many variables in the +optimal setting; experimentation may help.
+ + + +
+An informal benchmark yields these results for my +setup:
+ + + +
+10 minutes with MacOS X Mail.app "manual +cache"
+5 minutes with GNUS agent sync
+20 seconds with OfflineIMAP 1.x
+9 seconds with OfflineIMAP 2.x
+3 seconds with OfflineIMAP 3.x "cold start"
+2 seconds with OfflineIMAP 3.x "held +connection"
+ +

CONFORMING TO

+ + + +
+Internet Message Access Protocol version 4rev1 (IMAP 4rev1) +as specified in RFC2060
+ + + +
+Maildir as specified in +http://www.qmail.org/qmail-manual-html/man5/maildir.html and +http://cr.yp.to/proto/maildir.html.
+ + + +
+Standard Python 2.2.1 as implemented on POSIX-compliant +systems.
+ +

NOTES

+ + + +
+DELETING LOCAL FOLDERS
+ + + +
+OfflineIMAP does a two-way synchronization. That is, +if you make a change to the mail on the server, it will be +propogated to your local copy, and vise-versa. Some people +might think that it would be wise to just delete all their +local mail folders periodically. If you do this with +OfflineIMAP, remember to also remove your local status cache +(~/.offlineimap by default). Otherwise, OfflineIMAP will +take this as an intentional deletion of many messages and +will interpret your action as requesting them to be deleted +from the server as well. (If you don't understand this, +don't worry; you probably won't encounter this +situation)
+ + + +
+MAILING LIST
+ + + +
+There is an OfflineIMAP mailing list available.
+ + + +
+To subscribe, send the text "Subscribe" in the +subject of a mail to offlineimap-request@complete.org. To +post, send the message to +offlineimap@complete.org.
+ +

BUGS

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

COPYRIGHT

+ + + +
+OfflineIMAP is Copyright (C) 2002 John Goerzen.
+ + + +
+This program is free software; you can redistribute it +and/or modify it under the terms of the GNU General Public +License as published by the Free Software Foundation; either +version 2 of the License, or (at your option) any later +version.
+ + + +
+This program is distributed in the hope that it will be +useful, but WITHOUT ANY WARRANTY; without even the implied +warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR +PURPOSE. See the GNU General Public License for more +details.
+ + + +
+You should have received a copy of the GNU General Public +License along with this program; if not, write +to:
+ + + +
+Free Software Foundation, Inc.
+59 Temple Place
+Suite 330
+Boston, MA 02111-1307
+USA
+ +

AUTHOR

+ + + +
+OfflineIMAP, its libraries, documentation, and all +included files, except where noted, was written by John +Goerzen <jgoerzen@complete.org> and copyright is held +as stated in the COPYRIGHT section.
+ + + +
+OfflineIMAP may be downloaded, and information found, from +its homepage via either Gopher or HTTP:
+ + + +
+gopher://quux.org/1/devel/offlineimap
+http://quux.org/devel/offlineimap
+ +

SEE ALSO

+ + + +
+mutt(1), python(1).
+
+ + diff --git a/head/manual.pdf b/head/manual.pdf new file mode 100644 index 0000000..e52e88e Binary files /dev/null and b/head/manual.pdf differ diff --git a/head/manual.ps b/head/manual.ps new file mode 100644 index 0000000..131ed1c --- /dev/null +++ b/head/manual.ps @@ -0,0 +1,704 @@ +%!PS-Adobe-3.0 +%%Creator: groff version 1.17.2 +%%CreationDate: Thu Jul 11 15:42:22 2002 +%%DocumentNeededResources: font Times-Roman +%%+ font Times-Bold +%%+ font Times-Italic +%%DocumentSuppliedResources: procset grops 1.17 2 +%%Pages: 6 +%%PageOrder: Ascend +%%Orientation: Portrait +%%EndComments +%%BeginProlog +%%BeginResource: procset grops 1.17 2 +/setpacking where{ +pop +currentpacking +true setpacking +}if +/grops 120 dict dup begin +/SC 32 def +/A/show load def +/B{0 SC 3 -1 roll widthshow}bind def +/C{0 exch ashow}bind def +/D{0 exch 0 SC 5 2 roll awidthshow}bind def +/E{0 rmoveto show}bind def +/F{0 rmoveto 0 SC 3 -1 roll widthshow}bind def +/G{0 rmoveto 0 exch ashow}bind def +/H{0 rmoveto 0 exch 0 SC 5 2 roll awidthshow}bind def +/I{0 exch rmoveto show}bind def +/J{0 exch rmoveto 0 SC 3 -1 roll widthshow}bind def +/K{0 exch rmoveto 0 exch ashow}bind def +/L{0 exch rmoveto 0 exch 0 SC 5 2 roll awidthshow}bind def +/M{rmoveto show}bind def +/N{rmoveto 0 SC 3 -1 roll widthshow}bind def +/O{rmoveto 0 exch ashow}bind def +/P{rmoveto 0 exch 0 SC 5 2 roll awidthshow}bind def +/Q{moveto show}bind def +/R{moveto 0 SC 3 -1 roll widthshow}bind def +/S{moveto 0 exch ashow}bind def +/T{moveto 0 exch 0 SC 5 2 roll awidthshow}bind def +/SF{ +findfont exch +[exch dup 0 exch 0 exch neg 0 0]makefont +dup setfont +[exch/setfont cvx]cvx bind def +}bind def +/MF{ +findfont +[5 2 roll +0 3 1 roll +neg 0 0]makefont +dup setfont +[exch/setfont cvx]cvx bind def +}bind def +/level0 0 def +/RES 0 def +/PL 0 def +/LS 0 def +/MANUAL{ +statusdict begin/manualfeed true store end +}bind def +/PLG{ +gsave newpath clippath pathbbox grestore +exch pop add exch pop +}bind def +/BP{ +/level0 save def +1 setlinecap +1 setlinejoin +72 RES div dup scale +LS{ +90 rotate +}{ +0 PL translate +}ifelse +1 -1 scale +}bind def +/EP{ +level0 restore +showpage +}bind def +/DA{ +newpath arcn stroke +}bind def +/SN{ +transform +.25 sub exch .25 sub exch +round .25 add exch round .25 add exch +itransform +}bind def +/DL{ +SN +moveto +SN +lineto stroke +}bind def +/DC{ +newpath 0 360 arc closepath +}bind def +/TM matrix def +/DE{ +TM currentmatrix pop +translate scale newpath 0 0 .5 0 360 arc closepath +TM setmatrix +}bind def +/RC/rcurveto load def +/RL/rlineto load def +/ST/stroke load def +/MT/moveto load def +/CL/closepath load def +/FL{ +currentgray exch setgray fill setgray +}bind def +/BL/fill load def +/LW/setlinewidth load def +/RE{ +findfont +dup maxlength 1 index/FontName known not{1 add}if dict begin +{ +1 index/FID ne{def}{pop pop}ifelse +}forall +/Encoding exch def +dup/FontName exch def +currentdict end definefont pop +}bind def +/DEFS 0 def +/EBEGIN{ +moveto +DEFS begin +}bind def +/EEND/end load def +/CNT 0 def +/level1 0 def +/PBEGIN{ +/level1 save def +translate +div 3 1 roll div exch scale +neg exch neg exch translate +0 setgray +0 setlinecap +1 setlinewidth +0 setlinejoin +10 setmiterlimit +[]0 setdash +/setstrokeadjust where{ +pop +false setstrokeadjust +}if +/setoverprint where{ +pop +false setoverprint +}if +newpath +/CNT countdictstack def +userdict begin +/showpage{}def +}bind def +/PEND{ +clear +countdictstack CNT sub{end}repeat +level1 restore +}bind def +end def +/setpacking where{ +pop +setpacking +}if +%%EndResource +%%IncludeResource: font Times-Roman +%%IncludeResource: font Times-Bold +%%IncludeResource: font Times-Italic +grops begin/DEFS 1 dict def DEFS begin/u{.001 mul}bind def end/RES 72 +def/PL 792 def/LS false def/ENC0[/asciicircum/asciitilde/Scaron/Zcaron +/scaron/zcaron/Ydieresis/trademark/quotesingle/.notdef/.notdef/.notdef +/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef +/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef +/.notdef/.notdef/space/exclam/quotedbl/numbersign/dollar/percent +/ampersand/quoteright/parenleft/parenright/asterisk/plus/comma/hyphen +/period/slash/zero/one/two/three/four/five/six/seven/eight/nine/colon +/semicolon/less/equal/greater/question/at/A/B/C/D/E/F/G/H/I/J/K/L/M/N/O +/P/Q/R/S/T/U/V/W/X/Y/Z/bracketleft/backslash/bracketright/circumflex +/underscore/quoteleft/a/b/c/d/e/f/g/h/i/j/k/l/m/n/o/p/q/r/s/t/u/v/w/x/y +/z/braceleft/bar/braceright/tilde/.notdef/quotesinglbase/guillemotleft +/guillemotright/bullet/florin/fraction/perthousand/dagger/daggerdbl +/endash/emdash/ff/fi/fl/ffi/ffl/dotlessi/dotlessj/grave/hungarumlaut +/dotaccent/breve/caron/ring/ogonek/quotedblleft/quotedblright/oe/lslash +/quotedblbase/OE/Lslash/.notdef/exclamdown/cent/sterling/currency/yen +/brokenbar/section/dieresis/copyright/ordfeminine/guilsinglleft +/logicalnot/minus/registered/macron/degree/plusminus/twosuperior +/threesuperior/acute/mu/paragraph/periodcentered/cedilla/onesuperior +/ordmasculine/guilsinglright/onequarter/onehalf/threequarters +/questiondown/Agrave/Aacute/Acircumflex/Atilde/Adieresis/Aring/AE +/Ccedilla/Egrave/Eacute/Ecircumflex/Edieresis/Igrave/Iacute/Icircumflex +/Idieresis/Eth/Ntilde/Ograve/Oacute/Ocircumflex/Otilde/Odieresis +/multiply/Oslash/Ugrave/Uacute/Ucircumflex/Udieresis/Yacute/Thorn +/germandbls/agrave/aacute/acircumflex/atilde/adieresis/aring/ae/ccedilla +/egrave/eacute/ecircumflex/edieresis/igrave/iacute/icircumflex/idieresis +/eth/ntilde/ograve/oacute/ocircumflex/otilde/odieresis/divide/oslash +/ugrave/uacute/ucircumflex/udieresis/yacute/thorn/ydieresis]def +/Times-Italic@0 ENC0/Times-Italic RE/Times-Bold@0 ENC0/Times-Bold RE +/Times-Roman@0 ENC0/Times-Roman RE +%%EndProlog +%%Page: 1 1 +%%BeginPageSetup +BP +%%EndPageSetup +/F0 10/Times-Roman@0 SF 111.22(OFFLINEIMAP\(1\) Of)72 48 R +(\215ineIMAP manual)-.25 E(OFFLINEIMAP\(1\))113.72 E/F1 10.95 +/Times-Bold@0 SF -.219(NA)72 84 S(ME).219 E F0(Of)108 96 Q +(\215ineIMAP \255 Po)-.25 E +(werful IMAP/Maildir synchronization and reader support)-.25 E F1 +(SYNOPSIS)72 112.8 Q/F2 10/Times-Bold@0 SF(of\215ineimap)108 124.8 Q F0 +([)2.5 E F22.5 E F0 2.5(][)2.5 G F2A/F3 10/Times-Italic@0 SF +(accountlist)2.5 E F0 2.5(][)2.5 G F2A F3(con\214g\214le)2.5 E F0 +(])2.5 E([)108 136.8 Q F22.5 E F0 2.5(][)2.5 G F2A F3 +(interface)2.5 E F0(])2.5 E F2(of\215ineimap \255h)108 160.8 Q F0(|)2.5 +E F2(\255\255help)2.5 E F1(DESCRIPTION)72 177.6 Q F2(Of\215ineIMAP)108 +189.6 Q F0 .019(is a tool to simplify your e-mail reading.)2.519 F -.4 +(Wi)5.019 G(th).4 E F2(Of\215ineIMAP)2.519 E(,)-.92 E F0 .018 +(you can read the same mailbox)2.519 F 1.115(from multiple computers.) +108 201.6 R -1.1(Yo)6.115 G 3.615(ug)1.1 G 1.115(et a current cop)-3.615 +F 3.616(yo)-.1 G 3.616(fy)-3.616 G 1.116(our messages on each computer) +-3.616 F 3.616(,a)-.4 G 1.116(nd changes you)-3.616 F(mak)108 213.6 Q +2.915(eo)-.1 G .414(ne place will be visible on all other systems.) +-2.915 F -.15(Fo)5.414 G 2.914(ri).15 G .414 +(nstance, you can delete a message on your home)-2.914 F(computer)108 +225.6 Q 3.5(,a)-.4 G 1(nd it will appear deleted on your w)-3.5 F 1 +(ork computer as well.)-.1 F F2(Of\215ineIMAP)6 E F0 1 +(is also useful if you)3.5 F -.1(wa)108 237.6 S .827 +(nt to use a mail reader that does not ha).1 F 1.127 -.15(ve I)-.2 H +.827(MAP support, has poor IMAP support, or does not pro).15 F(vide)-.15 +E(disconnected operation.)108 249.6 Q F2(Of\215ineIMAP)108 266.4 Q F0 +(is)3.216 E F3 -1.15(FA)3.216 G(ST)1.15 E(;)-.65 E F0 .716 +(it synchronizes my tw)3.216 F 3.216(oa)-.1 G .716(ccounts with o)-3.216 +F -.15(ve)-.15 G 3.216(r5).15 G 3.216(0f)-3.216 G .717 +(olders in 3 seconds.)-3.216 F .717(Other similar)5.717 F .26 +(tools might tak)108 278.4 R 2.76(eo)-.1 G -.15(ve)-2.91 G 2.76(ram).15 +G .26(inute, and achie)-2.76 F .56 -.15(ve a l)-.25 H .259 +(ess-reliable result.).15 F .259(Some mail readers can tak)5.259 F 2.759 +(eo)-.1 G -.15(ve)-2.909 G 2.759(r1).15 G 2.759(0m)-2.759 G(in-)-2.759 E +.157(utes to do the same thing, and some don')108 290.4 R 2.657(te)-.18 +G -.15(ve)-2.907 G 2.657(ns).15 G .157(upport it at all.)-2.657 F(Unlik) +5.158 E 2.658(eo)-.1 G .158(ther mail tools,)-2.658 F F2(Of\215ineIMAP) +2.658 E F0(fea-)2.658 E .321(tures a multi-threaded synchronization alg\ +orithm that can dramatically speed up performance in man)108 302.4 R +2.82(ys)-.15 G(itu-)-2.82 E(ations by synchronizing se)108 314.4 Q -.15 +(ve)-.25 G(ral dif).15 E(ferent things simultaneously)-.25 E(.)-.65 E F2 +(Of\215ineIMAP)108 331.2 Q F0(is)3.065 E F3(FLEXIBLE;)3.065 E F0 .566 +(you can customize which folders are synced via re)3.065 F .566(gular e) +-.15 F .566(xpressions, lists, or)-.15 F .734(Python e)108 343.2 R .734 +(xpressions; a v)-.15 F .734(ersatile and comprehensi)-.15 F 1.034 -.15 +(ve c)-.25 H .733(on\214guration \214le is used to control beha).15 F +.733(vior; tw)-.2 F 3.233(ou)-.1 G(ser)-3.233 E(interf)108 355.2 Q .535 +(aces are b)-.1 F .535(uilt-in; \214ne-tuning of synchronization perfor\ +mance is possible; internal or e)-.2 F .535(xternal automa-)-.15 F .441 +(tion is supported; SSL and PREA)108 367.2 R .441 +(UTH tunnels are both supported; of)-.55 F .44 +(\215ine \(or "unplugged"\) reading is sup-)-.25 F .543(ported; and eso\ +teric IMAP features are supported to ensure compatibility with the wide\ +st v)108 379.2 R .544(ariety of IMAP)-.25 F(serv)108 391.2 Q(ers.)-.15 E +F2(Of\215ineIMAP)108 408 Q F0(is)4.065 E F3(SAFE;)4.065 E F0 1.565 +(it uses an algorithm designed to pre)4.065 F -.15(ve)-.25 G 1.565 +(nt mail loss at all costs.).15 F 1.564(Because of the)6.564 F .01 +(design of this algorithm, e)108 420 R -.15(ve)-.25 G 2.51(np).15 G .01 +(rogramming errors should not result in loss of mail.)-2.51 F 2.511(Ia) +5.011 G 2.511(ms)-2.511 G 2.511(oc)-2.511 G .011(on\214dent in the) +-2.511 F .448(algorithm that I use my o)108 432 R .448 +(wn personal and w)-.25 F .448(ork accounts for testing of)-.1 F F2 +(Of\215ineIMAP)2.948 E F0 .448(pre-release, de)2.948 F -.15(ve)-.25 G +(lop-).15 E(ment, and beta releases.)108 444 Q F2(METHOD OF OPERA)87 +460.8 Q(TION)-.95 E(Of\215ineIMAP)108 472.8 Q F0 .07 +(operates by maintaining a hierarch)2.57 F 2.57(yo)-.05 G 2.57(fm)-2.57 +G .07(ail folders in Maildir format locally)-2.57 F 5.07(.Y)-.65 G .07 +(our o)-6.17 F .07(wn mail)-.25 F .618 +(reader will read mail from this tree, and need ne)108 484.8 R -.15(ve) +-.25 G 3.118(rk).15 G(no)-3.118 E 3.118(wt)-.25 G .617 +(hat the mail comes from IMAP)-3.118 F(.)-1.11 E F2(Of\215ineIMAP)5.617 +E F0 .849(will detect changes to the mail folders on your IMAP serv)108 +496.8 R .849(er and your o)-.15 F .849(wn computer and bi-directionally) +-.25 F(synchronize them, cop)108 508.8 Q +(ying, marking, and deleting messages as necessary)-.1 E(.)-.65 E F1 +(INST)72 525.6 Q(ALLA)-.986 E(TION)-1.04 E F0 .491 +(If you are reading this document via the "man" command, it is lik)108 +537.6 R .49(ely that you ha)-.1 F .79 -.15(ve n)-.2 H 2.99(oi).15 G .49 +(nstallation tasks to)-2.99 F .043 +(perform; your system administrator has already installed it.)108 549.6 +R .044(If you need to install it yourself, you ha)5.043 F .344 -.15 +(ve t)-.2 H(hree).15 E .39(options: a system-wide installation with Deb\ +ian, system-wide installation with other systems, and a single-)108 +561.6 R 12.823(user installation.)108 573.6 R -1.1(Yo)17.823 G 15.323 +(uc)1.1 G 12.823(an do)-15.323 F 12.823(wnload the latest v)-.25 F +12.823(ersion of Of)-.15 F 12.823(\215ineIMAP from)-.25 F +(http://quux.or)108 585.6 Q(g/de)-.18 E -.15(ve)-.25 G(l/of).15 E +(\215ineimap/.)-.25 E F2(PREREQ)87 602.4 Q(UISITES)-.1 E F0 +(In order to use Of)108 614.4 Q(\215ineIMAP)-.25 E 2.5(,y)-1.11 G +(ou need to ha)-2.5 E .3 -.15(ve t)-.2 H(hese conditions satis\214ed:) +.15 E 32.5<8359>108 631.2 S .197(our mail serv)-33.6 F .197 +(er must support IMAP)-.15 F 5.197(.M)-1.11 G .197 +(ost Internet Service Pro)-5.197 F .197(viders and corporate netw)-.15 F +.196(orks do,)-.1 F(and most operating systems ha)144 643.2 Q .3 -.15 +(ve a)-.2 H 2.5(nI).15 G(MAP implementation readily a)-2.5 E -.25(va)-.2 +G(ilable.).25 E 32.5<8359>108 660 S .085(ou must ha)-33.6 F .385 -.15 +(ve P)-.2 H .085(ython v).15 F .085(ersion 2.2.1 or abo)-.15 F .385 -.15 +(ve i)-.15 H 2.585(nstalled. If).15 F .086 +(you are running on Debian GNU/Linux,)2.585 F .813 +(this requirement will automatically be tak)144 672 R .813 +(en care of for you.)-.1 F .812(If you do not ha)5.812 F 1.112 -.15 +(ve P)-.2 H .812(ython already).15 F(,)-.65 E 3.88 +(check with your system administrator or operating system v)144 684 R +3.88(endor; or)-.15 F 6.38(,d)-.4 G -.25(ow)-6.38 G 3.88(nload it from) +.25 F(http://www)144 696 Q(.p)-.65 E(ython.or)-.1 E 3.378(g/. If)-.18 F +.878(you intend to use the Tk interf)3.378 F .877(ace, you must ha)-.1 F +1.177 -.15(ve T)-.2 H .877(kiner \(p).15 F(ython-tk\))-.1 E 2.859 +(installed. If)144 708 R .359(you intend to use the SSL interf)2.859 F +.359(ace, your Python must ha)-.1 F .66 -.15(ve b)-.2 H .36(een b).15 F +.36(uilt with SSL sup-)-.2 F(port.)144 720 Q(John Goerzen)72 768 Q +(July 11, 2002)151.655 E(1)201.915 E EP +%%Page: 2 2 +%%BeginPageSetup +BP +%%EndPageSetup +/F0 10/Times-Roman@0 SF 111.22(OFFLINEIMAP\(1\) Of)72 48 R +(\215ineIMAP manual)-.25 E(OFFLINEIMAP\(1\))113.72 E 32.5<8348>108 84 S +-2.25 -.2(av e)-32.5 H 2.784(am)2.984 G .284 +(ail reader that supports the Maildir mailbox format.)-2.784 F .284 +(Most modern mail readers ha)5.284 F .584 -.15(ve t)-.2 H(his).15 E .111 +(support b)144 96 R .112(uilt-in, so you can choose from a wide v)-.2 F +.112(ariety of mail serv)-.25 F 2.612(ers. This)-.15 F .112 +(format is also kno)2.612 F(wn)-.25 E(as the "qmail" format, so an)144 +108 Q 2.5(ym)-.15 G(ail reader compatible with it will w)-2.5 E +(ork with Of)-.1 E(\215ineIMAP)-.25 E(.)-1.11 E/F1 10/Times-Bold@0 SF +(DEBIAN SYSTEM-WIDE INST)87 124.8 Q(ALLA)-.9 E(TION)-.95 E F0 .708 +(If you are tracking Debian unstable, you may install)108 136.8 R F1 +(Of\215ineIMAP)3.208 E F0 .708(by simply running the follo)3.208 F .708 +(wing com-)-.25 F(mand as root:)108 148.8 Q F1 +(apt-get install of\215ineimap)108 165.6 Q F0 .339 +(If you are not tracking Debian unstable, do)108 182.4 R .34 +(wnload the Debian .deb package from the Of)-.25 F .34 +(\215ineIMAP website)-.25 F .39(and then run)108 194.4 R F1 .39(dpkg -i) +2.89 F F0 .389(to install the do)2.89 F .389(wnloaded package.)-.25 F +.389(Then, go to CONFIGURA)5.389 F .389(TION belo)-1.11 F 4.189 -.65 +(w. Y)-.25 H .389(ou will)-.45 F(type)108 206.4 Q F1(of\215ineimap)2.5 E +F0(to in)2.5 E -.2(vo)-.4 G .2 -.1(ke t).2 H(he program.).1 E F1 -.4(OT) +87 223.2 S(HER SYSTEM-WIDE INST).4 E(ALLA)-.9 E(TION)-.95 E F0(Do)108 +235.2 Q(wnload the tar)-.25 E(.gz v)-.55 E +(ersion of the package from the website.)-.15 E +(Then run these commands:)5 E F1(tar -zxvf of\215ineimap-x.y)108 252 Q +(.z.tar)-.7 E(.gz)-1 E(cd of\215ineimap-x.y)108 264 Q(.z)-.7 E +(python2.2 setup.py)108 276 Q F0 1.272(Some systems will need to use)108 +292.8 R F1(python)3.773 E F0 1.273(instead of)3.773 F F1(python2.2.) +3.773 E F0(Ne)6.273 E 1.273(xt, proceed to con\214guration.)-.15 F -1.1 +(Yo)6.273 G 3.773(uw)1.1 G(ill)-3.773 E(type)108 304.8 Q F1 +(of\215ineimap)2.5 E F0(to in)2.5 E -.2(vo)-.4 G .2 -.1(ke t).2 H +(he program.).1 E F1(SINGLE-A)87 321.6 Q(CCOUNT INST)-.55 E(ALLA)-.9 E +(TION)-.95 E F0(Do)108 333.6 Q(wnload the tar)-.25 E(.gz v)-.55 E +(ersion of the package from the website.)-.15 E +(Then run these commands:)5 E F1(tar -zxvf of\215ineimap-x.y)108 350.4 Q +(.z.tar)-.7 E(.gz)-1 E(cd of\215ineimap-x.y)108 362.4 Q(.z)-.7 E F0 .149 +(When you w)108 379.2 R .149(ant to run)-.1 F F1(Of\215ineIMAP)2.648 E +(,)-.92 E F0 .148(you will issue the)2.648 F F1(cd)2.648 E F0 .148 +(command as abo)2.648 F .448 -.15(ve a)-.15 H .148(nd then type).15 F F1 +(./of\215ineimap;)2.648 E F0(there is no installation step necessary)108 +391.2 Q(.)-.65 E/F2 10.95/Times-Bold@0 SF(CONFIGURA)72 408 Q(TION)-1.04 +E F1(Of\215ineIMAP)108 420 Q F0 .508(is re)3.008 F .508 +(gulated by a con\214guration \214le that is normally stored in)-.15 F +/F3 10/Times-Italic@0 SF(~/.of)3.009 E(\215ineimapr)-.18 E(c.)-.37 E F1 +(Of\215ineIMAP)5.509 E F0 .004(ships with a \214le named)108 432 R F3 +(of)2.503 E(\215ineimap.conf)-.18 E F0 .003(that you should cop)2.503 F +2.503(yt)-.1 G 2.503(ot)-2.503 G .003(hat location and then edit.)-2.503 +F .003(This \214le is vital)5.003 F .255 +(to proper operation of the system; it sets e)108 444 R -.15(ve)-.25 G +.256(rything you need to run).15 F F1(Of\215ineIMAP)2.756 E(.)-1.1 E F0 +.256(Full documentation for)5.256 F +(the con\214guration \214le is included within the sample \214le.)108 +456 Q F2(OPTIONS)72 472.8 Q F0 .061 +(Most con\214guration is done via the con\214guration \214le.)108 484.8 +R(Ne)5.061 E -.15(ve)-.25 G .061(rtheless, there are a fe).15 F 2.561 +(wo)-.25 G .061(ptions that you may set)-2.561 F(for)108 496.8 Q F1 +(Of\215ineIMAP)2.5 E(.)-1.1 E108 513.6 Q F0 .281(Disable all mult\ +ithreading operations and use solely a single-thread sync.)25.3 F .281 +(This ef)5.281 F(fecti)-.25 E -.15(ve)-.25 G .281(ly sets the).15 F F1 +(maxsyncaccounts)144 525.6 Q F0(and all)2.5 E F1(maxconnections)2.5 E F0 +(con\214guration \214le v)2.5 E(ariables to 1.)-.25 E F1108 542.4 +Q F3(accountlist)2.5 E F0(Ov)144 554.4 Q .84(errides the)-.15 F F1 +(accounts)3.34 E F0 .84(section in the con\214g \214le.)3.34 F .84 +(Lets you specify a particular account or set of)5.84 F 1.647 +(accounts to sync without ha)144 566.4 R 1.647 +(ving to edit the con\214g \214le.)-.2 F -1.1(Yo)6.648 G 4.148(um)1.1 G +1.648(ight use this to e)-4.148 F 1.648(xclude certain)-.15 F +(accounts, or to sync some accounts that you normally prefer not to.)144 +578.4 Q F1108 595.2 Q F3(con\214g\214le)2.5 E F0 +(Speci\214es a con\214guration \214le to use in lieu of the def)144 +607.2 Q(ault,)-.1 E F3(~/.of)2.5 E(\215ineimapr)-.18 E(c.)-.37 E F1 +108 624 Q F0 1.139(Enables IMAP protocol stream and parsing deb) +24.74 F 3.639(ugging. This)-.2 F 1.138 +(is useful if you are trying to track)3.639 F(do)144 636 Q .081 +(wn a malfunction or \214gure out what is going on under the hood.)-.25 +F 2.582(Is)5.082 G .082(uggest that you use this with)-2.582 F F1 +144 648 Q F0 .336(in order to mak)2.836 F 2.836(et)-.1 G .335 +(he results more sensible.)-2.836 F .335 +(Note that this output will contain full IMAP proto-)5.335 F 1.7 +(col in plain te)144 660 R 1.7(xt, including passw)-.15 F 1.7 +(ords, so tak)-.1 F 4.2(ec)-.1 G 1.7(are to remo)-4.2 F 2 -.15(ve t)-.15 +H 1.7(hat from the deb).15 F 1.7(ugging output)-.2 F +(before sending it to an)144 672 Q(yone else.)-.15 E F1 +(\255h, \255\255help)108 688.8 Q F0(Sho)144 700.8 Q 2.5(ws)-.25 G +(ummary of options.)-2.5 E(John Goerzen)72 768 Q(July 11, 2002)151.655 E +(2)201.915 E EP +%%Page: 3 3 +%%BeginPageSetup +BP +%%EndPageSetup +/F0 10/Times-Roman@0 SF 111.22(OFFLINEIMAP\(1\) Of)72 48 R +(\215ineIMAP manual)-.25 E(OFFLINEIMAP\(1\))113.72 E/F1 10/Times-Bold@0 +SF108 84 Q/F2 10/Times-Italic@0 SF(interface)2.5 E F0 1.133 +(Speci\214es an alternati)144 96 R 1.433 -.15(ve u)-.25 H 1.133 +(ser interf).15 F 1.133(ace module to use.)-.1 F 1.133(This o)6.133 F +-.15(ve)-.15 G 1.133(rrides the def).15 F 1.132(ault speci\214ed in the) +-.1 F .28(con\214guration \214le.)144 108 R .28(The UI speci\214ed with) +5.28 F F1(-u)2.78 E F0 .281(will be forced to be used, e)2.78 F -.15(ve) +-.25 G 2.781(ni).15 G 2.781(fi)-2.781 G(ts)-2.781 E F1(isuable\(\))2.781 +E F0(method)2.781 E(states that it cannot be.)144 120 Q +(Use this option with care.)5 E/F3 10.95/Times-Bold@0 SF(EXAMPLES)72 +136.8 Q F0(Here is an e)108 148.8 Q +(xample con\214guration for a particularly comple)-.15 E 2.5(xs)-.15 G +(ituation; more e)-2.5 E(xamples will be added later)-.15 E(.)-.55 E F1 +(MUL)87 165.6 Q(TIPLE A)-.92 E(CCOUNTS WITH MUTT)-.55 E F0 .514(This e) +108 177.6 R .514(xample sho)-.15 F .514(ws you ho)-.25 F 3.014(wt)-.25 G +3.014(os)-3.014 G .514(et up)-3.014 F F1(Of\215ineIMAP)3.014 E F0 .513 +(to synchronize multiple accounts with the mutt mail)3.014 F(reader)108 +189.6 Q(.)-.55 E(Start by creating a directory to hold your folders:)108 +206.4 Q F1(mkdir ~/Mail)108 218.4 Q F0(In your)108 235.2 Q F2(~/.of)2.5 +E(\215ineimapr)-.18 E(c,)-.37 E F0(specify this:)2.5 E F1(accounts = P) +108 247.2 Q(ersonal, W)-.2 E(ork)-.75 E F0(Mak)108 264 Q 2.82(es)-.1 G +.32(ure that you ha)-2.82 F .62 -.15(ve b)-.2 H .32(oth a).15 F F1([P) +2.821 E(ersonal])-.2 E F0 .321(and a)2.821 F F1([W)2.821 E(ork])-.75 E +F0 .321(section, with dif)2.821 F .321(ferent localfolder pathnames and) +-.25 F(enable)108 276 Q F1([mbnames].)2.5 E F0 +(In each account section, do something lik)108 292.8 Q 2.5(et)-.1 G +(his:)-2.5 E F1(localf)108 304.8 Q(olders = ~/Mail/P)-.25 E(ersonal)-.2 +E F0(Add these lines to your)108 321.6 Q F2(~/.muttr)2.5 E(c:)-.37 E F1 +(sour)108 333.6 Q(ce ~/path-to-mbnames-muttr)-.18 E(c-mailboxes)-.18 E +-.25(fo)108 345.6 S(lder).25 E(-hook P)-.37 E(ersonal set fr)-.2 E +(om="y)-.18 E(our)-.25 E(email@personal.com")-.18 E -.25(fo)108 357.6 S +(lder).25 E(-hook W)-.37 E(ork set fr)-.75 E(om="y)-.18 E(our)-.25 E +(email@w)-.18 E(ork.com")-.1 E(set mbox_type=Maildir)108 369.6 Q(set f) +108 381.6 Q(older=$HOME/Mail)-.25 E(set spool\214le=+P)108 393.6 Q +(ersonal/INBO)-.2 E(X)-.4 E F0(That')108 410.4 Q 2.5(si)-.55 G(t!)-2.5 E +F3(ERR)72 427.2 Q(ORS)-.329 E F0(If you get one of some frequently-enco\ +untered or confusing errors, please check this section.)108 439.2 Q F1 +(UID v)87 456 Q(alidity pr)-.1 E(oblem f)-.18 E(or f)-.25 E(older)-.25 E +F0 1.638(IMAP serv)108 468 R 1.637 +(ers use a unique ID \(UID\) to refer to a speci\214c message.)-.15 F +1.637(This number is guaranteed to be)6.637 F 1.109 +(unique to a particular message FOREVER.)108 480 R 1.109 +(No other message in the same folder will e)6.109 F -.15(ve)-.25 G 3.61 +(rg).15 G 1.11(et the same)-3.61 F 2.874(UID. UIDs)108 492 R .373 +(are an inte)2.874 F .373(gral part of Of)-.15 F(\215ineIMAP')-.25 E +2.873(ss)-.55 G .373(ynchronization scheme; the)-2.873 F 2.873(ya)-.15 G +.373(re used to match up mes-)-2.873 F +(sages on your computer to messages on the serv)108 504 Q(er)-.15 E(.) +-.55 E .107(Sometimes, the UIDs on the serv)108 520.8 R .108 +(er might get reset.)-.15 F .108 +(Usually this will happen if you delete and then recreate)5.108 F 3.743 +(af)108 532.8 S(older)-3.743 E 6.243(.W)-.55 G 1.243 +(hen you create a folder)-6.243 F 3.742(,t)-.4 G 1.242(he serv)-3.742 F +1.242(er will often start the UID back from 1.)-.15 F(But)6.242 E F1 +(Of\215ineIMAP)3.742 E F0 .302(might still ha)108 544.8 R .602 -.15 +(ve t)-.2 H .302(he UIDs from the pre).15 F .302 +(vious folder by the same name stored.)-.25 F F1(Of\215ineIMAP)5.303 E +F0 .303(will detect this)2.803 F(condition and skip the folder)108 556.8 +Q 5(.T)-.55 G(his is GOOD, because it pre)-5 E -.15(ve)-.25 G +(nts data loss.).15 E -1.1(Yo)108 573.6 S 2.827(uc)1.1 G .327 +(an \214x it by remo)-2.827 F .327 +(ving your local folder and cache data.)-.15 F -.15(Fo)5.327 G 2.827(ri) +.15 G .327(nstance, if your folders are under)-2.827 F F2(~/F)2.826 E +(old-)-1.05 E(er)108 585.6 Q(s)-.1 E F0 +(and the folder with the problem is INBO)2.5 E(X, you')-.4 E 2.5(dt)-.5 +G(ype this:)-2.5 E F1(rm -r ~/F)108 602.4 Q(olders/INBO)-.25 E(X)-.4 E +(rm ~/.of\215ineimap/AccountName/INBO)108 614.4 Q(X)-.4 E F0 +(\(replacing AccountName with the account name as speci\214ed in)108 +631.2 Q F2(~/.of)2.5 E(\215ineimapr)-.18 E(c\))-.37 E F0(Ne)108 648 Q +.801(xt time you run)-.15 F F1(Of\215ineIMAP)3.301 E(,)-.92 E F0 .802 +(it will re-do)3.302 F .802(wnload the folder with the ne)-.25 F 3.302 +(wU)-.25 G 3.302(IDs. Note)-3.302 F .802(that the proce-)3.302 F +(dure speci\214ed abo)108 660 Q .3 -.15(ve w)-.15 H(ill lose an).15 E +2.5(yl)-.15 G(ocal changes made to the folder)-2.5 E(.)-.55 E .523 +(Some IMAP serv)108 676.8 R .522(ers are brok)-.15 F .522 +(en and do not support UIDs properly)-.1 F 5.522(.I)-.65 G 3.022(fy) +-5.522 G .522(ou continue to get this error for all)-3.022 F .066 +(your folders e)108 688.8 R -.15(ve)-.25 G 2.566(na).15 G .066 +(fter performing the abo)-2.566 F .366 -.15(ve p)-.15 H .066 +(rocedure, it is lik).15 F .066(ely that your IMAP serv)-.1 F .066(er f) +-.15 F .067(alls into this cat-)-.1 F -.15(eg)108 700.8 S(ory).15 E(.) +-.65 E F1(Of\215ineIMAP)5.984 E F0 .984(is incompatible with such serv) +3.484 F 3.484(ers. Using)-.15 F F1(Of\215ineIMAP)3.484 E F0 .984 +(with them will not destro)3.484 F(y)-.1 E(an)108 712.8 Q 2.769(ym)-.15 +G .269(ail, b)-2.769 F .269 +(ut at the same time, it will not actually synchronize it either)-.2 F +5.27(.\()-.55 G(Of)-5.27 E .27(\215ineIMAP will detect this con-)-.25 F +(dition and abort prior to synchronization\))108 724.8 Q(John Goerzen)72 +768 Q(July 11, 2002)151.655 E(3)201.915 E EP +%%Page: 4 4 +%%BeginPageSetup +BP +%%EndPageSetup +/F0 10/Times-Roman@0 SF 111.22(OFFLINEIMAP\(1\) Of)72 48 R +(\215ineIMAP manual)-.25 E(OFFLINEIMAP\(1\))113.72 E/F1 10.95 +/Times-Bold@0 SF -.438(OT)72 84 S(HER FREQ).438 E(UENTL)-.11 E 2.738(YA) +-1.007 G(SKED Q)-2.738 E(UESTIONS)-.11 E F0 .684(There are some other F) +108 96 R -.55(AQ)-.74 G 3.184(st).55 G .684 +(hat might not \214t into another section of this document, and the) +-3.184 F 3.183(ya)-.15 G .683(re enumer)-3.183 F(-)-.2 E(ated here.)108 +108 Q/F2 10/Times-Bold@0 SF(What platf)108 124.8 Q +(orms does Of\215ineIMAP run on?)-.25 E F0(It should run on most platfo\ +rms supported by Python, which are quite a fe)144 136.8 Q -.65(w.)-.25 G +F2 .688(I'm using Mutt. Other IMAP sync pr)108 153.6 R .689(ograms r) +-.18 F(equir)-.18 E 3.189(em)-.18 G 3.189(et)-3.189 G 3.189(ou)-3.189 G +.689(se set maildir_trash=y)-3.189 F .689(es . Do I need to)-.1 F +(do that with Of\215ineIMAP?)108 165.6 Q F0(No.)144 177.6 Q F2 +(Of\215ineIMAP)7.27 E F0 2.27 +(is smart enough to \214gure out message deletion without this e)4.77 F +2.27(xtra crutch.)-.15 F -1.1(Yo)144 189.6 S(u')1.1 E +(ll get the best results if you don')-.1 E 2.5(tu)-.18 G +(se this setting, in f)-2.5 E(act.)-.1 E F2(Ho)108 206.4 Q 2.5(wd)-.1 G +2.5(oIs)-2.5 G(pecify the names of my f)-2.5 E(olders?)-.25 E F0 -1.1 +(Yo)144 218.4 S 3.55(ud)1.1 G 3.55(on)-3.55 G 1.05(ot need to.)-3.55 F +F2(Of\215ineIMAP)6.05 E F0 1.05 +(is smart enough to automatically \214gure out what folders are)3.55 F +.678(present on the IMAP serv)144 230.4 R .678(er and synchronize them.) +-.15 F -1.1(Yo)5.679 G 3.179(uc)1.1 G .679(an use the)-3.179 F F2 -.25 +(fo)3.179 G(lder\214lter).25 E F0(and)3.179 E F2 -.25(fo)3.179 G +(ldertrans).25 E F0(con\214guration \214le options to request certain f\ +olders and rename them as the)144 242.4 Q 2.5(yc)-.15 G +(ome in if you lik)-2.5 E(e.)-.1 E F2(Ho)108 259.2 Q 2.5(wc)-.1 G +(an I pr)-2.5 E -2.3 -.15(ev e)-.18 H(nt certain f).15 E(olders fr)-.25 +E(om being synced?)-.18 E F0(Use the)144 271.2 Q F2 -.25(fo)2.5 G +(lder\214lter).25 E F0(option in the con\214guration \214le.)2.5 E F2 +(Ho)108 288 Q 2.5(wc)-.1 G(an I add or delete a f)-2.5 E(older?)-.25 E +(Of\215ineIMAP)144 300 Q F0 .504(does not currently pro)3.004 F .504 +(vide this feature, b)-.15 F .504(ut if you create a ne)-.2 F 3.003(wf) +-.25 G .503(older on the IMAP)-3.003 F(serv)144 312 Q(er)-.15 E 2.5(,i) +-.4 G 2.5(tw)-2.5 G(ill be created locally automatically)-2.5 E(.)-.65 E +F2(Ar)108 328.8 Q 2.5(et)-.18 G(her)-2.5 E 2.5(ea)-.18 G(ny other war) +-2.5 E(nings that I should be awar)-.15 E 2.5(eo)-.18 G(f?)-2.5 E F0 -1 +(Ye)144 340.8 S(s; see the NO)1 E(TES section belo)-.4 E -.65(w.)-.25 G +F2(What is the mailbox name r)108 357.6 Q(ecorder \(mbnames\) f)-.18 E +(or?)-.25 E F0 1.019(The Mutt mail reader is not capable of automatical\ +ly determining the names of your mailbox)144 369.6 R(es.)-.15 E(Of)144 +381.6 Q .266(\215ineIMAP can help it \(or man)-.25 F 2.765(yo)-.15 G +.265(ther\) programs out be writing these names out in a format you) +-2.765 F(specify)144 393.6 Q 5(.S)-.65 G(ee the e)-5 E(xample of)-.15 E +(\215ineimap.conf \214le for details.)-.25 E F2(Can I synchr)108 410.4 Q +(onize multiple accounts with Of\215ineIMAP?)-.18 E F0 3.344(Sure. Just) +144 422.4 R .845(name them all in the accounts line in the general sect\ +ion of the con\214g \214le, and add a)3.344 F(per)144 434.4 Q +(-account section for each one.)-.2 E F2 +(Does Of\215ineIMAP support POP?)108 451.2 Q F0 4.077(No. POP)144 463.2 +R 1.576(is not rob)4.077 F 1.576(ust enough to do a completely reliable\ + multi-machine synchronization lik)-.2 F(e)-.1 E(Of)144 475.2 Q +(\215ineIMAP can do.)-.25 E(Of)5 E(\215ineIMAP will not support it.)-.25 +E F2(Do y)108 492 Q(ou support mailbox f)-.25 E +(ormats other than Maildir?)-.25 E F0 .409(Not at present.)144 504 R +.409(There is no technical reason not to; just no demand yet.)5.409 F +.41(Maildir is a superior for)5.41 F(-)-.2 E(mat an)144 516 Q(yw)-.15 E +(ay)-.1 E(.)-.65 E F2([technical] Wh)108 532.8 Q 2.5(ya)-.15 G .36 -.18 +(re y)-2.5 H(our Maildir message \214lenames so huge?)-.07 E +(Of\215ineIMAP)144 544.8 Q F0 .959(has tw)3.459 F 3.459(or)-.1 G(ele) +-3.459 E -.25(va)-.25 G .959(nt principles: 1\) ne).25 F -.15(ve)-.25 G +3.459(rm).15 G .958(odifying your messages in an)-3.459 F 3.458(yw)-.15 +G .958(ay and 2\))-3.558 F .493 +(ensuring 100% reliable synchronizations.)144 556.8 R .493 +(In order to do a reliable sync,)5.493 F F2(Of\215ineIMAP)2.993 E F0 +.494(must ha)2.993 F -.15(ve)-.2 G 3.095(aw)144 568.8 S .595 +(ay to uniquely identify each e-mail.)-3.195 F .594 +(Three pieces of information are required to do this: your)5.594 F .537 +(account name, the folder name, and the message UID.)144 580.8 R .538 +(The account name can be calculated from)5.537 F 1.082 +(the path in which your messages are.)144 592.8 R 1.082 +(The folder name can usually be as well, B)6.082 F 1.081(UT some mail) +-.1 F(clients mo)144 604.8 Q .3 -.15(ve m)-.15 H +(essages between folders by simply mo).15 E(ving the \214le, lea)-.15 E +(ving the name intact.)-.2 E(So,)144 621.6 Q F2(Of\215ineIMAP)3.2 E F0 +.7(must store both a UID folder ID.)3.2 F .7 +(The folder ID is necessary so)5.7 F F2(Of\215ineIMAP)3.2 E F0 .456 +(can detect a message mo)144 633.6 R -.15(ve)-.15 G 2.956(dt).15 G 2.955 +(oad)-2.956 G(if)-2.955 E .455(ferent folder)-.25 F(.)-.55 E F2 +(Of\215ineIMAP)5.455 E F0 .455(stores the UID \(U= number\) and)2.955 F +(an md5sum of the foldername \(FMD5= number\) to f)144 645.6 Q +(acilitate this.)-.1 E F2(What is the speed of Of\215ineIMAP')108 662.4 +Q 2.5(ss)-.37 G(ync?)-2.5 E(Of\215ineIMAP)144 674.4 Q F0 -.15(ve)2.89 G +.39(rsions 2.0 and abo).15 F .691 -.15(ve c)-.15 H .391 +(ontain a multithreaded system.).15 F 2.891(Ag)5.391 G .391(ood w)-2.891 +F .391(ay to e)-.1 F(xperiment)-.15 E(is by setting maxsyncaccounts to \ +3 and maxconnections to 3 in each account clause.)144 686.4 Q .382 +(This lets Of)144 703.2 R .382 +(\215ineIMAP open up multiple connections simultaneously)-.25 F 5.381 +(.T)-.65 G .381(hat will let it process mul-)-5.381 F +(tiple folders and messages at once.)144 715.2 Q +(In most cases, this will increase performance of the sync.)5 E +(John Goerzen)72 768 Q(July 11, 2002)151.655 E(4)201.915 E EP +%%Page: 5 5 +%%BeginPageSetup +BP +%%EndPageSetup +/F0 10/Times-Roman@0 SF 111.22(OFFLINEIMAP\(1\) Of)72 48 R +(\215ineIMAP manual)-.25 E(OFFLINEIMAP\(1\))113.72 E(Don')144 84 Q 3.103 +(ts)-.18 G .603(et the number too high.)-3.103 F .603 +(If you do that, things might actually slo)5.603 F 3.104(wd)-.25 G -.25 +(ow)-3.104 G 3.104(na).25 G 3.104(sy)-3.104 G .604(our link gets)-3.104 +F 2.633(saturated. Also,)144 96 R .133(too man)2.633 F 2.633(yc)-.15 G +.132(onnections can cause mail serv)-2.633 F .132(ers to ha)-.15 F .432 +-.15(ve ex)-.2 H(cessi).15 E .432 -.15(ve l)-.25 H 2.632 +(oad. Administra-).15 F .506(tors might tak)144 108 R 3.006(eu)-.1 G +.506(nkindly to this, and the serv)-3.006 F .507(er might bog do)-.15 F +3.007(wn. There)-.25 F .507(are man)3.007 F 3.007(yv)-.15 G .507 +(ariables in the)-3.257 F(optimal setting; e)144 120 Q +(xperimentation may help.)-.15 E +(An informal benchmark yields these results for my setup:)144 136.8 Q +(10 minutes with MacOS X Mail.app "manual cache")144 153.6 Q 2.5(5m)144 +165.6 S(inutes with GNUS agent sync)-2.5 E(20 seconds with Of)144 177.6 +Q(\215ineIMAP 1.x)-.25 E 2.5(9s)144 189.6 S(econds with Of)-2.5 E +(\215ineIMAP 2.x)-.25 E 2.5(3s)144 201.6 S(econds with Of)-2.5 E +(\215ineIMAP 3.x "cold start")-.25 E 2.5(2s)144 213.6 S(econds with Of) +-2.5 E(\215ineIMAP 3.x "held connection")-.25 E/F1 10.95/Times-Bold@0 SF +(CONFORMING T)72 230.4 Q(O)-.197 E F0 32.5<8349>108 242.4 S +(nternet Message Access Protocol v)-32.5 E(ersion 4re)-.15 E +(v1 \(IMAP 4re)-.25 E(v1\) as speci\214ed in RFC2060)-.25 E 32.5<834d> +108 259.2 S 8.92(aildir as speci\214ed in http://www)-32.5 F(.qmail.or) +-.65 E(g/qmail-manual-html/man5/maildir)-.18 E 8.92(.html and)-.55 F +(http://cr)144 271.2 Q(.yp.to/proto/maildir)-.55 E(.html.)-.55 E 32.5 +<8353>108 288 S +(tandard Python 2.2.1 as implemented on POSIX-compliant systems.)-32.5 E +F1(NO)72 304.8 Q(TES)-.438 E/F2 10/Times-Bold@0 SF +(DELETING LOCAL FOLDERS)87 316.8 Q(Of\215ineIMAP)108 328.8 Q F0 .532 +(does a tw)3.032 F(o-w)-.1 E .532(ay synchronization.)-.1 F .532 +(That is, if you mak)5.532 F 3.032(eac)-.1 G .532 +(hange to the mail on the serv)-3.032 F(er)-.15 E 3.033(,i)-.4 G(t) +-3.033 E .897(will be propog)108 340.8 R .897(ated to your local cop) +-.05 F 2.197 -.65(y, a)-.1 H .897(nd vise-v).65 F 3.397(ersa. Some)-.15 +F .896(people might think that it w)3.397 F .896(ould be wise to)-.1 F +1.59(just delete all their local mail folders periodically)108 352.8 R +6.59(.I)-.65 G 4.09(fy)-6.59 G 1.59(ou do this with Of)-4.09 F +(\215ineIMAP)-.25 E 4.09(,r)-1.11 G 1.59(emember to also)-4.09 F(remo) +108 364.8 Q 1.67 -.15(ve y)-.15 H 1.37(our local status cache \(~/.of) +.15 F 1.37(\215ineimap by def)-.25 F 3.87(ault\). Otherwise,)-.1 F(Of) +3.87 E 1.37(\215ineIMAP will tak)-.25 F 3.87(et)-.1 G 1.37(his as an) +-3.87 F .415(intentional deletion of man)108 376.8 R 2.915(ym)-.15 G +.416(essages and will interpret your action as requesting them to be de\ +leted from)-2.915 F(the serv)108 388.8 Q(er as well.)-.15 E +(\(If you don')5 E 2.5(tu)-.18 G(nderstand this, don')-2.5 E 2.5(tw)-.18 +G(orry; you probably w)-2.6 E(on')-.1 E 2.5(te)-.18 G +(ncounter this situation\))-2.5 E F2(MAILING LIST)87 405.6 Q F0 +(There is an Of)108 417.6 Q(\215ineIMAP mailing list a)-.25 E -.25(va) +-.2 G(ilable.).25 E 2.448 -.8(To s)108 434.4 T .847 +(ubscribe, send the te).8 F .847 +(xt "Subscribe" in the subject of a mail to of)-.15 F +(\215ineimap-request@complete.or)-.25 E 3.347(g. T)-.18 F(o)-.8 E +(post, send the message to of)108 446.4 Q(\215ineimap@complete.or)-.25 E +(g.)-.18 E F1 -.11(BU)72 463.2 S(GS).11 E F0 +(Should be reported to the author at the address speci\214ed belo)108 +475.2 Q -.65(w.)-.25 G F1(COPYRIGHT)72 492 Q F0(Of)108 504 Q +(\215ineIMAP is Cop)-.25 E(yright \(C\) 2002 John Goerzen.)-.1 E .286 +(This program is free softw)108 520.8 R .286(are; you can redistrib)-.1 +F .287(ute it and/or modify it under the terms of the GNU General)-.2 F +.766(Public License as published by the Free Softw)108 532.8 R .766 +(are F)-.1 F .766(oundation; either v)-.15 F .766 +(ersion 2 of the License, or \(at your)-.15 F(option\) an)108 544.8 Q +2.5(yl)-.15 G(ater v)-2.5 E(ersion.)-.15 E .579(This program is distrib) +108 561.6 R .579(uted in the hope that it will be useful, b)-.2 F .58 +(ut WITHOUT ANY W)-.2 F(ARRANTY)-1.2 E 3.08(;w)-.92 G(ithout)-3.08 E +-2.15 -.25(ev e)108 573.6 T 2.73(nt).25 G .23(he implied w)-2.73 F .229 +(arranty of MERCHANT)-.1 F .229(ABILITY or FITNESS FOR A P)-.93 F(AR) +-.92 E .229(TICULAR PURPOSE.)-.6 F(See)5.229 E +(the GNU General Public License for more details.)108 585.6 Q -1.1(Yo) +108 602.4 S 2.77(us)1.1 G .27(hould ha)-2.77 F .57 -.15(ve r)-.2 H(ecei) +.15 E -.15(ve)-.25 G 2.77(dac).15 G(op)-2.77 E 2.77(yo)-.1 G 2.77(ft) +-2.77 G .27 +(he GNU General Public License along with this program; if not, write) +-2.77 F(to:)108 614.4 Q(Free Softw)108 631.2 Q(are F)-.1 E +(oundation, Inc.)-.15 E(59 T)108 643.2 Q(emple Place)-.7 E(Suite 330)108 +655.2 Q(Boston, MA)108 667.2 Q(02111-1307)5 E(USA)108 679.2 Q F1 -.548 +(AU)72 696 S(THOR).548 E F2(Of\215ineIMAP)108 708 Q(,)-.92 E F0 .488 +(its libraries, documentation, and all included \214les, e)2.988 F .488 +(xcept where noted, w)-.15 F .487(as written by John)-.1 F +(Goerzen and cop)-.18 E +(yright is held as stated in the COPYRIGHT section.)-.1 E(John Goerzen) +72 768 Q(July 11, 2002)151.655 E(5)201.915 E EP +%%Page: 6 6 +%%BeginPageSetup +BP +%%EndPageSetup +/F0 10/Times-Roman@0 SF 111.22(OFFLINEIMAP\(1\) Of)72 48 R +(\215ineIMAP manual)-.25 E(OFFLINEIMAP\(1\))113.72 E(Of)108 84 Q +(\215ineIMAP may be do)-.25 E(wnloaded, and information found, from its\ + homepage via either Gopher or HTTP:)-.25 E(gopher://quux.or)108 100.8 Q +(g/1/de)-.18 E -.15(ve)-.25 G(l/of).15 E(\215ineimap)-.25 E +(http://quux.or)108 112.8 Q(g/de)-.18 E -.15(ve)-.25 G(l/of).15 E +(\215ineimap)-.25 E/F1 10.95/Times-Bold@0 SF(SEE ALSO)72 141.6 Q/F2 10 +/Times-Bold@0 SF(mutt)108 153.6 Q F0(\(1\),)A F2(python)2.5 E F0(\(1\).) +A(John Goerzen)72 768 Q(July 11, 2002)151.655 E(6)201.915 E EP +%%Trailer +end +%%EOF diff --git a/head/manual.txt b/head/manual.txt new file mode 100644 index 0000000..6a27a0d --- /dev/null +++ b/head/manual.txt @@ -0,0 +1,456 @@ +OFFLINEIMAP(1) OfflineIMAP manual OFFLINEIMAP(1) + + + +NAME + OfflineIMAP - Powerful IMAP/Maildir synchronization and + reader support + +SYNOPSIS + offlineimap [ -1 ] [ -a accountlist ] [ -c configfile ] + [ -d ] [ -u interface ] + + offlineimap -h | --help + +DESCRIPTION + OfflineIMAP is a tool to simplify your e-mail reading. + With OfflineIMAP, you can read the same mailbox from mul- + tiple computers. You get a current copy of your messages + on each computer, and changes you make one place will be + visible on all other systems. For instance, you can + delete a message on your home computer, and it will appear + deleted on your work computer as well. OfflineIMAP is + also useful if you want to use a mail reader that does not + have IMAP support, has poor IMAP support, or does not pro- + vide disconnected operation. + + OfflineIMAP is FAST; it synchronizes my two accounts with + over 50 folders in 3 seconds. Other similar tools might + take over a minute, and achieve a less-reliable result. + Some mail readers can take over 10 minutes to do the same + thing, and some don't even support it at all. Unlike + other mail tools, OfflineIMAP features a multi-threaded + synchronization algorithm that can dramatically speed up + performance in many situations by synchronizing several + different things simultaneously. + + OfflineIMAP is FLEXIBLE; you can customize which folders + are synced via regular expressions, lists, or Python + expressions; a versatile and comprehensive configuration + file is used to control behavior; two user interfaces are + built-in; fine-tuning of synchronization performance is + possible; internal or external automation is supported; + SSL and PREAUTH tunnels are both supported; offline (or + "unplugged") reading is supported; and esoteric IMAP fea- + tures are supported to ensure compatibility with the + widest variety of IMAP servers. + + OfflineIMAP is SAFE; it uses an algorithm designed to pre- + vent mail loss at all costs. Because of the design of + this algorithm, even programming errors should not result + in loss of mail. I am so confident in the algorithm that + I use my own personal and work accounts for testing of + OfflineIMAP pre-release, development, and beta releases. + + METHOD OF OPERATION + OfflineIMAP operates by maintaining a hierarchy of mail + folders in Maildir format locally. Your own mail reader + will read mail from this tree, and need never know that + the mail comes from IMAP. OfflineIMAP will detect changes + to the mail folders on your IMAP server and your own com- + puter and bi-directionally synchronize them, copying, + marking, and deleting messages as necessary. + +INSTALLATION + If you are reading this document via the "man" command, it + is likely that you have no installation tasks to perform; + your system administrator has already installed it. If + you need to install it yourself, you have three options: a + system-wide installation with Debian, system-wide instal- + lation with other systems, and a single-user installation. + You can download the latest version of OfflineIMAP from + http://quux.org/devel/offlineimap/. + + PREREQUISITES + In order to use OfflineIMAP, you need to have these condi- + tions satisfied: + + o Your mail server must support IMAP. Most Internet + Service Providers and corporate networks do, and + most operating systems have an IMAP implementation + readily available. + + o You must have Python version 2.2.1 or above + installed. If you are running on Debian GNU/Linux, + this requirement will automatically be taken care + of for you. If you do not have Python already, + check with your system administrator or operating + system vendor; or, download it from + http://www.python.org/. If you intend to use the + Tk interface, you must have Tkiner (python-tk) + installed. If you intend to use the SSL interface, + your Python must have been built with SSL support. + + o Have a mail reader that supports the Maildir mail- + box format. Most modern mail readers have this + support built-in, so you can choose from a wide + variety of mail servers. This format is also known + as the "qmail" format, so any mail reader compati- + ble with it will work with OfflineIMAP. + + DEBIAN SYSTEM-WIDE INSTALLATION + If you are tracking Debian unstable, you may install + OfflineIMAP by simply running the following command as + root: + + apt-get install offlineimap + + If you are not tracking Debian unstable, download the + Debian .deb package from the OfflineIMAP website and then + run dpkg -i to install the downloaded package. Then, go + to CONFIGURATION below. You will type offlineimap to + invoke the program. + + OTHER SYSTEM-WIDE INSTALLATION + Download the tar.gz version of the package from the web- + site. Then run these commands: + + tar -zxvf offlineimap-x.y.z.tar.gz + cd offlineimap-x.y.z + python2.2 setup.py + + Some systems will need to use python instead of python2.2. + Next, proceed to configuration. You will type offlineimap + to invoke the program. + + SINGLE-ACCOUNT INSTALLATION + Download the tar.gz version of the package from the web- + site. Then run these commands: + + tar -zxvf offlineimap-x.y.z.tar.gz + cd offlineimap-x.y.z + + When you want to run OfflineIMAP, you will issue the cd + command as above and then type ./offlineimap; there is no + installation step necessary. + +CONFIGURATION + OfflineIMAP is regulated by a configuration file that is + normally stored in ~/.offlineimaprc. OfflineIMAP ships + with a file named offlineimap.conf that you should copy to + that location and then edit. This file is vital to proper + operation of the system; it sets everything you need to + run OfflineIMAP. Full documentation for the configuration + file is included within the sample file. + +OPTIONS + Most configuration is done via the configuration file. + Nevertheless, there are a few options that you may set for + OfflineIMAP. + + -1 Disable all multithreading operations and use + solely a single-thread sync. This effectively sets + the maxsyncaccounts and all maxconnections configu- + ration file variables to 1. + + -a accountlist + Overrides the accounts section in the config file. + Lets you specify a particular account or set of + accounts to sync without having to edit the config + file. You might use this to exclude certain + accounts, or to sync some accounts that you nor- + mally prefer not to. + + -c configfile + Specifies a configuration file to use in lieu of + the default, ~/.offlineimaprc. + + -d Enables IMAP protocol stream and parsing debugging. + This is useful if you are trying to track down a + malfunction or figure out what is going on under + the hood. I suggest that you use this with -1 in + order to make the results more sensible. Note that + this output will contain full IMAP protocol in + plain text, including passwords, so take care to + remove that from the debugging output before send- + ing it to anyone else. + + -h, --help + Show summary of options. + + -u interface + Specifies an alternative user interface module to + use. This overrides the default specified in the + configuration file. The UI specified with -u will + be forced to be used, even if its isuable() method + states that it cannot be. Use this option with + care. + +EXAMPLES + Here is an example configuration for a particularly com- + plex situation; more examples will be added later. + + MULTIPLE ACCOUNTS WITH MUTT + This example shows you how to set up OfflineIMAP to syn- + chronize multiple accounts with the mutt mail reader. + + Start by creating a directory to hold your folders: + mkdir ~/Mail + + In your ~/.offlineimaprc, specify this: + accounts = Personal, Work + + Make sure that you have both a [Personal] and a [Work] + section, with different localfolder pathnames and enable + [mbnames]. + + In each account section, do something like this: + localfolders = ~/Mail/Personal + + Add these lines to your ~/.muttrc: + source ~/path-to-mbnames-muttrc-mailboxes + folder-hook Personal set from="youremail@personal.com" + folder-hook Work set from="youremail@work.com" + set mbox_type=Maildir + set folder=$HOME/Mail + set spoolfile=+Personal/INBOX + + That's it! + +ERRORS + If you get one of some frequently-encountered or confusing + errors, please check this section. + + UID validity problem for folder + IMAP servers use a unique ID (UID) to refer to a specific + message. This number is guaranteed to be unique to a par- + ticular message FOREVER. No other message in the same + folder will ever get the same UID. UIDs are an integral + part of OfflineIMAP's synchronization scheme; they are + used to match up messages on your computer to messages on + the server. + + Sometimes, the UIDs on the server might get reset. Usu- + ally this will happen if you delete and then recreate a + folder. When you create a folder, the server will often + start the UID back from 1. But OfflineIMAP might still + have the UIDs from the previous folder by the same name + stored. OfflineIMAP will detect this condition and skip + the folder. This is GOOD, because it prevents data loss. + + You can fix it by removing your local folder and cache + data. For instance, if your folders are under ~/Folders + and the folder with the problem is INBOX, you'd type this: + + rm -r ~/Folders/INBOX + rm ~/.offlineimap/AccountName/INBOX + + (replacing AccountName with the account name as specified + in ~/.offlineimaprc) + + Next time you run OfflineIMAP, it will re-download the + folder with the new UIDs. Note that the procedure speci- + fied above will lose any local changes made to the folder. + + Some IMAP servers are broken and do not support UIDs prop- + erly. If you continue to get this error for all your + folders even after performing the above procedure, it is + likely that your IMAP server falls into this category. + OfflineIMAP is incompatible with such servers. Using + OfflineIMAP with them will not destroy any mail, but at + the same time, it will not actually synchronize it either. + (OfflineIMAP will detect this condition and abort prior to + synchronization) + + +OTHER FREQUENTLY ASKED QUESTIONS + There are some other FAQs that might not fit into another + section of this document, and they are enumerated here. + + What platforms does OfflineIMAP run on? + It should run on most platforms supported by + Python, which are quite a few. + + I'm using Mutt. Other IMAP sync programs require me to use + set maildir_trash=yes . Do I need to do that with + OfflineIMAP? + No. OfflineIMAP is smart enough to figure out mes- + sage deletion without this extra crutch. You'll + get the best results if you don't use this setting, + in fact. + + How do I specify the names of my folders? + You do not need to. OfflineIMAP is smart enough to + automatically figure out what folders are present + on the IMAP server and synchronize them. You can + use the folderfilter and foldertrans configuration + file options to request certain folders and rename + them as they come in if you like. + + How can I prevent certain folders from being synced? + Use the folderfilter option in the configuration + file. + + How can I add or delete a folder? + OfflineIMAP does not currently provide this fea- + ture, but if you create a new folder on the IMAP + server, it will be created locally automatically. + + Are there any other warnings that I should be aware of? + Yes; see the NOTES section below. + + What is the mailbox name recorder (mbnames) for? + The Mutt mail reader is not capable of automati- + cally determining the names of your mailboxes. + OfflineIMAP can help it (or many other) programs + out be writing these names out in a format you + specify. See the example offlineimap.conf file for + details. + + Can I synchronize multiple accounts with OfflineIMAP? + Sure. Just name them all in the accounts line in + the general section of the config file, and add a + per-account section for each one. + + Does OfflineIMAP support POP? + No. POP is not robust enough to do a completely + reliable multi-machine synchronization like + OfflineIMAP can do. OfflineIMAP will not support + it. + + Do you support mailbox formats other than Maildir? + Not at present. There is no technical reason not + to; just no demand yet. Maildir is a superior for- + mat anyway. + + [technical] Why are your Maildir message filenames so + huge? + OfflineIMAP has two relevant principles: 1) never + modifying your messages in any way and 2) ensuring + 100% reliable synchronizations. In order to do a + reliable sync, OfflineIMAP must have a way to + uniquely identify each e-mail. Three pieces of + information are required to do this: your account + name, the folder name, and the message UID. The + account name can be calculated from the path in + which your messages are. The folder name can usu- + ally be as well, BUT some mail clients move mes- + sages between folders by simply moving the file, + leaving the name intact. + + So, OfflineIMAP must store both a UID folder ID. + The folder ID is necessary so OfflineIMAP can + detect a message moved to a different folder. + OfflineIMAP stores the UID (U= number) and an + md5sum of the foldername (FMD5= number) to facili- + tate this. + + What is the speed of OfflineIMAP's sync? + OfflineIMAP versions 2.0 and above contain a multi- + threaded system. A good way to experiment is by + setting maxsyncaccounts to 3 and maxconnections to + 3 in each account clause. + + This lets OfflineIMAP open up multiple connections + simultaneously. That will let it process multiple + folders and messages at once. In most cases, this + will increase performance of the sync. + + Don't set the number too high. If you do that, + things might actually slow down as your link gets + saturated. Also, too many connections can cause + mail servers to have excessive load. Administra- + tors might take unkindly to this, and the server + might bog down. There are many variables in the + optimal setting; experimentation may help. + + An informal benchmark yields these results for my + setup: + + 10 minutes with MacOS X Mail.app "manual cache" + 5 minutes with GNUS agent sync + 20 seconds with OfflineIMAP 1.x + 9 seconds with OfflineIMAP 2.x + 3 seconds with OfflineIMAP 3.x "cold start" + 2 seconds with OfflineIMAP 3.x "held connection" + +CONFORMING TO + o Internet Message Access Protocol version 4rev1 + (IMAP 4rev1) as specified in RFC2060 + + o Maildir as specified in http://www.qmail.org/qmail- + manual-html/man5/maildir.html and + http://cr.yp.to/proto/maildir.html. + + o Standard Python 2.2.1 as implemented on POSIX-com- + pliant systems. + +NOTES + DELETING LOCAL FOLDERS + OfflineIMAP does a two-way synchronization. That is, if + you make a change to the mail on the server, it will be + propogated to your local copy, and vise-versa. Some peo- + ple might think that it would be wise to just delete all + their local mail folders periodically. If you do this + with OfflineIMAP, remember to also remove your local sta- + tus cache (~/.offlineimap by default). Otherwise, + OfflineIMAP will take this as an intentional deletion of + many messages and will interpret your action as requesting + them to be deleted from the server as well. (If you don't + understand this, don't worry; you probably won't encounter + this situation) + + MAILING LIST + There is an OfflineIMAP mailing list available. + + To subscribe, send the text "Subscribe" in the subject of + a mail to offlineimap-request@complete.org. To post, send + the message to offlineimap@complete.org. + +BUGS + Should be reported to the author at the address specified + below. + +COPYRIGHT + OfflineIMAP is Copyright (C) 2002 John Goerzen. + + This program is free software; you can redistribute it + and/or modify it under the terms of the GNU General Public + License as published by the Free Software Foundation; + either version 2 of the License, or (at your option) any + later version. + + This program is distributed in the hope that it will be + useful, but WITHOUT ANY WARRANTY; without even the implied + warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR + PURPOSE. See the GNU General Public License for more + details. + + You should have received a copy of the GNU General Public + License along with this program; if not, write to: + + Free Software Foundation, Inc. + 59 Temple Place + Suite 330 + Boston, MA 02111-1307 + USA + +AUTHOR + OfflineIMAP, its libraries, documentation, and all + included files, except where noted, was written by John + Goerzen and copyright is held as + stated in the COPYRIGHT section. + + OfflineIMAP may be downloaded, and information found, from + its homepage via either Gopher or HTTP: + + gopher://quux.org/1/devel/offlineimap + http://quux.org/devel/offlineimap + + +SEE ALSO + mutt(1), python(1). + + + +John Goerzen July 11, 2002 OFFLINEIMAP(1) diff --git a/head/offlineimap.1 b/head/offlineimap.1 index bf5cfae..7a66d86 100644 --- a/head/offlineimap.1 +++ b/head/offlineimap.1 @@ -2,7 +2,7 @@ .\" First parameter, NAME, should be all caps .\" Second parameter, SECTION, should be 1-8, maybe w/ subsection .\" other parameters are allowed: see man(7), man(1) -.TH OFFLINEIMAP 1 "July 11, 2002" "quux.org" "OfflineIMAP manual" +.TH OFFLINEIMAP 1 "July 11, 2002" "John Goerzen" "OfflineIMAP manual" .\" Please adjust this date whenever revising the manpage. .\" .\" Some roff macros, for reference: @@ -16,31 +16,33 @@ .\" .sp insert n+1 empty lines .\" for manpage-specific macros, see man(7) .SH NAME -OfflineIMAP \- IMAP/Maildir synchronization and reader support +OfflineIMAP \- Powerful IMAP/Maildir synchronization and reader support .SH SYNOPSIS .B offlineimap [ -.BI -1 +.BI \-1 ] [ -.BI -a \ accountlist +.BI \-a \ accountlist ] [ -.BI -c \ configfile +.BI \-c \ configfile ] .br [ -.BI -d +.BI \-d ] [ -.BI -u " interface" +.BI \-u " interface" ] .\".RI [ -c \ foo ] .\".RI [ options ] " files" ... .br .B offlineimap -.B -h +.B \-h +| +.B \-\-help .\".RI [ options ] " files" ... .SH DESCRIPTION .B OfflineIMAP @@ -90,38 +92,460 @@ should not result in loss of mail. I am so confident in the algorithm that I use my own personal and work accounts for testing of .B OfflineIMAP pre-release, development, and beta releases. +.SS "METHOD OF OPERATION" +.B OfflineIMAP +operates by maintaining a hierarchy of mail folders in Maildir format +locally. Your own mail reader will read mail from this tree, and need +never know that the mail comes from IMAP. +.B OfflineIMAP +will detect changes to the mail folders on your IMAP server and your +own computer and bi-directionally synchronize them, copying, marking, +and deleting messages as necessary. +.SH INSTALLATION +If you are reading this document via the "man" command, it is likely +that you have no installation tasks to perform; your system +administrator has already installed it. If you need to install it +yourself, you have three options: a system-wide installation with +Debian, system-wide installation with other systems, and a single-user +installation. You can download the latest version of OfflineIMAP from +.UR http://quux.org/devel/offlineimap/ +http://quux.org/devel/offlineimap/. +.UE +.SS PREREQUISITES +In order to use OfflineIMAP, you need to have these conditions +satisfied: +.IP \(bu +Your mail server must support IMAP. Most Internet Service Providers +and corporate networks do, and most operating systems have an IMAP +implementation readily available. +.IP \(bu +You must have Python version 2.2.1 or above installed. If you are +running on Debian GNU/Linux, this requirement will automatically be +taken care of for you. If you do not have Python already, check with +your system administrator or operating system vendor; or, download it +from +.UR http://www.python.org/ +http://www.python.org/. +.UE +If you intend to use the Tk interface, you must have Tkiner +(python-tk) installed. If you intend to use the SSL interface, your +Python must have been built with SSL support. +.IP \(bu +Have a mail reader that supports the Maildir mailbox format. Most +modern mail readers have this support built-in, so you can choose from +a wide variety of mail servers. This format is also known as the +"qmail" format, so any mail reader compatible with it will work with +OfflineIMAP. +.SS DEBIAN SYSTEM-WIDE INSTALLATION +If you are tracking Debian unstable, you may install +.B OfflineIMAP +by simply running the following command as root: .PP -This manual page documents briefly the +.B apt-get install offlineimap +.PP +If you are not tracking Debian unstable, download the Debian .deb +package from the OfflineIMAP website +and then run +.B dpkg -i +to install the downloaded package. Then, go to CONFIGURATION below. +You will type .B offlineimap -and -.B bar -commands. -This manual page was written for the Debian distribution -because the original program does not have a manual page. -Instead, it has documentation in the GNU Info format; see below. +to invoke the program. +.SS OTHER SYSTEM-WIDE INSTALLATION +Download the tar.gz version of the package from the website. Then run +these commands: .PP +.B tar -zxvf offlineimap-x.y.z.tar.gz +.br +.B cd offlineimap-x.y.z +.br +.B python2.2 setup.py +.PP +Some systems will need to use +.B python +instead of +.B python2.2. +Next, proceed to configuration. You will type +.B offlineimap +to invoke the program. +.SS SINGLE-ACCOUNT INSTALLATION +Download the tar.gz version of the package from the website. Then run +these commands: +.PP +.B tar -zxvf offlineimap-x.y.z.tar.gz +.br +.B cd offlineimap-x.y.z +.PP +When you want to run +.B OfflineIMAP, +you will issue the +.B cd +command as above and then type +.B ./offlineimap; +there is no installation step necessary. +.\"################################################## +.SH CONFIGURATION +.B OfflineIMAP +is regulated by a configuration file that is normally stored in +.I ~/.offlineimaprc. +.B OfflineIMAP +ships with a file named +.I offlineimap.conf +that you should copy to that location and then edit. This file is +vital to proper operation of the system; it sets everything you need +to run +.B OfflineIMAP. +Full documentation for the configuration file is included within the +sample file. +.\"################################################## .\" TeX users may be more comfortable with the \fB\fP and .\" \fI\fP escape sequences to invode bold face and italics, .\" respectively. -\fBofflineimap\fP is a program that... +.\"\fBofflineimap\fP is a program that... .SH OPTIONS -These programs follow the usual GNU command line syntax, with long -options starting with two dashes (`-'). -A summary of options is included below. -For a complete description, see the Info files. +Most configuration is done via the configuration file. Nevertheless, +there are a few options that you may set for +.B OfflineIMAP. +.TP +.B \-1 +Disable all multithreading operations and use solely a single-thread +sync. This effectively sets the +.B maxsyncaccounts +and all +.B maxconnections +configuration file variables to 1. +.TP +.BI \-a \ accountlist +Overrides the +.B accounts +section in the config file. Lets you specify a particular account or +set of accounts to sync without having to edit the config file. You +might use this to exclude certain accounts, or to sync some accounts +that you normally prefer not to. +.TP +.BI \-c \ configfile +Specifies a configuration file to use in lieu of the default, +.I ~/.offlineimaprc. +.TP +.BI \-d +Enables IMAP protocol stream and parsing debugging. This is useful if +you are trying to track down a malfunction or figure out what is going +on under the hood. I suggest that you use this with +.BI \-1 +in order to make the results more sensible. Note that this output +will contain full IMAP protocol in plain text, including passwords, so +take care to remove that from the debugging output before sending it +to anyone else. .TP .B \-h, \-\-help Show summary of options. .TP -.B \-v, \-\-version -Show version of program. -.SH SEE ALSO -.BR bar (1), -.BR baz (1). +.BI \-u \ interface +Specifies an alternative user interface module to use. This overrides +the default specified in the configuration file. The UI specified +with +.B -u +will be forced to be used, even if its +.B isuable() +method states that it cannot be. Use this option with care. +.\".TP +.\".B \-v, \-\-version +.\"Show version of program. +.SH EXAMPLES +Here is an example configuration for a particularly complex situation; +more examples will be added later. +.SS MULTIPLE ACCOUNTS WITH MUTT +This example shows you how to set up +.B OfflineIMAP +to synchronize multiple accounts with the mutt mail reader. +.PP +Start by creating a directory to hold your folders: .br -The programs are documented fully by -.IR "The Rise and Fall of a Fooish Bar" , -available via the Info system. +.B mkdir ~/Mail +.PP +In your +.I ~/.offlineimaprc, +specify this: +.br +.B accounts = Personal, Work +.PP +Make sure that you have both a +.B [Personal] +and a +.B [Work] +section, with different localfolder pathnames and enable +.B [mbnames]. +.PP +In each account section, do something like this: +.br +.B localfolders = ~/Mail/Personal +.PP +Add these lines to your +.I ~/.muttrc: +.br +.B source ~/path-to-mbnames-muttrc-mailboxes +.br +.B folder-hook Personal set from="youremail@personal.com" +.br +.B folder-hook Work set from="youremail@work.com" +.br +.B set mbox_type=Maildir +.br +.B set folder=$HOME/Mail +.br +.B set spoolfile=+Personal/INBOX +.PP +That's it! +.SH ERRORS +If you get one of some frequently-encountered or confusing errors, +please check this section. +.SS UID validity problem for folder +IMAP servers use a unique ID (UID) to refer to a specific message. +This number is guaranteed to be unique to a particular message +FOREVER. No other message in the same folder will ever get the same +UID. UIDs are an integral part of OfflineIMAP's synchronization +scheme; they are used to match up messages on your computer to +messages on the server. +.PP +Sometimes, the UIDs on the server might get reset. Usually this will +happen if you delete and then recreate a folder. When you create a +folder, the server will often start the UID back from 1. But +.B OfflineIMAP +might still have the UIDs from the previous folder by the +same name stored. +.B OfflineIMAP +will detect this condition and skip the +folder. This is GOOD, because it prevents data loss. +.PP +You can fix it by removing your local folder and cache data. For +instance, if your folders are under +.I ~/Folders +and the folder with the +problem is INBOX, you'd type this: +.PP +.B rm -r ~/Folders/INBOX +.br +.B rm ~/.offlineimap/AccountName/INBOX +.PP +(replacing AccountName with the account name as specified in +.I ~/.offlineimaprc) +.PP +Next time you run +.B OfflineIMAP, +it will re-download the folder with the +new UIDs. Note that the procedure specified above will lose any local +changes made to the folder. +.PP +Some IMAP servers are broken and do not support UIDs properly. If you +continue to get this error for all your folders even after performing +the above procedure, it is likely that your IMAP server falls into +this category. +.B OfflineIMAP +is incompatible with such servers. Using +.B OfflineIMAP +with them will not destroy any mail, but at the same time, +it will not actually synchronize it either. (OfflineIMAP will detect +this condition and abort prior to synchronization) + +.SH OTHER FREQUENTLY ASKED QUESTIONS +There are some other FAQs that might not fit into another section of +this document, and they are enumerated here. +.TP +.B What platforms does OfflineIMAP run on? +It should run on most platforms supported by Python, which are quite a +few. +.TP +.B I'm using Mutt. Other IMAP sync programs require me to use "set maildir_trash=yes". Do I need to do that with OfflineIMAP? +No. +.B OfflineIMAP +is smart enough to figure out message deletion without this extra +crutch. You'll get the best results if you don't use this setting, in +fact. +.TP +.B How do I specify the names of my folders? +You do not need to. +.B OfflineIMAP +is smart enough to automatically figure out what folders are present +on the IMAP server and synchronize them. You can use the +.B folderfilter +and +.B foldertrans +configuration file options to request certain folders and rename them +as they come in if you like. +.TP +.B How can I prevent certain folders from being synced? +Use the +.B folderfilter +option in the configuration file. +.TP +.B How can I add or delete a folder? +.B OfflineIMAP +does not currently provide this feature, but if you create a new +folder on the IMAP server, it will be created locally automatically. +.TP +.B Are there any other warnings that I should be aware of? +Yes; see the NOTES section below. +.TP +.B What is the mailbox name recorder (mbnames) for? +The Mutt mail reader is not capable of automatically determining +the names of your mailboxes. OfflineIMAP can help it (or many other) +programs out be writing these names out in a format you specify. See +the example offlineimap.conf file for details. +.TP +.B Can I synchronize multiple accounts with OfflineIMAP? +Sure. Just name them all in the accounts line in the general +section of the config file, and add a per-account section for each one. +.TP +.B Does OfflineIMAP support POP? +No. POP is not robust enough to do a completely reliable +multi-machine synchronization like OfflineIMAP can do. OfflineIMAP +will not support it. +.TP +.B Do you support mailbox formats other than Maildir? +Not at present. There is no technical reason not to; just no +demand yet. Maildir is a superior format anyway. +.TP +.B [technical] Why are your Maildir message filenames so huge? +.B OfflineIMAP +has two relevant principles: 1) never modifying your +messages in any way and 2) ensuring 100% reliable synchronizations. +In order to do a reliable sync, +.B OfflineIMAP +must have a way to +uniquely identify each e-mail. Three pieces of information are +required to do this: your account name, the folder name, and the +message UID. The account name can be calculated from the path in +which your messages are. The folder name can usually be as well, BUT +some mail clients move messages between folders by simply moving the +file, leaving the name intact. +.IP +So, +.B OfflineIMAP +must store both a UID folder ID. The folder ID is +necessary so +.B OfflineIMAP +can detect a message moved to a different +folder. +.B OfflineIMAP +stores the UID (U= number) and an md5sum of the +foldername (FMD5= number) to facilitate this. +.TP +.B What is the speed of OfflineIMAP's sync? +.B OfflineIMAP +versions 2.0 and above contain a multithreaded system. A good way to +experiment is by setting maxsyncaccounts to 3 and maxconnections to 3 +in each account clause. +.IP +This lets OfflineIMAP open up multiple connections simultaneously. +That will let it process multiple folders and messages at once. In +most cases, this will increase performance of the sync. +.IP +Don't set the number too high. If you do that, things might actually +slow down as your link gets saturated. Also, too many connections can +cause mail servers to have excessive load. Administrators might take +unkindly to this, and the server might bog down. There are many +variables in the optimal setting; experimentation may help. +.IP +An informal benchmark yields these results for my setup: +.IP +10 minutes with MacOS X Mail.app "manual cache" +.br +5 minutes with GNUS agent sync +.br +20 seconds with OfflineIMAP 1.x +.br +9 seconds with OfflineIMAP 2.x +.br +3 seconds with OfflineIMAP 3.x "cold start" +.br +2 seconds with OfflineIMAP 3.x "held connection" +.SH CONFORMING TO +.IP \(bu +Internet Message Access Protocol version 4rev1 (IMAP 4rev1) as +specified in RFC2060 +.IP \(bu +Maildir as specified in +.UR http://www.qmail.org/qmail-manual-html/man5/maildir.html +http://www.qmail.org/qmail-manual-html/man5/maildir.html +.UE +and +.UR http://cr.yp.to/proto/maildir.html +http://cr.yp.to/proto/maildir.html. +.UE +.IP \(bu +Standard Python 2.2.1 as implemented on POSIX-compliant systems. +.SH NOTES +.SS DELETING LOCAL FOLDERS +.B OfflineIMAP +does a two-way synchronization. That is, if you +make a change to the mail on the server, it will be propogated to your +local copy, and vise-versa. Some people might think that it would be +wise to just delete all their local mail folders periodically. If you +do this with OfflineIMAP, remember to also remove your local status +cache (~/.offlineimap by default). Otherwise, OfflineIMAP will take +this as an intentional deletion of many messages and will interpret +your action as requesting them to be deleted from the server as well. +(If you don't understand this, don't worry; you probably won't +encounter this situation) +.SS MAILING LIST +There is an OfflineIMAP mailing list available. +.PP +To subscribe, send the text "Subscribe" in the subject of a mail to +offlineimap-request@complete.org. To post, send the message to +offlineimap@complete.org. +.SH BUGS +Should be reported to the author at the address specified below. +.SH COPYRIGHT +OfflineIMAP is Copyright (C) 2002 John Goerzen. +.PP +This program is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2 of the License, or +(at your option) any later version. +.PP +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. +.PP +You should have received a copy of the GNU General Public License +along with this program; if not, write to: +.PP +Free Software Foundation, Inc. +.br +59 Temple Place +.br +Suite 330 +.br +Boston, MA 02111-1307 +.br +USA .SH AUTHOR -This manual page was written by John Goerzen , -for the Debian GNU/Linux system (but may be used by others). +.B OfflineIMAP, +its libraries, documentation, and all included files, except where +noted, was written by John Goerzen and +copyright is held as stated in the COPYRIGHT section. +.PP +OfflineIMAP may be downloaded, and information found, from its +homepage via either Gopher or HTTP: +.PP +.UR gopher://quux.org/1/devel/offlineimap +gopher://quux.org/1/devel/offlineimap +.UE +.br +.UR http://quux.org/devel/offlineimap +http://quux.org/devel/offlineimap +.UE + +.SH SEE ALSO +.BR mutt (1), +.BR python (1). +.\".BR bar (1), +.\".BR baz (1). +.\".br +.\"The programs are documented fully by +.\".IR "The Rise and Fall of a Fooish Bar" , +.\"available via the Info system. +.\".SH AUTHOR +.\"This manual page was written by John Goerzen , +.\"for the Debian GNU/Linux system (but may be used by others).