Show
Ignore:
Timestamp:
2007-11-01 03:45:44 (15 months ago)
Author:
Rocco Rutte <pdmef@…>
Branch:
HEAD
Message:

Manual: Move POP3, IMAP and cache-related sections to their own chapter.

Files:
1 modified

Legend:

Unmodified
Added
Removed

  • doc/manual.xml.head

    r5247 r5248  
    46314631</sect1> 
    46324632 
    4633 <sect1 id="pop"> 
    4634 <title>POP3 Support (OPTIONAL)</title> 
    4635  
    4636 <para> 
    4637 If Mutt was compiled with POP3 support (by running the <emphasis>configure</emphasis> 
    4638 script with the <emphasis>--enable-pop</emphasis> flag), it has the ability to work 
    4639 with mailboxes located on a remote POP3 server and fetch mail for local 
    4640 browsing. 
    4641 </para> 
    4642  
    4643 <para> 
    4644 You can access the remote POP3 mailbox by selecting the folder 
    4645 <literal>pop://popserver/</literal>. 
    4646 </para> 
    4647  
    4648 <para> 
    4649 You can select an alternative port by specifying it with the server, ie: 
    4650 <literal>pop://popserver:port/</literal>. 
    4651 </para> 
    4652  
    4653 <para> 
    4654 You can also specify different username for each folder, ie: 
    4655 <literal>pop://username@popserver[:port]/</literal>. 
    4656 </para> 
    4657  
    4658 <para> 
    4659 Polling for new mail is more expensive over POP3 than locally. For this 
    4660 reason the frequency at which Mutt will check for mail remotely can be 
    4661 controlled by the 
    4662 <link linkend="pop-checkinterval">&dollar;pop&lowbar;checkinterval</link> 
    4663 variable, which defaults to every 60 seconds. 
    4664 </para> 
    4665  
    4666 <para> 
    4667 If Mutt was compiled with SSL support (by running the <emphasis>configure</emphasis> 
    4668 script with the <emphasis>--with-ssl</emphasis> flag), connections to POP3 servers 
    4669 can be encrypted. This naturally requires that the server supports 
    4670 SSL encrypted connections. To access a folder with POP3/SSL, you should 
    4671 use pops: prefix, ie: 
    4672 <literal>pops://[username@]popserver[:port]/</literal>. 
    4673 </para> 
    4674  
    4675 <para> 
    4676 Another way to access your POP3 mail is the <emphasis>fetch-mail</emphasis> function 
    4677 (default: G).  It allows to connect to <link linkend="pop-host">&dollar;pop&lowbar;host</link>, fetch all your new mail and place it in the 
    4678 local <link linkend="spoolfile">&dollar;spoolfile</link>.  After this 
    4679 point, Mutt runs exactly as if the mail had always been local. 
    4680 </para> 
    4681  
    4682 <para> 
    4683 <emphasis role="bold">Note:</emphasis> If you only need to fetch all messages to local mailbox 
    4684 you should consider using a specialized program, such as <ulink 
    4685 url="http://www.ccil.org/~esr/fetchmail" 
    4686 >fetchmail</ulink 
    4687 > 
    4688 </para> 
    4689  
    4690 </sect1> 
    4691  
    4692 <sect1 id="imap"> 
    4693 <title>IMAP Support (OPTIONAL)</title> 
    4694  
    4695 <para> 
    4696 If Mutt was compiled with IMAP support (by running the <emphasis>configure</emphasis> 
    4697 script with the <emphasis>--enable-imap</emphasis> flag), it has the ability to work 
    4698 with folders located on a remote IMAP server. 
    4699 </para> 
    4700  
    4701 <para> 
    4702 You can access the remote inbox by selecting the folder 
    4703 <literal>imap://imapserver/INBOX</literal>, where <literal>imapserver</literal> is the name of the 
    4704 IMAP server and <literal>INBOX</literal> is the special name for your spool mailbox on 
    4705 the IMAP server. If you want to access another mail folder at the IMAP 
    4706 server, you should use <literal>imap://imapserver/path/to/folder</literal> where 
    4707 <literal>path/to/folder</literal> is the path of the folder you want to access. 
    4708 </para> 
    4709  
    4710 <para> 
    4711 You can select an alternative port by specifying it with the server, ie: 
    4712 <literal>imap://imapserver:port/INBOX</literal>. 
    4713 </para> 
    4714  
    4715 <para> 
    4716 You can also specify different username for each folder, ie: 
    4717 <literal>imap://username@imapserver[:port]/INBOX</literal>. 
    4718 </para> 
    4719  
    4720 <para> 
    4721 If Mutt was compiled with SSL support (by running the <emphasis>configure</emphasis> 
    4722 script with the <emphasis>--with-ssl</emphasis> flag), connections to IMAP servers 
    4723 can be encrypted. This naturally requires that the server supports 
    4724 SSL encrypted connections. To access a folder with IMAP/SSL, you should 
    4725 use <literal>imaps://[username@]imapserver[:port]/path/to/folder</literal> as your  
    4726 folder path. 
    4727 </para> 
    4728  
    4729 <para> 
    4730 Pine-compatible notation is also supported, ie 
    4731 <literal>&lcub;[username@]imapserver[:port][/ssl]&rcub;path/to/folder</literal> 
    4732 </para> 
    4733  
    4734 <para> 
    4735 Note that not all servers use / as the hierarchy separator.  Mutt should 
    4736 correctly notice which separator is being used by the server and convert 
    4737 paths accordingly. 
    4738 </para> 
    4739  
    4740 <para> 
    4741 When browsing folders on an IMAP server, you can toggle whether to look 
    4742 at only the folders you are subscribed to, or all folders with the 
    4743 <emphasis>toggle-subscribed</emphasis> command.  See also the  
    4744 <link linkend="imap-list-subscribed">&dollar;imap&lowbar;list&lowbar;subscribed</link> variable. 
    4745 </para> 
    4746  
    4747 <para> 
    4748 Polling for new mail on an IMAP server can cause noticeable delays. So, you'll 
    4749 want to carefully tune the 
    4750 <link linkend="mail-check">&dollar;mail&lowbar;check</link> 
    4751 and 
    4752 <link linkend="timeout">&dollar;timeout</link> 
    4753 variables. Personally I use 
    4754  
    4755 <screen> 
    4756 set mail_check=90 
    4757 set timeout=15 
    4758 </screen> 
    4759  
    4760 with relatively good results over my slow modem line. 
    4761 </para> 
    4762  
    4763 <para> 
    4764 Note that if you are using mbox as the mail store on UW servers prior to 
    4765 v12.250, the server has been reported to disconnect a client if another client 
    4766 selects the same folder. 
    4767 </para> 
    4768  
    4769 <sect2> 
    4770 <title>The Folder Browser</title> 
    4771  
    4772 <para> 
    4773 As of version 1.2, mutt supports browsing mailboxes on an IMAP 
    4774 server. This is mostly the same as the local file browser, with the 
    4775 following differences: 
    4776  
    4777 <itemizedlist> 
    4778 <listitem> 
    4779  
    4780 <para> 
    4781 In lieu of file permissions, mutt displays the string "IMAP", 
    4782 possibly followed by the symbol "+", indicating 
    4783 that the entry contains both messages and subfolders. On 
    4784 Cyrus-like servers folders will often contain both messages and 
    4785 subfolders.  
    4786 </para> 
    4787 </listitem> 
    4788 <listitem> 
    4789  
    4790 <para> 
    4791 For the case where an entry can contain both messages and 
    4792 subfolders, the selection key (bound to <literal>enter</literal> by default) 
    4793 will choose to descend into the subfolder view. If you wish to view 
    4794 the messages in that folder, you must use <literal>view-file</literal> instead 
    4795 (bound to <literal>space</literal> by default). 
    4796 </para> 
    4797 </listitem> 
    4798 <listitem> 
    4799  
    4800 <para> 
    4801 You can create, delete and rename mailboxes with the 
    4802 <literal>create-mailbox</literal>, <literal>delete-mailbox</literal>, and 
    4803 <literal>rename-mailbox</literal> commands (default bindings: <literal>C</literal>, 
    4804 <literal>d</literal> and <literal>r</literal>, respectively). You may also 
    4805 <literal>subscribe</literal> and <literal>unsubscribe</literal> to mailboxes (normally 
    4806 these are bound to <literal>s</literal> and <literal>u</literal>, respectively). 
    4807 </para> 
    4808 </listitem> 
    4809  
    4810 </itemizedlist> 
    4811  
    4812 </para> 
    4813  
    4814 </sect2> 
    4815  
    4816 <sect2> 
    4817 <title>Authentication</title> 
    4818  
    4819 <para> 
    4820 Mutt supports four authentication methods with IMAP servers: SASL, 
    4821 GSSAPI, CRAM-MD5, and LOGIN (there is a patch by Grant Edwards to add 
    4822 NTLM authentication for you poor exchange users out there, but it has 
    4823 yet to be integrated into the main tree). There is also support for 
    4824 the pseudo-protocol ANONYMOUS, which allows you to log in to a public 
    4825 IMAP server without having an account. To use ANONYMOUS, simply make 
    4826 your username blank or "anonymous". 
    4827 </para> 
    4828  
    4829 <para> 
    4830 SASL is a special super-authenticator, which selects among several protocols 
    4831 (including GSSAPI, CRAM-MD5, ANONYMOUS, and DIGEST-MD5) the most secure 
    4832 method available on your host and the server. Using some of these methods 
    4833 (including DIGEST-MD5 and possibly GSSAPI), your entire session will be 
    4834 encrypted and invisible to those teeming network snoops. It is the best 
    4835 option if you have it. To use it, you must have the Cyrus SASL library 
    4836 installed on your system and compile mutt with the <emphasis>--with-sasl</emphasis> flag. 
    4837 </para> 
    4838  
    4839 <para> 
    4840 Mutt will try whichever methods are compiled in and available on the server, 
    4841 in the following order: SASL, ANONYMOUS, GSSAPI, CRAM-MD5, LOGIN. 
    4842 </para> 
    4843  
    4844 <para> 
    4845 There are a few variables which control authentication:  
    4846  
    4847 <itemizedlist> 
    4848 <listitem> 
    4849  
    4850 <para> 
    4851 <link linkend="imap-user">&dollar;imap&lowbar;user</link> - controls 
    4852 the username under which you request authentication on the IMAP server, 
    4853 for all authenticators. This is overridden by an explicit username in 
    4854 the mailbox path (ie by using a mailbox name of the form 
    4855 <literal>&lcub;user@host&rcub;</literal>). 
    4856 </para> 
    4857 </listitem> 
    4858 <listitem> 
    4859  
    4860 <para> 
    4861 <link linkend="imap-pass">&dollar;imap&lowbar;pass</link> - a 
    4862 password which you may preset, used by all authentication methods where 
    4863 a password is needed. 
    4864 </para> 
    4865 </listitem> 
    4866 <listitem> 
    4867  
    4868 <para> 
    4869 <link linkend="imap-authenticators">&dollar;imap&lowbar;authenticators</link> - a colon-delimited list of IMAP 
    4870 authentication methods to try, in the order you wish to try them. If 
    4871 specified, this overrides mutt's default (attempt everything, in the order 
    4872 listed above). 
    4873 </para> 
    4874 </listitem> 
    4875  
    4876 </itemizedlist> 
    4877  
    4878 </para> 
    4879  
    4880 </sect2> 
    4881  
    4882 </sect1> 
    4883  
    4884 <sect1 id="account-hook"> 
    4885 <title>Managing multiple IMAP/POP accounts (OPTIONAL)</title> 
    4886  
    4887 <para> 
    4888 If you happen to have accounts on multiple IMAP and/or POP servers, 
    4889 you may find managing all the authentication settings inconvenient and 
    4890 error-prone.  The account-hook command may help. This hook works like 
    4891 folder-hook but is invoked whenever you access a remote mailbox 
    4892 (including inside the folder browser), not just when you open the 
    4893 mailbox. 
    4894 </para> 
    4895  
    4896 <para> 
    4897 Some examples: 
    4898 </para> 
    4899  
    4900 <para> 
    4901  
    4902 <screen> 
    4903 account-hook . 'unset imap_user; unset imap_pass; unset tunnel' 
    4904 account-hook imap://host1/ 'set imap_user=me1 imap_pass=foo' 
    4905 account-hook imap://host2/ 'set tunnel="ssh host2 /usr/libexec/imapd"' 
    4906 </screen> 
    4907  
    4908 </para> 
    4909  
    4910 </sect1> 
    4911  
    49124633<sect1 id="urlview"> 
    49134634<title>Start a WWW Browser on URLs (EXTERNAL)</title> 
    … …  
    49294650 
    49304651</para> 
    4931  
    4932 </sect1> 
    4933  
    4934 <sect1 id="caching"> 
    4935 <title>Local caching (OPTIONAL)</title> 
    4936  
    4937 <para> 
    4938 Mutt contains two types of local caching: <emphasis>(1)</emphasis> 
    4939 the so-called ``header caching'' and <emphasis>(2)</emphasis> the 
    4940 so-called ``body caching'' which are both described in this section. 
    4941 </para> 
    4942  
    4943 <para> 
    4944 These are optional which means they're not enabled by default. 
    4945 Details on how to enable either of these techniques are given in the 
    4946 following subsections. 
    4947 </para> 
    4948  
    4949 <sect2 id="header-caching"> 
    4950 <title>Header caching</title> 
    4951  
    4952 <para> 
    4953 Mutt provides optional support for caching message headers for the 
    4954 following types of folders: IMAP, POP, Maildir and MH. Header caching 
    4955 greatly improves speed because for remote folders, headers 
    4956 usually only need to be downloaded once. For Maildir and MH, reading the 
    4957 headers from a single file is much faster than looking at possibly 
    4958 thousands of single files (since Maildir and MH use one file per message.) 
    4959 </para> 
    4960  
    4961 <para> 
    4962 Header caching can be enabled via the configure script and the 
    4963 <emphasis>--enable-hcache</emphasis> option. It's not turned on 
    4964 by default because external database libraries are required: one 
    4965 of qdbm, gdbm or bdb must be present. 
    4966 </para> 
    4967  
    4968 <para> 
    4969 If enabled, <link 
    4970 linkend="header-cache">&dollar;header&lowbar;cache</link> can be 
    4971 used to either point to a file or a directory. If set to point to 
    4972 a file, one database file for all folders will be used (which may 
    4973 result in lower performance), but one file per folder if it points 
    4974 to a directory. 
    4975 </para> 
    4976  
    4977 <para> 
    4978 For the one-file-per-folder case, database files will be named by MD5 
    4979 sums. They may be safely removed if a system is short on space. You 
    4980 can compute the name of the header cache file for a particular folder 
    4981 through a command like the following: 
    4982 </para> 
    4983  
    4984 <para> 
    4985 <screen> 
    4986 $ printf '%s' '/path/to/folder' | md5sum 
    4987 $ printf '%s' 'imaps://user@host/path/to/folder' | md5sum 
    4988 $ printf '%s' 'pops://user@host' | md5sum 
    4989 </screen> 
    4990 </para> 
    4991  
    4992 <para> 
    4993 The <literal>md5sum</literal> command may also be 
    4994 named <literal>md5</literal>, depending on your operating system. 
    4995 </para> 
    4996  
    4997 </sect2> 
    4998  
    4999 <sect2 id="body-caching"> 
    5000 <title>Body caching</title> 
    5001  
    5002 <para> 
    5003 In addition to caching message headers only, mutt can also cache 
    5004 whole message bodies. This results in faster display of messages 
    5005 for POP and IMAP folders because messages usually have to be 
    5006 downloaded only once. 
    5007 </para> 
    5008  
    5009 <para> 
    5010 If the configure script is called with <emphasis>--enable-pop</emphasis> 
    5011 and/or <emphasis>--enable-imap</emphasis>, body caching will be 
    5012 built in as it does not require additional software packages such 
    5013 as database libraries. 
    5014 </para> 
    5015  
    5016 <para> 
    5017 For configuration, the variable <link linkend="message-cachedir" 
    5018 >&dollar;message&lowbar;cachedir</link> must point to a 
    5019 directory. There, mutt will create a hierarchy of subdirectories 
    5020 named like: <literal>proto:user@hostname</literal> where 
    5021 <literal>proto</literal> is either ``pop'' or ``imap.'' Within 
    5022 there for each folder, mutt stores messages in single files (just 
    5023 like Maildir) so that with manual symlink creation these cache 
    5024 directories can be examined with mutt as read-only Maildir folders. 
    5025 </para> 
    5026  
    5027 <para> 
    5028 All files can be removed as needed if the consumed disk space 
    5029 becomes an issue as mutt will silently fetch missing items again. 
    5030 </para> 
    5031  
    5032 </sect2> 
    50334652 
    50344653</sect1> 
    … …  
    59495568muttrc. 
    59505569</para> 
     5570 
     5571</sect1> 
     5572 
     5573</chapter> 
     5574 
     5575<chapter id="optionalfeatures"> 
     5576<title>Optional features</title> 
     5577 
     5578<sect1 id="pop"> 
     5579<title>POP3 Support</title> 
     5580 
     5581<para> 
     5582If Mutt was compiled with POP3 support (by running the <emphasis>configure</emphasis> 
     5583script with the <emphasis>--enable-pop</emphasis> flag), it has the ability to work 
     5584with mailboxes located on a remote POP3 server and fetch mail for local 
     5585browsing. 
     5586</para> 
     5587 
     5588<para> 
     5589You can access the remote POP3 mailbox by selecting the folder 
     5590<literal>pop://popserver/</literal>. 
     5591</para> 
     5592 
     5593<para> 
     5594You can select an alternative port by specifying it with the server, ie: 
     5595<literal>pop://popserver:port/</literal>. 
     5596</para> 
     5597 
     5598<para> 
     5599You can also specify different username for each folder, ie: 
     5600<literal>pop://username@popserver[:port]/</literal>. 
     5601</para> 
     5602 
     5603<para> 
     5604Polling for new mail is more expensive over POP3 than locally. For this 
     5605reason the frequency at which Mutt will check for mail remotely can be 
     5606controlled by the 
     5607<link linkend="pop-checkinterval">&dollar;pop&lowbar;checkinterval</link> 
     5608variable, which defaults to every 60 seconds. 
     5609</para> 
     5610 
     5611<para> 
     5612If Mutt was compiled with SSL support (by running the <emphasis>configure</emphasis> 
     5613script with the <emphasis>--with-ssl</emphasis> flag), connections to POP3 servers 
     5614can be encrypted. This naturally requires that the server supports 
     5615SSL encrypted connections. To access a folder with POP3/SSL, you should 
     5616use pops: prefix, ie: 
     5617<literal>pops://[username@]popserver[:port]/</literal>. 
     5618</para> 
     5619 
     5620<para> 
     5621Another way to access your POP3 mail is the <emphasis>fetch-mail</emphasis> function 
     5622(default: G).  It allows to connect to <link linkend="pop-host">&dollar;pop&lowbar;host</link>, fetch all your new mail and place it in the 
     5623local <link linkend="spoolfile">&dollar;spoolfile</link>.  After this 
     5624point, Mutt runs exactly as if the mail had always been local. 
     5625</para> 
     5626 
     5627<para> 
     5628<emphasis role="bold">Note:</emphasis> If you only need to fetch all messages to local mailbox 
     5629you should consider using a specialized program, such as <ulink 
     5630url="http://www.ccil.org/~esr/fetchmail" 
     5631>fetchmail</ulink 
     5632> 
     5633</para> 
     5634 
     5635</sect1> 
     5636 
     5637<sect1 id="imap"> 
     5638<title>IMAP Support</title> 
     5639 
     5640<para> 
     5641If Mutt was compiled with IMAP support (by running the <emphasis>configure</emphasis> 
     5642script with the <emphasis>--enable-imap</emphasis> flag), it has the ability to work 
     5643with folders located on a remote IMAP server. 
     5644</para> 
     5645 
     5646<para> 
     5647You can access the remote inbox by selecting the folder 
     5648<literal>imap://imapserver/INBOX</literal>, where <literal>imapserver</literal> is the name of the 
     5649IMAP server and <literal>INBOX</literal> is the special name for your spool mailbox on 
     5650the IMAP server. If you want to access another mail folder at the IMAP 
     5651server, you should use <literal>imap://imapserver/path/to/folder</literal> where 
     5652<literal>path/to/folder</literal> is the path of the folder you want to access. 
     5653</para> 
     5654 
     5655<para> 
     5656You can select an alternative port by specifying it with the server, ie: 
     5657<literal>imap://imapserver:port/INBOX</literal>. 
     5658</para> 
     5659 
     5660<para> 
     5661You can also specify different username for each folder, ie: 
     5662<literal>imap://username@imapserver[:port]/INBOX</literal>. 
     5663</para> 
     5664 
     5665<para> 
     5666If Mutt was compiled with SSL support (by running the <emphasis>configure</emphasis> 
     5667script with the <emphasis>--with-ssl</emphasis> flag), connections to IMAP servers 
     5668can be encrypted. This naturally requires that the server supports 
     5669SSL encrypted connections. To access a folder with IMAP/SSL, you should 
     5670use <literal>imaps://[username@]imapserver[:port]/path/to/folder</literal> as your  
     5671folder path. 
     5672</para> 
     5673 
     5674<para> 
     5675Pine-compatible notation is also supported, ie 
     5676<literal>&lcub;[username@]imapserver[:port][/ssl]&rcub;path/to/folder</literal> 
     5677</para> 
     5678 
     5679<para> 
     5680Note that not all servers use / as the hierarchy separator.  Mutt should 
     5681correctly notice which separator is being used by the server and convert 
     5682paths accordingly. 
     5683</para> 
     5684 
     5685<para> 
     5686When browsing folders on an IMAP server, you can toggle whether to look 
     5687at only the folders you are subscribed to, or all folders with the 
     5688<emphasis>toggle-subscribed</emphasis> command.  See also the  
     5689<link linkend="imap-list-subscribed">&dollar;imap&lowbar;list&lowbar;subscribed</link> variable. 
     5690</para> 
     5691 
     5692<para> 
     5693Polling for new mail on an IMAP server can cause noticeable delays. So, you'll 
     5694want to carefully tune the 
     5695<link linkend="mail-check">&dollar;mail&lowbar;check</link> 
     5696and 
     5697<link linkend="timeout">&dollar;timeout</link> 
     5698variables. Personally I use 
     5699 
     5700<screen> 
     5701set mail_check=90 
     5702set timeout=15 
     5703</screen> 
     5704 
     5705with relatively good results over my slow modem line. 
     5706</para> 
     5707 
     5708<para> 
     5709Note that if you are using mbox as the mail store on UW servers prior to 
     5710v12.250, the server has been reported to disconnect a client if another client 
     5711selects the same folder. 
     5712</para> 
     5713 
     5714<sect2> 
     5715<title>The Folder Browser</title> 
     5716 
     5717<para> 
     5718As of version 1.2, mutt supports browsing mailboxes on an IMAP 
     5719server. This is mostly the same as the local file browser, with the 
     5720following differences: 
     5721 
     5722<itemizedlist> 
     5723<listitem> 
     5724 
     5725<para> 
     5726In lieu of file permissions, mutt displays the string "IMAP", 
     5727possibly followed by the symbol "+", indicating 
     5728that the entry contains both messages and subfolders. On 
     5729Cyrus-like servers folders will often contain both messages and 
     5730subfolders.  
     5731</para> 
     5732</listitem> 
     5733<listitem> 
     5734 
     5735<para> 
     5736For the case where an entry can contain both messages and 
     5737subfolders, the selection key (bound to <literal>enter</literal> by default) 
     5738will choose to descend into the subfolder view. If you wish to view 
     5739the messages in that folder, you must use <literal>view-file</literal> instead 
     5740(bound to <literal>space</literal> by default). 
     5741</para> 
     5742</listitem> 
     5743<listitem> 
     5744 
     5745<para> 
     5746You can create, delete and rename mailboxes with the 
     5747<literal>create-mailbox</literal>, <literal>delete-mailbox</literal>, and 
     5748<literal>rename-mailbox</literal> commands (default bindings: <literal>C</literal>, 
     5749<literal>d</literal> and <literal>r</literal>, respectively). You may also 
     5750<literal>subscribe</literal> and <literal>unsubscribe</literal> to mailboxes (normally 
     5751these are bound to <literal>s</literal> and <literal>u</literal>, respectively). 
     5752</para> 
     5753</listitem> 
     5754 
     5755</itemizedlist> 
     5756 
     5757</para> 
     5758 
     5759</sect2> 
     5760 
     5761<sect2> 
     5762<title>Authentication</title> 
     5763 
     5764<para> 
     5765Mutt supports four authentication methods with IMAP servers: SASL, 
     5766GSSAPI, CRAM-MD5, and LOGIN (there is a patch by Grant Edwards to add 
     5767NTLM authentication for you poor exchange users out there, but it has 
     5768yet to be integrated into the main tree). There is also support for 
     5769the pseudo-protocol ANONYMOUS, which allows you to log in to a public 
     5770IMAP server without having an account. To use ANONYMOUS, simply make 
     5771your username blank or "anonymous". 
     5772</para> 
     5773 
     5774<para> 
     5775SASL is a special super-authenticator, which selects among several protocols 
     5776(including GSSAPI, CRAM-MD5, ANONYMOUS, and DIGEST-MD5) the most secure 
     5777method available on your host and the server. Using some of these methods 
     5778(including DIGEST-MD5 and possibly GSSAPI), your entire session will be 
     5779encrypted and invisible to those teeming network snoops. It is the best 
     5780option if you have it. To use it, you must have the Cyrus SASL library 
     5781installed on your system and compile mutt with the <emphasis>--with-sasl</emphasis> flag. 
     5782</para> 
     5783 
     5784<para> 
     5785Mutt will try whichever methods are compiled in and available on the server, 
     5786in the following order: SASL, ANONYMOUS, GSSAPI, CRAM-MD5, LOGIN. 
     5787</para> 
     5788 
     5789<para> 
     5790There are a few variables which control authentication:  
     5791 
     5792<itemizedlist> 
     5793<listitem> 
     5794 
     5795<para> 
     5796<link linkend="imap-user">&dollar;imap&lowbar;user</link> - controls 
     5797the username under which you request authentication on the IMAP server, 
     5798for all authenticators. This is overridden by an explicit username in 
     5799the mailbox path (ie by using a mailbox name of the form 
     5800<literal>&lcub;user@host&rcub;</literal>). 
     5801</para> 
     5802</listitem> 
     5803<listitem> 
     5804 
     5805<para> 
     5806<link linkend="imap-pass">&dollar;imap&lowbar;pass</link> - a 
     5807password which you may preset, used by all authentication methods where 
     5808a password is needed. 
     5809</para> 
     5810</listitem> 
     5811<listitem> 
     5812 
     5813<para> 
     5814<link linkend="imap-authenticators">&dollar;imap&lowbar;authenticators</link> - a colon-delimited list of IMAP 
     5815authentication methods to try, in the order you wish to try them. If 
     5816specified, this overrides mutt's default (attempt everything, in the order 
     5817listed above). 
     5818</para> 
     5819</listitem> 
     5820 
     5821</itemizedlist> 
     5822 
     5823</para> 
     5824 
     5825</sect2> 
     5826 
     5827</sect1> 
     5828 
     5829<sect1 id="account-hook"> 
     5830<title>Managing multiple IMAP/POP accounts</title> 
     5831 
     5832<para> 
     5833If you happen to have accounts on multiple IMAP and/or POP servers, 
     5834you may find managing all the authentication settings inconvenient and 
     5835error-prone.  The account-hook command may help. This hook works like 
     5836folder-hook but is invoked whenever you access a remote mailbox 
     5837(including inside the folder browser), not just when you open the 
     5838mailbox. 
     5839</para> 
     5840 
     5841<para> 
     5842Some examples: 
     5843</para> 
     5844 
     5845<para> 
     5846 
     5847<screen> 
     5848account-hook . 'unset imap_user; unset imap_pass; unset tunnel' 
     5849account-hook imap://host1/ 'set imap_user=me1 imap_pass=foo' 
     5850account-hook imap://host2/ 'set tunnel="ssh host2 /usr/libexec/imapd"' 
     5851</screen> 
     5852 
     5853</para> 
     5854 
     5855</sect1> 
     5856 
     5857<sect1 id="caching"> 
     5858<title>Local caching</title> 
     5859 
     5860<para> 
     5861Mutt contains two types of local caching: <emphasis>(1)</emphasis> 
     5862the so-called ``header caching'' and <emphasis>(2)</emphasis> the 
     5863so-called ``body caching'' which are both described in this section. 
     5864</para> 
     5865 
     5866<para> 
     5867These are optional which means they're not enabled by default. 
     5868Details on how to enable either of these techniques are given in the 
     5869following subsections. 
     5870</para> 
     5871 
     5872<sect2 id="header-caching"> 
     5873<title>Header caching</title> 
     5874 
     5875<para> 
     5876Mutt provides optional support for caching message headers for the 
     5877following types of folders: IMAP, POP, Maildir and MH. Header caching 
     5878greatly improves speed because for remote folders, headers 
     5879usually only need to be downloaded once. For Maildir and MH, reading the 
     5880headers from a single file is much faster than looking at possibly 
     5881thousands of single files (since Maildir and MH use one file per message.) 
     5882</para> 
     5883 
     5884<para> 
     5885Header caching can be enabled via the configure script and the 
     5886<emphasis>--enable-hcache</emphasis> option. It's not turned on 
     5887by default because external database libraries are required: one 
     5888of qdbm, gdbm or bdb must be present. 
     5889</para> 
     5890 
     5891<para> 
     5892If enabled, <link 
     5893linkend="header-cache">&dollar;header&lowbar;cache</link> can be 
     5894used to either point to a file or a directory. If set to point to 
     5895a file, one database file for all folders will be used (which may 
     5896result in lower performance), but one file per folder if it points 
     5897to a directory. 
     5898</para> 
     5899 
     5900<para> 
     5901For the one-file-per-folder case, database files will be named by MD5 
     5902sums. They may be safely removed if a system is short on space. You 
     5903can compute the name of the header cache file for a particular folder 
     5904through a command like the following: 
     5905</para> 
     5906 
     5907<para> 
     5908<screen> 
     5909$ printf '%s' '/path/to/folder' | md5sum 
     5910$ printf '%s' 'imaps://user@host/path/to/folder' | md5sum 
     5911$ printf '%s' 'pops://user@host' | md5sum 
     5912</screen> 
     5913</para> 
     5914 
     5915<para> 
     5916The <literal>md5sum</literal> command may also be 
     5917named <literal>md5</literal>, depending on your operating system. 
     5918</para> 
     5919 
     5920</sect2> 
     5921 
     5922<sect2 id="body-caching"> 
     5923<title>Body caching</title> 
     5924 
     5925<para> 
     5926In addition to caching message headers only, mutt can also cache 
     5927whole message bodies. This results in faster display of messages 
     5928for POP and IMAP folders because messages usually have to be 
     5929downloaded only once. 
     5930</para> 
     5931 
     5932<para> 
     5933If the configure script is called with <emphasis>--enable-pop</emphasis> 
     5934and/or <emphasis>--enable-imap</emphasis>, body caching will be 
     5935built in as it does not require additional software packages such 
     5936as database libraries. 
     5937</para> 
     5938 
     5939<para> 
     5940For configuration, the variable <link linkend="message-cachedir" 
     5941>&dollar;message&lowbar;cachedir</link> must point to a 
     5942directory. There, mutt will create a hierarchy of subdirectories 
     5943named like: <literal>proto:user@hostname</literal> where 
     5944<literal>proto</literal> is either ``pop'' or ``imap.'' Within 
     5945there for each folder, mutt stores messages in single files (just 
     5946like Maildir) so that with manual symlink creation these cache 
     5947directories can be examined with mutt as read-only Maildir folders. 
     5948</para> 
     5949 
     5950<para> 
     5951All files can be removed as needed if the consumed disk space 
     5952becomes an issue as mutt will silently fetch missing items again. 
     5953</para> 
     5954 
     5955</sect2> 
    59515956 
    59525957</sect1>