<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>Mutt and IMAP</title>
</head>
<body bgcolor="white">
These notes describe IMAP facilities present in mutt 1.4 and later.
<h1>1. Getting started</h1>
<h2>1.1. How to write an IMAP mailbox in mutt</h2>
To point mutt to an IMAP mailbox, write your mailbox in IMAP URL format:
<blockquote>
<tt>imap://<em>hostname</em>/<em>mailbox</em></tt>
</blockquote>
where <em>hostname</em> is the name of your IMAP server, and <em>mailbox</em>
is the name of your mailbox on the server. All IMAP servers provide
one special folder called INBOX, which is where your incoming mail
normally arrives. For example, if your IMAP server is
mailhost.mydomain.com, you could open your INBOX there by telling
mutt to open <tt>imap://mailhost.mydomain.com/INBOX</tt>
<p>
If necessary, you can also specify the port your IMAP server listens on, and
ask mutt to use ssl if available. The full form of an IMAP mailbox in mutt is
<blockquote>
<tt>imap[s]://[<em>user</em>@]<em>hostname</em>[:<em>port</em>]/<em>mailbox</em></tt>
</blockquote>
Mutt also understands PINE-compatible IMAP mailbox notation:
<blockquote>
<tt>{[<em>user</em>@]<em>hostname</em>[:<em>port</em>][/ssl]}<em>mailbox</em></tt>
</blockquote>
<h3>1.1.1. What about the mailbox part?</h3>
How you write the actually mailbox name may depend on your IMAP
server. First, some servers will put all of your mail into a
subfolder, often a subfolder of <tt>INBOX</tt>. For instance, if your
server is Courier or Cyrus, your folder Lists may actually be
INBOX.Lists. This brings us to point number two: some servers don't
use '/' to separate folder names. The reference server (UW-IMAP) uses
'/', but two common servers (Courier and Cyrus) both generally use
'.', and Lotus Notes has a server which uses '\' (a very bad choice,
by the way). Generally you can use '/' and mutt will figure out what
to do with it, though. Some examples:
<blockquote><tt>
imap://hostname/lists/mutt-dev
<br>
imap://hostname/INBOX.lists.mutt-dev
</tt></blockquote>
When mutt has proper namespace support, you will hopefully no longer
have to worry about either of these issues.
<h2>1.2. Connecting to your IMAP server</h2>
To connect to your IMAP server, just switch to an IMAP mailbox. That is, press
<tt>c</tt> to get the <tt>Open mailbox:</tt> prompt, and enter an IMAP mailbox
as described above. You'll need your IMAP user name and password. You may set
these in advance via configuration the variables <tt>imap_user</tt>
and <tt>imap_pass</tt>. If you haven't set them, mutt will prompt you
for this information when you first connect to your server.
<h3>1.2.1. Connection security</h3>
Mutt has advanced support for IMAP session security - probably as
advanced as any other IMAP client, and more than most.
<ul>
<li>Mutt can encrypt your entire session using SSL, TLS or a SASL
protection layer.</li>
<li>Mutt also knows about several authentication methods which don't
send your password across the network: it has native support for
CRAM-MD5 and GSSAPI (Kerberos) authentication, and if compiled
with the <a
href="http://asg.web.cmu.edu/sasl/sasl-library.html">Cyrus SASL
library</a> it can support numerous other methods (and more can be
added by upgrading your SASL library, without recompiling
mutt!).</li>
<li>Mutt supports a tunneling driver which allows you to connect
using, eg, an SSH pipe which invokes your IMAP server directly on
the remote machine.</li>
<li>Finally, you can specify a shell command to be run before every
connection attempt, which may for instance use SSH to set up
encrypted port-forwarding between mutt and the IMAP server.</li>
</ul>
<h4>1.2.1.1. SSL/TLS</h4>
To use SSL, specify your IMAP mailbox starting with <tt>imaps:</tt>
instead of <tt>imap:</tt>. Mutt also supports TLS, which means that if
your server does too, you can negotiate SSL over a normal IMAP
connection (using <tt>imap:</tt>). Whether or not this happens depends
on the mutt quadoption <tt>ssl_starttls</tt>, which defaults to
<tt>ask-yes</tt>, meaning that if, and only if, the server supports
TLS, mutt will ask you whether it should encrypt the connection before
authenticating.
<p>
Each time you connect to an IMAP server using SSL, mutt will check the
server's certificate against its list of known-good certificates, if
available. These certificates are stored in the file pointed to by the
configuration variable <tt>certificate_file</tt>, which is unset by
default. If mutt cannot find the server certificate in this file, the
certificate will be displayed to you and you must decide whether to
accept it or reject it (and if you accept it and have a
<tt>certificate_file</tt> set, whether or not to save it
permanently). If you reject the certificate your connection will be
terminated. Note you may also place a signing certificate into this
file, in which case mutt will automatically accept any certificate
which has been signed by it.
<p>
Some servers do not fully support all SSL protocols, and may
disconnect you during connection if mutt tries to use one they do not
understand. You can disable certain protocols by unsetting one or more
of the configuration variables <tt>ssl_use_sslv2</tt>,
<tt>ssl_use_sslv3</tt>, or <tt>ssl_use_tlsv1</tt>.
<p>
For more information, see the <a href="README.SSL">README.SSL</a> file
included in the mutt distribution.
<h4>1.2.1.2. Authentication methods</h4>
Mutt supports several ways to authenticate to your IMAP server,
including plain-old login, CRAM-MD5 (in which the server issues a
one-time challeng string which you hash with your password and then
send back. The server also hashes the string with your password and
compares the result), and GSSAPI, which is Kerberos V
authentication. Additionally mutt supports authentication using the
Cyrus SASL library, and can even encrypt your session when using SASL,
if the particular method being used supports it.
<p>
Mutt will generally pick the best available authentication method, but
you may override its selection by setting the
<tt>imap_authenticators</tt> configuration variable. This is a
colon-delimited list of methods mutt may try, in the order it should
try them. If any of these methods are available but fail, or none of
them are available, mutt will fail to authenticate. For example, if
you only want to use GSSAPI to authenticate, you could
<blockquote>
<tt>set imap_authenticators="gssapi"</tt>
</blockquote>
in which case mutt will only try gssapi, and if that fails or is
unavailable (either because the server doesn't support it or you have
no ticket-granting ticket), mutt will not log you in. Or you could try
something like
<blockquote>
<tt>set imap_authenticators="digest-md5:cram-md5"</tt>
</blockquote>
in which case mutt would attempt DIGEST-MD5 if your SASL library
and the server support it, otherwise CRAM-MD5.
<h4>1.2.1.3. Using a tunnel to your IMAP server</h4>
If you set the configuration variable <tt>tunnel</tt>, mutt will
attempt to run it as a shell command and treat the process as a pipe
to an IMAP server, instead of connecting through a normal network
socket. Note that the hostname, port and SSL options are ignored when
<tt>tunnel</tt> is set, they are used only to display the mailbox
name.
<p>
Also note that your tunnel command has no way to interact with the
terminal, so it can't, for example, ask you for a password. If you try
to use an SSH tunnel with something like
<blockquote>
<tt>set tunnel="ssh -q mailhost /usr/libexec/imapd"</tt>
</blockquote>
you'd better make sure that you don't need a password, probably by
using ssh-agent. Otherwise you are likely to get a "Broken pipe" error
when SSH dies.
<h4>1.2.1.4. Running a shell command before connecting</h4>
If you set the configuration variable <tt>preconnect</tt>, mutt will
attempt to run it as a shell command before connecting to your IMAP
server. You can use this feature to set up SSH port forwarding between
your computer and the IMAP server. For example, if you
<blockquote>
<tt>set preconnect="ssh -f -q -L 1234:mailhost:143 mailhost sleep 5"</tt>
</blockquote>
then an IMAP folder of <tt>imap://localhost:1234/</tt> can be used to
access <tt>imap://mailhost/</tt> over a secure SSH connection.
<h2>1.3. Using an IMAP server instead of local mail</h2>
<ol>
<li>Tell mutt to use your IMAP INBOX as your $spoolfile:
<tt>set spoolfile=imap://<em>hostname</em>/INBOX</tt>
</li>
<li>Set your $folder to your IMAP root:
<tt>set folder=imap://<em>hostname</em>/</tt>
</li>
</ol>
<h3>1.3.1. Polling for new mail</h3>
This works the same as normal mail, with a couple of caveats. You add
mailboxes you'd like to check for mail using the <tt>mailboxes</tt>
command. If you've set your <tt>folder</tt> as above, you can do
<blockquote>
<tt>mailboxes =lists/mutt-dev =lists/mutt-users</tt>
</blockquote>
to poll for mail in <tt>imap://hostname/lists/mutt-dev</tt> and
<tt>imap://hostname/lists/mutt-users</tt>.
<p>
The caveats:
<ul>
<li>Mutt will scan for new mail in all of your mailboxes every
<tt>mail_check</tt> seconds. The default is 5 seconds, which will
make mutt feel very sluggish if you have more than a couple of
mailboxes defined. You'll like mutt better if you increase this to
at least 60.</li>
<li>Mutt checks for mail in the current IMAP mailbox no more ofter
than <tt>timeout</tt> seconds. The default is 600, which means you
will only get notified about new mail in your current mailbox
every 10 minutes. You may wish to lower this to something like 15.
</ul>
<address><a href="mailto:brendan@kublai.com">Brendan Cully</a></address>
</body>
</html>
distrib
>
Altlinux
>
4.1
>
i586
>
media
>
core-src
>
by-pkgid
>
818205f6325473533f345b0ba31e289d
>
files
>
1
