GSP/GSP-Agent-Windows
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
GSP-Agent-Windows/OGP64/usr/share/doc/mutt/optionalfeatures.html

840 lines
No EOL
78 KiB
HTML
Raw Permalink Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 6. Optional Features</title><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="home" href="index.html" title="The Mutt E-Mail Client" /><link rel="up" href="index.html" title="The Mutt E-Mail Client" /><link rel="prev" href="mimesupport.html" title="Chapter 5. Mutt's MIME Support" /><link rel="next" href="security.html" title="Chapter 7. Security Considerations" /><style xmlns="" type="text/css">
body { margin-left:2%; margin-right:2%; font-family:serif; }
.toc, .list-of-tables, .list-of-examples { font-family:sans-serif; }
h1, h2, h3, h4, h5, h6 { font-family:sans-serif; }
p { text-align:justify; }
div.table p.title, div.example p.title { font-size:smaller; font-family:sans-serif; }
.email, .email a { font-family:monospace; }
div.table-contents table, div.informaltable table { border-collapse:collapse; border:1px solid #c0c0c0; }
div.table-contents table td, div.informaltable td, div.table-contents table th, div.informaltable table th { padding:5px; text-align:left; }
div.table-contents table th, div.informaltable table th {
font-family:sans-serif;
background:#d0d0d0;
font-weight:normal;
vertical-align:top;
}
div.cmdsynopsis { border-left:1px solid #707070; padding-left:5px; }
li div.cmdsynopsis { border-left:none; padding-left:0px; }
pre.screen, div.note { background:#f0f0f0; border:1px solid #c0c0c0; padding:5px; margin-left:2%; margin-right:2%; }
div.example p.title { margin-left:2%; }
div.note h3 { font-size:small; font-style:italic; font-variant: small-caps; }
div.note h3:after { content: ":" }
div.note { margin-bottom: 5px; }
.command { font-family: monospace; font-weight: normal; }
.command strong { font-weight: normal; }
tr { vertical-align: top; }
.comment { color:#707070; }
</style></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 6. Optional Features</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="mimesupport.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="security.html">Next</a></td></tr></table><hr /></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="optionalfeatures"></a>Chapter 6. Optional Features</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="optionalfeatures.html#optionalfeatures-notes">1. General Notes</a></span></dt><dd><dl><dt><span class="sect2"><a href="optionalfeatures.html#compile-time-features">1.1. Enabling/Disabling Features</a></span></dt><dt><span class="sect2"><a href="optionalfeatures.html#url-syntax">1.2. URL Syntax</a></span></dt></dl></dd><dt><span class="sect1"><a href="optionalfeatures.html#ssl">2. SSL/TLS Support</a></span></dt><dd><dl><dt><span class="sect2"><a href="optionalfeatures.html#starttls">2.1. STARTTLS</a></span></dt><dt><span class="sect2"><a href="optionalfeatures.html#secure-tunnel">2.2. Tunnel</a></span></dt></dl></dd><dt><span class="sect1"><a href="optionalfeatures.html#pop">3. POP3 Support</a></span></dt><dt><span class="sect1"><a href="optionalfeatures.html#imap">4. IMAP Support</a></span></dt><dd><dl><dt><span class="sect2"><a href="optionalfeatures.html#imap-browser">4.1. The IMAP Folder Browser</a></span></dt><dt><span class="sect2"><a href="optionalfeatures.html#imap-authentication">4.2. Authentication</a></span></dt></dl></dd><dt><span class="sect1"><a href="optionalfeatures.html#smtp">5. SMTP Support</a></span></dt><dt><span class="sect1"><a href="optionalfeatures.html#oauth">6. OAUTHBEARER Support</a></span></dt><dd><dl><dt><span class="sect2"><a href="optionalfeatures.html#xoauth2">6.1. XOAUTH2 Support</a></span></dt></dl></dd><dt><span class="sect1"><a href="optionalfeatures.html#account-hook">7. Managing Multiple Accounts</a></span></dt><dt><span class="sect1"><a href="optionalfeatures.html#caching">8. Local Caching</a></span></dt><dd><dl><dt><span class="sect2"><a href="optionalfeatures.html#header-caching">8.1. Header Caching</a></span></dt><dt><span class="sect2"><a href="optionalfeatures.html#body-caching">8.2. Body Caching</a></span></dt><dt><span class="sect2"><a href="optionalfeatures.html#cache-dirs">8.3. Cache Directories</a></span></dt><dt><span class="sect2"><a href="optionalfeatures.html#maint-cache">8.4. Maintenance</a></span></dt></dl></dd><dt><span class="sect1"><a href="optionalfeatures.html#exact-address">9. Exact Address Generation</a></span></dt><dt><span class="sect1"><a href="optionalfeatures.html#sending-mixmaster">10. Sending Anonymous Messages via Mixmaster</a></span></dt><dt><span class="sect1"><a href="optionalfeatures.html#sidebar">11. Sidebar</a></span></dt><dd><dl><dt><span class="sect2"><a href="optionalfeatures.html#sidebar-intro">11.1. Introduction</a></span></dt><dt><span class="sect2"><a href="optionalfeatures.html#sidebar-variables">11.2. Variables</a></span></dt><dt><span class="sect2"><a href="optionalfeatures.html#sidebar-functions">11.3. Functions</a></span></dt><dt><span class="sect2"><a href="optionalfeatures.html#sidebar-whitelist">11.4. Commands</a></span></dt><dt><span class="sect2"><a href="optionalfeatures.html#sidebar-colors">11.5. Colors</a></span></dt><dt><span class="sect2"><a href="optionalfeatures.html#sidebar-sort">11.6. Sort</a></span></dt><dt><span class="sect2"><a href="optionalfeatures.html#sidebar-see-also">11.7. See Also</a></span></dt></dl></dd><dt><span class="sect1"><a href="optionalfeatures.html#compress">12. Compressed Folders Feature</a></span></dt><dd><dl><dt><span class="sect2"><a href="optionalfeatures.html#compress-intro">12.1. Introduction</a></span></dt><dt><span class="sect2"><a href="optionalfeatures.html#compress-commands">12.2. Commands</a></span></dt></dl></dd><dt><span class="sect1"><a href="optionalfeatures.html#autocryptdoc">13. Autocrypt</a></span></dt><dd><dl><dt><span class="sect2"><a href="optionalfeatures.html#autocryptdoc-requirements">13.1. Requirements</a></span></dt><dt><span class="sect2"><a href="optionalfeatures.html#autocryptdoc-init">13.2. First Run</a></span></dt><dt><span class="sect2"><a href="optionalfeatures.html#autocryptdoc-compose">13.3. Compose Menu</a></span></dt><dt><span class="sect2"><a href="optionalfeatures.html#autocryptdoc-acctmgmt">13.4. Account Management</a></span></dt><dt><span class="sect2"><a href="optionalfeatures.html#autocryptdoc-keyrings">13.5. Alternative Key and Keyring Strategies</a></span></dt></dl></dd></dl></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="optionalfeatures-notes"></a>1. General Notes</h2></div></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="compile-time-features"></a>1.1. Enabling/Disabling Features</h3></div></div></div><p>
Mutt supports several of optional features which can be enabled or
disabled at compile-time by giving the <span class="emphasis"><em>configure</em></span>
script certain arguments. These are listed in the <span class="quote">“<span class="quote">Optional
features</span>”</span> section of the <span class="emphasis"><em>configure --help</em></span>
output.
</p><p>
Which features are enabled or disabled can later be determined from the
output of <code class="literal">mutt -v</code>. If a compile option starts with
<span class="quote">“<span class="quote">+</span>”</span> it is enabled and disabled if prefixed with
<span class="quote">“<span class="quote">-</span>”</span>. For example, if Mutt was compiled using GnuTLS for
encrypted communication instead of OpenSSL, <code class="literal">mutt -v</code>
would contain:
</p><pre class="screen">
-USE_SSL_OPENSSL +USE_SSL_GNUTLS</pre></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="url-syntax"></a>1.2. URL Syntax</h3></div></div></div><p>
Mutt optionally supports the IMAP, POP3 and SMTP protocols which require
to access servers using URLs. The canonical syntax for specifying URLs
in Mutt is (an item enclosed in <code class="literal">[]</code> means it is
optional and may be omitted):
</p><pre class="screen">
proto[s]://[username[:password]@]server[:port][/path]
</pre><p>
<span class="emphasis"><em>proto</em></span> is the communication protocol:
<code class="literal">imap</code> for IMAP, <code class="literal">pop</code> for POP3 and
<code class="literal">smtp</code> for SMTP. If <span class="quote">“<span class="quote">s</span>”</span> for <span class="quote">“<span class="quote">secure
communication</span>”</span> is appended, Mutt will attempt to establish an
encrypted communication using SSL or TLS.
</p><p>
Since all protocols supported by Mutt support/require authentication,
login credentials may be specified in the URL. This has the advantage
that multiple IMAP, POP3 or SMTP servers may be specified (which isn't
possible using, for example, <a class="link" href="reference.html#imap-user" title="3.155. imap_user">$imap_user</a>). The username may contain the
<span class="quote">“<span class="quote">@</span>”</span> symbol being used by many mail systems as part of the
login name. The special characters <span class="quote">“<span class="quote">/</span>”</span>
(<code class="literal">%2F</code>), <span class="quote">“<span class="quote">:</span>”</span> (<code class="literal">%3A</code>) and
<span class="quote">“<span class="quote">%</span>”</span> (<code class="literal">%25</code>) have to be URL-encoded in
usernames using the <code class="literal">%</code>-notation.
</p><p>
A password can be given, too but is not recommended if the URL is
specified in a configuration file on disk.
</p><p>
If no port number is given, Mutt will use the system's default for the
given protocol (usually consulting <code class="literal">/etc/services</code>).
</p><p>
The optional path is only relevant for IMAP and ignored elsewhere.
</p><div class="example"><a id="ex-url"></a><p class="title"><strong>Example 6.1. URLs</strong></p><div class="example-contents"><pre class="screen">
pops://host/
imaps://user@host/INBOX/Sent
smtp://user@host:587/
</pre></div></div><br class="example-break" /></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ssl"></a>2. SSL/TLS Support</h2></div></div></div><p>
If Mutt is compiled with IMAP, POP3 and/or SMTP support, it can also be
compiled with support for SSL or TLS using either OpenSSL or GnuTLS ( by
running the <span class="emphasis"><em>configure</em></span> script with the
<span class="emphasis"><em>--enable-ssl=...</em></span> option for OpenSSL or
<span class="emphasis"><em>--enable-gnutls=...</em></span> for GnuTLS). Mutt can then
attempt to encrypt communication with remote servers if these protocols
are suffixed with <span class="quote">“<span class="quote">s</span>”</span> for <span class="quote">“<span class="quote">secure
communication</span>”</span>.
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="starttls"></a>2.1. STARTTLS</h3></div></div></div><p>
When non-secure URL protocols <code class="literal">imap://</code>,
<code class="literal">pop://</code>, and <code class="literal">smtp://</code> are
used, the initial connection to the server will be unencrypted.
<code class="literal">STARTTLS</code> can be used to negotiate an encrypted
connection after the initial unencrypted connection and exchange.
</p><p>
Two configuration variables control Mutt's behavior with
<code class="literal">STARTTLS</code>. <a class="link" href="reference.html#ssl-starttls" title="3.375. ssl_starttls">$ssl_starttls</a> will initiate
<code class="literal">STARTTLS</code> if the server advertises support for
it. <a class="link" href="reference.html#ssl-force-tls" title="3.373. ssl_force_tls">$ssl_force_tls</a> will
always try to initiate it, whether the server advertises support
or not.
</p><p>
Mutt <span class="emphasis"><em>highly recommends</em></span> setting <a class="link" href="reference.html#ssl-force-tls" title="3.373. ssl_force_tls">$ssl_force_tls</a> unless you need to
connect to an unencrypted server. It's possible for an attacker
to spoof interactions during the initial connection and hide
support for <code class="literal">STARTTLS</code>. The only way to prevent
these attacks is by forcing <code class="literal">STARTTLS</code> with the
<a class="link" href="reference.html#ssl-force-tls" title="3.373. ssl_force_tls">$ssl_force_tls</a> configuration
variable.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="secure-tunnel"></a>2.2. Tunnel</h3></div></div></div><p>
When connecting through a <a class="link" href="reference.html#tunnel" title="3.405. tunnel">$tunnel</a>
and <a class="link" href="reference.html#tunnel-is-secure" title="3.406. tunnel_is_secure">$tunnel_is_secure</a> is
set (the default), Mutt will assume the connection to the server
through the pipe is already secured. Mutt will ignore <a class="link" href="reference.html#ssl-starttls" title="3.375. ssl_starttls">$ssl_starttls</a> and <a class="link" href="reference.html#ssl-force-tls" title="3.373. ssl_force_tls">$ssl_force_tls</a>, behaving as if TLS
has already been negotiated.
</p><p>
When <a class="link" href="reference.html#tunnel-is-secure" title="3.406. tunnel_is_secure">$tunnel_is_secure</a> is
unset, Mutt will respect the values of <a class="link" href="reference.html#ssl-starttls" title="3.375. ssl_starttls">$ssl_starttls</a> and <a class="link" href="reference.html#ssl-force-tls" title="3.373. ssl_force_tls">$ssl_force_tls</a>. It is
<span class="emphasis"><em>highly recommended</em></span> to set <a class="link" href="reference.html#ssl-force-tls" title="3.373. ssl_force_tls">$ssl_force_tls</a> in this case, to
force <code class="literal">STARTTLS</code> negotiation. Note that doing so
will prevent connection to an IMAP server configured for
preauthentication (<code class="literal">PREAUTH</code>). If you use this
configuration, it is recommended to use a secure tunnel.
</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="pop"></a>3. POP3 Support</h2></div></div></div><p>
If Mutt is compiled with POP3 support (by running the
<span class="emphasis"><em>configure</em></span> script with the
<span class="emphasis"><em>--enable-pop</em></span> flag), it has the ability to work with
mailboxes located on a remote POP3 server and fetch mail for local
browsing.
</p><p>
Remote POP3 servers can be accessed using URLs with the
<code class="literal">pop</code> protocol for unencrypted and
<code class="literal">pops</code> for encrypted communication, see <a class="xref" href="optionalfeatures.html#url-syntax" title="1.2. URL Syntax">Section 1.2, “URL Syntax”</a> for details.
</p><p>
Polling for new mail is more expensive over POP3 than locally. For this
reason the frequency at which Mutt will check for mail remotely can be
controlled by the <a class="link" href="reference.html#pop-checkinterval" title="3.251. pop_checkinterval">$pop_checkinterval</a> variable, which
defaults to every 60 seconds.
</p><p>
POP is read-only which doesn't allow for some features like editing
messages or changing flags. However, using <a class="xref" href="optionalfeatures.html#header-caching" title="8.1. Header Caching">Section 8.1, “Header Caching”</a> and <a class="xref" href="optionalfeatures.html#body-caching" title="8.2. Body Caching">Section 8.2, “Body Caching”</a> Mutt
simulates the new/old/read flags as well as flagged and replied. Mutt
applies some logic on top of remote messages but cannot change them so
that modifications of flags are lost when messages are downloaded from
the POP server (either by Mutt or other tools).
</p><a id="fetch-mail"></a><p>
Another way to access your POP3 mail is the
<code class="literal">&lt;fetch-mail&gt;</code> function (default: G). It allows
to connect to <a class="link" href="reference.html#pop-host" title="3.253. pop_host">$pop_host</a>, fetch all your
new mail and place it in the local <a class="link" href="reference.html#spoolfile" title="3.370. spoolfile">$spoolfile</a>. After this point, Mutt runs
exactly as if the mail had always been local.
</p><div class="note"><h3 class="title">Note</h3><p>
If you only need to fetch all messages to a local mailbox you should
consider using a specialized program, such as
<code class="literal">fetchmail(1)</code>, <code class="literal">getmail(1)</code> or
similar.
</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="imap"></a>4. IMAP Support</h2></div></div></div><p>
If Mutt was compiled with IMAP support (by running the
<span class="emphasis"><em>configure</em></span> script with the
<span class="emphasis"><em>--enable-imap</em></span> flag), it has the ability to work
with folders located on a remote IMAP server.
</p><p>
You can access the remote inbox by selecting the folder by its URL (see
<a class="xref" href="optionalfeatures.html#url-syntax" title="1.2. URL Syntax">Section 1.2, “URL Syntax”</a> for details) using the
<code class="literal">imap</code> or <code class="literal">imaps</code> protocol.
Alternatively, a pine-compatible notation is also supported, i.e.
<code class="literal">{[username@]imapserver[:port][/ssl]}path/to/folder</code>
</p><p>
Note that not all servers use <span class="quote">“<span class="quote">/</span>”</span> as the hierarchy
separator. Mutt should correctly notice which separator is being used
by the server and convert paths accordingly.
</p><p>
When browsing folders on an IMAP server, you can toggle whether to look
at only the folders you are subscribed to, or all folders with the
<span class="emphasis"><em>toggle-subscribed</em></span> command. See also the <a class="link" href="reference.html#imap-list-subscribed" title="3.143. imap_list_subscribed">$imap_list_subscribed</a> variable.
</p><p>
Polling for new mail on an IMAP server can cause noticeable delays. So,
you'll want to carefully tune the <a class="link" href="reference.html#mail-check" title="3.165. mail_check">$mail_check</a> and <a class="link" href="reference.html#timeout" title="3.398. timeout">$timeout</a> variables. Reasonable values are:
</p><pre class="screen">
set mail_check=90
set timeout=15
</pre><p>
with relatively good results even over slow modem lines.
</p><div class="note"><h3 class="title">Note</h3><p>
Note that if you are using mbox as the mail store on UW servers prior to
v12.250, the server has been reported to disconnect a client if another
client selects the same folder.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="imap-browser"></a>4.1. The IMAP Folder Browser</h3></div></div></div><p>
As of version 1.2, Mutt supports browsing mailboxes on an IMAP
server. This is mostly the same as the local file browser, with the
following differences:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
In lieu of file permissions, Mutt displays the string
<span class="quote">“<span class="quote">IMAP</span>”</span>, possibly followed by the symbol <span class="quote">“<span class="quote">+</span>”</span>,
indicating that the entry contains both messages and subfolders. On
Cyrus-like servers folders will often contain both messages and
subfolders. A mailbox name with a trailing delimiter (usually
<span class="quote">“<span class="quote">/</span>”</span> or <span class="quote">“<span class="quote">.</span>”</span>) indicates subfolders.
</p></li><li class="listitem"><p>
For the case where an entry can contain both messages and subfolders,
the selection key (bound to <code class="literal">enter</code> by default) will
choose to descend into the subfolder view. If you wish to view the
messages in that folder, you must use <code class="literal">view-file</code>
instead (bound to <code class="literal">space</code> by default).
</p></li><li class="listitem"><p>
You can create, delete and rename mailboxes with the
<code class="literal">&lt;create-mailbox&gt;</code>,
<code class="literal">&lt;delete-mailbox&gt;</code>, and
<code class="literal">&lt;rename-mailbox&gt;</code> commands (default bindings:
<code class="literal">C</code>, <code class="literal">d</code> and <code class="literal">r</code>,
respectively). You may also <code class="literal">&lt;subscribe&gt;</code> and
<code class="literal">&lt;unsubscribe&gt;</code> to mailboxes (normally these are
bound to <code class="literal">s</code> and <code class="literal">u</code>, respectively).
</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="imap-authentication"></a>4.2. Authentication</h3></div></div></div><p>
Mutt supports four authentication methods with IMAP servers: SASL,
GSSAPI, CRAM-MD5, and LOGIN (there is a patch by Grant Edwards to add
NTLM authentication for you poor exchange users out there, but it has
yet to be integrated into the main tree). There is also support for the
pseudo-protocol ANONYMOUS, which allows you to log in to a public IMAP
server without having an account. To use ANONYMOUS, simply make your
username blank or <span class="quote">“<span class="quote">anonymous</span>”</span>.
</p><p>
SASL is a special super-authenticator, which selects among several
protocols (including GSSAPI, CRAM-MD5, ANONYMOUS, and DIGEST-MD5) the
most secure method available on your host and the server. Using some of
these methods (including DIGEST-MD5 and possibly GSSAPI), your entire
session will be encrypted and invisible to those teeming network
snoops. It is the best option if you have it. To use it, you must have
the Cyrus SASL library installed on your system and compile Mutt with
the <span class="emphasis"><em>--with-sasl</em></span> flag.
</p><p>
Mutt will try whichever methods are compiled in and available on the
server, in the following order: SASL, ANONYMOUS, GSSAPI, CRAM-MD5,
LOGIN.
</p><p>
There are a few variables which control authentication:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<a class="link" href="reference.html#imap-user" title="3.155. imap_user">$imap_user</a> - controls the username
under which you request authentication on the IMAP server, for all
authenticators. This is overridden by an explicit username in the
mailbox path (i.e. by using a mailbox name of the form
<code class="literal">{user@host}</code>).
</p></li><li class="listitem"><p>
<a class="link" href="reference.html#imap-pass" title="3.146. imap_pass">$imap_pass</a> - a password which you may
preset, used by all authentication methods where a password is needed.
</p></li><li class="listitem"><p>
<a class="link" href="reference.html#imap-authenticators" title="3.134. imap_authenticators">$imap_authenticators</a> - a
colon-delimited list of IMAP authentication methods to try, in the order
you wish to try them. If specified, this overrides Mutt's default
(attempt everything, in the order listed above).
</p></li></ul></div></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="smtp"></a>5. SMTP Support</h2></div></div></div><p>
Besides supporting traditional mail delivery through a
sendmail-compatible program, Mutt supports delivery through SMTP if it
was configured and built with <code class="literal">--enable-smtp</code>.
</p><p>
If the configuration variable <a class="link" href="reference.html#smtp-url" title="3.359. smtp_url">$smtp_url</a>
is set, Mutt will contact the given SMTP server to deliver messages; if
it is unset, Mutt will use the program specified by <a class="link" href="reference.html#sendmail" title="3.305. sendmail">$sendmail</a>.
</p><p>
For details on the URL syntax, please see <a class="xref" href="optionalfeatures.html#url-syntax" title="1.2. URL Syntax">Section 1.2, “URL Syntax”</a>.
</p><p>
The built-in SMTP support supports encryption (the
<code class="literal">smtps</code> protocol using SSL or TLS) as well as SMTP
authentication using SASL. The authentication mechanisms for SASL are
specified in <a class="link" href="reference.html#smtp-authenticators" title="3.356. smtp_authenticators">$smtp_authenticators</a> defaulting to
an empty list which makes Mutt try all available methods from
most-secure to least-secure.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="oauth"></a>6. OAUTHBEARER Support</h2></div></div></div><p>
Preliminary OAUTH support for IMAP, POP, and SMTP is provided via
external scripts.
</p><p>
At least for Gmail, you can use the <code class="literal">oauth2.py</code>
script from Google's gmail-oauth2-tools: <a class="ulink" href="https://github.com/google/gmail-oauth2-tools/blob/master/python/oauth2.py" target="_top">https://github.com/google/gmail-oauth2-tools/blob/master/python/oauth2.py</a>
</p><p>
You'll need to get your own oauth client credentials for Gmail here:
<a class="ulink" href="https://console.developers.google.com/apis/credentials" target="_top">https://console.developers.google.com/apis/credentials</a>
</p><p>
Then, you'd use <code class="literal">oauth2.py</code> with
<code class="literal">--generate_oauth2_token</code> to get a refresh token, and
configure mutt with:
</p><pre class="screen">
set imap_authenticators="oauthbearer"
set imap_oauth_refresh_command="/path/to/oauth2.py --quiet --user=[email_address]\
--client_id=[client_id] --client_secret=[client_secret]\
--refresh_token=[refresh_token]"
</pre><p>
Substitute pop or smtp for imap in the above example to configure for those.
</p><p>
An alternative script is <a class="ulink" href="https://gitlab.com/muttmua/mutt/tree/master/contrib/mutt_oauth2.py" target="_top">contrib/mutt_oauth2.py</a> script. For more details see <a class="ulink" href="https://gitlab.com/muttmua/mutt/tree/master/contrib/mutt_oauth2.py.README" target="_top">contrib/mutt_oauth2.py.README</a>.
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="xoauth2"></a>6.1. XOAUTH2 Support</h3></div></div></div><p>
Support for the deprecated XOAUTH2 protocol is also available. To
enable this, add <span class="quote">“<span class="quote">xoauth2</span>”</span> to the
<a class="link" href="reference.html#imap-authenticators" title="3.134. imap_authenticators">$imap_authenticators</a>,
<a class="link" href="reference.html#pop-authenticators" title="3.250. pop_authenticators">$pop_authenticators</a>, or
<a class="link" href="reference.html#smtp-authenticators" title="3.356. smtp_authenticators">$smtp_authenticators</a> config
variables. XOAUTH2 uses the same refresh command configuration variables
as OAUTHBEARER:
<a class="link" href="reference.html#imap-oauth-refresh-command" title="3.145. imap_oauth_refresh_command">$imap_oauth_refresh_command</a>,
<a class="link" href="reference.html#pop-oauth-refresh-command" title="3.255. pop_oauth_refresh_command">$pop_oauth_refresh_command</a>, and
<a class="link" href="reference.html#smtp-oauth-refresh-command" title="3.357. smtp_oauth_refresh_command">$smtp_oauth_refresh_command</a>.
Those will need to be set to a script to generate the appropriate XOAUTH2
token.
</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="account-hook"></a>7. Managing Multiple Accounts</h2></div></div></div><p>
Usage:
</p><div class="cmdsynopsis"><p><code class="command">account-hook</code>
<em class="replaceable"><code>regexp</code></em>
<em class="replaceable"><code>command</code></em>
</p></div><p>
If you happen to have accounts on multiple IMAP, POP and/or SMTP
servers, you may find managing all the authentication settings
inconvenient and error-prone. The <a class="link" href="optionalfeatures.html#account-hook" title="7. Managing Multiple Accounts"><span class="command"><strong>account-hook</strong></span></a> command
may help. This hook works like <a class="link" href="configuration.html#folder-hook" title="9. Setting Variables Based Upon Mailbox"><span class="command"><strong>folder-hook</strong></span></a> but is
invoked whenever Mutt needs to access a remote mailbox (including inside
the folder browser), not just when you open the mailbox. This includes
(for example) polling for new mail, storing Fcc messages and saving
messages to a folder. As a consequence, <a class="link" href="optionalfeatures.html#account-hook" title="7. Managing Multiple Accounts"><span class="command"><strong>account-hook</strong></span></a> should
only be used to set connection-related settings such as passwords or
tunnel commands but not settings such as sender address or name (because
in general it should be considered unpredictable which <a class="link" href="optionalfeatures.html#account-hook" title="7. Managing Multiple Accounts"><span class="command"><strong>account-hook</strong></span></a> was last
used).
</p><p>
Some examples:
</p><pre class="screen">
account-hook . 'unset imap_user; unset imap_pass; unset tunnel'
account-hook imap://host1/ 'set imap_user=me1 imap_pass=foo'
account-hook imap://host2/ 'set tunnel="ssh host2 /usr/libexec/imapd"'
account-hook smtp://user@host3/ 'set tunnel="ssh host3 /usr/libexec/smtpd"'
</pre><p>
To manage multiple accounts with, for example, different values of <a class="link" href="reference.html#record" title="3.279. record">$record</a> or sender addresses, <a class="link" href="configuration.html#folder-hook" title="9. Setting Variables Based Upon Mailbox"><span class="command"><strong>folder-hook</strong></span></a> has to be
used together with the <a class="link" href="configuration.html#mailboxes" title="16. Monitoring Incoming Mail"><span class="command"><strong>mailboxes</strong></span></a> command.
</p><div class="example"><a id="ex-multiaccount"></a><p class="title"><strong>Example 6.2. Managing multiple accounts</strong></p><div class="example-contents"><pre class="screen">
mailboxes imap://user@host1/INBOX
folder-hook imap://user@host1/ 'set folder=imap://host1/ ; set record=+INBOX/Sent'
mailboxes imap://user@host2/INBOX
folder-hook imap://user@host2/ 'set folder=imap://host2/ ; set record=+INBOX/Sent'
</pre></div></div><br class="example-break" /><p>
In example <a class="xref" href="optionalfeatures.html#ex-multiaccount" title="Example 6.2. Managing multiple accounts">Example 6.2, “Managing multiple accounts”</a> the folders are defined
using <a class="link" href="configuration.html#mailboxes" title="16. Monitoring Incoming Mail"><span class="command"><strong>mailboxes</strong></span></a> so
Mutt polls them for new mail. Each <a class="link" href="configuration.html#folder-hook" title="9. Setting Variables Based Upon Mailbox"><span class="command"><strong>folder-hook</strong></span></a> triggers
when one mailbox below each IMAP account is opened and sets <a class="link" href="reference.html#folder" title="3.97. folder">$folder</a> to the account's root folder. Next, it
sets <a class="link" href="reference.html#record" title="3.279. record">$record</a> to the
<span class="emphasis"><em>INBOX/Sent</em></span> folder below the newly set <a class="link" href="reference.html#folder" title="3.97. folder">$folder</a>. Please notice that the value the
<span class="quote">“<span class="quote">+</span>”</span> <a class="link" href="advancedusage.html#shortcuts" title="10. Mailbox Shortcuts">mailbox shortcut</a>
refers to depends on the <span class="emphasis"><em>current</em></span> value of <a class="link" href="reference.html#folder" title="3.97. folder">$folder</a> and therefore has to be set separately
per account. Setting other values like <a class="link" href="reference.html#from" title="3.109. from">$from</a>
or <a class="link" href="reference.html#signature" title="3.323. signature">$signature</a> is analogous to setting
<a class="link" href="reference.html#record" title="3.279. record">$record</a>.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="caching"></a>8. Local Caching</h2></div></div></div><p>
Mutt contains two types of local caching: <span class="emphasis"><em>(1)</em></span> the
so-called <span class="quote">“<span class="quote">header caching</span>”</span> and <span class="emphasis"><em>(2)</em></span> the
so-called <span class="quote">“<span class="quote">body caching</span>”</span> which are both described in this
section.
</p><p>
Header caching is optional as it depends on external libraries, body
caching is always enabled if Mutt is compiled with POP and/or IMAP
support as these use it (body caching requires no external library).
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="header-caching"></a>8.1. Header Caching</h3></div></div></div><p>
Mutt provides optional support for caching message headers for the
following types of folders: IMAP, POP, Maildir and MH. Header caching
greatly speeds up opening large folders because for remote folders,
headers usually only need to be downloaded once. For Maildir and MH,
reading the headers from a single file is much faster than looking at
possibly thousands of single files (since Maildir and MH use one file
per message.)
</p><p>
Header caching can be enabled via the configure script and the
<span class="emphasis"><em>--enable-hcache</em></span> option. It's not turned on by
default because external database libraries are required: one of
tokyocabinet, kyotocabinet, lmdb, qdbm, gdbm or bdb must be present.
</p><p>
If enabled, <a class="link" href="reference.html#header-cache" title="3.113. header_cache">$header_cache</a> can be
used to either point to a file or a directory. If set to point to a
file, one database file for all folders will be used (which may result
in lower performance), but one file per folder if it points to a
directory. When pointing to a directory, be sure to create the directory
in advance, or Mutt will interpret it as a file to be created.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="body-caching"></a>8.2. Body Caching</h3></div></div></div><p>
Both cache methods can be combined using the same directory for storage
(and for IMAP/POP even provide meaningful file names) which simplifies
manual maintenance tasks.
</p><p>
In addition to caching message headers only, Mutt can also cache whole
message bodies. This results in faster display of messages for POP and
IMAP folders because messages usually have to be downloaded only once.
</p><p>
For configuration, the variable <a class="link" href="reference.html#message-cachedir" title="3.184. message_cachedir">$message_cachedir</a> must point to a directory. There, Mutt will
create a hierarchy of subdirectories named like the account and mailbox
path the cache is for.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="cache-dirs"></a>8.3. Cache Directories</h3></div></div></div><p>
For using both, header and body caching, <a class="link" href="reference.html#header-cache" title="3.113. header_cache">$header_cache</a> and <a class="link" href="reference.html#message-cachedir" title="3.184. message_cachedir">$message_cachedir</a> can be safely set
to the same value.
</p><p>
In a header or body cache directory, Mutt creates a directory hierarchy
named like: <code class="literal">proto:user@hostname</code> where
<code class="literal">proto</code> is either <span class="quote">“<span class="quote">pop</span>”</span> or
<span class="quote">“<span class="quote">imap.</span>”</span> Within there, for each folder, Mutt stores messages
in single files and header caches in files with the
<span class="quote">“<span class="quote">.hcache</span>”</span> extension. All files can be removed as needed if
the consumed disk space becomes an issue as Mutt will silently fetch
missing items again. Pathnames are always stored in UTF-8 encoding.
</p><p>
For Maildir and MH, the header cache files are named after the MD5
checksum of the path.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="maint-cache"></a>8.4. Maintenance</h3></div></div></div><p>
Mutt does not (yet) support maintenance features for header cache
database files so that files have to be removed in case they grow too
big. It depends on the database library used for header caching whether
disk space freed by removing messages is re-used.
</p><p>
For body caches, Mutt can keep the local cache in sync with the remote
mailbox if the <a class="link" href="reference.html#message-cache-clean" title="3.183. message_cache_clean">$message_cache_clean</a> variable is
set. Cleaning means to remove messages from the cache which are no
longer present in the mailbox which only happens when other mail clients
or instances of Mutt using a different body cache location delete
messages (Mutt itself removes deleted messages from the cache when
syncing a mailbox). As cleaning can take a noticeable amount of time, it
should not be set in general but only occasionally.
</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="exact-address"></a>9. Exact Address Generation</h2></div></div></div><p>
Mutt supports the <span class="quote">“<span class="quote">Name &lt;user@host&gt;</span>”</span> address syntax
for reading and writing messages, the older <span class="quote">“<span class="quote">user@host
(Name)</span>”</span> syntax is only supported when reading messages. The
<span class="emphasis"><em>--enable-exact-address</em></span> switch can be given to
configure to build it with write-support for the latter
syntax. <code class="literal">EXACT_ADDRESS</code> in the output of <code class="literal">mutt
-v</code> indicates whether it's supported.
</p><p>
Note: If the full address contains non-ascii characters, or sequences
that require RFC 2047 encoding, Mutt reverts to writing out the
normalized <span class="quote">“<span class="quote">Name &lt;user@host&gt;</span>”</span> form, in order to
generate legal output.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="sending-mixmaster"></a>10. Sending Anonymous Messages via Mixmaster</h2></div></div></div><p>
You may also have compiled Mutt to co-operate with Mixmaster, an
anonymous remailer. Mixmaster permits you to send your messages
anonymously using a chain of remailers. Mixmaster support in Mutt is for
mixmaster version 2.04 or later.
</p><p>
To use it, you'll have to obey certain restrictions. Most important,
you cannot use the <code class="literal">Cc</code> and <code class="literal">Bcc</code>
headers. To tell Mutt to use mixmaster, you have to select a remailer
chain, using the mix function on the compose menu.
</p><p>
The chain selection screen is divided into two parts. In the (larger)
upper part, you get a list of remailers you may use. In the lower part,
you see the currently selected chain of remailers.
</p><p>
You can navigate in the chain using the
<code class="literal">&lt;chain-prev&gt;</code> and
<code class="literal">&lt;chain-next&gt;</code> functions, which are by default
bound to the left and right arrows and to the <code class="literal">h</code> and
<code class="literal">l</code> keys (think vi keyboard bindings). To insert a
remailer at the current chain position, use the
<code class="literal">&lt;insert&gt;</code> function. To append a remailer behind
the current chain position, use <code class="literal">&lt;select-entry&gt;</code>
or <code class="literal">&lt;append&gt;</code>. You can also delete entries from
the chain, using the corresponding function. Finally, to abandon your
changes, leave the menu, or <code class="literal">&lt;accept&gt;</code> them
pressing (by default) the <code class="literal">Return</code> key.
</p><p>
Note that different remailers do have different capabilities, indicated
in the %c entry of the remailer menu lines (see <a class="link" href="reference.html#mix-entry-format" title="3.198. mix_entry_format">$mix_entry_format</a>). Most important is
the <span class="quote">“<span class="quote">middleman</span>”</span> capability, indicated by a capital
<span class="quote">“<span class="quote">M</span>”</span>: This means that the remailer in question cannot be
used as the final element of a chain, but will only forward messages to
other mixmaster remailers. For details on the other capabilities,
please have a look at the mixmaster documentation.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="sidebar"></a>11. Sidebar</h2></div><div><h3 class="subtitle">Overview of mailboxes</h3></div></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="sidebar-intro"></a>11.1. Introduction</h3></div></div></div><p>
The Sidebar shows a list of all your mailboxes. The list can be
turned on and off, it can be themed and the list style can be
configured.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="sidebar-variables"></a>11.2. Variables</h3></div></div></div><div class="table"><a id="table-sidebar-variables"></a><p class="title"><strong>Table 6.1. Sidebar Variables</strong></p><div class="table-contents"><table class="table" summary="Sidebar Variables" border="1"><colgroup><col /><col /><col /></colgroup><thead><tr><th>Name</th><th>Type</th><th>Default</th></tr></thead><tbody><tr><td><code class="literal">sidebar_delim_chars</code></td><td>string</td><td><code class="literal">/.</code></td></tr><tr><td><code class="literal">sidebar_divider_char</code></td><td>string</td><td><code class="literal">|</code></td></tr><tr><td><code class="literal">sidebar_folder_indent</code></td><td>boolean</td><td><code class="literal">no</code></td></tr><tr><td><code class="literal">sidebar_format</code></td><td>string</td><td><code class="literal">%B%* %n</code></td></tr><tr><td><code class="literal">sidebar_indent_string</code></td><td>string</td><td><code class="literal">  </code> (two spaces)</td></tr><tr><td><code class="literal">sidebar_new_mail_only</code></td><td>boolean</td><td><code class="literal">no</code></td></tr><tr><td><code class="literal">sidebar_next_new_wrap</code></td><td>boolean</td><td><code class="literal">no</code></td></tr><tr><td><code class="literal">sidebar_short_path</code></td><td>boolean</td><td><code class="literal">no</code></td></tr><tr><td><code class="literal">sidebar_sort_method</code></td><td>enum</td><td><code class="literal">unsorted</code></td></tr><tr><td><code class="literal">sidebar_visible</code></td><td>boolean</td><td><code class="literal">no</code></td></tr><tr><td><code class="literal">sidebar_width</code></td><td>number</td><td><code class="literal">20</code></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="sidebar-functions"></a>11.3. Functions</h3></div></div></div><p>
Sidebar adds the following functions to Mutt.
By default, none of them are bound to keys.
</p><div class="table"><a id="table-sidebar-functions"></a><p class="title"><strong>Table 6.2. Sidebar Functions</strong></p><div class="table-contents"><table class="table" summary="Sidebar Functions" border="1"><colgroup><col /><col /><col /></colgroup><thead><tr><th>Menus</th><th>Function</th><th>Description</th></tr></thead><tbody><tr><td>index,pager</td><td><code class="literal">&lt;sidebar-next&gt;</code></td><td>Move the highlight to next mailbox</td></tr><tr><td>index,pager</td><td><code class="literal">&lt;sidebar-next-new&gt;</code></td><td>Move the highlight to next mailbox with new mail</td></tr><tr><td>index,pager</td><td><code class="literal">&lt;sidebar-open&gt;</code></td><td>Open highlighted mailbox</td></tr><tr><td>index,pager</td><td><code class="literal">&lt;sidebar-page-down&gt;</code></td><td>Scroll the Sidebar down 1 page</td></tr><tr><td>index,pager</td><td><code class="literal">&lt;sidebar-page-up&gt;</code></td><td>Scroll the Sidebar up 1 page</td></tr><tr><td>index,pager</td><td><code class="literal">&lt;sidebar-prev&gt;</code></td><td>Move the highlight to previous mailbox</td></tr><tr><td>index,pager</td><td><code class="literal">&lt;sidebar-prev-new&gt;</code></td><td>Move the highlight to previous mailbox with new mail</td></tr><tr><td>index,pager</td><td><code class="literal">&lt;sidebar-toggle-visible&gt;</code></td><td>Make the Sidebar (in)visible</td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="sidebar-whitelist"></a>11.4. Commands</h3></div></div></div><div class="cmdsynopsis"><p><code class="command">sidebar_whitelist</code>
<em class="replaceable"><code>mailbox</code></em>
[
<em class="replaceable"><code>mailbox</code></em>
...]<br /><code class="command">unsidebar_whitelist</code> {
<em class="replaceable"><code>*</code></em>
|
<em class="replaceable"><code>mailbox</code></em>
... }</p></div><p>
This command specifies mailboxes that will always be displayed
in the sidebar, even if <a class="link" href="reference.html#sidebar-new-mail-only" title="3.313. sidebar_new_mail_only">$sidebar_new_mail_only</a>
is set and the mailbox does not contain new mail.
</p><p>
The <span class="quote">“<span class="quote">unsidebar_whitelist</span>”</span> command is used to remove a mailbox from
the list of whitelisted mailboxes. Use <span class="quote">“<span class="quote">unsidebar_whitelist *</span>”</span>
to remove all mailboxes.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="sidebar-colors"></a>11.5. Colors</h3></div></div></div><div class="table"><a id="table-sidebar-colors"></a><p class="title"><strong>Table 6.3. Sidebar Colors</strong></p><div class="table-contents"><table class="table" summary="Sidebar Colors" border="1"><colgroup><col /><col /><col /></colgroup><thead><tr><th>Name</th><th>Default Color</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">sidebar_divider</code></td><td>default</td><td>The dividing line between the Sidebar and the Index/Pager panels</td></tr><tr><td><code class="literal">sidebar_flagged</code></td><td>default</td><td>Mailboxes containing flagged mail</td></tr><tr><td><code class="literal">sidebar_highlight</code></td><td>underline</td><td>Cursor to select a mailbox</td></tr><tr><td><code class="literal">sidebar_indicator</code></td><td>mutt <code class="literal">indicator</code></td><td>The mailbox open in the Index panel</td></tr><tr><td><code class="literal">sidebar_new</code></td><td>default</td><td>Mailboxes containing new mail</td></tr><tr><td><code class="literal">sidebar_spoolfile</code></td><td>default</td><td>Mailbox that receives incoming mail</td></tr></tbody></table></div></div><br class="table-break" /><p>
If the <code class="literal">sidebar_indicator</code> color isn't set, then the default Mutt
indicator color will be used (the color used in the index panel).
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="sidebar-sort"></a>11.6. Sort</h3></div></div></div><div class="table"><a id="table-sidebar-sort"></a><p class="title"><strong>Table 6.4. Sidebar Sort</strong></p><div class="table-contents"><table class="table" summary="Sidebar Sort" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Sort</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">alpha</code></td><td>Alphabetically by path or label</td></tr><tr><td><code class="literal">count</code></td><td>Total number of messages</td></tr><tr><td><code class="literal">flagged</code></td><td>Number of flagged messages</td></tr><tr><td><code class="literal">name</code></td><td>Alphabetically by path or label</td></tr><tr><td><code class="literal">new</code></td><td>Number of unread messages</td></tr><tr><td><code class="literal">path</code></td><td>Alphabetically by path (ignores label)</td></tr><tr><td><code class="literal">unread</code></td><td>Number of unread messages</td></tr><tr><td><code class="literal">unsorted</code></td><td>Do not resort the paths</td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="sidebar-see-also"></a>11.7. See Also</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a class="link" href="advancedusage.html#regexp" title="2. Regular Expressions">Regular Expressions</a></p></li><li class="listitem"><p><a class="link" href="advancedusage.html#patterns" title="3. Patterns: Searching, Limiting and Tagging">Patterns</a></p></li><li class="listitem"><p><a class="link" href="configuration.html#color" title="11. Using Color and Mono Video Attributes">Color command</a></p></li></ul></div></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="compress"></a>12. Compressed Folders Feature</h2></div><div><h3 class="subtitle">Read from/write to compressed mailboxes</h3></div></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="compress-intro"></a>12.1. Introduction</h3></div></div></div><p>
The Compressed Folder patch allows Mutt to read mailbox files that are
compressed. But it isn't limited to compressed files. It works well
with encrypted files, too. In fact, if you can create a program/script
to convert to and from your format, then Mutt can read it.
</p><p>
The patch adds three hooks to Mutt: <code class="literal">open-hook</code>,
<code class="literal">close-hook</code> and <code class="literal">append-hook</code>. They
define commands to: uncompress a file; compress a file; append
messages to an already compressed file.
</p><p>
There are some examples of both compressed and encrypted files,
later. For now, the documentation will just concentrate on
compressed files.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="compress-commands"></a>12.2. Commands</h3></div></div></div><div class="cmdsynopsis"><p><code class="command">open-hook</code>
<em class="replaceable"><code>pattern</code></em>
<em class="replaceable"><code>shell-command</code></em>
<br /><code class="command">close-hook</code>
<em class="replaceable"><code>pattern</code></em>
<em class="replaceable"><code>shell-command</code></em>
<br /><code class="command">append-hook</code>
<em class="replaceable"><code>pattern</code></em>
<em class="replaceable"><code>shell-command</code></em>
</p></div><p>
The shell-command must contain two placeholders for filenames:
<code class="literal">%f</code> and <code class="literal">%t</code>. These represent
<span class="quote">“<span class="quote">from</span>”</span> and <span class="quote">“<span class="quote">to</span>”</span> filenames. These placeholders
should be placed inside single-quotes to prevent unintended shell
expansions.
</p><p>
If you need the exact string <span class="quote">“<span class="quote">%f</span>”</span> or <span class="quote">“<span class="quote">%t</span>”</span> in your
command, simply double up the <span class="quote">“<span class="quote">%</span>”</span> character, e.g.
<span class="quote">“<span class="quote">%%f</span>”</span> or <span class="quote">“<span class="quote">%%t</span>”</span>.
</p><div class="table"><a id="table-compress-optional"></a><p class="title"><strong>Table 6.5. Not all Hooks are Required</strong></p><div class="table-contents"><table class="table" summary="Not all Hooks are Required" border="1"><colgroup><col /><col /><col /><col /><col /></colgroup><thead><tr><th>Open</th><th>Close</th><th>Append</th><th>Effect</th><th>Useful if</th></tr></thead><tbody><tr><td>Open</td><td>-</td><td>-</td><td>Folder is readonly</td><td>The folder is just a backup</td></tr><tr><td>Open</td><td>Close</td><td>-</td><td>Folder is read/write, but the entire folder must be
written if anything is changed</td><td>Your compression format doesn't support appending</td></tr><tr><td>Open</td><td>Close</td><td>Append</td><td>Folder is read/write and emails can be efficiently added
to the end</td><td>Your compression format supports appending</td></tr><tr><td>Open</td><td>-</td><td>Append</td><td>Folder is readonly, but can be appended to</td><td>You want to store emails, but never change them</td></tr></tbody></table></div></div><br class="table-break" /><div class="note"><h3 class="title">Note</h3><p>The command:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>should return a non-zero exit status on failure</p></li><li class="listitem"><p>should not delete any files</p></li></ul></div></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="open-hook"></a>12.2.1. Read from compressed mailbox</h4></div></div></div><pre class="screen">open-hook regexp shell-command</pre><p>
If Mutt is unable to open a file, it then looks for
<code class="literal">open-hook</code> that matches the filename.
</p><p>
If your compression program doesn't have a well-defined extension,
then you can use <code class="literal">.</code> as the regexp.
</p><div class="example"><a id="compress-open-hook-example"></a><p class="title"><strong>Example 6.3. Example of open-hook</strong></p><div class="example-contents"><pre class="screen">open-hook '\.gz$' "gzip -cd '%f' &gt; '%t'"</pre><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Mutt finds a file, <span class="quote">“<span class="quote">example.gz</span>”</span>,
that it can't read</p></li><li class="listitem"><p>Mutt has an <code class="literal">open-hook</code>
whose regexp matches the filename:
<code class="literal">\.gz$</code></p></li><li class="listitem"><p>Mutt uses the command <code class="literal">gzip -cd</code>
to create a temporary file that it <span class="emphasis"><em>can</em></span>
read</p></li></ul></div></div></div><br class="example-break" /></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="close-hook"></a>12.2.2. Write to a compressed mailbox</h4></div></div></div><pre class="screen">close-hook regexp shell-command</pre><p>
When Mutt has finished with a compressed mail folder, it will look
for a matching <code class="literal">close-hook</code> to recompress the file.
This hook is <a class="link" href="optionalfeatures.html#table-compress-optional" title="Table 6.5. Not all Hooks are Required">optional</a>.
</p><div class="note"><h3 class="title">Note</h3><p>
If the folder has not been modified, the
<code class="literal">close-hook</code> will not be called.
</p></div><div class="example"><a id="compress-close-hook-example"></a><p class="title"><strong>Example 6.4. Example of close-hook</strong></p><div class="example-contents"><pre class="screen">close-hook '\.gz$' "gzip -c '%t' &gt; '%f'"</pre><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Mutt has finished with a folder, <span class="quote">“<span class="quote">example.gz</span>”</span>,
that it opened with <code class="literal">open-hook</code></p></li><li class="listitem"><p>The folder has been modified</p></li><li class="listitem"><p>Mutt has a <code class="literal">close-hook</code> whose regexp
matches the filename: <code class="literal">\.gz$</code></p></li><li class="listitem"><p>Mutt uses the command <code class="literal">gzip -c</code>
to create a new compressed file</p></li></ul></div></div></div><br class="example-break" /></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="append-hook"></a>12.2.3. Append to a compressed mailbox</h4></div></div></div><pre class="screen">append-hook regexp shell-command</pre><p>
When Mutt wants to append an email to a compressed mail folder, it
will look for a matching <code class="literal">append-hook</code>.
This hook is <a class="link" href="optionalfeatures.html#table-compress-optional" title="Table 6.5. Not all Hooks are Required">optional</a>.
</p><p>
Using the <code class="literal">append-hook</code> will save time, but
Mutt won't be able to determine the type of the mail folder
inside the compressed file.
</p><p>
Mutt will <span class="emphasis"><em>assume</em></span> the type to be that of
the <code class="literal">$mbox_type</code> variable. Mutt also uses
this type for temporary files.
</p><p>
Mutt will only use the <code class="literal">append-hook</code> for existing files.
The <code class="literal">close-hook</code> will be used for empty, or missing files.
</p><div class="note"><h3 class="title">Note</h3><p>
If your command writes to stdout, it is vital that you use
<code class="literal">&gt;&gt;</code> in the <span class="quote">“<span class="quote">append-hook</span>”</span>.
If not, data will be lost.
</p></div><div class="example"><a id="compress-append-hook-example"></a><p class="title"><strong>Example 6.5. Example of append-hook</strong></p><div class="example-contents"><pre class="screen">append-hook '\.gz$' "gzip -c '%t' &gt;&gt; '%f'"</pre><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Mutt wants to append an email to a folder, <span class="quote">“<span class="quote">example.gz</span>”</span>,
that it opened with <code class="literal">open-hook</code></p></li><li class="listitem"><p>Mutt has an <code class="literal">append-hook</code> whose regexp matches
the filename: <code class="literal">\.gz$</code></p></li><li class="listitem"><p>Mutt knows the mailbox type from the <code class="literal">$mbox</code>
variable</p></li><li class="listitem"><p>Mutt uses the command <code class="literal">gzip -c</code>
to append to an existing compressed file</p></li></ul></div></div></div><br class="example-break" /></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="compress-empty"></a>12.2.4. Empty Files</h4></div></div></div><p>
Mutt assumes that an empty file is not compressed. In this
situation, unset <a class="link" href="reference.html#save-empty" title="3.294. save_empty">$save_empty</a>, so
that the compressed file will be removed if you delete all of the
messages.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="compress-security"></a>12.2.5. Security</h4></div></div></div><p>
Encrypted files are decrypted into temporary files which are
stored in the <a class="link" href="reference.html#tmpdir" title="3.399. tmpdir">$tmpdir</a> directory.
This could be a security risk.
</p></div></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="autocryptdoc"></a>13. Autocrypt</h2></div></div></div><p>
Mutt can be compiled with Autocrypt support by running
<code class="literal">configure</code> with the
<code class="literal">--enable-autocrypt</code> flag. Autocrypt provides
easy to use, passive protection against data collection. Keys are
distributed via an <code class="literal">Autocrypt:</code> header added to
emails. It does <span class="emphasis"><em>not</em></span> protect against active
adversaries, and so should not be considered a substitute for
normal encryption via your keyring, using key signing and the web
of trust to verify identities. With an understanding of these
limitations, Autocrypt still provides an easy way to minimize
cleartext emails sent between common correspondents, without
having to explicitly exchange keys. More information can be found
at <a class="ulink" href="https://autocrypt.org/" target="_top">https://autocrypt.org/</a>.
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="autocryptdoc-requirements"></a>13.1. Requirements</h3></div></div></div><p>
Autocrypt requires support for ECC cryptography, and Mutt by
default will generate ECC keys. Therefore GnuPG 2.1 or greater
is required. Additionally, Mutt's Autocrypt implementation uses
GPGME and requires at least version 1.8.0.
</p><p>
Account and peer information is stored in a sqlite3 database, and
so Mutt must be configured with the <code class="literal">--with-sqlite3</code>
flag when autocrypt is enabled.
</p><p>
It is highly recommended Mutt be configured
<code class="literal">--with-idn</code> or
<code class="literal">--with-idn2</code> so that Autocrypt can properly
deal with international domain names.
</p><p>
While Mutt uses GPGME for Autocrypt, normal keyring operations
can still be performed via classic mode (i.e. with <a class="link" href="reference.html#crypt-use-gpgme" title="3.71. crypt_use_gpgme">$crypt_use_gpgme</a> unset).
However, to avoid unnecessary prompts, it is recommended gpg not
be configured in <code class="literal">loopback pinentry</code> mode, and
that <a class="link" href="reference.html#pgp-use-gpg-agent" title="3.242. pgp_use_gpg_agent">$pgp_use_gpg_agent</a>
remain set (the default).
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="autocryptdoc-init"></a>13.2. First Run</h3></div></div></div><p>
To enable Autocrypt, set <a class="link" href="reference.html#autocrypt" title="3.24. autocrypt">$autocrypt</a>, and if desired change the
value of <a class="link" href="reference.html#autocrypt-dir" title="3.26. autocrypt_dir">$autocrypt_dir</a> in
your muttrc. The first time Mutt is run after that, you will be
prompted to create <a class="link" href="reference.html#autocrypt-dir" title="3.26. autocrypt_dir">$autocrypt_dir</a>. Mutt will then
automatically create an sqlite3 database and GPG keyring in that
directory. Note since these files should be considered private,
Mutt will create this directory with mode
<code class="literal">700</code>. If you create the directory manually,
you should do the same.
</p><p>
Mutt recommends keeping the <a class="link" href="reference.html#autocrypt-dir" title="3.26. autocrypt_dir">$autocrypt_dir</a> directory set
differently from your GnuPG keyring directory
(e.g. <code class="literal">~/.gnupg</code>). Keys are automatically
imported into the keyring from <code class="literal">Autocrypt:</code>
headers. Compared to standard <span class="quote">“<span class="quote">web of trust</span>”</span> keys,
Autocrypt keys are somewhat ephemeral, and the autocrypt
database is used to track when keys change or fall out of use.
Having these keys mixed in with your normal keyring will make it
more difficult to use features such as <a class="link" href="reference.html#crypt-opportunistic-encrypt" title="3.61. crypt_opportunistic_encrypt">$crypt_opportunistic_encrypt</a>
and Autocrypt at the same time.
</p><p>
The <a class="link" href="reference.html#autocrypt-dir" title="3.26. autocrypt_dir">$autocrypt_dir</a> variable
is not designed to be changed while Mutt is running. The
database is created (if necessary) and connected to during
startup. Changing the variable can result in a situation where
Mutt is looking in one place for the database and a different
place for the GPG keyring, resulting in strange behavior.
</p><p>
Once the directory, keyring, and database are created, Mutt will
ask whether you would like to create an account. In order to
use Autocrypt, each sending address needs an account. As a
convenience you can create an account during the first run. If
you would like to add additional accounts later, this can be
done via the <code class="literal">&lt;autocrypt-acct-menu&gt;</code>
function in the index, by default bound to <code class="literal">A</code>.
</p><p>
Account creation will first ask you for an email address. Next,
it will ask whether you want to create a new key or select an
existing key. (Note key selection takes place from the <a class="link" href="reference.html#autocrypt-dir" title="3.26. autocrypt_dir">$autocrypt_dir</a> keyring, which
will normally be empty during first run). Finally, it will ask
whether this address should prefer encryption or not. Autocrypt
1.1 allows automatically enabling encryption if
<span class="emphasis"><em>both</em></span> sender and receiver have set
<span class="quote">“<span class="quote">prefer encryption</span>”</span>. Otherwise, you will need to
manually enable autocrypt encryption in the compose menu. For
more details, see the compose menu section below.
</p><p>
After optionally creating an account, Mutt will prompt you to
scan mailboxes for Autocrypt headers. This step occurs because
header cached messages are not re-scanned for Autocrypt headers.
Scanning during this step will temporarily disable the header
cache while opening each mailbox. If you wish to do this
manually later, you can simulate the same thing by unsetting
<a class="link" href="reference.html#header-cache" title="3.113. header_cache">$header_cache</a> and opening a
mailbox.
</p><p>
A final technical note: the first run process takes place
between reading the muttrc and opening the initial mailbox.
Some muttrc files will <a class="link" href="configuration.html#push" title="25. Adding Key Sequences to the Keyboard Buffer">push</a> macros
to be run after opening the mailbox. To prevent this from
interfering with the first run prompts, Mutt disables all macros
during the first run.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="autocryptdoc-compose"></a>13.3. Compose Menu</h3></div></div></div><p>
When enabled, Autocrypt will add a line to the compose menu with
two fields: <code class="literal">Autocrypt:</code> and
<code class="literal">Recommendation:</code>.
</p><p>
The <code class="literal">Autocrypt:</code> field shows whether the
message will be encrypted by Autocrypt when sent. It has two
values: <code class="literal">Encrypt</code> and <code class="literal">Off</code>.
<code class="literal">Encrypt</code> can be enabled using the
<code class="literal">&lt;autocrypt-menu&gt;</code> function, by default
bound to <code class="literal">o</code>.
</p><p>
The <code class="literal">Recommendation:</code> field shows the output of
the Autocrypt recommendation engine. This can have one of five
values:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<code class="literal">Off</code> means the engine is disabled. This
can happen if the From address doesn't have an autocrypt
account, or if the account has been manually disabled.
</p></li><li class="listitem"><p>
<code class="literal">No</code> means one or more recipients are
missing an autocrypt key, or the key found is unusable
(i.e. expired, revoked, disabled, invalid, or not usable for
encryption.)
</p></li><li class="listitem"><p>
<code class="literal">Discouraged</code> means a key was found for
every recipient, but the engine is not confident the message
will be decryptable by the recipient. This can happen if
the key hasn't been used recently (compared to their last
seen email).
</p><p>
It can also happen if the key wasn't seen first-hand from
the sender. Autocrypt has a feature where recipient keys
can be included in group-encrypted emails. This allows you
to reply to a conversation where you don't have a key
first-hand from one of the other recipients. However, those
keys are not trusted as much as from first-hand emails, so
the engine warns you with a <code class="literal">Discouraged</code>
status.
</p></li><li class="listitem"><p>
<code class="literal">Available</code> means a key was found for every
recipient, and the engine believes all keys are recent and
seen from the recipient first hand. However, either you or
one of the recipients chose not to specify <span class="quote">“<span class="quote">prefer
encryption</span>”</span>.
</p></li><li class="listitem"><p>
<code class="literal">Yes</code> is the same as
<code class="literal">Available</code>, with the addition that you and
all recipients have specified <span class="quote">“<span class="quote">prefer
encryption</span>”</span>. This value will automatically enable
encryption, unless you have manually switched it off or
enabled regular encryption or signing via the
<code class="literal">&lt;pgp-menu&gt;</code>.
</p></li></ul></div><p>
As mentioned above the <code class="literal">&lt;autocrypt-menu&gt;</code>
function, by default bound to <code class="literal">o</code>, can be used
to change the <code class="literal">Encrypt:</code> field value.
<code class="literal">(e)ncrypt</code> will toggle encryption on.
<code class="literal">(c)lear</code> will toggle encryption off. If
either of these are chosen, the field will remain in that state
despite what the <code class="literal">Recommendation:</code> field shows.
Lastly, <code class="literal">(a)utomatic</code> will set the value based
on the recommendation engine's output.
</p><p>
Autocrypt encryption defers to normal encryption or signing.
<span class="emphasis"><em>Anything</em></span> that enables normal encryption or
signing will cause autocrypt encryption to turn off. The only
exception is when replying to an autocrypt-encrypted email
(i.e. an email decrypted from the <a class="link" href="reference.html#autocrypt-dir" title="3.26. autocrypt_dir">$autocrypt_dir</a> keyring). Then,
if <a class="link" href="reference.html#autocrypt-reply" title="3.27. autocrypt_reply">$autocrypt_reply</a> is
<span class="emphasis"><em>set</em></span>, autocrypt mode will be forced on,
overriding the settings
<a class="link" href="reference.html#crypt-autosign" title="3.58. crypt_autosign">$crypt_autosign</a>,
<a class="link" href="reference.html#crypt-autoencrypt" title="3.56. crypt_autoencrypt">$crypt_autoencrypt</a>,
<a class="link" href="reference.html#crypt-replyencrypt" title="3.67. crypt_replyencrypt">$crypt_replyencrypt</a>,
<a class="link" href="reference.html#crypt-replysign" title="3.68. crypt_replysign">$crypt_replysign</a>,
<a class="link" href="reference.html#crypt-replysignencrypted" title="3.69. crypt_replysignencrypted">$crypt_replysignencrypted</a>, and
<a class="link" href="reference.html#crypt-opportunistic-encrypt" title="3.61. crypt_opportunistic_encrypt">$crypt_opportunistic_encrypt</a>.
</p><p>
When postponing a message, autocrypt will respect <a class="link" href="reference.html#postpone-encrypt" title="3.262. postpone_encrypt">$postpone_encrypt</a>, but will
use the autocrypt account key to encrypt the message. Be sure
to set <a class="link" href="reference.html#postpone-encrypt" title="3.262. postpone_encrypt">$postpone_encrypt</a>
to ensure postponed messages marked for autocrypt encryption are
encrypted.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="autocryptdoc-acctmgmt"></a>13.4. Account Management</h3></div></div></div><p>
The Autocrypt Account Menu is available from the index via
<code class="literal">&lt;autocrypt-acct-menu&gt;</code>, by default bound
to <code class="literal">A</code>. See <a class="link" href="reference.html#autocrypt-account-map" title="4.14. Autocrypt Account Menu">Autocrypt Account Menu</a> for the
list of functions and their default keybindings.
</p><p>
In this menu, you can create new accounts, delete accounts,
toggle an account active/inactive, and toggle the <span class="quote">“<span class="quote">prefer
encryption</span>”</span> flag for an account.
</p><p>
Deleting an account only removes the account from the database.
The GPG key is kept, to ensure you still have the ability to
read past encrypted emails.
</p><p>
The Autocrypt 1.1 <span class="quote">“<span class="quote">Setup Message</span>”</span> feature is not
available yet, but will be added in the future.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="autocryptdoc-keyrings"></a>13.5. Alternative Key and Keyring Strategies</h3></div></div></div><p>
Mutt by default partitions Autocrypt from normal keyring
encryption/signing. It does this by using a separate GPG
keyring (in <a class="link" href="reference.html#autocrypt-dir" title="3.26. autocrypt_dir">$autocrypt_dir</a>)
and creating a new ECC key in that keyring for accounts. There
are good reasons for doing this by default. It keeps random
keys found inside email headers out of your normal keyring. ECC
keys are compact and better suited for email headers. Autocrypt
key selection is completely different from <span class="quote">“<span class="quote">web of
trust</span>”</span> key selection, based on last-seen rules as opposed
to trust and validity. It also allows Mutt to distinguish
Autocrypt encrypted emails from regular encrypted emails, and
set the mode appropriately when replying to each type of email.
</p><p>
Still, some users may want to use an existing key from their
normal keyring for Autocrypt too. There are two ways this can
be accomplished. The <span class="emphasis"><em>recommended</em></span> way is to
set <a class="link" href="reference.html#autocrypt-dir" title="3.26. autocrypt_dir">$autocrypt_dir</a> to your
normal keyring directory (e.g. <code class="literal">~/.gnupg</code>).
During account creation, choosing <span class="quote">“<span class="quote">(s)elect existing GPG
key</span>”</span> will then list and allow selecting your existing key
for the new account.
</p><p>
An alternative is to copy your key over to the Autocrypt keyring,
but there is a severe downside. Mutt <span class="emphasis"><em>first</em></span>
tries to decrypt messages using the Autocrypt keyring, and if
that fails tries the normal keyring second. This means all
encrypted emails to that key will be decrypted, and have
signatures verified from, the Autocrypt keyring. Keys signatures
and web of trust from your normal keyring will no longer show up
in signatures when decrypting.
</p><p>
For that reason, if you want to use an existing key from your
normal keyring, it is recommended to just set <a class="link" href="reference.html#autocrypt-dir" title="3.26. autocrypt_dir">$autocrypt_dir</a> to
<code class="literal">~/.gnupg</code>. This allows <span class="quote">“<span class="quote">web of
trust</span>”</span> to show an appropriate signature message for
verified messages. Autocrypt header keys will be imported into
your keyring, but if you don't want them mixed you should
strongly consider using a separate autocrypt key and keyring
instead.
</p><p>
Both methods have a couple additional caveats:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Replying to an Autocrypt decrypted message by default forces
Autocrypt mode on. By sharing the same key, all replies
will then start in Autocrypt mode, even if a message wasn't
sent by one of your Autocrypt peers. <a class="link" href="reference.html#autocrypt-reply" title="3.27. autocrypt_reply">$autocrypt_reply</a> can be
<span class="emphasis"><em>unset</em></span> to allow manual control of the
mode when replying.
</p></li><li class="listitem"><p>
When Mutt creates an account from a GPG key, it exports the
public key, base64 encodes it, and stores that value in the
sqlite3 database. The value is then used in the Autocrypt
header added to outgoing emails. The ECC keys Mutt creates
don't change, but if you use external keys that expire, when
you resign to extend the expiration you will need to
recreate the Autocrypt account using the <a class="link" href="optionalfeatures.html#autocryptdoc-acctmgmt" title="13.4. Account Management">account menu</a>.
Otherwise the Autocrypt header will contain the old expired
exported keydata.
</p></li></ul></div></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="mimesupport.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="security.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 5. Mutt's MIME Support </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 7. Security Considerations</td></tr></table></div></body></html>
Reference in a new issue View git blame Copy permalink